diff --git a/docs/index.rst b/docs/index.rst index fe21c47b..2c72e9bc 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -78,7 +78,7 @@ Key features of the ``Dependency Injector``: and dictionaries. See :ref:`configuration-provider`. - **Containers**. Provides declarative and dynamic containers. See :ref:`containers`. - **Performance**. Fast. Written in ``Cython``. -- **Typing**. Provides typing stubs, ``mypy``-friendly. +- **Typing**. Provides typing stubs, ``mypy``-friendly. See :ref:`provider-typing`. - **Maturity**. Mature and production-ready. Well-tested, documented and supported. .. code-block:: python diff --git a/docs/introduction/key_features.rst b/docs/introduction/key_features.rst index f344d881..f81e62ca 100644 --- a/docs/introduction/key_features.rst +++ b/docs/introduction/key_features.rst @@ -20,7 +20,7 @@ Key features of the ``Dependency Injector``: and dictionaries. See :ref:`configuration-provider`. - **Containers**. Provides declarative and dynamic containers. See :ref:`containers`. - **Performance**. Fast. Written in ``Cython``. -- **Typing**. Provides typing stubs, ``mypy``-friendly. +- **Typing**. Provides typing stubs, ``mypy``-friendly. See :ref:`provider-typing`. - **Maturity**. Mature and production-ready. Well-tested, documented and supported. The framework stands on two principles: diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index a114154a..0c83786f 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -11,6 +11,7 @@ Develop ------- - Add native support of the generics to the providers: ``some_provider = providers.Provider[SomeClass]``. - Deprecate module ``types``. +- Add documentation page on providers typing and ``mypy`` support. 3.43.1 ------ diff --git a/docs/providers/index.rst b/docs/providers/index.rst index 91ffc9fd..8d14c670 100644 --- a/docs/providers/index.rst +++ b/docs/providers/index.rst @@ -49,3 +49,4 @@ Providers module API docs - :py:mod:`dependency_injector.providers` overriding provided_instance custom + typing_mypy diff --git a/docs/providers/typing_mypy.rst b/docs/providers/typing_mypy.rst new file mode 100644 index 00000000..f108a77a --- /dev/null +++ b/docs/providers/typing_mypy.rst @@ -0,0 +1,58 @@ +.. _provider-typing: + +Typing and mypy +=============== + +.. meta:: + :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Providers,Typing,Mypy, + Pattern,Example + :description: Dependency Injector providers are mypy-friendly. Providers module goes with the + typing stubs to provide the typing information to ``mypy``, IDEs and editors. + +Providers are ``mypy``-friendly. + +Providers module goes with the typing stubs. It provides typing information to ``mypy`` and your +IDE. + +.. code-block:: python + + from dependency_injector import providers + + + class Animal: + ... + + + class Cat(Animal) + ... + + + provider = providers.Factory(Cat) + + + if __name__ == '__main__': + animal = provider() # mypy knows that animal is of type "Cat" + + +You can use ``Provider`` as a generic type. This helps when a provider is an argument of a +function or method. + +.. code-block:: python + :emphasize-lines: 12 + + from dependency_injector import providers + + + class Animal: + ... + + + class Cat(Animal) + ... + + + provider: providers.Provider[Animal] = providers.Factory(Cat) + + + if __name__ == '__main__': + animal = provider() # mypy knows that animal is of type "Animal"