Add docs page

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

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:

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
 ------

docs/providers/index.rst

@@ -49,3 +49,4 @@ Providers module API docs - :py:mod:`dependency_injector.providers`
     overriding
     provided_instance
     custom
+    typing_mypy

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"