Add OptionsType and PresetType

Author: chrisjsewell

markdown_it/main.py

@@ -12,15 +12,15 @@
 from .renderer import RendererHTML, RendererProtocol
 from .rules_core.state_core import StateCore
 from .token import Token
-from .utils import EnvType, OptionsDict
+from .utils import EnvType, OptionsDict, OptionsType, PresetType
 
 try:
     import linkify_it
 except ModuleNotFoundError:
     linkify_it = None
 
 
-_PRESETS = {
+_PRESETS: dict[str, PresetType] = {
     "default": presets.default.make(),
     "js-default": presets.js_default.make(),
     "zero": presets.zero.make(),
@@ -32,8 +32,8 @@
 class MarkdownIt:
     def __init__(
         self,
-        config: str | Mapping = "commonmark",
-        options_update: Mapping | None = None,
+        config: str | PresetType = "commonmark",
+        options_update: Mapping[str, Any] | None = None,
         *,
         renderer_cls: Callable[[MarkdownIt], RendererProtocol] = RendererHTML,
     ):
@@ -75,7 +75,7 @@ def __getitem__(self, name: str) -> Any:
             "renderer": self.renderer,
         }[name]
 
-    def set(self, options: MutableMapping) -> None:
+    def set(self, options: OptionsType) -> None:
         """Set parser options (in the same format as in constructor).
         Probably, you will never need it, but you can change options after constructor call.
 
@@ -86,7 +86,7 @@ def set(self, options: MutableMapping) -> None:
         self.options = OptionsDict(options)
 
     def configure(
-        self, presets: str | Mapping, options_update: Mapping | None = None
+        self, presets: str | PresetType, options_update: Mapping[str, Any] | None = None
     ) -> MarkdownIt:
         """Batch load of all options and component settings.
         This is an internal method, and you probably will not need it.
@@ -108,9 +108,9 @@ def configure(
 
         options = config.get("options", {}) or {}
         if options_update:
-            options = {**options, **options_update}
+            options = {**options, **options_update}  # type: ignore
 
-        self.set(options)
+        self.set(options)  # type: ignore
 
         if "components" in config:
             for name, component in config["components"].items():
@@ -206,15 +206,19 @@ def reset_rules(self) -> Generator[None, None, None]:
                 self[chain].ruler.enableOnly(rules)
         self.inline.ruler2.enableOnly(chain_rules["inline2"])
 
-    def add_render_rule(self, name: str, function: Callable, fmt: str = "html") -> None:
+    def add_render_rule(
+        self, name: str, function: Callable[..., Any], fmt: str = "html"
+    ) -> None:
         """Add a rule for rendering a particular Token type.
 
         Only applied when ``renderer.__output__ == fmt``
         """
         if self.renderer.__output__ == fmt:
             self.renderer.rules[name] = function.__get__(self.renderer)  # type: ignore
 
-    def use(self, plugin: Callable, *params, **options) -> MarkdownIt:
+    def use(
+        self, plugin: Callable[..., None], *params: Any, **options: Any
+    ) -> MarkdownIt:
         """Load specified plugin with given params into current parser instance. (chainable)
 
         It's just a sugar to call `plugin(md, params)` with curring.

markdown_it/presets/__init__.py

@@ -1,6 +1,7 @@
 __all__ = ("commonmark", "default", "zero", "js_default", "gfm_like")
 
 from . import commonmark, default, zero
+from ..utils import PresetType
 
 js_default = default
 
@@ -16,7 +17,7 @@ class gfm_like:
     """
 
     @staticmethod
-    def make():
+    def make() -> PresetType:
         config = commonmark.make()
         config["components"]["core"]["rules"].append("linkify")
         config["components"]["block"]["rules"].append("table")

markdown_it/presets/commonmark.py

@@ -6,9 +6,10 @@
 - block: table
 - inline: strikethrough
 """
+from ..utils import PresetType
 
 
-def make():
+def make() -> PresetType:
     return {
         "options": {
             "maxNesting": 20,  # Internal protection, recursion limit

markdown_it/presets/default.py

@@ -1,7 +1,8 @@
 """markdown-it default options."""
+from ..utils import PresetType
 
 
-def make():
+def make() -> PresetType:
     return {
         "options": {
             "maxNesting": 100,  # Internal protection, recursion limit

markdown_it/presets/zero.py

@@ -2,9 +2,10 @@
 "Zero" preset, with nothing enabled. Useful for manual configuring of simple
 modes. For example, to parse bold/italic only.
 """
+from ..utils import PresetType
 
 
-def make():
+def make() -> PresetType:
     return {
         "options": {
             "maxNesting": 20,  # Internal protection, recursion limit

markdown_it/utils.py

@@ -1,101 +1,160 @@
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import MutableMapping as MutableMappingABC
 from pathlib import Path
-from typing import Any, MutableMapping
+from typing import Any, Callable, Iterable, MutableMapping, TypedDict
 
-EnvType = MutableMapping[str, Any]
+EnvType = MutableMapping[str, Any]  # note: could use TypeAlias in python 3.10
 """Type for the environment sandbox used in parsing and rendering,
 which stores mutable variables for use by plugins and rules.
 """
 
 
-class OptionsDict(dict):
+class OptionsType(TypedDict):
+    """Options for parsing."""
+
+    maxNesting: int
+    """Internal protection, recursion limit."""
+    html: bool
+    """Enable HTML tags in source."""
+    linkify: bool
+    """Enable autoconversion of URL-like texts to links."""
+    typographer: bool
+    """Enable smartquotes and replacements."""
+    quotes: str
+    """Quote characters."""
+    xhtmlOut: bool
+    """Use '/' to close single tags (<br />)."""
+    breaks: bool
+    """Convert newlines in paragraphs into <br>."""
+    langPrefix: str
+    """CSS language prefix for fenced blocks."""
+    highlight: Callable[[str, str, str], str] | None
+    """Highlighter function: (content, lang, attrs) -> str."""
+
+
+class PresetType(TypedDict):
+    """Preset configuration for markdown-it."""
+
+    options: OptionsType
+    """Options for parsing."""
+    components: MutableMapping[str, MutableMapping[str, list[str]]]
+    """Components for parsing and rendering."""
+
+
+class OptionsDict(MutableMappingABC):  # type: ignore
     """A dictionary, with attribute access to core markdownit configuration options."""
 
+    # Note: ideally we would probably just remove attribute access entirely,
+    # but we keep it for backwards compatibility.
+
+    def __init__(self, options: OptionsType) -> None:
+        self._options = options
+
+    def __getitem__(self, key: str) -> Any:
+        return self._options[key]  # type: ignore[literal-required]
+
+    def __setitem__(self, key: str, value: Any) -> None:
+        self._options[key] = value  # type: ignore[literal-required]
+
+    def __delitem__(self, key: str) -> None:
+        del self._options[key]  # type: ignore
+
+    def __iter__(self) -> Iterable[str]:  # type: ignore
+        return iter(self._options)
+
+    def __len__(self) -> int:
+        return len(self._options)
+
+    def __repr__(self) -> str:
+        return repr(self._options)
+
+    def __str__(self) -> str:
+        return str(self._options)
+
     @property
     def maxNesting(self) -> int:
         """Internal protection, recursion limit."""
-        return self["maxNesting"]
+        return self._options["maxNesting"]
 
     @maxNesting.setter
-    def maxNesting(self, value: int):
-        self["maxNesting"] = value
+    def maxNesting(self, value: int) -> None:
+        self._options["maxNesting"] = value
 
     @property
     def html(self) -> bool:
         """Enable HTML tags in source."""
-        return self["html"]
+        return self._options["html"]
 
     @html.setter
-    def html(self, value: bool):
-        self["html"] = value
+    def html(self, value: bool) -> None:
+        self._options["html"] = value
 
     @property
     def linkify(self) -> bool:
         """Enable autoconversion of URL-like texts to links."""
-        return self["linkify"]
+        return self._options["linkify"]
 
     @linkify.setter
-    def linkify(self, value: bool):
-        self["linkify"] = value
+    def linkify(self, value: bool) -> None:
+        self._options["linkify"] = value
 
     @property
     def typographer(self) -> bool:
         """Enable smartquotes and replacements."""
-        return self["typographer"]
+        return self._options["typographer"]
 
     @typographer.setter
-    def typographer(self, value: bool):
-        self["typographer"] = value
+    def typographer(self, value: bool) -> None:
+        self._options["typographer"] = value
 
     @property
     def quotes(self) -> str:
         """Quote characters."""
-        return self["quotes"]
+        return self._options["quotes"]
 
     @quotes.setter
-    def quotes(self, value: str):
-        self["quotes"] = value
+    def quotes(self, value: str) -> None:
+        self._options["quotes"] = value
 
     @property
     def xhtmlOut(self) -> bool:
         """Use '/' to close single tags (<br />)."""
-        return self["xhtmlOut"]
+        return self._options["xhtmlOut"]
 
     @xhtmlOut.setter
-    def xhtmlOut(self, value: bool):
-        self["xhtmlOut"] = value
+    def xhtmlOut(self, value: bool) -> None:
+        self._options["xhtmlOut"] = value
 
     @property
     def breaks(self) -> bool:
         """Convert newlines in paragraphs into <br>."""
-        return self["breaks"]
+        return self._options["breaks"]
 
     @breaks.setter
-    def breaks(self, value: bool):
-        self["breaks"] = value
+    def breaks(self, value: bool) -> None:
+        self._options["breaks"] = value
 
     @property
     def langPrefix(self) -> str:
         """CSS language prefix for fenced blocks."""
-        return self["langPrefix"]
+        return self._options["langPrefix"]
 
     @langPrefix.setter
-    def langPrefix(self, value: str):
-        self["langPrefix"] = value
+    def langPrefix(self, value: str) -> None:
+        self._options["langPrefix"] = value
 
     @property
     def highlight(self) -> Callable[[str, str, str], str] | None:
         """Highlighter function: (content, langName, langAttrs) -> escaped HTML."""
-        return self["highlight"]
+        return self._options["highlight"]
 
     @highlight.setter
-    def highlight(self, value: Callable[[str, str, str], str] | None):
-        self["highlight"] = value
+    def highlight(self, value: Callable[[str, str, str], str] | None) -> None:
+        self._options["highlight"] = value
 
 
-def read_fixture_file(path: str | Path) -> list[list]:
+def read_fixture_file(path: str | Path) -> list[list[Any]]:
     text = Path(path).read_text(encoding="utf-8")
     tests = []
     section = 0