From 59615fc9938e0e7c7cf8141069f5eaaba05b18eb Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 22 May 2018 20:49:08 -0400 Subject: [PATCH] add caveat language re MicroPython libraries; other slight changes --- README.rst | 7 ++-- docs/library/gc.rst | 2 ++ docs/library/index.rst | 36 ++++++++++++------- docs/library/struct.rst | 2 ++ docs/library/sys.rst | 4 ++- .../unsupported_in_circuitpython.inc | 9 +++-- 6 files changed, 40 insertions(+), 20 deletions(-) diff --git a/README.rst b/README.rst index ace4ac1889..a1b90fa02a 100644 --- a/README.rst +++ b/README.rst @@ -108,9 +108,10 @@ CircuitPython: - supports only SAMD21, SAMD51, and ESP8266 ports. An nRF port is under development. - tracks MicroPython's releases (not master). -- Longints (arbitrary-length integers) are turned on for most Express builds - (those boards with SPI flash chips external to the microcontroller), - but not for boards without SPI flash, for space reasons. +- Longints (arbitrary-length integers) are enabled for most M0 + Express boards (those boards with SPI flash chips external + to the microcontroller), and for all M4 builds. + Longints are disabled on other boards due to lack of flash space. Behavior ~~~~~~~~ diff --git a/docs/library/gc.rst b/docs/library/gc.rst index ba25d788f2..1a6c3d68c0 100644 --- a/docs/library/gc.rst +++ b/docs/library/gc.rst @@ -1,6 +1,8 @@ :mod:`gc` -- control the garbage collector ========================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: gc :synopsis: control the garbage collector diff --git a/docs/library/index.rst b/docs/library/index.rst index 3d2703c0a9..3156f9352f 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -1,21 +1,30 @@ .. _micropython_lib: -CircuitPython libraries +MicroPython libraries ===================== Python standard libraries and micro-libraries --------------------------------------------- -These libraries are the same or are subsets or slight variants of the standard Python libraries. +These libraries are inherited from MicroPython. +They are similar to the standard Python libraries with the same name +or with the "u" prefix dropped. +They implement a subset of or a variant of the corresponding +standard Python library. -MicroPython prefixed many of these libraries with ``u``. In CircuitPython, those -that are subsets or the same as the standard Python libraries have been or will be renamed -to their original names. -Our aspiration is that code written in CircuitPython -that uses Python standard libraries will be runnable on CPython without changes. -But we may fall short of this goal in some cases. +.. warning:: -Some of the libraries below are not enabled on CircuitPython builds with + Though these MicroPython-based libraries are available in CircuitPython, + their functionality may change in the future, perhaps significantly. + As CircuitPython continues to develop, new versions of these libraries will + be created that are more compliant with the standard Python libraries. + You may need to change your code later if you rely + on any non-standard functionality they currently provide. + +CircuitPython's goal long-term goalis that code written in CircuitPython +using Python standard libraries will be runnable on CPython without changes. + +Some libraries below are not enabled on CircuitPython builds with limited flash memory, usually on non-Express builds: ``uerrno``, ``ure``. @@ -51,8 +60,8 @@ Not all of these are enabled on all WiFi-capable ports. Omitted functions in the ``string`` library ------------------------------------------- -A few string operations are not enabled on CircuitPython builds with -limited flash memory, usually on non-Express builds: +A few string operations are not enabled on CircuitPython +M0 non-Express builds, due to limited flash memory: ``string.center()``, ``string.partition()``, ``string.splitlines()``, ``string.reversed()``. @@ -60,8 +69,9 @@ limited flash memory, usually on non-Express builds: CircuitPython/MicroPython-specific libraries ------------------------------ -Functionality specific to the CircuitPython (MicroPython) implementation is available in -the following libraries. +Functionality specific to the CircuitPython/MicroPython implementation is available in +the following libraries. These libraries may change signficantly or be removed in future +versions of CircuitPtyon. .. toctree:: :maxdepth: 1 diff --git a/docs/library/struct.rst b/docs/library/struct.rst index fd953473af..bee5a612bc 100644 --- a/docs/library/struct.rst +++ b/docs/library/struct.rst @@ -1,6 +1,8 @@ :mod:`struct` -- pack and unpack primitive data types ====================================================== +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: struct :synopsis: pack and unpack primitive data types diff --git a/docs/library/sys.rst b/docs/library/sys.rst index eeda578e6b..bb92850b89 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -1,6 +1,8 @@ :mod:`sys` -- system specific functions ======================================= +.. include:: ../templates/unsupported_in_circuitpython.inc + .. module:: sys :synopsis: system specific functions @@ -98,7 +100,7 @@ Constants usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it is an identifier of the chip on a board, e.g. ``"MicroChip SAMD51"``. It thus can be used to distinguish one board from another. - If you need to check whether your program runs on MicroPython (vs other + If you need to check whether your program runs on CircuitPython (vs other Python implementation), use `sys.implementation` instead. .. data:: stderr diff --git a/docs/templates/unsupported_in_circuitpython.inc b/docs/templates/unsupported_in_circuitpython.inc index 18c9215a84..1ed605d503 100644 --- a/docs/templates/unsupported_in_circuitpython.inc +++ b/docs/templates/unsupported_in_circuitpython.inc @@ -1,5 +1,8 @@ .. warning:: - This module is inherited from MicroPython and may not work in CircuitPython - as documented or at all! If they do work, they may change at any time. It is - unsupported. + Though this MicroPython-based library is available for use in CircuitPython, + its functionality may change in the future, perhaps significantly. + As CircuitPython continues to develop, it may be changed + to comply more closely with the corresponding standard Python library. + You may need to change your code later if you rely + on any non-standard functionality it currently provides.