Fix all mypy typechecking errors, add a lot of type annotations

.github/workflows/tox.yml

@@ -71,7 +71,7 @@ jobs:
       fail-fast: false
       max-parallel: 4
       matrix:
-        tox-env: [flake8, pep517check, checkspelling]
+        tox-env: [mypy, flake8, pep517check, checkspelling]
 
     env:
       TOXENV: ${{ matrix.tox-env }}

markdown/__main__.py

@@ -24,6 +24,11 @@
 import codecs
 import warnings
 import markdown
+import logging
+from logging import DEBUG, WARNING, CRITICAL
+from typing import Any, Callable, IO, Mapping
+
+yaml_load: Callable[[IO], Any]
 try:
     # We use `unsafe_load` because users may need to pass in actual Python
     # objects. As this is only available from the CLI, the user has much
@@ -32,18 +37,16 @@
 except ImportError:  # pragma: no cover
     try:
         # Fall back to PyYAML <5.1
-        from yaml import load as yaml_load
+        from yaml import load as yaml_load  # type: ignore
     except ImportError:
         # Fall back to JSON
         from json import load as yaml_load
 
-import logging
-from logging import DEBUG, WARNING, CRITICAL
 
 logger = logging.getLogger('MARKDOWN')
 
 
-def parse_options(args=None, values=None):
+def parse_options(args=None, values=None) -> tuple[Mapping[str, Any], bool]:
     """
     Define and parse `optparse` options for command-line usage.
     """

markdown/blockprocessors.py

@@ -121,7 +121,7 @@ def test(self, parent: etree.Element, block: str) -> bool:
             parent: An `etree` element which will be the parent of the block.
             block: A block of text from the source which has been split at blank lines.
         """
-        pass  # pragma: no cover
+        raise NotImplementedError()  # pragma: no cover
 
     def run(self, parent: etree.Element, blocks: list[str]) -> bool | None:
         """ Run processor. Must be overridden by subclasses.
@@ -147,7 +147,7 @@ def run(self, parent: etree.Element, blocks: list[str]) -> bool | None:
             parent: An `etree` element which is the parent of the current block.
             blocks: A list of all remaining blocks of the document.
         """
-        pass  # pragma: no cover
+        raise NotImplementedError()  # pragma: no cover
 
 
 class ListIndentProcessor(BlockProcessor):
@@ -167,15 +167,15 @@ class ListIndentProcessor(BlockProcessor):
     LIST_TYPES = ['ul', 'ol']
     """ Types of lists this processor can operate on. """
 
-    def __init__(self, *args):
+    def __init__(self, *args) -> None:
         super().__init__(*args)
         self.INDENT_RE = re.compile(r'^(([ ]{%s})+)' % self.tab_length)
 
     def test(self, parent: etree.Element, block: str) -> bool:
         return block.startswith(' '*self.tab_length) and \
             not self.parser.state.isstate('detabbed') and \
             (parent.tag in self.ITEM_TYPES or
-                (len(parent) and parent[-1] is not None and
+                (len(parent) > 0 and parent[-1] is not None and
                     (parent[-1].tag in self.LIST_TYPES)))
 
     def run(self, parent: etree.Element, blocks: list[str]) -> None:
@@ -417,7 +417,7 @@ def run(self, parent: etree.Element, blocks: list[str]) -> None:
 
     def get_items(self, block: str) -> list[str]:
         """ Break a block into list items. """
-        items = []
+        items: list[str] = []
         for line in block.split('\n'):
             m = self.CHILD_RE.match(line)
             if m:
@@ -426,7 +426,9 @@ def get_items(self, block: str) -> list[str]:
                 if not items and self.TAG == 'ol':
                     # Detect the integer value of first list item
                     INTEGER_RE = re.compile(r'(\d+)')
-                    self.STARTSWITH = INTEGER_RE.match(m.group(1)).group()
+                    int_match = INTEGER_RE.match(m.group(1))
+                    assert int_match is not None
+                    self.STARTSWITH = int_match.group()
                 # Append to the list
                 items.append(m.group(3))
             elif self.INDENT_RE.match(line):

markdown/core.py

@@ -85,7 +85,7 @@ class Markdown:
     callable which accepts an [`Element`][xml.etree.ElementTree.Element] and returns a `str`.
     """
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs: Any):
         """
         Creates a new Markdown instance.
 
@@ -183,7 +183,7 @@ def registerExtensions(
                     'Successfully loaded extension "%s.%s".'
                     % (ext.__class__.__module__, ext.__class__.__name__)
                 )
-            elif ext is not None:
+            elif ext is not None:  # type: ignore[unreachable]
                 raise TypeError(
                     'Extension "{}.{}" must be of type: "{}.{}"'.format(
                         ext.__class__.__module__, ext.__class__.__name__,
@@ -417,11 +417,11 @@ def convertFile(
         # Read the source
         if input:
             if isinstance(input, str):
-                input_file = codecs.open(input, mode="r", encoding=encoding)
+                with codecs.open(input, mode="r", encoding=encoding) as input_file:
+                    text = input_file.read()
             else:
-                input_file = codecs.getreader(encoding)(input)
-            text = input_file.read()
-            input_file.close()
+                with codecs.getreader(encoding)(input) as input_file:
+                    text = input_file.read()
         else:
             text = sys.stdin.read()
 
@@ -440,13 +440,13 @@ def convertFile(
                 output_file.close()
             else:
                 writer = codecs.getwriter(encoding)
-                output_file = writer(output, errors="xmlcharrefreplace")
-                output_file.write(html)
+                output_writer = writer(output, errors="xmlcharrefreplace")
+                output_writer.write(html)
                 # Don't close here. User may want to write more.
         else:
             # Encode manually and write bytes to stdout.
-            html = html.encode(encoding, "xmlcharrefreplace")
-            sys.stdout.buffer.write(html)
+            html_bytes = html.encode(encoding, "xmlcharrefreplace")
+            sys.stdout.buffer.write(html_bytes)
 
         return self
 
@@ -482,7 +482,13 @@ def markdown(text: str, **kwargs: Any) -> str:
     return md.convert(text)
 
 
-def markdownFromFile(**kwargs: Any):
+def markdownFromFile(
+    *,
+    input: str | BinaryIO | None = None,
+    output: str | BinaryIO | None = None,
+    encoding: str | None = None,
+    **kwargs: Any
+) -> None:
     """
     Read Markdown text from a file and write output to a file or a stream.
 
@@ -491,13 +497,11 @@ def markdownFromFile(**kwargs: Any):
     [`convert`][markdown.Markdown.convert].
 
     Keyword arguments:
-        input (str | BinaryIO): A file name or readable object.
-        output (str | BinaryIO): A file name or writable object.
-        encoding (str): Encoding of input and output.
+        input: A file name or readable object.
+        output: A file name or writable object.
+        encoding: Encoding of input and output.
         **kwargs: Any arguments accepted by the `Markdown` class.
 
     """
     md = Markdown(**kwargs)
-    md.convertFile(kwargs.get('input', None),
-                   kwargs.get('output', None),
-                   kwargs.get('encoding', None))
+    md.convertFile(input, output, encoding)

markdown/extensions/__init__.py

@@ -53,7 +53,7 @@ class Extension:
     if a default is not set for each option.
     """
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs) -> None:
         """ Initiate Extension and set up configs. """
         self.setConfigs(kwargs)
 

markdown/extensions/abbr.py

@@ -28,12 +28,16 @@
 from ..util import AtomicString
 import re
 import xml.etree.ElementTree as etree
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover
+    from markdown import Markdown
 
 
 class AbbrExtension(Extension):
     """ Abbreviation Extension for Python-Markdown. """
 
-    def extendMarkdown(self, md):
+    def extendMarkdown(self, md: Markdown) -> None:
         """ Insert `AbbrPreprocessor` before `ReferencePreprocessor`. """
         md.parser.blockprocessors.register(AbbrPreprocessor(md.parser), 'abbr', 16)
 

markdown/extensions/admonition.py

@@ -33,13 +33,14 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:  # pragma: no cover
+    from markdown import Markdown
     from markdown import blockparser
 
 
 class AdmonitionExtension(Extension):
     """ Admonition extension for Python-Markdown. """
 
-    def extendMarkdown(self, md):
+    def extendMarkdown(self, md: Markdown) -> None:
         """ Add Admonition to Markdown instance. """
         md.registerExtension(self)
 
@@ -59,7 +60,7 @@ def __init__(self, parser: blockparser.BlockParser):
         super().__init__(parser)
 
         self.current_sibling: etree.Element | None = None
-        self.content_indention = 0
+        self.content_indent = 0
 
     def parse_content(self, parent: etree.Element, block: str) -> tuple[etree.Element | None, str, str]:
         """Get sibling admonition.
@@ -74,11 +75,11 @@ def parse_content(self, parent: etree.Element, block: str) -> tuple[etree.Elemen
 
         # We already acquired the block via test
         if self.current_sibling is not None:
-            sibling = self.current_sibling
+            prev_sibling = self.current_sibling
             block, the_rest = self.detab(block, self.content_indent)
             self.current_sibling = None
             self.content_indent = 0
-            return sibling, block, the_rest
+            return prev_sibling, block, the_rest
 
         sibling = self.lastChild(parent)
 
@@ -147,6 +148,7 @@ def run(self, parent: etree.Element, blocks: list[str]) -> None:
                 p.text = title
                 p.set('class', self.CLASSNAME_TITLE)
         else:
+            assert sibling is not None
             # Sibling is a list item, but we need to wrap it's content should be wrapped in <p>
             if sibling.tag in ('li', 'dd') and sibling.text:
                 text = sibling.text

markdown/extensions/attr_list.py

@@ -32,6 +32,7 @@
 
 if TYPE_CHECKING:  # pragma: no cover
     from xml.etree.ElementTree import Element
+    from markdown import Markdown
 
 
 def _handle_double_quote(s, t):
@@ -56,7 +57,7 @@ def _handle_word(s, t):
     return t, t
 
 
-_scanner = re.Scanner([
+_scanner = re.Scanner([  # type: ignore[attr-defined]
     (r'[^ =]+=".*?"', _handle_double_quote),
     (r"[^ =]+='.*?'", _handle_single_quote),
     (r'[^ =]+=[^ =]+', _handle_key_value),
@@ -86,6 +87,8 @@ class AttrListTreeprocessor(Treeprocessor):
                          r'\uf900-\ufdcf\ufdf0-\ufffd'
                          r'\:\-\.0-9\u00b7\u0300-\u036f\u203f-\u2040]+')
 
+    md: Markdown
+
     def run(self, doc: Element) -> None:
         for elem in doc.iter():
             if self.md.is_block_level(elem.tag):
@@ -102,18 +105,18 @@ def run(self, doc: Element) -> None:
                         if child.tag in ['ul', 'ol']:
                             pos = i
                             break
-                    if pos is None and elem[-1].tail:
+                    if pos is None and (tail := elem[-1].tail):
                         # use tail of last child. no `ul` or `ol`.
-                        m = RE.search(elem[-1].tail)
+                        m = RE.search(tail)
                         if m:
                             self.assign_attrs(elem, m.group(1))
-                            elem[-1].tail = elem[-1].tail[:m.start()]
-                    elif pos is not None and pos > 0 and elem[pos-1].tail:
+                            elem[-1].tail = tail[:m.start()]
+                    elif pos is not None and pos > 0 and (tail := elem[pos-1].tail):
                         # use tail of last child before `ul` or `ol`
-                        m = RE.search(elem[pos-1].tail)
+                        m = RE.search(tail)
                         if m:
                             self.assign_attrs(elem, m.group(1))
-                            elem[pos-1].tail = elem[pos-1].tail[:m.start()]
+                            elem[pos-1].tail = tail[:m.start()]
                     elif elem.text:
                         # use text. `ul` is first child.
                         m = RE.search(elem.text)
@@ -170,7 +173,7 @@ def sanitize_name(self, name: str) -> str:
 
 class AttrListExtension(Extension):
     """ Attribute List extension for Python-Markdown """
-    def extendMarkdown(self, md):
+    def extendMarkdown(self, md: Markdown) -> None:
         md.treeprocessors.register(AttrListTreeprocessor(md), 'attr_list', 8)
         md.registerExtension(self)
 

markdown/extensions/codehilite.py

@@ -27,6 +27,7 @@
 from typing import TYPE_CHECKING, Callable, Any
 
 if TYPE_CHECKING:  # pragma: no cover
+    from markdown import Markdown
     import xml.etree.ElementTree as etree
 
 try:  # pragma: no cover
@@ -150,7 +151,7 @@ def hilite(self, shebang: bool = True) -> str:
 
         if pygments and self.use_pygments:
             try:
-                lexer = get_lexer_by_name(self.lang, **self.options)
+                lexer = get_lexer_by_name(self.lang or '', **self.options)
             except ValueError:
                 try:
                     if self.guess_lang:
@@ -161,7 +162,7 @@ def hilite(self, shebang: bool = True) -> str:
                     lexer = get_lexer_by_name('text', **self.options)
             if not self.lang:
                 # Use the guessed lexer's language instead
-                self.lang = lexer.aliases[0]
+                self.lang = lexer.aliases[0]  # type: ignore[attr-defined]
             lang_str = f'{self.lang_prefix}{self.lang}'
             if isinstance(self.pygments_formatter, str):
                 try:
@@ -254,6 +255,7 @@ class HiliteTreeprocessor(Treeprocessor):
     """ Highlight source code in code blocks. """
 
     config: dict[str, Any]
+    md: Markdown
 
     def code_unescape(self, text: str) -> str:
         """Unescape code."""
@@ -270,8 +272,10 @@ def run(self, root: etree.Element) -> None:
         for block in blocks:
             if len(block) == 1 and block[0].tag == 'code':
                 local_config = self.config.copy()
+                text = block[0].text
+                assert text is not None
                 code = CodeHilite(
-                    self.code_unescape(block[0].text),
+                    self.code_unescape(text),
                     tab_length=self.md.tab_length,
                     style=local_config.pop('pygments_style', 'default'),
                     **local_config
@@ -288,7 +292,7 @@ def run(self, root: etree.Element) -> None:
 class CodeHiliteExtension(Extension):
     """ Add source code highlighting to markdown code blocks. """
 
-    def __init__(self, **kwargs):
+    def __init__(self, **kwargs) -> None:
         # define default configs
         self.config = {
             'linenums': [
@@ -331,7 +335,7 @@ def __init__(self, **kwargs):
                         pass  # Assume it's not a boolean value. Use as-is.
                 self.config[key] = [value, '']
 
-    def extendMarkdown(self, md):
+    def extendMarkdown(self, md: Markdown) -> None:
         """ Add `HilitePostprocessor` to Markdown instance. """
         hiliter = HiliteTreeprocessor(md)
         hiliter.config = self.getConfigs()