Skip to content

Commit 5159304

Browse files
jimmodpgeorge
authored andcommitted
docs/library/index: Update built-in extension docs.
- Make the docs match the new behavior which only allows certain modules to be extended. - List the modules that currently have the u-prefix. - Add a note about the sys.path method for forcing a built-in import. This work was funded through GitHub Sponsors. Signed-off-by: Jim Mussared <[email protected]>
1 parent 952a78f commit 5159304

File tree

1 file changed

+49
-19
lines changed

1 file changed

+49
-19
lines changed

docs/library/index.rst

Lines changed: 49 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -8,15 +8,17 @@ MicroPython libraries
88
Important summary of this section
99

1010
* 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`)
1617
* Due to resource constraints or other limitations, some ports or firmware
1718
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.
2022

2123
This chapter describes modules (function and class libraries) which are built
2224
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
4143
modules from the Python standard library, as well as further MicroPython
4244
extensions to it, can be found in :term:`micropython-lib`.
4345

46+
.. _micropython_lib_python:
47+
4448
Python standard libraries and micro-libraries
4549
---------------------------------------------
4650

@@ -77,6 +81,7 @@ library.
7781
zlib.rst
7882
_thread.rst
7983

84+
.. _micropython_lib_micropython:
8085

8186
MicroPython-specific libraries
8287
------------------------------
@@ -181,23 +186,48 @@ The following libraries are specific to the Zephyr port.
181186

182187
zephyr.rst
183188

189+
.. _micropython_lib_extending:
190+
184191
Extending built-in libraries from Python
185192
----------------------------------------
186193

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.
191200

192201
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.
201215

202216
*Other than when you specifically want to force the use of the built-in module,
203217
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

Comments
 (0)