SF.net SVN: docutils:[9872 ] trunk/docutils/docutils/r eaders/__init__.py

Revision: 9872
          http://sourceforge.net/p/docutils/code/9872
Author:   aa-turner
Date:     2024-08-09 05:36:39 +0000 (Fri, 09 Aug 2024)
Log Message:
-----------
Add type hints to ``docutils.readers``

Modified Paths:
--------------
    trunk/docutils/docutils/readers/__init__.py

Modified: trunk/docutils/docutils/readers/__init__.py
===================================================================
--- trunk/docutils/docutils/readers/__init__.py	2024-08-09 04:52:40 UTC (rev 9871)
+++ trunk/docutils/docutils/readers/__init__.py	2024-08-09 05:36:39 UTC (rev 9872)
@@ -6,15 +6,27 @@
 This package contains Docutils Reader modules.
 """
 
+from __future__ import annotations
+
 __docformat__ = 'reStructuredText'
 
-from importlib import import_module
+import importlib
 import warnings
+from typing import TYPE_CHECKING, overload
 
 from docutils import utils, parsers, Component
 from docutils.transforms import universal
 
+if TYPE_CHECKING:
+    from typing import Final, Literal
 
+    from docutils import nodes
+    from docutils.io import Input
+    from docutils.parsers import Parser
+    from docutils.readers import doctree, pep, standalone
+    from docutils.transforms import Transform
+
+
 class Reader(Component):
 
     """
@@ -27,15 +39,18 @@
     Call `read()` to process a document.
     """
 
-    component_type = 'reader'
-    config_section = 'readers'
+    component_type: Final = 'reader'
+    config_section: Final = 'readers'
 
-    def get_transforms(self):
+    def get_transforms(self) -> list[type[Transform]]:
         return super().get_transforms() + [universal.Decorations,
                                            universal.ExposeInternals,
                                            universal.StripComments]
 
-    def __init__(self, parser=None, parser_name=None) -> None:
+    def __init__(self,
+                 parser: Parser | str | None = None,
+                 parser_name: str | None = None
+                 ) -> None:
         """
         Initialize the Reader instance.
 
@@ -46,7 +61,7 @@
         Subclasses may use these attributes as they wish.
         """
 
-        self.parser = parser
+        self.parser: Parser | None = parser
         """A `parsers.Parser` instance shared by all doctrees.  May be left
         unspecified if the document source determines the parser."""
 
@@ -60,14 +75,14 @@
             if self.parser is None:
                 self.set_parser(parser_name)
 
-        self.source = None
+        self.source: Input | None = None
         """`docutils.io` IO object, source of input data."""
 
-        self.input = None
+        self.input: str | None = None
         """Raw text input; either a single string or, for more complex cases,
         a collection of strings."""
 
-    def set_parser(self, parser_name) -> None:
+    def set_parser(self, parser_name: str) -> None:
         """Set `self.parser` by name."""
         parser_class = parsers.get_parser_class(parser_name)
         self.parser = parser_class()
@@ -83,11 +98,12 @@
 
     def parse(self) -> None:
         """Parse `self.input` into a document tree."""
-        self.document = document = self.new_document()
+        document = self.new_document()
         self.parser.parse(self.input, document)
         document.current_source = document.current_line = None
+        self.document: nodes.document = document
 
-    def new_document(self):
+    def new_document(self) -> nodes.document:
         """Create and return a new empty document tree (root node)."""
         return utils.new_document(self.source.source_path, self.settings)
 
@@ -101,24 +117,50 @@
     Often used in conjunction with `writers.UnfilteredWriter`.
     """
 
-    def get_transforms(self):
+    def get_transforms(self) -> list[type[Transform]]:
         # Do not add any transforms.  They have already been applied
         # by the reader which originally created the document.
         return Component.get_transforms(self)
 
 
-_reader_aliases = {}
+@overload
+def get_reader_class(
+    reader_name: Literal['standalone']
+) -> type[standalone.Reader]:
+    ...
 
 
-def get_reader_class(reader_name):
+@overload
+def get_reader_class(reader_name: Literal['doctree']) -> type[doctree.Reader]:
+    ...
+
+
+@overload
+def get_reader_class(reader_name: Literal['pep']) -> type[pep.Reader]:
+    ...
+
+
+@overload
+def get_reader_class(reader_name: str) -> type[Reader]:
+    ...
+
+
+def get_reader_class(reader_name: str) -> type[Reader]:
     """Return the Reader class from the `reader_name` module."""
     name = reader_name.lower()
-    name = _reader_aliases.get(name, name)
+    if name == 'standalone':
+        from docutils.readers import standalone
+        return standalone.Reader
+    if name == 'doctree':
+        from docutils.readers import doctree
+        return doctree.Reader
+    if name == 'pep':
+        from docutils.readers import pep
+        return pep.Reader
+
     try:
-        module = import_module('docutils.readers.'+name)
-    except ImportError:
-        try:
-            module = import_module(name)
-        except ImportError as err:
-            raise ImportError(f'Reader "{reader_name}" not found. {err}')
-    return module.Reader
+        module = importlib.import_module(name)
+    except ImportError as err:
+        raise ImportError(f'Reader "{reader_name}" not found.') from err
+    else:
+        return module.Reader

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