Add mypy checking

[jbms]

No description provided.

[2bndy5]

I've been trying to fix the typing in json_domain.py (pyright and I are having problems understanding it)... I see you've made some significant changes to that file here - some of which doesn't seem related to typing. For now, I'll just use type: ignore on that file. Later, we can patch in the changes from here.

[jbms]

I removed object_pairs_hook parameter because it wasn't needed. The other refactoring was related to mypy --- mypy does not support the same variable name being assigned different types, e.g. in one block it being used with one type, then later the same name being used independently with a different type. Therefore I split up one of the functions into a number of smaller functions.

[2bndy5]

oh I see; I just type ignored that param because I'm not sure how to tell pyright that it is a class (not an instance of a class).

I did some type aliasing to cpp_domain_fixes.py and found that pyright doesn't like using a module's namespace (sphinx.domains.c/sphinx.domains.cpp) as an arg to a function. I haven't checked with the PEPs that pyright adheres to though.

[jbms]

oh I see; I just type ignored that param because I'm not sure how to tell pyright that it is a class (not an instance of a class).

I'm not sure which parameter you're referring to, but typing.Type[X] is how you specify a parameter that is a type itself that inherits from X, rather than an instance of X.

[2bndy5]

sphinx-immaterial/sphinx_immaterial/cpp_domain_fixes.py

Line 715 in bd1e359

domain_module,

I've been going through and adding types to all function params. I have pyright to emit this violation as a warning so builds still pass, but it helps me understand the focus of a function without having to backtrack what was passed to it (in trying to understand what the function is doing with the param).

[jbms]

sphinx-immaterial/sphinx_immaterial/cpp_domain_fixes.py

Line 715 in bd1e359

domain_module,

I've been going through and adding types to all function params. I have pyright to emit this violation as a warning so builds still pass, but it helps me understand the focus of a function without having to backtrack what was passed to it (in trying to understand what the function is doing with the param).

I think the correct type for that would be: typing_extensions.Literal[sphinx.domains.c, sphinx.domains.cpp]

Not clear if it will handle that, though.

[jbms]

Nevermind, I see that that Literal is only supposed to contain a limited set of possible values:
https://peps.python.org/pep-0586/#illegal-parameters-for-literal-at-type-check-time

Maybe types.ModuleType (which I don't think can be used like ModuleType[sphinx.domains.c]) is the best we can do.

[2bndy5]

tried that. pyright says that

Type arguments for "Literal" must be None, a literal value (int, bool, str, or bytes), or an enum value

also tried Union[sphinx.domains.c, sphinx.domains.cpp] which lead to

Module cannot be used as a type

In fact, the CI log errored out when I combined Union[sphinx.domains.c, sphinx.domains.cpp], # type: ignore; something about the incorrect args given to Union...

There really isn't many type: ignore comments added, so I'm ok with just using

sphinx-immaterial/sphinx_immaterial/cpp_domain_fixes.py

Line 731 in 55d187c

domain_module, # type: ignore Union[sphinx.domains.c, sphinx.domains.cpp]

because the parameter is well named enough

[2bndy5]

Hey! types.ModuleType worked. Pyright is ok with using

    domain_module: ModuleType,  # Union[sphinx.domains.c, sphinx.domains.cpp]

I put the Union of the specific modules for precision.

[2bndy5]

I made some changes:

1. use custom stubs for pymdownx.keymap_db and sphinxcontrib.details.directive modules (they now exist in typings_py folder
   • turns out typeshed has stubs for jsonschema pkg 👍🏼
2. add mypy config to pyproject.toml (use pretty/verbose error ouput and point to custom stubs)
3. removed some type: ignore comments by using getattr() and setattr()

[jbms]

Thanks!

This looks good to me.

[2bndy5]

ready to merge when you are