From 9b18a861f392b5368719887799da1c3459731b51 Mon Sep 17 00:00:00 2001 From: Jason Grace <110117391+JasonGrace2282@users.noreply.github.com> Date: Sun, 24 Dec 2023 12:33:45 -0500 Subject: [PATCH] Finish TODO's in ``contributing/typings.rst`` (#3545) * Updated typing docs * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Added link for protocols * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Added object vs Any * Fix Typo * Rephrase TypeVar Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> * Compare between tuple vs list Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> * typing -> collections.abc Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> * typing -> collections.abc Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> * change method to attr Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> * clarify object typehint Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> * Fix code typo Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> * Added if TYPE_CHECKING section * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Fix reST for inline code * Elaborate on if TYPE_CHECKING Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> * functions -> collections Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> Co-authored-by: Viicos <65306057+Viicos@users.noreply.github.com> --- docs/source/contributing/typings.rst | 52 +++++++++++++++++++++++++--- 1 file changed, 48 insertions(+), 4 deletions(-) diff --git a/docs/source/contributing/typings.rst b/docs/source/contributing/typings.rst index 9880bfb3b7..748cff1e02 100644 --- a/docs/source/contributing/typings.rst +++ b/docs/source/contributing/typings.rst @@ -40,6 +40,9 @@ Typing guidelines pending shape support, using the correct type aliases will help users understand which shape should be used. +* For typings of generic collections, check out `this `_ + link. + * Always use a type hint of ``None`` for functions that does not return a value (this also applies to ``__init__``), e.g.: @@ -57,6 +60,8 @@ Typing guidelines * Following `PEP 484 `_, use ``float`` instead of ``int | float``. +* Use ``x | y`` instead of ``Union[x, y]`` + * Mobjects have the typehint ``Mobject``, e.g.: .. code:: py @@ -66,16 +71,55 @@ Typing guidelines return self.set_color(mobject.get_color()) * Always parametrize generics (``list[int]`` instead of ``list``, - ``type[Any]`` instead of ``type``, etc.). This also applies to callables: + ``type[Any]`` instead of ``type``, etc.). This also applies to callables. .. code:: py rate_func: Callable[[float], float] = lambda t: smooth(1 - t) +* Use ``TypeVar`` when you want to "link" type hints as being the same type. + Consider ``Mobject.copy``, which returns a new instance of the same class. + It would be type-hinted as: + +.. code:: py + + T = TypeVar("T") + + + def copy(self: T) -> T: + ... + +* Use ``typing.Iterable`` whenever the function works with *any* iterable, not a specific type. + +* If the function returns a container of a specific length each time, consider using ``tuple`` instead of ``list``. + +.. code:: py + + def foo() -> tuple[float, float, float]: + return (0, 0, 0) + +* If a function works with a parameter as long as said parameter has a ``__getitem__``, ``__iter___`` and ``__len__`` method, + the typehint of the parameter should be ``collections.abc.Mapping``. If it also supports ``__setitem__`` and/or ``__delitem__``, it + should be marked as ``collections.abc.MutableMapping``. + +* Typehinting something as ``object`` means that only attributes available on every Python object should be accessed, + like ``__str__`` and so on. On the other hand, literally any attribute can be accessed on a variable with the ``Any`` typehint - + it's more freeing than the ``object`` typehint, and makes mypy stop typechecking the variable. Note that whenever possible, + try to keep typehints as specific as possible. + +* If objects are imported purely for type hint purposes, keep it under an ``if typing.TYPE_CHECKING`` guard, to prevent them from + being imported at runtime (helps library performance). Do not forget to use the ``from __future__ import annotations`` import to avoid having runtime ``NameError`` exceptions. + +.. code:: py + + from typing import TYPE_CHECKING + + if TYPE_CHECKING: + from manim.typing import Vector3 + # type stuff with Vector3 + Missing Sections for typehints are: ----------------------------------- * Mypy and numpy import errors: https://realpython.com/python-type-checking/#running-mypy -* When to use ``object`` vs ``Any`` -* The use of a TypeVar on the type hints for ``copy()``. -* The definition and use of Protocols (like ``Sized``, ``Sequence``, ``Iterable``...) +* Explain ``mypy.ini`` (see above link)