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