@@ -8,15 +8,17 @@ MicroPython libraries
8
8
Important summary of this section
9
9
10
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 `)
11
+ :ref: `Python standard library <micropython_lib_python >` (e.g. :mod: `os `,
12
+ :mod: `time `), as well as :ref: `MicroPython-specific modules <micropython_lib_micropython >`
13
+ (e.g. :mod: `bluetooth `, :mod: `machine `).
14
+ * Most Python standard library modules implement a subset of the
15
+ functionality of the equivalent Python module, and in a few cases provide
16
+ some MicroPython-specific extensions (e.g. :mod: `array `, :mod: `os `)
16
17
* Due to resource constraints or other limitations, some ports or firmware
17
18
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.
19
+ * To allow for extensibility, some built-in modules can be
20
+ :ref: `extended from Python code <micropython_lib_extending >` loaded onto
21
+ the device filesystem.
20
22
21
23
This chapter describes modules (function and class libraries) which are built
22
24
into MicroPython. This documentation in general aspires to describe all modules
@@ -41,6 +43,8 @@ Beyond the built-in libraries described in this documentation, many more
41
43
modules from the Python standard library, as well as further MicroPython
42
44
extensions to it, can be found in :term: `micropython-lib `.
43
45
46
+ .. _micropython_lib_python :
47
+
44
48
Python standard libraries and micro-libraries
45
49
---------------------------------------------
46
50
@@ -77,6 +81,7 @@ library.
77
81
zlib.rst
78
82
_thread.rst
79
83
84
+ .. _micropython_lib_micropython :
80
85
81
86
MicroPython-specific libraries
82
87
------------------------------
@@ -181,23 +186,48 @@ The following libraries are specific to the Zephyr port.
181
186
182
187
zephyr.rst
183
188
189
+ .. _micropython_lib_extending :
190
+
184
191
Extending built-in libraries from Python
185
192
----------------------------------------
186
193
187
- In most cases, the above modules are actually named ``umodule `` rather than
188
- ``module ``, but MicroPython will alias any module prefixed with a ``u `` to the
189
- non-``u `` version. However a file (or :term: `frozen module `) named
190
- ``module.py `` will take precedence over this alias.
194
+ Many built-in modules are actually named ``umodule `` rather than ``module ``, but
195
+ MicroPython will alias any module prefixed with a ``u `` to the non-``u ``
196
+ version. This means that, for example, ``import time `` will first attempt to
197
+ resolve from the filesystem, and then failing that will fall back to the
198
+ built-in ``utime ``. On the other hand, ``import utime `` will always go directly
199
+ to the built-in.
191
200
192
201
This allows the user to provide an extended implementation of a built-in library
193
- (perhaps to provide additional CPython compatibility). The user-provided module
194
- (in ``module.py ``) can still use the built-in functionality by importing
195
- ``umodule `` directly. This is used extensively in :term: `micropython-lib `. See
196
- :ref: `packages ` for more information.
197
-
198
- This applies to both the Python standard libraries (e.g. ``os ``, ``time ``, etc),
199
- but also the MicroPython libraries too (e.g. ``machine ``, ``bluetooth ``, etc).
200
- The main exception is the port-specific libraries (``pyb ``, ``esp ``, etc).
202
+ (perhaps to provide additional CPython compatibility or missing functionality).
203
+ The user-provided module (in ``module.py ``) can still use the built-in
204
+ functionality by importing ``umodule `` directly (e.g. typically an extension
205
+ module ``time.py `` will do ``from utime import * ``). This is used extensively
206
+ in :term: `micropython-lib `. See :ref: `packages ` for more information.
207
+
208
+ This extensibility applies to the following Python standard library modules
209
+ which are built-in to the firmware: ``array ``, ``binascii ``, ``collections ``,
210
+ ``errno ``, ``hashlib ``, ``heapq ``, ``io ``, ``json ``, ``os ``, ``platform ``,
211
+ ``random ``, ``re ``, ``select ``, ``socket ``, ``ssl ``, ``struct ``, ``sys ``,
212
+ ``time ``, ``zlib ``, as well as the MicroPython-specific libraries: ``bluepy ``,
213
+ ``bluetooth ``, ``machine ``, ``timeq ``, ``websocket ``. All other built-in
214
+ modules cannot be extended from the filesystem.
201
215
202
216
*Other than when you specifically want to force the use of the built-in module,
203
217
we recommend always using * ``import module `` *rather than * ``import umodule ``.
218
+
219
+ **Note: ** In MicroPython v1.21.0 and higher, it is now possible to force an
220
+ import of the built-in module by clearing ``sys.path `` during the import. For
221
+ example, in ``time.py ``, you can write::
222
+
223
+ _path = sys.path
224
+ sys.path = ()
225
+ try:
226
+ from time import *
227
+ finally:
228
+ sys.path = _path
229
+ del _path
230
+
231
+ This is now the preferred way (instead of ``from utime import * ``), as the
232
+ ``u ``-prefix will be removed from the names of built-in modules in a future
233
+ version of MicroPython.
0 commit comments