diff --git a/docs/examples-other/bundles_miniapp.rst b/docs/examples-other/bundles_miniapp.rst deleted file mode 100644 index 4be60cb5..00000000 --- a/docs/examples-other/bundles_miniapp.rst +++ /dev/null @@ -1,74 +0,0 @@ -Bundles mini application example --------------------------------- - -.. currentmodule:: dependency_injector.containers - -"Bundles" is an example mini application that is intended to demonstrate the -power of dependency injection for creation of re-usable application components -("bundles") with 100% transparency of their dependencies. - -Example application -~~~~~~~~~~~~~~~~~~~ - -"Bundles" mini application has next structure: - -.. code-block:: bash - - bundles/ - bundles/ <-- Bundles package - photos/ <-- Photos bundle - __init__.py <-- Photos bundle dependency injection container - entities.py - repositories.py - users/ <-- Users bundle - __init__.py <-- Users bundle dependency injection container - entities.py - repositories.py - run.py <-- Entrypoint - - -IoC containers -~~~~~~~~~~~~~~ - -Next two listings show :py:class:`DeclarativeContainer`'s for "users" and -"photos" bundles. - -Listing of ``bundles/users/__init__.py``: - -.. literalinclude:: ../../examples/miniapps/bundles/bundles/users/__init__.py - :language: python - -.. note:: - - - ``Users`` container has dependency on database. - -Listing of ``bundles/photos/__init__.py``: - -.. literalinclude:: ../../examples/miniapps/bundles/bundles/photos/__init__.py - :language: python - -.. note:: - - - ``Photos`` container has dependencies on database and file storage. - -Run application -~~~~~~~~~~~~~~~ - -Finally, both "bundles" are initialized by providing needed dependencies. -Initialization of dependencies happens right in the runtime, not earlier. -Generally, it means, that any part of any bundle could be overridden on the -fly. - -Listing of ``run.py``: - -.. literalinclude:: ../../examples/miniapps/bundles/run.py - :language: python - -Links -~~~~~ - -+ `Dependency Injector `_ -+ `Full example sources `_ - - -.. disqus:: diff --git a/docs/examples-other/index.rst b/docs/examples-other/index.rst index e99ec099..8b082fa8 100644 --- a/docs/examples-other/index.rst +++ b/docs/examples-other/index.rst @@ -8,14 +8,11 @@ Other examples of inversion of control principle and powered by "Dependency Injector" framework. -Current section of documentation is designed to provide several example mini -applications that are built according to the inversion of control principle -and powered by *Dependency Injector* framework. +This sections contains assorted ``Dependency Injector`` examples. .. toctree:: :maxdepth: 2 - bundles_miniapp use_cases_miniapp password_hashing_miniapp chained_factories diff --git a/docs/examples/decoupled-packages.rst b/docs/examples/decoupled-packages.rst new file mode 100644 index 00000000..87bc9f66 --- /dev/null +++ b/docs/examples/decoupled-packages.rst @@ -0,0 +1,121 @@ +Decoupled packages example (multiple containers) +================================================ + +.. currentmodule:: dependency_injector.containers + +This example shows how to use ``Dependency Injector`` to create decoupled packages. + +To achieve a decoupling each package has a container with the components. When a component needs a +dependency from the outside of the package scope we use the ``Dependency`` provider. The package +container has no knowledge on where the dependencies come from. It states a need that the +dependencies must be provided. This helps to decouple a package from the 3rd party dependencies +and other packages. + +To wire the packages we use an application container. Application container has all 3rd party +dependencies and package containers. It wires the packages and dependencies to create a +complete application. + +We build an example micro application that consists from 3 packages: + +- ``user`` - a package with user domain logic, depends on a database +- ``photo`` - a package with photo domain logic, depends on a database and AWS S3 +- ``analytics`` - a package with analytics domain logic, depends on the ``user`` and ``photo`` + package components + +.. image:: images/decoupled-packages.png + :width: 100% + :align: center + +Start from the scratch or jump to the section: + +.. contents:: + :local: + :backlinks: none + +You can find the source code and instructions for running on the `Github `_. + +Application structure +--------------------- + +Application consists of an ``example`` package, a configuration file and a ``requirements.txt`` +file. + +.. code-block:: bash + + ./ + ├── example/ + │ ├── analytics/ + │ │ ├── __init__.py + │ │ ├── containers.py + │ │ └── services.py + │ ├── photo/ + │ │ ├── __init__.py + │ │ ├── containers.py + │ │ ├── entities.py + │ │ └── repositories.py + │ ├── user/ + │ │ ├── __init__.py + │ │ ├── containers.py + │ │ ├── entities.py + │ │ └── repositories.py + │ ├── __init__.py + │ ├── __main__.py + │ └── containers.py + ├── config.ini + └── requirements.txt + +Package containers +------------------ + +Listing of the ``example/user/containers.py``: + +.. literalinclude:: ../../examples/miniapps/decoupled-packages/example/user/containers.py + :language: python + +Listing of the ``example/photo/containers.py``: + +.. literalinclude:: ../../examples/miniapps/decoupled-packages/example/photo/containers.py + :language: python + +Listing of the ``example/analytics/containers.py``: + +.. literalinclude:: ../../examples/miniapps/decoupled-packages/example/analytics/containers.py + :language: python + +Application container +--------------------- + +Application container consists of all packages and 3rd party dependencies. Its role is to wire +everything together in a complete application. + +Listing of the ``example/containers.py``: + +.. literalinclude:: ../../examples/miniapps/decoupled-packages/example/containers.py + :language: python + +.. note:: + Package ``analytics`` has dependencies on the repositories from the ``user`` and + ``photo`` packages. This is an example of how you can pass the dependencies from one package + to another. + +Main module +----------- +Listing of the ``example/__main__.py``: + +.. literalinclude:: ../../examples/miniapps/decoupled-packages/example/__main__.py + :language: python + +Configuration +------------- + +Listing of the ``config.ini``: + +.. literalinclude:: ../../examples/miniapps/decoupled-packages/config.ini + :language: ini + +Run the application +------------------- + +You can find the source code and instructions for running on the `Github `_. + +.. disqus:: diff --git a/docs/examples/images/decoupled-packages.png b/docs/examples/images/decoupled-packages.png new file mode 100644 index 00000000..4e626b0c Binary files /dev/null and b/docs/examples/images/decoupled-packages.png differ diff --git a/docs/examples/index.rst b/docs/examples/index.rst index 2d3545f2..17c62462 100644 --- a/docs/examples/index.rst +++ b/docs/examples/index.rst @@ -12,5 +12,6 @@ Explore the examples to see the ``Dependency Injector`` in action. application-single-container application-multiple-containers + decoupled-packages .. disqus::