.coveragerc

@@ -0,0 +1,3 @@
+[run]
+include = dependency_injector/*
+omit = tests/*

.cursor/rules/coding-guide.mdc

@@ -1,29 +0,0 @@
----
-description: Code in Python and Cython
-globs:
-alwaysApply: false
----
-- Follow PEP 8 rules
-- When you write imports, split system, 3rd-party, and local imports with a new line
-- Have two empty lines between the import block and the rest of the code
-- Have an empty line (\n) at the end of every file
-- If a file is supposed to be run, always add ``if __name__ == 'main'``
-- Always follow a consistent pattern of using double or single quotes
-- When there is a class without a docblock, leave one blank line before its members, e.g.:
-```python
-class Container(containers.DeclarativeContainer):
-
-    service = providers.Factory(Service)
-```
-
-- Avoid shortcuts in names unless absolutely necessary, exceptions:
-```
-arg
-args
-kwarg
-kwargs
-obj
-cls
-```
-
-- Avoid inline comments unless absolutely necessary

.cursor/rules/makefile-commands.mdc

@@ -1,7 +0,0 @@
----
-description: Build and run tests
-globs:
-alwaysApply: false
----
-- Use Makefile commands to build, test, lint and other similar operations when they are available.
-- Activate virtualenv before running any commands by ``. venv/bin/actvate``

.cursor/rules/run-examples.mdc

@@ -1,8 +0,0 @@
----
-description: Run examples
-globs:
-alwaysApply: false
----
-- When you run an example from the ``examples/`` folder, switch to the example folder and run it from there.
-- If there are instructions on running the examples or its tests in readme, follow them
-- Activate virtualenv before running any commands by ``. venv/bin/actvate``

.deepsource.toml

@@ -1,12 +0,0 @@
-version = 1
-
-test_patterns = ["tests/**/test_*.py"]
-
-exclude_patterns = ["docs/**"]
-
-[[analyzers]]
-name = "python"
-enabled = true
-
-  [analyzers.meta]
-  runtime_version = "3.x.x"

.editorconfig

@@ -1,9 +0,0 @@
-root = true
-
-[*]
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.{py,pyi,pxd,pyx}]
-ij_visual_guides = 80,88

.github/FUNDING.yml

@@ -1 +0,0 @@
-github: rmk135

.github/workflows/publishing.yml

@@ -1,131 +0,0 @@
-name: Publishing
-
-on:
-  workflow_dispatch:
-  push:
-    tags:
-      - '*'
-
-jobs:
-
-  tests:
-    name: Run tests
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: 3.13
-      - run: pip install tox
-      - run: tox
-        env:
-          TOXENV: 3.13
-
-  linters:
-    name: Run linters
-    runs-on: ubuntu-24.04
-    strategy:
-      matrix:
-        toxenv: [flake8, pydocstyle, mypy, pylint]
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: 3.13
-      - run: pip install tox
-      - run: tox
-        env:
-          TOXENV: ${{ matrix.toxenv }}
-
-  build-sdist:
-    name: Build source tarball
-    needs: [tests, linters]
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: 3.13
-      - run: |
-          python -m pip install --upgrade build
-          python -m build --sdist
-      - uses: actions/upload-artifact@v4
-        with:
-          name: cibw-sdist
-          path: ./dist/*
-
-  build-wheels:
-    name: Build wheels
-    needs: [tests, linters]
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        os: [ubuntu-24.04, ubuntu-24.04-arm, windows-2022, macos-14]
-    env:
-      CIBW_ENABLE: pypy
-      CIBW_ENVIRONMENT: >-
-        PIP_CONFIG_SETTINGS="build_ext=-j4"
-        DEPENDENCY_INJECTOR_LIMITED_API="1"
-        CFLAGS="-g0"
-    steps:
-      - uses: actions/checkout@v3
-      - name: Build wheels
-        uses: pypa/cibuildwheel@v3.0.0
-      - uses: actions/upload-artifact@v4
-        with:
-          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
-          path: ./wheelhouse/*.whl
-
-  test-publish:
-    name: Upload release to TestPyPI
-    needs: [build-sdist, build-wheels]
-    runs-on: ubuntu-latest
-    environment: test-pypi
-    permissions:
-      id-token: write
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          pattern: cibw-*
-          path: dist
-          merge-multiple: true
-      - uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          repository-url: https://test.pypi.org/legacy/
-
-  publish:
-    name: Upload release to PyPI
-    needs: [build-sdist, build-wheels, test-publish]
-    runs-on: ubuntu-latest
-    environment: pypi
-    permissions:
-      id-token: write
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          pattern: cibw-*
-          path: dist
-          merge-multiple: true
-      - uses: pypa/gh-action-pypi-publish@release/v1
-
-  publish-docs:
-    name: Publish docs
-    needs: [publish]
-    runs-on: ubuntu-24.04
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: 3.13
-      - run: pip install awscli
-      - run: pip install -r requirements-doc.txt
-      - run: pip install -e .
-      - run: (cd docs && make clean html)
-      - run: |
-          aws s3 sync docs/_build/html s3://python-dependency-injector-docs --delete
-          aws cloudfront create-invalidation --distribution-id ${{ secrets.AWS_CLOUDFRONT_DISTRIBUTION_ID }} --path "/*" > /dev/null
-          echo "Cache invalidation triggered"
-        env:
-          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
-          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
-          AWS_DEFAULT_REGION: ${{ secrets.AWS_DEFAULT_REGION }}

.github/workflows/tests-and-linters.yml

@@ -1,67 +0,0 @@
-name: Tests and linters
-
-on: [push, pull_request, workflow_dispatch]
-
-jobs:
-
-  test-on-different-versions:
-    name: Run tests
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: ${{ matrix.python-version }}
-      - run: pip install tox
-      - run: tox
-        env:
-          DEPENDENCY_INJECTOR_LIMITED_API: 1
-          TOXENV: ${{ matrix.python-version }}
-
-  test-different-pydantic-versions:
-    name: Run tests with different pydantic versions
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: "3.12"
-      - run: pip install tox
-      - run: tox -e pydantic-v1,pydantic-v2
-
-  test-coverage:
-    name: Run tests with coverage
-    runs-on: ubuntu-latest
-    env:
-      DEPENDENCY_INJECTOR_DEBUG_MODE: 1
-      PIP_VERBOSE: 1
-      COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: 3.12
-      - run: pip install tox
-      - run: tox -vv
-        env:
-          TOXENV: coveralls
-
-  linters:
-    name: Run linters
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        toxenv: [flake8, pydocstyle, mypy, pylint]
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: 3.13
-      - run: pip install tox
-      - run: tox
-        env:
-          TOXENV: ${{ matrix.toxenv }}

.gitignore

@@ -2,6 +2,9 @@
 __pycache__/
 *.py[cod]
 
+# C extensions
+*.so
+
 # Distribution / packaging
 .Python
 env/
@@ -15,7 +18,6 @@ lib64/
 parts/
 sdist/
 var/
-wheelhouse/
 *.egg-info/
 .installed.cfg
 *.egg
@@ -31,13 +33,12 @@ pip-log.txt
 pip-delete-this-directory.txt
 
 # Unit test / coverage reports
-reports/
+htmlcov/
 .tox/
 .coverage
 .cache
 nosetests.xml
 coverage.xml
-.hypothesis/
 
 # Translations
 *.mo
@@ -56,21 +57,13 @@ target/
 .idea/
 
 # Virtualenv
-venv*/
+venv/
 
 # SQLite
 *.db
 
+# JointJS Experiments
+jointjs/
+
 # Vim Rope
 .ropeproject/
-
-# Cython artifacts
-src/**/*.c
-src/**/*.h
-src/**/*.so
-src/**/*.html
-
-# Workspace for samples
-.workspace/
-
-.vscode/

.pylintrc

@@ -0,0 +1,49 @@
+[MASTER]
+
+# Add <file or directory> to the black list. It should be a base name, not a
+# path. You may set this option multiple times.
+ignore=utils,test
+
+[MESSAGES CONTROL]
+
+# Disable the message(s) with the given id(s).
+# disable-msg=
+
+[SIMILARITIES]
+
+# Minimum lines number of a similarity.
+min-similarity-lines=5
+
+[TYPECHECK]
+ignore-mixin-members=yes
+# ignored-classes=
+zope=no
+# generated-members=providedBy,implementedBy,rawDataReceived
+
+[DESIGN]
+# Maximum number of arguments for function / method
+max-args=10
+
+# Maximum number of locals for function / method body
+max-locals=20
+
+# Maximum number of return / yield for function / method body
+max-returns=10
+
+# Maximum number of branch for function / method body
+max-branchs=10
+
+# Maximum number of statements in function / method body
+max-statements=60
+
+# Maximum number of parents for a class (see R0901).
+max-parents=10
+
+# Maximum number of attributes for a class (see R0902).
+max-attributes=30
+
+# Minimum number of public methods for a class (see R0903).
+min-public-methods=0
+
+# Maximum number of public methods for a class (see R0904).
+max-public-methods=30

.travis.yml

@@ -0,0 +1,19 @@
+sudo: false
+language: python
+install: pip install tox
+script: tox
+python:
+  - 3.5
+env:
+  - TOXENV=coveralls
+  - TOXENV=pylint
+  - TOXENV=flake8
+  - TOXENV=pep257
+  - TOXENV=py26
+  - TOXENV=py27
+  - TOXENV=py32
+  - TOXENV=py33
+  - TOXENV=py34
+  - TOXENV=py35
+  - TOXENV=pypy
+  - TOXENV=pypy3

CONTRIBUTORS.rst

@@ -1,24 +0,0 @@
-Dependency Injector Contributors
-================================
-
-+ Roman Mogylatov (rmk135)
-+ Konstantin vz'One Enchant (sirkonst)
-+ Terrence Brannon (metaperl)
-+ Stanislav Lobanov (asyncee)
-+ James Lafa (jameslafa)
-+ Vlad Ghita (vlad-ghita)
-+ Jeroen Rietveld (jeroenrietveld)
-+ Dmitry Kuzmin (xotonic)
-+ supakeen (supakeen)
-+ Bruno P. Kinoshita (kinow)
-+ RobinsonMa (RobinsonMa)
-+ Rüdiger Busche (JarnoRFB)
-+ Dmitry Rassoshenko (rda-dev)
-+ Fotis Koutoupas (kootoopas)
-+ Shubhendra Singh Chauhan (withshubh)
-+ sonthonaxrk (sonthonaxrk)
-+ Ngo Thanh Loi (Leonn) (loingo95)
-+ Thiago Hiromi (thiromi)
-+ Felipe Rubio (krouw)
-+ Anton Petrov (anton-petrov)
-+ ZipFile (ZipFile)

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2024, Roman Mogylatov
+Copyright (c) 2015, Roman Mogilatov
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -25,3 +25,4 @@ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

MANIFEST.in

@@ -1,7 +1,5 @@
-recursive-include src/dependency_injector *.py* *.c py.typed
+include dependency_injector/*
-recursive-include tests *.py
 include README.rst
-include CONTRIBUTORS.rst
+include LICENSE
-include LICENSE.rst
+include requirements.txt
 include setup.py
-include tox.ini

Makefile

@@ -1,65 +0,0 @@
-VERSION := $(shell python setup.py --version)
-
-export COVERAGE_RCFILE := pyproject.toml
-
-clean:
-	# Clean sources
-	find src -name '*.py[cod]' -delete
-	find src -name '__pycache__' -delete
-	find src -name '*.c' -delete
-	find src -name '*.h' -delete
-	find src -name '*.so' -delete
-	find src -name '*.html' -delete
-	# Clean tests
-	find tests -name '*.py[co]' -delete
-	find tests -name '__pycache__' -delete
-	# Clean examples
-	find examples -name '*.py[co]' -delete
-	find examples -name '__pycache__' -delete
-
-build: clean
-	# Compile C extensions
-	python setup.py build_ext --inplace
-	# Move all Cython html reports
-	mkdir -p reports/cython/
-	find src -name '*.html' -exec mv {}  reports/cython/  \;
-
-docs-live:
-	sphinx-autobuild docs docs/_build/html
-
-install: uninstall clean build
-	pip install -ve .
-
-uninstall:
-	- pip uninstall -y -q dependency-injector 2> /dev/null
-
-test:
-	# Unit tests with coverage report
-	coverage erase
-	coverage run -m pytest
-	coverage report
-	coverage html
-
-check:
-	flake8 src/dependency_injector/
-	flake8 examples/
-
-	pydocstyle src/dependency_injector/
-	pydocstyle examples/
-
-	mypy tests/typing
-
-test-publish: build
-	# Create distributions
-	python -m build --sdist
-	# Upload distributions to PyPI
-	twine upload --repository testpypi dist/dependency-injector-$(VERSION)*
-
-publish:
-	# Merge release to master branch
-	git checkout master
-	git merge --no-ff release/$(VERSION) -m "Merge branch 'release/$(VERSION)' into master"
-	git push origin master
-	# Create and upload tag
-	git tag -a $(VERSION) -m 'version $(VERSION)'
-	git push --tags

README.rst

@@ -1,230 +1,158 @@
-.. figure:: https://raw.githubusercontent.com/wiki/ets-labs/python-dependency-injector/img/logo.svg
+Dependency Injector
-   :target: https://github.com/ets-labs/python-dependency-injector
+===================
 
-| 
+Dependency injection framework for Python projects.
 
-.. image:: https://img.shields.io/pypi/v/dependency_injector.svg
++---------------------------------------+-------------------------------------------------------------------------------+
-   :target: https://pypi.org/project/dependency-injector/
+| *PyPi*                                | .. image:: https://img.shields.io/pypi/v/dependency_injector.svg              |
-   :alt: Latest Version
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
-   
+|                                       |    :alt: Latest Version                                                       |
-.. image:: https://img.shields.io/pypi/l/dependency_injector.svg
+|                                       | .. image:: https://img.shields.io/pypi/dm/dependency_injector.svg             |
-   :target: https://pypi.org/project/dependency-injector/
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
-   :alt: License
+|                                       |    :alt: Downloads                                                            |
+|                                       | .. image:: https://img.shields.io/pypi/l/dependency_injector.svg              |
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
+|                                       |    :alt: License                                                              |
++---------------------------------------+-------------------------------------------------------------------------------+
+| *Python versions and implementations* | .. image:: https://img.shields.io/pypi/pyversions/dependency_injector.svg     |
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
+|                                       |    :alt: Supported Python versions                                            |
+|                                       | .. image:: https://img.shields.io/pypi/implementation/dependency_injector.svg |
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
+|                                       |    :alt: Supported Python implementations                                     |
++---------------------------------------+-------------------------------------------------------------------------------+
+| *Builds and tests coverage*           | .. image:: https://travis-ci.org/rmk135/dependency_injector.svg?branch=master |
+|                                       |    :target: https://travis-ci.org/rmk135/dependency_injector                  |
+|                                       |    :alt: Build Status                                                         |
+|                                       | .. image:: https://coveralls.io/repos/rmk135/dependency_injector/badge.svg    |
+|                                       |    :target: https://coveralls.io/r/rmk135/dependency_injector                 |
+|                                       |    :alt: Coverage Status                                                      |
++---------------------------------------+-------------------------------------------------------------------------------+
 
-.. image:: https://img.shields.io/pypi/pyversions/dependency_injector.svg
+*Dependency Injector* is a dependency injection framework for Python projects. 
-   :target: https://pypi.org/project/dependency-injector/
+It was designed to be unified, developer's friendly tool for managing any kind
-   :alt: Supported Python versions
+of Python objects and their dependencies in formal, pretty way.
-   
-.. image:: https://img.shields.io/pypi/implementation/dependency_injector.svg
-   :target: https://pypi.org/project/dependency-injector/
-   :alt: Supported Python implementations
 
-.. image:: https://pepy.tech/badge/dependency-injector
+Below is a list of some key features and points of *Dependency Injector*
-   :target: https://pepy.tech/project/dependency-injector
+framework:
-   :alt: Downloads
 
-.. image:: https://pepy.tech/badge/dependency-injector/month
+- Easy, smart, pythonic style.
-   :target: https://pepy.tech/project/dependency-injector
+- Obvious, clear structure.
-   :alt: Downloads
+- Memory efficiency.
+- Thread safety.
+- Semantic versioning.
 
-.. image:: https://pepy.tech/badge/dependency-injector/week
+Main idea of *Dependency Injector* is to keep dependencies under control.
-   :target: https://pepy.tech/project/dependency-injector
-   :alt: Downloads
-
-.. image:: https://img.shields.io/pypi/wheel/dependency-injector.svg
-   :target: https://pypi.org/project/dependency-injector/
-   :alt: Wheel
-
-.. image:: https://img.shields.io/github/actions/workflow/status/ets-labs/python-dependency-injector/tests-and-linters.yml?branch=master
-   :target: https://github.com/ets-labs/python-dependency-injector/actions
-   :alt: Build Status
-
-.. image:: https://coveralls.io/repos/github/ets-labs/python-dependency-injector/badge.svg?branch=master
-   :target: https://coveralls.io/github/ets-labs/python-dependency-injector?branch=master
-   :alt: Coverage Status
-
-What is ``Dependency Injector``?
-================================
-
-``Dependency Injector`` is a dependency injection framework for Python.
-
-It helps implement the dependency injection principle.
-
-Key features of the ``Dependency Injector``:
-
-- **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
-  ``List``, ``Dict``, ``Configuration``, ``Resource``, ``Dependency``, and ``Selector`` providers
-  that help assemble your objects.
-  See `Providers <https://python-dependency-injector.ets-labs.org/providers/index.html>`_.
-- **Overriding**. Can override any provider by another provider on the fly. This helps in testing
-  and configuring dev/stage environment to replace API clients with stubs etc. See
-  `Provider overriding <https://python-dependency-injector.ets-labs.org/providers/overriding.html>`_.
-- **Configuration**. Reads configuration from ``yaml``, ``ini``, and ``json`` files, ``pydantic`` settings,
-  environment variables, and dictionaries.
-  See `Configuration provider <https://python-dependency-injector.ets-labs.org/providers/configuration.html>`_.
-- **Resources**. Helps with initialization and configuring of logging, event loop, thread
-  or process pool, etc. Can be used for per-function execution scope in tandem with wiring.
-  See `Resource provider <https://python-dependency-injector.ets-labs.org/providers/resource.html>`_.
-- **Containers**. Provides declarative and dynamic containers.
-  See `Containers <https://python-dependency-injector.ets-labs.org/containers/index.html>`_.
-- **Wiring**. Injects dependencies into functions and methods. Helps integrate with
-  other frameworks: Django, Flask, Aiohttp, Sanic, FastAPI, etc.
-  See `Wiring <https://python-dependency-injector.ets-labs.org/wiring.html>`_.
-- **Asynchronous**. Supports asynchronous injections.
-  See `Asynchronous injections <https://python-dependency-injector.ets-labs.org/providers/async.html>`_.
-- **Typing**. Provides typing stubs, ``mypy``-friendly.
-  See `Typing and mypy <https://python-dependency-injector.ets-labs.org/providers/typing_mypy.html>`_.
-- **Performance**. Fast. Written in ``Cython``.
-- **Maturity**. Mature and production-ready. Well-tested, documented, and supported.
-
-.. code-block:: python
-
-   from dependency_injector import containers, providers
-   from dependency_injector.wiring import Provide, inject
-
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration()
-
-       api_client = providers.Singleton(
-           ApiClient,
-           api_key=config.api_key,
-           timeout=config.timeout,
-       )
-
-       service = providers.Factory(
-           Service,
-           api_client=api_client,
-       )
-
-
-   @inject
-   def main(service: Service = Provide[Container.service]) -> None:
-       ...
-
-
-   if __name__ == "__main__":
-       container = Container()
-       container.config.api_key.from_env("API_KEY", required=True)
-       container.config.timeout.from_env("TIMEOUT", as_=int, default=5)
-       container.wire(modules=[__name__])
-
-       main()  # <-- dependency is injected automatically
-
-       with container.api_client.override(mock.Mock()):
-           main()  # <-- overridden dependency is injected automatically
-
-When you call the ``main()`` function the ``Service`` dependency is assembled and injected automatically.
-
-When you do testing, you call the ``container.api_client.override()`` method to replace the real API
-client with a mock. When you call ``main()``, the mock is injected.
-
-You can override any provider with another provider.
-
-It also helps you in a re-configuring project for different environments: replace an API client
-with a stub on the dev or stage.
-
-With the ``Dependency Injector``, object assembling is consolidated in a container. Dependency injections are defined explicitly.
-This makes it easier to understand and change how an application works.
-
-.. figure:: https://raw.githubusercontent.com/wiki/ets-labs/python-dependency-injector/img/di-readme.svg
-   :target: https://github.com/ets-labs/python-dependency-injector
-
-Visit the docs to know more about the
-`Dependency injection and inversion of control in Python <https://python-dependency-injector.ets-labs.org/introduction/di_in_python.html>`_.
 
 Installation
 ------------
 
-The package is available on the `PyPi`_::
+*Dependency Injector* library is available on PyPi_::
 
-    pip install dependency-injector
+    pip install dependency_injector
 
 Documentation
 -------------
 
-The documentation is available `here <https://python-dependency-injector.ets-labs.org/>`_.
+*Dependency Injector* documentation is hosted on ReadTheDocs:
+
+- `User's guide`_ 
+- `API docs`_
 
 Examples
 --------
 
-Choose one of the following:
+.. code-block:: python
 
-- `Application example (single container) <https://python-dependency-injector.ets-labs.org/examples/application-single-container.html>`_
+    """Concept example of `Dependency Injector`."""
-- `Application example (multiple containers) <https://python-dependency-injector.ets-labs.org/examples/application-multiple-containers.html>`_
-- `Decoupled packages example (multiple containers) <https://python-dependency-injector.ets-labs.org/examples/decoupled-packages.html>`_
-- `Boto3 example <https://python-dependency-injector.ets-labs.org/examples/boto3.html>`_
-- `Django example <https://python-dependency-injector.ets-labs.org/examples/django.html>`_
-- `Flask example <https://python-dependency-injector.ets-labs.org/examples/flask.html>`_
-- `Aiohttp example <https://python-dependency-injector.ets-labs.org/examples/aiohttp.html>`_
-- `Sanic example <https://python-dependency-injector.ets-labs.org/examples/sanic.html>`_
-- `FastAPI example <https://python-dependency-injector.ets-labs.org/examples/fastapi.html>`_
-- `FastAPI + Redis example <https://python-dependency-injector.ets-labs.org/examples/fastapi-redis.html>`_
-- `FastAPI + SQLAlchemy example <https://python-dependency-injector.ets-labs.org/examples/fastapi-sqlalchemy.html>`_
 
-Tutorials
+    import sqlite3
----------
 
-Choose one of the following:
+    from dependency_injector import catalogs
+    from dependency_injector import providers
+    from dependency_injector import injections
 
-- `Flask web application tutorial <https://python-dependency-injector.ets-labs.org/tutorials/flask.html>`_
-- `Aiohttp REST API tutorial <https://python-dependency-injector.ets-labs.org/tutorials/aiohttp.html>`_
-- `Asyncio monitoring daemon tutorial <https://python-dependency-injector.ets-labs.org/tutorials/asyncio-daemon.html>`_
-- `CLI application tutorial <https://python-dependency-injector.ets-labs.org/tutorials/cli.html>`_
 
-Concept
+    class UsersService(object):
--------
+        """Users service, that has dependency on database."""
 
-The framework stands on the `PEP20 (The Zen of Python) <https://www.python.org/dev/peps/pep-0020/>`_ principle:
+        def __init__(self, db):
+            """Initializer."""
+            self.db = db
 
-.. code-block:: bash
 
-   Explicit is better than implicit
+    class AuthService(object):
+        """Auth service, that has dependencies on users service and database."""
 
-You need to specify how to assemble and where to inject the dependencies explicitly.
+        def __init__(self, db, users_service):
+            """Initializer."""
+            self.db = db
+            self.users_service = users_service
 
-The power of the framework is in its simplicity.
-``Dependency Injector`` is a simple tool for the powerful concept.
 
-Frequently asked questions
+    class Services(catalogs.DeclarativeCatalog):
---------------------------
+        """Catalog of service providers."""
 
-What is dependency injection?
+        database = providers.Singleton(sqlite3.connect,
- - dependency injection is a principle that decreases coupling and increases cohesion
+                                       injections.Arg(':memory:'))
+        """:type: providers.Provider -> sqlite3.Connection"""
 
-Why should I do the dependency injection?
+        users = providers.Factory(UsersService,
- - your code becomes more flexible, testable, and clear 😎
+                                  injections.KwArg('db', database))
+        """:type: providers.Provider -> UsersService"""
 
-How do I start applying the dependency injection?
+        auth = providers.Factory(AuthService,
- - you start writing the code following the dependency injection principle
+                                 injections.KwArg('db', database),
- - you register all of your application components and their dependencies in the container
+                                 injections.KwArg('users_service', users))
- - when you need a component, you specify where to inject it or get it from the container
+        """:type: providers.Provider -> AuthService"""
 
-What price do I pay and what do I get?
- - you need to explicitly specify the dependencies
- - it will be extra work in the beginning
- - it will payoff as project grows
 
-Have a question?
+    # Retrieving catalog providers:
- - Open a `Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_
+    users_service = Services.users()
+    auth_service = Services.auth()
 
-Found a bug?
+    # Making some asserts:
- - Open a `Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_
+    assert users_service.db is auth_service.db is Services.database()
+    assert isinstance(auth_service.users_service, UsersService)
+    assert users_service is not Services.users()
+    assert auth_service is not Services.auth()
 
-Want to help?
- - |star| Star the ``Dependency Injector`` on the `Github <https://github.com/ets-labs/python-dependency-injector/>`_
- - |new| Start a new project with the ``Dependency Injector``
- - |tell| Tell your friend about the ``Dependency Injector``
 
-Want to contribute?
+    # Making some "inline" injections:
- - |fork| Fork the project
+    @injections.inject(users_service=Services.users)
- - |pull| Open a pull request to the ``develop`` branch
+    @injections.inject(auth_service=Services.auth)
+    @injections.inject(database=Services.database)
+    def example(users_service, auth_service, database):
+        """Example callback."""
+        assert users_service.db is auth_service.db
+        assert auth_service.db is database
+        assert database is Services.database()
 
-.. _PyPi: https://pypi.org/project/dependency-injector/
 
-.. |star| unicode:: U+2B50 U+FE0F .. star sign1
+    # Making a call of decorated callback:
-.. |new| unicode:: U+1F195 .. new sign
+    example()
-.. |tell| unicode:: U+1F4AC .. tell sign
+
-.. |fork| unicode:: U+1F500 .. fork sign
+You can get more *Dependency Injector* examples in ``/examples`` directory on
-.. |pull| unicode:: U+2B05 U+FE0F .. pull sign
+GitHub:
+
+    https://github.com/rmk135/dependency_injector
+
+
+Feedback
+--------
+
+Feel free to post questions, bugs, feature requests, proposals etc. on
+*Dependency Injector*  GitHub Issues:
+
+    https://github.com/rmk135/dependency_injector/issues
+
+Your feedback is quite important!
+
+
+.. _PyPi: https://pypi.python.org/pypi/dependency_injector
+.. _User's guide: http://dependency_injector.readthedocs.org/en/stable/
+.. _API docs: http://dependency-injector.readthedocs.org/en/stable/api/
+.. _SLOC: http://en.wikipedia.org/wiki/Source_lines_of_code
+.. _SOLID: http://en.wikipedia.org/wiki/SOLID_%28object-oriented_design%29
+.. _IoC: http://en.wikipedia.org/wiki/Inversion_of_control
+.. _dependency injection: http://en.wikipedia.org/wiki/Dependency_injection

dependency_injector/__init__.py

@@ -0,0 +1,108 @@
+"""Dependency injector."""
+
+from .catalogs import DeclarativeCatalog
+from .catalogs import AbstractCatalog
+from .catalogs import DynamicCatalog
+from .catalogs import CatalogBundle
+from .catalogs import override
+
+from .providers import Provider
+from .providers import Delegate
+from .providers import Factory
+from .providers import Singleton
+from .providers import ExternalDependency
+from .providers import StaticProvider
+from .providers import Class
+from .providers import Object
+from .providers import Function
+from .providers import Value
+from .providers import Callable
+from .providers import Config
+
+from .injections import Injection
+from .injections import Arg
+from .injections import KwArg
+from .injections import Attribute
+from .injections import Method
+from .injections import inject
+
+from .utils import is_provider
+from .utils import ensure_is_provider
+from .utils import is_injection
+from .utils import ensure_is_injection
+from .utils import is_arg_injection
+from .utils import is_kwarg_injection
+from .utils import is_attribute_injection
+from .utils import is_method_injection
+from .utils import is_catalog
+from .utils import is_dynamic_catalog
+from .utils import is_declarative_catalog
+from .utils import is_catalog_bundle
+from .utils import ensure_is_catalog_bundle
+
+from .errors import Error
+from .errors import UndefinedProviderError
+
+# Backward compatibility for versions < 0.11.*
+from . import catalogs
+catalog = catalogs
+
+VERSION = '1.12.0'
+"""Version number that follows semantic versioning.
+
+:type: str
+"""
+
+
+__all__ = (
+    # Catalogs
+    'DeclarativeCatalog',
+    'AbstractCatalog',
+    'DynamicCatalog',
+    'CatalogBundle',
+    'override',
+
+    # Providers
+    'Provider',
+    'Delegate',
+    'Factory',
+    'Singleton',
+    'ExternalDependency',
+    'StaticProvider',
+    'Class',
+    'Object',
+    'Function',
+    'Value',
+    'Callable',
+    'Config',
+
+    # Injections
+    'Injection',
+    'Arg',
+    'KwArg',
+    'Attribute',
+    'Method',
+    'inject',
+
+    # Utils
+    'is_provider',
+    'ensure_is_provider',
+    'is_injection',
+    'ensure_is_injection',
+    'is_arg_injection',
+    'is_kwarg_injection',
+    'is_attribute_injection',
+    'is_method_injection',
+    'is_catalog',
+    'is_dynamic_catalog',
+    'is_declarative_catalog',
+    'is_catalog_bundle',
+    'ensure_is_catalog_bundle',
+
+    # Errors
+    'Error',
+    'UndefinedProviderError',
+
+    # Version
+    'VERSION'
+)

dependency_injector/catalogs.py

@@ -0,0 +1,891 @@
+"""Catalogs module."""
+
+import six
+
+from .errors import Error
+from .errors import UndefinedProviderError
+
+from .utils import is_provider
+from .utils import is_catalog
+from .utils import is_declarative_catalog
+from .utils import ensure_is_provider
+from .utils import ensure_is_catalog_bundle
+
+
+@six.python_2_unicode_compatible
+class CatalogBundle(object):
+    """Bundle of catalog providers.
+
+    :py:class:`CatalogBundle` is a frozen, limited collection of catalog
+    providers. While catalog could be used as a centralized place for
+    particular providers group, such bundles of catalog providers can be used
+    for creating several frozen, limited scopes that could be passed to
+    different subsystems.
+
+    :py:class:`CatalogBundle` has API's parity with catalogs
+    (:py:class:`DeclarativeCatalog` or :py:class:`DynamicCatalog`) in terms of
+    retrieving the providers, but it is "frozen" in terms of modification
+    provider's list.
+
+    :py:class:`CatalogBundle` is considered to be dependable on catalogs
+    (:py:class:`DeclarativeCatalog` or :py:class:`DynamicCatalog`) entity by
+    its design.
+
+    .. py:attribute:: catalog
+
+        Bundle's catalog.
+
+        :type: :py:class:`DeclarativeCatalog` | :py:class:`DynamicCatalog`
+
+    .. py:attribute:: providers
+
+        Dictionary of all providers.
+
+        :type: dict[str, :py:class:`dependency_injector.providers.Provider`]
+    """
+
+    catalog = None
+
+    __IS_CATALOG_BUNDLE__ = True
+    __slots__ = ('providers', '__dict__')
+
+    @classmethod
+    def sub_cls_factory(cls, catalog):
+        """Create bundle subclass for catalog.
+
+        :return: Subclass of :py:class:`CatalogBundle`.
+        :rtype: :py:class:`CatalogBundle`
+        """
+        return type('BundleSubclass', (cls,), dict(catalog=catalog))
+
+    def __init__(self, *providers):
+        """Initializer.
+
+        :param providers: Tuple of catalog's bundle providers.
+        :type providers: tuple[
+            :py:class:`dependency_injector.providers.Provider`]
+        """
+        self.providers = dict((self.catalog.get_provider_bind_name(provider),
+                               provider)
+                              for provider in providers)
+        self.__dict__.update(self.providers)
+        super(CatalogBundle, self).__init__()
+
+    def get_provider(self, name):
+        """Return provider with specified name or raise an error.
+
+        :param name: Provider's name.
+        :type name: str
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+
+        :return: Provider with specified name.
+        :rtype: :py:class:`dependency_injector.providers.Provider`
+        """
+        try:
+            return self.providers[name]
+        except KeyError:
+            raise Error('Provider "{0}" is not a part of {1}'.format(name,
+                                                                     self))
+
+    def has_provider(self, name):
+        """Check if there is provider with certain name.
+
+        :param name: Provider's name.
+        :type name: str
+
+        :rtype: bool
+        """
+        return name in self.providers
+
+    def __getattr__(self, item):
+        """Return provider with specified name or raise en error.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+        """
+        if item.startswith('__') and item.endswith('__'):
+            return super(CatalogBundle, self).__getattr__(item)
+        raise UndefinedProviderError('Provider "{0}" is not a part '
+                                     'of {1}'.format(item, self))
+
+    def __repr__(self):
+        """Return string representation of catalog's bundle.
+
+        :rtype: str
+        """
+        return '<{0}.Bundle({1})>'.format(
+            self.catalog.name, ', '.join(six.iterkeys(self.providers)))
+
+    __str__ = __repr__
+
+
+@six.python_2_unicode_compatible
+class DynamicCatalog(object):
+    """Dynamic catalog of providers.
+
+    :py:class:`DynamicCatalog` is a catalog of providers that could be created
+    in application's runtime. It should cover most of the cases when list of
+    providers that would be included in catalog is non-deterministic in terms
+    of apllication code (catalog's structure could be determined just after
+    application will be started and will do some initial work, like parsing
+    list of catalog's providers from the configuration).
+
+    .. code-block:: python
+
+        services = DynamicCatalog(auth=providers.Factory(AuthService),
+                                  users=providers.Factory(UsersService))
+
+        users_service = services.users()
+
+    .. py:attribute:: Bundle
+
+        Catalog's bundle class.
+
+        :type: :py:class:`CatalogBundle`
+
+    .. py:attribute:: name
+
+        Catalog's name.
+
+        By default, it is catalog's module + catalog's class name.
+
+        :type: str
+
+    .. py:attribute:: providers
+
+        Dictionary of all providers.
+
+        :type: dict[str, :py:class:`dependency_injector.providers.Provider`]
+
+    .. py:attribute:: overridden_by
+
+        Tuple of overriding catalogs.
+
+        :type: tuple[
+            :py:class:`DeclarativeCatalog` | :py:class:`DynamicCatalog`]
+
+    .. py:attribute:: provider_type
+
+        If provider type is defined, :py:class:`DynamicCatalog` checks that
+        all of its providers are instances of
+        :py:attr:`DynamicCatalog.provider_type`.
+
+        :type: type | None
+    """
+
+    provider_type = None
+
+    __IS_CATALOG__ = True
+    __slots__ = ('name', 'providers', 'provider_names', 'overridden_by',
+                 'Bundle')
+
+    def __init__(self, **providers):
+        """Initializer.
+
+        :param providers: Dictionary of catalog providers.
+        :type providers:
+            dict[str, :py:class:`dependency_injector.providers.Provider`]
+        """
+        self.Bundle = CatalogBundle.sub_cls_factory(self)
+        self.name = '.'.join((self.__class__.__module__,
+                              self.__class__.__name__))
+        self.providers = dict()
+        self.provider_names = dict()
+        self.overridden_by = tuple()
+        self.bind_providers(providers)
+        super(DynamicCatalog, self).__init__()
+
+    def is_bundle_owner(self, bundle):
+        """Check if catalog is bundle owner.
+
+        :param bundle: Catalog's bundle instance.
+        :type bundle: :py:class:`CatalogBundle`
+
+        :rtype: bool
+        """
+        return ensure_is_catalog_bundle(bundle) and bundle.catalog is self
+
+    def get_provider_bind_name(self, provider):
+        """Return provider's name in catalog.
+
+        :param provider: Provider instance.
+        :type provider: :py:class:`dependency_injector.providers.Provider`
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+
+        :return: Provider's name.
+        :rtype: str
+        """
+        if not self.is_provider_bound(provider):
+            raise Error('Can not find bind name for {0} in catalog {1}'.format(
+                provider, self))
+        return self.provider_names[provider]
+
+    def is_provider_bound(self, provider):
+        """Check if provider is bound to the catalog.
+
+        :param provider: Provider instance.
+        :type provider: :py:class:`dependency_injector.providers.Provider`
+
+        :rtype: bool
+        """
+        return provider in self.provider_names
+
+    def filter(self, provider_type):
+        """Return dictionary of providers, that are instance of provided type.
+
+        :param provider_type: Provider's type.
+        :type provider_type: :py:class:`dependency_injector.providers.Provider`
+
+        :rtype: dict[str, :py:class:`dependency_injector.providers.Provider`]
+        """
+        return dict((name, provider)
+                    for name, provider in six.iteritems(self.providers)
+                    if isinstance(provider, provider_type))
+
+    @property
+    def is_overridden(self):
+        """Read-only property that is set to ``True`` if catalog is overridden.
+
+        :rtype: bool
+        """
+        return bool(self.overridden_by)
+
+    @property
+    def last_overriding(self):
+        """Read-only reference to the last overriding catalog, if any.
+
+        :type: :py:class:`DeclarativeCatalog` | :py:class:`DynamicCatalog` |
+               None
+        """
+        return self.overridden_by[-1] if self.overridden_by else None
+
+    def override(self, overriding):
+        """Override current catalog providers by overriding catalog providers.
+
+        :param overriding: Overriding catalog.
+        :type overriding: :py:class:`DeclarativeCatalog` |
+                          :py:class:`DynamicCatalog`
+
+        :raise: :py:exc:`dependency_injector.errors.Error` if trying to
+                override catalog by itself
+
+        :rtype: None
+        """
+        if overriding is self:
+            raise Error('Catalog {0} could not be overridden '
+                        'with itself'.format(self))
+        self.overridden_by += (overriding,)
+        for name, provider in six.iteritems(overriding.providers):
+            self.get_provider(name).override(provider)
+
+    def reset_last_overriding(self):
+        """Reset last overriding catalog.
+
+        :rtype: None
+        """
+        if not self.is_overridden:
+            raise Error('Catalog {0} is not overridden'.format(self))
+        self.overridden_by = self.overridden_by[:-1]
+        for provider in six.itervalues(self.providers):
+            provider.reset_last_overriding()
+
+    def reset_override(self):
+        """Reset all overridings for all catalog providers.
+
+        :rtype: None
+        """
+        self.overridden_by = tuple()
+        for provider in six.itervalues(self.providers):
+            provider.reset_override()
+
+    def get_provider(self, name):
+        """Return provider with specified name or raise an error.
+
+        :param name: Provider's name.
+        :type name: str
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+
+        :return: Provider with specified name.
+        :rtype: :py:class:`dependency_injector.providers.Provider`
+        """
+        try:
+            return self.providers[name]
+        except KeyError:
+            raise UndefinedProviderError('{0} has no provider with such '
+                                         'name - {1}'.format(self, name))
+
+    def bind_provider(self, name, provider):
+        """Bind provider to catalog with specified name.
+
+        :param name: Name of the provider.
+        :type name: str
+
+        :param provider: Provider instance.
+        :type provider: :py:class:`dependency_injector.providers.Provider`
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+
+        :rtype: None
+        """
+        provider = ensure_is_provider(provider)
+
+        if (self.__class__.provider_type and
+                not isinstance(provider, self.__class__.provider_type)):
+            raise Error('{0} can contain only {1} instances'.format(
+                self, self.__class__.provider_type))
+
+        if name in self.providers:
+            raise Error('Catalog {0} already has provider with '
+                        'such name - {1}'.format(self, name))
+        if provider in self.provider_names:
+            raise Error('Catalog {0} already has such provider '
+                        'instance - {1}'.format(self, provider))
+
+        self.providers[name] = provider
+        self.provider_names[provider] = name
+
+    def bind_providers(self, providers):
+        """Bind providers dictionary to catalog.
+
+        :param providers: Dictionary of providers, where key is a name
+            and value is a provider.
+        :type providers:
+            dict[str, :py:class:`dependency_injector.providers.Provider`]
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+
+        :rtype: None
+        """
+        for name, provider in six.iteritems(providers):
+            self.bind_provider(name, provider)
+
+    def has_provider(self, name):
+        """Check if there is provider with certain name.
+
+        :param name: Provider's name.
+        :type name: str
+
+        :rtype: bool
+        """
+        return name in self.providers
+
+    def unbind_provider(self, name):
+        """Remove provider binding.
+
+        :param name: Provider's name.
+        :type name: str
+
+        :rtype: None
+        """
+        provider = self.get_provider(name)
+        del self.providers[name]
+        del self.provider_names[provider]
+
+    def __getattr__(self, name):
+        """Return provider with specified name or raise en error.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+        """
+        return self.get_provider(name)
+
+    def __setattr__(self, name, value):
+        """Handle setting of catalog attributes.
+
+        Setting of attributes works as usual, but if value of attribute is
+        provider, this provider will be bound to catalog.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :param value: Attribute's value.
+        :type value: :py:class:`dependency_injector.providers.Provider` |
+                     object
+
+        :rtype: None
+        """
+        if is_provider(value):
+            return self.bind_provider(name, value)
+        return super(DynamicCatalog, self).__setattr__(name, value)
+
+    def __delattr__(self, name):
+        """Handle deleting of catalog attibute.
+
+        Deleting of attributes works as usual, but if value of attribute is
+        provider, this provider will be unbound from catalog.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :rtype: None
+        """
+        self.unbind_provider(name)
+
+    def __repr__(self):
+        """Return Python representation of catalog.
+
+        :rtype: str
+        """
+        return '<{0}({1})>'.format(self.name,
+                                   ', '.join(six.iterkeys(self.providers)))
+
+    __str__ = __repr__
+
+
+@six.python_2_unicode_compatible
+class DeclarativeCatalogMetaClass(type):
+    """Declarative catalog meta class."""
+
+    def __new__(mcs, class_name, bases, attributes):
+        """Declarative catalog class factory."""
+        cls_providers = tuple((name, provider)
+                              for name, provider in six.iteritems(attributes)
+                              if is_provider(provider))
+
+        inherited_providers = tuple((name, provider)
+                                    for base in bases if is_catalog(base)
+                                    for name, provider in six.iteritems(
+                                        base.providers))
+
+        providers = cls_providers + inherited_providers
+
+        cls = type.__new__(mcs, class_name, bases, attributes)
+
+        if cls.provider_type:
+            cls._catalog = type('DynamicCatalog',
+                                (DynamicCatalog,),
+                                dict(provider_type=cls.provider_type))()
+        else:
+            cls._catalog = DynamicCatalog()
+
+        cls._catalog.name = '.'.join((cls.__module__, cls.__name__))
+        cls._catalog.bind_providers(dict(providers))
+
+        cls.cls_providers = dict(cls_providers)
+        cls.inherited_providers = dict(inherited_providers)
+
+        cls.Bundle = cls._catalog.Bundle
+
+        return cls
+
+    @property
+    def name(cls):
+        """Read-only property that represents catalog's name.
+
+        Catalog's name is catalog's module + catalog's class name.
+
+        :type: str
+        """
+        return cls._catalog.name
+
+    @property
+    def providers(cls):
+        """Read-only dictionary of all providers.
+
+        :type: dict[str, :py:class:`dependency_injector.providers.Provider`]
+        """
+        return cls._catalog.providers
+
+    @property
+    def overridden_by(cls):
+        """Tuple of overriding catalogs.
+
+        :type: tuple[
+            :py:class:`DeclarativeCatalog` |
+            :py:class:`DynamicCatalog`]
+        """
+        return cls._catalog.overridden_by
+
+    @property
+    def is_overridden(cls):
+        """Read-only property that is set to ``True`` if catalog is overridden.
+
+        :rtype: bool
+        """
+        return cls._catalog.is_overridden
+
+    @property
+    def last_overriding(cls):
+        """Read-only reference to the last overriding catalog, if any.
+
+        :type: :py:class:`DeclarativeCatalog` | :py:class:`DynamicCatalog` |
+               None
+        """
+        return cls._catalog.last_overriding
+
+    def __getattr__(cls, name):
+        """Return provider with specified name or raise en error.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+        """
+        raise UndefinedProviderError('There is no provider "{0}" in '
+                                     'catalog {1}'.format(name, cls))
+
+    def __setattr__(cls, name, value):
+        """Handle setting of catalog attributes.
+
+        Setting of attributes works as usual, but if value of attribute is
+        provider, this provider will be bound to catalog.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :param value: Attribute's value.
+        :type value: :py:class:`dependency_injector.providers.Provider` |
+                     object
+
+        :rtype: None
+        """
+        if is_provider(value):
+            setattr(cls._catalog, name, value)
+        return super(DeclarativeCatalogMetaClass, cls).__setattr__(name, value)
+
+    def __delattr__(cls, name):
+        """Handle deleting of catalog attibute.
+
+        Deleting of attributes works as usual, but if value of attribute is
+        provider, this provider will be unbound from catalog.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :rtype: None
+        """
+        if is_provider(getattr(cls, name)):
+            delattr(cls._catalog, name)
+        return super(DeclarativeCatalogMetaClass, cls).__delattr__(name)
+
+    def __repr__(cls):
+        """Return string representation of the catalog.
+
+        :rtype: str
+        """
+        return '<{0}({1})>'.format(cls.name,
+                                   ', '.join(six.iterkeys(cls.providers)))
+
+    __str__ = __repr__
+
+
+@six.add_metaclass(DeclarativeCatalogMetaClass)
+class DeclarativeCatalog(object):
+    """Declarative catalog of providers.
+
+    :py:class:`DeclarativeCatalog` is a catalog of providers that could be
+    defined in declarative manner. It should cover most of the cases when list
+    of providers that would be included in catalog is deterministic (catalog
+    will not change its structure in runtime).
+
+    .. code-block:: python
+
+        class Services(DeclarativeCatalog):
+
+            auth = providers.Factory(AuthService)
+
+            users = providers.Factory(UsersService)
+
+        users_service = Services.users()
+
+    .. py:attribute:: Bundle
+
+        Catalog's bundle class.
+
+        :type: :py:class:`CatalogBundle`
+
+    .. py:attribute:: name
+
+        Read-only property that represents catalog's name.
+
+        Catalog's name is catalog's module + catalog's class name.
+
+        :type: str
+
+    .. py:attribute:: cls_providers
+
+        Read-only dictionary of current catalog providers.
+
+        :type: dict[str, :py:class:`dependency_injector.providers.Provider`]
+
+    .. py:attribute:: inherited_providers
+
+        Read-only dictionary of inherited providers.
+
+        :type: dict[str, :py:class:`dependency_injector.providers.Provider`]
+
+    .. py:attribute:: providers
+
+        Read-only dictionary of all providers.
+
+        :type: dict[str, :py:class:`dependency_injector.providers.Provider`]
+
+    .. py:attribute:: overridden_by
+
+        Tuple of overriding catalogs.
+
+        :type: tuple[:py:class:`DeclarativeCatalog` |
+                    :py:class:`DynamicCatalog`]
+
+    .. py:attribute:: is_overridden
+
+        Read-only property that is set to ``True`` if catalog is overridden.
+
+        :type: bool
+
+    .. py:attribute:: is_overridden
+
+        Read-only reference to the last overriding catalog, if any.
+
+        :type: :py:class:`DeclarativeCatalog` | :py:class:`DynamicCatalog` |
+               None
+
+    .. py:attribute:: provider_type
+
+        If provider type is defined, :py:class:`DeclarativeCatalog` checks that
+        all of its providers are instances of
+        :py:attr:`DeclarativeCatalog.provider_type`.
+
+        :type: type | None
+    """
+
+    Bundle = CatalogBundle
+
+    name = str()
+
+    cls_providers = dict()
+    inherited_providers = dict()
+    providers = dict()
+
+    overridden_by = tuple()
+    is_overridden = bool
+    last_overriding = None
+
+    provider_type = None
+
+    _catalog = DynamicCatalog
+
+    __IS_CATALOG__ = True
+
+    @classmethod
+    def is_bundle_owner(cls, bundle):
+        """Check if catalog is bundle owner.
+
+        :param bundle: Catalog's bundle instance.
+        :type bundle: :py:class:`CatalogBundle`
+
+        :rtype: bool
+        """
+        return cls._catalog.is_bundle_owner(bundle)
+
+    @classmethod
+    def get_provider_bind_name(cls, provider):
+        """Return provider's name in catalog.
+
+        :param provider: Provider instance.
+        :type provider: :py:class:`dependency_injector.providers.Provider`
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+
+        :return: Provider's name.
+        :rtype: str
+        """
+        return cls._catalog.get_provider_bind_name(provider)
+
+    @classmethod
+    def is_provider_bound(cls, provider):
+        """Check if provider is bound to the catalog.
+
+        :param provider: Provider instance.
+        :type provider: :py:class:`dependency_injector.providers.Provider`
+
+        :rtype: bool
+        """
+        return cls._catalog.is_provider_bound(provider)
+
+    @classmethod
+    def filter(cls, provider_type):
+        """Return dictionary of providers, that are instance of provided type.
+
+        :param provider_type: Provider's type.
+        :type provider_type: :py:class:`dependency_injector.providers.Provider`
+
+        :rtype: dict[str, :py:class:`dependency_injector.providers.Provider`]
+        """
+        return cls._catalog.filter(provider_type)
+
+    @classmethod
+    def override(cls, overriding):
+        """Override current catalog providers by overriding catalog providers.
+
+        :param overriding: Overriding catalog.
+        :type overriding: :py:class:`DeclarativeCatalog` |
+                          :py:class:`DynamicCatalog`
+
+        :raise: :py:exc:`dependency_injector.errors.Error` if trying to
+                override catalog by itself or its subclasses
+
+        :rtype: None
+        """
+        if is_declarative_catalog(overriding) and issubclass(cls, overriding):
+            raise Error('Catalog {0} could not be overridden '
+                        'with itself or its subclasses'.format(cls))
+        return cls._catalog.override(overriding)
+
+    @classmethod
+    def reset_last_overriding(cls):
+        """Reset last overriding catalog.
+
+        :rtype: None
+        """
+        cls._catalog.reset_last_overriding()
+
+    @classmethod
+    def reset_override(cls):
+        """Reset all overridings for all catalog providers.
+
+        :rtype: None
+        """
+        cls._catalog.reset_override()
+
+    @classmethod
+    def get_provider(cls, name):
+        """Return provider with specified name or raise an error.
+
+        :param name: Provider's name.
+        :type name: str
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+
+        :return: Provider with specified name.
+        :rtype: :py:class:`dependency_injector.providers.Provider`
+        """
+        return cls._catalog.get_provider(name)
+
+    get = get_provider  # Backward compatibility for versions < 0.11.*
+
+    @classmethod
+    def bind_provider(cls, name, provider):
+        """Bind provider to catalog with specified name.
+
+        :param name: Name of the provider.
+        :type name: str
+
+        :param provider: Provider instance.
+        :type provider: :py:class:`dependency_injector.providers.Provider`
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+
+        :rtype: None
+        """
+        setattr(cls, name, provider)
+
+    @classmethod
+    def bind_providers(cls, providers):
+        """Bind providers dictionary to catalog.
+
+        :param providers: Dictionary of providers, where key is a name
+            and value is a provider.
+        :type providers:
+            dict[str, :py:class:`dependency_injector.providers.Provider`]
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+
+        :rtype: None
+        """
+        for name, provider in six.iteritems(providers):
+            setattr(cls, name, provider)
+
+    @classmethod
+    def has_provider(cls, name):
+        """Check if there is provider with certain name.
+
+        :param name: Provider's name.
+        :type name: str
+
+        :rtype: bool
+        """
+        return hasattr(cls, name)
+
+    has = has_provider  # Backward compatibility for versions < 0.11.*
+
+    @classmethod
+    def unbind_provider(cls, name):
+        """Remove provider binding.
+
+        :param name: Provider's name.
+        :type name: str
+
+        :rtype: None
+        """
+        delattr(cls, name)
+
+    @classmethod
+    def __getattr__(cls, name):  # pragma: no cover
+        """Return provider with specified name or raise en error.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :raise: :py:exc:`dependency_injector.errors.UndefinedProviderError`
+        """
+        raise NotImplementedError('Implementated in metaclass')
+
+    @classmethod
+    def __setattr__(cls, name, value):  # pragma: no cover
+        """Handle setting of catalog attributes.
+
+        Setting of attributes works as usual, but if value of attribute is
+        provider, this provider will be bound to catalog.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :param value: Attribute's value.
+        :type value: :py:class:`dependency_injector.providers.Provider` |
+                     object
+
+        :rtype: None
+        """
+        raise NotImplementedError('Implementated in metaclass')
+
+    @classmethod
+    def __delattr__(cls, name):  # pragma: no cover
+        """Handle deleting of catalog attibute.
+
+        Deleting of attributes works as usual, but if value of attribute is
+        provider, this provider will be unbound from catalog.
+
+        :param name: Attribute's name.
+        :type name: str
+
+        :rtype: None
+        """
+        raise NotImplementedError('Implementated in metaclass')
+
+
+# Backward compatibility for versions < 0.11.*
+AbstractCatalog = DeclarativeCatalog
+
+
+def override(catalog):
+    """:py:class:`DeclarativeCatalog` overriding decorator.
+
+    :param catalog: Catalog that should be overridden by decorated catalog.
+    :type catalog: :py:class:`DeclarativeCatalog` | :py:class:`DynamicCatalog`
+
+    :return: Declarative catalog's overriding decorator.
+    :rtype: callable(:py:class:`DeclarativeCatalog`)
+    """
+    def decorator(overriding_catalog):
+        """Overriding decorator."""
+        catalog.override(overriding_catalog)
+        return overriding_catalog
+    return decorator

dependency_injector/errors.py

@@ -0,0 +1,22 @@
+"""Errors module."""
+
+
+class Error(Exception):
+    """Base error.
+
+    All dependency injector errors extend this error class.
+    """
+
+
+class UndefinedProviderError(Error, AttributeError):
+    """Undefined provider error.
+
+    This error is used when provider could not be defined, for example:
+
+        - provider with certain name could not be defined
+        - catalog's name of the certain provider could not be defined
+        - etc...
+
+    Also this error extends standard :py:class:`AttributeError`. This gives
+    possibility to use it correctly with ``__getattr__()``.
+    """

dependency_injector/injections.py

@@ -0,0 +1,285 @@
+"""Injections module."""
+
+import sys
+import itertools
+
+import six
+
+from .utils import is_provider
+from .utils import is_injection
+from .utils import is_arg_injection
+from .utils import is_kwarg_injection
+
+from .errors import Error
+
+
+_IS_PYPY = '__pypy__' in sys.builtin_module_names
+if _IS_PYPY or six.PY3:  # pragma: no cover
+    _OBJECT_INIT = six.get_unbound_function(object.__init__)
+else:  # pragma: no cover
+    _OBJECT_INIT = None
+
+
+@six.python_2_unicode_compatible
+class Injection(object):
+    """Base injection class.
+
+    All injections extend this class.
+
+    .. py:attribute:: injectable
+
+        Injectable value, could be provider or any other object.
+
+        :type: object | :py:class:`dependency_injector.providers.Provider`
+
+    .. py:attribute:: injectable_is_provider
+
+        Flag that is set to ``True`` if injectable value is provider.
+
+        :type: bool
+    """
+
+    __IS_INJECTION__ = True
+    __slots__ = ('injectable', 'injectable_is_provider')
+
+    def __init__(self, injectable):
+        """Initializer.
+
+        :param injectable: Injectable value, could be provider or any
+                           other object.
+        :type injectable: object |
+                          :py:class:`dependency_injector.providers.Provider`
+        """
+        self.injectable = injectable
+        self.injectable_is_provider = is_provider(injectable)
+        super(Injection, self).__init__()
+
+    @property
+    def value(self):
+        """Read-only property that represents injectable value.
+
+        Injectable values are provided "as is", except of providers
+        (subclasses of :py:class:`dependency_injector.providers.Provider`).
+        Providers will be called every time, when injection needs to be done.
+
+        :rtype: object
+        """
+        if self.injectable_is_provider:
+            return self.injectable()
+        return self.injectable
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return '<{injection}({injectable}) at {address}>'.format(
+            injection='.'.join((self.__class__.__module__,
+                                self.__class__.__name__)),
+            injectable=repr(self.injectable),
+            address=hex(id(self)))
+
+    __repr__ = __str__
+
+
+class Arg(Injection):
+    """Positional argument injection."""
+
+    __IS_ARG_INJECTION__ = True
+
+
+@six.python_2_unicode_compatible
+class _NamedInjection(Injection):
+    """Base class of named injections.
+
+    .. py:attribute:: name
+
+        Injection target's name (keyword argument, attribute, method).
+
+        :type: str
+    """
+
+    __slots__ = ('name',)
+
+    def __init__(self, name, injectable):
+        """Initializer.
+
+        :param name: Injection target's name.
+        :type name: str
+
+        :param injectable: Injectable value, could be provider or any
+                           other object.
+        :type injectable: object |
+                          :py:class:`dependency_injector.providers.Provider`
+        """
+        self.name = name
+        super(_NamedInjection, self).__init__(injectable)
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return '<{injection}({name}, {injectable}) at {address}>'.format(
+            name=repr(self.name),
+            injection='.'.join((self.__class__.__module__,
+                                self.__class__.__name__)),
+            injectable=repr(self.injectable),
+            address=hex(id(self)))
+
+    __repr__ = __str__
+
+
+class KwArg(_NamedInjection):
+    """Keyword argument injection.
+
+    .. py:attribute:: name
+
+        Keyword argument's name.
+
+        :type: str
+    """
+
+    __IS_KWARG_INJECTION__ = True
+
+
+class Attribute(_NamedInjection):
+    """Attribute injection.
+
+    .. py:attribute:: name
+
+        Attribute's name.
+
+        :type: str
+    """
+
+    __IS_ATTRIBUTE_INJECTION__ = True
+
+
+class Method(_NamedInjection):
+    """Method injection.
+
+    .. py:attribute:: name
+
+        Method's name.
+
+        :type: str
+    """
+
+    __IS_METHOD_INJECTION__ = True
+
+
+def inject(*args, **kwargs):
+    """Dependency injection decorator.
+
+    :py:func:`inject` decorator can be used for making inline dependency
+    injections. It patches decorated callable in such way that dependency
+    injection will be done during every call of decorated callable.
+
+    :py:func:`inject` decorator supports different syntaxes of passing
+    injections:
+
+    .. code-block:: python
+
+        # Positional arguments injections (simplified syntax):
+        @inject(1, 2)
+        def some_function(arg1, arg2):
+            pass
+
+        # Keyword arguments injections (simplified syntax):
+        @inject(arg1=1)
+        @inject(arg2=2)
+        def some_function(arg1, arg2):
+            pass
+
+        # Keyword arguments injections (extended (full) syntax):
+        @inject(KwArg('arg1', 1))
+        @inject(KwArg('arg2', 2))
+        def some_function(arg1, arg2):
+            pass
+
+        # Keyword arguments injections into class init (simplified syntax):
+        @inject(arg1=1)
+        @inject(arg2=2)
+        class SomeClass(object):
+
+            def __init__(self, arg1, arg2):
+                pass
+
+    :param args: Tuple of context positional arguments.
+    :type args: tuple[object]
+
+    :param kwargs: Dictionary of context keyword arguments.
+    :type kwargs: dict[str, object]
+
+    :return: Class / callable decorator
+    :rtype: (callable) -> (type | callable)
+    """
+    arg_injections = _parse_args_injections(args)
+    kwarg_injections = _parse_kwargs_injections(args, kwargs)
+
+    def decorator(callback_or_cls):
+        """Dependency injection decorator."""
+        if isinstance(callback_or_cls, six.class_types):
+            cls = callback_or_cls
+            try:
+                cls_init = six.get_unbound_function(cls.__init__)
+                assert cls_init is not _OBJECT_INIT
+            except (AttributeError, AssertionError):
+                raise Error(
+                    'Class {0}.{1} has no __init__() '.format(cls.__module__,
+                                                              cls.__name__) +
+                    'method and could not be decorated with @inject decorator')
+            cls.__init__ = decorator(cls_init)
+            return cls
+
+        callback = callback_or_cls
+        if hasattr(callback, 'injections'):
+            callback.args += arg_injections
+            callback.kwargs += kwarg_injections
+            callback.injections += arg_injections + kwarg_injections
+            return callback
+
+        @six.wraps(callback)
+        def decorated(*args, **kwargs):
+            """Decorated with dependency injection callback."""
+            return callback(*_get_injectable_args(args, decorated.args),
+                            **_get_injectable_kwargs(kwargs, decorated.kwargs))
+
+        decorated.args = arg_injections
+        decorated.kwargs = kwarg_injections
+        decorated.injections = arg_injections + kwarg_injections
+
+        return decorated
+    return decorator
+
+
+def _parse_args_injections(args):
+    """Parse positional argument injections according to current syntax."""
+    return tuple(Arg(arg) if not is_injection(arg) else arg
+                 for arg in args
+                 if not is_injection(arg) or is_arg_injection(arg))
+
+
+def _parse_kwargs_injections(args, kwargs):
+    """Parse keyword argument injections according to current syntax."""
+    kwarg_injections = tuple(injection
+                             for injection in args
+                             if is_kwarg_injection(injection))
+    if kwargs:
+        kwarg_injections += tuple(KwArg(name, value)
+                                  for name, value in six.iteritems(kwargs))
+    return kwarg_injections
+
+
+def _get_injectable_args(context_args, arg_injections):
+    """Return tuple of positional arguments, patched with injections."""
+    return itertools.chain((arg.value for arg in arg_injections), context_args)
+
+
+def _get_injectable_kwargs(context_kwargs, kwarg_injections):
+    """Return dictionary of keyword arguments, patched with injections."""
+    injectable_kwargs = dict((kwarg.name, kwarg.value)
+                             for kwarg in kwarg_injections)
+    injectable_kwargs.update(context_kwargs)
+    return injectable_kwargs

dependency_injector/providers.py

@@ -0,0 +1,856 @@
+"""Providers module."""
+
+import six
+
+from .injections import _parse_args_injections
+from .injections import _parse_kwargs_injections
+from .injections import _get_injectable_args
+from .injections import _get_injectable_kwargs
+
+from .utils import ensure_is_provider
+from .utils import is_attribute_injection
+from .utils import is_method_injection
+from .utils import represent_provider
+from .utils import GLOBAL_LOCK
+
+from .errors import Error
+
+
+@six.python_2_unicode_compatible
+class Provider(object):
+    """Base provider class.
+
+    :py:class:`Provider` is callable (implements ``__call__`` method). Every
+    call to provider object returns provided result, according to the providing
+    strategy of particular provider. This ``callable`` functionality is a
+    regular part of providers API and it should be the same for all provider's
+    subclasses.
+
+    Implementation of particular providing strategy should be done in
+    :py:meth:`Provider._provide` of :py:class:`Provider` subclass. Current
+    method is called every time when not overridden provider is called.
+
+    :py:class:`Provider` implements provider overriding logic that should be
+    also common for all providers:
+
+    .. code-block:: python
+
+        provider1 = Factory(SomeClass)
+        provider2 = Factory(ChildSomeClass)
+
+        provider1.override(provider2)
+
+        some_instance = provider1()
+        assert isinstance(some_instance, ChildSomeClass)
+
+    Also :py:class:`Provider` implements helper function for creating its
+    delegates:
+
+    .. code-block:: python
+
+        provider = Factory(object)
+        delegate = provider.delegate()
+
+        delegated = delegate()
+
+        assert provider is delegated
+
+    All providers should extend this class.
+
+    .. py:attribute:: overridden_by
+
+        Tuple of overriding providers, if any.
+
+        :type: tuple[:py:class:`Provider`] | None
+    """
+
+    __IS_PROVIDER__ = True
+    __slots__ = ('overridden_by',)
+
+    def __init__(self):
+        """Initializer."""
+        self.overridden_by = None
+        super(Provider, self).__init__()
+
+    def __call__(self, *args, **kwargs):
+        """Return provided instance.
+
+        Implementation of current method adds ``callable`` functionality for
+        providers API and it should be common for all provider's subclasses.
+        Also this method implements provider overriding logic that is also
+        common for all providers. Implementation of particular providing
+        strategy should be done in :py:meth:`Provider._provide` of
+        :py:class:`Provider` subclass.
+        """
+        if self.overridden_by:
+            return self.last_overriding(*args, **kwargs)
+        return self._provide(*args, **kwargs)
+
+    def _provide(self, *args, **kwargs):
+        """Providing strategy implementation.
+
+        Abstract protected method that implements providing strategy of
+        particular provider. Current method is called every time when not
+        overridden provider is called. Need to be overridden in subclasses.
+        """
+        raise NotImplementedError()
+
+    @property
+    def is_overridden(self):
+        """Read-only property that is set to ``True`` if provider is overridden.
+
+        :rtype: bool
+        """
+        return bool(self.overridden_by)
+
+    @property
+    def last_overriding(self):
+        """Read-only reference to the last overriding provider, if any.
+
+        :type: :py:class:`Provider` | None
+        """
+        return self.overridden_by[-1] if self.overridden_by else None
+
+    def override(self, provider):
+        """Override provider with another provider.
+
+        :param provider: Overriding provider.
+        :type provider: :py:class:`Provider`
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+        """
+        if provider is self:
+            raise Error('Provider {0} could not be overridden '
+                        'with itself'.format(self))
+        if not self.is_overridden:
+            self.overridden_by = (ensure_is_provider(provider),)
+        else:
+            self.overridden_by += (ensure_is_provider(provider),)
+
+    def reset_last_overriding(self):
+        """Reset last overriding provider.
+
+        :raise: :py:exc:`dependency_injector.errors.Error` if provider is not
+                overridden.
+
+        :rtype: None
+        """
+        if not self.overridden_by:
+            raise Error('Provider {0} is not overridden'.format(str(self)))
+        self.overridden_by = self.overridden_by[:-1]
+
+    def reset_override(self):
+        """Reset all overriding providers.
+
+        :rtype: None
+        """
+        self.overridden_by = None
+
+    def delegate(self):
+        """Return provider's delegate.
+
+        :rtype: :py:class:`Delegate`
+        """
+        return Delegate(self)
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return represent_provider(provider=self, provides=None)
+
+    __repr__ = __str__
+
+
+@six.python_2_unicode_compatible
+class Delegate(Provider):
+    """:py:class:`Delegate` provider delegates another provider.
+
+    .. code-block:: python
+
+        provider = Factory(object)
+        delegate = Delegate(provider)
+
+        delegated = delegate()
+
+        assert provider is delegated
+
+    .. py:attribute:: delegated
+
+        Delegated provider.
+
+        :type: :py:class:`Provider`
+    """
+
+    __slots__ = ('delegated',)
+
+    def __init__(self, delegated):
+        """Initializer.
+
+        :provider delegated: Delegated provider.
+        :type delegated: :py:class:`Provider`
+        """
+        self.delegated = ensure_is_provider(delegated)
+        super(Delegate, self).__init__()
+
+    def _provide(self, *args, **kwargs):
+        """Return provided instance.
+
+        :param args: Tuple of context positional arguments.
+        :type args: tuple[object]
+
+        :param kwargs: Dictionary of context keyword arguments.
+        :type kwargs: dict[str, object]
+
+        :rtype: object
+        """
+        return self.delegated
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return represent_provider(provider=self, provides=self.delegated)
+
+    __repr__ = __str__
+
+
+@six.python_2_unicode_compatible
+class Callable(Provider):
+    """:py:class:`Callable` provider calls wrapped callable on every call.
+
+    :py:class:`Callable` provider provides callable that is called on every
+    provider call with some predefined dependency injections.
+
+    :py:class:`Callable` syntax of passing injections is the same like
+    :py:class:`Factory` one:
+
+    .. code-block:: python
+
+        # simplified syntax for passing positional and keyword argument
+        # injections:
+        some_function = Callable(some_function, 'arg1', 'arg2', arg3=3, arg4=4)
+
+        # extended (full) syntax for passing positional and keyword argument
+        # injections:
+        some_function = Callable(some_function,
+                                 injections.Arg(1),
+                                 injections.Arg(2),
+                                 injections.KwArg('some_arg', 3),
+                                 injections.KwArg('other_arg', 4))
+
+    .. py:attribute:: provides
+
+        Provided callable.
+
+        :type: callable
+
+    .. py:attribute:: args
+
+        Tuple of positional argument injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.Arg`]
+
+    .. py:attribute:: kwargs
+
+        Tuple of keyword argument injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.KwArg`]
+    """
+
+    __slots__ = ('provides', 'args', 'kwargs')
+
+    def __init__(self, provides, *args, **kwargs):
+        """Initializer.
+
+        :param provides: Wrapped callable.
+        :type provides: callable
+
+        :param args: Tuple of injections.
+        :type args: tuple
+
+        :param kwargs: Dictionary of injections.
+        :type kwargs: dict
+        """
+        if not callable(provides):
+            raise Error('Provider{0} expected to get callable, '
+                        'got {0}'.format('.'.join((self.__class__.__module__,
+                                                   self.__class__.__name__)),
+                                         provides))
+
+        self.provides = provides
+
+        self.args = _parse_args_injections(args)
+        self.kwargs = _parse_kwargs_injections(args, kwargs)
+
+        super(Callable, self).__init__()
+
+    @property
+    def injections(self):
+        """Read-only tuple of all injections.
+
+        :rtype: tuple[:py:class:`dependency_injector.injections.Injection`]
+        """
+        return self.args + self.kwargs
+
+    def _provide(self, *args, **kwargs):
+        """Return provided instance.
+
+        :param args: Tuple of context positional arguments.
+        :type args: tuple[object]
+
+        :param kwargs: Dictionary of context keyword arguments.
+        :type kwargs: dict[str, object]
+
+        :rtype: object
+        """
+        return self.provides(*_get_injectable_args(args, self.args),
+                             **_get_injectable_kwargs(kwargs, self.kwargs))
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return represent_provider(provider=self, provides=self.provides)
+
+    __repr__ = __str__
+
+
+class Factory(Callable):
+    """:py:class:`Factory` provider creates new instance on every call.
+
+    :py:class:`Factory` supports different syntaxes of passing injections:
+
+    .. code-block:: python
+
+        # simplified syntax for passing positional and keyword argument
+        # injections only:
+        factory = Factory(SomeClass, 'arg1', 'arg2', arg3=3, arg4=4)
+
+        # extended (full) syntax for passing any type of injections:
+        factory = Factory(SomeClass,
+                          injections.Arg(1),
+                          injections.Arg(2),
+                          injections.KwArg('some_arg', 3),
+                          injections.KwArg('other_arg', 4),
+                          injections.Attribute('some_attribute', 5))
+
+    Retrieving of provided instance can be performed via calling
+    :py:class:`Factory` object:
+
+    .. code-block:: python
+
+        factory = Factory(SomeClass,
+                          some_arg1=1,
+                          some_arg2=2)
+        some_object = factory()
+
+    .. py:attribute:: provided_type
+
+        If provided type is defined, :py:class:`Factory` checks that
+        :py:attr:`Factory.provides` is subclass of
+        :py:attr:`Factory.provided_type`.
+
+        :type: type | None
+
+    .. py:attribute:: provides
+
+        Class or other callable that provides object.
+
+        :type: type | callable
+
+    .. py:attribute:: args
+
+        Tuple of positional argument injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.Arg`]
+
+    .. py:attribute:: kwargs
+
+        Tuple of keyword argument injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.KwArg`]
+
+    .. py:attribute:: attributes
+
+        Tuple of attribute injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.Attribute`]
+
+    .. py:attribute:: methods
+
+        Tuple of method injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.Method`]
+    """
+
+    provided_type = None
+
+    __slots__ = ('attributes', 'methods')
+
+    def __init__(self, provides, *args, **kwargs):
+        """Initializer.
+
+        :param provides: Class or other callable that provides object
+            for creation.
+        :type provides: type | callable
+
+        :param args: Tuple of injections.
+        :type args: tuple
+
+        :param kwargs: Dictionary of injections.
+        :type kwargs: dict
+        """
+        if (self.__class__.provided_type and
+                not issubclass(provides, self.__class__.provided_type)):
+            raise Error('{0} can provide only {1} instances'.format(
+                self.__class__, self.__class__.provided_type))
+
+        self.attributes = tuple(injection
+                                for injection in args
+                                if is_attribute_injection(injection))
+
+        self.methods = tuple(injection
+                             for injection in args
+                             if is_method_injection(injection))
+
+        super(Factory, self).__init__(provides, *args, **kwargs)
+
+    @property
+    def injections(self):
+        """Read-only tuple of all injections.
+
+        :rtype: tuple[:py:class:`dependency_injector.injections.Injection`]
+        """
+        return self.args + self.kwargs + self.attributes + self.methods
+
+    def _provide(self, *args, **kwargs):
+        """Return provided instance.
+
+        :param args: Tuple of context positional arguments.
+        :type args: tuple[object]
+
+        :param kwargs: Dictionary of context keyword arguments.
+        :type kwargs: dict[str, object]
+
+        :rtype: object
+        """
+        instance = super(Factory, self)._provide(*args, **kwargs)
+
+        for attribute in self.attributes:
+            setattr(instance, attribute.name, attribute.value)
+        for method in self.methods:
+            getattr(instance, method.name)(method.value)
+
+        return instance
+
+
+class Singleton(Factory):
+    """:py:class:`Singleton` provider returns same instance on every call.
+
+    :py:class:`Singleton` provider creates instance once and return it on every
+    call. :py:class:`Singleton` extends :py:class:`Factory`, so, please follow
+    :py:class:`Factory` documentation to go inside with injections syntax.
+
+    :py:class:`Singleton` is thread-safe and could be used in multithreading
+    environment without any negative impact.
+
+    Retrieving of provided instance can be performed via calling
+    :py:class:`Singleton` object:
+
+    .. code-block:: python
+
+        singleton = Singleton(SomeClass,
+                              some_arg1=1,
+                              some_arg2=2)
+        some_object = singleton()
+
+    .. py:attribute:: provided_type
+
+        If provided type is defined, :py:class:`Factory` checks that
+        :py:attr:`Factory.provides` is subclass of
+        :py:attr:`Factory.provided_type`.
+
+        :type: type | None
+
+    .. py:attribute:: instance
+
+        Read-only reference to singleton's instance.
+
+        :type: object
+
+    .. py:attribute:: provides
+
+        Class or other callable that provides object.
+
+        :type: type | callable
+
+    .. py:attribute:: args
+
+        Tuple of positional argument injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.Arg`]
+
+    .. py:attribute:: kwargs
+
+        Tuple of keyword argument injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.KwArg`]
+
+    .. py:attribute:: attributes
+
+        Tuple of attribute injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.Attribute`]
+
+    .. py:attribute:: methods
+
+        Tuple of method injections.
+
+        :type: tuple[:py:class:`dependency_injector.injections.Method`]
+    """
+
+    __slots__ = ('instance',)
+
+    def __init__(self, provides, *args, **kwargs):
+        """Initializer.
+
+        :param provides: Class or other callable that provides object
+            for creation.
+        :type provides: type | callable
+
+        :param args: Tuple of injections.
+        :type args: tuple
+
+        :param kwargs: Dictionary of injections.
+        :type kwargs: dict
+        """
+        self.instance = None
+        super(Singleton, self).__init__(provides, *args, **kwargs)
+
+    def reset(self):
+        """Reset cached instance, if any.
+
+        :rtype: None
+        """
+        self.instance = None
+
+    def _provide(self, *args, **kwargs):
+        """Return provided instance.
+
+        :param args: Tuple of context positional arguments.
+        :type args: tuple[object]
+
+        :param kwargs: Dictionary of context keyword arguments.
+        :type kwargs: dict[str, object]
+
+        :rtype: object
+        """
+        with GLOBAL_LOCK:
+            if not self.instance:
+                self.instance = super(Singleton, self)._provide(*args,
+                                                                **kwargs)
+        return self.instance
+
+
+@six.python_2_unicode_compatible
+class ExternalDependency(Provider):
+    """:py:class:`ExternalDependency` provider describes dependency interface.
+
+    This provider is used for description of dependency interface. That might
+    be useful when dependency could be provided in the client's code only,
+    but it's interface is known. Such situations could happen when required
+    dependency has non-determenistic list of dependencies itself.
+
+    .. code-block:: python
+
+        database_provider = ExternalDependency(sqlite3.dbapi2.Connection)
+        database_provider.override(Factory(sqlite3.connect, ':memory:'))
+
+        database = database_provider()
+
+    .. py:attribute:: instance_of
+
+        Class of required dependency.
+
+        :type: type
+    """
+
+    __slots__ = ('instance_of',)
+
+    def __init__(self, instance_of):
+        """Initializer."""
+        if not isinstance(instance_of, six.class_types):
+            raise Error('ExternalDependency provider expects to get class, ' +
+                        'got {0} instead'.format(str(instance_of)))
+        self.instance_of = instance_of
+        super(ExternalDependency, self).__init__()
+
+    def __call__(self, *args, **kwargs):
+        """Return provided instance.
+
+        :param args: Tuple of context positional arguments.
+        :type args: tuple[object]
+
+        :param kwargs: Dictionary of context keyword arguments.
+        :type kwargs: dict[str, object]
+
+        :raise: :py:exc:`dependency_injector.errors.Error`
+
+        :rtype: object
+        """
+        if not self.is_overridden:
+            raise Error('Dependency is not defined')
+
+        instance = self.last_overriding(*args, **kwargs)
+
+        if not isinstance(instance, self.instance_of):
+            raise Error('{0} is not an '.format(instance) +
+                        'instance of {0}'.format(self.instance_of))
+
+        return instance
+
+    def provided_by(self, provider):
+        """Set external dependency provider.
+
+        :param provider: Provider that provides required dependency.
+        :type provider: :py:class:`Provider`
+
+        :rtype: None
+        """
+        return self.override(provider)
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return represent_provider(provider=self, provides=self.instance_of)
+
+    __repr__ = __str__
+
+
+@six.python_2_unicode_compatible
+class Static(Provider):
+    """:py:class:`Static` provider returns provided instance "as is".
+
+    :py:class:`Static` provider is base implementation that provides exactly
+    the same as it got on input.
+
+    .. py:attribute:: provides
+
+        Value that have to be provided.
+
+        :type: object
+    """
+
+    __slots__ = ('provides',)
+
+    def __init__(self, provides):
+        """Initializer.
+
+        :param provides: Value that have to be provided.
+        :type provides: object
+        """
+        self.provides = provides
+        super(Static, self).__init__()
+
+    def _provide(self, *args, **kwargs):
+        """Return provided instance.
+
+        :param args: Tuple of context positional arguments.
+        :type args: tuple[object]
+
+        :param kwargs: Dictionary of context keyword arguments.
+        :type kwargs: dict[str, object]
+
+        :rtype: object
+        """
+        return self.provides
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return represent_provider(provider=self, provides=self.provides)
+
+    __repr__ = __str__
+
+
+StaticProvider = Static
+# Backward compatibility for versions < 1.11.1
+
+
+class Class(Static):
+    """:py:class:`Class` returns provided class "as is".
+
+    .. code-block:: python
+
+        cls_provider = Class(object)
+        object_cls = cls_provider()
+    """
+
+
+class Object(Static):
+    """:py:class:`Object` returns provided object "as is".
+
+    .. code-block:: python
+
+        object_provider = Object(object())
+        object_instance = object_provider()
+    """
+
+
+class Function(Static):
+    """:py:class:`Function` returns provided function "as is".
+
+    .. code-block:: python
+
+        function_provider = Function(len)
+        len_function = function_provider()
+    """
+
+
+class Value(Static):
+    """:py:class:`Value` returns provided value "as is".
+
+    .. code-block:: python
+
+        value_provider = Value(31337)
+        value = value_provider()
+    """
+
+
+@six.python_2_unicode_compatible
+class Config(Provider):
+    """:py:class:`Config` provider provide dict values.
+
+    :py:class:`Config` provider creates :py:class:`ChildConfig` objects for all
+    undefined attribute calls. It makes possible to create deferred config
+    value providers. It might be useful in cases where it is needed to
+    define / pass some configuration in declarative manner, while
+    configuration values will be loaded / updated in application's runtime.
+    """
+
+    __slots__ = ('value',)
+
+    def __init__(self, value=None):
+        """Initializer.
+
+        :param value: Configuration dictionary.
+        :type value: dict[str, object]
+        """
+        if not value:
+            value = dict()
+        self.value = value
+        super(Config, self).__init__()
+
+    def __getattr__(self, item):
+        """Return instance of deferred config.
+
+        :param item: Name of configuration option or section.
+        :type item: str
+
+        :rtype: :py:class:`ChildConfig`
+        """
+        return ChildConfig(parents=(item,), root_config=self)
+
+    def _provide(self, paths=None):
+        """Return provided instance.
+
+        :param paths: Tuple of pieces of configuration option / section path.
+        :type args: tuple[str]
+
+        :rtype: object
+        """
+        value = self.value
+        if paths:
+            for path in paths:
+                try:
+                    value = value[path]
+                except KeyError:
+                    raise Error('Config key '
+                                '"{0}" is undefined'.format('.'.join(paths)))
+        return value
+
+    def update_from(self, value):
+        """Update current value from another one.
+
+        :param value: Configuration dictionary.
+        :type value: dict[str, object]
+
+        :rtype: None
+        """
+        self.value.update(value)
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return represent_provider(provider=self, provides=self.value)
+
+    __repr__ = __str__
+
+
+@six.python_2_unicode_compatible
+class ChildConfig(Provider):
+    """:py:class:`ChildConfig` provider provides value from :py:class:`Config`.
+
+    :py:class:`ChildConfig` provides value from the root config object
+    according to the current path in the config tree.
+    """
+
+    __slots__ = ('parents', 'root_config')
+
+    def __init__(self, parents, root_config):
+        """Initializer.
+
+        :param parents: Tuple of pieces of configuration option / section
+            parent path.
+        :type parents: tuple[str]
+
+        :param root_config: Root configuration object.
+        :type root_config: :py:class:`Config`
+        """
+        self.parents = parents
+        self.root_config = root_config
+        super(ChildConfig, self).__init__()
+
+    def __getattr__(self, item):
+        """Return instance of deferred config.
+
+        :param item: Name of configuration option or section.
+        :type item: str
+
+        :rtype: :py:class:`ChildConfig`
+        """
+        return ChildConfig(parents=self.parents + (item,),
+                           root_config=self.root_config)
+
+    def _provide(self, *args, **kwargs):
+        """Return provided instance.
+
+        :param args: Tuple of context positional arguments.
+        :type args: tuple[object]
+
+        :param kwargs: Dictionary of context keyword arguments.
+        :type kwargs: dict[str, object]
+
+        :rtype: object
+        """
+        return self.root_config(self.parents)
+
+    def __str__(self):
+        """Return string representation of provider.
+
+        :rtype: str
+        """
+        return represent_provider(provider=self,
+                                  provides='.'.join(self.parents))
+
+    __repr__ = __str__

dependency_injector/utils.py

@@ -0,0 +1,209 @@
+"""Utils module."""
+
+import threading
+
+import six
+
+from .errors import Error
+
+
+GLOBAL_LOCK = threading.RLock()
+"""Dependency injector global reentrant lock.
+
+:type: :py:class:`threading.RLock`
+"""
+
+
+def is_provider(instance):
+    """Check if instance is provider instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (not isinstance(instance, six.class_types) and
+            hasattr(instance, '__IS_PROVIDER__') and
+            getattr(instance, '__IS_PROVIDER__') is True)
+
+
+def ensure_is_provider(instance):
+    """Check if instance is provider instance and return it.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :raise: :py:exc:`dependency_injector.errors.Error` if provided instance is
+            not provider.
+
+    :rtype: :py:class:`dependency_injector.providers.Provider`
+    """
+    if not is_provider(instance):
+        raise Error('Expected provider instance, '
+                    'got {0}'.format(str(instance)))
+    return instance
+
+
+def is_injection(instance):
+    """Check if instance is injection instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (not isinstance(instance, six.class_types) and
+            hasattr(instance, '__IS_INJECTION__') and
+            getattr(instance, '__IS_INJECTION__') is True)
+
+
+def ensure_is_injection(instance):
+    """Check if instance is injection instance and return it.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :raise: :py:exc:`dependency_injector.errors.Error` if provided instance is
+            not injection.
+
+    :rtype: :py:class:`dependency_injector.injections.Injection`
+    """
+    if not is_injection(instance):
+        raise Error('Expected injection instance, '
+                    'got {0}'.format(str(instance)))
+    return instance
+
+
+def is_arg_injection(instance):
+    """Check if instance is positional argument injection instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (not isinstance(instance, six.class_types) and
+            hasattr(instance, '__IS_ARG_INJECTION__') and
+            getattr(instance, '__IS_ARG_INJECTION__', False) is True)
+
+
+def is_kwarg_injection(instance):
+    """Check if instance is keyword argument injection instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (not isinstance(instance, six.class_types) and
+            hasattr(instance, '__IS_KWARG_INJECTION__') and
+            getattr(instance, '__IS_KWARG_INJECTION__', False) is True)
+
+
+def is_attribute_injection(instance):
+    """Check if instance is attribute injection instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (not isinstance(instance, six.class_types) and
+            hasattr(instance, '__IS_ATTRIBUTE_INJECTION__') and
+            getattr(instance, '__IS_ATTRIBUTE_INJECTION__', False) is True)
+
+
+def is_method_injection(instance):
+    """Check if instance is method injection instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (not isinstance(instance, six.class_types) and
+            hasattr(instance, '__IS_METHOD_INJECTION__') and
+            getattr(instance, '__IS_METHOD_INJECTION__', False) is True)
+
+
+def is_catalog(instance):
+    """Check if instance is catalog instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (hasattr(instance, '__IS_CATALOG__') and
+            getattr(instance, '__IS_CATALOG__', False) is True)
+
+
+def is_dynamic_catalog(instance):
+    """Check if instance is dynamic catalog instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (not isinstance(instance, six.class_types) and is_catalog(instance))
+
+
+def is_declarative_catalog(instance):
+    """Check if instance is declarative catalog instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (isinstance(instance, six.class_types) and is_catalog(instance))
+
+
+def is_catalog_bundle(instance):
+    """Check if instance is catalog bundle instance.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :rtype: bool
+    """
+    return (not isinstance(instance, six.class_types) and
+            hasattr(instance, '__IS_CATALOG_BUNDLE__') and
+            getattr(instance, '__IS_CATALOG_BUNDLE__', False) is True)
+
+
+def ensure_is_catalog_bundle(instance):
+    """Check if instance is catalog bundle instance and return it.
+
+    :param instance: Instance to be checked.
+    :type instance: object
+
+    :raise: :py:exc:`dependency_injector.errors.Error` if provided instance
+            is not catalog bundle.
+
+    :rtype: :py:class:`dependency_injector.catalogs.CatalogBundle`
+    """
+    if not is_catalog_bundle(instance):
+        raise Error('Expected catalog bundle instance, '
+                    'got {0}'.format(str(instance)))
+    return instance
+
+
+def represent_provider(provider, provides):
+    """Return string representation of provider.
+
+    :param provider: Provider object
+    :type provider: :py:class:`dependency_injector.providers.Provider`
+
+    :param provides: Object that provider provides
+    :type provider: object
+
+    :return: String representation of provider
+    :rtype: str
+    """
+    return '<{provider}({provides}) at {address}>'.format(
+        provider='.'.join((provider.__class__.__module__,
+                           provider.__class__.__name__)),
+        provides=repr(provides) if provides is not None else '',
+        address=hex(id(provider)))

docs/_static/custom.css

@@ -1,9 +0,0 @@
-.no-border {
-    border: 0 !important;
-    box-shadow: none !important;
-    -webkit-box-shadow: none !important;
-}
-.no-border td {
-    border: 0px !important;
-    padding: 0px 10px 0px 0px !important;
-}

docs/_static/sponsor.html

@@ -1 +0,0 @@
-<iframe src="https://github.com/sponsors/rmk135/button" title="Sponsor Dependency Injector" height="32" width="114" style="border: 0; border-radius: 6px;"></iframe>

docs/advanced_usage/index.rst

@@ -0,0 +1,63 @@
+Advanced usage
+==============
+
+Current section of documentation describes advanced usage of 
+*Dependency Injector*.
+
+@inject decorator
+-----------------
+
+.. currentmodule:: dependency_injector.injections
+
+:py:func:`inject` decorator is a part of 
+:py:mod:`dependency_injector.injections` module.
+
+:py:func:`inject` decorator can be used for making *inline* dependency 
+injections.  It *patches* decorated callable in such way that dependency 
+injection will be done during every call of decorated callable.
+
+:py:func:`inject` takes a various number of positional and keyword arguments 
+that are used as decorated callable injections. Every time, when 
+:py:func:`inject` is called, positional and keyword argument injections would 
+be passed as an callable arguments.
+
+Such behaviour is very similar to the standard Python ``functools.partial`` 
+object, except of one thing: all injectable values are provided 
+*"as is"*, except of providers (subclasses of 
+:py:class:`dependency_injector.providers.Provider`). Providers 
+will be called every time, when injection needs to be done. For example, 
+if injectable value of injection is a 
+:py:class:`dependency_injector.providers.Factory`, it will provide new one 
+instance (as a result of its call) every time, when injection needs to be done.
+
+:py:func:`inject` behaviour with context positional and keyword arguments is 
+very like a standard Python ``functools.partial``:
+
+- Positional context arguments will be appended after :py:func:`inject` 
+  positional injections.
+- Keyword context arguments have priority on :py:func:`inject` keyword 
+  injections and will be merged over them.
+
+Example:
+
+.. literalinclude:: ../../examples/advanced_usage/inject_simple.py
+   :language: python
+
+Example of usage :py:func:`inject` decorator with Flask:
+
+.. literalinclude:: ../../examples/advanced_usage/inject_flask.py
+   :language: python
+
+
+@inject decorator with classes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:py:func:`inject` could be applied for classes. In such case, it will look for 
+class ``__init__()`` method and pass injection to it. If decorated class has 
+no ``__init__()`` method, appropriate 
+:py:exc:`dependency_injector.errors.Error` will be raised.
+
+Example of usage :py:func:`inject` with Flask class-based view:
+
+.. literalinclude:: ../../examples/advanced_usage/inject_flask_class_based.py
+   :language: python

docs/api/asgi-lifespan.rst

@@ -1,9 +0,0 @@
-dependency_injector.ext.starlette
-=================================
-
-.. automodule:: dependency_injector.ext.starlette
-   :members:
-   :inherited-members:
-   :show-inheritance:
-
-.. disqus::

docs/api/catalogs.rst

@@ -0,0 +1,6 @@
+``dependency_injector.catalogs``
+--------------------------------
+
+.. automodule:: dependency_injector.catalogs
+   :members:
+   :special-members:

docs/api/containers.rst

@@ -1,9 +0,0 @@
-dependency_injector.containers
-==============================
-
-.. automodule:: dependency_injector.containers
-   :members:
-   :inherited-members:
-   :show-inheritance:
-
-.. disqus::

docs/api/errors.rst

@@ -1,8 +1,5 @@
-dependency_injector.errors
+``dependency_injector.errors``
-==========================
+------------------------------
 
 .. automodule:: dependency_injector.errors
    :members:
-
-
-.. disqus::

docs/api/index.rst

@@ -2,11 +2,11 @@ API Documentation
 =================
 
 ..  toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   top-level
+    top_level
-   providers
+    providers
-   containers
+    injections
-   wiring
+    catalogs
-   errors
+    utils
-   asgi-lifespan
+    errors

docs/api/injections.rst

@@ -0,0 +1,6 @@
+``dependency_injector.injections``
+----------------------------------
+
+.. automodule:: dependency_injector.injections
+   :members:
+   :inherited-members:

docs/api/providers.rst

@@ -1,10 +1,7 @@
-dependency_injector.providers
+``dependency_injector.providers``
-=============================
+---------------------------------
 
 .. automodule:: dependency_injector.providers
    :members:
    :inherited-members:
    :show-inheritance:
-
-
-.. disqus::

docs/api/top-level.rst

@@ -1,8 +0,0 @@
-dependency_injector
-===================
-
-.. automodule:: dependency_injector
-   :members: __version__
-
-
-.. disqus::

docs/api/top_level.rst

@@ -0,0 +1,5 @@
+``dependency_injector``
+-----------------------
+
+.. automodule:: dependency_injector
+   :members: VERSION

docs/api/utils.rst

@@ -0,0 +1,5 @@
+``dependency_injector.utils``
+-----------------------------
+
+.. automodule:: dependency_injector.utils
+   :members:

docs/api/wiring.rst

@@ -1,7 +0,0 @@
-dependency_injector.wiring
-=============================
-
-.. automodule:: dependency_injector.wiring
-   :members:
-
-.. disqus::

docs/catalogs/bundles.rst

@@ -0,0 +1,60 @@
+Catalog provider bundles
+------------------------
+
+.. currentmodule:: dependency_injector.catalogs
+
+:py:class:`CatalogBundle` is a frozen, limited collection of catalog 
+providers. While catalog could be used as a centralized place for 
+particular providers group, such bundles of catalog providers can be used 
+for creating several frozen, limited scopes that could be passed to different 
+subsystems.
+
+:py:class:`CatalogBundle` has API's parity with catalogs
+(:py:class:`DeclarativeCatalog` or :py:class:`DynamicCatalog`) in terms of 
+retrieving the providers, but it is "frozen" in terms of modification 
+provider's list.
+
+:py:class:`CatalogBundle` is considered to be dependable on catalogs 
+(:py:class:`DeclarativeCatalog` or :py:class:`DynamicCatalog`) entity by 
+its design.
+
+Each catalog (:py:class:`DeclarativeCatalog` or :py:class:`DynamicCatalog`) 
+has a reference to its bundle class - :py:attr:`DeclarativeCatalog.Bundle` 
+(or :py:attr:`DynamicCatalog.Bundle` consequently). For example, subclass of 
+:py:class:`CatalogBundle` for some concrete declarative catalog 
+``SomeCatalog`` could be reached as ``SomeCatalog.Bundle``. 
+
+:py:class:`CatalogBundle` expects to get the list of its catalog providers
+as positional arguments and will limit the scope of created bundle to this 
+list. 
+
+.. note:: 
+   
+    Some notes about :py:class:`CatalogBundle` design.
+
+    Design and syntax of :py:class:`CatalogBundle` was developed with the idea 
+    of keeping full functionalities of type-hinting and introspection of 
+    modern IDE's. This design came from some practical experience of using 
+    :py:class:`CatalogBundle` and considered to be the most comfortable for 
+    developer.
+
+Example:
+
+.. image:: /images/catalogs/bundles.png
+    :width: 100%
+    :align: center
+
+Listing of `services.py`:
+
+.. literalinclude:: ../../examples/catalogs/bundles/services.py
+   :language: python
+
+Listing of `views.py`:
+
+.. literalinclude:: ../../examples/catalogs/bundles/views.py
+   :language: python
+
+Listing of `catalogs.py`:
+
+.. literalinclude:: ../../examples/catalogs/bundles/catalogs.py
+   :language: python

docs/catalogs/declarative.rst

@@ -0,0 +1,61 @@
+Declarative catalogs
+--------------------
+
+.. currentmodule:: dependency_injector.catalogs
+
+:py:class:`DeclarativeCatalog` is a catalog of providers that could be
+defined in declarative manner. It should cover most of the cases when list
+of providers that would be included in catalog is deterministic (catalog
+will not change its structure in runtime).
+
+Declarative catalogs have to extend base declarative catalog class - 
+:py:class:`dependency_injector.catalogs.DeclarativeCatalog`.
+
+Declarative catalog's providers have to be defined like catalog's class 
+attributes. Every provider in catalog has name. This name should follow 
+``some_provider`` convention, that is standard naming convention for 
+attribute names in Python.
+
+.. note::
+
+    Declarative catalogs have several features that could be useful 
+    for some kind of operations on catalog's providers, please visit API 
+    documentation for getting full list of features - 
+    :py:class:`dependency_injector.catalogs.DeclarativeCatalog`.
+
+.. note::
+
+    It might be useful to add such 
+    ``""":type: dependency_injector.providers.Provider -> Object1"""`` 
+    docstrings just on the next line after provider's definition.  It will 
+    help code analyzing tools and IDE's to understand that variable above 
+    contains some callable object, that returns particular instance as a 
+    result of its call.
+
+Here is an simple example of defining declarative catalog with several 
+factories:
+
+.. image:: /images/catalogs/declarative.png
+    :width: 85%
+    :align: center
+
+.. literalinclude:: ../../examples/catalogs/declarative.py
+   :language: python
+
+Example of declarative catalogs inheritance:
+
+.. image:: /images/catalogs/declarative_inheritance.png
+    :width: 100%
+    :align: center
+
+.. literalinclude:: ../../examples/catalogs/declarative_inheritance.py
+   :language: python
+
+Example of declarative catalog's provider injections:
+
+.. image:: /images/catalogs/declarative_injections.png
+    :width: 100%
+    :align: center
+
+.. literalinclude:: ../../examples/catalogs/declarative_injections.py
+   :language: python

docs/catalogs/dynamic.rst

@@ -0,0 +1,29 @@
+Dynamic catalogs
+----------------
+
+.. currentmodule:: dependency_injector.catalogs
+
+:py:class:`DynamicCatalog` is a catalog of providers that could be created in 
+application's runtime. It should cover most of the cases when list of 
+providers that would be included in catalog is non-deterministic in terms of 
+apllication code (catalog's structure could be determined just after 
+application will be started and will do some initial work, like parsing list 
+of catalog's providers from the configuration).
+
+:py:class:`DeclarativeCatalog` and :py:class:`DynamicCatalog` have 
+100% API parity.
+
+Main difference between :py:class:`DeclarativeCatalog` and 
+:py:class:`DynamicCatalog` is that :py:class:`DeclarativeCatalog` acts on 
+class-level, while :py:class:`DynamicCatalog` do the same on 
+instance-level.
+
+Here is an simple example of defining dynamic catalog with several factories:
+
+.. literalinclude:: ../../examples/catalogs/dynamic.py
+   :language: python
+
+Next one example demonstrates creation and runtime filling of dynamic catalog:
+
+.. literalinclude:: ../../examples/catalogs/dynamic_runtime_creation.py
+   :language: python

docs/catalogs/index.rst

@@ -0,0 +1,28 @@
+Catalogs
+========
+
+Catalogs are collections of providers. Main purpose of catalogs is to group
+providers. 
+
+There are, actually, several popular cases of catalogs usage:
+
+- Grouping of providers from the same architectural layer (for example, 
+  ``Services``, ``Models`` and ``Forms`` catalogs).
+- Grouping of providers from the same functional groups (for example,
+  catalog ``Users``, that contains all functional parts of ``Users``
+  component).
+
+Also, for both of these and some other cases, it might be useful to attach 
+some init / shutdown functionality or something else, that deals with group 
+of providers.
+
+Catalogs module API docs - :py:mod:`dependency_injector.catalogs`.
+
+..  toctree::
+    :maxdepth: 2
+
+    declarative
+    dynamic
+    bundles
+    specialization
+    overriding

docs/catalogs/overriding.rst

@@ -0,0 +1,49 @@
+Overriding of catalogs
+----------------------
+
+.. currentmodule:: dependency_injector.catalogs
+
+Catalogs can be overridden by other catalogs. This, actually, means that 
+all of the providers from overriding catalog will override providers with the 
+same names in overridden catalog.
+
+There are two ways to override :py:class:`DeclarativeCatalog` with another 
+catalog:
+
+- Use :py:meth:`DeclarativeCatalog.override` method.
+- Use :py:func:`override` class decorator.
+
+Example of overriding catalog using :py:meth:`DeclarativeCatalog.override` 
+method:
+
+.. literalinclude:: ../../examples/catalogs/override_declarative.py
+   :language: python
+
+Example of overriding catalog using :py:func:`override` decorator:
+
+.. literalinclude:: ../../examples/catalogs/override_declarative_decorator.py
+   :language: python
+
+Also there are several useful :py:class:`DeclarativeCatalog`  methods and 
+properties that help to work with catalog overridings:
+
+- :py:attr:`DeclarativeCatalog.is_overridden` - read-only property that is set 
+  to ``True`` if catalog is overridden.
+- :py:attr:`DeclarativeCatalog.last_overriding` - read-only reference to 
+  the last overriding catalog, if any.
+- :py:attr:`DeclarativeCatalog.overridden_by` - tuple of all overriding 
+  catalogs.
+- :py:meth:`DeclarativeCatalog.reset_last_overriding()` - reset last 
+  overriding catalog.
+- :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

docs/catalogs/specialization.rst

@@ -0,0 +1,41 @@
+Specialization of catalogs
+--------------------------
+
+.. currentmodule:: dependency_injector.catalogs
+
+:py:class:`DeclarativeCatalog` and :py:class:`DynamicCatalog` could be 
+specialized for any kind of needs via declaring its subclasses. 
+
+One of such `builtin` features is a limitation to 
+:py:class:`DeclarativeCatalog` (and :py:class:`DynamicCatalog`) provider type. 
+
+Next example shows usage of this feature with :py:class:`DeclarativeCatalog` 
+in couple with feature of :py:class:`dependency_injector.providers.Factory` 
+for limitation of its provided type:
+
+
+Listing of `services.py`:
+
+.. literalinclude:: ../../examples/catalogs/declarative_provider_type/services.py
+   :language: python
+
+Listing of `catalog.py`:
+
+.. literalinclude:: ../../examples/catalogs/declarative_provider_type/catalog.py
+   :language: python
+
+Limitation to provider type could be used with :py:class:`DynamicCatalog` 
+as well.
+
+Next example does the same that previous one, but use 
+:py:class:`DynamicCatalog` instead of :py:class:`DeclarativeCatalog`:
+
+Listing of `services.py`:
+
+.. literalinclude:: ../../examples/catalogs/dynamic_provider_type/services.py
+   :language: python
+
+Listing of `catalog.py`:
+
+.. literalinclude:: ../../examples/catalogs/dynamic_provider_type/catalog.py
+   :language: python

docs/conf.py

@@ -15,54 +15,49 @@
 import os
 import re
 import sys
-import alabaster
 
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath(".."))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-#needs_sphinx = "1.0"
+#needs_sphinx = '1.0'
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = [
+extensions = ['sphinx.ext.autodoc']
-    "alabaster",
-    "sphinx.ext.autodoc",
-    "sphinx_disqus.disqus",
-]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
+templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = [".rst", ".md"]
+# source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = "utf-8-sig"
+#source_encoding = 'utf-8-sig'
 
 # The master toctree document.
-master_doc = "index"
+master_doc = 'index'
 
 # General information about the project.
-project = "Dependency Injector"
+project = u'Dependency Injector'
-copyright = "2024, Roman Mogylatov"
+copyright = u'2015, Roman Mogilatov'
-author = "Roman Mogylatov"
+author = u'Roman Mogilatov'
 
-# The version info for the project you"re documenting, acts as replacement for
+# The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
 # Getting version:
-with open("../src/dependency_injector/__init__.py") as init_file:
+with open('../dependency_injector/__init__.py') as init_file:
-    version = re.search("__version__ = \"(.*?)\"", init_file.read()).group(1)
+    version = re.search('VERSION = \'(.*?)\'', init_file.read()).group(1)
 
 # The full version, including alpha/beta/rc tags.
 release = version
@@ -72,23 +67,23 @@ release = version
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = "en"
+language = None
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-#today = ""
+#today = ''
 # Else, today_fmt is used as the format for a strftime call.
-#today_fmt = "%B %d, %Y"
+#today_fmt = '%B %d, %Y'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = ['_build']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
 #default_role = None
 
-# If true, "()" will be appended to :func: etc. cross-reference text.
+# If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
@@ -100,7 +95,7 @@ exclude_patterns = ["_build"]
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
+pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
 #modindex_common_prefix = []
@@ -116,16 +111,15 @@ todo_include_todos = False
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-# html_theme = "sphinx_rtd_theme"
+html_theme = 'default'
-html_theme = "alabaster"
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
-# html_context = {}
+#html_theme_options = {}
 
 # Add any paths that contain custom themes here, relative to this directory.
-html_theme_path = [alabaster.get_path()]
+#html_theme_path = []
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
@@ -141,24 +135,21 @@ html_theme_path = [alabaster.get_path()]
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
 # pixels large.
-html_favicon = "favicon.ico"
+#html_favicon = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
+html_static_path = []
-html_css_files = [
-    "custom.css",
-]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
 #html_extra_path = []
 
-# If not "", a "Last updated on:" timestamp is inserted at every page bottom,
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-#html_last_updated_fmt = "%b %d, %Y"
+#html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -192,50 +183,61 @@ html_css_files = [
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
-#html_use_opensearch = ""
+#html_use_opensearch = ''
 
 # This is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = None
 
 # Language to be used for generating the HTML full-text search index.
 # Sphinx supports the following languages:
-#   "da", "de", "en", "es", "fi", "fr", "hu", "it", "ja"
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja'
-#   "nl", "no", "pt", "ro", "ru", "sv", "tr"
+#   'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr'
-#html_search_language = "en"
+#html_search_language = 'en'
 
 # A dictionary with options for the search language support, empty by default.
-# Now only "ja" uses this config value
+# Now only 'ja' uses this config value
-#html_search_options = {"type": "default"}
+#html_search_options = {'type': 'default'}
 
 # The name of a javascript file (relative to the configuration directory) that
 # implements a search results scorer. If empty, the default will be used.
-#html_search_scorer = "scorer.js"
+#html_search_scorer = 'scorer.js'
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "dependency_injectordoc"
+htmlhelp_basename = 'dependency_injectordoc'
+
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from
+# docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# otherwise, readthedocs.org uses their theme by default, so no need to
+# specify it
 
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {
-# The paper size ("letterpaper" or "a4paper").
+# The paper size ('letterpaper' or 'a4paper').
-#"papersize": "letterpaper",
+#'papersize': 'letterpaper',
 
-# The font size ("10pt", "11pt" or "12pt").
+# The font size ('10pt', '11pt' or '12pt').
-#"pointsize": "10pt",
+#'pointsize': '10pt',
 
 # Additional stuff for the LaTeX preamble.
-#"preamble": "",
+#'preamble': '',
 
 # Latex figure (float) alignment
-#"figure_align": "htbp",
+#'figure_align': 'htbp',
 }
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-  (master_doc, "dependency_injector.tex", u"Dependency Injector Documentation",
+  (master_doc, 'dependency_injector.tex', u'Dependency Injector Documentation',
-   u"Roman Mogylatov", "manual"),
+   u'Roman Mogilatov', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -264,7 +266,7 @@ latex_documents = [
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, "Dependency Injector", u"Dependency Injector Documentation",
+    (master_doc, 'Dependency Injector', u'Dependency Injector Documentation',
      [author], 1)
 ]
 
@@ -278,9 +280,9 @@ man_pages = [
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  (master_doc, "Dependency Injector", u"Dependency Injector Documentation",
+  (master_doc, 'Dependency Injector', u'Dependency Injector Documentation',
-   author, "Dependency Injector", "Dependency injection microframework for Python",
+   author, 'Dependency Injector', 'Dependency management tool for Python projects.',
-   "Miscellaneous"),
+   'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -289,25 +291,10 @@ texinfo_documents = [
 # If false, no module index is generated.
 #texinfo_domain_indices = True
 
-# How to display URL addresses: "footnote", "no", or "inline".
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
-#texinfo_show_urls = "footnote"
+#texinfo_show_urls = 'footnote'
 
-# If true, do not generate a @detailmenu in the "Top" node"s menu.
+# If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
 
-autodoc_member_order = "bysource"
+autodoc_member_order = 'bysource'
-
-disqus_shortname = "python-dependency-injector"
-
-html_theme_options = {
-    "github_user": "ets-labs",
-    "github_repo": "python-dependency-injector",
-    "github_type": "star",
-    "github_button": True,
-    "github_banner": True,
-    "logo": "logo.svg",
-    "description": "Dependency injection framework for Python by Roman Mogylatov",
-    "code_font_size": "10pt",
-    "analytics_id": "UA-67012059-1",
-    "donate_url": "https://github.com/sponsors/rmk135",
-}

docs/containers/check_dependencies.rst

@@ -1,18 +0,0 @@
-.. _check-container-dependencies:
-
-Check container dependencies
-----------------------------
-
-To check container dependencies use method ``.check_dependencies()``.
-
-.. literalinclude:: ../../examples/containers/check_dependencies.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12
-
-Method ``.check_dependencies()`` raises an error if container has any undefined dependencies.
-If all dependencies are provided or have defaults, no error is raised.
-
-See also: :ref:`dependency-provider`.
-
-.. disqus::

docs/containers/copying.rst

@@ -1,23 +0,0 @@
-Container copying
------------------
-
-You can create declarative container copies using ``@containers.copy()`` decorator.
-
-.. literalinclude:: ../../examples/containers/declarative_copy_decorator1.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 18-22
-
-Decorator ``@containers.copy()`` copies providers from source container to destination container.
-Destination container provider will replace source provider, if names match.
-
-Decorator ``@containers.copy()`` helps you when you create derived declarative containers
-from the base one. Base container often keeps default dependencies while derived containers define
-overriding providers. Without ``@containers.copy()`` decorator, overridden providers are available
-in the derived container, but base class dependencies continue to be bound to the base class providers.
-
-.. literalinclude:: ../../examples/containers/declarative_copy_decorator2.py
-   :language: python
-   :lines: 11-
-
-.. disqus::

docs/containers/declarative.rst

@@ -1,72 +0,0 @@
-Declarative container
----------------------
-
-.. currentmodule:: dependency_injector.containers
-
-:py:class:`DeclarativeContainer` is a class-based style of the providers definition.
-
-You create the declarative container subclass, put the providers as attributes and create the
-container instance.
-
-.. literalinclude:: ../../examples/containers/declarative.py
-   :language: python
-   :lines: 3-
-
-The declarative container providers should only be used when you have the container instance.
-Working with the providers of the container on the class level will influence all further
-instances.
-
-The declarative container can not have any methods or any other attributes then providers.
-
-The container class provides next attributes:
-
-- ``providers`` - the dictionary of all the container providers
-- ``cls_providers`` - the dictionary of the container providers of the current container
-- ``inherited_providers`` - the dictionary of all the inherited container providers
-
-.. literalinclude:: ../../examples/containers/declarative_inheritance.py
-   :language: python
-   :lines: 3-
-
-Injections in the declarative container are done the usual way:
-
-.. literalinclude:: ../../examples/containers/declarative_injections.py
-   :language: python
-   :lines: 3-
-
-You can override container providers while creating a container instance:
-
-.. literalinclude:: ../../examples/containers/declarative_override_providers.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 13
-
-Alternatively, you can call ``container.override_providers()`` method when the container instance
-already exists:
-
-.. code-block:: python
-   :emphasize-lines: 3
-
-   container = Container()
-
-   container.override_providers(foo=mock.Mock(Foo), bar=mock.Mock(Bar))
-
-   assert isinstance(container.foo(), mock.Mock)
-   assert isinstance(container.bar(), mock.Mock)
-
-You can also use ``container.override_providers()`` with a context manager to reset
-provided overriding after the context is closed:
-
-.. code-block:: python
-   :emphasize-lines: 3
-
-   container = Container()
-
-   with container.override_providers(foo=mock.Mock(Foo), bar=mock.Mock(Bar)):
-       assert isinstance(container.foo(), mock.Mock)
-       assert isinstance(container.bar(), mock.Mock)
-
-   assert isinstance(container.foo(), Foo)
-   assert isinstance(container.bar(), Bar)
-
-.. disqus::

docs/containers/dynamic.rst

@@ -1,25 +0,0 @@
-Dynamic container
------------------
-
-.. currentmodule:: dependency_injector.containers
-
-:py:class:`DynamicContainer` is a collection of the providers defined in the runtime.
-
-You create the dynamic container instance and put the providers as attributes.
-
-.. literalinclude:: ../../examples/containers/dynamic.py
-   :language: python
-   :lines: 3-
-
-The dynamic container is good for the case when your application structure depends on the
-configuration file or some other source that you can reach only after application is already
-running (database, api, etc).
-
-In this example we use the configuration to fill in the dynamic container with the providers:
-
-.. literalinclude:: ../../examples/containers/dynamic_runtime_creation.py
-   :language: python
-   :lines: 3-
-
-.. disqus::
-

docs/containers/index.rst

@@ -1,29 +0,0 @@
-.. _containers:
-
-Containers
-==========
-
-Containers are collections of the providers.
-
-There are several use cases how you can use containers:
-
-+ Keeping all the providers in a single container (most common).
-+ Grouping of the providers from the same architectural layer (for example,
-  ``Services``, ``Models`` and ``Forms`` containers).
-+ Grouping of providers from the same functional groups (for example,
-  container ``Users``, that contains all functional parts of the ``users``
-  package).
-
-Containers module API docs - :py:mod:`dependency_injector.containers`.
-
-..  toctree::
-    :maxdepth: 2
-
-    declarative
-    dynamic
-    specialization
-    overriding
-    copying
-    reset_singletons
-    check_dependencies
-    traversal

docs/containers/overriding.rst

@@ -1,40 +0,0 @@
-Container overriding
---------------------
-
-.. currentmodule:: dependency_injector.containers
-
-The container can be overridden by the other container. All of the providers from the overriding
-container will override the providers with the same names in the overridden container.
-
-.. literalinclude:: ../../examples/containers/override.py
-   :language: python
-   :lines: 3-
-
-It helps in a testing. Also you can use it for configuring project for the different
-environments: replace an API client with a stub on the dev or stage.
-
-The container also has:
-
-- ``container.overridden`` - tuple of all overriding containers.
-- ``container.reset_last_overriding()`` - reset last overriding for each provider in the container.
-- ``container.reset_override()`` - reset all overriding in the container.
-
-:py:class:`DynamicContainer` has the same functionality.
-
-Another possible way to override container providers on declarative level is
-``@containers.override()`` decorator:
-
-.. literalinclude:: ../../examples/containers/declarative_override_decorator.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12-16
-
-Decorator ``@containers.override()`` takes a container for overriding as an argument.
-This container providers will be overridden by the providers with the same names from
-the decorated container.
-
-It helps to change the behaviour of application by importing extension modules but not a code change.
-Imported module can override providers in main container. While the code uses main container as
-before, the overridden providers provide components defined in the extension module.
-
-.. disqus::

docs/containers/reset_singletons.rst

@@ -1,31 +0,0 @@
-.. _reset-container-singletons:
-
-Reset container singletons
---------------------------
-
-To reset all container singletons use method ``.reset_singletons()``.
-
-.. literalinclude:: ../../examples/containers/reset_singletons.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 16
-
-Method ``.reset_singletons()`` also resets singletons in sub-containers: ``providers.Container`` and
-``providers.DependenciesContainer.``
-
-.. literalinclude:: ../../examples/containers/reset_singletons_subcontainers.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 21
-
-You can use ``.reset_singletons()`` method with a context manager. Singletons will be reset on
-both entering and exiting a context.
-
-.. literalinclude:: ../../examples/containers/reset_singletons_with.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 14-15
-
-See also: :ref:`singleton-provider`.
-
-.. disqus::

docs/containers/specialization.rst

@@ -1,25 +0,0 @@
-Specialization of the container provider type
----------------------------------------------
-
-.. currentmodule:: dependency_injector.containers
-
-You can make a restriction of the :py:class:`DeclarativeContainer` provider type:
-
-.. literalinclude:: ../../examples/containers/declarative_provider_type.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 29-31
-
-The emphasized lines will cause an error because ``other_provider`` is not a subtype of the
-``ServiceProvider``. This helps to control the content of the container.
-
-The same works for the :py:class:`DynamicContainer`:
-
-.. literalinclude:: ../../examples/containers/dynamic_provider_type.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 23
-
-The emphasized line will also cause an error.
-
-.. disqus::

docs/containers/traversal.rst

@@ -1,33 +0,0 @@
-Container providers traversal
------------------------------
-
-To traverse container providers use method ``.traverse()``.
-
-.. literalinclude:: ../../examples/containers/traverse.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 38
-
-Method ``.traverse()`` returns a generator. Traversal generator visits all container providers.
-This includes nested providers even if they are not present on the root level of the container.
-
-Traversal generator guarantees that each container provider will be visited only once.
-It can traverse cyclic provider graphs.
-
-Traversal generator does not guarantee traversal order.
-
-You can use ``types=[...]`` argument to filter providers. Traversal generator will only return
-providers matching specified types.
-
-.. code-block:: python
-   :emphasize-lines: 3
-
-   container = Container()
-
-   for provider in container.traverse(types=[providers.Resource]):
-       print(provider)
-
-    # <dependency_injector.providers.Resource(<function init_database at 0x10bd2cb80>) at 0x10d346b40>
-    # <dependency_injector.providers.Resource(<function init_cache at 0x10be373a0>) at 0x10d346bc0>
-
-.. disqus::

docs/examples-other/chained-factories.rst

@@ -1,68 +0,0 @@
-Chained Factories pattern
-=========================
-
-This example demonstrates "Chained Factories" pattern.
-
-The idea of the pattern is in wrapping ``Factory`` into another ``Factory`` that adds
-additional arguments.
-
-.. code-block:: python
-
-   base_factory = providers.Factory(
-       SomeClass,
-       base_argument=1,
-   )
-
-   concrete_factory = providers.Factory(
-       base_factory,
-       extra_argument=2,
-   )
-
-
-   if __name__ == "__main__":
-       instance = concrete_factory()
-       # Same as: # instance = SomeClass(base_argument=1, extra_argument=2)
-
-Sample code
------------
-
-Listing of the pattern example:
-
-.. literalinclude:: ../../examples/miniapps/factory-patterns/chained_factories.py
-   :language: python
-
-Arguments priority
-------------------
-
-Passing of the arguments works the same way like for any other :ref:`factory-provider`.
-
-.. code-block:: python
-
-   # 1. Keyword arguments of upper level factory are added to lower level factory
-   chained_dict_factory = providers.Factory(
-       providers.Factory(dict, arg1=1),
-       arg2=2,
-   )
-   print(chained_dict_factory())  # prints: {"arg1": 1, "arg2": 2}
-
-   # 2. Keyword arguments of upper level factory have priority
-   chained_dict_factory = providers.Factory(
-       providers.Factory(dict, arg1=1),
-       arg1=2,
-   )
-   print(chained_dict_factory())  # prints: {"arg1": 2}
-
-   # 3. Keyword arguments provided from context have the most priority
-   chained_dict_factory = providers.Factory(
-       providers.Factory(dict, arg1=1),
-       arg1=2,
-   )
-   print(chained_dict_factory(arg1=3))  # prints: {"arg1": 3}
-
-
-Credits
--------
-
-The "Chained Factories" pattern was suggested by the ``Dependency Injector`` users.
-
-.. disqus::

docs/examples-other/factory-of-factories.rst

@@ -1,74 +0,0 @@
-Factory of Factories pattern
-============================
-
-This example demonstrates "Factory of Factories" pattern.
-
-The idea of the pattern is in creating a ``Factory`` that creates another ``Factory`` and adds
-additional arguments.
-
-.. code-block:: python
-
-   base_factory = providers.Factory(
-       providers.Factory
-       SomeClass,
-       base_argument=1,
-   )
-
-   concrete_factory = providers.Factory(
-       OtherClass,
-       instance=base_factory(extra_argument=1),
-   )
-
-
-   if __name__ == "__main__":
-       instance = concrete_factory()
-       # Same as: # instance = SomeClass(base_argument=1, extra_argument=2)
-
-Sample code
------------
-
-Listing of the pattern example:
-
-.. literalinclude:: ../../examples/miniapps/factory-patterns/factory_of_factories.py
-   :language: python
-
-Arguments priority
-------------------
-
-Passing of the arguments works the same way like for any other :ref:`factory-provider`.
-
-.. code-block:: python
-
-   # 1. Keyword arguments of upper level factory are added to lower level factory
-   factory_of_dict_factories = providers.Factory(
-       providers.Factory,
-       dict,
-       arg1=1,
-   )
-   dict_factory = factory_of_dict_factories(arg2=2)
-   print(dict_factory())  # prints: {"arg1": 1, "arg2": 2}
-
-   # 2. Keyword arguments of upper level factory have priority
-   factory_of_dict_factories = providers.Factory(
-       providers.Factory,
-       dict,
-       arg1=1,
-   )
-   dict_factory = factory_of_dict_factories(arg1=2)
-   print(dict_factory())  # prints: {"arg1": 2}
-
-   # 3. Keyword arguments provided from context have the most priority
-   factory_of_dict_factories = providers.Factory(
-       providers.Factory,
-       dict,
-       arg1=1,
-   )
-   dict_factory = factory_of_dict_factories(arg1=2)
-   print(dict_factory(arg1=3))  # prints: {"arg1": 3}
-
-Credits
--------
-
-The "Factory of Factories" pattern was suggested by the ``Dependency Injector`` users.
-
-.. disqus::

docs/examples-other/index.rst

@@ -1,17 +0,0 @@
-Other examples
-==============
-
-.. meta::
-   :keywords: Python,Dependency Injection,Inversion of Control,Container,Example,Application,
-              Framework
-   :description: This sections contains assorted Dependency Injector examples.
-
-This sections contains assorted ``Dependency Injector`` examples.
-
-..  toctree::
-    :maxdepth: 2
-
-    use-cases
-    password-hashing
-    chained-factories
-    factory-of-factories

docs/examples-other/password-hashing.rst

@@ -1,30 +0,0 @@
-Password hashing example
-========================
-
-.. meta::
-   :keywords: Python,Dependency Injection,Inversion of Control,Container,Example,Application,
-              Framework,Callable
-   :description: This example demonstrates a usage of the Callable provider.
-
-This example demonstrates an injection of the ``Callable`` provider.
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/password-hashing>`_.
-
-Sample code
------------
-
-Listing of the pattern example:
-
-.. literalinclude:: ../../examples/miniapps/password-hashing/example.py
-   :language: python
-
-Run the example
----------------
-
-Instructions for running:
-
-.. code-block:: bash
-
-    python example.py
-
-.. disqus::

docs/examples-other/use-cases.rst

@@ -1,74 +0,0 @@
-Use cases example
-=================
-
-.. meta::
-   :keywords: Python,Dependency Injection,Inversion of Control,Container,Example,Application,
-              Framework,DependenciesContainer
-   :description: This example demonstrates a usage of the DependenciesContainer provider.
-
-This example demonstrates a usage of the ``DependenciesContainer`` provider.
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/decoupled-packages>`_.
-
-Application structure
----------------------
-
-Example application has next structure:
-
-.. code-block:: bash
-
-
-   ./
-   └── example/
-       ├── __init__.py
-       ├── __main__.py
-       ├── adapters.py
-       ├── containers.py
-       └── usecases.py
-
-Containers
-----------
-
-Listing of the ``example/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/use-cases/example/containers.py
-   :language: python
-
-Main module
------------
-
-Listing of the ``example/__main__.py``:
-
-.. literalinclude:: ../../examples/miniapps/use-cases/example/__main__.py
-   :language: python
-
-
-Run the application
--------------------
-
-Instructions for running in the "test" mode:
-
-.. code-block:: bash
-
-    python run.py test example@example.com
-
-Instructions for running in the "prod" mode:
-
-.. code-block:: bash
-
-    python run.py prod example@example.com
-
-Adapters and use cases
-----------------------
-
-Listing of the ``example/adapters.py``:
-
-.. literalinclude:: ../../examples/miniapps/use-cases/example/adapters.py
-   :language: python
-
-Listing of the ``example/usecases.py``:
-
-.. literalinclude:: ../../examples/miniapps/use-cases/example/usecases.py
-   :language: python
-
-.. disqus::

docs/examples/aiohttp.rst

@@ -1,83 +0,0 @@
-.. _aiohttp-example:
-
-Aiohttp example
-===============
-
-.. meta::
-   :keywords: Python,Dependency Injection,Aiohttp,Example
-   :description: This example demonstrates a usage of the Aiohttp and Dependency Injector.
-
-
-This example shows how to use ``Dependency Injector`` with `Aiohttp <https://docs.aiohttp.org/>`_.
-
-The example application is a REST API that searches for funny GIFs on the `Giphy <https://giphy.com/>`_.
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/aiohttp>`_.
-
-:ref:`aiohttp-tutorial` demonstrates how to build this application step-by-step.
-
-Application structure
----------------------
-
-Application has next structure:
-
-.. code-block:: bash
-
-   ./
-   ├── giphynavigator/
-   │   ├── __init__.py
-   │   ├── application.py
-   │   ├── containers.py
-   │   ├── giphy.py
-   │   ├── handlers.py
-   │   ├── services.py
-   │   └── tests.py
-   ├── config.yml
-   └── requirements.txt
-
-Container
----------
-
-Declarative container is defined in ``giphynavigator/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/aiohttp/giphynavigator/containers.py
-   :language: python
-
-Handlers
---------
-
-Handler has dependencies on search service and some config options. The dependencies are injected
-using :ref:`wiring` feature.
-
-Listing of ``giphynavigator/handlers.py``:
-
-.. literalinclude:: ../../examples/miniapps/aiohttp/giphynavigator/handlers.py
-   :language: python
-
-Application factory
--------------------
-Application factory creates container, wires it with the ``handlers`` module, creates
-``Aiohttp`` app and setup routes.
-
-Listing of ``giphynavigator/application.py``:
-
-.. literalinclude:: ../../examples/miniapps/aiohttp/giphynavigator/application.py
-   :language: python
-
-Tests
------
-
-Tests use :ref:`provider-overriding` feature to replace giphy client with a mock ``giphynavigator/tests.py``:
-
-.. literalinclude:: ../../examples/miniapps/aiohttp/giphynavigator/tests.py
-   :language: python
-   :emphasize-lines: 32,59,73
-
-Sources
--------
-
-Explore the sources on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/aiohttp>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/application-multiple-containers.rst

@@ -1,89 +0,0 @@
-.. _application-multiple-containers:
-
-Application example (multiple containers)
-=========================================
-
-.. meta::
-   :keywords: Python,Dependency Injection,Inversion of Control,Container,Example,Application,
-              Framework,AWS,boto3,client
-   :description: This example shows how you can create an application using multiple declarative
-                 containers. We build an example Python micro application following the dependency
-                 injection principle. It consists from several services with a domain logic that
-                 have dependencies on database & AWS S3.
-
-This example shows how you can create an application using multiple declarative containers. Using
-multiple declarative containers is a good choice for a large application. For
-building a moderate or a small size application refer to :ref:`application-single-container`.
-
-We build an example micro application following the dependency injection principle. It consists
-of several services with a domain logic. The services have dependencies on database & AWS S3.
-
-.. image:: images/application.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 <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/application-multiple-containers>`_.
-
-Application structure
----------------------
-
-Application consists of an ``example`` package, a configuration file and a ``requirements.txt``
-file.
-
-.. code-block:: bash
-
-   ./
-   ├── example/
-   │   ├── __init__.py
-   │   ├── __main__.py
-   │   ├── containers.py
-   │   └── services.py
-   ├── config.yml
-   └── requirements.txt
-
-Containers
-----------
-
-Listing of the ``example/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/application-multiple-containers/example/containers.py
-   :language: python
-
-Main module
------------
-
-Listing of the ``example/__main__.py``:
-
-.. literalinclude:: ../../examples/miniapps/application-multiple-containers/example/__main__.py
-   :language: python
-
-Services
---------
-
-Listing of the ``example/services.py``:
-
-.. literalinclude:: ../../examples/miniapps/application-multiple-containers/example/services.py
-   :language: python
-
-Configuration
--------------
-
-Listing of the ``config.yml``:
-
-.. literalinclude:: ../../examples/miniapps/application-multiple-containers/config.yml
-   :language: yaml
-
-Run the application
--------------------
-
-You can find the source code and instructions for running on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/application-multiple-containers>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/application-single-container.rst

@@ -1,95 +0,0 @@
-.. _application-single-container:
-
-Application example (single container)
-======================================
-
-.. meta::
-   :keywords: Python,Dependency Injection,Inversion of Control,Container,Example,Application,
-              Framework,AWS,boto3,client
-   :description: This example shows how you can create an application using a single declarative
-                 container. We build an example Python micro application following the dependency
-                 injection principle. It consists from several services with a domain logic that
-                 have dependencies on database & AWS S3.
-
-This example shows how you can create an application using a single declarative container. Using
-a single declarative container is a good choice for small or moderate size application. For
-building a large application refer to :ref:`application-multiple-containers`.
-
-We build an example micro application following the dependency injection principle. It consists
-of several services with a domain logic. The services have dependencies on database & AWS S3.
-
-.. image:: images/application.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 <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/application-single-container>`_.
-
-Application structure
----------------------
-
-Application consists of an ``example`` package, several configuration files and a
-``requirements.txt`` file.
-
-.. code-block:: bash
-
-   ./
-   ├── example/
-   │   ├── __init__.py
-   │   ├── __main__.py
-   │   ├── containers.py
-   │   └── services.py
-   ├── config.ini
-   ├── logging.ini
-   └── requirements.txt
-
-Container
----------
-
-Listing of the ``example/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/application-single-container/example/containers.py
-   :language: python
-
-Main module
------------
-
-Listing of the ``example/__main__.py``:
-
-.. literalinclude:: ../../examples/miniapps/application-single-container/example/__main__.py
-   :language: python
-
-Services
---------
-
-Listing of the ``example/services.py``:
-
-.. literalinclude:: ../../examples/miniapps/application-single-container/example/services.py
-   :language: python
-
-Configuration
--------------
-
-Listing of the ``config.ini``:
-
-.. literalinclude:: ../../examples/miniapps/application-single-container/config.ini
-   :language: ini
-
-Listing of the ``logging.ini``:
-
-.. literalinclude:: ../../examples/miniapps/application-single-container/logging.ini
-   :language: ini
-
-Run the application
--------------------
-
-You can find the source code and instructions for running on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/application-single-container>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/boto3.rst

@@ -1,22 +0,0 @@
-.. _boto3-example:
-
-Boto3 example
-=============
-
-.. meta::
-   :keywords: Python,Dependency Injection,Boto3,AWS,Amazon Web Services,S3,SQS,Rout53,EC2,Lambda,Example
-   :description: This example demonstrates a usage of Boto3 AWS client and Dependency Injector.
-
-
-This example shows how to use ``Dependency Injector`` with `Boto3 <https://github.com/boto/boto3>`_.
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/boto3-session>`_.
-
-Listing of ``boto3_session_example.py``:
-
-.. literalinclude:: ../../examples/miniapps/boto3-session/boto3_session_example.py
-   :language: python
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/decoupled-packages.rst

@@ -1,134 +0,0 @@
-.. _decoupled-packages:
-
-Decoupled packages example (multiple containers)
-================================================
-
-.. meta::
-   :keywords: Python,Dependency Injection,Inversion of Control,Container,Example,Application,
-              Framework,AWS,boto3,client
-   :description: This example shows how to use Dependency Injector to create Python 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.
-
-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 of 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 <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/decoupled-packages>`_.
-
-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 <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/decoupled-packages>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/django.rst

@@ -1,99 +0,0 @@
-.. _django-example:
-
-Django example
-==============
-
-.. meta::
-   :keywords: Python,Dependency Injection,Django,Example
-   :description: This example demonstrates a usage of the Django and Dependency Injector.
-
-
-This example shows how to use ``Dependency Injector`` with `Django <https://www.djangoproject.com/>`_.
-
-The example application helps to search for repositories on the Github.
-
-.. image:: images/django.png
-    :width: 100%
-    :align: center
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/django>`_.
-
-Application structure
----------------------
-
-Application has standard Django project structure. It consists of ``githubnavigator`` project package and
-``web`` application package:
-
-.. code-block:: bash
-
-   ./
-   ├── githubnavigator/
-   │   ├── __init__.py
-   │   ├── asgi.py
-   │   ├── containers.py
-   │   ├── services.py
-   │   ├── settings.py
-   │   ├── urls.py
-   │   └── wsgi.py
-   ├── web/
-   │   ├── templates/
-   │   │   ├── base.html
-   │   │   └── index.html
-   │   ├── __init__.py
-   │   ├── apps.py
-   │   ├── tests.py
-   │   ├── urls.py
-   │   └── views.py
-   ├── manage.py
-   └── requirements.txt
-
-Container
----------
-
-Declarative container is defined in ``githubnavigator/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/django/githubnavigator/containers.py
-   :language: python
-
-Container instance is created in ``githubnavigator/__init__.py``:
-
-.. literalinclude:: ../../examples/miniapps/django/githubnavigator/__init__.py
-   :language: python
-
-Views
------
-
-View has dependencies on search service and some config options. The dependencies are injected
-using :ref:`wiring` feature.
-
-Listing of ``web/views.py``:
-
-.. literalinclude:: ../../examples/miniapps/django/web/views.py
-   :language: python
-
-App config
-----------
-
-Container is wired to the ``views`` module in the app config ``web/apps.py``:
-
-.. literalinclude:: ../../examples/miniapps/django/web/apps.py
-   :language: python
-   :emphasize-lines: 12
-
-Tests
------
-
-Tests use :ref:`provider-overriding` feature to replace github client with a mock ``web/tests.py``:
-
-.. literalinclude:: ../../examples/miniapps/django/web/tests.py
-   :language: python
-   :emphasize-lines: 39,60
-
-Sources
--------
-
-Explore the sources on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/django>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/fastapi-redis.rst

@@ -1,100 +0,0 @@
-.. _fastapi-redis-example:
-
-FastAPI + Redis example
-=======================
-
-.. meta::
-   :keywords: Python,Dependency Injection,FastAPI,Redis,Example
-   :description: This example demonstrates a usage of the FastAPI, Redis, and Dependency Injector.
-
-This example shows how to use ``Dependency Injector`` with `FastAPI <https://fastapi.tiangolo.com/>`_ and
-`Redis <https://redis.io/>`_.
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/fastapi-redis>`_.
-
-See also:
-
-- Provider :ref:`async-injections`
-- Resource provider :ref:`resource-async-initializers`
-- Wiring :ref:`async-injections-wiring`
-
-Application structure
----------------------
-
-Application has next structure:
-
-.. code-block:: bash
-
-   ./
-   ├── fastapiredis/
-   │   ├── __init__.py
-   │   ├── application.py
-   │   ├── containers.py
-   │   ├── redis.py
-   │   ├── services.py
-   │   └── tests.py
-   ├── docker-compose.yml
-   ├── Dockerfile
-   └── requirements.txt
-
-Redis
------
-
-Module ``redis`` defines Redis connection pool initialization and shutdown. See ``fastapiredis/redis.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-redis/fastapiredis/redis.py
-   :language: python
-
-Service
--------
-
-Module ``services`` contains example service. Service has a dependency on Redis connection pool.
-It uses it for getting and setting a key asynchronously. Real life service will do something more meaningful.
-See ``fastapiredis/services.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-redis/fastapiredis/services.py
-   :language: python
-
-Container
----------
-
-Declarative container wires example service with Redis connection pool. See ``fastapiredis/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-redis/fastapiredis/containers.py
-   :language: python
-
-Application
------------
-
-Module ``application`` creates ``FastAPI`` app, setup endpoint, and init container.
-
-Endpoint ``index`` has a dependency on example service. The dependency is injected using :ref:`wiring` feature.
-
-Listing of ``fastapiredis/application.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-redis/fastapiredis/application.py
-   :language: python
-
-Tests
------
-
-Tests use :ref:`provider-overriding` feature to replace example service with a mock. See ``fastapiredis/tests.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-redis/fastapiredis/tests.py
-   :language: python
-   :emphasize-lines: 24
-
-Sources
--------
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/fastapi-redis>`_.
-
-See also:
-
-- Provider :ref:`async-injections`
-- Resource provider :ref:`resource-async-initializers`
-- Wiring :ref:`async-injections-wiring`
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/fastapi-sqlalchemy.rst

@@ -1,121 +0,0 @@
-.. _fastapi-sqlalchemy-example:
-
-FastAPI + SQLAlchemy example
-============================
-
-.. meta::
-   :keywords: Python,Dependency Injection,FastAPI,SQLAlchemy,Example
-   :description: This example demonstrates a usage of the FastAPI, SQLAlchemy, and Dependency Injector.
-
-This example shows how to use ``Dependency Injector`` with `FastAPI <https://fastapi.tiangolo.com/>`_ and
-`SQLAlchemy <https://www.sqlalchemy.org/>`_.
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/fastapi-sqlalchemy>`_.
-
-Thanks to `@ShvetsovYura <https://github.com/ShvetsovYura>`_ for providing initial example:
-`FastAPI_DI_SqlAlchemy <https://github.com/ShvetsovYura/FastAPI_DI_SqlAlchemy>`_.
-
-Application structure
----------------------
-
-Application has next structure:
-
-.. code-block:: bash
-
-   ./
-   ├── webapp/
-   │   ├── __init__.py
-   │   ├── application.py
-   │   ├── containers.py
-   │   ├── database.py
-   │   ├── endpoints.py
-   │   ├── models.py
-   │   ├── repositories.py
-   │   ├── services.py
-   │   └── tests.py
-   ├── config.yml
-   ├── docker-compose.yml
-   ├── Dockerfile
-   └── requirements.txt
-
-Application factory
--------------------
-
-Application factory creates container, wires it with the ``endpoints`` module, creates
-``FastAPI`` app, and setup routes.
-
-Application factory also creates database if it does not exist.
-
-Listing of ``webapp/application.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-sqlalchemy/webapp/application.py
-   :language: python
-
-Endpoints
----------
-
-Module ``endpoints`` contains example endpoints. Endpoints have a dependency on user service.
-User service is injected using :ref:`wiring` feature. See ``webapp/endpoints.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-sqlalchemy/webapp/endpoints.py
-   :language: python
-
-Container
----------
-
-Declarative container wires example user service, user repository, and utility database class.
-See ``webapp/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-sqlalchemy/webapp/containers.py
-   :language: python
-
-Services
---------
-
-Module ``services`` contains example user service. See ``webapp/services.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-sqlalchemy/webapp/services.py
-   :language: python
-
-Repositories
-------------
-
-Module ``repositories`` contains example user repository. See ``webapp/repositories.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-sqlalchemy/webapp/repositories.py
-   :language: python
-
-Models
-------
-
-Module ``models`` contains example SQLAlchemy user model. See ``webapp/models.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-sqlalchemy/webapp/models.py
-   :language: python
-
-Database
---------
-
-Module ``database`` defines declarative base and utility class with engine and session factory.
-See ``webapp/database.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-sqlalchemy/webapp/database.py
-   :language: python
-
-Tests
------
-
-Tests use :ref:`provider-overriding` feature to replace repository with a mock. See ``webapp/tests.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi-sqlalchemy/webapp/tests.py
-   :language: python
-   :emphasize-lines: 25, 45, 58, 74, 86, 97
-
-Sources
--------
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/fastapi-sqlalchemy>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/fastapi.rst

@@ -1,81 +0,0 @@
-.. _fastapi-example:
-
-FastAPI example
-===============
-
-.. meta::
-   :keywords: Python,Dependency Injection,FastAPI,Example
-   :description: This example demonstrates a usage of the FastAPI and Dependency Injector.
-
-
-This example shows how to use ``Dependency Injector`` with `FastAPI <https://fastapi.tiangolo.com/>`_.
-
-The example application is a REST API that searches for funny GIFs on the `Giphy <https://giphy.com/>`_.
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/fastapi>`_.
-
-Application structure
----------------------
-
-Application has next structure:
-
-.. code-block:: bash
-
-   ./
-   ├── giphynavigator/
-   │   ├── __init__.py
-   │   ├── application.py
-   │   ├── containers.py
-   │   ├── endpoints.py
-   │   ├── giphy.py
-   │   ├── services.py
-   │   └── tests.py
-   ├── config.yml
-   └── requirements.txt
-
-Container
----------
-
-Declarative container is defined in ``giphynavigator/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi/giphynavigator/containers.py
-   :language: python
-
-Endpoints
----------
-
-Endpoint has a dependency on search service. There are also some config options that are used as default values.
-The dependencies are injected using :ref:`wiring` feature.
-
-Listing of ``giphynavigator/endpoints.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi/giphynavigator/endpoints.py
-   :language: python
-
-Application factory
--------------------
-Application factory creates container, wires it with the ``endpoints`` module, creates
-``FastAPI`` app, and setup routes.
-
-Listing of ``giphynavigator/application.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi/giphynavigator/application.py
-   :language: python
-
-Tests
------
-
-Tests use :ref:`provider-overriding` feature to replace giphy client with a mock ``giphynavigator/tests.py``:
-
-.. literalinclude:: ../../examples/miniapps/fastapi/giphynavigator/tests.py
-   :language: python
-   :emphasize-lines: 29,57,72
-
-Sources
--------
-
-Explore the sources on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/fastapi>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/fastdepends.rst

@@ -1,48 +0,0 @@
-.. _fastdepends-example:
-
-FastDepends example
-===================
-
-.. meta::
-   :keywords: Python,Dependency Injection,FastDepends,Example
-   :description: This example demonstrates a usage of the FastDepends and Dependency Injector.
-
-
-This example demonstrates how to use ``Dependency Injector`` with `FastDepends <https://github.com/Lancetnik/FastDepends>`_, a lightweight dependency injection framework inspired by FastAPI's dependency system, but without the web framework components.
-
-Basic Usage
------------
-
-The integration between FastDepends and Dependency Injector is straightforward. Simply use Dependency Injector's ``Provide`` marker within FastDepends' ``Depends`` function:
-
-.. code-block:: python
-
-    import sys
-
-    from dependency_injector import containers, providers
-    from dependency_injector.wiring import inject, Provide
-    from fast_depends import Depends
-
-
-    class CoefficientService:
-        @staticmethod
-        def get_coefficient() -> float:
-            return 1.2
-
-
-    class Container(containers.DeclarativeContainer):
-        service = providers.Factory(CoefficientService)
-
-
-    @inject
-    def apply_coefficient(
-        a: int,
-        coefficient_provider: CoefficientService = Depends(Provide[Container.service]),
-    ) -> float:
-        return a * coefficient_provider.get_coefficient()
-
-
-    container = Container()
-    container.wire(modules=[sys.modules[__name__]])
-
-    apply_coefficient(100) == 120.0

docs/examples/flask-blueprints.rst

@@ -1,91 +0,0 @@
-.. _flask-blueprints-example:
-
-Flask blueprints example
-========================
-
-.. meta::
-   :keywords: Python,Dependency Injection,Flask,Blueprints,Example
-   :description: This example demonstrates a usage of the Flask Blueprints and Dependency Injector.
-
-
-This example shows how to use ``Dependency Injector`` with `Flask <https://flask.palletsprojects.com/en/1.1.x/>`_
-blueprints.
-
-The example application helps to search for repositories on the Github.
-
-.. image:: images/flask.png
-    :width: 100%
-    :align: center
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/flask-blueprints>`_.
-
-Application structure
----------------------
-
-Application has next structure:
-
-.. code-block:: bash
-
-   ./
-   ├── githubnavigator/
-   │   ├── blueprints
-   │   │   ├── __init__.py
-   │   │   └── example.py
-   │   ├── templates
-   │   │   ├── base.html
-   │   │   └── index.py
-   │   ├── __init__.py
-   │   ├── application.py
-   │   ├── containers.py
-   │   ├── services.py
-   │   └── tests.py
-   ├── config.yml
-   └── requirements.txt
-
-Container
----------
-
-Declarative container is defined in ``githubnavigator/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/flask-blueprints/githubnavigator/containers.py
-   :language: python
-
-Blueprints
-----------
-
-Blueprint's view has dependencies on search service and some config options. The dependencies are injected
-using :ref:`wiring` feature.
-
-Listing of ``githubnavigator/blueprints/example.py``:
-
-.. literalinclude:: ../../examples/miniapps/flask-blueprints/githubnavigator/blueprints/example.py
-   :language: python
-
-Application factory
--------------------
-
-Application factory creates container, wires it with the blueprints, creates
-``Flask`` app, and setup routes.
-
-Listing of ``githubnavigator/application.py``:
-
-.. literalinclude:: ../../examples/miniapps/flask-blueprints/githubnavigator/application.py
-   :language: python
-
-Tests
------
-
-Tests use :ref:`provider-overriding` feature to replace github client with a mock ``githubnavigator/tests.py``:
-
-.. literalinclude:: ../../examples/miniapps/flask-blueprints/githubnavigator/tests.py
-   :language: python
-   :emphasize-lines: 44,67
-
-Sources
--------
-
-Explore the sources on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/flask-blueprints>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/flask.rst

@@ -1,89 +0,0 @@
-.. _flask-example:
-
-Flask example
-=============
-
-.. meta::
-   :keywords: Python,Dependency Injection,Flask,Example
-   :description: This example demonstrates a usage of the Flask and Dependency Injector.
-
-
-This example shows how to use ``Dependency Injector`` with `Flask <https://flask.palletsprojects.com/en/1.1.x/>`_.
-
-The example application helps to search for repositories on the Github.
-
-.. image:: images/flask.png
-    :width: 100%
-    :align: center
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/flask>`_.
-
-:ref:`flask-tutorial` demonstrates how to build this application step-by-step.
-
-Application structure
----------------------
-
-Application has next structure:
-
-.. code-block:: bash
-
-   ./
-   ├── githubnavigator/
-   │   ├── templates
-   │   │   ├── base.html
-   │   │   └── index.py
-   │   ├── __init__.py
-   │   ├── application.py
-   │   ├── containers.py
-   │   ├── services.py
-   │   ├── tests.py
-   │   └── views.py
-   ├── config.yml
-   └── requirements.txt
-
-Container
----------
-
-Declarative container is defined in ``githubnavigator/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/flask/githubnavigator/containers.py
-   :language: python
-
-Views
------
-
-View has dependencies on search service and some config options. The dependencies are injected
-using :ref:`wiring` feature.
-
-Listing of ``githubnavigator/views.py``:
-
-.. literalinclude:: ../../examples/miniapps/flask/githubnavigator/views.py
-   :language: python
-
-Application factory
--------------------
-Application factory creates container, wires it with the ``views`` module, creates
-``Flask`` app and setup routes.
-
-Listing of ``githubnavigator/application.py``:
-
-.. literalinclude:: ../../examples/miniapps/flask/githubnavigator/application.py
-   :language: python
-
-Tests
------
-
-Tests use :ref:`provider-overriding` feature to replace github client with a mock ``githubnavigator/tests.py``:
-
-.. literalinclude:: ../../examples/miniapps/flask/githubnavigator/tests.py
-   :language: python
-   :emphasize-lines: 44,67
-
-Sources
--------
-
-Explore the sources on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/flask>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/examples/index.rst

@@ -1,27 +0,0 @@
-Examples
-========
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Example
-   :description: Python dependency injection examples.
-
-Explore the examples to see the ``Dependency Injector`` in action.
-
-..  toctree::
-    :maxdepth: 2
-
-    application-single-container
-    application-multiple-containers
-    decoupled-packages
-    boto3
-    django
-    flask
-    flask-blueprints
-    aiohttp
-    sanic
-    fastapi
-    fastapi-redis
-    fastapi-sqlalchemy
-    fastdepends
-
-.. disqus::

docs/examples/sanic.rst

@@ -1,82 +0,0 @@
-.. _sanic-example:
-
-Sanic example
-==============
-
-.. meta::
-   :keywords: Python,Dependency Injection,Sanic,Example
-   :description: This example demonstrates a usage of the Sanic and Dependency Injector.
-
-
-This example shows how to use ``Dependency Injector`` with `Sanic <https://sanic.readthedocs.io/en/latest/>`_.
-
-The example application is a REST API that searches for funny GIFs on the `Giphy <https://giphy.com/>`_.
-
-The source code is available on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/sanic>`_.
-
-Application structure
----------------------
-
-Application has next structure:
-
-.. code-block:: bash
-
-   ./
-   ├── giphynavigator/
-   │   ├── __init__.py
-   │   ├── __main__.py
-   │   ├── application.py
-   │   ├── containers.py
-   │   ├── giphy.py
-   │   ├── handlers.py
-   │   ├── services.py
-   │   └── tests.py
-   ├── config.yml
-   └── requirements.txt
-
-Container
----------
-
-Declarative container is defined in ``giphynavigator/containers.py``:
-
-.. literalinclude:: ../../examples/miniapps/sanic/giphynavigator/containers.py
-   :language: python
-
-Handlers
---------
-
-Handler has dependencies on search service and some config options. The dependencies are injected
-using :ref:`wiring` feature.
-
-Listing of ``giphynavigator/handlers.py``:
-
-.. literalinclude:: ../../examples/miniapps/sanic/giphynavigator/handlers.py
-   :language: python
-
-Application factory
--------------------
-Application factory creates container, wires it with the ``handlers`` module, creates
-``Sanic`` app and setup routes.
-
-Listing of ``giphynavigator/application.py``:
-
-.. literalinclude:: ../../examples/miniapps/sanic/giphynavigator/application.py
-   :language: python
-
-Tests
------
-
-Tests use :ref:`provider-overriding` feature to replace giphy client with a mock ``giphynavigator/tests.py``:
-
-.. literalinclude:: ../../examples/miniapps/sanic/giphynavigator/tests.py
-   :language: python
-   :emphasize-lines: 34,61,75
-
-Sources
--------
-
-Explore the sources on the `Github <https://github.com/ets-labs/python-dependency-injector/tree/master/examples/miniapps/sanic>`_.
-
-.. include:: ../sponsor.rst
-
-.. disqus::

docs/index.rst

@@ -1,150 +1,60 @@
-=================================================================
+Dependency Injector
-Dependency Injector --- Dependency injection framework for Python
+===================
-=================================================================
 
-.. meta::
+Dependency injection framework for Python projects.
-   :google-site-verification: V1hlKfpgL3AARAElwFcqP4qW1Smsx5bKSRU8O86i20Y
-   :keywords: Python,Dependency injection,DI,Inversion of Control,IoC,
-              IoC Container,Factory, Singleton, Design Patterns
-   :description: Dependency Injector is a dependency injection framework
-                 for Python. It helps to maintain you application structure.
-                 It was designed to be unified, developer-friendly
-                 tool that helps to implement dependency injection design
-                 pattern in formal, pretty, Pythonic way. Dependency Injector
-                 provides implementations of such popular design patterns
-                 like IoC container, Factory and Singleton. Dependency
-                 Injector providers are implemented as C extension types
-                 using Cython.
 
-.. _index:
++---------------------------------------+-------------------------------------------------------------------------------+
+| *PyPi*                                | .. image:: https://img.shields.io/pypi/v/dependency_injector.svg              |
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
+|                                       |    :alt: Latest Version                                                       |
+|                                       | .. image:: https://img.shields.io/pypi/dm/dependency_injector.svg             |
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
+|                                       |    :alt: Downloads                                                            |
+|                                       | .. image:: https://img.shields.io/pypi/l/dependency_injector.svg              |
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
+|                                       |    :alt: License                                                              |
++---------------------------------------+-------------------------------------------------------------------------------+
+| *Python versions and implementations* | .. image:: https://img.shields.io/pypi/pyversions/dependency_injector.svg     |
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
+|                                       |    :alt: Supported Python versions                                            |
+|                                       | .. image:: https://img.shields.io/pypi/implementation/dependency_injector.svg |
+|                                       |    :target: https://pypi.python.org/pypi/dependency_injector/                 |
+|                                       |    :alt: Supported Python implementations                                     |
++---------------------------------------+-------------------------------------------------------------------------------+
+| *Builds and tests coverage*           | .. image:: https://travis-ci.org/rmk135/dependency_injector.svg?branch=master |
+|                                       |    :target: https://travis-ci.org/rmk135/dependency_injector                  |
+|                                       |    :alt: Build Status                                                         |
+|                                       | .. image:: https://coveralls.io/repos/rmk135/dependency_injector/badge.svg    |
+|                                       |    :target: https://coveralls.io/r/rmk135/dependency_injector                 |
+|                                       |    :alt: Coverage Status                                                      |
++---------------------------------------+-------------------------------------------------------------------------------+
 
-.. image:: https://img.shields.io/pypi/v/dependency_injector.svg
+*Dependency Injector* is a dependency injection framework for Python projects. 
-   :target: https://pypi.org/project/dependency-injector/
+It was designed to be unified, developer's friendly tool for managing any kind
-   :alt: Latest Version
+of Python objects and their dependencies in formal, pretty way.
 
-.. image:: https://img.shields.io/pypi/l/dependency_injector.svg
+Below is a list of some key features and points of *Dependency Injector*
-   :target: https://pypi.org/project/dependency-injector/
+framework:
-   :alt: License
 
-.. image:: https://img.shields.io/pypi/pyversions/dependency_injector.svg
+- Easy, smart, pythonic style.
-   :target: https://pypi.org/project/dependency-injector/
+- Obvious, clear structure.
-   :alt: Supported Python versions
+- Memory efficiency.
+- Thread safety.
+- Semantic versioning.
 
-.. image:: https://img.shields.io/pypi/implementation/dependency_injector.svg
+Main idea of *Dependency Injector* is to keep dependencies under control.
-   :target: https://pypi.org/project/dependency-injector/
-   :alt: Supported Python implementations
-
-.. image:: https://static.pepy.tech/badge/dependency-injector
-   :target: https://pepy.tech/project/dependency-injector
-   :alt: Downloads
-
-.. image:: https://static.pepy.tech/badge/dependency-injector/month
-   :target: https://pepy.tech/project/dependency-injector
-   :alt: Downloads
-
-.. image:: https://static.pepy.tech/badge/dependency-injector/week
-   :target: https://pepy.tech/project/dependency-injector
-   :alt: Downloads
-
-.. image:: https://img.shields.io/pypi/wheel/dependency-injector.svg
-   :target: https://pypi.org/project/dependency-injector/
-   :alt: Wheel
-
-.. image:: https://img.shields.io/github/actions/workflow/status/ets-labs/python-dependency-injector/tests-and-linters.yml?branch=master
-   :target: https://github.com/ets-labs/python-dependency-injector/actions
-   :alt: Build Status
-
-.. image:: https://coveralls.io/repos/github/ets-labs/python-dependency-injector/badge.svg?branch=master
-   :target: https://coveralls.io/github/ets-labs/python-dependency-injector?branch=master
-   :alt: Coverage Status
-
-``Dependency Injector`` is a dependency injection framework for Python.
-
-It helps implementing the dependency injection principle.
-
-Key features of the ``Dependency Injector``:
-
-- **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
-  ``List``, ``Dict``, ``Configuration``, ``Resource``, ``Dependency``, and ``Selector`` providers
-  that help assemble your objects. See :ref:`providers`.
-- **Overriding**. Can override any provider by another provider on the fly. This helps in testing
-  and configuring dev/stage environment to replace API clients with stubs etc. See
-  :ref:`provider-overriding`.
-- **Configuration**. Reads configuration from ``yaml``, ``ini``, and ``json`` files, ``pydantic`` settings,
-  environment variables, and dictionaries. See :ref:`configuration-provider`.
-- **Resources**. Helps with initialization and configuring of logging, event loop, thread
-  or process pool, etc. Can be used for per-function execution scope in tandem with wiring.
-  See :ref:`resource-provider`.
-- **Containers**. Provides declarative and dynamic containers. See :ref:`containers`.
-- **Wiring**. Injects dependencies into functions and methods. Helps integrate with
-  other frameworks: Django, Flask, Aiohttp, Sanic, FastAPI, etc. See :ref:`wiring`.
-- **Asynchronous**. Supports asynchronous injections. See :ref:`async-injections`.
-- **Typing**. Provides typing stubs, ``mypy``-friendly. See :ref:`provider-typing`.
-- **Performance**. Fast. Written in ``Cython``.
-- **Maturity**. Mature and production-ready. Well-tested, documented, and supported.
-
-.. code-block:: python
-
-   from dependency_injector import containers, providers
-   from dependency_injector.wiring import Provide, inject
-
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration()
-
-       api_client = providers.Singleton(
-           ApiClient,
-           api_key=config.api_key,
-           timeout=config.timeout,
-       )
-
-       service = providers.Factory(
-           Service,
-           api_client=api_client,
-       )
-
-
-   @inject
-   def main(service: Service = Provide[Container.service]) -> None:
-       ...
-
-
-   if __name__ == "__main__":
-       container = Container()
-       container.config.api_key.from_env("API_KEY", required=True)
-       container.config.timeout.from_env("TIMEOUT", as_=int, default=5)
-       container.wire(modules=[__name__])
-
-       main()  # <-- dependency is injected automatically
-
-       with container.api_client.override(mock.Mock()):
-           main()  # <-- overridden dependency is injected automatically
-
-With the ``Dependency Injector``, object assembling is consolidated in the container.
-Dependency injections are defined explicitly.
-This makes it easier to understand and change how the application works.
-
-.. figure:: https://raw.githubusercontent.com/wiki/ets-labs/python-dependency-injector/img/di-readme.svg
-   :target: https://github.com/ets-labs/python-dependency-injector
-
-Explore the documentation to know more about the ``Dependency Injector``.
-
-.. _contents:
 
 Contents
 --------
 
-.. toctree::
+..  toctree::
-   :maxdepth: 2
+    :maxdepth: 2
 
-   introduction/index
+    main/introduction
-   examples/index
+    main/installation
-   tutorials/index
+    providers/index
-   providers/index
+    catalogs/index
-   containers/index
+    advanced_usage/index
-   wiring
+    api/index
-   examples-other/index
+    main/feedback
-   api/index
+    main/changelog
-   main/feedback
-   main/changelog

docs/introduction/di_in_python.rst

@@ -1,315 +0,0 @@
-Dependency injection and inversion of control in Python
-=======================================================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Example
-   :description: This page describes a usage of the dependency injection and inversion of control
-                 in Python. It contains Python examples that show how to implement dependency
-                 injection. It demonstrates a usage of the dependency injection framework
-                 Dependency Injector, its container, Factory, Singleton and Configuration
-                 providers. The example show how to use Dependency Injector providers overriding
-                 feature for testing or configuring project in different environments and explains
-                 why it's better than monkey-patching.
-
-Originally dependency injection pattern got popular in languages with static typing like Java.
-Dependency injection is a principle that helps to achieve an inversion of control. A
-dependency injection framework can significantly improve the flexibility of a language
-with static typing. Implementation of a dependency injection framework for a language
-with static typing is not something that one can do quickly. It will be a quite complex thing
-to be done well. And will take time.
-
-Python is an interpreted language with dynamic typing. There is an opinion that dependency
-injection doesn't work for it as well as it does for Java. A lot of the flexibility is already
-built-in. Also, there is an opinion that a dependency injection framework is something that
-Python developer rarely needs. Python developers say that dependency injection can be implemented
-easily using language fundamentals.
-
-This page describes the advantages of applying dependency injection in Python. It
-contains Python examples that show how to implement dependency injection. It demonstrates the usage
-of the ``Dependency Injector`` framework, its container, ``Factory``, ``Singleton``,
-and ``Configuration`` providers. The example shows how to use providers' overriding feature
-of ``Dependency Injector`` for testing or re-configuring a project in different environments and
-explains why it's better than monkey-patching.
-
-What is dependency injection?
------------------------------
-
-Let's see what the dependency injection is.
-
-Dependency injection is a principle that helps to decrease coupling and increase cohesion.
-
-.. image:: images/coupling-cohesion.png
-
-What is coupling and cohesion?
-
-Coupling and cohesion are about how tough the components are tied.
-
-- **High coupling**. If the coupling is high it's like using superglue or welding. No easy way
-  to disassemble.
-- **High cohesion**. High cohesion is like using screws. Quite easy to disassemble and
-  re-assemble in a different way. It is an opposite to high coupling.
-
-Cohesion often correlates with coupling. Higher cohesion usually leads to lower coupling and vice versa.
-
-Low coupling brings flexibility. Your code becomes easier to change and test.
-
-How to implement the dependency injection?
-
-Objects do not create each other anymore. They provide a way to inject the dependencies instead.
-
-Before:
-
-.. code-block:: python
-
-   import os
-
-
-   class ApiClient:
-
-       def __init__(self) -> None:
-           self.api_key = os.getenv("API_KEY")  # <-- dependency
-           self.timeout = int(os.getenv("TIMEOUT"))  # <-- dependency
-
-
-   class Service:
-
-       def __init__(self) -> None:
-           self.api_client = ApiClient()  # <-- dependency
-
-
-   def main() -> None:
-       service = Service()  # <-- dependency
-       ...
-
-
-   if __name__ == "__main__":
-       main()
-
-After:
-
-.. code-block:: python
-
-   import os
-
-
-   class ApiClient:
-
-       def __init__(self, api_key: str, timeout: int) -> None:
-           self.api_key = api_key  # <-- dependency is injected
-           self.timeout = timeout  # <-- dependency is injected
-
-
-   class Service:
-
-       def __init__(self, api_client: ApiClient) -> None:
-           self.api_client = api_client  # <-- dependency is injected
-
-
-   def main(service: Service) -> None:  # <-- dependency is injected
-       ...
-
-
-   if __name__ == "__main__":
-       main(
-           service=Service(
-               api_client=ApiClient(
-                   api_key=os.getenv("API_KEY"),
-                   timeout=int(os.getenv("TIMEOUT")),
-               ),
-           ),
-       )
-
-``ApiClient`` is decoupled from knowing where the options come from. You can read a key and a
-timeout from a configuration file or even get them from a database.
-
-``Service`` is decoupled from the ``ApiClient``. It does not create it anymore. You can provide a
-stub or other compatible object.
-
-Function ``main()`` is decoupled from ``Service``. It receives it as an argument.
-
-Flexibility comes with a price.
-
-Now you need to assemble and inject the objects like this:
-
-.. code-block:: python
-
-   main(
-       service=Service(
-           api_client=ApiClient(
-               api_key=os.getenv("API_KEY"),
-               timeout=int(os.getenv("TIMEOUT")),
-           ),
-       ),
-   )
-
-The assembly code might get duplicated and it'll become harder to change the application structure.
-
-Here comes the ``Dependency Injector``.
-
-What does the Dependency Injector do?
--------------------------------------
-
-With the dependency injection pattern, objects lose the responsibility of assembling
-the dependencies. The ``Dependency Injector`` absorbs that responsibility.
-
-``Dependency Injector`` helps to assemble and inject the dependencies.
-
-It provides a container and providers that help you with the objects assembly.
-When you need an object you place a ``Provide`` marker as a default value of a
-function argument. When you call this function, framework assembles and injects
-the dependency.
-
-.. code-block:: python
-
-   from dependency_injector import containers, providers
-   from dependency_injector.wiring import Provide, inject
-
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration()
-
-       api_client = providers.Singleton(
-           ApiClient,
-           api_key=config.api_key,
-           timeout=config.timeout,
-       )
-
-       service = providers.Factory(
-           Service,
-           api_client=api_client,
-       )
-
-
-   @inject
-   def main(service: Service = Provide[Container.service]) -> None:
-       ...
-
-
-   if __name__ == "__main__":
-       container = Container()
-       container.config.api_key.from_env("API_KEY", required=True)
-       container.config.timeout.from_env("TIMEOUT", as_=int, default=5)
-       container.wire(modules=[__name__])
-
-       main()  # <-- dependency is injected automatically
-
-       with container.api_client.override(mock.Mock()):
-           main()  # <-- overridden dependency is injected automatically
-
-When you call the ``main()`` function the ``Service`` dependency is assembled and injected automatically.
-
-When you do testing, you call the ``container.api_client.override()`` method to replace the real API
-client with a mock. When you call ``main()``, the mock is injected.
-
-You can override any provider with another provider.
-
-It also helps you in a re-configuring project for different environments: replace an API client
-with a stub on the dev or stage.
-
-Objects assembling is consolidated in a container. Dependency injections are defined explicitly.
-This makes it easier to understand and change how an application works.
-
-Testing, Monkey-patching and dependency injection
--------------------------------------------------
-
-The testability benefit is opposed to monkey-patching.
-
-In Python, you can monkey-patch anything, anytime. The problem with monkey-patching is
-that it's too fragile. The cause of it is that when you monkey-patch you do something that
-wasn't intended to be done. You monkey-patch the implementation details. When implementation
-changes the monkey-patching is broken.
-
-With dependency injection, you patch the interface, not an implementation. This is a way more
-stable approach.
-
-Also, monkey-patching is way too dirty to be used outside of the testing code for
-re-configuring the project for the different environments.
-
-Conclusion
-----------
-
-Dependency injection provides you with three advantages:
-
-- **Flexibility**. The components are loosely coupled. You can easily extend or change the
-  functionality of a system by combining the components in a different way. You even can do it on
-  the fly.
-- **Testability**. Testing is easier because you can easily inject mocks instead of real objects
-  that use API or database, etc.
-- **Clearness and maintainability**. Dependency injection helps you reveal the dependencies.
-  Implicit becomes explicit. And "Explicit is better than implicit" (PEP 20 - The Zen of Python).
-  You have all the components and dependencies defined explicitly in a container. This
-  provides an overview and control of the application structure. It is easier to understand and
-  change it.
-
-Is it worth applying dependency injection in Python?
-
-It depends on what you build. The advantages above are not too important if you use Python as a
-scripting language. The picture is different when you use Python to create an application. The
-larger the application the more significant the benefits.
-
-Is it worth using a framework for applying dependency injection?
-
-The complexity of the dependency injection pattern implementation in Python is
-lower than in other languages but it's still in place. It doesn't mean you have to use a
-framework but using a framework is beneficial because the framework is:
-
-- Already implemented
-- Tested on all platforms and versions of Python
-- Documented
-- Supported
-- Other engineers are familiar with it
-
-An advice at last:
-
-- **Give it a try**. Dependency injection is counter-intuitive. Our nature is that
-  when we need something the first thought that comes to our mind is to go and get it. Dependency
-  injection is just like "Wait, I need to state a need instead of getting something right away".
-  It's like a little investment that will pay-off later. The advice is to just give it a try for
-  two weeks. This time will be enough for getting your own impression. If you don't like it you
-  won't lose too much.
-- **Common sense first**. Use common sense when applying dependency injection. It is a good
-  principle, but not a silver bullet. If you do it too much you will reveal too many of the
-  implementation details. Experience comes with practice and time.
-
-What's next?
-------------
-
-Choose one of the following as a next step:
-
-- Look at the application examples:
-    - :ref:`application-single-container`
-    - :ref:`application-multiple-containers`
-    - :ref:`decoupled-packages`
-    - :ref:`boto3-example`
-    - :ref:`django-example`
-    - :ref:`flask-example`
-    - :ref:`flask-blueprints-example`
-    - :ref:`aiohttp-example`
-    - :ref:`sanic-example`
-    - :ref:`fastapi-example`
-    - :ref:`fastapi-redis-example`
-    - :ref:`fastapi-sqlalchemy-example`
-- Pass the tutorials:
-    - :ref:`flask-tutorial`
-    - :ref:`aiohttp-tutorial`
-    - :ref:`asyncio-daemon-tutorial`
-    - :ref:`cli-tutorial`
-- Know more about the ``Dependency Injector`` :ref:`key-features`
-- Know more about the :ref:`providers`
-- Know more about the :ref:`wiring`
-- Go to the :ref:`contents`
-
-Useful links
-------------
-
-A few useful links related to a dependency injection design pattern for further reading:
-
-+ https://en.wikipedia.org/wiki/Dependency_injection
-+ https://martinfowler.com/articles/injection.html
-+ https://github.com/ets-labs/python-dependency-injector
-+ https://pypi.org/project/dependency-injector/
-
-.. include:: ../sponsor.rst
-
-.. disqus::