Add headings and order to the import_helper section

Author: DavidCEllis

Doc/library/test.rst

@@ -1693,64 +1693,48 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
 
 .. versionadded:: 3.10
 
+Creating Module Objects
+-----------------------
 
-.. function:: forget(modname)
+.. function:: create_module(name, loader=None, *, ispkg=False)
 
-   Remove the module named *modname* from :data:`sys.modules` and delete any
-   byte-compiled files of the module.
+   Create a new, empty :term:`module` or :term:`package` and return it.
 
+   *name*, *loader* and *ispkg* (as ``is_package``) are passed to
+   :class:`importlib.machinery.ModuleSpec`.
 
-.. function:: import_fresh_module(name, fresh=(), blocked=(), *, deprecated=False, usefrozen=False)
 
-   This function imports and returns a fresh copy of the named Python module
-   by removing the named module from :data:`sys.modules` before doing the import.
-   Note that unlike :func:`reload`, the original module is not affected by
-   this operation.
+.. function:: add_module(spec, *, parents=True)
 
-   *fresh* is an iterable of additional module names that are also removed
-   from the :data:`sys.modules` cache before doing the import.
+   Create a :term:`module` from a name or spec and add it to :data:`sys.modules`.
 
-   *blocked* is an iterable of module names that are replaced with ``None``
-   in the module cache during the import to ensure that attempts to import
-   them raise :exc:`ImportError`.
+   If *parents* is ``True`` then also create any missing parent modules.
 
-   The named module and any modules named in the *fresh* and *blocked*
-   parameters are saved before starting the import and then reinserted into
-   :data:`sys.modules` when the fresh import is complete.
+   Return the new module.
 
-   Module and package deprecation messages are suppressed during this import
-   if *deprecated* is ``True``.
 
-   If *usefrozen* is False (the default) then the frozen importer is
-   disabled (except for essential modules like ``importlib._bootstrap``).
+.. function:: add_package(spec, *, parents=True)
 
-   This function will raise :exc:`ImportError` if the named module cannot be
-   imported.
+   Create a :term:`package` from a name and add it to :data:`sys.modules`.
 
-   Example use::
+   If *parents* is ``True`` then also create any missing parent modules.
 
-      # Get copies of the warnings module for testing without affecting the
-      # version being used by the rest of the test suite. One copy uses the
-      # C implementation, the other is forced to use the pure Python fallback
-      # implementation
-      py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
-      c_warnings = import_fresh_module('warnings', fresh=['_warnings'])
+   Return the new package.
 
-   .. versionadded:: 3.1
 
+Manipulating sys.modules
+------------------------
 
-.. function:: import_module(name, deprecated=False, *, required_on=())
 
-   This function imports and returns the named module. Unlike a normal
-   import, this function raises :exc:`unittest.SkipTest` if the module
-   cannot be imported.
+.. function:: unload(name)
 
-   Module and package deprecation messages are suppressed during this import
-   if *deprecated* is ``True``.  If a module is required on a platform but
-   optional for others, set *required_on* to an iterable of platform prefixes
-   which will be compared against :data:`sys.platform`.
+   Remove the module named *name* from :data:`sys.modules`.
 
-   .. versionadded:: 3.1
+
+.. function:: forget(modname)
+
+   Remove the module named *modname* from :data:`sys.modules` and delete any
+   byte-compiled files of the module.
 
 
 .. function:: modules_setup()
@@ -1760,23 +1744,14 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
 
 .. function:: modules_cleanup(oldmodules)
 
-   Remove modules except for *oldmodules* and ``encodings`` in order to
-   preserve internal cache.
+   Remove modules except for *oldmodules* and ``encodings`` from :data:`sys.modules`
+   in order to preserve internal cache.
 
 
-.. function:: unload(name)
-
-   Delete *name* from :data:`sys.modules`.
-
-
-.. function:: make_legacy_pyc(source, allow_compile=False)
-
-   Move a :pep:`3147`/:pep:`488` pyc file to its legacy pyc location and return the file
-   system path to the legacy pyc file.  The *source* value is the file system
-   path to the source file.  It does not need to exist, however the PEP
-   3147/488 pyc file must exist or *allow_compile* must be set.
+.. function:: isolated_modules()
 
-   *allow_compile* will create a .pyc file if it does not exist.
+   A context manager that makes a copy of :data:`sys.modules` on entry and restores
+   it on exit.
 
 
 .. class:: CleanImport(*module_names, usefrozen=False)
@@ -1795,46 +1770,62 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
    Example usage::
 
       with CleanImport('foo'):
-          importlib.import_module('foo')  # New reference.
-
+            importlib.import_module('foo')  # New reference.
 
-.. class:: DirsOnSysPath(*paths)
 
-   A context manager to temporarily add directories to :data:`sys.path`.
+Special importers
+-----------------
 
-   This makes a copy of :data:`sys.path`, appends any directories given
-   as positional arguments, then reverts :data:`sys.path` to the copied
-   settings when the context ends.
-
-   Note that *all* :data:`sys.path` modifications in the body of the
-   context manager, including replacement of the object,
-   will be reverted at the end of the block.
+.. function:: import_module(name, deprecated=False, *, required_on=())
 
+   This function imports and returns the named module. Unlike a normal
+   import, this function raises :exc:`unittest.SkipTest` if the module
+   cannot be imported.
 
-.. function:: create_module(name, loader=None, *, ispkg=False)
+   Module and package deprecation messages are suppressed during this import
+   if *deprecated* is ``True``.  If a module is required on a platform but
+   optional for others, set *required_on* to an iterable of platform prefixes
+   which will be compared against :data:`sys.platform`.
 
-   Create a new, empty :term:`module` or :term:`package` and return it.
+   .. versionadded:: 3.1
 
-   *name*, *loader* and *ispkg* (as ``is_package``) are passed to
-   :class:`importlib.machinery.ModuleSpec`.
+.. function:: import_fresh_module(name, fresh=(), blocked=(), *, deprecated=False, usefrozen=False)
 
+   This function imports and returns a fresh copy of the named Python module
+   by removing the named module from :data:`sys.modules` before doing the import.
+   Note that unlike :func:`reload`, the original module is not affected by
+   this operation.
 
-.. function:: add_module(spec, *, parents=True)
+   *fresh* is an iterable of additional module names that are also removed
+   from the :data:`sys.modules` cache before doing the import.
 
-   Create a :term:`module` from a name or spec and add it to :data:`sys.modules`.
+   *blocked* is an iterable of module names that are replaced with ``None``
+   in the module cache during the import to ensure that attempts to import
+   them raise :exc:`ImportError`.
 
-   If *parents* is ``True`` then also create any missing parent modules.
+   The named module and any modules named in the *fresh* and *blocked*
+   parameters are saved before starting the import and then reinserted into
+   :data:`sys.modules` when the fresh import is complete.
 
-   Return the new module.
+   Module and package deprecation messages are suppressed during this import
+   if *deprecated* is ``True``.
 
+   If *usefrozen* is False (the default) then the frozen importer is
+   disabled (except for essential modules like ``importlib._bootstrap``).
 
-.. function:: add_package(spec, *, parents=True)
+   This function will raise :exc:`ImportError` if the named module cannot be
+   imported.
 
-   Create a :term:`package` from a name and add it to :data:`sys.modules`.
+   Example use::
 
-   If *parents* is ``True`` then also create any missing parent modules.
+      # Get copies of the warnings module for testing without affecting the
+      # version being used by the rest of the test suite. One copy uses the
+      # C implementation, the other is forced to use the pure Python fallback
+      # implementation
+      py_warnings = import_fresh_module('warnings', blocked=['_warnings'])
+      c_warnings = import_fresh_module('warnings', fresh=['_warnings'])
 
-   Return the new package.
+   .. versionadded:: 3.1
 
 
 .. function:: ensure_module_imported(name, *, clearnone=True)
@@ -1849,6 +1840,47 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
    would block the import.
 
 
+Manipulating sys.path
+---------------------
+
+.. class:: DirsOnSysPath(*paths)
+
+   A context manager to temporarily add directories to :data:`sys.path`.
+
+   This makes a copy of :data:`sys.path`, appends any directories given
+   as positional arguments, then reverts :data:`sys.path` to the copied
+   settings when the context ends.
+
+   Note that *all* :data:`sys.path` modifications in the body of the
+   context manager, including replacement of the object,
+   will be reverted at the end of the block.
+
+
+.. function:: ready_to_import(name=None, source="")
+
+   A context manager that will create a new python module *name* with *source*
+   source code in a temporary directory and inserts this directory at the start
+   of :data:`sys.path`.
+
+   If the name matches an existing module, this will be cleared from :data:`sys.modules`
+   on entry and restored on exit.
+
+   Yields (name, path_to_script)
+
+
+Manipulating internals
+----------------------
+
+.. function:: make_legacy_pyc(source, allow_compile=False)
+
+   Move a :pep:`3147`/:pep:`488` pyc file to its legacy pyc location and return the file
+   system path to the legacy pyc file.  The *source* value is the file system
+   path to the source file.  It does not need to exist, however the PEP
+   3147/488 pyc file must exist or *allow_compile* must be set.
+
+   *allow_compile* will create a .pyc file if it does not exist.
+
+
 .. function:: frozen_modules(enabled=True)
 
    A context manager that forces frozen modules to be used or excluded.
@@ -1857,12 +1889,6 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
    modules will always be imported frozen.
 
 
-.. function:: isolated_modules()
-
-   A context manager that makes a copy of :data:`sys.modules` on entry and restores
-   it on exit.
-
-
 .. function:: multi_interp_extensions_check(enabled=True)
 
    A context manager that forces (if ``True``) or prevents legacy (single-phase init)
@@ -1873,17 +1899,8 @@ The :mod:`!test.support.import_helper` module provides support for import tests.
    setting.
 
 
-.. function:: ready_to_import(name=None, source="")
-
-   A context manager that will create a new python module *name* with *source*
-   source code in a temporary directory and inserts this directory at the start
-   of :data:`sys.path`.
-
-   If the name already defines a module, this will be cleared from :data:`sys.modules`
-   on entry and restored on exit.
-
-   Yields (name, path_to_script)
-
+Lazy imports
+------------
 
 .. function:: ensure_lazy_imports(imported_module, modules_to_block, *, additional_code=None)