mirror of
https://github.com/ets-labs/python-dependency-injector.git
synced 2025-06-16 11:33:13 +03:00
Update catalogs overriding docs
This commit is contained in:
parent
e55f6ed212
commit
556c842685
|
@ -220,7 +220,7 @@ class DynamicCatalog(object):
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def is_overridden(self):
|
def is_overridden(self):
|
||||||
"""Read-only property that is set to True if catalog is overridden.
|
"""Read-only property that is set to ``True`` if catalog is overridden.
|
||||||
|
|
||||||
:rtype: bool
|
:rtype: bool
|
||||||
"""
|
"""
|
||||||
|
@ -464,7 +464,7 @@ class DeclarativeCatalogMetaClass(type):
|
||||||
|
|
||||||
@property
|
@property
|
||||||
def is_overridden(cls):
|
def is_overridden(cls):
|
||||||
"""Read-only property that is set to True if catalog is overridden.
|
"""Read-only property that is set to ``True`` if catalog is overridden.
|
||||||
|
|
||||||
:rtype: bool
|
:rtype: bool
|
||||||
"""
|
"""
|
||||||
|
@ -585,7 +585,7 @@ class DeclarativeCatalog(object):
|
||||||
"""
|
"""
|
||||||
|
|
||||||
is_overridden = bool
|
is_overridden = bool
|
||||||
"""Read-only property that is set to True if catalog is overridden.
|
"""Read-only property that is set to ``True`` if catalog is overridden.
|
||||||
|
|
||||||
:type: bool
|
:type: bool
|
||||||
"""
|
"""
|
||||||
|
@ -798,7 +798,7 @@ AbstractCatalog = DeclarativeCatalog
|
||||||
|
|
||||||
|
|
||||||
def override(catalog):
|
def override(catalog):
|
||||||
"""Catalog overriding decorator.
|
""":py:class:`DeclarativeCatalog` overriding decorator.
|
||||||
|
|
||||||
:param catalog: Catalog that should be overridden by decorated catalog.
|
:param catalog: Catalog that should be overridden by decorated catalog.
|
||||||
:type catalog: :py:class:`dependency_injector.catalogs.DeclarativeCatalog`
|
:type catalog: :py:class:`dependency_injector.catalogs.DeclarativeCatalog`
|
||||||
|
|
|
@ -1,35 +1,49 @@
|
||||||
Overriding of catalogs
|
Overriding of catalogs
|
||||||
----------------------
|
----------------------
|
||||||
|
|
||||||
|
.. module:: dependency_injector.catalogs
|
||||||
|
|
||||||
Catalogs can be overridden by other catalogs. This, actually, means that
|
Catalogs can be overridden by other catalogs. This, actually, means that
|
||||||
all of the providers from overriding catalog will override providers with the
|
all of the providers from overriding catalog will override providers with the
|
||||||
same names in overridden catalog.
|
same names in overridden catalog.
|
||||||
|
|
||||||
There are two ways to override catalog by another catalog:
|
There are two ways to override :py:class:`DeclarativeCatalog` with another
|
||||||
|
catalog:
|
||||||
|
|
||||||
- Use ``di.DeclarativeCatalog.override(AnotherCatalog)`` method.
|
- Use :py:meth:`DeclarativeCatalog.override` method.
|
||||||
- Use ``@di.override(AnotherCatalog)`` class decorator.
|
- Use :py:func:`override` class decorator.
|
||||||
|
|
||||||
Example of overriding catalog using ``di.DeclarativeCatalog.override()``
|
Example of overriding catalog using :py:meth:`DeclarativeCatalog.override`
|
||||||
method:
|
method:
|
||||||
|
|
||||||
.. literalinclude:: ../../examples/catalogs/override.py
|
.. literalinclude:: ../../examples/catalogs/override_declarative.py
|
||||||
:language: python
|
:language: python
|
||||||
|
|
||||||
Example of overriding catalog using ``@di.override()`` decorator:
|
Example of overriding catalog using :py:func:`override` decorator:
|
||||||
|
|
||||||
.. literalinclude:: ../../examples/catalogs/override_decorator.py
|
.. literalinclude:: ../../examples/catalogs/override_declarative_decorator.py
|
||||||
:language: python
|
:language: python
|
||||||
|
|
||||||
Also there are several useful methods and properties that help to work with
|
Also there are several useful :py:class:`DeclarativeCatalog` methods and
|
||||||
catalog overridings:
|
properties that help to work with catalog overridings:
|
||||||
|
|
||||||
- ``di.DeclarativeCatalog.is_overridden`` - read-only, evaluated in runtime,
|
- :py:attr:`DeclarativeCatalog.is_overridden` - read-only property that is set
|
||||||
property that is set to True if catalog is overridden.
|
to ``True`` if catalog is overridden.
|
||||||
- ``di.DeclarativeCatalog.last_overriding`` - reference to the last overriding
|
- :py:attr:`DeclarativeCatalog.last_overriding` - read-only reference to
|
||||||
catalog, if any.
|
the last overriding catalog, if any.
|
||||||
- ``di.DeclarativeCatalog.overridden_by`` - tuple of all overriding catalogs.
|
- :py:attr:`DeclarativeCatalog.overridden_by` - tuple of all overriding
|
||||||
- ``di.DeclarativeCatalog.reset_last_overriding()`` - reset last overriding
|
catalogs.
|
||||||
catalog.
|
- :py:meth:`DeclarativeCatalog.reset_last_overriding()` - reset last
|
||||||
- ``di.DeclarativeCatalog.reset_override()`` - reset all overridings for all
|
overriding catalog.
|
||||||
catalog providers.
|
- :py:meth:`DeclarativeCatalog.reset_override()` - reset all overridings for
|
||||||
|
all catalog providers.
|
||||||
|
|
||||||
|
:py:class:`DynamicCatalog` has exactly the same functionality, except of
|
||||||
|
:py:func:`override` decorator. Also :py:class:`DynamicCatalog` can override
|
||||||
|
:py:class:`DeclarativeCatalog` and vise versa.
|
||||||
|
|
||||||
|
Example of overriding :py:class:`DeclarativeCatalog` by
|
||||||
|
:py:class:`DynamicCatalog`:
|
||||||
|
|
||||||
|
.. literalinclude:: ../../examples/catalogs/override_declarative_by_dynamic.py
|
||||||
|
:language: python
|
||||||
|
|
|
@ -1,44 +0,0 @@
|
||||||
"""Catalog overriding example."""
|
|
||||||
|
|
||||||
import collections
|
|
||||||
import dependency_injector as di
|
|
||||||
|
|
||||||
|
|
||||||
# Creating some example classes:
|
|
||||||
Object1 = collections.namedtuple('Object1', ['arg1', 'arg2'])
|
|
||||||
Object2 = collections.namedtuple('Object2', ['object1'])
|
|
||||||
ExtendedObject2 = collections.namedtuple('ExtendedObject2', [])
|
|
||||||
|
|
||||||
|
|
||||||
class Catalog(di.DeclarativeCatalog):
|
|
||||||
"""Providers catalog."""
|
|
||||||
|
|
||||||
object1_factory = di.Factory(Object1,
|
|
||||||
arg1=1,
|
|
||||||
arg2=2)
|
|
||||||
""":type: di.Provider -> Object1"""
|
|
||||||
|
|
||||||
object2_factory = di.Factory(Object2,
|
|
||||||
object1=object1_factory)
|
|
||||||
""":type: di.Provider -> Object2"""
|
|
||||||
|
|
||||||
|
|
||||||
class AnotherCatalog(di.DeclarativeCatalog):
|
|
||||||
"""Another providers catalog."""
|
|
||||||
|
|
||||||
object2_factory = di.Factory(ExtendedObject2)
|
|
||||||
""":type: di.Provider -> ExtendedObject2"""
|
|
||||||
|
|
||||||
|
|
||||||
# Overriding `Catalog` with `AnotherCatalog`:
|
|
||||||
Catalog.override(AnotherCatalog)
|
|
||||||
|
|
||||||
# Creating some objects using overridden catalog:
|
|
||||||
object2_1 = Catalog.object2_factory()
|
|
||||||
object2_2 = Catalog.object2_factory()
|
|
||||||
|
|
||||||
# Making some asserts:
|
|
||||||
assert object2_1 is not object2_2
|
|
||||||
|
|
||||||
assert isinstance(object2_1, ExtendedObject2)
|
|
||||||
assert isinstance(object2_2, ExtendedObject2)
|
|
48
examples/catalogs/override_declarative.py
Normal file
48
examples/catalogs/override_declarative.py
Normal file
|
@ -0,0 +1,48 @@
|
||||||
|
"""Declarative catalog overriding example."""
|
||||||
|
|
||||||
|
import collections
|
||||||
|
|
||||||
|
from dependency_injector import catalogs
|
||||||
|
from dependency_injector import providers
|
||||||
|
|
||||||
|
|
||||||
|
# Creating some example classes:
|
||||||
|
Object1 = collections.namedtuple('Object1', ['arg1', 'arg2'])
|
||||||
|
Object2 = collections.namedtuple('Object2', ['object1'])
|
||||||
|
ExtendedObject2 = collections.namedtuple('ExtendedObject2', [])
|
||||||
|
|
||||||
|
|
||||||
|
class Catalog(catalogs.DeclarativeCatalog):
|
||||||
|
"""Catalog of some providers."""
|
||||||
|
|
||||||
|
object1_factory = providers.Factory(Object1,
|
||||||
|
arg1=1,
|
||||||
|
arg2=2)
|
||||||
|
""":type: providers.Provider -> Object1"""
|
||||||
|
|
||||||
|
object2_factory = providers.Factory(Object2,
|
||||||
|
object1=object1_factory)
|
||||||
|
""":type: providers.Provider -> Object2"""
|
||||||
|
|
||||||
|
|
||||||
|
class AnotherCatalog(catalogs.DeclarativeCatalog):
|
||||||
|
"""Overriding catalog."""
|
||||||
|
|
||||||
|
object2_factory = providers.Factory(ExtendedObject2)
|
||||||
|
""":type: providers.Provider -> ExtendedObject2"""
|
||||||
|
|
||||||
|
|
||||||
|
# Overriding `Catalog` with `AnotherCatalog`:
|
||||||
|
Catalog.override(AnotherCatalog)
|
||||||
|
|
||||||
|
# Creating some objects using overridden catalog:
|
||||||
|
object2_1 = Catalog.object2_factory()
|
||||||
|
object2_2 = Catalog.object2_factory()
|
||||||
|
|
||||||
|
# Making some asserts:
|
||||||
|
assert Catalog.is_overridden
|
||||||
|
|
||||||
|
assert object2_1 is not object2_2
|
||||||
|
|
||||||
|
assert isinstance(object2_1, ExtendedObject2)
|
||||||
|
assert isinstance(object2_2, ExtendedObject2)
|
43
examples/catalogs/override_declarative_by_dynamic.py
Normal file
43
examples/catalogs/override_declarative_by_dynamic.py
Normal file
|
@ -0,0 +1,43 @@
|
||||||
|
"""Declarative catalog overriding by dynamic catalog example."""
|
||||||
|
|
||||||
|
import collections
|
||||||
|
|
||||||
|
from dependency_injector import catalogs
|
||||||
|
from dependency_injector import providers
|
||||||
|
|
||||||
|
|
||||||
|
# Creating some example classes:
|
||||||
|
Object1 = collections.namedtuple('Object1', ['arg1', 'arg2'])
|
||||||
|
Object2 = collections.namedtuple('Object2', ['object1'])
|
||||||
|
ExtendedObject2 = collections.namedtuple('ExtendedObject2', [])
|
||||||
|
|
||||||
|
|
||||||
|
class Catalog(catalogs.DeclarativeCatalog):
|
||||||
|
"""Catalog of some providers."""
|
||||||
|
|
||||||
|
object1_factory = providers.Factory(Object1,
|
||||||
|
arg1=1,
|
||||||
|
arg2=2)
|
||||||
|
""":type: providers.Provider -> Object1"""
|
||||||
|
|
||||||
|
object2_factory = providers.Factory(Object2,
|
||||||
|
object1=object1_factory)
|
||||||
|
""":type: providers.Provider -> Object2"""
|
||||||
|
|
||||||
|
|
||||||
|
# Overriding `Catalog` with some `DynamicCatalog` instance:
|
||||||
|
overriding_catalog = catalogs.DynamicCatalog(
|
||||||
|
object2_factory=providers.Factory(ExtendedObject2))
|
||||||
|
Catalog.override(overriding_catalog)
|
||||||
|
|
||||||
|
# Creating some objects using overridden catalog:
|
||||||
|
object2_1 = Catalog.object2_factory()
|
||||||
|
object2_2 = Catalog.object2_factory()
|
||||||
|
|
||||||
|
# Making some asserts:
|
||||||
|
assert Catalog.is_overridden
|
||||||
|
|
||||||
|
assert object2_1 is not object2_2
|
||||||
|
|
||||||
|
assert isinstance(object2_1, ExtendedObject2)
|
||||||
|
assert isinstance(object2_2, ExtendedObject2)
|
46
examples/catalogs/override_declarative_decorator.py
Normal file
46
examples/catalogs/override_declarative_decorator.py
Normal file
|
@ -0,0 +1,46 @@
|
||||||
|
"""Declarative catalog overriding using `@override()` decorator example."""
|
||||||
|
|
||||||
|
import collections
|
||||||
|
|
||||||
|
from dependency_injector import catalogs
|
||||||
|
from dependency_injector import providers
|
||||||
|
|
||||||
|
# Creating some example classes:
|
||||||
|
Object1 = collections.namedtuple('Object1', ['arg1', 'arg2'])
|
||||||
|
Object2 = collections.namedtuple('Object2', ['object1'])
|
||||||
|
ExtendedObject2 = collections.namedtuple('ExtendedObject2', [])
|
||||||
|
|
||||||
|
|
||||||
|
class Catalog(catalogs.DeclarativeCatalog):
|
||||||
|
"""Catalog of some providers."""
|
||||||
|
|
||||||
|
object1_factory = providers.Factory(Object1,
|
||||||
|
arg1=1,
|
||||||
|
arg2=2)
|
||||||
|
""":type: providers.Provider -> Object1"""
|
||||||
|
|
||||||
|
object2_factory = providers.Factory(Object2,
|
||||||
|
object1=object1_factory)
|
||||||
|
""":type: providers.Provider -> Object2"""
|
||||||
|
|
||||||
|
|
||||||
|
# Overriding `Catalog` with `AnotherCatalog`:
|
||||||
|
@catalogs.override(Catalog)
|
||||||
|
class AnotherCatalog(catalogs.DeclarativeCatalog):
|
||||||
|
"""Overriding catalog."""
|
||||||
|
|
||||||
|
object2_factory = providers.Factory(ExtendedObject2)
|
||||||
|
""":type: providers.Provider -> ExtendedObject2"""
|
||||||
|
|
||||||
|
|
||||||
|
# Creating some objects using overridden catalog:
|
||||||
|
object2_1 = Catalog.object2_factory()
|
||||||
|
object2_2 = Catalog.object2_factory()
|
||||||
|
|
||||||
|
# Making some asserts:
|
||||||
|
assert Catalog.is_overridden
|
||||||
|
|
||||||
|
assert object2_1 is not object2_2
|
||||||
|
|
||||||
|
assert isinstance(object2_1, ExtendedObject2)
|
||||||
|
assert isinstance(object2_2, ExtendedObject2)
|
|
@ -1,43 +0,0 @@
|
||||||
"""Catalog overriding using `@di.override()` decorator example."""
|
|
||||||
|
|
||||||
import collections
|
|
||||||
import dependency_injector as di
|
|
||||||
|
|
||||||
|
|
||||||
# Creating some example classes:
|
|
||||||
Object1 = collections.namedtuple('Object1', ['arg1', 'arg2'])
|
|
||||||
Object2 = collections.namedtuple('Object2', ['object1'])
|
|
||||||
ExtendedObject2 = collections.namedtuple('ExtendedObject2', [])
|
|
||||||
|
|
||||||
|
|
||||||
class Catalog(di.DeclarativeCatalog):
|
|
||||||
"""Providers catalog."""
|
|
||||||
|
|
||||||
object1_factory = di.Factory(Object1,
|
|
||||||
arg1=1,
|
|
||||||
arg2=2)
|
|
||||||
""":type: di.Provider -> Object1"""
|
|
||||||
|
|
||||||
object2_factory = di.Factory(Object2,
|
|
||||||
object1=object1_factory)
|
|
||||||
""":type: di.Provider -> Object2"""
|
|
||||||
|
|
||||||
|
|
||||||
# Overriding `Catalog` with `AnotherCatalog`:
|
|
||||||
@di.override(Catalog)
|
|
||||||
class AnotherCatalog(di.DeclarativeCatalog):
|
|
||||||
"""Another providers catalog."""
|
|
||||||
|
|
||||||
object2_factory = di.Factory(ExtendedObject2)
|
|
||||||
""":type: di.Provider -> ExtendedObject2"""
|
|
||||||
|
|
||||||
|
|
||||||
# Creating some objects using overridden catalog:
|
|
||||||
object2_1 = Catalog.object2_factory()
|
|
||||||
object2_2 = Catalog.object2_factory()
|
|
||||||
|
|
||||||
# Making some asserts:
|
|
||||||
assert object2_1 is not object2_2
|
|
||||||
|
|
||||||
assert isinstance(object2_1, ExtendedObject2)
|
|
||||||
assert isinstance(object2_2, ExtendedObject2)
|
|
Loading…
Reference in New Issue
Block a user