Skip to content

Commit dd88b0f

Browse files
kwagyemanclaude
andcommitted
docs: OpenMV-accuracy audit of library reference + TLS tutorial
Scrub the MicroPython library docs for OpenMV correctness, verified against the openmv firmware sources: - Replace non-OpenMV port hedging and generic "Availability" notes with OpenMV-accurate statements (deflate, gzip, zlib, types, string.templatelib, sys, time, errno, hashlib, builtins, io, socket, select, re, os, random, platform). - Fix factual errors verified against firmware config: sys.platform examples, time epoch (STM32 2000 vs Alif/i.MX RT 1970), ticks_cpu, sys.settrace / sys.tracebacklimit availability. - Model re.match as a class (matching select.poll) to remove the genpyi function/class shadowing. - Replace `= ...` placeholder defaults with correct defaults across machine.*, network.LAN, math, omv.ulab.numpy, omv.display.spidisplay. - Add the "Working with TLS certificates" tutorial and link it from the ssl module documentation. genpyi + verify_stubs pass (0 skipped, all signatures match). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 1a65e44 commit dd88b0f

38 files changed

Lines changed: 1403 additions & 420 deletions

docs/library/builtins.rst

Lines changed: 7 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -423,7 +423,7 @@ Functions and types
423423
changes to the dictionary and supports iteration, :func:`len`, the
424424
``in`` operator and set-comparison operators.
425425

426-
.. method:: pop(key: Any, default: Any = ...) -> Any
426+
.. method:: pop(key: Any, default: Any = None) -> Any
427427

428428
Remove *key* from the dictionary and return its value. If *key* is not
429429
present, return *default* if it was supplied; otherwise raise
@@ -546,7 +546,7 @@ Functions and types
546546
MicroPython only a single *other* argument is accepted (CPython accepts
547547
multiple).
548548

549-
.. function:: getattr(obj: Any, name: str, default: Any = ...) -> Any
549+
.. function:: getattr(obj: Any, name: str, default: Any = None) -> Any
550550

551551
Return the value of the named attribute of *obj*. If the attribute does not
552552
exist, *default* is returned if provided, otherwise :exc:`AttributeError` is
@@ -607,7 +607,7 @@ Functions and types
607607
Return ``True`` if *cls* is a subclass (direct, indirect, or virtual) of
608608
*classinfo*.
609609

610-
.. function:: iter(obj: Any, sentinel: Any = ...) -> Iterator[Any]
610+
.. function:: iter(obj: Any, sentinel: Any = None) -> Iterator[Any]
611611

612612
Return an iterator object. With one argument, *obj* must support the
613613
iteration protocol. With two arguments, *obj* must be callable and iteration
@@ -686,7 +686,7 @@ Functions and types
686686
Return an iterator that applies *function* to every item of *iterables*,
687687
yielding the results.
688688

689-
.. function:: max(*args: Any, key: Optional[Callable[[Any], Any]] = None, default: Any = ...) -> Any
689+
.. function:: max(*args: Any, key: Optional[Callable[[Any], Any]] = None, default: Any = None) -> Any
690690

691691
With a single iterable argument, return its largest item. With two or more
692692
arguments, return the largest argument.
@@ -698,12 +698,12 @@ Functions and types
698698
access and slicing of the underlying memory; slicing a memoryview returns
699699
another memoryview rather than a copy.
700700

701-
.. function:: min(*args: Any, key: Optional[Callable[[Any], Any]] = None, default: Any = ...) -> Any
701+
.. function:: min(*args: Any, key: Optional[Callable[[Any], Any]] = None, default: Any = None) -> Any
702702

703703
With a single iterable argument, return its smallest item. With two or more
704704
arguments, return the smallest argument.
705705

706-
.. function:: next(iterator: Iterator[Any], default: Any = ...) -> Any
706+
.. function:: next(iterator: Iterator[Any], default: Any = None) -> Any
707707

708708
Retrieve the next item from *iterator*. If *default* is given and the
709709
iterator is exhausted, *default* is returned instead of raising
@@ -1124,10 +1124,7 @@ Exceptions
11241124
Raised by :func:`sys.exit` to request interpreter termination. Unlike
11251125
most exceptions, it does not produce a traceback when uncaught.
11261126

1127-
On non-embedded ports (i.e. Windows and Unix), an unhandled ``SystemExit``
1128-
exits the MicroPython process in a similar way to CPython.
1129-
1130-
On embedded ports, an unhandled ``SystemExit`` currently causes a
1127+
On the OpenMV Cam, an unhandled ``SystemExit`` currently causes a
11311128
:ref:`soft_reset` of MicroPython.
11321129

11331130
.. exception:: TypeError

docs/library/collections.rst

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -84,8 +84,6 @@ Classes
8484
:noindex:
8585

8686
Return the field names and their values as an :class:`OrderedDict`.
87-
(``namedtuple`` builds types dynamically, so this method has no fixed
88-
host class to attach to in the API model.)
8987

9088
.. class:: OrderedDict(*args: Any, **kwargs: Any)
9189

docs/library/deflate.rst

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,12 +12,10 @@ This module allows compression and decompression of binary data with the
1212

1313
* Added in MicroPython v1.21.
1414

15-
* Decompression: Enabled via the ``MICROPY_PY_DEFLATE`` build option, on by default
16-
on ports with the "extra features" level or higher (which is most boards).
15+
* **Decompression** is available on all OpenMV Cams.
1716

18-
* Compression: Enabled via the ``MICROPY_PY_DEFLATE_COMPRESS`` build option, on
19-
by default on ports with the "full features" level or higher (generally this means
20-
you need to build your own firmware to enable this).
17+
* **Compression** is **not** available on the STM32-based OpenMV Cams. It is
18+
available only on the Alif- and i.MX RT-based OpenMV Cams.
2119

2220
Classes
2321
-------

docs/library/errno.rst

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,19 +4,17 @@
44
.. module:: errno
55
:synopsis: system error codes
66

7-
This module provides access to symbolic error codes for :exc:`OSError` exception,
8-
along with the :data:`errorcode` dictionary mapping numeric codes back to
9-
their symbolic names. The particular inventory of codes depends on the
10-
:term:`MicroPython port`.
7+
This module provides access to symbolic error codes for the :exc:`OSError`
8+
exception, along with the :data:`errorcode` dictionary mapping numeric codes
9+
back to their symbolic names.
1110

1211
Constants
1312
---------
1413

1514
The error codes below are based on the ANSI C / POSIX standard; each is an
16-
integer whose symbolic name starts with ``E``. As noted above, the inventory
17-
of codes depends on the :term:`MicroPython port`; these are the codes provided
18-
by the default MicroPython build. An error code is usually accessed as
19-
``exc.errno`` where ``exc`` is an instance of :exc:`OSError`. Usage example::
15+
integer whose symbolic name starts with ``E``. These are the codes provided on
16+
the OpenMV Cam. An error code is usually accessed as ``exc.errno`` where
17+
``exc`` is an instance of :exc:`OSError`. Usage example::
2018

2119
try:
2220
os.mkdir("my_dir")

docs/library/gzip.rst

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -17,16 +17,17 @@ file or stream object.
1717

1818
**Availability:**
1919

20-
* This module is **not present by default** in official MicroPython firmware
21-
releases as it duplicates functionality available in the :mod:`deflate
22-
<deflate>` module.
20+
* This module is **not included on the OpenMV Cam** by default, as it
21+
duplicates functionality already provided by the :mod:`deflate <deflate>`
22+
module.
2323

24-
* A copy of this module can be installed (or frozen)
24+
* A copy can be installed (or frozen into custom firmware)
2525
from :term:`micropython-lib` (`source <https://github.com/micropython/micropython-lib/blob/master/python-stdlib/gzip/gzip.py>`_).
2626
See :ref:`packages` for more information. This documentation describes that module.
2727

28-
* Compression support will only be available if compression support is enabled
29-
in the built-in :mod:`deflate <deflate>` module.
28+
* Compression is only available if compression is available in the built-in
29+
:mod:`deflate <deflate>` module -- that is, not on the STM32-based OpenMV
30+
Cams (see its availability note above).
3031

3132
Functions
3233
---------

docs/library/hashlib.rst

Lines changed: 13 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -6,23 +6,19 @@
66

77
This module implements binary data hashing algorithms. Each algorithm is
88
exposed as a class whose instances accept incremental data via
9-
``update()`` and produce a fixed-size digest via ``digest()``. The
10-
exact inventory of available algorithms depends on the board. Among the
11-
algorithms which may be implemented:
12-
13-
* SHA256 - The current generation, modern hashing algorithm (of SHA2 series).
14-
It is suitable for cryptographically-secure purposes. Included in the
15-
MicroPython core and any board is recommended to provide this, unless
16-
it has particular code size constraints.
17-
18-
* SHA1 - A previous generation algorithm. Not recommended for new usages,
19-
but SHA1 is a part of number of Internet standards and existing
20-
applications, so boards targeting network connectivity and
21-
interoperability will try to provide this.
22-
23-
* MD5 - A legacy algorithm, not considered cryptographically secure. Only
24-
selected boards, targeting interoperability with legacy applications,
25-
will offer this.
9+
``update()`` and produce a fixed-size digest via ``digest()``. The OpenMV
10+
Cam provides three algorithms:
11+
12+
* SHA256 - The current generation, modern hashing algorithm (of the SHA-2
13+
series). It is suitable for cryptographically-secure purposes and is always
14+
available.
15+
16+
* SHA1 - A previous generation algorithm. Not recommended for new uses, but
17+
SHA1 is part of a number of Internet standards and existing applications,
18+
so it remains available.
19+
20+
* MD5 - A legacy algorithm, not considered cryptographically secure. Provided
21+
for interoperability with legacy applications.
2622

2723
Classes
2824
-------

0 commit comments

Comments
 (0)