From 69869e1439a1ebad383b75b28e7e88f21ccab732 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Sun, 24 Jan 2021 22:49:28 -0500 Subject: CIRCUITPY_* switches for JSON, RE, etc. Doc cleanup --- docs/library/errno.rst | 32 ++++++++++++ docs/library/index.rst | 51 +++++------------- docs/library/io.rst | 114 ++++++++++++++++++++++++++++++++++++++++ docs/library/json.rst | 35 +++++++++++++ docs/library/re.rst | 101 +++++++++++++++++++++++++++++++++++ docs/library/uerrno.rst | 34 ------------ docs/library/uio.rst | 116 ----------------------------------------- docs/library/ujson.rst | 37 ------------- docs/library/ure.rst | 103 ------------------------------------ docs/shared_bindings_matrix.py | 4 +- 10 files changed, 297 insertions(+), 330 deletions(-) create mode 100644 docs/library/errno.rst create mode 100644 docs/library/io.rst create mode 100644 docs/library/json.rst create mode 100644 docs/library/re.rst delete mode 100644 docs/library/uerrno.rst delete mode 100644 docs/library/uio.rst delete mode 100644 docs/library/ujson.rst delete mode 100644 docs/library/ure.rst (limited to 'docs') diff --git a/docs/library/errno.rst b/docs/library/errno.rst new file mode 100644 index 000000000..96777b205 --- /dev/null +++ b/docs/library/errno.rst @@ -0,0 +1,32 @@ +:mod:`errno` -- system error codes +=================================== + +.. module:: errno + :synopsis: system error codes + +|see_cpython_module| :mod:`cpython:errno`. + +This module provides access to symbolic error codes for `OSError` exception. + +Constants +--------- + +.. data:: EEXIST, EAGAIN, etc. + + Error codes, based on ANSI C/POSIX standard. All error codes start with + "E". Errors are usually accessible as ``exc.args[0]`` + where ``exc`` is an instance of `OSError`. Usage example:: + + try: + os.mkdir("my_dir") + except OSError as exc: + if exc.args[0] == errno.EEXIST: + print("Directory already exists") + +.. data:: errorcode + + Dictionary mapping numeric error codes to strings with symbolic error + code (see above):: + + >>> print(errno.errorcode[uerrno.EEXIST]) + EEXIST diff --git a/docs/library/index.rst b/docs/library/index.rst index e91387242..94bd8a656 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -7,34 +7,20 @@ 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 are similar to the standard Python libraries with the same name. 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 long-term goal is 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 +These libraries 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``. +``binascii``, ``errno``, ``json``, ``re``. -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. +These libraries are not currently enabled in any CircuitPython build, but may be in the future, +with the ``u`` prefix dropped: +``uctypes`, ``uhashlib``, ``uio``, ``uzlib``. .. toctree:: :maxdepth: 1 @@ -44,13 +30,14 @@ Not all of these are enabled on all WiFi-capable ports. array.rst binascii.rst collections.rst + errno.rst gc.rst hashlib.rst + io.rst + json.rst + re.rst sys.rst - uerrno.rst - uio.rst - ujson.rst - ure.rst + uctypes.rst uselect.rst usocket.rst ussl.rst @@ -59,8 +46,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 -M0 non-Express builds, due to limited flash memory: +A few string operations are not enabled on small builds +(usually non-Express), due to limited flash memory: ``string.center()``, ``string.partition()``, ``string.splitlines()``, ``string.reversed()``. @@ -78,15 +65,3 @@ versions of CircuitPython. btree.rst framebuf.rst micropython.rst - network.rst - uctypes.rst - -Libraries specific to the ESP8266 ---------------------------------- - -The following libraries are specific to the ESP8266. - -.. toctree:: - :maxdepth: 2 - - esp.rst diff --git a/docs/library/io.rst b/docs/library/io.rst new file mode 100644 index 000000000..37e3eb7c9 --- /dev/null +++ b/docs/library/io.rst @@ -0,0 +1,114 @@ +:mod:`io` -- input/output streams +================================== + +.. module:: io + :synopsis: input/output streams + +|see_cpython_module| :mod:`cpython:io`. + +This module contains additional types of ``stream`` (file-like) objects +and helper functions. + +Conceptual hierarchy +-------------------- + +.. admonition:: Difference to CPython + :class: attention + + Conceptual hierarchy of stream base classes is simplified in MicroPython, + as described in this section. + +(Abstract) base stream classes, which serve as a foundation for behavior +of all the concrete classes, adhere to few dichotomies (pair-wise +classifications) in CPython. In MicroPython, they are somewhat simplified +and made implicit to achieve higher efficiencies and save resources. + +An important dichotomy in CPython is unbuffered vs buffered streams. In +MicroPython, all streams are currently unbuffered. This is because all +modern OSes, and even many RTOSes and filesystem drivers already perform +buffering on their side. Adding another layer of buffering is counter- +productive (an issue known as "bufferbloat") and takes precious memory. +Note that there still cases where buffering may be useful, so we may +introduce optional buffering support at a later time. + +But in CPython, another important dichotomy is tied with "bufferedness" - +it's whether a stream may incur short read/writes or not. A short read +is when a user asks e.g. 10 bytes from a stream, but gets less, similarly +for writes. In CPython, unbuffered streams are automatically short +operation susceptible, while buffered are guarantee against them. The +no short read/writes is an important trait, as it allows to develop +more concise and efficient programs - something which is highly desirable +for MicroPython. So, while MicroPython doesn't support buffered streams, +it still provides for no-short-operations streams. Whether there will +be short operations or not depends on each particular class' needs, but +developers are strongly advised to favor no-short-operations behavior +for the reasons stated above. For example, MicroPython sockets are +guaranteed to avoid short read/writes. Actually, at this time, there is +no example of a short-operations stream class in the core, and one would +be a port-specific class, where such a need is governed by hardware +peculiarities. + +The no-short-operations behavior gets tricky in case of non-blocking +streams, blocking vs non-blocking behavior being another CPython dichotomy, +fully supported by MicroPython. Non-blocking streams never wait for +data either to arrive or be written - they read/write whatever possible, +or signal lack of data (or ability to write data). Clearly, this conflicts +with "no-short-operations" policy, and indeed, a case of non-blocking +buffered (and this no-short-ops) streams is convoluted in CPython - in +some places, such combination is prohibited, in some it's undefined or +just not documented, in some cases it raises verbose exceptions. The +matter is much simpler in MicroPython: non-blocking stream are important +for efficient asynchronous operations, so this property prevails on +the "no-short-ops" one. So, while blocking streams will avoid short +reads/writes whenever possible (the only case to get a short read is +if end of file is reached, or in case of error (but errors don't +return short data, but raise exceptions)), non-blocking streams may +produce short data to avoid blocking the operation. + +The final dichotomy is binary vs text streams. MicroPython of course +supports these, but while in CPython text streams are inherently +buffered, they aren't in MicroPython. (Indeed, that's one of the cases +for which we may introduce buffering support.) + +Note that for efficiency, MicroPython doesn't provide abstract base +classes corresponding to the hierarchy above, and it's not possible +to implement, or subclass, a stream class in pure Python. + +Functions +--------- + +.. function:: open(name, mode='r', **kwargs) + + Open a file. Builtin ``open()`` function is aliased to this function. + All ports (which provide access to file system) are required to support + ``mode`` parameter, but support for other arguments vary by port. + +Classes +------- + +.. class:: FileIO(...) + + This is type of a file open in binary mode, e.g. using ``open(name, "rb")``. + You should not instantiate this class directly. + +.. class:: TextIOWrapper(...) + + This is type of a file open in text mode, e.g. using ``open(name, "rt")``. + You should not instantiate this class directly. + +.. class:: StringIO([string]) +.. class:: BytesIO([string]) + + In-memory file-like objects for input/output. `StringIO` is used for + text-mode I/O (similar to a normal file opened with "t" modifier). + `BytesIO` is used for binary-mode I/O (similar to a normal file + opened with "b" modifier). Initial contents of file-like objects + can be specified with `string` parameter (should be normal string + for `StringIO` or bytes object for `BytesIO`). All the usual file + methods like ``read()``, ``write()``, ``seek()``, ``flush()``, + ``close()`` are available on these objects, and additionally, a + following method: + + .. method:: getvalue() + + Get the current contents of the underlying buffer which holds data. diff --git a/docs/library/json.rst b/docs/library/json.rst new file mode 100644 index 000000000..21574e556 --- /dev/null +++ b/docs/library/json.rst @@ -0,0 +1,35 @@ +:mod:`json` -- JSON encoding and decoding +========================================== + +.. module:: json + :synopsis: JSON encoding and decoding + +|see_cpython_module| :mod:`cpython:json`. + +This modules allows to convert between Python objects and the JSON +data format. + +Functions +--------- + +.. function:: dump(obj, stream) + + Serialise ``obj`` to a JSON string, writing it to the given *stream*. + +.. function:: dumps(obj) + + Return ``obj`` represented as a JSON string. + +.. function:: load(stream) + + Parse the given ``stream``, interpreting it as a JSON string and + deserialising the data to a Python object. The resulting object is + returned. + + Parsing continues until end-of-file is encountered. + A :exc:`ValueError` is raised if the data in ``stream`` is not correctly formed. + +.. function:: loads(str) + + Parse the JSON *str* and return an object. Raises :exc:`ValueError` if the + string is not correctly formed. diff --git a/docs/library/re.rst b/docs/library/re.rst new file mode 100644 index 000000000..bdcc9f52c --- /dev/null +++ b/docs/library/re.rst @@ -0,0 +1,101 @@ +:mod:`re` -- simple regular expressions +======================================== + +.. module:: re + :synopsis: regular expressions + +|see_cpython_module| :mod:`cpython:re`. + +This module implements regular expression operations. Regular expression +syntax supported is a subset of CPython ``re`` module (and actually is +a subset of POSIX extended regular expressions). + +Supported operators are: + +``'.'`` + Match any character. + +``'[...]'`` + Match set of characters. Individual characters and ranges are supported, + including negated sets (e.g. ``[^a-c]``). + +``'^'`` + +``'$'`` + +``'?'`` + +``'*'`` + +``'+'`` + +``'??'`` + +``'*?'`` + +``'+?'`` + +``'|'`` + +``'(...)'`` + Grouping. Each group is capturing (a substring it captures can be accessed + with `match.group()` method). + +**NOT SUPPORTED**: Counted repetitions (``{m,n}``), more advanced assertions +(``\b``, ``\B``), named groups (``(?P...)``), non-capturing groups +(``(?:...)``), etc. + + +Functions +--------- + +.. function:: compile(regex_str, [flags]) + + Compile regular expression, return `regex ` object. + +.. function:: match(regex_str, string) + + Compile *regex_str* and match against *string*. Match always happens + from starting position in a string. + +.. function:: search(regex_str, string) + + Compile *regex_str* and search it in a *string*. Unlike `match`, this will search + string for first position which matches regex (which still may be + 0 if regex is anchored). + +.. data:: DEBUG + + Flag value, display debug information about compiled expression. + + +.. _regex: + +Regex objects +------------- + +Compiled regular expression. Instances of this class are created using +`re.compile()`. + +.. method:: regex.match(string) + regex.search(string) + + Similar to the module-level functions :meth:`match` and :meth:`search`. + Using methods is (much) more efficient if the same regex is applied to + multiple strings. + +.. method:: regex.split(string, max_split=-1) + + Split a *string* using regex. If *max_split* is given, it specifies + maximum number of splits to perform. Returns list of strings (there + may be up to *max_split+1* elements if it's specified). + +Match objects +------------- + +Match objects as returned by `match()` and `search()` methods. + +.. method:: match.group([index]) + + Return matching (sub)string. *index* is 0 for entire match, + 1 and above for each capturing group. Only numeric groups are supported. diff --git a/docs/library/uerrno.rst b/docs/library/uerrno.rst deleted file mode 100644 index 72f71f0aa..000000000 --- a/docs/library/uerrno.rst +++ /dev/null @@ -1,34 +0,0 @@ -:mod:`uerrno` -- system error codes -=================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: uerrno - :synopsis: system error codes - -|see_cpython_module| :mod:`cpython:errno`. - -This module provides access to symbolic error codes for `OSError` exception. - -Constants ---------- - -.. data:: EEXIST, EAGAIN, etc. - - Error codes, based on ANSI C/POSIX standard. All error codes start with - "E". Errors are usually accessible as ``exc.args[0]`` - where ``exc`` is an instance of `OSError`. Usage example:: - - try: - os.mkdir("my_dir") - except OSError as exc: - if exc.args[0] == uerrno.EEXIST: - print("Directory already exists") - -.. data:: errorcode - - Dictionary mapping numeric error codes to strings with symbolic error - code (see above):: - - >>> print(uerrno.errorcode[uerrno.EEXIST]) - EEXIST diff --git a/docs/library/uio.rst b/docs/library/uio.rst deleted file mode 100644 index d1f7c111f..000000000 --- a/docs/library/uio.rst +++ /dev/null @@ -1,116 +0,0 @@ -:mod:`uio` -- input/output streams -================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: uio - :synopsis: input/output streams - -|see_cpython_module| :mod:`cpython:io`. - -This module contains additional types of ``stream`` (file-like) objects -and helper functions. - -Conceptual hierarchy --------------------- - -.. admonition:: Difference to CPython - :class: attention - - Conceptual hierarchy of stream base classes is simplified in MicroPython, - as described in this section. - -(Abstract) base stream classes, which serve as a foundation for behavior -of all the concrete classes, adhere to few dichotomies (pair-wise -classifications) in CPython. In MicroPython, they are somewhat simplified -and made implicit to achieve higher efficiencies and save resources. - -An important dichotomy in CPython is unbuffered vs buffered streams. In -MicroPython, all streams are currently unbuffered. This is because all -modern OSes, and even many RTOSes and filesystem drivers already perform -buffering on their side. Adding another layer of buffering is counter- -productive (an issue known as "bufferbloat") and takes precious memory. -Note that there still cases where buffering may be useful, so we may -introduce optional buffering support at a later time. - -But in CPython, another important dichotomy is tied with "bufferedness" - -it's whether a stream may incur short read/writes or not. A short read -is when a user asks e.g. 10 bytes from a stream, but gets less, similarly -for writes. In CPython, unbuffered streams are automatically short -operation susceptible, while buffered are guarantee against them. The -no short read/writes is an important trait, as it allows to develop -more concise and efficient programs - something which is highly desirable -for MicroPython. So, while MicroPython doesn't support buffered streams, -it still provides for no-short-operations streams. Whether there will -be short operations or not depends on each particular class' needs, but -developers are strongly advised to favor no-short-operations behavior -for the reasons stated above. For example, MicroPython sockets are -guaranteed to avoid short read/writes. Actually, at this time, there is -no example of a short-operations stream class in the core, and one would -be a port-specific class, where such a need is governed by hardware -peculiarities. - -The no-short-operations behavior gets tricky in case of non-blocking -streams, blocking vs non-blocking behavior being another CPython dichotomy, -fully supported by MicroPython. Non-blocking streams never wait for -data either to arrive or be written - they read/write whatever possible, -or signal lack of data (or ability to write data). Clearly, this conflicts -with "no-short-operations" policy, and indeed, a case of non-blocking -buffered (and this no-short-ops) streams is convoluted in CPython - in -some places, such combination is prohibited, in some it's undefined or -just not documented, in some cases it raises verbose exceptions. The -matter is much simpler in MicroPython: non-blocking stream are important -for efficient asynchronous operations, so this property prevails on -the "no-short-ops" one. So, while blocking streams will avoid short -reads/writes whenever possible (the only case to get a short read is -if end of file is reached, or in case of error (but errors don't -return short data, but raise exceptions)), non-blocking streams may -produce short data to avoid blocking the operation. - -The final dichotomy is binary vs text streams. MicroPython of course -supports these, but while in CPython text streams are inherently -buffered, they aren't in MicroPython. (Indeed, that's one of the cases -for which we may introduce buffering support.) - -Note that for efficiency, MicroPython doesn't provide abstract base -classes corresponding to the hierarchy above, and it's not possible -to implement, or subclass, a stream class in pure Python. - -Functions ---------- - -.. function:: open(name, mode='r', **kwargs) - - Open a file. Builtin ``open()`` function is aliased to this function. - All ports (which provide access to file system) are required to support - ``mode`` parameter, but support for other arguments vary by port. - -Classes -------- - -.. class:: FileIO(...) - - This is type of a file open in binary mode, e.g. using ``open(name, "rb")``. - You should not instantiate this class directly. - -.. class:: TextIOWrapper(...) - - This is type of a file open in text mode, e.g. using ``open(name, "rt")``. - You should not instantiate this class directly. - -.. class:: StringIO([string]) -.. class:: BytesIO([string]) - - In-memory file-like objects for input/output. `StringIO` is used for - text-mode I/O (similar to a normal file opened with "t" modifier). - `BytesIO` is used for binary-mode I/O (similar to a normal file - opened with "b" modifier). Initial contents of file-like objects - can be specified with `string` parameter (should be normal string - for `StringIO` or bytes object for `BytesIO`). All the usual file - methods like ``read()``, ``write()``, ``seek()``, ``flush()``, - ``close()`` are available on these objects, and additionally, a - following method: - - .. method:: getvalue() - - Get the current contents of the underlying buffer which holds data. diff --git a/docs/library/ujson.rst b/docs/library/ujson.rst deleted file mode 100644 index 4ed91f053..000000000 --- a/docs/library/ujson.rst +++ /dev/null @@ -1,37 +0,0 @@ -:mod:`ujson` -- JSON encoding and decoding -========================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: ujson - :synopsis: JSON encoding and decoding - -|see_cpython_module| :mod:`cpython:json`. - -This modules allows to convert between Python objects and the JSON -data format. - -Functions ---------- - -.. function:: dump(obj, stream) - - Serialise ``obj`` to a JSON string, writing it to the given *stream*. - -.. function:: dumps(obj) - - Return ``obj`` represented as a JSON string. - -.. function:: load(stream) - - Parse the given ``stream``, interpreting it as a JSON string and - deserialising the data to a Python object. The resulting object is - returned. - - Parsing continues until end-of-file is encountered. - A :exc:`ValueError` is raised if the data in ``stream`` is not correctly formed. - -.. function:: loads(str) - - Parse the JSON *str* and return an object. Raises :exc:`ValueError` if the - string is not correctly formed. diff --git a/docs/library/ure.rst b/docs/library/ure.rst deleted file mode 100644 index 4af182b01..000000000 --- a/docs/library/ure.rst +++ /dev/null @@ -1,103 +0,0 @@ -:mod:`ure` -- simple regular expressions -======================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: ure - :synopsis: regular expressions - -|see_cpython_module| :mod:`cpython:re`. - -This module implements regular expression operations. Regular expression -syntax supported is a subset of CPython ``re`` module (and actually is -a subset of POSIX extended regular expressions). - -Supported operators are: - -``'.'`` - Match any character. - -``'[...]'`` - Match set of characters. Individual characters and ranges are supported, - including negated sets (e.g. ``[^a-c]``). - -``'^'`` - -``'$'`` - -``'?'`` - -``'*'`` - -``'+'`` - -``'??'`` - -``'*?'`` - -``'+?'`` - -``'|'`` - -``'(...)'`` - Grouping. Each group is capturing (a substring it captures can be accessed - with `match.group()` method). - -**NOT SUPPORTED**: Counted repetitions (``{m,n}``), more advanced assertions -(``\b``, ``\B``), named groups (``(?P...)``), non-capturing groups -(``(?:...)``), etc. - - -Functions ---------- - -.. function:: compile(regex_str, [flags]) - - Compile regular expression, return `regex ` object. - -.. function:: match(regex_str, string) - - Compile *regex_str* and match against *string*. Match always happens - from starting position in a string. - -.. function:: search(regex_str, string) - - Compile *regex_str* and search it in a *string*. Unlike `match`, this will search - string for first position which matches regex (which still may be - 0 if regex is anchored). - -.. data:: DEBUG - - Flag value, display debug information about compiled expression. - - -.. _regex: - -Regex objects -------------- - -Compiled regular expression. Instances of this class are created using -`ure.compile()`. - -.. method:: regex.match(string) - regex.search(string) - - Similar to the module-level functions :meth:`match` and :meth:`search`. - Using methods is (much) more efficient if the same regex is applied to - multiple strings. - -.. method:: regex.split(string, max_split=-1) - - Split a *string* using regex. If *max_split* is given, it specifies - maximum number of splits to perform. Returns list of strings (there - may be up to *max_split+1* elements if it's specified). - -Match objects -------------- - -Match objects as returned by `match()` and `search()` methods. - -.. method:: match.group([index]) - - Return matching (sub)string. *index* is 0 for entire match, - 1 and above for each capturing group. Only numeric groups are supported. diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py index f38c0b64a..ca6ddd3ed 100644 --- a/docs/shared_bindings_matrix.py +++ b/docs/shared_bindings_matrix.py @@ -30,7 +30,7 @@ import sys from concurrent.futures import ThreadPoolExecutor -SUPPORTED_PORTS = ['atmel-samd', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'stm'] +SUPPORTED_PORTS = ['atmel-samd', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'raspberrypi', 'stm'] def get_circuitpython_root_dir(): """ The path to the root './circuitpython' directory @@ -44,7 +44,7 @@ def get_shared_bindings(): """ Get a list of modules in shared-bindings based on folder names """ shared_bindings_dir = get_circuitpython_root_dir() / "shared-bindings" - return [item.name for item in shared_bindings_dir.iterdir()] + ["ulab"] + return [item.name for item in shared_bindings_dir.iterdir()] + ["binascii", "errno", "json", "re", "ulab"] def read_mpconfig(): -- cgit v1.2.3 From 34d63debd5c339a37009b961b9b51defcdf540ae Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Mon, 25 Jan 2021 08:21:55 -0500 Subject: Remove obsolete esp.rst, network.rst --- docs/library/esp.rst | 85 --------------- docs/library/network.rst | 278 ----------------------------------------------- 2 files changed, 363 deletions(-) delete mode 100644 docs/library/esp.rst delete mode 100644 docs/library/network.rst (limited to 'docs') diff --git a/docs/library/esp.rst b/docs/library/esp.rst deleted file mode 100644 index 125aaa890..000000000 --- a/docs/library/esp.rst +++ /dev/null @@ -1,85 +0,0 @@ -:mod:`esp` --- functions related to the ESP8266 -=============================================== - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: esp - :synopsis: functions related to the ESP8266 - -The ``esp`` module contains specific functions related to the ESP8266 module. - - -Functions ---------- - -.. function:: sleep_type([sleep_type]) - - Get or set the sleep type. - - If the *sleep_type* parameter is provided, sets the sleep type to its - value. If the function is called without parameters, returns the current - sleep type. - - The possible sleep types are defined as constants: - - * ``SLEEP_NONE`` -- all functions enabled, - * ``SLEEP_MODEM`` -- modem sleep, shuts down the WiFi Modem circuit. - * ``SLEEP_LIGHT`` -- light sleep, shuts down the WiFi Modem circuit - and suspends the processor periodically. - - The system enters the set sleep mode automatically when possible. - -.. function:: deepsleep(time=0) - - Enter deep sleep. - - The whole module powers down, except for the RTC clock circuit, which can - be used to restart the module after the specified time if the pin 16 is - connected to the reset pin. Otherwise the module will sleep until manually - reset. - -.. function:: flash_id() - - Read the device ID of the flash memory. - -.. function:: flash_read(byte_offset, length_or_buffer) - -.. function:: flash_write(byte_offset, bytes) - -.. function:: flash_erase(sector_no) - -.. function:: set_native_code_location(start, length) - - Set the location that native code will be placed for execution after it is - compiled. Native code is emitted when the ``@micropython.native``, - ``@micropython.viper`` and ``@micropython.asm_xtensa`` decorators are applied - to a function. The ESP8266 must execute code from either iRAM or the lower - 1MByte of flash (which is memory mapped), and this function controls the - location. - - If *start* and *length* are both ``None`` then the native code location is - set to the unused portion of memory at the end of the iRAM1 region. The - size of this unused portion depends on the firmware and is typically quite - small (around 500 bytes), and is enough to store a few very small - functions. The advantage of using this iRAM1 region is that it does not - get worn out by writing to it. - - If neither *start* nor *length* are ``None`` then they should be integers. - *start* should specify the byte offset from the beginning of the flash at - which native code should be stored. *length* specifies how many bytes of - flash from *start* can be used to store native code. *start* and *length* - should be multiples of the sector size (being 4096 bytes). The flash will - be automatically erased before writing to it so be sure to use a region of - flash that is not otherwise used, for example by the firmware or the - filesystem. - - When using the flash to store native code *start+length* must be less - than or equal to 1MByte. Note that the flash can be worn out if repeated - erasures (and writes) are made so use this feature sparingly. - In particular, native code needs to be recompiled and rewritten to flash - on each boot (including wake from deepsleep). - - In both cases above, using iRAM1 or flash, if there is no more room left - in the specified region then the use of a native decorator on a function - will lead to `MemoryError` exception being raised during compilation of - that function. diff --git a/docs/library/network.rst b/docs/library/network.rst deleted file mode 100644 index 3bd41150d..000000000 --- a/docs/library/network.rst +++ /dev/null @@ -1,278 +0,0 @@ -**************************************** -:mod:`network` --- network configuration -**************************************** - -.. include:: ../templates/unsupported_in_circuitpython.inc - -.. module:: network - :noindex: - :synopsis: network configuration - -This module provides network drivers and routing configuration. To use this -module, a MicroPython variant/build with network capabilities must be installed. -Network drivers for specific hardware are available within this module and are -used to configure hardware network interface(s). Network services provided -by configured interfaces are then available for use via the :mod:`usocket` -module. - -For example:: - - # connect/ show IP config a specific network interface - # see below for examples of specific drivers - import network - import utime - nic = network.Driver(...) - if not nic.isconnected(): - nic.connect() - print("Waiting for connection...") - while not nic.isconnected(): - utime.sleep(1) - print(nic.ifconfig()) - - # now use usocket as usual - import usocket as socket - addr = socket.getaddrinfo('micropython.org', 80)[0][-1] - s = socket.socket() - s.connect(addr) - s.send(b'GET / HTTP/1.1\r\nHost: micropython.org\r\n\r\n') - data = s.recv(1000) - s.close() - -Common network adapter interface -================================ - -This section describes an (implied) abstract base class for all network -interface classes implemented by ``MicroPython ports `` -for different hardware. This means that MicroPython does not actually -provide ``AbstractNIC`` class, but any actual NIC class, as described -in the following sections, implements methods as described here. - -.. class:: AbstractNIC(id=None, ...) - -Instantiate a network interface object. Parameters are network interface -dependent. If there are more than one interface of the same type, the first -parameter should be `id`. - - .. method:: active([is_active]) - - Activate ("up") or deactivate ("down") the network interface, if - a boolean argument is passed. Otherwise, query current state if - no argument is provided. Most other methods require an active - interface (behavior of calling them on inactive interface is - undefined). - - .. method:: connect([service_id, key=None, \*, ...]) - - Connect the interface to a network. This method is optional, and - available only for interfaces which are not "always connected". - If no parameters are given, connect to the default (or the only) - service. If a single parameter is given, it is the primary identifier - of a service to connect to. It may be accompanied by a key - (password) required to access said service. There can be further - arbitrary keyword-only parameters, depending on the networking medium - type and/or particular device. Parameters can be used to: a) - specify alternative service identifier types; b) provide additional - connection parameters. For various medium types, there are different - sets of predefined/recommended parameters, among them: - - * WiFi: *bssid* keyword to connect to a specific BSSID (MAC address) - - .. method:: disconnect() - - Disconnect from network. - - .. method:: isconnected() - - Returns ``True`` if connected to network, otherwise returns ``False``. - - .. method:: scan(\*, ...) - - Scan for the available network services/connections. Returns a - list of tuples with discovered service parameters. For various - network media, there are different variants of predefined/ - recommended tuple formats, among them: - - * WiFi: (ssid, bssid, channel, RSSI, authmode, hidden). There - may be further fields, specific to a particular device. - - The function may accept additional keyword arguments to filter scan - results (e.g. scan for a particular service, on a particular channel, - for services of a particular set, etc.), and to affect scan - duration and other parameters. Where possible, parameter names - should match those in connect(). - - .. method:: status() - - Return detailed status of the interface, values are dependent - on the network medium/technology. - - .. method:: ifconfig([(ip, subnet, gateway, dns)]) - - Get/set IP-level network interface parameters: IP address, subnet mask, - gateway and DNS server. When called with no arguments, this method returns - a 4-tuple with the above information. To set the above values, pass a - 4-tuple with the required information. For example:: - - nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - - .. method:: config('param') - config(param=value, ...) - - Get or set general network interface parameters. These methods allow to work - with additional parameters beyond standard IP configuration (as dealt with by - `ifconfig()`). These include network-specific and hardware-specific - parameters and status values. For setting parameters, the keyword argument - syntax should be used, and multiple parameters can be set at once. For - querying, a parameter name should be quoted as a string, and only one - parameter can be queried at a time:: - - # Set WiFi access point name (formally known as ESSID) and WiFi channel - ap.config(essid='My AP', channel=11) - # Query params one by one - print(ap.config('essid')) - print(ap.config('channel')) - # Extended status information also available this way - print(sta.config('rssi')) - -.. _network.WLAN: - -Functions -========= - -.. function:: phy_mode([mode]) - - Get or set the PHY mode. - - If the *mode* parameter is provided, sets the mode to its value. If - the function is called without parameters, returns the current mode. - - The possible modes are defined as constants: - * ``MODE_11B`` -- IEEE 802.11b, - * ``MODE_11G`` -- IEEE 802.11g, - * ``MODE_11N`` -- IEEE 802.11n. - -class WLAN -========== - -This class provides a driver for WiFi network processor in the ESP8266. Example usage:: - - import network - # enable station interface and connect to WiFi access point - nic = network.WLAN(network.STA_IF) - nic.active(True) - nic.connect('your-ssid', 'your-password') - # now use sockets as usual - -Constructors ------------- -.. class:: WLAN(interface_id) - -Create a WLAN network interface object. Supported interfaces are -``network.STA_IF`` (station aka client, connects to upstream WiFi access -points) and ``network.AP_IF`` (access point, allows other WiFi clients to -connect). Availability of the methods below depends on interface type. -For example, only STA interface may `connect()` to an access point. - -Methods -------- - -.. method:: wlan.active([is_active]) - - Activate ("up") or deactivate ("down") network interface, if boolean - argument is passed. Otherwise, query current state if no argument is - provided. Most other methods require active interface. - -.. method:: wlan.connect(ssid=None, password=None, \*, bssid=None) - - Connect to the specified wireless network, using the specified password. - If *bssid* is given then the connection will be restricted to the - access-point with that MAC address (the *ssid* must also be specified - in this case). - -.. method:: wlan.disconnect() - - Disconnect from the currently connected wireless network. - -.. method:: wlan.scan() - - Scan for the available wireless networks. - - Scanning is only possible on STA interface. Returns list of tuples with - the information about WiFi access points: - - (ssid, bssid, channel, RSSI, authmode, hidden) - - *bssid* is hardware address of an access point, in binary form, returned as - bytes object. You can use `binascii.hexlify()` to convert it to ASCII form. - - There are five values for authmode: - - * 0 -- open - * 1 -- WEP - * 2 -- WPA-PSK - * 3 -- WPA2-PSK - * 4 -- WPA/WPA2-PSK - - and two for hidden: - - * 0 -- visible - * 1 -- hidden - -.. method:: wlan.status() - - Return the current status of the wireless connection. - - The possible statuses are defined as constants: - - * ``STAT_IDLE`` -- no connection and no activity, - * ``STAT_CONNECTING`` -- connecting in progress, - * ``STAT_WRONG_PASSWORD`` -- failed due to incorrect password, - * ``STAT_NO_AP_FOUND`` -- failed because no access point replied, - * ``STAT_CONNECT_FAIL`` -- failed due to other problems, - * ``STAT_GOT_IP`` -- connection successful. - -.. method:: wlan.isconnected() - - In case of STA mode, returns ``True`` if connected to a WiFi access - point and has a valid IP address. In AP mode returns ``True`` when a - station is connected. Returns ``False`` otherwise. - -.. method:: wlan.ifconfig([(ip, subnet, gateway, dns)]) - - Get/set IP-level network interface parameters: IP address, subnet mask, - gateway and DNS server. When called with no arguments, this method returns - a 4-tuple with the above information. To set the above values, pass a - 4-tuple with the required information. For example:: - - nic.ifconfig(('192.168.0.4', '255.255.255.0', '192.168.0.1', '8.8.8.8')) - -.. method:: wlan.config('param') - wlan.config(param=value, ...) - - Get or set general network interface parameters. These methods allow to work - with additional parameters beyond standard IP configuration (as dealt with by - `wlan.ifconfig()`). These include network-specific and hardware-specific - parameters. For setting parameters, keyword argument syntax should be used, - multiple parameters can be set at once. For querying, parameters name should - be quoted as a string, and only one parameter can be queries at time:: - - # Set WiFi access point name (formally known as ESSID) and WiFi channel - ap.config(essid='My AP', channel=11) - # Query params one by one - print(ap.config('essid')) - print(ap.config('channel')) - - Following are commonly supported parameters (availability of a specific parameter - depends on network technology type, driver, and ``MicroPython port``). - - ============= =========== - Parameter Description - ============= =========== - mac MAC address (bytes) - essid WiFi access point name (string) - channel WiFi channel (integer) - hidden Whether ESSID is hidden (boolean) - authmode Authentication mode supported (enumeration, see module constants) - password Access password (string) - dhcp_hostname The DHCP hostname to use - ============= =========== -- cgit v1.2.3 From a9f339b4619a55cf5748124180e43afca32d8fb7 Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Mon, 25 Jan 2021 22:40:31 -0500 Subject: typo in circuitpy_mpconfig.h; forgot cxd56 port --- docs/shared_bindings_matrix.py | 2 +- py/circuitpy_mpconfig.h | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/shared_bindings_matrix.py b/docs/shared_bindings_matrix.py index ca6ddd3ed..e62b1d218 100644 --- a/docs/shared_bindings_matrix.py +++ b/docs/shared_bindings_matrix.py @@ -30,7 +30,7 @@ import sys from concurrent.futures import ThreadPoolExecutor -SUPPORTED_PORTS = ['atmel-samd', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'raspberrypi', 'stm'] +SUPPORTED_PORTS = ['atmel-samd', 'cxd56', 'esp32s2', 'litex', 'mimxrt10xx', 'nrf', 'raspberrypi', 'stm'] def get_circuitpython_root_dir(): """ The path to the root './circuitpython' directory diff --git a/py/circuitpy_mpconfig.h b/py/circuitpy_mpconfig.h index c193e61c4..7c7768391 100644 --- a/py/circuitpy_mpconfig.h +++ b/py/circuitpy_mpconfig.h @@ -199,7 +199,7 @@ typedef long mp_off_t; #define MICROPY_PY_COLLECTIONS_ORDEREDDICT (CIRCUITPY_FULL_BUILD) #endif // Opposite setting is deliberate. -#define MICROPY_PY_UERRNO_ERRORCODE (!CIRCUITPY_RE) +#define MICROPY_PY_UERRNO_ERRORCODE (!CIRCUITPY_FULL_BUILD) #define MICROPY_PY_URE_MATCH_GROUPS (CIRCUITPY_RE) #define MICROPY_PY_URE_MATCH_SPAN_START_END (CIRCUITPY_RE) #define MICROPY_PY_URE_SUB (CIRCUITPY_RE) -- cgit v1.2.3 From 5b4249e365f620f7732ff2079fe345eda5074cbf Mon Sep 17 00:00:00 2001 From: Dan Halbert Date: Mon, 25 Jan 2021 23:06:47 -0500 Subject: fix doc typos --- docs/library/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/library/index.rst b/docs/library/index.rst index 94bd8a656..181ff0109 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -6,7 +6,7 @@ MicroPython libraries Python standard libraries and micro-libraries --------------------------------------------- -These libraries are inherited from MicroPython. +The libraries below are inherited from MicroPython. They are similar to the standard Python libraries with the same name. They implement a subset of or a variant of the corresponding standard Python library. @@ -20,7 +20,7 @@ limited flash memory, usually on non-Express builds: These libraries are not currently enabled in any CircuitPython build, but may be in the future, with the ``u`` prefix dropped: -``uctypes`, ``uhashlib``, ``uio``, ``uzlib``. +``uctypes``, ``uhashlib``, ``uzlib``. .. toctree:: :maxdepth: 1 -- cgit v1.2.3 From 365fafb32bc2e395b1d50e75c1a7160ee31eefcd Mon Sep 17 00:00:00 2001 From: "Ryan A. Pavlik" Date: Tue, 26 Jan 2021 10:36:40 -0600 Subject: Update design_guide.rst Add CO2 as a member name, and clarify the description of eCO2. --- docs/design_guide.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 75825893a..7a8c76b50 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -520,7 +520,9 @@ properties. +-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``temperature`` | float | degrees centigrade | +-----------------------+-----------------------+-------------------------------------------------------------------------+ -| ``eCO2`` | float | equivalent CO2 in ppm | +| ``CO2`` | float | measured CO2 in ppm | ++-----------------------+-----------------------+-------------------------------------------------------------------------+ +| ``eCO2`` | float | equivalent/estimated CO2 in ppm (estimated from some other measurement) | +-----------------------+-----------------------+-------------------------------------------------------------------------+ | ``TVOC`` | float | Total Volatile Organic Compounds in ppb | +-----------------------+-----------------------+-------------------------------------------------------------------------+ -- cgit v1.2.3