From 59615fc9938e0e7c7cf8141069f5eaaba05b18eb Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 22 May 2018 20:49:08 -0400 Subject: add caveat language re MicroPython libraries; other slight changes --- docs/library/gc.rst | 2 ++ docs/library/index.rst | 36 ++++++++++++++++--------- docs/library/struct.rst | 2 ++ docs/library/sys.rst | 4 ++- docs/templates/unsupported_in_circuitpython.inc | 9 ++++--- 5 files changed, 36 insertions(+), 17 deletions(-) (limited to 'docs') diff --git a/docs/library/gc.rst b/docs/library/gc.rst index ba25d788f..1a6c3d68c 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 3d2703c0a..3156f9352 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 fd953473a..bee5a612b 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 eeda578e6..bb92850b8 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 18c9215a8..1ed605d50 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. -- cgit v1.2.3