djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/library/index.rst: Clarify module naming and purpose.

Browse Source 
Adds section about extending built-in modules from Python.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>
This commit is contained in:
Jim Mussared 2021-08-12 15:15:03 +10:00 committed by Damien George
parent ee549d725a
commit d7fbc755dc
2 changed files with 52 additions and 50 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

100
docs/library/index.rst
View File

@ -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``.*

2
docs/reference/packages.rst
View File

@ -1,3 +1,5 @@
.. _packages:
Distribution packages, package management, and deploying applications
=====================================================================