From 8f59364a117944c8895391028dbd39bf0b9cf4a4 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Wed, 16 Feb 2022 15:50:29 -0600 Subject: [PATCH] remove accidentally added docs --- docs/differences/python_35.rst | 181 ------------------------------- docs/differences/python_36.rst | 191 --------------------------------- docs/differences/python_37.rst | 95 ---------------- docs/differences/python_38.rst | 118 -------------------- docs/differences/python_39.rst | 121 --------------------- docs/library/random.rst | 82 -------------- docs/library/stm.rst | 104 ------------------ docs/rp2/tutorial/pio.rst | 123 --------------------- 8 files changed, 1015 deletions(-) delete mode 100644 docs/differences/python_35.rst delete mode 100644 docs/differences/python_36.rst delete mode 100644 docs/differences/python_37.rst delete mode 100644 docs/differences/python_38.rst delete mode 100644 docs/differences/python_39.rst delete mode 100644 docs/library/random.rst delete mode 100644 docs/library/stm.rst delete mode 100644 docs/rp2/tutorial/pio.rst diff --git a/docs/differences/python_35.rst b/docs/differences/python_35.rst deleted file mode 100644 index 84c38c9cc1..0000000000 --- a/docs/differences/python_35.rst +++ /dev/null @@ -1,181 +0,0 @@ -.. _python_35: - -Python 3.5 -========== - -Below is a list of finalised/accepted PEPs for Python 3.5 grouped into their impact to MicroPython. - - +----------------------------------------------------------------------------------------------------------+---------------+ - | **Extensions to the syntax:** | **Status** | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 448 `_ | additional unpacking generalizations | | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 465 `_ | a new matrix multiplication operator | Completed | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 492 `_ | coroutines with async and await syntax | Completed | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | **Extensions and changes to runtime:** | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 461 `_ | % formatting for binary strings | Completed | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 475 `_ | retrying system calls that fail with EINTR | Completed | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 479 `_ | change StopIteration handling inside generators | Completed | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | **Standard library changes:** | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 471 `_ | os.scandir() | | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 485 `_ | math.isclose(), a function for testing | Completed | - | | approximate equality | | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | **Miscellaneous changes:** | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 441 `_ | improved Python zip application support | | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 486 `_ | make the Python Laucher aware of virtual | | - | | environments | | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 484 `_ | type hints (advisory only) | In Progress | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 488 `_ | elimination of PYO files | Not relevant | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - | `PEP 489 `_ | redesigning extension module loading | | - +--------------------------------------------------------+-------------------------------------------------+---------------+ - - -Other Language Changes: - - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Added the *namereplace* error handlers. The *backslashreplace* error handlers now work with decoding and | | - | translating. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Property docstrings are now writable. This is especially useful for collections.namedtuple() docstrings | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Circular imports involving relative imports are now supported. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - - -New Modules: - -* `typing `_ - -* `zipzap `_ - - -Changes to built-in modules: - - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `collections `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *OrderedDict* class is now implemented in C, which makes it 4 to 100 times faster. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | *OrderedDict.items()* , *OrderedDict.keys()* , *OrderedDict.values()* views now support reversed() | | - | iteration. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The deque class now defines *index()*, *insert()*, and *copy()*, and supports the + and * operators. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Docstrings produced by namedtuple() can now be updated. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The UserString class now implements the *__getnewargs__()*, *__rmod__()*, *casefold()*, *format_map()*, | | - | *isprintable()*, and *maketrans()* methods to match the corresponding methods of str. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `heapq `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Element comparison in *merge()* can now be customized by passing a key function in a new optional key | | - | keyword argument, and a new optional *reverse* keyword argument can be used to reverse element comparison | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `io `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | A new *BufferedIOBase.readinto1()* method, that uses at most one call to the underlying raw stream's | | - | *RawIOBase.read()* or *RawIOBase.readinto()* methods | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `json `_ | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | JSON decoder now raises JSONDecodeError instead of ValueError to provide better context information about | | - | the error. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `math `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Two new constants have been added to the math module: *inf* and *nan*. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | A new function *isclose()* provides a way to test for approximate equality. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | A new *gcd()* function has been added. The *fractions.gcd()* function is now deprecated. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `os `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The new *scandir()* function returning an iterator of DirEntry objects has been added. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *urandom()* function now uses the *getrandom()* syscall on Linux 3.17 or newer, and *getentropy()* on | | - | OpenBSD 5.6 and newer, removing the need to use /dev/urandom and avoiding failures due to potential file | | - | descriptor exhaustion. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | New *get_blocking()* and *set_blocking()* functions allow getting and setting a file descriptor's blocking| | - | mode (O_NONBLOCK.) | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | There is a new *os.path.commonpath()* function returning the longest common sub-path of each passed | | - | pathname | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `re `_ | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | References and conditional references to groups with fixed length are now allowed in lookbehind assertions| | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The number of capturing groups in regular expressions is no longer limited to 100. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *sub()* and *subn()* functions now replace unmatched groups with empty strings instead of raising an | | - | exception. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *re.error* exceptions have new attributes, msg, pattern, pos, lineno, and colno, that provide better | | - | context information about the error | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `socket `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Functions with timeouts now use a monotonic clock, instead of a system clock. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | A new *socket.sendfile()* method allows sending a file over a socket by using the high-performance | | - | *os.sendfile()* function on UNIX, resulting in uploads being from 2 to 3 times faster than when using | | - | plain *socket.send()* | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *socket.sendall()* method no longer resets the socket timeout every time bytes are received or sent. | | - | The socket timeout is now the maximum total duration to send all data. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The backlog argument of the *socket.listen()* method is now optional. By default it is set to SOMAXCONN or| | - | to 128, whichever is less. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `ssl `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Memory BIO Support | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | Application-Layer Protocol Negotiation Support | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | There is a new *SSLSocket.version()* method to query the actual protocol version in use. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The SSLSocket class now implements a *SSLSocket.sendfile()* method. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *SSLSocket.send()* method now raises either the *ssl.SSLWantReadError* or *ssl.SSLWantWriteError* | | - | exception on a non-blocking socket if the operation would block. Previously, it would return 0. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *cert_time_to_seconds()* function now interprets the input time as UTC and not as local time, per RFC | | - | 5280. Additionally, the return value is always an int. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | New *SSLObject.shared_ciphers()* and *SSLSocket.shared_ciphers()* methods return the list of ciphers sent | | - | by the client during the handshake. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *SSLSocket.do_handshake()*, *SSLSocket.read()*, *SSLSocket.shutdown()*, and *SSLSocket.write()* | | - | methods of the SSLSocket class no longer reset the socket timeout every time bytes are received or sent. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *match_hostname()* function now supports matching of IP addresses. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `sys `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | A new *set_coroutine_wrapper()* function allows setting a global hook that will be called whenever a | | - | coroutine object is created by an async def function. A corresponding *get_coroutine_wrapper()* can be | | - | used to obtain a currently set wrapper. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | A new *is_finalizing()* function can be used to check if the Python interpreter is shutting down. | | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | `time `_ | - +-----------------------------------------------------------------------------------------------------------+---------------+ - | The *monotonic()* function is now always available | | - +-----------------------------------------------------------------------------------------------------------+---------------+ diff --git a/docs/differences/python_36.rst b/docs/differences/python_36.rst deleted file mode 100644 index 4ea8742243..0000000000 --- a/docs/differences/python_36.rst +++ /dev/null @@ -1,191 +0,0 @@ -.. _python_36: - -Python 3.6 -========== - -Python 3.6 beta 1 was released on 12 Sep 2016, and a summary of the new features can be found here: - - +-----------------------------------------------------------------------------------------------------------+--------------+ - | **New Syntax Features:** | **Status** | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 498 `_ | Literal String Formatting | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 515 `_ | Underscores in Numeric Literals | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 525 `_ | Asynchronous Generators | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 526 `_ | Syntax for Variable Annotations (provisional) | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 530 `_ | Asynchronous Comprehensions | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | **New Built-in Features:** | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 468 `_ | Preserving the order of *kwargs* in a function | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 487 `_ | Simpler customization of class creation | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 520 `_ | Preserving Class Attribute Definition Order | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | **Standard Library Changes:** | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 495 `_ | Local Time Disambiguation | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 506 `_ | Adding A Secrets Module To The Standard Library | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 519 `_ | Adding a file system path protocol | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | **CPython internals:** | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 509 `_ | Add a private version to dict | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 523 `_ | Adding a frame evaluation API to CPython | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | **Linux/Window Changes** | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 524 `_ | Make os.urandom() blocking on Linux | | - | | (during system startup) | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 528 `_ | Change Windows console encoding to UTF-8 | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - | `PEP 529 `_ | Change Windows filesystem encoding to UTF-8 | | - +--------------------------------------------------------+--------------------------------------------------+--------------+ - -Other Language Changes: - - +-------------------------------------------------------------------------------------------------------------+---------------+ - | A *global* or *nonlocal* statement must now textually appear before the first use of the affected name in | | - | the same scope. Previously this was a SyntaxWarning. | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | It is now possible to set a special method to None to indicate that the corresponding operation is not | | - | available. For example, if a class sets *__iter__()* to *None* , the class is not iterable. | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | Long sequences of repeated traceback lines are now abbreviated as *[Previous line repeated {count} more | | - | times]* | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | Import now raises the new exception *ModuleNotFoundError* when it cannot find a module. Code that currently | | - | checks for ImportError (in try-except) will still work. | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | Class methods relying on zero-argument *super()* will now work correctly when called from metaclass methods | | - | during class creation. | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - -Changes to built-in modules: - - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `array `_ | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | Exhausted iterators of *array.array* will now stay exhausted even if the iterated array is extended. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `binascii `_ | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The b2a_base64() function now accepts an optional newline keyword argument to control whether the newline | | - | character is appended to the return value | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `cmath `_ | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The new cmath.tau (τ) constant has been added | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | New constants: *cmath.inf* and *cmath.nan* to match *math.inf* and *math.nan* , and also *cmath.infj* and | | - | *cmath.nanj* to match the format used by complex repr | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `collections `_ | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The new Collection abstract base class has been added to represent sized iterable container classes | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The new *Reversible* abstract base class represents iterable classes that also provide the *__reversed__()* | | - | method. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The new *AsyncGenerator* abstract base class represents asynchronous generators. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The *namedtuple()* function now accepts an optional keyword argument module, which, when specified, is used | | - | for the *__module__* attribute of the returned named tuple class. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The verbose and rename arguments for *namedtuple()* are now keyword-only. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | Recursive *collections.deque* instances can now be pickled. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `hashlib `_ | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | BLAKE2 hash functions were added to the module. *blake2b()* and *blake2s()* are always available and support | | - | the full feature set of BLAKE2. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The SHA-3 hash functions *sha3_224()*, *sha3_256()*, *sha3_384()*, *sha3_512()*, and *SHAKE* hash functions | | - | *shake_128()* and *shake_256()* were added. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The password-based key derivation function *scrypt()* is now available with OpenSSL 1.1.0 and newer. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `json `_ | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | *json.load()* and *json.loads()* now support binary input. Encoded JSON should be represented using either | | - | UTF-8, UTF-16, or UTF-32. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `math `_ | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The new math.tau (τ) constant has been added | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `os `_ | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | A new *close()* method allows explicitly closing a *scandir()* iterator. The *scandir()* iterator now | | - | supports the context manager protocol. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | On Linux, *os.urandom()* now blocks until the system urandom entropy pool is initialized to increase the | | - | security. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The Linux *getrandom()* syscall (get random bytes) is now exposed as the new *os.getrandom()* function. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `re `_ | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | Added support of modifier spans in regular expressions. Examples: *'(?i:p)ython'* matches 'python' and | | - | 'Python', but not 'PYTHON'; *'(?i)g(?-i:v)r'* matches *'GvR'* and *'gvr'*, but not *'GVR'* . | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | Match object groups can be accessed by *__getitem__*, which is equivalent to *group()*. So *mo['name']* is | | - | now equivalent to *mo.group('name')*. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | Match objects now support index-like objects as group indices. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `socket `_ | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The *ioctl()* function now supports the *SIO_LOOPBACK_FAST_PATH* control code. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The *getsockopt()* constants *SO_DOMAIN* , *SO_PROTOCOL*, *SO_PEERSEC* , and *SO_PASSSEC* are now supported. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The *setsockopt()* now supports the *setsockopt(level, optname, None, optlen: int)* form. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The socket module now supports the address family *AF_ALG* to interface with Linux Kernel crypto API. | | - | *ALG_*, *SOL_ALG* and *sendmsg_afalg()* were added. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | New Linux constants *TCP_USER_TIMEOUT* and *TCP_CONGESTION* were added. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `ssl `_ | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | ssl supports OpenSSL 1.1.0. The minimum recommend version is 1.0.2. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | 3DES has been removed from the default cipher suites and ChaCha20 Poly1305 cipher suites have been added. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | *SSLContext* has better default configuration for options and ciphers. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | SSL session can be copied from one client-side connection to another with the new *SSLSession* class. TLS | | - | session resumption can speed up the initial handshake, reduce latency and improve performance. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The new *get_ciphers()* method can be used to get a list of enabled ciphers in order of cipher priority. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | All constants and flags have been converted to *IntEnum* and *IntFlags*. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | Server and client-side specific TLS protocols for *SSLContext* were added. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | Added *SSLContext.post_handshake_auth* to enable and *ssl.SSLSocket.verify_client_post_handshake()* to | | - | initiate TLS 1.3 post-handshake authentication. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `struct `_ | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | now supports IEEE 754 half-precision floats via the 'e' format specifier. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `sys `_ | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The new *getfilesystemencodeerrors()* function returns the name of the error mode used to convert between | | - | Unicode filenames and bytes filenames. | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | `zlib `_ | | - +--------------------------------------------------------------------------------------------------------------+----------------+ - | The *compress()* and *decompress()* functions now accept keyword arguments | | - +--------------------------------------------------------------------------------------------------------------+----------------+ diff --git a/docs/differences/python_37.rst b/docs/differences/python_37.rst deleted file mode 100644 index c46678e931..0000000000 --- a/docs/differences/python_37.rst +++ /dev/null @@ -1,95 +0,0 @@ -.. _python_37: - -Python 3.7 -========== - -New Features: - - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | **Features:** | **Status** | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 538 `_ | Coercing the legacy C locale to a UTF-8 based | | - | | locale | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 539 `_ | A New C-API for Thread-Local Storage in CPython | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 540 `_ | UTF-8 mode | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 552 `_ | Deterministic pyc | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 553 `_ | Built-in breakpoint() | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 557 `_ | Data Classes | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 560 `_ | Core support for typing module and generic types | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 562 `_ | Module __getattr__ and __dir__ | Partially done | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 563 `_ | Postponed Evaluation of Annotations | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 564 `_ | Time functions with nanosecond resolution | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 565 `_ | Show DeprecationWarning in __main__ | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - | `PEP 567 `_ | Context Variables | | - +--------------------------------------------------------+--------------------------------------------------+----------------+ - -Other Language Changes: - - +----------------------------------------------------------------------------------------------------------+----------------+ - | async and await are now reserved keywords | Completed | - +----------------------------------------------------------------------------------------------------------+----------------+ - | dict objects must preserve insertion-order | | - +----------------------------------------------------------------------------------------------------------+----------------+ - | More than 255 arguments can now be passed to a function; a function can now have more than 255 parameters| | - +----------------------------------------------------------------------------------------------------------+----------------+ - | bytes.fromhex() and bytearray.fromhex() now ignore all ASCII whitespace, not only spaces | | - +----------------------------------------------------------------------------------------------------------+----------------+ - | str, bytes, and bytearray gained support for the new isascii() method, which can be used to test if a | | - | string or bytes contain only the ASCII characters | | - +----------------------------------------------------------------------------------------------------------+----------------+ - | ImportError now displays module name and module __file__ path whenfrom ... import ... fails | | - +----------------------------------------------------------------------------------------------------------+----------------+ - | Circular imports involving absolute imports with binding a submodule to a name are now supported | | - +----------------------------------------------------------------------------------------------------------+----------------+ - | object.__format__(x, '') is now equivalent to str(x) rather than format(str(self), '') | | - +----------------------------------------------------------------------------------------------------------+----------------+ - | In order to better support dynamic creation of stack traces, types.TracebackType can now be instantiated | | - | from Python code, and the tb_next attribute on tracebacks is now writable | | - +----------------------------------------------------------------------------------------------------------+----------------+ - | When using the -m switch, sys.path[0] is now eagerly expanded to the full starting directory path, rather| | - | than being left as the empty directory (which allows imports from the current working directory at the | | - | time when an import occurs) | | - +----------------------------------------------------------------------------------------------------------+----------------+ - | The new -X importtime option or the PYTHONPROFILEIMPORTTIME environment variable can be used to show the | | - | timing of each module import | | - +----------------------------------------------------------------------------------------------------------+----------------+ - -Changes to built-in modules: - - +------------------------------------------------------------------------------------------------------------+----------------+ - | `asyncio `_ | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | asyncio (many, may need a separate ticket) | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | `gc `_ | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | New features include *gc.freeze()*, *gc.unfreeze()*, *gc-get_freeze_count* | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | `math `_ | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | math.remainder() added to implement IEEE 754-style remainder | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | `re `_ | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | A number of tidy up features including better support for splitting on empty strings and copy support for | | - | compiled expressions and match objects | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | `sys `_ | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | sys.breakpointhook() added. sys.get(/set)_coroutine_origin_tracking_depth() added | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | `time `_ | | - +------------------------------------------------------------------------------------------------------------+----------------+ - | Mostly updates to support nanosecond resolution in PEP564, see above | | - +------------------------------------------------------------------------------------------------------------+----------------+ diff --git a/docs/differences/python_38.rst b/docs/differences/python_38.rst deleted file mode 100644 index 47840a8b40..0000000000 --- a/docs/differences/python_38.rst +++ /dev/null @@ -1,118 +0,0 @@ -.. _python_38: - -Python 3.8 -========== - -Python 3.8.0 (final) was released on the 14 October 2019. The Features for 3.8 -are defined in `PEP 569 `_ and -a detailed description of the changes can be found in What's New in `Python -3.8. `_ - - +--------------------------------------------------------+---------------------------------------------------+---------------+ - | **Features:** | Status | - +--------------------------------------------------------+---------------------------------------------------+---------------+ - | `PEP 570 `_ | Positional-only arguments | | - +--------------------------------------------------------+---------------------------------------------------+---------------+ - | `PEP 572 `_ | Assignment Expressions | | - +--------------------------------------------------------+---------------------------------------------------+---------------+ - | `PEP 574 `_ | Pickle protocol 5 with out-of-band data | | - +--------------------------------------------------------+---------------------------------------------------+---------------+ - | `PEP 578 `_ | Runtime audit hooks | | - +--------------------------------------------------------+---------------------------------------------------+---------------+ - | `PEP 587 `_ | Python Initialization Configuration | | - +--------------------------------------------------------+---------------------------------------------------+---------------+ - | `PEP 590 `_ | Vectorcall: a fast calling protocol for CPython | | - +--------------------------------------------------------+---------------------------------------------------+---------------+ - | **Miscellaneous** | - +------------------------------------------------------------------------------------------------------------+---------------+ - | f-strings support = for self-documenting expressions and debugging | Completed | - +------------------------------------------------------------------------------------------------------------+---------------+ - -Other Language Changes: - - +------------------------------------------------------------------------------------------------------------+-------------+ - | A *continue* statement was illegal in the *finally* clause due to a problem with the implementation. In | Completed | - | Python 3.8 this restriction was lifted | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | The *bool*, *int* , and *fractions.Fraction* types now have an *as_integer_ratio()* method like that found | | - | in *float* and *decimal.Decimal* | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Constructors of *int*, *float* and *complex* will now use the *__index__()* special method, if available | | - | and the corresponding method *__int__()*, *__float__()* or *__complex__()* is not available | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Added support of *\N{name}* escapes in regular expressions | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Dict and dictviews are now iterable in reversed insertion order using *reversed()* | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | The syntax allowed for keyword names in function calls was further restricted. In particular, | | - | f((keyword)=arg) is no longer allowed | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Generalized iterable unpacking in yield and return statements no longer requires enclosing parentheses | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | When a comma is missed in code such as [(10, 20) (30, 40)], the compiler displays a SyntaxWarning with a | | - | helpful suggestion | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Arithmetic operations between subclasses of *datetime.date* or *datetime.datetime* and *datetime.timedelta*| | - | objects now return an instance of the subclass, rather than the base class | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | When the Python interpreter is interrupted by *Ctrl-C (SIGINT)* and the resulting *KeyboardInterrupt* | | - | exception is not caught, the Python process now exits via a SIGINT signal or with the correct exit code | | - | such that the calling process can detect that it died due to a *Ctrl-C* | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Some advanced styles of programming require updating the *types.CodeType* object for an existing function | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | For integers, the three-argument form of the pow() function now permits the exponent to be negative in the | | - | case where the base is relatively prime to the modulus | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Dict comprehensions have been synced-up with dict literals so that the key is computed first and the value | | - | second | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | The *object.__reduce__()* method can now return a tuple from two to six elements long | | - +------------------------------------------------------------------------------------------------------------+-------------+ - -Changes to built-in modules: - - +------------------------------------------------------------------------------------------------------------+-------------+ - | `asyncio` | - +------------------------------------------------------------------------------------------------------------+-------------+ - | *asyncio.run()* has graduated from the provisional to stable API | Completed | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Running *python -m asyncio* launches a natively async REPL | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | The exception *asyncio.CancelledError* now inherits from *BaseException* rather than *Exception* and no | Completed | - | longer inherits from *concurrent.futures.CancelledError* | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Added *asyncio.Task.get_coro()* for getting the wrapped coroutine within an *asyncio.Task* | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Asyncio tasks can now be named, either by passing the name keyword argument to *asyncio.create_task()* or | | - | the *create_task()* event loop method, or by calling the *set_name()* method on the task object | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Added support for Happy Eyeballs to *asyncio.loop.create_connection()*. To specify the behavior, two new | | - | parameters have been added: *happy_eyeballs_delay* and interleave. | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | `gc` | - +------------------------------------------------------------------------------------------------------------+-------------+ - | *get_objects()* can now receive an optional generation parameter indicating a generation to get objects | | - | from. (Note, though, that while *gc* is a built-in, *get_objects()* is not implemented for MicroPython) | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | `math` | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Added new function *math.dist()* for computing Euclidean distance between two points | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Expanded the *math.hypot()* function to handle multiple dimensions | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Added new function, *math.prod()*, as analogous function to *sum()* that returns the product of a "start" | | - | value (default: 1) times an iterable of numbers | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Added two new combinatoric functions *math.perm()* and *math.comb()* | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Added a new function *math.isqrt()* for computing accurate integer square roots without conversion to | | - | floating point | | - +------------------------------------------------------------------------------------------------------------+-------------+ - | The function *math.factorial()* no longer accepts arguments that are not int-like | Completed | - +------------------------------------------------------------------------------------------------------------+-------------+ - | `sys` | - +------------------------------------------------------------------------------------------------------------+-------------+ - | Add new *sys.unraisablehook()* function which can be overridden to control how "unraisable exceptions" | | - | are handled | | - +------------------------------------------------------------------------------------------------------------+-------------+ diff --git a/docs/differences/python_39.rst b/docs/differences/python_39.rst deleted file mode 100644 index 6852dd635e..0000000000 --- a/docs/differences/python_39.rst +++ /dev/null @@ -1,121 +0,0 @@ -.. _python_39: - -Python 3.9 -========== - -Python 3.9.0 (final) was released on the 5th October 2020. The Features for 3.9 are -defined in `PEP 596 `_ -and a detailed description of the changes can be found in -`What's New in Python 3.9 `_ - - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | **Features:** | | **Status** | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 573 `_ | fast access to module state from methods of C | | - | | extension types | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 584 `_ | union operators added to dict | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 585 `_ | type hinting generics in standard collections | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 593 `_ | flexible function and variable annotations | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 602 `_ | CPython adopts an annual release cycle. Instead of | | - | | annual, aiming for two month release cycle | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 614 `_ | relaxed grammar restrictions on decorators | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 615 `_ | the IANA Time Zone Database is now present in the | | - | | standard library in the zoneinfo module | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 616 `_ | string methods to remove prefixes and suffixes | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - | `PEP 617 `_ | CPython now uses a new parser based on PEG | | - +--------------------------------------------------------+----------------------------------------------------+--------------+ - -Other Language Changes: - - +-------------------------------------------------------------------------------------------------------------+---------------+ - | *__import__()* now raises *ImportError* instead of *ValueError* | Completed | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | Python now gets the absolute path of the script filename specified on the command line (ex: *python3* | | - | *script.py*): the *__file__* attribute of the *__main__* module became an absolute path, rather than a | | - | relative path | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | By default, for best performance, the errors argument is only checked at the first encoding/decoding error | | - | and the encoding argument is sometimes ignored for empty strings | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | *"".replace("", s, n)* now returns *s* instead of an empty string for all non-zero n. It is now consistent | | - | with *"".replace("", s)* | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | Any valid expression can now be used as a decorator. Previously, the grammar was much more restrictive | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | Parallel running of *aclose()* / *asend()* / *athrow()* is now prohibited, and *ag_running* now reflects | | - | the actual running status of the async generator | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | Unexpected errors in calling the *__iter__* method are no longer masked by TypeError in the in operator and | | - | functions contains(), indexOf() and countOf() of the operator module | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - | Unparenthesized lambda expressions can no longer be the expression part in an if clause in comprehensions | | - | and generator expressions | | - +-------------------------------------------------------------------------------------------------------------+---------------+ - -Changes to built-in modules: - - +---------------------------------------------------------------------------------------------------------------+---------------+ - | `asyncio` | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Due to significant security concerns, the reuse_address parameter of *asyncio.loop.create_datagram_endpoint()*| | - | is no longer supported | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added a new coroutine *shutdown_default_executor()* that schedules a shutdown for the default executor that | | - | waits on the *ThreadPoolExecutor* to finish closing. Also, *asyncio.run()* has been updated to use the new | | - | coroutine. | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added *asyncio.PidfdChildWatcher*, a Linux-specific child watcher implementation that polls process file | | - | descriptors | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | added a new *coroutine asyncio.to_thread()* | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | When cancelling the task due to a timeout, *asyncio.wait_for()* will now wait until the cancellation is | | - | complete also in the case when timeout is <= 0, like it does with positive timeouts | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | *asyncio* now raises *TyperError* when calling incompatible methods with an *ssl.SSLSocket* socket | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | `gc` | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Garbage collection does not block on resurrected objects | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added a new function *gc.is_finalized()* to check if an object has been finalized by the garbage collector | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | `math` | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Expanded the *math.gcd()* function to handle multiple arguments. Formerly, it only supported two arguments | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added *math.lcm()*: return the least common multiple of specified arguments | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added *math.nextafter()*: return the next floating-point value after x towards y | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added *math.ulp()*: return the value of the least significant bit of a float | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | `os` | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Exposed the Linux-specific *os.pidfd_open()* and *os.P_PIDFD* | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | The *os.unsetenv()* function is now also available on Windows | Completed | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | The *os.putenv()* and *os.unsetenv()* functions are now always available | Completed | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added *os.waitstatus_to_exitcode()* function: convert a wait status to an exit code | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | `random` | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added a new *random.Random.randbytes* method: generate random bytes | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | `sys` | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Added a new *sys.platlibdir* attribute: name of the platform-specific library directory | | - +---------------------------------------------------------------------------------------------------------------+---------------+ - | Previously, *sys.stderr* was block-buffered when non-interactive. Now stderr defaults to always being | | - | line-buffered | | - +---------------------------------------------------------------------------------------------------------------+---------------+ diff --git a/docs/library/random.rst b/docs/library/random.rst deleted file mode 100644 index dd8b47c80f..0000000000 --- a/docs/library/random.rst +++ /dev/null @@ -1,82 +0,0 @@ -:mod:`random` -- generate random numbers -======================================== - -.. module:: random - :synopsis: random numbers - -This module implements a pseudo-random number generator (PRNG). - -|see_cpython_module| :mod:`python:random` . - -.. note:: - - The following notation is used for intervals: - - - () are open interval brackets and do not include their endpoints. - For example, (0, 1) means greater than 0 and less than 1. - In set notation: (0, 1) = {x | 0 < x < 1}. - - - [] are closed interval brackets which include all their limit points. - For example, [0, 1] means greater than or equal to 0 and less than - or equal to 1. - In set notation: [0, 1] = {x | 0 <= x <= 1}. - -.. note:: - - The :func:`randrange`, :func:`randint` and :func:`choice` functions are only - available if the ``MICROPY_PY_URANDOM_EXTRA_FUNCS`` configuration option is - enabled. - - -Functions for integers ----------------------- - -.. function:: getrandbits(n) - - Return an integer with *n* random bits (0 <= n <= 32). - -.. function:: randint(a, b) - - Return a random integer in the range [*a*, *b*]. - -.. function:: randrange(stop) - randrange(start, stop) - randrange(start, stop[, step]) - - The first form returns a random integer from the range [0, *stop*). - The second form returns a random integer from the range [*start*, *stop*). - The third form returns a random integer from the range [*start*, *stop*) in - steps of *step*. For instance, calling ``randrange(1, 10, 2)`` will - return odd numbers between 1 and 9 inclusive. - - -Functions for floats --------------------- - -.. function:: random() - - Return a random floating point number in the range [0.0, 1.0). - -.. function:: uniform(a, b) - - Return a random floating point number N such that *a* <= N <= *b* for *a* <= *b*, - and *b* <= N <= *a* for *b* < *a*. - - -Other Functions ---------------- - -.. function:: seed(n=None, /) - - Initialise the random number generator module with the seed *n* which should - be an integer. When no argument (or ``None``) is passed in it will (if - supported by the port) initialise the PRNG with a true random number - (usually a hardware generated random number). - - The ``None`` case only works if ``MICROPY_PY_URANDOM_SEED_INIT_FUNC`` is - enabled by the port, otherwise it raises ``ValueError``. - -.. function:: choice(sequence) - - Chooses and returns one item at random from *sequence* (tuple, list or - any object that supports the subscript operation). diff --git a/docs/library/stm.rst b/docs/library/stm.rst deleted file mode 100644 index a181d6044c..0000000000 --- a/docs/library/stm.rst +++ /dev/null @@ -1,104 +0,0 @@ -.. currentmodule:: stm - -:mod:`stm` --- functionality specific to STM32 MCUs -=================================================== - -.. module:: stm - :synopsis: functionality specific to STM32 MCUs - -This module provides functionality specific to STM32 microcontrollers, including -direct access to peripheral registers. - -Memory access -------------- - -The module exposes three objects used for raw memory access. - -.. data:: mem8 - - Read/write 8 bits of memory. - -.. data:: mem16 - - Read/write 16 bits of memory. - -.. data:: mem32 - - Read/write 32 bits of memory. - -Use subscript notation ``[...]`` to index these objects with the address of -interest. - -These memory objects can be used in combination with the peripheral register -constants to read and write registers of the MCU hardware peripherals, as well -as all other areas of address space. - - -Peripheral register constants ------------------------------ - -The module defines constants for registers which are generated from CMSIS header -files, and the constants available depend on the microcontroller series that is -being compiled for. Examples of some constants include: - -.. data:: GPIOA - - Base address of the GPIOA peripheral. - -.. data:: GPIOB - - Base address of the GPIOB peripheral. - -.. data:: GPIO_BSRR - - Offset of the GPIO bit set/reset register. - -.. data:: GPIO_IDR - - Offset of the GPIO input data register. - -.. data:: GPIO_ODR - - Offset of the GPIO output data register. - -Constants that are named after a peripheral, like ``GPIOA``, are the absolute -address of that peripheral. Constants that have a prefix which is the name of a -peripheral, like ``GPIO_BSRR``, are relative offsets of the register. Accessing -peripheral registers requires adding the absolute base address of the peripheral -and the relative register offset. For example ``GPIOA + GPIO_BSRR`` is the -full, absolute address of the ``GPIOA->BSRR`` register. - -Example use: - -.. code-block:: python3 - - # set PA2 high - stm.mem32[stm.GPIOA + stm.GPIO_BSRR] = 1 << 2 - - # read PA3 - value = (stm.mem32[stm.GPIOA + stm.GPIO_IDR] >> 3) & 1 - - -Functions specific to STM32WBxx MCUs ------------------------------------- - -These functions are available on STM32WBxx microcontrollers, and interact with -the second CPU, the RF core. - -.. function:: rfcore_status() - - Returns the status of the second CPU as an integer (the first word of device - info table). - -.. function:: rfcore_fw_version(id) - - Get the version of the firmware running on the second CPU. Pass in 0 for - *id* to get the FUS version, and 1 to get the WS version. - - Returns a 5-tuple with the full version number. - -.. function:: rfcore_sys_hci(ogf, ocf, data, timeout_ms=0) - - Execute a HCI command on the SYS channel. The execution is synchronous. - - Returns a bytes object with the result of the SYS command. diff --git a/docs/rp2/tutorial/pio.rst b/docs/rp2/tutorial/pio.rst deleted file mode 100644 index 9981aed832..0000000000 --- a/docs/rp2/tutorial/pio.rst +++ /dev/null @@ -1,123 +0,0 @@ -Programmable IO -=============== - -The RP2040 has hardware support for standard communication protocols like I2C, -SPI and UART. For protocols where there is no hardware support, or where there -is a requirement of custom I/O behaviour, Programmable Input Output (PIO) comes -into play. Also, some MicroPython applications make use of a technique called -bit banging in which pins are rapidly turned on and off to transmit data. This -can make the entire process slow as the processor concentrates on bit banging -rather than executing other logic. However, PIO allows bit banging to happen -in the background while the CPU is executing the main work. - -Along with the two central Cortex-M0+ processing cores, the RP2040 has two PIO -blocks each of which has four independent state machines. These state machines -can transfer data to/from other entities using First-In-First-Out (FIFO) buffers, -which allow the state machine and main processor to work independently yet also -synchronise their data. Each FIFO has four words (each of 32 bits) which can be -linked to the DMA to transfer larger amounts of data. - -All PIO instructions follow a common pattern:: - - .side() [] - -The side-set ``.side(...)`` and delay ``[...]`` parts are both optional, and if -specified allow the instruction to perform more than one operation. This keeps -PIO programs small and efficient. - -There are nine instructions which perform the following tasks: - -- ``jmp()`` transfers control to a different part of the code -- ``wait()`` pauses until a particular action happens -- ``in_()`` shifts the bits from a source (scratch register or set of pins) to the - input shift register -- ``out()`` shifts the bits from the output shift register to a destination -- ``push()`` sends data to the RX FIFO -- ``pull()`` receives data from the TX FIFO -- ``mov()`` moves data from a source to a destination -- ``irq()`` sets or clears an IRQ flag -- ``set()`` writes a literal value to a destination - -The instruction modifiers are: - -- ``.side()`` sets the side-set pins at the start of the instruction -- ``[]`` delays for a certain number of cycles after execution of the instruction - -There are also directives: - -- ``wrap_target()`` specifies where the program execution will get continued from -- ``wrap()`` specifies the instruction where the control flow of the program will - get wrapped from -- ``label()`` sets a label for use with ``jmp()`` instructions -- ``word()`` emits a raw 16-bit value which acts as an instruction in the program - -An example ----------- - -Take the ``pio_1hz.py`` example for a simple understanding of how to use the PIO -and state machines. Below is the code for reference. - -.. code-block:: python3 - - # Example using PIO to blink an LED and raise an IRQ at 1Hz. - - import time - from machine import Pin - import rp2 - - - @rp2.asm_pio(set_init=rp2.PIO.OUT_LOW) - def blink_1hz(): - # Cycles: 1 + 1 + 6 + 32 * (30 + 1) = 1000 - irq(rel(0)) - set(pins, 1) - set(x, 31) [5] - label("delay_high") - nop() [29] - jmp(x_dec, "delay_high") - - # Cycles: 1 + 7 + 32 * (30 + 1) = 1000 - set(pins, 0) - set(x, 31) [6] - label("delay_low") - nop() [29] - jmp(x_dec, "delay_low") - - - # Create the StateMachine with the blink_1hz program, outputting on Pin(25). - sm = rp2.StateMachine(0, blink_1hz, freq=2000, set_base=Pin(25)) - - # Set the IRQ handler to print the millisecond timestamp. - sm.irq(lambda p: print(time.ticks_ms())) - - # Start the StateMachine. - sm.active(1) - -This creates an instance of class :class:`rp2.StateMachine` which runs the -``blink_1hz`` program at 2000Hz, and connects to pin 25. The ``blink_1hz`` -program uses the PIO to blink an LED connected to this pin at 1Hz, and also -raises an IRQ as the LED turns on. This IRQ then calls the ``lambda`` function -which prints out a millisecond timestamp. - -The ``blink_1hz`` program is a PIO assembler routine. It connects to a single -pin which is configured as an output and starts out low. The instructions do -the following: - -- ``irq(rel(0))`` raises the IRQ associated with the state machine. -- The LED is turned on via the ``set(pins, 1)`` instruction. -- The value 31 is put into register X, and then there is a delay for 5 more - cycles, specified by the ``[5]``. -- The ``nop() [29]`` instruction waits for 30 cycles. -- The ``jmp(x_dec, "delay_high")`` will keep looping to the ``delay_high`` label - as long as the register X is non-zero, and will also post-decrement X. Since - X starts with the value 31 this jump will happen 31 times, so the ``nop() [29]`` - runs 32 times in total (note there is also one instruction cycle taken by the - ``jmp`` for each of these 32 loops). -- ``set(pins, 0)`` will turn the LED off by setting pin 25 low. -- Another 32 loops of ``nop() [29]`` and ``jmp(...)`` will execute. -- Because ``wrap_target()`` and ``wrap()`` are not specified, their default will - be used and execution of the program will wrap around from the bottom to the - top. This wrapping does not cost any execution cycles. - -The entire routine takes exactly 2000 cycles of the state machine. Setting the -frequency of the state machine to 2000Hz makes the LED blink at 1Hz.