From e65cc077640881baedae1dcea0b8fcc1886d0f88 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Tue, 22 May 2018 19:52:01 -0400 Subject: RTD documentation updates --- docs/library/array.rst | 2 -- docs/library/builtins.rst | 18 +++++++++--------- docs/library/gc.rst | 8 +++----- docs/library/index.rst | 48 ++++++++++++++++++++++++++++++++++------------- docs/library/struct.rst | 42 +++++++++++++++++++++++++++++++++++++++++ docs/library/sys.rst | 20 +++++++++----------- docs/library/ustruct.rst | 44 ------------------------------------------- 7 files changed, 98 insertions(+), 84 deletions(-) create mode 100644 docs/library/struct.rst delete mode 100644 docs/library/ustruct.rst (limited to 'docs/library') diff --git a/docs/library/array.rst b/docs/library/array.rst index dfaef0ff6..0f1310b68 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 83246afc9..c60ade040 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 01bd925e9..ba25d788f 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 c7b6879aa..3d2703c0a 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -1,44 +1,66 @@ .. _micropython_lib: -MicroPython libraries +CircuitPython libraries ===================== -.. warning:: +Python standard libraries and micro-libraries +--------------------------------------------- - 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. +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. -Python standard libraries and micro-libraries ---------------------------------------------- +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 +------------------------------------------- + +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()``. + -MicroPython-specific libraries +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/struct.rst b/docs/library/struct.rst new file mode 100644 index 000000000..fd953473a --- /dev/null +++ b/docs/library/struct.rst @@ -0,0 +1,42 @@ +:mod:`struct` -- pack and unpack primitive data types +====================================================== + +.. 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. diff --git a/docs/library/sys.rst b/docs/library/sys.rst index de2ec2dcd..eeda578e6 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. diff --git a/docs/library/ustruct.rst b/docs/library/ustruct.rst deleted file mode 100644 index c378a94bb..000000000 --- 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. -- cgit v1.2.3