Skip to content

Commit

Permalink
Add Type annotations developer guideline
Browse files Browse the repository at this point in the history
  • Loading branch information
Avasam committed Jul 1, 2024
1 parent 3accd5c commit 59de2cf
Showing 1 changed file with 32 additions and 0 deletions.
32 changes: 32 additions & 0 deletions docs/development/developer-guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -131,3 +131,35 @@ simple Python script ``tools/vendor.py``.
To refresh the dependencies, run the following command::

$ tox -e vendor

----------------
Type annotations
----------------

Most standards and best practices are enforced by
[Ruff](https://docs.astral.sh/ruff/rules/)'s ``ANN2``, ``FA``, ``PYI``, ``UP``
and ``YTT`` rules.

Explicit return types have to be added for typed public functions whose
parameters are *all* annotated. This is enforced by ``ANN2``, but it's worth noting
that this is due to mypy inferring ``Any`` even for simple return types. Mypy also
doesn't count functions with missing parameter annotations as "typed". (see
[python/mypy#4409](https://github.com/python/mypy/issues/4409),
[python/mypy#10149](https://github.com/python/mypy/issues/10149) and
[python/mypy#6646](https://github.com/python/mypy/issues/6646)).
Otherwise, return annotations can be omitted to reduce verbosity,
especially for complex return types.

Instead of typing an explicit return type annotation as
``Generator[..., None, None]``, we'll prefer using an ``Iterator`` as it is more
concise and conceptually easier to deal with. Returning a ``Generator`` with no
``yield`` type or ``send`` type can sometimes be considered as exposing
implementation details. See
[Y058](https://github.com/PyCQA/flake8-pyi/blob/main/ERRORCODES.md#Y058).

Avoid importing private type-checking-only symbols. These are often
[typeshed](https://github.com/python/typeshed) internal details and are not
guaranteed to be stable.
Importing from ``_typeshed`` or ``typing_extensions`` is fine, but if you find
yourself importing the same symbol in ``TYPE_CHECKING`` blocks a lot, consider
implementing an alias directly in ``setuptools``.

0 comments on commit 59de2cf

Please sign in to comment.