From e65cc077640881baedae1dcea0b8fcc1886d0f88 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 22 May 2018 19:52:01 -0400 Subject: [PATCH 1/6] RTD documentation updates --- README.rst | 10 +++-- docs/library/array.rst | 2 - docs/library/builtins.rst | 18 ++++----- docs/library/gc.rst | 8 ++-- docs/library/index.rst | 50 +++++++++++++++++------- docs/library/{ustruct.rst => struct.rst} | 6 +-- docs/library/sys.rst | 20 +++++----- 7 files changed, 66 insertions(+), 48 deletions(-) rename docs/library/{ustruct.rst => struct.rst} (90%) diff --git a/README.rst b/README.rst index 6017be207c..ace4ac1889 100644 --- a/README.rst +++ b/README.rst @@ -103,10 +103,14 @@ Differences from `MicroPython `__ CircuitPython: -- includes a port for Atmel SAMD21 (Commonly known as M0 in Adafruit - product names.) -- supports only Atmel SAMD21 and ESP8266 ports. +- includes a ports for MicroChip SAMD21 (Commonly known as M0 in Adafruit + product names and SAMD51 (M4). +- 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. Behavior ~~~~~~~~ diff --git a/docs/library/array.rst b/docs/library/array.rst index dfaef0ff6c..0f1310b687 100644 --- a/docs/library/array.rst +++ b/docs/library/array.rst @@ -1,8 +1,6 @@ :mod:`array` -- arrays of numeric data ====================================== -.. include:: ../templates/unsupported_in_circuitpython.inc - .. module:: array :synopsis: efficient arrays of numeric data diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst index 83246afc92..c60ade0406 100644 --- a/docs/library/builtins.rst +++ b/docs/library/builtins.rst @@ -1,18 +1,14 @@ Builtin functions and exceptions ================================ -.. warning:: - - These builtins are inherited from MicroPython and may not work in CircuitPython - as documented or at all! If work differently from CPython, then their behavior - may change. - All builtin functions and exceptions are described here. They are also available via ``builtins`` module. Functions and types ------------------- +Not all of these functions and types are turned on in all CircuitPython ports, for space reasons. + .. function:: abs() .. function:: all() @@ -62,6 +58,8 @@ Functions and types .. class:: frozenset() +`frozenset() is not enabled on non-Express CircuitPython boards.` + .. function:: getattr() .. function:: globals() @@ -80,12 +78,12 @@ Functions and types .. classmethod:: from_bytes(bytes, byteorder) - In MicroPython, `byteorder` parameter must be positional (this is + In CircuitPython, `byteorder` parameter must be positional (this is compatible with CPython). .. method:: to_bytes(size, byteorder) - In MicroPython, `byteorder` parameter must be positional (this is + In CircuitPython, `byteorder` parameter must be positional (this is compatible with CPython). .. function:: isinstance() @@ -130,6 +128,8 @@ Functions and types .. function:: reversed() +`reversed() is not enabled on non-Express CircuitPython boards.` + .. function:: round() .. class:: set() @@ -182,7 +182,7 @@ Exceptions .. exception:: OSError - |see_cpython| `OSError`. MicroPython doesn't implement ``errno`` + |see_cpython| `OSError`. CircuitPython doesn't implement the ``errno`` attribute, instead use the standard way to access exception arguments: ``exc.args[0]``. diff --git a/docs/library/gc.rst b/docs/library/gc.rst index 01bd925e99..ba25d788f2 100644 --- a/docs/library/gc.rst +++ b/docs/library/gc.rst @@ -1,8 +1,6 @@ :mod:`gc` -- control the garbage collector ========================================== -.. include:: ../templates/unsupported_in_circuitpython.inc - .. module:: gc :synopsis: control the garbage collector @@ -31,7 +29,7 @@ Functions .. admonition:: Difference to CPython :class: attention - This function is MicroPython extension. + This function is a MicroPython extension. .. function:: mem_free() @@ -41,7 +39,7 @@ Functions .. admonition:: Difference to CPython :class: attention - This function is MicroPython extension. + This function is a MicroPython extension. .. function:: threshold([amount]) @@ -63,6 +61,6 @@ Functions .. admonition:: Difference to CPython :class: attention - This function is a MicroPython extension. CPython has a similar + This function is a a MicroPython extension. CPython has a similar function - ``set_threshold()``, but due to different GC implementations, its signature and semantics are different. diff --git a/docs/library/index.rst b/docs/library/index.rst index c7b6879aa4..3d2703c0a9 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -1,44 +1,66 @@ .. _micropython_lib: -MicroPython libraries +CircuitPython libraries ===================== -.. warning:: - - These modules are inherited from MicroPython and may not work in CircuitPython - as documented or at all! If they do work, they may change at any time. - - Python standard libraries and micro-libraries --------------------------------------------- +These libraries are the same or are subsets or slight variants of the standard Python libraries. + +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. + +Some of the libraries below are not enabled on CircuitPython builds with +limited flash memory, usually on non-Express builds: +``uerrno``, ``ure``. + +Some libraries are not currently enabled in any CircuitPython build, but may be in the future: +``uio``, ``ujson``, ``uzlib``. + +Some libraries are only enabled only WiFi-capable ports (ESP8266, nRF) +because they are typically used for network software: +``binascii``, ``hashlib``, ``uheapq``, ``uselect``, ``ussl``. +Not all of these are enabled on all WiFi-capable ports. .. toctree:: :maxdepth: 1 builtins.rst + uheapq.rst array.rst - gc.rst - sys.rst binascii.rst collections.rst - uerrno.rst + gc.rst hashlib.rst - uheapq.rst + struct.rst + sys.rst + uerrno.rst uio.rst ujson.rst ure.rst uselect.rst usocket.rst ussl.rst - ustruct.rst uzlib.rst +Omitted functions in the ``string`` library +------------------------------------------- -MicroPython-specific libraries +A few string operations are not enabled on CircuitPython builds with +limited flash memory, usually on non-Express builds: +``string.center()``, ``string.partition()``, ``string.splitlines()``, +``string.reversed()``. + + +CircuitPython/MicroPython-specific libraries ------------------------------ -Functionality specific to the MicroPython implementation is available in +Functionality specific to the CircuitPython (MicroPython) implementation is available in the following libraries. .. toctree:: diff --git a/docs/library/ustruct.rst b/docs/library/struct.rst similarity index 90% rename from docs/library/ustruct.rst rename to docs/library/struct.rst index c378a94bbe..fd953473af 100644 --- a/docs/library/ustruct.rst +++ b/docs/library/struct.rst @@ -1,9 +1,7 @@ -:mod:`ustruct` -- pack and unpack primitive data types +:mod:`struct` -- pack and unpack primitive data types ====================================================== -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: ustruct +.. module:: struct :synopsis: pack and unpack primitive data types |see_cpython_module| :mod:`cpython:struct`. diff --git a/docs/library/sys.rst b/docs/library/sys.rst index de2ec2dcd2..eeda578e6b 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -1,8 +1,6 @@ :mod:`sys` -- system specific functions ======================================= -.. include:: ../templates/unsupported_in_circuitpython.inc - .. module:: sys :synopsis: system specific functions @@ -45,12 +43,12 @@ Constants .. data:: implementation Object with information about the current Python implementation. For - MicroPython, it has following attributes: + CircuitPython, it has following attributes: - * *name* - string "micropython" + * *name* - string "circuitpython" * *version* - tuple (major, minor, micro), e.g. (1, 7, 0) - This object is the recommended way to distinguish MicroPython from other + This object is the recommended way to distinguish CircuitPython from other Python implementations (note that it still may not exist in the very minimal ports). @@ -58,13 +56,13 @@ Constants :class: attention CPython mandates more attributes for this object, but the actual useful - bare minimum is implemented in MicroPython. + bare minimum is implemented in CircuitPython. .. data:: maxsize Maximum value which a native integer type can hold on the current platform, - or maximum value representable by MicroPython integer type, if it's smaller - than platform max value (that is the case for MicroPython ports without + or maximum value representable by CircuitPython integer type, if it's smaller + than platform max value (that is the case for CircuitPython ports without long int support). This attribute is useful for detecting "bitness" of a platform (32-bit vs @@ -96,10 +94,10 @@ Constants .. data:: platform - The platform that MicroPython is running on. For OS/RTOS ports, this is + The platform that CircuitPython is running on. For OS/RTOS ports, this is usually an identifier of the OS, e.g. ``"linux"``. For baremetal ports it - is an identifier of a board, e.g. ``"pyboard"`` for the original MicroPython - reference board. It thus can be used to distinguish one board from another. + 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 Python implementation), use `sys.implementation` instead. From 59615fc9938e0e7c7cf8141069f5eaaba05b18eb Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 22 May 2018 20:49:08 -0400 Subject: [PATCH 2/6] 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. From 20a13fa9fb1ed7b9e23aa9272132b97d7082cbd1 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 22 May 2018 21:21:19 -0400 Subject: [PATCH 3/6] fix title underline --- docs/library/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/library/index.rst b/docs/library/index.rst index 3156f9352f..b14d7d2f80 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -67,7 +67,7 @@ M0 non-Express builds, due to limited flash memory: CircuitPython/MicroPython-specific libraries ------------------------------- +-------------------------------------------- Functionality specific to the CircuitPython/MicroPython implementation is available in the following libraries. These libraries may change signficantly or be removed in future From 079c20e58e2bb1ce8859cea99b951f6a3605e80b Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Wed, 23 May 2018 14:24:02 -0400 Subject: [PATCH 4/6] use shared-bindings struct doc; remove docs/library one --- docs/library/index.rst | 1 - docs/library/struct.rst | 44 ----------------------------------------- 2 files changed, 45 deletions(-) delete mode 100644 docs/library/struct.rst diff --git a/docs/library/index.rst b/docs/library/index.rst index b14d7d2f80..6c2e576e7d 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -46,7 +46,6 @@ Not all of these are enabled on all WiFi-capable ports. collections.rst gc.rst hashlib.rst - struct.rst sys.rst uerrno.rst uio.rst diff --git a/docs/library/struct.rst b/docs/library/struct.rst deleted file mode 100644 index bee5a612bc..0000000000 --- a/docs/library/struct.rst +++ /dev/null @@ -1,44 +0,0 @@ -:mod:`struct` -- pack and unpack primitive data types -====================================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: struct - :synopsis: pack and unpack primitive data types - -|see_cpython_module| :mod:`cpython:struct`. - -Supported size/byte order prefixes: ``@``, ``<``, ``>``, ``!``. - -Supported format codes: ``b``, ``B``, ``h``, ``H``, ``i``, ``I``, ``l``, -``L``, ``q``, ``Q``, ``s``, ``P``, ``f``, ``d`` (the latter 2 depending -on the floating-point support). - -Functions ---------- - -.. function:: calcsize(fmt) - - Return the number of bytes needed to store the given *fmt*. - -.. function:: pack(fmt, v1, v2, ...) - - Pack the values *v1*, *v2*, ... according to the format string *fmt*. - The return value is a bytes object encoding the values. - -.. function:: pack_into(fmt, buffer, offset, v1, v2, ...) - - Pack the values *v1*, *v2*, ... according to the format string *fmt* - into a *buffer* starting at *offset*. *offset* may be negative to count - from the end of *buffer*. - -.. function:: unpack(fmt, data) - - Unpack from the *data* according to the format string *fmt*. - The return value is a tuple of the unpacked values. - -.. function:: unpack_from(fmt, data, offset=0) - - Unpack from the *data* starting at *offset* according to the format string - *fmt*. *offset* may be negative to count from the end of *buffer*. The return - value is a tuple of the unpacked values. From 6a63ff096a553dd3b6de29a8cc89667fc434f36e Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Wed, 23 May 2018 15:05:38 -0400 Subject: [PATCH 5/6] ustruct -> struct in design_guide.rst --- docs/design_guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index a1524eaa2b..e7b3832bcb 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -441,10 +441,10 @@ buffers. Examples ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -ustruct.pack +struct.pack ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use `ustruct.pack_into` instead of `ustruct.pack`. +Use `struct.pack_into` instead of `struct.pack`. Sensor properties and units -------------------------------------------------------------------------------- From bbdca2f3529f23d76c8da7cf0a5d881d6acead36 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Wed, 23 May 2018 15:07:32 -0400 Subject: [PATCH 6/6] typos in builtins.rst --- docs/library/builtins.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/library/builtins.rst b/docs/library/builtins.rst index c60ade0406..36a84bc0c5 100644 --- a/docs/library/builtins.rst +++ b/docs/library/builtins.rst @@ -58,7 +58,7 @@ Not all of these functions and types are turned on in all CircuitPython ports, f .. class:: frozenset() -`frozenset() is not enabled on non-Express CircuitPython boards.` +`frozenset()` is not enabled on non-Express CircuitPython boards. .. function:: getattr() @@ -128,7 +128,7 @@ Not all of these functions and types are turned on in all CircuitPython ports, f .. function:: reversed() -`reversed() is not enabled on non-Express CircuitPython boards.` +`reversed()` is not enabled on non-Express CircuitPython boards. .. function:: round()