diff options
| -rw-r--r-- | docs/esp32/tutorial/pwm.rst | 4 | ||||
| -rw-r--r-- | docs/library/index.rst | 68 | ||||
| -rw-r--r-- | docs/library/zephyr.DiskAccess.rst | 2 | ||||
| -rw-r--r-- | docs/library/zephyr.FlashArea.rst | 2 | ||||
| -rw-r--r-- | docs/renesas-ra/tutorial/using_peripheral.rst | 5 | ||||
| -rw-r--r-- | docs/zephyr/quickref.rst | 2 |
6 files changed, 47 insertions, 36 deletions
diff --git a/docs/esp32/tutorial/pwm.rst b/docs/esp32/tutorial/pwm.rst index 12d10a86b..2650284d3 100644 --- a/docs/esp32/tutorial/pwm.rst +++ b/docs/esp32/tutorial/pwm.rst @@ -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 diff --git a/docs/library/index.rst b/docs/library/index.rst index 985a7ad77..e428f3a06 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -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 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:: +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. + +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``. diff --git a/docs/library/zephyr.DiskAccess.rst b/docs/library/zephyr.DiskAccess.rst index d19d81a96..3e5fa9a35 100644 --- a/docs/library/zephyr.DiskAccess.rst +++ b/docs/library/zephyr.DiskAccess.rst @@ -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`. diff --git a/docs/library/zephyr.FlashArea.rst b/docs/library/zephyr.FlashArea.rst index 306347d44..9cd4dd59d 100644 --- a/docs/library/zephyr.FlashArea.rst +++ b/docs/library/zephyr.FlashArea.rst @@ -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`. diff --git a/docs/renesas-ra/tutorial/using_peripheral.rst b/docs/renesas-ra/tutorial/using_peripheral.rst index c50181b3d..7296d8b33 100644 --- a/docs/renesas-ra/tutorial/using_peripheral.rst +++ b/docs/renesas-ra/tutorial/using_peripheral.rst @@ -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'. diff --git a/docs/zephyr/quickref.rst b/docs/zephyr/quickref.rst index 329a9c41c..57262ffb5 100644 --- a/docs/zephyr/quickref.rst +++ b/docs/zephyr/quickref.rst @@ -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 |