type: add types.py with type aliases for md2zhihu

Define common type aliases to be used across the codebase for
consistent type annotations.

Changes:
- Add `ASTNode` and `ASTNodes` type aliases for AST nodes
- Add `RefDict` type alias for reference dictionaries
- Add `FeatureHandler` and `Features` type aliases for renderer features
- Add `typing_extensions` dependency for Python 3.9 compatibility

Author: drmingdrmer

md2zhihu/types.py

@@ -0,0 +1,26 @@
+"""Type definitions for md2zhihu"""
+
+from __future__ import annotations
+
+from typing import Any
+from typing import Callable
+from typing import Dict
+from typing import List
+from typing import Optional
+from typing import Union
+
+from typing_extensions import TypeAlias
+
+# AST node types
+ASTNode: TypeAlias = Dict[str, Any]
+ASTNodes: TypeAlias = List[ASTNode]
+
+# Reference dictionary: {ref_id: url}
+RefDict: TypeAlias = Dict[str, str]
+
+# Feature handler type for MDRender
+# Returns list of rendered lines, or None if not handled
+FeatureHandler: TypeAlias = Callable[..., Optional[List[str]]]
+
+# Features dictionary: {node_type: handler} or {node_type: {subtype: handler}}
+Features: TypeAlias = Dict[str, Union[FeatureHandler, Dict[str, FeatureHandler]]]

pyproject.toml

@@ -31,6 +31,7 @@ dependencies = [
     "k3fs>=0.1.5,<0.2",
     "k3git>=0.1.18,<0.2",
     "k3handy>=0.1.12,<0.2",
+    "typing_extensions>=4.0,<5",
     "urllib3>=1.26.7,<3",
 ]