Improve the state of Python type hints in basilisp.lang.*

CHANGELOG.md

@@ -31,6 +31,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
  * Removed support for PyPy 3.8 (#785)
 
+### Other
+ * Improve the state of the Python type hints in `basilisp.lang.*` (#???)
+
+
 ## [v0.1.0b0]
 ### Added
  * Added rudimentary support for `clojure.stacktrace` with `print-cause-trace` (part of #721)

pyproject.toml

@@ -37,6 +37,7 @@ prompt-toolkit = "^3.0.0"
 pyrsistent = "^0.18.0"
 python-dateutil = "^2.8.1"
 readerwriterlock = "^1.0.8"
+typing_extensions = "^4.9.0"
 
 astor = { version = "^0.8.1", python = "<3.9", optional = true }
 pytest = { version = "^7.0.0", optional = true }
@@ -219,6 +220,7 @@ disable = [
 check_untyped_defs = true
 mypy_path = "src/"
 show_error_codes = true
+warn_redundant_casts = true
 warn_unused_configs = true
 warn_unused_ignores = true
 

src/basilisp/cli.py

@@ -237,8 +237,13 @@ def _subcommand(
     help: Optional[str] = None,  # pylint: disable=redefined-builtin
     description: Optional[str] = None,
     handler: Handler,
-):
-    def _wrap_add_subcommand(f: Callable[[argparse.ArgumentParser], None]):
+) -> Callable[
+    [Callable[[argparse.ArgumentParser], None]],
+    Callable[["argparse._SubParsersAction"], None],
+]:
+    def _wrap_add_subcommand(
+        f: Callable[[argparse.ArgumentParser], None]
+    ) -> Callable[["argparse._SubParsersAction"], None]:
         def _wrapped_subcommand(subparsers: "argparse._SubParsersAction"):
             parser = subparsers.add_parser(
                 subcommand, help=help, description=description
@@ -279,14 +284,14 @@ def bootstrap_basilisp_installation(_, args: argparse.Namespace) -> None:
     description=textwrap.dedent(
         """Bootstrap the Python installation to allow importing Basilisp namespaces"
         without requiring an additional bootstrapping step.
-        
+
         Python installations are bootstrapped by installing a `basilispbootstrap.pth`
         file in your `site-packages` directory. Python installations execute `*.pth`
         files found at startup.
-        
+
         Bootstrapping your Python installation in this way can help avoid needing to
         perform manual bootstrapping from Python code within your application.
-        
+
         On the first startup, Basilisp will compile `basilisp.core` to byte code
         which could take up to 30 seconds in some cases depending on your system and
         which version of Python you are using. Subsequent startups should be
@@ -319,7 +324,7 @@ def _add_bootstrap_subcommand(parser: argparse.ArgumentParser) -> None:
 def nrepl_server(
     _,
     args: argparse.Namespace,
-):
+) -> None:
     opts = compiler.compiler_opts()
     basilisp.init(opts)
 
@@ -369,7 +374,7 @@ def _add_nrepl_server_subcommand(parser: argparse.ArgumentParser) -> None:
 def repl(
     _,
     args: argparse.Namespace,
-):
+) -> None:
     opts = compiler.compiler_opts(
         warn_on_shadowed_name=args.warn_on_shadowed_name,
         warn_on_shadowed_var=args.warn_on_shadowed_var,
@@ -465,7 +470,7 @@ def _add_repl_subcommand(parser: argparse.ArgumentParser) -> None:
 def run(
     parser: argparse.ArgumentParser,
     args: argparse.Namespace,
-):
+) -> None:
     target = args.file_or_ns_or_code
     if args.load_namespace:
         if args.in_ns is not None:
@@ -523,18 +528,18 @@ def run(
     help="run a Basilisp script or code or namespace",
     description=textwrap.dedent(
         """Run a Basilisp script or a line of code or load a Basilisp namespace.
-        
+
         If `-c` is provided, execute the line of code as given. If `-n` is given,
         interpret `file_or_ns_or_code` as a fully qualified Basilisp namespace
         relative to `sys.path`. Otherwise, execute the file as a script relative to
         the current working directory.
-        
+
         `*main-ns*` will be set to the value provided for `-n`. In all other cases,
         it will be `nil`."""
     ),
     handler=run,
 )
-def _add_run_subcommand(parser: argparse.ArgumentParser):
+def _add_run_subcommand(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "file_or_ns_or_code",
         help=(
@@ -570,7 +575,9 @@ def _add_run_subcommand(parser: argparse.ArgumentParser):
     _add_debug_arg_group(parser)
 
 
-def test(parser: argparse.ArgumentParser, args: argparse.Namespace):  # pragma: no cover
+def test(
+    parser: argparse.ArgumentParser, args: argparse.Namespace
+) -> None:  # pragma: no cover
     try:
         import pytest
     except (ImportError, ModuleNotFoundError):
@@ -591,7 +598,7 @@ def _add_test_subcommand(parser: argparse.ArgumentParser) -> None:
     parser.add_argument("args", nargs=-1)
 
 
-def version(_, __):
+def version(_, __) -> None:
     v = importlib.metadata.version("basilisp")
     print(f"Basilisp {v}")
 

src/basilisp/importer.py

@@ -8,7 +8,16 @@
 from functools import lru_cache
 from importlib.abc import MetaPathFinder, SourceLoader
 from importlib.machinery import ModuleSpec
-from typing import Iterable, List, Mapping, MutableMapping, Optional, Sequence, cast
+from typing import (
+    Any,
+    Iterable,
+    List,
+    Mapping,
+    MutableMapping,
+    Optional,
+    Sequence,
+    cast,
+)
 
 from basilisp.lang import compiler as compiler
 from basilisp.lang import reader as reader
@@ -191,22 +200,22 @@ def find_spec(
                     return ModuleSpec(fullname, None, is_package=True)
         return None
 
-    def invalidate_caches(self):
+    def invalidate_caches(self) -> None:
         super().invalidate_caches()
         self._cache = {}
 
-    def _cache_bytecode(self, source_path, cache_path, data):
+    def _cache_bytecode(self, source_path: str, cache_path: str, data: bytes) -> None:
         self.set_data(cache_path, data)
 
-    def path_stats(self, path):
+    def path_stats(self, path: str) -> Mapping[str, Any]:
         stat = os.stat(path)
         return {"mtime": int(stat.st_mtime), "size": stat.st_size}
 
-    def get_data(self, path):
+    def get_data(self, path: str) -> bytes:
         with open(path, mode="r+b") as f:
             return f.read()
 
-    def set_data(self, path, data):
+    def set_data(self, path: str, data: bytes) -> None:
         os.makedirs(os.path.dirname(path), exist_ok=True)
         with open(path, mode="w+b") as f:
             f.write(data)
@@ -279,7 +288,7 @@ def get_code(self, fullname: str) -> Optional[types.CodeType]:
                 assert len(code) == 1
                 return code[0]
 
-    def create_module(self, spec: ModuleSpec):
+    def create_module(self, spec: ModuleSpec) -> BasilispModule:
         logger.debug(f"Creating Basilisp module '{spec.name}'")
         mod = BasilispModule(spec.name)
         mod.__file__ = spec.loader_state["filename"]
@@ -400,7 +409,7 @@ def exec_module(self, module: types.ModuleType) -> None:
                 self._exec_module(fullname, spec.loader_state, path_stats, ns)
 
 
-def hook_imports():
+def hook_imports() -> None:
     """Hook into Python's import machinery with a custom Basilisp code
     importer.
 

src/basilisp/lang/atom.py

@@ -1,12 +1,14 @@
 from typing import Callable, Generic, Optional, TypeVar
 
 from readerwriterlock.rwlock import RWLockFair
+from typing_extensions import Concatenate, ParamSpec
 
 from basilisp.lang.interfaces import IPersistentMap, RefValidator
 from basilisp.lang.map import PersistentMap
 from basilisp.lang.reference import RefBase
 
 T = TypeVar("T")
+P = ParamSpec("P")
 
 
 class Atom(RefBase[T], Generic[T]):
@@ -58,7 +60,9 @@ def reset(self, v: T) -> T:
                 self._notify_watches(oldval, v)
                 return v
 
-    def swap(self, f: Callable[..., T], *args, **kwargs) -> T:
+    def swap(
+        self, f: Callable[Concatenate[T, P], T], *args: P.args, **kwargs: P.kwargs
+    ) -> T:
         """Atomically swap the state of the Atom to the return value of
         `f(old, *args, **kwargs)`, returning the new value."""
         while True:

src/basilisp/lang/compiler/analyzer.py

@@ -28,6 +28,7 @@
     Pattern,
     Set,
     Tuple,
+    TypeVar,
     Union,
     cast,
 )
@@ -175,13 +176,13 @@
 AnalyzerException = partial(CompilerException, phase=CompilerPhase.ANALYZING)
 
 
-@attr.s(auto_attribs=True, slots=True)
+@attr.define
 class RecurPoint:
     loop_id: str
     args: Collection[Binding] = ()
 
 
-@attr.s(auto_attribs=True, frozen=True, slots=True)
+@attr.frozen
 class SymbolTableEntry:
     binding: Binding
     used: bool = False
@@ -196,7 +197,7 @@ def context(self) -> LocalType:
         return self.binding.local
 
 
-@attr.s(auto_attribs=True, slots=True)
+@attr.define
 class SymbolTable:
     name: str
     _is_context_boundary: bool = False
@@ -647,7 +648,12 @@ def get_meta_prop(o: Union[IMeta, Var]) -> Any:
 _tag_meta = _meta_getter(SYM_TAG_META_KEY)
 
 
-def _loc(form: Union[LispForm, ISeq]) -> Optional[Tuple[int, int, int, int]]:
+T_form = TypeVar("T_form", bound=ReaderForm)
+T_node = TypeVar("T_node", bound=Node)
+LispAnalyzer = Callable[[T_form, AnalyzerContext], T_node]
+
+
+def _loc(form: T_form) -> Optional[Tuple[int, int, int, int]]:
     """Fetch the location of the form in the original filename from the
     input form, if it has metadata."""
     # Technically, IMeta is sufficient for fetching `form.meta` but the
@@ -669,17 +675,17 @@ def _loc(form: Union[LispForm, ISeq]) -> Optional[Tuple[int, int, int, int]]:
     return None
 
 
-def _with_loc(f):
+def _with_loc(f: LispAnalyzer[T_form, T_node]) -> LispAnalyzer[T_form, T_node]:
     """Attach any available location information from the input form to
     the node environment returned from the parsing function."""
 
     @wraps(f)
-    def _analyze_form(form: Union[LispForm, ISeq], ctx: AnalyzerContext) -> Node:
+    def _analyze_form(form: T_form, ctx: AnalyzerContext) -> T_node:
         form_loc = _loc(form)
         if form_loc is None:
             return f(form, ctx)
         else:
-            return f(form, ctx).fix_missing_locations(form_loc)
+            return cast(T_node, f(form, ctx).fix_missing_locations(form_loc))
 
     return _analyze_form
 
@@ -795,24 +801,15 @@ def _tag_ast(form: Optional[LispForm], ctx: AnalyzerContext) -> Optional[Node]:
     return _analyze_form(form, ctx)
 
 
-def _with_meta(gen_node):
+def _with_meta(gen_node: LispAnalyzer[T_form, T_node]) -> LispAnalyzer[T_form, T_node]:
     """Wraps the node generated by gen_node in a :with-meta AST node if the
     original form has meta.
 
     :with-meta AST nodes are used for non-quoted collection literals and for
     function expressions."""
 
     @wraps(gen_node)
-    def with_meta(
-        form: Union[
-            llist.PersistentList,
-            lmap.PersistentMap,
-            ISeq,
-            lset.PersistentSet,
-            vec.PersistentVector,
-        ],
-        ctx: AnalyzerContext,
-    ) -> Node:
+    def with_meta(form: T_form, ctx: AnalyzerContext) -> T_node:
         assert not ctx.is_quoted, "with-meta nodes are not used in quoted expressions"
 
         descriptor = gen_node(form, ctx)
@@ -825,11 +822,14 @@ def with_meta(
                 assert isinstance(meta_ast, MapNode) or (
                     isinstance(meta_ast, Const) and meta_ast.type == ConstType.MAP
                 )
-                return WithMeta(
-                    form=form,
-                    meta=meta_ast,
-                    expr=descriptor,
-                    env=ctx.get_node_env(pos=ctx.syntax_position),
+                return cast(
+                    T_node,
+                    WithMeta(
+                        form=cast(LispForm, form),
+                        meta=meta_ast,
+                        expr=descriptor,
+                        env=ctx.get_node_env(pos=ctx.syntax_position),
+                    ),
                 )
 
         return descriptor
@@ -3113,7 +3113,7 @@ def _yield_ast(form: ISeq, ctx: AnalyzerContext) -> Yield:
         return Yield.expressionless(form, ctx.get_node_env(pos=ctx.syntax_position))
 
 
-SpecialFormHandler = Callable[[ISeq, AnalyzerContext], SpecialFormNode]
+SpecialFormHandler = Callable[[T_form, AnalyzerContext], SpecialFormNode]
 _SPECIAL_FORM_HANDLERS: Mapping[sym.Symbol, SpecialFormHandler] = {
     SpecialForm.AWAIT: _await_ast,
     SpecialForm.DEF: _def_ast,

src/basilisp/lang/compiler/exception.py

@@ -30,7 +30,7 @@ class CompilerPhase(Enum):
     COMPILING_PYTHON = kw.keyword("compiling-python")
 
 
-@attr.s(auto_attribs=True, frozen=True, slots=True)
+@attr.frozen
 class _loc:
     line: Optional[int] = None
     col: Optional[int] = None
@@ -46,7 +46,7 @@ def __bool__(self):
         )
 
 
-@attr.s(auto_attribs=True, slots=True, str=False)
+@attr.define(str=False)
 class CompilerException(IExceptionInfo):
     msg: str
     phase: CompilerPhase

src/basilisp/lang/compiler/generator.py

@@ -135,14 +135,14 @@
 GeneratorException = partial(CompilerException, phase=CompilerPhase.CODE_GENERATION)
 
 
-@attr.s(auto_attribs=True, frozen=True, slots=True)
+@attr.frozen
 class SymbolTableEntry:
     context: LocalType
     munged: str
     symbol: sym.Symbol
 
 
-@attr.s(auto_attribs=True, slots=True)
+@attr.define
 class SymbolTable:
     name: str
     _is_context_boundary: bool = False
@@ -203,7 +203,7 @@ class RecurType(Enum):
     LOOP = kw.keyword("loop")
 
 
-@attr.s(auto_attribs=True, slots=True)
+@attr.define
 class RecurPoint:
     loop_id: str
     type: RecurType
@@ -313,7 +313,7 @@ def new_this(self, this: sym.Symbol):
         self._this.pop()
 
 
-@attr.s(auto_attribs=True, frozen=True, slots=True)
+@attr.frozen
 class GeneratedPyAST:
     node: ast.AST
     dependencies: Iterable[ast.AST] = ()