docs/library/index: Update docs after umodule rename.

- Update guide for extending built-in modules.
- Remove any last trace of umodule in other docs.

This work was funded through GitHub Sponsors.

Signed-off-by: Jim Mussared <jim.mussared@gmail.com>

3 files changed, 42 insertions, 30 deletions

diff --git a/docs/library/index.rst b/docs/library/index.rst
index 985a7ad77..e428f3a06 100644
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@@ -191,34 +191,27 @@ The following libraries are specific to the Zephyr port.
 Extending built-in libraries from Python
 ----------------------------------------
 
-Many built-in modules are actually named ``umodule`` rather than ``module``, but
-MicroPython will alias any module prefixed with a ``u`` to the non-``u``
-version. This means that, for example, ``import time`` will first attempt to
-resolve from the filesystem, and then failing that will fall back to the
-built-in ``utime``. On the other hand, ``import utime`` will always go directly
-to the built-in.
+A subset of the built-in modules are able to be extended by Python code by
+providing a module of the same name in the filesystem. This extensibility
+applies to the following Python standard library modules which are built-in to
+the firmware: ``array``, ``binascii``, ``collections``, ``errno``, ``hashlib``,
+``heapq``, ``io``, ``json``, ``os``, ``platform``, ``random``, ``re``,
+``select``, ``socket``, ``ssl``, ``struct``, ``time`` ``zlib``, as well as the
+MicroPython-specific ``machine`` module. All other built-in modules cannot be
+extended from the filesystem.
 
 This allows the user to provide an extended implementation of a built-in library
 (perhaps to provide additional CPython compatibility or missing functionality).
-The user-provided module (in ``module.py``) can still use the built-in
-functionality by importing ``umodule`` directly (e.g. typically an extension
-module ``time.py`` will do ``from utime import *``). This is used extensively
-in :term:`micropython-lib`. See :ref:`packages` for more information.
-
-This extensibility applies to the following Python standard library modules
-which are built-in to the firmware: ``array``, ``binascii``, ``collections``,
-``errno``, ``hashlib``, ``heapq``, ``io``, ``json``, ``os``, ``platform``,
-``random``, ``re``, ``select``, ``socket``, ``ssl``, ``struct``, ``sys``,
-``time``, ``zlib``, as well as the MicroPython-specific libraries: ``bluepy``,
-``bluetooth``, ``machine``, ``timeq``, ``websocket``. All other built-in
-modules cannot be extended from the filesystem.
-
-*Other than when you specifically want to force the use of the built-in module,
-we recommend always using* ``import module`` *rather than* ``import umodule``.
-
-**Note:** In MicroPython v1.21.0 and higher, it is now possible to force an
-import of the built-in module by clearing ``sys.path`` during the import. For
-example, in ``time.py``, you can write::
+This is used extensively in :term:`micropython-lib`, see :ref:`packages` for
+more information. The filesystem module will typically do a wildcard import of
+the built-in module in order to inherit all the globals (classes, functions and
+variables) from the built-in.
+
+In MicroPython v1.21.0 and higher, to prevent the filesystem module from
+importing itself, it can force an import of the built-in module it by
+temporarily clearing ``sys.path`` during the import. For example, to extend the
+``time`` module from Python, a file named ``time.py`` on the filesystem would
+do the following::
 
   _path = sys.path
   sys.path = ()
@@ -228,6 +221,25 @@ example, in ``time.py``, you can write::
     sys.path = _path
     del _path
 
-This is now the preferred way (instead of ``from utime import *``), as the
-``u``-prefix will be removed from the names of built-in modules in a future
-version of MicroPython.
+  def extra_method():
+    pass
+
+The result is that ``time.py`` contains all the globals of the built-in ``time``
+module, but adds ``extra_method``.
+
+In earlier versions of MicroPython, you can force an import of a built-in module
+by appending a ``u`` to the start of its name. For example, ``import utime``
+instead of ``import time``. For example, ``time.py`` on the filesystem could
+look like::
+
+  from utime import *
+
+  def extra_method():
+    pass
+
+This way is still supported, but the ``sys.path`` method described above is now
+preferred as the ``u``-prefix will be removed from the names of built-in
+modules in a future version of MicroPython.
+
+*Other than when it specifically needs to force the use of the built-in module,
+code should always use* ``import module`` *rather than* ``import umodule``.
diff --git a/docs/library/zephyr.DiskAccess.rst b/docs/library/zephyr.DiskAccess.rst
index d19d81a96..3e5fa9a35 100644
--- a/docs/library/zephyr.DiskAccess.rst
+++ b/docs/library/zephyr.DiskAccess.rst
@@ -34,5 +34,5 @@ Methods
 
     These methods implement the simple and extended
     :ref:`block protocol <block-device-interface>` defined by
-    :class:`uos.AbstractBlockDev`.
+    :class:`os.AbstractBlockDev`.
 
diff --git a/docs/library/zephyr.FlashArea.rst b/docs/library/zephyr.FlashArea.rst
index 306347d44..9cd4dd59d 100644
--- a/docs/library/zephyr.FlashArea.rst
+++ b/docs/library/zephyr.FlashArea.rst
@@ -37,4 +37,4 @@ Methods
 
     These methods implement the simple and extended
     :ref:`block protocol <block-device-interface>` defined by
-    :class:`uos.AbstractBlockDev`.
+    :class:`os.AbstractBlockDev`.