Merge in MicroPython v1.10

docs/library/collections.rst

@@ -14,6 +14,33 @@ hold/accumulate various objects.
 Classes
 -------
 
+.. function:: deque(iterable, maxlen[, flags])
+
+    Deques (double-ended queues) are a list-like container that support O(1)
+    appends and pops from either side of the deque.  New deques are created
+    using the following arguments:
+
+        - *iterable* must be the empty tuple, and the new deque is created empty.
+
+        - *maxlen* must be specified and the deque will be bounded to this
+          maximum length.  Once the deque is full, any new items added will
+          discard items from the opposite end.
+
+        - The optional *flags* can be 1 to check for overflow when adding items.
+
+    As well as supporting `bool` and `len`, deque objects have the following
+    methods:
+
+    .. method:: deque.append(x)
+
+        Add *x* to the right side of the deque.
+        Raises IndexError if overflow checking is enabled and there is no more room left.
+
+    .. method:: deque.popleft()
+
+        Remove and return an item from the left side of the deque.
+        Raises IndexError if no items are present.
+
 .. function:: namedtuple(name, fields)
 
     This is factory function to create a new namedtuple type with a specific

docs/library/index.rst

@@ -39,8 +39,6 @@ with the ``u`` prefix dropped:
    sys.rst
    uctypes.rst
    uselect.rst
-   usocket.rst
-   ussl.rst
    uzlib.rst
 
 Omitted functions in the ``string`` library

docs/library/micropython.rst

@@ -81,6 +81,9 @@ Functions
    in a row and the lock-depth will increase, and then `heap_unlock()` must be
    called the same number of times to make the heap available again.
 
+   If the REPL becomes active with the heap locked then it will be forcefully
+   unlocked.
+
 .. function:: kbd_intr(chr)
 
    Set the character that will raise a `KeyboardInterrupt` exception.  By

docs/library/re.rst

@@ -10,41 +10,101 @@ This module implements regular expression operations. Regular expression
 syntax supported is a subset of CPython ``re`` module (and actually is
 a subset of POSIX extended regular expressions).
 
-Supported operators are:
+Supported operators and special sequences are:
 
-``'.'``
+``.``
    Match any character.
 
-``'[...]'``
+``[...]``
    Match set of characters. Individual characters and ranges are supported,
    including negated sets (e.g. ``[^a-c]``).
 
-``'^'``
+``^``
+   Match the start of the string.
 
-``'$'``
+``$``
+   Match the end of the string.
 
-``'?'``
+``?``
+   Match zero or one of the previous sub-pattern.
 
-``'*'``
+``*``
+   Match zero or more of the previous sub-pattern.
 
-``'+'``
+``+``
+   Match one or more of the previous sub-pattern.
 
-``'??'``
+``??``
+   Non-greedy version of ``?``, match zero or one, with the preference
+   for zero.
 
-``'*?'``
+``*?``
+   Non-greedy version of ``*``, match zero or more, with the preference
+   for the shortest match.
 
-``'+?'``
+``+?``
+   Non-greedy version of ``+``, match one or more, with the preference
+   for the shortest match.
 
-``'|'``
+``|``
+   Match either the left-hand side or the right-hand side sub-patterns of
+   this operator.
 
-``'(...)'``
+``(...)``
    Grouping. Each group is capturing (a substring it captures can be accessed
    with `match.group()` method).
 
-**NOT SUPPORTED**: Counted repetitions (``{m,n}``), more advanced assertions
-(``\b``, ``\B``), named groups (``(?P<name>...)``), non-capturing groups
-(``(?:...)``), etc.
+``\d``
+   Matches digit. Equivalent to ``[0-9]``.
 
+``\D``
+   Matches non-digit. Equivalent to ``[^0-9]``.
+
+``\s``
+   Matches whitespace. Equivalent to ``[ \t-\r]``.
+
+``\S``
+   Matches non-whitespace. Equivalent to ``[^ \t-\r]``.
+
+``\w``
+   Matches "word characters" (ASCII only). Equivalent to ``[A-Za-z0-9_]``.
+
+``\W``
+   Matches non "word characters" (ASCII only). Equivalent to ``[^A-Za-z0-9_]``.
+
+``\``
+   Escape character. Any other character following the backslash, except
+   for those listed above, is taken literally. For example, ``\*`` is
+   equivalent to literal ``*`` (not treated as the ``*`` operator).
+   Note that ``\r``, ``\n``, etc. are not handled specially, and will be
+   equivalent to literal letters ``r``, ``n``, etc. Due to this, it's
+   not recommended to use raw Python strings (``r""``) for regular
+   expressions. For example, ``r"\r\n"`` when used as the regular
+   expression is equivalent to ``"rn"``. To match CR character followed
+   by LF, use ``"\r\n"``.
+
+**NOT SUPPORTED**:
+
+* counted repetitions (``{m,n}``)
+* named groups (``(?P<name>...)``)
+* non-capturing groups (``(?:...)``)
+* more advanced assertions (``\b``, ``\B``)
+* special character escapes like ``\r``, ``\n`` - use Python's own escaping
+  instead
+* etc.
+
+Example::
+
+    import ure
+
+    # As ure doesn't support escapes itself, use of r"" strings is not
+    # recommended.
+    regex = ure.compile("[\r\n]")
+
+    regex.split("line1\rline2\nline3\r\n")
+
+    # Result:
+    # ['line1', 'line2', 'line3', '', '']
 
 Functions
 ---------
@@ -64,6 +124,22 @@ Functions
    string for first position which matches regex (which still may be
    0 if regex is anchored).
 
+.. function:: sub(regex_str, replace, string, count=0, flags=0)
+
+   Compile *regex_str* and search for it in *string*, replacing all matches
+   with *replace*, and returning the new string.
+
+   *replace* can be a string or a function.  If it is a string then escape
+   sequences of the form ``\<number>`` and ``\g<number>`` can be used to
+   expand to the corresponding group (or an empty string for unmatched groups).
+   If *replace* is a function then it must take a single argument (the match)
+   and should return a replacement string.
+
+   If *count* is specified and non-zero then substitution will stop after
+   this many substitutions are made.  The *flags* argument is ignored.
+
+   Note: availability of this function depends on MicroPython port.
+
 .. data:: DEBUG
 
    Flag value, display debug information about compiled expression.
@@ -79,8 +155,10 @@ Compiled regular expression. Instances of this class are created using
 
 .. method:: regex.match(string)
             regex.search(string)
+            regex.sub(replace, string, count=0, flags=0)
 
-   Similar to the module-level functions :meth:`match` and :meth:`search`.
+   Similar to the module-level functions :meth:`match`, :meth:`search`
+   and :meth:`sub`.
    Using methods is (much) more efficient if the same regex is applied to
    multiple strings.
 
@@ -93,9 +171,31 @@ Compiled regular expression. Instances of this class are created using
 Match objects
 -------------
 
-Match objects as returned by `match()` and `search()` methods.
+Match objects as returned by `match()` and `search()` methods, and passed
+to the replacement function in `sub()`.
 
 .. method:: match.group([index])
 
    Return matching (sub)string. *index* is 0 for entire match,
    1 and above for each capturing group. Only numeric groups are supported.
+
+.. method:: match.groups()
+
+   Return a tuple containing all the substrings of the groups of the match.
+
+   Note: availability of this method depends on MicroPython port.
+
+.. method:: match.start([index])
+            match.end([index])
+
+   Return the index in the original string of the start or end of the
+   substring group that was matched.  *index* defaults to the entire
+   group, otherwise it will select a group.
+
+   Note: availability of these methods depends on MicroPython port.
+
+.. method:: match.span([index])
+
+   Returns the 2-tuple ``(match.start(index), match.end(index))``.
+
+   Note: availability of this method depends on MicroPython port.