From d7fbc755dc208be0d252afb379ab4e9880a2b693 Mon Sep 17 00:00:00 2001 From: Jim Mussared Date: Thu, 12 Aug 2021 15:15:03 +1000 Subject: [PATCH] docs/library/index.rst: Clarify module naming and purpose. Adds section about extending built-in modules from Python. Signed-off-by: Jim Mussared --- docs/library/index.rst | 100 ++++++++++++++++++------------------ docs/reference/packages.rst | 2 + 2 files changed, 52 insertions(+), 50 deletions(-) diff --git a/docs/library/index.rst b/docs/library/index.rst index 9af4fec056..c69050267a 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -7,47 +7,39 @@ MicroPython libraries Important summary of this section - * MicroPython implements a subset of Python functionality for each module. - * To ease extensibility, MicroPython versions of standard Python modules - usually have ``u`` ("micro") prefix. - * Any particular MicroPython variant or port may miss any feature/function - described in this general documentation (due to resource constraints or - other limitations). - + * MicroPython provides built-in modules that mirror the functionality of the + Python standard library (e.g. :mod:`os`, :mod:`time`), as well as + MicroPython-specific modules (e.g. :mod:`bluetooth`, :mod:`machine`). + * Most standard library modules implement a subset of the functionality of + the equivalent Python module, and in a few cases provide some + MicroPython-specific extensions (e.g. :mod:`array`, :mod:`os`) + * Due to resource constraints or other limitations, some ports or firmware + versions may not include all the functionality documented here. + * To allow for extensibility, the built-in modules can be extended from + Python code loaded onto the device. This chapter describes modules (function and class libraries) which are built -into MicroPython. There are a few categories of such modules: +into MicroPython. This documentation in general aspires to describe all modules +and functions/classes which are implemented in the MicroPython project. +However, MicroPython is highly configurable, and each port to a particular +board/embedded system may include only a subset of the available MicroPython +libraries. -* Modules which implement a subset of standard Python functionality and are not - intended to be extended by the user. -* Modules which implement a subset of Python functionality, with a provision - for extension by the user (via Python code). -* Modules which implement MicroPython extensions to the Python standard libraries. -* Modules specific to a particular :term:`MicroPython port` and thus not portable. - -Note about the availability of the modules and their contents: This documentation -in general aspires to describe all modules and functions/classes which are -implemented in MicroPython project. However, MicroPython is highly configurable, and -each port to a particular board/embedded system makes available only a subset -of MicroPython libraries. For officially supported ports, there is an effort -to either filter out non-applicable items, or mark individual descriptions -with "Availability:" clauses describing which ports provide a given feature. - -With that in mind, please still be warned that some functions/classes -in a module (or even the entire module) described in this documentation **may be -unavailable** in a particular build of MicroPython on a particular system. The -best place to find general information of the availability/non-availability -of a particular feature is the "General Information" section which contains -information pertaining to a specific :term:`MicroPython port`. +With that in mind, please be warned that some functions/classes in a module (or +even the entire module) described in this documentation **may be unavailable** +in a particular build of MicroPython on a particular system. The best place to +find general information of the availability/non-availability of a particular +feature is the "General Information" section which contains information +pertaining to a specific :term:`MicroPython port`. On some ports you are able to discover the available, built-in libraries that -can be imported by entering the following at the REPL:: +can be imported by entering the following at the :term:`REPL`:: help('modules') Beyond the built-in libraries described in this documentation, many more modules from the Python standard library, as well as further MicroPython -extensions to it, can be found in `micropython-lib`. +extensions to it, can be found in :term:`micropython-lib`. Python standard libraries and micro-libraries --------------------------------------------- @@ -55,20 +47,7 @@ Python standard libraries and micro-libraries The following standard Python libraries have been "micro-ified" to fit in with the philosophy of MicroPython. They provide the core functionality of that module and are intended to be a drop-in replacement for the standard Python -library. Some modules below use a standard Python name, but prefixed with "u", -e.g. ``json`` instead of ``json``. This is to signify that such a module is -micro-library, i.e. implements only a subset of CPython module functionality. -By naming them differently, a user has a choice to write a Python-level module -to extend functionality for better compatibility with CPython (indeed, this is -what done by the `micropython-lib` project mentioned above). - -On some embedded platforms, where it may be cumbersome to add Python-level -wrapper modules to achieve naming compatibility with CPython, micro-modules -are available both by their u-name, and also by their non-u-name. The -non-u-name can be overridden by a file of that name in your library path (``sys.path``). -For example, ``import json`` will first search for a file ``json.py`` (or package -directory ``json``) and load that module if it is found. If nothing is found, -it will fallback to loading the built-in ``json`` module. +library. .. toctree:: :maxdepth: 1 @@ -131,7 +110,7 @@ To access platform-specific hardware use the appropriate library, e.g. Libraries specific to the pyboard ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following libraries are specific to the pyboard. @@ -143,7 +122,7 @@ The following libraries are specific to the pyboard. Libraries specific to the WiPy ------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following libraries and classes are specific to the WiPy. @@ -156,7 +135,7 @@ The following libraries and classes are specific to the WiPy. Libraries specific to the ESP8266 and ESP32 -------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following libraries are specific to the ESP8266 and ESP32. @@ -168,7 +147,7 @@ The following libraries are specific to the ESP8266 and ESP32. Libraries specific to the RP2040 --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following libraries are specific to the RP2040, as used in the Raspberry Pi Pico. @@ -178,7 +157,7 @@ The following libraries are specific to the RP2040, as used in the Raspberry Pi rp2.rst Libraries specific to Zephyr ----------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following libraries are specific to the Zephyr port. @@ -186,3 +165,24 @@ The following libraries are specific to the Zephyr port. :maxdepth: 2 zephyr.rst + +Extending built-in libraries from Python +---------------------------------------- + +In most cases, the above modules are actually named ``umodule`` rather than +``module``, but MicroPython will alias any module prefixed with a ``u`` to the +non-``u`` version. However a file (or :term:``frozen module``) named +``module.py`` will take precedence over this alias. + +This allows the user to provide an extended implementation of a built-in library +(perhaps to provide additional CPython compatibility). The user-provided module +(in ``module.py``) can still use the built-in functionality by importing +``umodule`` directly. This is used extensively in :term:`micropython-lib`. See +:ref:`packages` for more information. + +This applies to both the Python standard libraries (e.g. ``os``, ``time``, etc), +but also the MicroPython libraries too (e.g. ``machine``, ``bluetooth``, etc). +The main exception is the port-specific libraries (``pyb``, ``esp``, etc). + +*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``.* diff --git a/docs/reference/packages.rst b/docs/reference/packages.rst index e9adfc176e..eb44992ed6 100644 --- a/docs/reference/packages.rst +++ b/docs/reference/packages.rst @@ -1,3 +1,5 @@ +.. _packages: + Distribution packages, package management, and deploying applications =====================================================================