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.