diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/library/array.rst | 4 | ||||
| -rw-r--r-- | docs/library/btree.rst | 2 | ||||
| -rw-r--r-- | docs/library/framebuf.rst | 8 | ||||
| -rw-r--r-- | docs/library/micropython.rst | 43 | ||||
| -rw-r--r-- | docs/library/sys.rst | 6 | ||||
| -rw-r--r-- | docs/library/uctypes.rst | 35 | ||||
| -rw-r--r-- | docs/library/uio.rst | 2 | ||||
| -rw-r--r-- | docs/library/ujson.rst | 15 | ||||
| -rw-r--r-- | docs/library/ure.rst | 14 | ||||
| -rw-r--r-- | docs/library/uselect.rst | 50 | ||||
| -rw-r--r-- | docs/library/usocket.rst | 4 | ||||
| -rw-r--r-- | docs/library/ussl.rst | 6 | ||||
| -rw-r--r-- | docs/library/uzlib.rst | 2 |
13 files changed, 100 insertions, 91 deletions
diff --git a/docs/library/array.rst b/docs/library/array.rst index 0f1310b68..d0121cb3e 100644 --- a/docs/library/array.rst +++ b/docs/library/array.rst @@ -21,9 +21,9 @@ Classes .. method:: append(val) - Append new element to the end of array, growing it. + Append new element ``val`` to the end of array, growing it. .. method:: extend(iterable) - Append new elements as contained in an iterable to the end of + Append new elements as contained in `iterable` to the end of array, growing it. diff --git a/docs/library/btree.rst b/docs/library/btree.rst index 303a936ad..4c7b30d5c 100644 --- a/docs/library/btree.rst +++ b/docs/library/btree.rst @@ -7,7 +7,7 @@ :synopsis: simple BTree database The ``btree`` module implements a simple key-value database using external -storage (disk files, or in general case, a random-access stream). Keys are +storage (disk files, or in general case, a random-access ``stream``). Keys are stored sorted in the database, and besides efficient retrieval by a key value, a database also supports efficient ordered range scans (retrieval of values with the keys in a given range). On the application interface diff --git a/docs/library/framebuf.rst b/docs/library/framebuf.rst index 80961b872..3117525dd 100644 --- a/docs/library/framebuf.rst +++ b/docs/library/framebuf.rst @@ -150,6 +150,14 @@ Constants Red Green Blue (16-bit, 5+6+5) color format +.. data:: framebuf.GS2_HMSB + + Grayscale (2-bit) color format + .. data:: framebuf.GS4_HMSB Grayscale (4-bit) color format + +.. data:: framebuf.GS8 + + Grayscale (8-bit) color format diff --git a/docs/library/micropython.rst b/docs/library/micropython.rst index 59e1886fa..31065fbe5 100644 --- a/docs/library/micropython.rst +++ b/docs/library/micropython.rst @@ -35,16 +35,17 @@ Functions compilation of scripts, and returns ``None``. Otherwise it returns the current optimisation level. -.. function:: alloc_emergency_exception_buf(size) + The optimisation level controls the following compilation features: - Allocate *size* bytes of RAM for the emergency exception buffer (a good - size is around 100 bytes). The buffer is used to create exceptions in cases - when normal RAM allocation would fail (eg within an interrupt handler) and - therefore give useful traceback information in these situations. + - Assertions: at level 0 assertion statements are enabled and compiled into the + bytecode; at levels 1 and higher assertions are not compiled. + - Built-in ``__debug__`` variable: at level 0 this variable expands to ``True``; + at levels 1 and higher it expands to ``False``. + - Source-code line numbers: at levels 0, 1 and 2 source-code line number are + stored along with the bytecode so that exceptions can report the line number + they occurred at; at levels 3 and higher line numbers are not stored. - A good way to use this function is to put it at the start of your main script - (eg ``boot.py`` or ``main.py``) and then the emergency exception buffer will be active - for all the code following it. + The default optimisation level is usually level 0. .. function:: mem_info([verbose]) @@ -90,29 +91,3 @@ Functions This function can be used to prevent the capturing of Ctrl-C on the incoming stream of characters that is usually used for the REPL, in case that stream is used for other purposes. - -.. function:: schedule(func, arg) - - Schedule the function *func* to be executed "very soon". The function - is passed the value *arg* as its single argument. "Very soon" means that - the MicroPython runtime will do its best to execute the function at the - earliest possible time, given that it is also trying to be efficient, and - that the following conditions hold: - - - A scheduled function will never preempt another scheduled function. - - Scheduled functions are always executed "between opcodes" which means - that all fundamental Python operations (such as appending to a list) - are guaranteed to be atomic. - - A given port may define "critical regions" within which scheduled - functions will never be executed. Functions may be scheduled within - a critical region but they will not be executed until that region - is exited. An example of a critical region is a preempting interrupt - handler (an IRQ). - - A use for this function is to schedule a callback from a preempting IRQ. - Such an IRQ puts restrictions on the code that runs in the IRQ (for example - the heap may be locked) and scheduling a function to call later will lift - those restrictions. - - There is a finite stack to hold the scheduled functions and `schedule` - will raise a `RuntimeError` if the stack is full. diff --git a/docs/library/sys.rst b/docs/library/sys.rst index bb92850b8..2aa15531a 100644 --- a/docs/library/sys.rst +++ b/docs/library/sys.rst @@ -105,15 +105,15 @@ Constants .. data:: stderr - Standard error stream. + Standard error ``stream``. .. data:: stdin - Standard input stream. + Standard input ``stream``. .. data:: stdout - Standard output stream. + Standard output ``stream``. .. data:: version diff --git a/docs/library/uctypes.rst b/docs/library/uctypes.rst index 55de9a0a2..f71b00c1e 100644 --- a/docs/library/uctypes.rst +++ b/docs/library/uctypes.rst @@ -10,7 +10,7 @@ This module implements "foreign data interface" for MicroPython. The idea behind it is similar to CPython's ``ctypes`` modules, but the actual API is different, streamlined and optimized for small size. The basic idea of the module is to define data structure layout with about the same power as the -C language allows, and the access it using familiar dot-syntax to reference +C language allows, and then access it using familiar dot-syntax to reference sub-fields. .. seealso:: @@ -31,25 +31,25 @@ Following are encoding examples for various field types: * Scalar types:: - "field_name": uctypes.UINT32 | 0 + "field_name": offset | uctypes.UINT32 in other words, value is scalar type identifier ORed with field offset (in bytes) from the start of the structure. * Recursive structures:: - "sub": (2, { - "b0": uctypes.UINT8 | 0, - "b1": uctypes.UINT8 | 1, + "sub": (offset, { + "b0": 0 | uctypes.UINT8, + "b1": 1 | uctypes.UINT8, }) i.e. value is a 2-tuple, first element of which is offset, and second is a structure descriptor dictionary (note: offsets in recursive descriptors - are relative to a structure it defines). + are relative to the structure it defines). * Arrays of primitive types:: - "arr": (uctypes.ARRAY | 0, uctypes.UINT8 | 2), + "arr": (offset | uctypes.ARRAY, size | uctypes.UINT8), i.e. value is a 2-tuple, first element of which is ARRAY flag ORed with offset, and second is scalar element type ORed number of elements @@ -57,7 +57,7 @@ Following are encoding examples for various field types: * Arrays of aggregate types:: - "arr2": (uctypes.ARRAY | 0, 2, {"b": uctypes.UINT8 | 0}), + "arr2": (offset | uctypes.ARRAY, size, {"b": 0 | uctypes.UINT8}), i.e. value is a 3-tuple, first element of which is ARRAY flag ORed with offset, second is a number of elements in array, and third is @@ -65,21 +65,21 @@ Following are encoding examples for various field types: * Pointer to a primitive type:: - "ptr": (uctypes.PTR | 0, uctypes.UINT8), + "ptr": (offset | uctypes.PTR, uctypes.UINT8), i.e. value is a 2-tuple, first element of which is PTR flag ORed with offset, and second is scalar element type. * Pointer to an aggregate type:: - "ptr2": (uctypes.PTR | 0, {"b": uctypes.UINT8 | 0}), + "ptr2": (offset | uctypes.PTR, {"b": 0 | uctypes.UINT8}), i.e. value is a 2-tuple, first element of which is PTR flag ORed with offset, second is descriptor of type pointed to. * Bitfields:: - "bitf0": uctypes.BFUINT16 | 0 | 0 << uctypes.BF_POS | 8 << uctypes.BF_LEN, + "bitf0": offset | uctypes.BFUINT16 | lsbit << uctypes.BF_POS | bitsize << uctypes.BF_LEN, i.e. value is type of scalar value containing given bitfield (typenames are similar to scalar types, but prefixes with "BF"), ORed with offset for @@ -88,20 +88,21 @@ Following are encoding examples for various field types: BF_POS and BF_LEN positions, respectively. Bitfield position is counted from the least significant bit, and is the number of right-most bit of a field (in other words, it's a number of bits a scalar needs to be shifted - right to extra the bitfield). + right to extract the bitfield). - In the example above, first UINT16 value will be extracted at offset 0 + In the example above, first a UINT16 value will be extracted at offset 0 (this detail may be important when accessing hardware registers, where particular access size and alignment are required), and then bitfield - whose rightmost bit is least-significant bit of this UINT16, and length - is 8 bits, will be extracted - effectively, this will access - least-significant byte of UINT16. + whose rightmost bit is *lsbit* bit of this UINT16, and length + is *bitsize* bits, will be extracted. For example, if *lsbit* is 0 and + *bitsize* is 8, then effectively it will access least-significant byte + of UINT16. Note that bitfield operations are independent of target byte endianness, in particular, example above will access least-significant byte of UINT16 in both little- and big-endian structures. But it depends on the least significant bit being numbered 0. Some targets may use different - numbering in their native ABI, but ``uctypes`` always uses normalized + numbering in their native ABI, but ``uctypes`` always uses the normalized numbering described above. Module contents diff --git a/docs/library/uio.rst b/docs/library/uio.rst index 5ae8b9ecb..d1f7c111f 100644 --- a/docs/library/uio.rst +++ b/docs/library/uio.rst @@ -8,7 +8,7 @@ |see_cpython_module| :mod:`cpython:io`. -This module contains additional types of stream (file-like) objects +This module contains additional types of ``stream`` (file-like) objects and helper functions. Conceptual hierarchy diff --git a/docs/library/ujson.rst b/docs/library/ujson.rst index 080ee2d03..4ed91f053 100644 --- a/docs/library/ujson.rst +++ b/docs/library/ujson.rst @@ -14,11 +14,24 @@ 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 ValueError if the + 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 index c6457de9a..4af182b01 100644 --- a/docs/library/ure.rst +++ b/docs/library/ure.rst @@ -17,8 +17,9 @@ Supported operators are: ``'.'`` Match any character. -``'[]'`` - Match set of characters. Individual characters and ranges are supported. +``'[...]'`` + Match set of characters. Individual characters and ranges are supported, + including negated sets (e.g. ``[^a-c]``). ``'^'`` @@ -38,18 +39,19 @@ Supported operators are: ``'|'`` -``'()'`` +``'(...)'`` Grouping. Each group is capturing (a substring it captures can be accessed with `match.group()` method). -Counted repetitions (``{m,n}``), more advanced assertions, named groups, -etc. are not supported. +**NOT SUPPORTED**: Counted repetitions (``{m,n}``), more advanced assertions +(``\b``, ``\B``), named groups (``(?P<name>...)``), non-capturing groups +(``(?:...)``), etc. Functions --------- -.. function:: compile(regex_str) +.. function:: compile(regex_str, [flags]) Compile regular expression, return `regex <regex>` object. diff --git a/docs/library/uselect.rst b/docs/library/uselect.rst index 685f5b318..a2b408b20 100644 --- a/docs/library/uselect.rst +++ b/docs/library/uselect.rst @@ -9,7 +9,7 @@ |see_cpython_module| :mod:`cpython:select`. This module provides functions to efficiently wait for events on multiple -streams (select streams which are ready for operations). +``stream`` objects (select streams which are ready for operations). Functions --------- @@ -35,14 +35,17 @@ Methods .. method:: poll.register(obj[, eventmask]) - Register *obj* for polling. *eventmask* is logical OR of: + Register ``stream`` *obj* for polling. *eventmask* is logical OR of: - * ``select.POLLIN`` - data available for reading - * ``select.POLLOUT`` - more data can be written - * ``select.POLLERR`` - error occurred - * ``select.POLLHUP`` - end of stream/connection termination detected + * ``uselect.POLLIN`` - data available for reading + * ``uselect.POLLOUT`` - more data can be written - *eventmask* defaults to ``select.POLLIN | select.POLLOUT``. + Note that flags like ``uselect.POLLHUP`` and ``uselect.POLLERR`` are + *not* valid as input eventmask (these are unsolicited events which + will be returned from `poll()` regardless of whether they are asked + for). This semantics is per POSIX. + + *eventmask* defaults to ``uselect.POLLIN | uselect.POLLOUT``. .. method:: poll.unregister(obj) @@ -52,16 +55,23 @@ Methods Modify the *eventmask* for *obj*. -.. method:: poll.poll([timeout]) +.. method:: poll.poll(timeout=-1) + + Wait for at least one of the registered objects to become ready or have an + exceptional condition, with optional timeout in milliseconds (if *timeout* + arg is not specified or -1, there is no timeout). - Wait for at least one of the registered objects to become ready. Returns - list of (``obj``, ``event``, ...) tuples, ``event`` element specifies - which events happened with a stream and is a combination of ``select.POLL*`` - constants described above. There may be other elements in tuple, depending - on a platform and version, so don't assume that its size is 2. In case of - timeout, an empty list is returned. + Returns list of (``obj``, ``event``, ...) tuples. There may be other elements in + tuple, depending on a platform and version, so don't assume that its size is 2. + The ``event`` element specifies which events happened with a stream and + is a combination of ``uselect.POLL*`` constants described above. Note that + flags ``uselect.POLLHUP`` and ``uselect.POLLERR`` can be returned at any time + (even if were not asked for), and must be acted on accordingly (the + corresponding stream unregistered from poll and likely closed), because + otherwise all further invocations of `poll()` may return immediately with + these flags set for this stream again. - Timeout is in milliseconds. + In case of timeout, an empty list is returned. .. admonition:: Difference to CPython :class: attention @@ -70,15 +80,15 @@ Methods .. method:: poll.ipoll(timeout=-1, flags=0) - Like :meth:`poll.poll`, but instead returns an iterator which yields + Like :meth:`poll.poll`, but instead returns an iterator which yields a ``callee-owned tuples``. This function provides efficient, allocation-free way to poll on streams. If *flags* is 1, one-shot behavior for events is employed: streams for - which events happened, event mask will be automatically reset (equivalent - to ``poll.modify(obj, 0)``), so new events for such a stream won't be - processed until new mask is set with `poll.modify()`. This behavior is - useful for asynchronous I/O schedulers. + which events happened will have their event masks automatically reset + (equivalent to ``poll.modify(obj, 0)``), so new events for such a stream + won't be processed until new mask is set with `poll.modify()`. This + behavior is useful for asynchronous I/O schedulers. .. admonition:: Difference to CPython :class: attention diff --git a/docs/library/usocket.rst b/docs/library/usocket.rst index b07ba4413..2751db6c4 100644 --- a/docs/library/usocket.rst +++ b/docs/library/usocket.rst @@ -14,7 +14,7 @@ This module provides access to the BSD socket interface. .. admonition:: Difference to CPython :class: attention - For efficiency and consistency, socket objects in MicroPython implement a stream + For efficiency and consistency, socket objects in MicroPython implement a ``stream`` (file-like) interface directly. In CPython, you need to convert a socket to a file-like object using `makefile()` method. This method is still supported by MicroPython (but is a no-op), so where compatibility with CPython matters, @@ -245,7 +245,7 @@ Methods Not every ``MicroPython port`` supports this method. A more portable and generic solution is to use `uselect.poll` object. This allows to wait on multiple objects at the same time (and not just on sockets, but on generic - stream objects which support polling). Example:: + ``stream`` objects which support polling). Example:: # Instead of: s.settimeout(1.0) # time in seconds diff --git a/docs/library/ussl.rst b/docs/library/ussl.rst index 34db3151d..91a64b025 100644 --- a/docs/library/ussl.rst +++ b/docs/library/ussl.rst @@ -17,13 +17,13 @@ Functions .. function:: ussl.wrap_socket(sock, server_side=False, keyfile=None, certfile=None, cert_reqs=CERT_NONE, ca_certs=None) - Takes a stream *sock* (usually usocket.socket instance of ``SOCK_STREAM`` type), + Takes a ``stream`` *sock* (usually usocket.socket instance of ``SOCK_STREAM`` type), and returns an instance of ssl.SSLSocket, which wraps the underlying stream in - an SSL context. Returned object has the usual stream interface methods like + an SSL context. Returned object has the usual ``stream`` interface methods like ``read()``, ``write()``, etc. In MicroPython, the returned object does not expose socket interface and methods like ``recv()``, ``send()``. In particular, a server-side SSL socket should be created from a normal socket returned from - `accept()` on a non-SSL listening server socket. + :meth:`~usocket.socket.accept()` on a non-SSL listening server socket. Depending on the underlying module implementation in a particular ``MicroPython port``, some or all keyword arguments above may be not supported. diff --git a/docs/library/uzlib.rst b/docs/library/uzlib.rst index 2a2d9668c..ba08b535c 100644 --- a/docs/library/uzlib.rst +++ b/docs/library/uzlib.rst @@ -27,7 +27,7 @@ Functions .. class:: DecompIO(stream, wbits=0) - Create a stream wrapper which allows transparent decompression of + Create a ``stream`` wrapper which allows transparent decompression of compressed data in another *stream*. This allows to process compressed streams with data larger than available heap size. In addition to values described in :func:`decompress`, *wbits* may take values |