CIRCUITPY_* switches for JSON, RE, etc. Doc cleanup

This commit is contained in:
Dan Halbert 2021-01-24 22:49:28 -05:00
parent 97f5d218a5
commit 69869e1439
18 changed files with 96 additions and 154 deletions

View File

@ -1,9 +1,7 @@
:mod:`uerrno` -- system error codes
:mod:`errno` -- system error codes
===================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uerrno
.. module:: errno
:synopsis: system error codes
|see_cpython_module| :mod:`cpython:errno`.
@ -22,7 +20,7 @@ Constants
try:
os.mkdir("my_dir")
except OSError as exc:
if exc.args[0] == uerrno.EEXIST:
if exc.args[0] == errno.EEXIST:
print("Directory already exists")
.. data:: errorcode
@ -30,5 +28,5 @@ Constants
Dictionary mapping numeric error codes to strings with symbolic error
code (see above)::
>>> print(uerrno.errorcode[uerrno.EEXIST])
>>> print(errno.errorcode[uerrno.EEXIST])
EEXIST

View File

@ -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``.
``binascii``, ``errno``, ``json``, ``re``.
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.
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

View File

@ -1,9 +1,7 @@
:mod:`uio` -- input/output streams
:mod:`io` -- input/output streams
==================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: uio
.. module:: io
:synopsis: input/output streams
|see_cpython_module| :mod:`cpython:io`.

View File

@ -1,9 +1,7 @@
:mod:`ujson` -- JSON encoding and decoding
:mod:`json` -- JSON encoding and decoding
==========================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ujson
.. module:: json
:synopsis: JSON encoding and decoding
|see_cpython_module| :mod:`cpython:json`.

View File

@ -1,9 +1,7 @@
:mod:`ure` -- simple regular expressions
:mod:`re` -- simple regular expressions
========================================
.. include:: ../templates/unsupported_in_circuitpython.inc
.. module:: ure
.. module:: re
:synopsis: regular expressions
|see_cpython_module| :mod:`cpython:re`.
@ -77,7 +75,7 @@ Regex objects
-------------
Compiled regular expression. Instances of this class are created using
`ure.compile()`.
`re.compile()`.
.. method:: regex.match(string)
regex.search(string)

View File

@ -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():

View File

@ -44,4 +44,5 @@
#define IGNORE_PIN_PA24 1
#define IGNORE_PIN_PA25 1
#define MICROPY_PY_URE 0
// Can't fit.
#define CIRCUITPY_RE 0

View File

@ -45,11 +45,7 @@
#define MICROPY_PY_BUILTINS_COMPLEX (0)
#define MICROPY_PY_BUILTINS_NOTIMPLEMENTED (0)
#define MICROPY_PY_FUNCTION_ATTRS (0)
// MICROPY_PY_UJSON depends on MICROPY_PY_IO
#define MICROPY_PY_IO (0)
#define MICROPY_PY_REVERSE_SPECIAL_METHODS (0)
#define MICROPY_PY_UBINASCII (0)
#define MICROPY_PY_UJSON (0)
#define MICROPY_PY_COLLECTIONS_ORDEREDDICT (0)
#define MICROPY_PY_UERRNO_LIST \
X(EPERM) \
@ -84,9 +80,6 @@
#define SPI_FLASH_MAX_BAUDRATE 24000000
#define MICROPY_PY_BUILTINS_NOTIMPLEMENTED (1)
#define MICROPY_PY_FUNCTION_ATTRS (1)
// MICROPY_PY_UJSON depends on MICROPY_PY_IO
#define MICROPY_PY_IO (1)
#define MICROPY_PY_UJSON (1)
// MICROPY_PY_UERRNO_LIST - Use the default
#endif // SAM_D5X_E5X

View File

@ -20,26 +20,16 @@ endif
# Put samd21-only choices here.
ifeq ($(CHIP_FAMILY),samd21)
# frequencyio not yet verified as working on SAMD21, though make it possible to override.
ifndef CIRCUITPY_AUDIOMIXER
CIRCUITPY_AUDIOMIXER = 0
endif
ifndef CIRCUITPY_AUDIOMP3
CIRCUITPY_AUDIOMP3 = 0
endif
# The ?='s allow overriding in mpconfigboard.mk.
ifndef CIRCUITPY_BUILTINS_POW3
CIRCUITPY_BUILTINS_POW3 = 0
endif
ifndef CIRCUITPY_FREQUENCYIO
CIRCUITPY_FREQUENCYIO = 0
endif
ifndef CIRCUITPY_TOUCHIO_USE_NATIVE
CIRCUITPY_TOUCHIO_USE_NATIVE = 1
endif
CIRCUITPY_AUDIOMIXER ?= 0
CIRCUITPY_BINASCII ?= 0
CIRCUITPY_AUDIOMP3 ?= 0
CIRCUITPY_BUILTINS_POW3 ?= 0
CIRCUITPY_FREQUENCYIO ?= 0
CIRCUITPY_JSON ?= 0
CIRCUITPY_TOUCHIO_USE_NATIVE ?= 1
# No room for HCI _bleio on SAMD21.
CIRCUITPY_BLEIO_HCI = 0
@ -71,27 +61,13 @@ ifeq ($(CHIP_FAMILY),samd51)
# No native touchio on SAMD51.
CIRCUITPY_TOUCHIO_USE_NATIVE = 0
# The ifndef's allow overriding in mpconfigboard.mk.
# The ?='s allow overriding in mpconfigboard.mk.
ifndef CIRCUITPY_NETWORK
CIRCUITPY_NETWORK = 0
endif
ifndef CIRCUITPY_PS2IO
CIRCUITPY_PS2IO = 1
endif
ifndef CIRCUITPY_SAMD
CIRCUITPY_SAMD = 1
endif
ifndef CIRCUITPY_RGBMATRIX
CIRCUITPY_RGBMATRIX = $(CIRCUITPY_FULL_BUILD)
endif
ifndef CIRCUITPY_FRAMEBUFFERIO
CIRCUITPY_FRAMEBUFFERIO = $(CIRCUITPY_FULL_BUILD)
endif
CIRCUITPY_NETWORK ?= 0
CIRCUITPY_PS2IO ?= 1
CIRCUITPY_SAMD ?= 1
CIRCUITPY_RGBMATRIX ?= $(CIRCUITPY_FULL_BUILD)
CIRCUITPY_FRAMEBUFFERIO ?= $(CIRCUITPY_FULL_BUILD)
endif # samd51

View File

@ -30,7 +30,6 @@
#define MICROPY_NLR_THUMB (0)
#define MICROPY_PY_UJSON (1)
#define MICROPY_USE_INTERNAL_PRINTF (0)
#define MICROPY_PY_SYS_PLATFORM "Espressif ESP32-S2"

View File

@ -31,8 +31,6 @@
#define CIRCUITPY_INTERNAL_NVM_SIZE (0)
#define MICROPY_NLR_THUMB (0)
#define MICROPY_PY_REVERSE_SPECIAL_METHODS (1)
#define MICROPY_PY_UBINASCII (1)
#define MICROPY_PY_UJSON (1)
#include "py/circuitpy_mpconfig.h"

View File

@ -41,8 +41,6 @@ extern uint8_t _ld_default_stack_size;
#define CIRCUITPY_DEFAULT_STACK_SIZE ((uint32_t) &_ld_default_stack_size)
#define MICROPY_PY_BUILTINS_NOTIMPLEMENTED (0)
#define MICROPY_PY_FUNCTION_ATTRS (0)
#define MICROPY_PY_IO (1)
#define MICROPY_PY_UJSON (1)
#define MICROPY_PY_REVERSE_SPECIAL_METHODS (1)

View File

@ -35,11 +35,8 @@
#include "peripherals/nrf/nvm.h" // for FLASH_PAGE_SIZE
#define MICROPY_PY_FUNCTION_ATTRS (1)
#define MICROPY_PY_IO (1)
#define MICROPY_PY_REVERSE_SPECIAL_METHODS (1)
#define MICROPY_PY_SYS_STDIO_BUFFER (1)
#define MICROPY_PY_UBINASCII (1)
#define MICROPY_PY_UJSON (1)
// 24kiB stack
#define CIRCUITPY_DEFAULT_STACK_SIZE (24*1024)

View File

@ -27,7 +27,9 @@
#ifndef __INCLUDED_MPCONFIGPORT_H
#define __INCLUDED_MPCONFIGPORT_H
#define MICROPY_PY_UJSON (1)
#define CIRCUITPY_BINASCII (1)
#define CIRCUITPY_ERRNO (1)
#define CIRCUITPY_JSON (1)
#define CIRCUITPY_INTERNAL_NVM_SIZE 0

View File

@ -31,9 +31,7 @@
#include <stdint.h>
#define MICROPY_PY_FUNCTION_ATTRS (1)
#define MICROPY_PY_IO (1)
#define MICROPY_PY_REVERSE_SPECIAL_METHODS (1)
#define MICROPY_PY_UJSON (1)
extern uint8_t _ld_default_stack_size;

View File

@ -195,21 +195,14 @@ typedef long mp_off_t;
#define MICROPY_PY_BUILTINS_STR_CENTER (CIRCUITPY_FULL_BUILD)
#define MICROPY_PY_BUILTINS_STR_PARTITION (CIRCUITPY_FULL_BUILD)
#define MICROPY_PY_BUILTINS_STR_SPLITLINES (CIRCUITPY_FULL_BUILD)
#define MICROPY_PY_UERRNO (CIRCUITPY_FULL_BUILD)
#ifndef MICROPY_PY_COLLECTIONS_ORDEREDDICT
#define MICROPY_PY_COLLECTIONS_ORDEREDDICT (CIRCUITPY_FULL_BUILD)
#endif
#ifndef MICROPY_PY_UBINASCII
#define MICROPY_PY_UBINASCII (CIRCUITPY_FULL_BUILD)
#endif
// Opposite setting is deliberate.
#define MICROPY_PY_UERRNO_ERRORCODE (!CIRCUITPY_FULL_BUILD)
#ifndef MICROPY_PY_URE
#define MICROPY_PY_URE (CIRCUITPY_FULL_BUILD)
#endif
#define MICROPY_PY_URE_MATCH_GROUPS (CIRCUITPY_FULL_BUILD)
#define MICROPY_PY_URE_MATCH_SPAN_START_END (CIRCUITPY_FULL_BUILD)
#define MICROPY_PY_URE_SUB (CIRCUITPY_FULL_BUILD)
#define MICROPY_PY_UERRNO_ERRORCODE (!CIRCUITPY_RE)
#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)
// LONGINT_IMPL_xxx are defined in the Makefile.
//
@ -301,6 +294,13 @@ extern const struct _mp_obj_module_t audiopwmio_module;
#define AUDIOPWMIO_MODULE
#endif
#if CIRCUITPY_BINASCII
#define MICROPY_PY_UBINASCII CIRCUITPY_BINASCII
#define BINASCII_MODULE { MP_ROM_QSTR(MP_QSTR_binascii), MP_ROM_PTR(&mp_module_ubinascii) },
#else
#define BINASCII_MODULE
#endif
#if CIRCUITPY_BITBANGIO
#define BITBANGIO_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_bitbangio), (mp_obj_t)&bitbangio_module },
extern const struct _mp_obj_module_t bitbangio_module;
@ -399,6 +399,13 @@ extern const struct _mp_obj_module_t terminalio_module;
#define TERMINALIO_MODULE
#endif
#if CIRCUITPY_ERRNO
#define MICROPY_PY_UERRNO (1)
#define ERRNO_MODULE { MP_ROM_QSTR(MP_QSTR_errno), MP_ROM_PTR(&mp_module_uerrno) },
#else
#define ERRNO_MODULE
#endif
#if CIRCUITPY_ESPIDF
extern const struct _mp_obj_module_t espidf_module;
#define ESPIDF_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_espidf),(mp_obj_t)&espidf_module },
@ -470,6 +477,18 @@ extern const struct _mp_obj_module_t ipaddress_module;
#define IPADDRESS_MODULE
#endif
#if CIRCUITPY_JSON
#define MICROPY_PY_UJSON (1)
#define MICROPY_PY_IO (1)
#define JSON_MODULE { MP_ROM_QSTR(MP_QSTR_json), MP_ROM_PTR(&mp_module_ujson) },
#else
#ifndef MICROPY_PY_IO
// We don't need MICROPY_PY_IO unless someone else wants it.
#define MICROPY_PY_IO (0)
#endif
#define JSON_MODULE
#endif
#if CIRCUITPY_MATH
extern const struct _mp_obj_module_t math_module;
#define MATH_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_math), (mp_obj_t)&math_module },
@ -588,6 +607,13 @@ extern const struct _mp_obj_module_t random_module;
#define RANDOM_MODULE
#endif
#if CIRCUITPY_RE
#define MICROPY_PY_URE (1)
#define RE_MODULE { MP_ROM_QSTR(MP_QSTR_re), MP_ROM_PTR(&mp_module_ure) },
#else
#define RE_MODULE
#endif
#if CIRCUITPY_RGBMATRIX
extern const struct _mp_obj_module_t rgbmatrix_module;
#define RGBMATRIX_MODULE { MP_OBJ_NEW_QSTR(MP_QSTR_rgbmatrix),(mp_obj_t)&rgbmatrix_module },
@ -730,25 +756,6 @@ extern const struct _mp_obj_module_t ustack_module;
#define USTACK_MODULE
#endif
// These modules are not yet in shared-bindings, but we prefer the non-uxxx names.
#if MICROPY_PY_UBINASCII
#define BINASCII_MODULE { MP_ROM_QSTR(MP_QSTR_binascii), MP_ROM_PTR(&mp_module_ubinascii) },
#else
#define BINASCII_MODULE
#endif
#if MICROPY_PY_UERRNO
#define ERRNO_MODULE { MP_ROM_QSTR(MP_QSTR_errno), MP_ROM_PTR(&mp_module_uerrno) },
#else
#define ERRNO_MODULE
#endif
#if MICROPY_PY_UJSON
#define JSON_MODULE { MP_ROM_QSTR(MP_QSTR_json), MP_ROM_PTR(&mp_module_ujson) },
#else
#define JSON_MODULE
#endif
#if defined(CIRCUITPY_ULAB) && CIRCUITPY_ULAB
// ulab requires reverse special methods
#if defined(MICROPY_PY_REVERSE_SPECIAL_METHODS) && !MICROPY_PY_REVERSE_SPECIAL_METHODS
@ -760,12 +767,6 @@ extern const struct _mp_obj_module_t ustack_module;
#define ULAB_MODULE
#endif
#if MICROPY_PY_URE
#define RE_MODULE { MP_ROM_QSTR(MP_QSTR_re), MP_ROM_PTR(&mp_module_ure) },
#else
#define RE_MODULE
#endif
// This is not a top-level module; it's microcontroller.watchdog.
#if CIRCUITPY_WATCHDOG
extern const struct _mp_obj_module_t watchdog_module;

View File

@ -86,6 +86,9 @@ endif
endif
CFLAGS += -DCIRCUITPY_AUDIOMP3=$(CIRCUITPY_AUDIOMP3)
CIRCUITPY_BINASCII ?= $(CIRCUITPY_FULL_BUILD)
CFLAGS += -DCIRCUITPY_BINASCII=$(CIRCUITPY_BINASCII)
CIRCUITPY_BITBANGIO ?= $(CIRCUITPY_FULL_BUILD)
CFLAGS += -DCIRCUITPY_BITBANGIO=$(CIRCUITPY_BITBANGIO)
@ -124,6 +127,9 @@ CFLAGS += -DCIRCUITPY_COUNTIO=$(CIRCUITPY_COUNTIO)
CIRCUITPY_DISPLAYIO ?= $(CIRCUITPY_FULL_BUILD)
CFLAGS += -DCIRCUITPY_DISPLAYIO=$(CIRCUITPY_DISPLAYIO)
CIRCUITPY_ERRNO ?= $(CIRCUITPY_FULL_BUILD)
CFLAGS += -DCIRCUITPY_ERRNO=$(CIRCUITPY_ERRNO)
# CIRCUITPY_ESPIDF is handled in the esp32s2 tree.
# Only for ESP32S chips.
# Assume not a ESP build.
@ -158,6 +164,9 @@ CFLAGS += -DCIRCUITPY_I2CPERIPHERAL=$(CIRCUITPY_I2CPERIPHERAL)
CIRCUITPY_IPADDRESS ?= $(CIRCUITPY_WIFI)
CFLAGS += -DCIRCUITPY_IPADDRESS=$(CIRCUITPY_IPADDRESS)
CIRCUITPY_JSON ?= $(CIRCUITPY_FULL_BUILD)
CFLAGS += -DCIRCUITPY_JSON=$(CIRCUITPY_JSON)
CIRCUITPY_MATH ?= 1
CFLAGS += -DCIRCUITPY_MATH=$(CIRCUITPY_MATH)
@ -204,6 +213,9 @@ CFLAGS += -DCIRCUITPY_PWMIO=$(CIRCUITPY_PWMIO)
CIRCUITPY_RANDOM ?= 1
CFLAGS += -DCIRCUITPY_RANDOM=$(CIRCUITPY_RANDOM)
CIRCUITPY_RE ?= $(CIRCUITPY_FULL_BUILD)
CFLAGS += -DCIRCUITPY_RE=$(CIRCUITPY_RE)
# CIRCUITPY_RP2PIO is handled in the raspberrypi tree.
# Only for rp2 chips.
# Assume not a rp2 build.

View File

@ -1,7 +1,7 @@
.. _module-support-matrix:
Support Matrix
===============
Module Support Matrix - Which Modules Are Available on Which Boards
===================================================================
The following table lists the available built-in modules for each CircuitPython
capable board.