SF.net SVN: docutils:[10046 ] trunk

Revision: 10046
          http://sourceforge.net/p/docutils/code/10046
Author:   aa-turner
Date:     2025-03-09 01:45:28 +0000 (Sun, 09 Mar 2025)
Log Message:
-----------
Introduce a private typing utility module

This eliminates all first-party runtime imports of the typing module,
and centralises version checks for new features (such as TypeAlias)
in one place.

Modified Paths:
--------------
    trunk/.flake8
    trunk/docutils/.ruff.toml
    trunk/docutils/docutils/languages/__init__.py
    trunk/docutils/docutils/nodes.py
    trunk/docutils/docutils/parsers/rst/languages/__init__.py
    trunk/docutils/docutils/utils/__init__.py
    trunk/docutils/test/alltests.py

Added Paths:
-----------
    trunk/docutils/docutils/utils/_typing.py

Modified: trunk/.flake8
===================================================================
--- trunk/.flake8	2025-03-09 01:02:23 UTC (rev 10045)
+++ trunk/.flake8	2025-03-09 01:45:28 UTC (rev 10046)
@@ -27,6 +27,10 @@
   # whitespace around the operators with the lowest priority(ies).
   # Use your own judgment; …"
 
+  F811,
+  # F811: "redefinition of unused '…' from line …"
+  # flake8 does not recognise ``@overload`` from any name other than 'typing'.
+
   W503,
   # W503: "line break before binary operator"
   # this is the recommended style (changed on April 16th, 2016)

Modified: trunk/docutils/.ruff.toml
===================================================================
--- trunk/docutils/.ruff.toml	2025-03-09 01:02:23 UTC (rev 10045)
+++ trunk/docutils/.ruff.toml	2025-03-09 01:45:28 UTC (rev 10046)
@@ -4,6 +4,8 @@
 
 [lint]
 preview = true
+typing-modules = ["docutils.utils._typing"]
+
 select = [
     "A",    # flake8-builtins
     "C4",   # flake8-comprehensions

Modified: trunk/docutils/docutils/languages/__init__.py
===================================================================
--- trunk/docutils/docutils/languages/__init__.py	2025-03-09 01:02:23 UTC (rev 10045)
+++ trunk/docutils/docutils/languages/__init__.py	2025-03-09 01:45:28 UTC (rev 10046)
@@ -14,7 +14,6 @@
 __docformat__ = 'reStructuredText'
 
 from importlib import import_module
-from typing import overload
 
 from docutils.utils import normalize_language_tag
 
@@ -21,7 +20,7 @@
 TYPE_CHECKING = False
 if TYPE_CHECKING:
     import types
-    from typing import NoReturn, Protocol, TypeVar
+    from typing import NoReturn, Protocol, TypeVar, overload
 
     from docutils.utils import Reporter
 
@@ -33,6 +32,8 @@
         author_separators: list[str]
 
     LanguageModuleT = TypeVar('LanguageModuleT')
+else:
+    from docutils.utils._typing import overload
 
 
 class LanguageImporter:

Modified: trunk/docutils/docutils/nodes.py
===================================================================
--- trunk/docutils/docutils/nodes.py	2025-03-09 01:02:23 UTC (rev 10045)
+++ trunk/docutils/docutils/nodes.py	2025-03-09 01:45:28 UTC (rev 10046)
@@ -41,11 +41,9 @@
                                  Mapping, Sequence)
     from types import ModuleType
     from typing import Any, ClassVar, Final, Literal, Self, SupportsIndex
-    if sys.version_info[:2] >= (3, 12):
-        from typing import TypeAlias
-    else:
-        from typing_extensions import TypeAlias
 
+    from docutils.utils._typing import TypeAlias
+
     from xml.dom import minidom
 
     from docutils.frontend import Values

Modified: trunk/docutils/docutils/parsers/rst/languages/__init__.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/languages/__init__.py	2025-03-09 01:02:23 UTC (rev 10045)
+++ trunk/docutils/docutils/parsers/rst/languages/__init__.py	2025-03-09 01:45:28 UTC (rev 10046)
@@ -14,14 +14,12 @@
 
 __docformat__ = 'reStructuredText'
 
-from typing import overload
-
 from docutils.languages import LanguageImporter
 
 TYPE_CHECKING = False
 if TYPE_CHECKING:
     import types
-    from typing import NoReturn, Protocol
+    from typing import NoReturn, Protocol, overload
 
     class RSTLanguageModule(Protocol):
         __name__: str
@@ -28,6 +26,8 @@
 
         directives: dict[str, str]
         roles: dict[str, str]
+else:
+    from docutils.utils._typing import overload
 
 
 class RstLanguageImporter(LanguageImporter):

Modified: trunk/docutils/docutils/utils/__init__.py
===================================================================
--- trunk/docutils/docutils/utils/__init__.py	2025-03-09 01:02:23 UTC (rev 10045)
+++ trunk/docutils/docutils/utils/__init__.py	2025-03-09 01:45:28 UTC (rev 10046)
@@ -28,11 +28,9 @@
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence, Iterable
     from typing import Any, Final, Literal, TextIO
-    if sys.version_info[:2] >= (3, 12):
-        from typing import TypeAlias
-    else:
-        from typing_extensions import TypeAlias
 
+    from docutils.utils._typing import TypeAlias
+
     from docutils.nodes import StrPath
     from docutils.frontend import Values
 

Added: trunk/docutils/docutils/utils/_typing.py
===================================================================
--- trunk/docutils/docutils/utils/_typing.py	                        (rev 0)
+++ trunk/docutils/docutils/utils/_typing.py	2025-03-09 01:45:28 UTC (rev 10046)
@@ -0,0 +1,29 @@
+# Copyright: This module has been placed in the public domain.
+# Author: Adam Turner
+
+"""Private helpers for the ``typing`` module."""
+
+from __future__ import annotations
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    import sys
+    from collections.abc import Callable
+    from typing import Any, Final, TypeVar, overload
+
+    if sys.version_info[:2] >= (3, 12):
+        from typing import TypeAlias
+    else:
+        from typing_extensions import TypeAlias  # NoQA: F401
+
+    _F = TypeVar("_F", bound=Callable[..., Any])
+else:
+
+    def _overload_inner(*args, **kwds):
+        raise NotImplementedError
+
+    # Runtime replacement for ``typing.overload``.
+    def overload(func: _F) -> _F:
+        return _overload_inner
+
+__all__: Final = ('overload',)

Modified: trunk/docutils/test/alltests.py
===================================================================
--- trunk/docutils/test/alltests.py	2025-03-09 01:02:23 UTC (rev 10045)
+++ trunk/docutils/test/alltests.py	2025-03-09 01:45:28 UTC (rev 10046)
@@ -33,7 +33,7 @@
     from typing import TextIO
     from unittest.case import TestCase
 
-    from typing_extensions import TypeAlias
+    from docutils.utils._typing import TypeAlias
 
     ErrorTriple: TypeAlias = tuple[
         type[BaseException],

This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.



_______________________________________________
Docutils-checkins mailing list
[email protected]
https://lists.sourceforge.net/lists/listinfo/docutils-checkins