Add selector provider docs

docs/providers/index.rst

@@ -24,6 +24,7 @@ Providers package API docs - :py:mod:`dependency_injector.providers`
     object
     list
     configuration
+    selector
     dependency
     overriding
     custom

docs/providers/selector.rst

@@ -0,0 +1,31 @@
+Selector providers
+------------------
+
+.. currentmodule:: dependency_injector.providers
+
+:py:class:`Selector` provider selects provider based on the configuration value or other callable.
+
+.. literalinclude:: ../../examples/providers/selector.py
+   :language: python
+   :emphasize-lines: 6-10
+   :lines: 3-5,14-20
+   :linenos:
+
+:py:class:`Selector` provider has a callable called ``selector`` and a dictionary of providers.
+
+The ``selector`` callable is provided as a first positional argument. It can be
+:py:class:`Configuration` provider or any other callable. It has to return a string value.
+That value is used as a key for selecting the provider from the dictionary of providers.
+
+The providers are provided as keyword arguments. Argument name is used as a key for
+selecting the provider.
+
+Full example:
+
+.. literalinclude:: ../../examples/providers/selector.py
+   :language: python
+   :emphasize-lines: 14-18
+   :lines: 3-
+   :linenos:
+
+.. disqus::

examples/providers/selector.py

@@ -20,9 +20,9 @@ selector = providers.Selector(
 )
 
 config.override({'one_or_another': 'one'})
-some_instance_1 = selector()
-assert isinstance(some_instance_1, SomeClass)
+instance_1 = selector()
+assert isinstance(instance_1, SomeClass)
 
 config.override({'one_or_another': 'another'})
-some_instance_2 = selector()
-assert isinstance(some_instance_2, SomeOtherClass)
+instance_2 = selector()
+assert isinstance(instance_2, SomeOtherClass)

src/dependency_injector/providers.c

@@ -67223,7 +67223,7 @@ static PyTypeObject __pyx_type_19dependency_injector_9providers_Selector = {
   0, /*tp_setattro*/
   0, /*tp_as_buffer*/
   Py_TPFLAGS_DEFAULT|Py_TPFLAGS_HAVE_VERSION_TAG|Py_TPFLAGS_CHECKTYPES|Py_TPFLAGS_HAVE_NEWBUFFER|Py_TPFLAGS_BASETYPE|Py_TPFLAGS_HAVE_GC, /*tp_flags*/
-  "Selector provider selects provider based on the configuration value or other callable.\n\n    :py:class:`Selector` provider has a callable called ``selector`` and a dictionary of providers.\n\n    The ``selector`` callable is provided as a first positional argument. It can be\n    :py:class:`Configuration` provider or any other callable. It has to return a string value.\n    That value is used as a key for selecting the provider from the dictionary of providers.\n\n    The providers are provided as keyword arguments. Argument name is used as a key for\n    selecting the provider.\n\n    .. code-block:: python\n\n        config = Configuration()\n\n        selector = Selector(\n            config.one_or_another,\n            one=providers.Factory(SomeClass),\n            another=providers.Factory(SomeOtherClass),\n        )\n\n        config.override({'one_or_another': 'one'})\n        some_instance = selector()\n        assert isinstance(some_instance, SomeClass)\n\n        config.override({'one_or_another': 'another'})\n        some_instance = selector()\n        assert isinstance(some_instance, SomeOtherClass)\n    ", /*tp_doc*/
+  "Selector provider selects provider based on the configuration value or other callable.\n\n    :py:class:`Selector` provider has a callable called ``selector`` and a dictionary of providers.\n\n    The ``selector`` callable is provided as a first positional argument. It can be\n    :py:class:`Configuration` provider or any other callable. It has to return a string value.\n    That value is used as a key for selecting the provider from the dictionary of providers.\n\n    The providers are provided as keyword arguments. Argument name is used as a key for\n    selecting the provider.\n\n    .. code-block:: python\n\n        config = Configuration()\n\n        selector = Selector(\n            config.one_or_another,\n            one=providers.Factory(SomeClass),\n            another=providers.Factory(SomeOtherClass),\n        )\n\n        config.override({'one_or_another': 'one'})\n        instance_1 = selector()\n        assert isinstance(instance_1, SomeClass)\n\n        config.override({'one_or_another': 'another'})\n        instance_2 = selector()\n        assert isinstance(instance_2, SomeOtherClass)\n    ", /*tp_doc*/
   __pyx_tp_traverse_19dependency_injector_9providers_Selector, /*tp_traverse*/
   __pyx_tp_clear_19dependency_injector_9providers_Selector, /*tp_clear*/
   0, /*tp_richcompare*/

src/dependency_injector/providers.pyx

@@ -2290,12 +2290,12 @@ cdef class Selector(Provider):
         )
 
         config.override({'one_or_another': 'one'})
-        some_instance = selector()
-        assert isinstance(some_instance, SomeClass)
+        instance_1 = selector()
+        assert isinstance(instance_1, SomeClass)
 
         config.override({'one_or_another': 'another'})
-        some_instance = selector()
-        assert isinstance(some_instance, SomeOtherClass)
+        instance_2 = selector()
+        assert isinstance(instance_2, SomeOtherClass)
     """
 
     def __init__(self, selector, **providers):