1.. _micropython_lib:
2
3MicroPython libraries
4=====================
5
6.. warning::
7
8   Important summary of this section
9
10   * MicroPython provides built-in modules that mirror the functionality of the
11     Python standard library (e.g. :mod:`os`, :mod:`time`), as well as
12     MicroPython-specific modules (e.g. :mod:`bluetooth`, :mod:`machine`).
13   * Most standard library modules implement a subset of the functionality of
14     the equivalent Python module, and in a few cases provide some
15     MicroPython-specific extensions (e.g. :mod:`array`, :mod:`os`)
16   * Due to resource constraints or other limitations, some ports or firmware
17     versions may not include all the functionality documented here.
18   * To allow for extensibility, the built-in modules can be extended from
19     Python code loaded onto the device.
20
21This chapter describes modules (function and class libraries) which are built
22into MicroPython. This documentation in general aspires to describe all modules
23and functions/classes which are implemented in the MicroPython project.
24However, MicroPython is highly configurable, and each port to a particular
25board/embedded system may include only a subset of the available MicroPython
26libraries.
27
28With that in mind, please be warned that some functions/classes in a module (or
29even the entire module) described in this documentation **may be unavailable**
30in a particular build of MicroPython on a particular system. The best place to
31find general information of the availability/non-availability of a particular
32feature is the "General Information" section which contains information
33pertaining to a specific :term:`MicroPython port`.
34
35On some ports you are able to discover the available, built-in libraries that
36can be imported by entering the following at the :term:`REPL`::
37
38    help('modules')
39
40Beyond the built-in libraries described in this documentation, many more
41modules from the Python standard library, as well as further MicroPython
42extensions to it, can be found in :term:`micropython-lib`.
43
44Python standard libraries and micro-libraries
45---------------------------------------------
46
47The following standard Python libraries have been "micro-ified" to fit in with
48the philosophy of MicroPython.  They provide the core functionality of that
49module and are intended to be a drop-in replacement for the standard Python
50library.
51
52.. toctree::
53   :maxdepth: 1
54
55   array.rst
56   binascii.rst
57   builtins.rst
58   cmath.rst
59   collections.rst
60   errno.rst
61   gc.rst
62   hashlib.rst
63   heapq.rst
64   io.rst
65   json.rst
66   math.rst
67   os.rst
68   re.rst
69   select.rst
70   socket.rst
71   ssl.rst
72   struct.rst
73   sys.rst
74   time.rst
75   uasyncio.rst
76   zlib.rst
77   _thread.rst
78
79
80MicroPython-specific libraries
81------------------------------
82
83Functionality specific to the MicroPython implementation is available in
84the following libraries.
85
86.. toctree::
87   :maxdepth: 1
88
89   bluetooth.rst
90   btree.rst
91   cryptolib.rst
92   framebuf.rst
93   machine.rst
94   micropython.rst
95   neopixel.rst
96   network.rst
97   uctypes.rst
98
99
100Port-specific libraries
101-----------------------
102
103In some cases the following port/board-specific libraries have functions or
104classes similar to those in the :mod:`machine` library.  Where this occurs, the
105entry in the port specific library exposes hardware functionality unique to
106that platform.
107
108To write portable code use functions and classes from the :mod:`machine` module.
109To access platform-specific hardware use the appropriate library, e.g.
110:mod:`pyb` in the case of the Pyboard.
111
112
113Libraries specific to the pyboard
114~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115
116The following libraries are specific to the pyboard.
117
118.. toctree::
119  :maxdepth: 2
120
121  pyb.rst
122  lcd160cr.rst
123
124
125Libraries specific to the WiPy
126~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127
128The following libraries and classes are specific to the WiPy.
129
130.. toctree::
131  :maxdepth: 2
132
133  wipy.rst
134  machine.ADCWiPy.rst
135  machine.TimerWiPy.rst
136
137
138Libraries specific to the ESP8266 and ESP32
139~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
140
141The following libraries are specific to the ESP8266 and ESP32.
142
143.. toctree::
144  :maxdepth: 2
145
146  esp.rst
147  esp32.rst
148
149
150Libraries specific to the RP2040
151~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152
153The following libraries are specific to the RP2040, as used in the Raspberry Pi Pico.
154
155.. toctree::
156  :maxdepth: 2
157
158  rp2.rst
159
160Libraries specific to Zephyr
161~~~~~~~~~~~~~~~~~~~~~~~~~~~~
162
163The following libraries are specific to the Zephyr port.
164
165.. toctree::
166  :maxdepth: 2
167
168  zephyr.rst
169
170Extending built-in libraries from Python
171----------------------------------------
172
173In most cases, the above modules are actually named ``umodule`` rather than
174``module``, but MicroPython will alias any module prefixed with a ``u`` to the
175non-``u`` version. However a file (or :term:`frozen module`) named
176``module.py`` will take precedence over this alias.
177
178This allows the user to provide an extended implementation of a built-in library
179(perhaps to provide additional CPython compatibility). The user-provided module
180(in ``module.py``) can still use the built-in functionality by importing
181``umodule`` directly. This is used extensively in :term:`micropython-lib`. See
182:ref:`packages` for more information.
183
184This applies to both the Python standard libraries (e.g. ``os``, ``time``, etc),
185but also the MicroPython libraries too (e.g. ``machine``, ``bluetooth``, etc).
186The main exception is the port-specific libraries (``pyb``, ``esp``, etc).
187
188*Other than when you specifically want to force the use of the built-in module,
189we recommend always using ``import module`` rather than ``import umodule``.*
190