Merge pull request #375 from mr-c/type_hints

type hints: mypy 1.8.0 clean

.github/workflows/tests.yml

@@ -33,7 +33,12 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install pytest pytest-cov
+        pip install pytest pytest-cov mypy
+
+    - name: Check types with Python ${{ matrix.python }} on ${{ matrix.os }}
+      run: |
+        mypy --strict src
+        mypy src tests
 
     - name: Test with Python ${{ matrix.python }} on ${{ matrix.os }}
       run: pytest

src/mistune/__init__.py

@@ -8,16 +8,26 @@
     Documentation: https://mistune.lepture.com/
 """
 
-from .markdown import Markdown
-from .core import BlockState, InlineState, BaseRenderer
+from typing import Any, Callable, Dict, Iterable, List, Optional, Tuple, Union
+
+from typing_extensions import Literal
+
 from .block_parser import BlockParser
+from .core import BaseRenderer, BlockState, InlineState
 from .inline_parser import InlineParser
+from .markdown import Markdown
+from .plugins import Plugin, PluginRef, import_plugin
 from .renderers.html import HTMLRenderer
 from .util import escape, escape_url, safe_entity, unikey
-from .plugins import import_plugin
 
+RendererRef = Union[Literal["html", "ast"], BaseRenderer]
 
-def create_markdown(escape: bool=True, hard_wrap: bool=False, renderer='html', plugins=None) -> Markdown:
+def create_markdown(
+    escape: bool = True,
+    hard_wrap: bool = False,
+    renderer: Optional[RendererRef] = "html",
+    plugins: Optional[Iterable[PluginRef]] = None,
+) -> Markdown:
     """Create a Markdown instance based on the given condition.
 
     :param escape: Boolean. If using html renderer, escape html.
@@ -41,9 +51,10 @@ def create_markdown(escape: bool=True, hard_wrap: bool=False, renderer='html', p
         renderer = HTMLRenderer(escape=escape)
 
     inline = InlineParser(hard_wrap=hard_wrap)
+    real_plugins: Optional[Iterable[Plugin]] = None
     if plugins is not None:
-        plugins = [import_plugin(n) for n in plugins]
-    return Markdown(renderer=renderer, inline=inline, plugins=plugins)
+        real_plugins = [import_plugin(n) for n in plugins]
+    return Markdown(renderer=renderer, inline=inline, plugins=real_plugins)
 
 
 html: Markdown = create_markdown(
@@ -52,11 +63,18 @@ def create_markdown(escape: bool=True, hard_wrap: bool=False, renderer='html', p
 )
 
 
-__cached_parsers = {}
+__cached_parsers: Dict[
+    Tuple[bool, Optional[RendererRef], Optional[Iterable[Any]]], Markdown
+] = {}
 
 
-def markdown(text, escape=True, renderer='html', plugins=None) -> str:
-    if renderer == 'ast':
+def markdown(
+    text: str,
+    escape: bool = True,
+    renderer: Optional[RendererRef] = "html",
+    plugins: Optional[Iterable[Any]] = None,
+) -> Union[str, List[Dict[str, Any]]]:
+    if renderer == "ast":
         # explicit and more similar to 2.x's API
         renderer = None
     key = (escape, renderer, plugins)
@@ -77,5 +95,5 @@ def markdown(text, escape=True, renderer='html', plugins=None) -> str:
     'html', 'create_markdown', 'markdown',
 ]
 
-__version__ = '3.0.1'
-__homepage__ = 'https://mistune.lepture.com/'
+__version__: str = "3.0.1"
+__homepage__: str = "https://mistune.lepture.com/"

src/mistune/__main__.py

@@ -1,23 +1,27 @@
-import sys
 import argparse
-from .renderers.rst import RSTRenderer
+import sys
+from typing import TYPE_CHECKING, Optional
+
+from . import __version__ as version
+from . import create_markdown
 from .renderers.markdown import MarkdownRenderer
-from . import (
-    create_markdown,
-    __version__ as version
-)
+from .renderers.rst import RSTRenderer
+
+if TYPE_CHECKING:
+    from .core import BaseRenderer
+    from .markdown import Markdown
 
 
-def _md(args):
+def _md(args: argparse.Namespace) -> "Markdown":
     if args.plugin:
         plugins = args.plugin
     else:
         # default plugins
         plugins = ['strikethrough', 'footnotes', 'table', 'speedup']
 
-    if args.renderer == 'rst':
-        renderer = RSTRenderer()
-    elif args.renderer == 'markdown':
+    if args.renderer == "rst":
+        renderer: "BaseRenderer" = RSTRenderer()
+    elif args.renderer == "markdown":
         renderer = MarkdownRenderer()
     else:
         renderer = args.renderer
@@ -29,7 +33,7 @@ def _md(args):
     )
 
 
-def _output(text, args):
+def _output(text: str, args: argparse.Namespace) -> None:
     if args.output:
         with open(args.output, 'w') as f:
             f.write(text)
@@ -52,7 +56,7 @@ def _output(text, args):
 '''
 
 
-def cli():
+def cli() -> None:
     parser = argparse.ArgumentParser(
         prog='python -m mistune',
         description=CMD_HELP,
@@ -102,17 +106,19 @@ def cli():
     if message:
         md = _md(args)
         text = md(message)
+        assert isinstance(text, str)
         _output(text, args)
     elif args.file:
         md = _md(args)
         text = md.read(args.file)[0]
+        assert isinstance(text, str)
         _output(text, args)
     else:
         print('You MUST specify a message or file')
-        return sys.exit(1)
+        sys.exit(1)
 
 
-def read_stdin():
+def read_stdin() -> Optional[str]:
     is_stdin_pipe = not sys.stdin.isatty()
     if is_stdin_pipe:
         return sys.stdin.read()