Document running type checkers (#614)

* pyproject: Configure mypy and pyright

Signed-off-by: Philipp Hahn <[email protected]>

* hacking-guide: Document type checkers

Signed-off-by: Philipp Hahn <[email protected]>

---------

Signed-off-by: Philipp Hahn <[email protected]>

Author: pmhahn

.gitignore

@@ -10,7 +10,5 @@ MANIFEST
 *.egg-info
 .vscode
 temp
-
-
-
-
+mypy.junit.xml
+mypy/

MANIFEST.in

@@ -4,6 +4,7 @@ recursive-include examples *.py *.elf *.out
 recursive-include test *
 global-exclude *.py[cod]
 global-exclude __pycache__
+global-exclude .mypy_cache
 include README.rst
 include LICENSE
 include CHANGES

doc/hacking-guide.rst

@@ -65,4 +65,26 @@ Coding conventions
 **pyelftools** is written in Python, following the `PEP 8 <http://www.python.org/dev/peps/pep-0008/>`_ style guide.
 
 
+Type checking
+-------------
 
+**pyelftools** is using and providing Type Hints, following the `PEP 484 <https://peps.python.org/pep-0484/>`_.
+Please make sure new functions and methods are properly type hinted.
+There are some known limitations as **pyelftools** is dynamic for some types, which does not work well for _static typing_.
+
+Please make sure to run [pyright](https://github.com/microsoft/pyright) and/or [mypy](https://mypy.readthedocs.io/en/stable/) on your contributions.
+For this Python 3.12 (or newer) is required:
+
+.. sourcecode:: text
+
+  > uv sync --dev --group typing --python 3.12
+  > . .venv/bin/activate
+  > pyright
+  > mypy
+
+You can also install ``pyright`` or ``mypy`` globally and (re-)use them for multiple projects:
+
+1. either install them once with ``uv tool install -p 3.12 pyright`` respective ``uv tool install -p 3.12 mypy``. Afterwards you can directly invoke ``pyright`` or ``mypy``.
+2. or run them from a temporary VENV each time by using ``uv tool run -p 3.12 pyright`` respective ``uv tool run -p 3.12 mypy``.
+
+Compared to the recommendation above this has the drawback that (in the future) type hints for external dependencies might be missing.

pyproject.toml

@@ -42,6 +42,9 @@ Homepage = "https://github.com/eliben/pyelftools"
 Repository = "https://github.com/eliben/pyelftools.git"
 Issues = "https://github.com/eliben/pyelftools/issues"
 
+[dependency-groups]
+typing = ["mypy[reports]", "pyright", "typeguard"]
+
 [tool.setuptools]
 packages = [
     "elftools",
@@ -64,3 +67,20 @@ version = {attr = "elftools.__version__"}
 
 [tool.setuptools.package-data]
 elftools = ["py.types"]
+
+[tool.mypy]
+error_summary = false
+disallow_any_generics = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+# html_report = "mypy"
+packages = "elftools"
+# junit_xml = "mypy.junit.xml"
+junit_format = "per_file"
+
+[tool.pyright]
+include = [
+    "elftools",
+]