|
- """For neatly implementing static typing in packaging.
-
- `mypy` - the static type analysis tool we use - uses the `typing` module, which
- provides core functionality fundamental to mypy's functioning.
-
- Generally, `typing` would be imported at runtime and used in that fashion -
- it acts as a no-op at runtime and does not have any run-time overhead by
- design.
-
- As it turns out, `typing` is not vendorable - it uses separate sources for
- Python 2/Python 3. Thus, this codebase can not expect it to be present.
- To work around this, mypy allows the typing import to be behind a False-y
- optional to prevent it from running at runtime and type-comments can be used
- to remove the need for the types to be accessible directly during runtime.
-
- This module provides the False-y guard in a nicely named fashion so that a
- curious maintainer can reach here to read this.
-
- In packaging, all static-typing related imports should be guarded as follows:
-
- from packaging._typing import TYPE_CHECKING
-
- if TYPE_CHECKING:
- from typing import ...
-
- Ref: https://github.com/python/mypy/issues/3216
- """
-
- __all__ = ["TYPE_CHECKING", "cast"]
-
- # The TYPE_CHECKING constant defined by the typing module is False at runtime
- # but True while type checking.
- if False: # pragma: no cover
- from typing import TYPE_CHECKING
- else:
- TYPE_CHECKING = False
-
- # typing's cast syntax requires calling typing.cast at runtime, but we don't
- # want to import typing at runtime. Here, we inform the type checkers that
- # we're importing `typing.cast` as `cast` and re-implement typing.cast's
- # runtime behavior in a block that is ignored by type checkers.
- if TYPE_CHECKING: # pragma: no cover
- # not executed at runtime
- from typing import cast
- else:
- # executed at runtime
- def cast(type_, value): # noqa
- return value
|
