diff --git a/README.rst b/README.rst index 6017be207c..a1b90fa02a 100644 --- a/README.rst +++ b/README.rst @@ -103,10 +103,15 @@ 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 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/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 -------------------------------------------------------------------------------- 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..36a84bc0c5 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..1a6c3d68c0 100644 --- a/docs/library/gc.rst +++ b/docs/library/gc.rst @@ -31,7 +31,7 @@ Functions .. admonition:: Difference to CPython :class: attention - This function is MicroPython extension. + This function is a MicroPython extension. .. function:: mem_free() @@ -41,7 +41,7 @@ Functions .. admonition:: Difference to CPython :class: attention - This function is MicroPython extension. + This function is a MicroPython extension. .. function:: threshold([amount]) @@ -63,6 +63,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..6c2e576e7d 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -3,43 +3,74 @@ MicroPython 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 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. + +.. warning:: + + 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``. + +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 + 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 +M0 non-Express builds, due to limited flash memory: +``string.center()``, ``string.partition()``, ``string.splitlines()``, +``string.reversed()``. -Functionality specific to the MicroPython implementation is available in -the following libraries. + +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 +versions of CircuitPtyon. .. toctree:: :maxdepth: 1 diff --git a/docs/library/sys.rst b/docs/library/sys.rst index de2ec2dcd2..bb92850b89 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -45,12 +45,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 +58,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,11 +96,11 @@ 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. - If you need to check whether your program runs on MicroPython (vs other + 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 CircuitPython (vs other Python implementation), use `sys.implementation` instead. .. data:: stderr diff --git a/docs/library/ustruct.rst b/docs/library/ustruct.rst deleted file mode 100644 index c378a94bbe..0000000000 --- a/docs/library/ustruct.rst +++ /dev/null @@ -1,44 +0,0 @@ -:mod:`ustruct` -- pack and unpack primitive data types -====================================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: ustruct - :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. 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.