docs/library/index: Update docs after umodule rename.

- Update guide for extending built-in modules.
- Remove any last trace of umodule in other docs.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
This commit is contained in:
Jim Mussared 2023-06-02 23:33:42 +10:00
parent 5fd042e7d1
commit 8211d56712
6 changed files with 46 additions and 35 deletions

View File

@ -50,7 +50,7 @@ low all of the time.
* Example of a smooth frequency change::
from utime import sleep
from time import sleep
from machine import Pin, PWM
F_MIN = 500
@ -75,7 +75,7 @@ low all of the time.
* Example of a smooth duty change::
from utime import sleep
from time import sleep
from machine import Pin, PWM
DUTY_MAX = 2**16 - 1

View File

@ -191,34 +191,27 @@ The following libraries are specific to the Zephyr port.
Extending built-in libraries from Python
----------------------------------------
Many built-in modules are actually named ``umodule`` rather than ``module``, but
MicroPython will alias any module prefixed with a ``u`` to the non-``u``
version. This means that, for example, ``import time`` will first attempt to
resolve from the filesystem, and then failing that will fall back to the
built-in ``utime``. On the other hand, ``import utime`` will always go directly
to the built-in.
A subset of the built-in modules are able to be extended by Python code by
providing a module of the same name in the filesystem. This extensibility
applies to the following Python standard library modules which are built-in to
the firmware: ``array``, ``binascii``, ``collections``, ``errno``, ``hashlib``,
``heapq``, ``io``, ``json``, ``os``, ``platform``, ``random``, ``re``,
``select``, ``socket``, ``ssl``, ``struct``, ``time`` ``zlib``, as well as the
MicroPython-specific ``machine`` module. All other built-in modules cannot be
extended from the filesystem.
This allows the user to provide an extended implementation of a built-in library
(perhaps to provide additional CPython compatibility or missing functionality).
The user-provided module (in ``module.py``) can still use the built-in
functionality by importing ``umodule`` directly (e.g. typically an extension
module ``time.py`` will do ``from utime import *``). This is used extensively
in :term:`micropython-lib`. See :ref:`packages` for more information.
This is used extensively in :term:`micropython-lib`, see :ref:`packages` for
more information. The filesystem module will typically do a wildcard import of
the built-in module in order to inherit all the globals (classes, functions and
variables) from the built-in.
This extensibility applies to the following Python standard library modules
which are built-in to the firmware: ``array``, ``binascii``, ``collections``,
``errno``, ``hashlib``, ``heapq``, ``io``, ``json``, ``os``, ``platform``,
``random``, ``re``, ``select``, ``socket``, ``ssl``, ``struct``, ``sys``,
``time``, ``zlib``, as well as the MicroPython-specific libraries: ``bluepy``,
``bluetooth``, ``machine``, ``timeq``, ``websocket``. All other built-in
modules cannot be extended from the filesystem.
*Other than when you specifically want to force the use of the built-in module,
we recommend always using* ``import module`` *rather than* ``import umodule``.
**Note:** In MicroPython v1.21.0 and higher, it is now possible to force an
import of the built-in module by clearing ``sys.path`` during the import. For
example, in ``time.py``, you can write::
In MicroPython v1.21.0 and higher, to prevent the filesystem module from
importing itself, it can force an import of the built-in module it by
temporarily clearing ``sys.path`` during the import. For example, to extend the
``time`` module from Python, a file named ``time.py`` on the filesystem would
do the following::
_path = sys.path
sys.path = ()
@ -228,6 +221,25 @@ example, in ``time.py``, you can write::
sys.path = _path
del _path
This is now the preferred way (instead of ``from utime import *``), as the
``u``-prefix will be removed from the names of built-in modules in a future
version of MicroPython.
def extra_method():
pass
The result is that ``time.py`` contains all the globals of the built-in ``time``
module, but adds ``extra_method``.
In earlier versions of MicroPython, you can force an import of a built-in module
by appending a ``u`` to the start of its name. For example, ``import utime``
instead of ``import time``. For example, ``time.py`` on the filesystem could
look like::
from utime import *
def extra_method():
pass
This way is still supported, but the ``sys.path`` method described above is now
preferred as the ``u``-prefix will be removed from the names of built-in
modules in a future version of MicroPython.
*Other than when it specifically needs to force the use of the built-in module,
code should always use* ``import module`` *rather than* ``import umodule``.

View File

@ -34,5 +34,5 @@ Methods
These methods implement the simple and extended
:ref:`block protocol <block-device-interface>` defined by
:class:`uos.AbstractBlockDev`.
:class:`os.AbstractBlockDev`.

View File

@ -37,4 +37,4 @@ Methods
These methods implement the simple and extended
:ref:`block protocol <block-device-interface>` defined by
:class:`uos.AbstractBlockDev`.
:class:`os.AbstractBlockDev`.

View File

@ -12,9 +12,8 @@ To list supported modules, please enter::
help('modules')
Especially `machine` module and class :ref:`machine.Pin <machine.Pin>` are very important for using
peripherals. Note that prefix 'u' is added to the module for MicroPython,
so you can see "umachine" in the list but you can use it like "import machine".
Especially `machine` module and class :ref:`machine.Pin <machine.Pin>` are very
important for using peripherals.
Using "from machine import Pin", Pin name is available corresponding to
the RA MCU's pin name which are Pin.cpu.P000 and 'P000'.

View File

@ -19,7 +19,7 @@ See the corresponding section of the tutorial: :ref:`intro`.
Delay and timing
----------------
Use the :mod:`time <utime>` module::
Use the :mod:`time <time>` module::
import time