.coveragerc

@@ -0,0 +1,3 @@
+[run]
+include = objects/*
+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,10 @@ target/
 .idea/
 
 # Virtualenv
-venv*/
+venv/
 
 # SQLite
 *.db
 
-# Vim Rope
+# JointJS Experiments
-.ropeproject/
+jointjs/
-
-# 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,17 @@
+language: python
+install:
+  - pip install tox
+script:
+  - tox
+env:
+  - TOXENV=coveralls
+  - TOXENV=pylint
+  - TOXENV=flake8
+  - TOXENV=pep257
+  - TOXENV=py26
+  - TOXENV=py27
+  - TOXENV=py32
+  - TOXENV=py33
+  - TOXENV=py34
+  - 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
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -11,7 +11,7 @@ modification, are permitted provided that the following conditions are met:
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.
 
-* Neither the name of "Dependency Injector" nor the names of its
+* Neither the name of Objects nor the names of its
   contributors may be used to endorse or promote products derived from
   this software without specific prior written permission.
 
@@ -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,6 @@
-recursive-include src/dependency_injector *.py* *.c py.typed
+include objects/*
-recursive-include tests *.py
 include README.rst
-include CONTRIBUTORS.rst
+include LICENSE
-include LICENSE.rst
+include VERSION
+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,159 @@
-.. figure:: https://raw.githubusercontent.com/wiki/ets-labs/python-dependency-injector/img/logo.svg
+Objects
-   :target: https://github.com/ets-labs/python-dependency-injector
+=======
 
-| 
+Dependency management tool for Python projects
 
-.. image:: https://img.shields.io/pypi/v/dependency_injector.svg
++---------------------------------------+-------------------------------------------------------------------+
-   :target: https://pypi.org/project/dependency-injector/
+| *PyPi*                                | .. image:: https://pypip.in/version/Objects/badge.svg             |
-   :alt: Latest Version
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: Latest Version                                           |
+|                                       | .. image:: https://pypip.in/download/Objects/badge.svg            |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: Downloads                                                |
+|                                       | .. image:: https://pypip.in/license/Objects/badge.svg             |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: License                                                  |
++---------------------------------------+-------------------------------------------------------------------+
+| *Python versions and implementations* | .. image:: https://pypip.in/py_versions/Objects/badge.svg         |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: Supported Python versions                                |
+|                                       | .. image:: https://pypip.in/implementation/Objects/badge.svg      |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: Supported Python implementations                         |
++---------------------------------------+-------------------------------------------------------------------+
+| *Builds and test coverage*            | .. image:: https://travis-ci.org/rmk135/objects.svg?branch=master |
+|                                       |    :target: https://travis-ci.org/rmk135/objects                  |
+|                                       |    :alt: Build Status                                             |
+|                                       | .. image:: https://coveralls.io/repos/rmk135/objects/badge.svg    |
+|                                       |    :target: https://coveralls.io/r/rmk135/objects                 |
+|                                       |    :alt: Coverage Status                                          |
++---------------------------------------+-------------------------------------------------------------------+
 
-.. image:: https://img.shields.io/pypi/l/dependency_injector.svg
+Introduction
-   :target: https://pypi.org/project/dependency-injector/
+------------
-   :alt: License
 
-.. image:: https://img.shields.io/pypi/pyversions/dependency_injector.svg
+Python ecosystem consists of a big amount of various classes, functions and
-   :target: https://pypi.org/project/dependency-injector/
+objects that could be used for applications development. Each of them has its
-   :alt: Supported Python versions
+own role.
 
-.. image:: https://img.shields.io/pypi/implementation/dependency_injector.svg
+Modern Python applications are mostly the composition of well-known open
-   :target: https://pypi.org/project/dependency-injector/
+source systems, frameworks, libraries and some turnkey functionality.
-   :alt: Supported Python implementations
 
-.. image:: https://pepy.tech/badge/dependency-injector
+When application goes bigger, its amount of objects and their dependencies
-   :target: https://pepy.tech/project/dependency-injector
+also increased extremely fast and became hard to maintain.
-   :alt: Downloads
 
-.. image:: https://pepy.tech/badge/dependency-injector/month
+**Objects** is designed to be developer's friendly tool for managing objects
-   :target: https://pepy.tech/project/dependency-injector
+and their dependencies in formal, pretty way. Main idea of **Objects** is to
-   :alt: Downloads
+keep dependencies under control.
-
-.. image:: https://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
-
-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`_::
+**Objects** library is available on PyPi_::
 
-    pip install dependency-injector
+    pip install objects
 
 Documentation
 -------------
 
-The documentation is available `here <https://python-dependency-injector.ets-labs.org/>`_.
+**Objects** documentation is hosted on ReadTheDocs:
+
+- `Stable version`_
+- `Latest version`_
 
 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 `Objects`."""
-- `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
+    from objects.catalog import AbstractCatalog
----------
 
-Choose one of the following:
+    from objects.providers import Singleton
+    from objects.providers import NewInstance
 
-- `Flask web application tutorial <https://python-dependency-injector.ets-labs.org/tutorials/flask.html>`_
+    from objects.injections import KwArg
-- `Aiohttp REST API tutorial <https://python-dependency-injector.ets-labs.org/tutorials/aiohttp.html>`_
+    from objects.injections import Attribute
-- `Asyncio monitoring daemon tutorial <https://python-dependency-injector.ets-labs.org/tutorials/asyncio-daemon.html>`_
+    from objects.injections import inject
-- `CLI application tutorial <https://python-dependency-injector.ets-labs.org/tutorials/cli.html>`_
 
-Concept
+    import sqlite3
--------
 
-The framework stands on the `PEP20 (The Zen of Python) <https://www.python.org/dev/peps/pep-0020/>`_ principle:
 
-.. code-block:: bash
+    class ObjectA(object):
 
-   Explicit is better than implicit
+        """Example class ObjectA, that has dependency on database."""
 
-You need to specify how to assemble and where to inject the dependencies explicitly.
+        def __init__(self, db):
+            """Initializer."""
+            self.db = db
 
-The power of the framework is in its simplicity.
-``Dependency Injector`` is a simple tool for the powerful concept.
 
-Frequently asked questions
+    class ObjectB(object):
---------------------------
 
-What is dependency injection?
+        """Example class ObjectB, that has dependencies on ObjectA and database."""
- - dependency injection is a principle that decreases coupling and increases cohesion
 
-Why should I do the dependency injection?
+        def __init__(self, a, db):
- - your code becomes more flexible, testable, and clear 😎
+            """Initializer."""
+            self.a = a
+            self.db = db
 
-How do I start applying the dependency injection?
- - you start writing the code following the dependency injection principle
- - you register all of your application components and their dependencies in the container
- - when you need a component, you specify where to inject it or get it from the container
 
-What price do I pay and what do I get?
+    class Catalog(AbstractCatalog):
- - you need to explicitly specify the dependencies
- - it will be extra work in the beginning
- - it will payoff as project grows
 
-Have a question?
+        """Catalog of objects providers."""
- - Open a `Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_
 
-Found a bug?
+        database = Singleton(sqlite3.Connection,
- - Open a `Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_
+                             KwArg('database', ':memory:'),
+                             Attribute('row_factory', sqlite3.Row))
+        """:type: (objects.Provider) -> sqlite3.Connection"""
 
-Want to help?
+        object_a = NewInstance(ObjectA,
- - |star| Star the ``Dependency Injector`` on the `Github <https://github.com/ets-labs/python-dependency-injector/>`_
+                               KwArg('db', database))
- - |new| Start a new project with the ``Dependency Injector``
+        """:type: (objects.Provider) -> ObjectA"""
- - |tell| Tell your friend about the ``Dependency Injector``
 
-Want to contribute?
+        object_b = NewInstance(ObjectB,
- - |fork| Fork the project
+                               KwArg('a', object_a),
- - |pull| Open a pull request to the ``develop`` branch
+                               KwArg('db', database))
+        """:type: (objects.Provider) -> ObjectB"""
 
-.. _PyPi: https://pypi.org/project/dependency-injector/
 
-.. |star| unicode:: U+2B50 U+FE0F .. star sign1
+    # Catalog static provides.
-.. |new| unicode:: U+1F195 .. new sign
+    a1, a2 = Catalog.object_a(), Catalog.object_a()
-.. |tell| unicode:: U+1F4AC .. tell sign
+    b1, b2 = Catalog.object_b(), Catalog.object_b()
-.. |fork| unicode:: U+1F500 .. fork sign
+
-.. |pull| unicode:: U+2B05 U+FE0F .. pull sign
+    assert a1 is not a2
+    assert b1 is not b2
+    assert a1.db is a2.db is b1.db is b2.db is Catalog.database()
+
+
+    # Example of inline injections.
+    @inject(KwArg('a', Catalog.object_a))
+    @inject(KwArg('b', Catalog.object_b))
+    @inject(KwArg('database', Catalog.database))
+    def example(a, b, database):
+        assert a.db is b.db is database is Catalog.database()
+
+
+    example()
+
+You can get more **Objects** examples in ``/examples`` directory on
+GitHub:
+
+    https://github.com/rmk135/objects
+
+
+Feedback
+--------
+
+Feel free to post questions, bugs, feature requests, proposals etc. on
+**Objects**  GitHub Issues:
+
+    https://github.com/rmk135/objects/issues
+
+Your feedback is quite important!
+
+
+.. _PyPi: https://pypi.python.org/pypi/Objects
+.. _Stable version: http://objects.readthedocs.org/en/stable/
+.. _Latest version: http://objects.readthedocs.org/en/latest/

VERSION

@@ -0,0 +1 @@
+0.7.3

docs/Makefile

@@ -87,9 +87,9 @@ qthelp:
 	@echo
 	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
 	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/dependency_injector.qhcp"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/objects.qhcp"
 	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/dependency_injector.qhc"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/objects.qhc"
 
 applehelp:
 	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@@ -104,8 +104,8 @@ devhelp:
 	@echo
 	@echo "Build finished."
 	@echo "To view the help file:"
-	@echo "# mkdir -p $$HOME/.local/share/devhelp/dependency_injector"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/objects"
-	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/dependency_injector"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/objects"
 	@echo "# devhelp"
 
 epub:

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

@@ -0,0 +1,201 @@
+Advanced usage
+==============
+
+Below you can find some variants of advanced usage of **Objects**.
+
+@inject decorator
+-----------------
+
+``@inject`` decorator could be used for patching any callable with injection.
+Any Python object will be injected *as is*, except **Objects** providers,
+that will be called to provide injectable value.
+
+.. code-block:: python
+
+    """`@inject` decorator example."""
+
+    from objects.providers import NewInstance
+
+    from objects.injections import KwArg
+    from objects.injections import inject
+
+
+    new_object = NewInstance(object)
+
+
+    @inject(KwArg('object_a', new_object))
+    @inject(KwArg('some_setting', 1334))
+    def example_callback(object_a, some_setting):
+        """This function has dependencies on object a and b.
+
+        Dependencies are injected using `@inject` decorator.
+        """
+        assert isinstance(object_a, object)
+        assert some_setting == 1334
+
+
+    example_callback()
+    example_callback()
+
+Overriding providers
+--------------------
+
+Any provider can be overridden by another provider.
+
+Example:
+
+.. code-block:: python
+
+    """Provider overriding example."""
+
+    import sqlite3
+
+    from objects.providers import Singleton
+    from objects.providers import NewInstance
+
+    from objects.injections import KwArg
+    from objects.injections import Attribute
+
+
+    class ObjectA(object):
+
+        """ObjectA has dependency on database."""
+
+        def __init__(self, database):
+            """Initializer.
+
+            Database dependency need to be injected via init arg."""
+            self.database = database
+
+        def get_one(self):
+            """Select one from database and return it."""
+            return self.database.execute('SELECT 1')
+
+
+    class ObjectAMock(ObjectA):
+
+        """Mock of ObjectA.
+
+        Has no dependency on database.
+        """
+
+        def __init__(self):
+            """Initializer."""
+
+        def get_one(self):
+            """Select one from database and return it.
+
+            Mock makes no database queries and always returns two instead of one.
+            """
+            return 2
+
+
+    # Database and `ObjectA` providers.
+    database = Singleton(sqlite3.Connection,
+                         KwArg('database', ':memory:'),
+                         KwArg('timeout', 30),
+                         KwArg('detect_types', True),
+                         KwArg('isolation_level', 'EXCLUSIVE'),
+                         Attribute('row_factory', sqlite3.Row))
+
+    object_a = NewInstance(ObjectA,
+                           KwArg('database', database))
+
+
+    # Overriding `ObjectA` provider with `ObjectAMock` provider.
+    object_a.override(NewInstance(ObjectAMock))
+
+    # Creating several `ObjectA` instances.
+    object_a_1 = object_a()
+    object_a_2 = object_a()
+
+    # Making some asserts.
+    assert object_a_1 is not object_a_2
+    assert object_a_1.get_one() == object_a_2.get_one() == 2
+
+Overriding catalogs
+-------------------
+
+Any catalog can be overridden by another catalog.
+
+Example:
+
+.. code-block:: python
+
+    """Catalog overriding example."""
+
+    import sqlite3
+
+    from objects.catalog import AbstractCatalog
+    from objects.catalog import override
+
+    from objects.providers import Singleton
+    from objects.providers import NewInstance
+
+    from objects.injections import KwArg
+    from objects.injections import Attribute
+
+
+    class ObjectA(object):
+
+        """ObjectA has dependency on database."""
+
+        def __init__(self, database):
+            """Initializer.
+
+            Database dependency need to be injected via init arg."""
+            self.database = database
+
+        def get_one(self):
+            """Select one from database and return it."""
+            return self.database.execute('SELECT 1')
+
+
+    class ObjectAMock(ObjectA):
+
+        """Mock of ObjectA.
+
+        Has no dependency on database.
+        """
+
+        def __init__(self):
+            """Initializer."""
+
+        def get_one(self):
+            """Select one from database and return it.
+
+            Mock makes no database queries and always returns two instead of one.
+            """
+            return 2
+
+
+    class Catalog(AbstractCatalog):
+
+        """Catalog of objects providers."""
+
+        database = Singleton(sqlite3.Connection,
+                             KwArg('database', ':memory:'),
+                             KwArg('timeout', 30),
+                             KwArg('detect_types', True),
+                             KwArg('isolation_level', 'EXCLUSIVE'),
+                             Attribute('row_factory', sqlite3.Row))
+
+        object_a = NewInstance(ObjectA,
+                               KwArg('database', database))
+
+
+    @override(Catalog)
+    class SandboxCatalog(Catalog):
+
+        """Sandbox objects catalog with some mocks that overrides Catalog."""
+
+        object_a = NewInstance(ObjectAMock)
+
+
+    # Creating several `ObjectA` instances.
+    object_a_1 = Catalog.object_a()
+    object_a_2 = Catalog.object_a()
+
+    # Making some asserts.
+    assert object_a_1 is not object_a_2
+    assert object_a_1.get_one() == object_a_2.get_one() == 2

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/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 +0,0 @@
-dependency_injector.errors
-==========================
-
-.. automodule:: dependency_injector.errors
-   :members:
-
-
-.. disqus::

docs/api/index.rst

@@ -1,12 +0,0 @@
-API Documentation
-=================
-
-..  toctree::
-   :maxdepth: 2
-
-   top-level
-   providers
-   containers
-   wiring
-   errors
-   asgi-lifespan

docs/api/providers.rst

@@ -1,10 +0,0 @@
-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/wiring.rst

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

docs/conf.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Dependency Injector documentation build configuration file, created by
+# Objects documentation build configuration file, created by
 # sphinx-quickstart on Wed Apr  1 17:36:06 2015.
 #
 # This file is execfile()d with the current directory set to its
@@ -13,56 +13,49 @@
 # serve to show the default.
 
 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 = []
-    "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'Objects'
-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:
+# Getting version.
-with open("../src/dependency_injector/__init__.py") as init_file:
+with open('../VERSION') as version:
-    version = re.search("__version__ = \"(.*?)\"", init_file.read()).group(1)
+    version = version.read().strip()
 
 # The full version, including alpha/beta/rc tags.
 release = version
@@ -72,23 +65,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 +93,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 +109,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 +133,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 = ['_static']
-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 +181,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 = 'objectsdoc'
+
+# 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, 'Objects.tex', u'Objects 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 +264,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, 'Objects', u'Objects Documentation',
      [author], 1)
 ]
 
@@ -278,9 +278,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, 'Objects', u'Objects Documentation',
-   author, "Dependency Injector", "Dependency injection microframework for Python",
+   author, 'Objects', 'Dependency management tool for Python projects.',
-   "Miscellaneous"),
+   'Miscellaneous'),
 ]
 
 # Documents to append as an appendix to all manuals.
@@ -289,25 +289,8 @@ 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"
-
-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/entities.rst

@@ -0,0 +1,187 @@
+Entities
+========
+
+Current section describes main **Objects** entities and their interaction.
+
+Providers
+---------
+
+Providers are strategies of accessing objects.
+
+All providers are callable. They describe how particular objects will be
+provided. For example:
+
+.. code-block:: python
+
+    """`NewInstance` and `Singleton` providers example."""
+
+    from objects.providers import NewInstance
+    from objects.providers import Singleton
+
+
+    # NewInstance provider will create new instance of specified class
+    # on every call.
+    new_object = NewInstance(object)
+
+    object_1 = new_object()
+    object_2 = new_object()
+
+    assert object_1 is not object_2
+
+    # Singleton provider will create new instance of specified class on first call,
+    # and return same instance on every next call.
+    single_object = Singleton(object)
+
+    single_object_1 = single_object()
+    single_object_2 = single_object()
+
+    assert single_object_1 is single_object_2
+
+Injections
+----------
+
+Injections are additional instructions, that are used for determining
+dependencies of objects.
+
+Objects can take dependencies in various forms. Some objects take init
+arguments, other are using attributes or methods to be initialized. Injection,
+in terms of **Objects**, is an instruction how to provide dependency for the
+particular object.
+
+Every Python object could be an injection's value. Special case is a **Objects**
+provider as an injection's value. In such case, injection value is a result of
+injectable provider call (every time injection is done).
+
+Injections are used by providers.
+
+.. code-block:: python
+
+    """`KwArg` and `Attribute` injections example."""
+
+    import sqlite3
+
+    from objects.providers import Singleton
+    from objects.providers import NewInstance
+
+    from objects.injections import KwArg
+    from objects.injections import Attribute
+
+
+    class ObjectA(object):
+
+        """ObjectA has dependency on database."""
+
+        def __init__(self, database):
+            """Initializer.
+
+            Database dependency need to be injected via init arg."""
+            self.database = database
+
+        def get_one(self):
+            """Select one from database and return it."""
+            return self.database.execute('SELECT 1').fetchone()[0]
+
+
+    # Database and `ObjectA` providers.
+    database = Singleton(sqlite3.Connection,
+                         KwArg('database', ':memory:'),
+                         KwArg('timeout', 30),
+                         KwArg('detect_types', True),
+                         KwArg('isolation_level', 'EXCLUSIVE'),
+                         Attribute('row_factory', sqlite3.Row))
+
+    object_a = NewInstance(ObjectA,
+                           KwArg('database', database))
+
+    # Creating several `ObjectA` instances.
+    object_a_1 = object_a()
+    object_a_2 = object_a()
+
+    # Making some asserts.
+    assert object_a_1 is not object_a_2
+    assert object_a_1.database is object_a_2.database
+    assert object_a_1.get_one() == object_a_2.get_one() == 1
+
+Catalogs
+--------
+
+Catalogs are named set of providers.
+
+**Objects** catalogs can be used for grouping of providers by some
+kind of rules. In example below, there are two catalogs:
+``Resources`` and ``Models``.
+
+``Resources`` catalog is used to group all common application resources like
+database connection and various api clients, while ``Models`` catalog is used
+for application model providers only.
+
+.. code-block:: python
+
+    """Catalogs example."""
+
+    import sqlite3
+    import httplib
+
+    from objects.catalog import AbstractCatalog
+
+    from objects.providers import Singleton
+    from objects.providers import NewInstance
+
+    from objects.injections import KwArg
+    from objects.injections import Attribute
+
+
+    class SomeModel(object):
+
+        """SomeModel has dependency on database and api client.
+
+        Dependencies need to be injected via init args.
+        """
+
+        def __init__(self, database, api_client):
+            """Initializer."""
+            self.database = database
+            self.api_client = api_client
+
+        def api_request(self):
+            """Make api request."""
+            self.api_client.request('GET', '/')
+            return self.api_client.getresponse()
+
+        def get_one(self):
+            """Select one from database and return it."""
+            return self.database.execute('SELECT 1').fetchone()[0]
+
+
+    class Resources(AbstractCatalog):
+
+        """Resource providers catalog."""
+
+        database = Singleton(sqlite3.Connection,
+                             KwArg('database', ':memory:'),
+                             KwArg('timeout', 30),
+                             KwArg('detect_types', True),
+                             KwArg('isolation_level', 'EXCLUSIVE'),
+                             Attribute('row_factory', sqlite3.Row))
+
+        api_client = Singleton(httplib.HTTPConnection,
+                               KwArg('host', 'example.com'),
+                               KwArg('port', 80),
+                               KwArg('timeout', 10))
+
+
+    class Models(AbstractCatalog):
+
+        """Model providers catalog."""
+
+        some_model = NewInstance(SomeModel,
+                                 KwArg('database', Resources.database),
+                                 KwArg('api_client', Resources.api_client))
+
+
+    # Creating `SomeModel` instance.
+    some_model = Models.some_model()
+
+    # Making some asserts.
+    assert some_model.get_one() == 1
+    assert some_model.api_request().status == 200

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

@@ -0,0 +1,8 @@
+Examples
+========
+
+You can get more **Objects** examples in ``/examples`` directory on
+GitHub:
+
+    https://github.com/rmk135/objects
+

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/feedback.rst

@@ -0,0 +1,9 @@
+Feedback
+========
+
+Feel free to post questions, bugs, feature requests, proposals etc. on
+**Objects**  GitHub Issues:
+
+    https://github.com/rmk135/objects/issues
+
+Your feedback is quite important!

docs/index.rst

@@ -1,150 +1,44 @@
-=================================================================
+Objects
-Dependency Injector --- Dependency injection framework for Python
+=======
-=================================================================
 
-.. meta::
+Dependency management tool 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://pypip.in/version/Objects/badge.svg             |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: Latest Version                                           |
+|                                       | .. image:: https://pypip.in/download/Objects/badge.svg            |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: Downloads                                                |
+|                                       | .. image:: https://pypip.in/license/Objects/badge.svg             |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: License                                                  |
++---------------------------------------+-------------------------------------------------------------------+
+| *Python versions and implementations* | .. image:: https://pypip.in/py_versions/Objects/badge.svg         |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: Supported Python versions                                |
+|                                       | .. image:: https://pypip.in/implementation/Objects/badge.svg      |
+|                                       |    :target: https://pypi.python.org/pypi/Objects/                 |
+|                                       |    :alt: Supported Python implementations                         |
++---------------------------------------+-------------------------------------------------------------------+
+| *Builds and test coverage*            | .. image:: https://travis-ci.org/rmk135/objects.svg?branch=master |
+|                                       |    :target: https://travis-ci.org/rmk135/objects                  |
+|                                       |    :alt: Build Status                                             |
+|                                       | .. image:: https://coveralls.io/repos/rmk135/objects/badge.svg    |
+|                                       |    :target: https://coveralls.io/r/rmk135/objects                 |
+|                                       |    :alt: Coverage Status                                          |
++---------------------------------------+-------------------------------------------------------------------+
 
-.. image:: https://img.shields.io/pypi/v/dependency_injector.svg
-   :target: https://pypi.org/project/dependency-injector/
-   :alt: Latest Version
-
-.. image:: https://img.shields.io/pypi/l/dependency_injector.svg
-   :target: https://pypi.org/project/dependency-injector/
-   :alt: License
-
-.. image:: https://img.shields.io/pypi/pyversions/dependency_injector.svg
-   :target: https://pypi.org/project/dependency-injector/
-   :alt: Supported Python versions
-
-.. image:: https://img.shields.io/pypi/implementation/dependency_injector.svg
-   :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
+    introduction
-   examples/index
+    installation
-   tutorials/index
+    entities
-   providers/index
+    advanced_usage
-   containers/index
+    examples
-   wiring
+    feedback
-   examples-other/index
-   api/index
-   main/feedback
-   main/changelog

docs/installation.rst

@@ -0,0 +1,15 @@
+Installation
+============
+
+Latest stable version of **Objects** library can be installed from PyPi_::
+
+    pip install objects
+
+Sources can be cloned from GitHub_::
+
+    git clone https://github.com/rmk135/objects.git
+
+All **Objects** releases can be found on GitHub: https://github.com/rmk135/objects/releases
+
+.. _PyPi: https://pypi.python.org/pypi/Objects
+.. _GitHub: https://github.com/rmk135/objects

docs/introduction.rst

@@ -0,0 +1,16 @@
+Introduction
+============
+
+Python ecosystem consists of a big amount of various classes, functions and
+objects that could be used for applications development. Each of them has its
+own role.
+
+Modern Python applications are mostly the composition of well-known open
+source systems, frameworks, libraries and some turnkey functionality.
+
+When application goes bigger, its amount of objects and their dependencies
+also increased extremely fast and became hard to maintain.
+
+**Objects** is designed to be developer's friendly tool for managing objects
+and their dependencies in formal, pretty way. Main idea of **Objects** is to
+keep dependencies under control.

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

docs/introduction/index.rst

@@ -1,18 +0,0 @@
-Introduction
-============
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control
-   :description: Current section of the documentation is provides an
-                 overview of the dependency injection, inversion of
-                 control and Dependency Injector framework.
-
-The current section of the documentation provides an overview of the
-dependency injection, inversion of control, and the ``Dependency Injector`` framework.
-
-..  toctree::
-    :maxdepth: 2
-
-    di_in_python
-    key_features
-    installation

docs/introduction/installation.rst

@@ -1,42 +0,0 @@
-Installation
-============
-
-``Dependency Injector`` is available on `PyPI <https://pypi.org/project/dependency-injector/>`_.
-To install the latest version you can use ``pip``:
-
-.. code-block:: bash
-
-    pip install dependency-injector
-
-Some modules of the ``Dependency Injector`` are implemented as C extensions.
-``Dependency Injector`` is distributed as a pre-compiled wheels. Wheels are
-available for all supported Python versions on Linux, Windows, and MacOS.
-Linux distribution uses `manylinux <https://github.com/pypa/manylinux>`_.
-
-If there is no appropriate wheel for your environment (Python version and OS)
-installer will compile the package from sources on your machine. You'll need
-a C compiler and Python header files.
-
-To verify the installed version:
-
-.. code-block:: bash
-
-    >>> import dependency_injector
-    >>> dependency_injector.__version__
-    '4.39.0'
-
-.. note::
-   When adding ``Dependency Injector`` to ``pyproject.toml`` or ``requirements.txt``
-   don't forget to pin the version to the current major:
-
-   .. code-block:: bash
-
-       dependency-injector>=4.0,<5.0
-
-   *The next major version can be incompatible.*
-
-All releases are available on the `PyPI release history page <https://pypi.org/project/dependency-injector/#history>`_.
-Each release has an appropriate tag. The tags are available on the
-`GitHub releases page <https://github.com/ets-labs/python-dependency-injector/releases>`_.
-
-.. disqus::

docs/introduction/key_features.rst

@@ -1,43 +0,0 @@
-.. _key-features:
-
-Key features
-------------
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control
-   :description: This article describes key features of the Dependency Injector
-                 framework.
-
-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.
-
-The framework stands on the `PEP20 (The Zen of Python) <https://www.python.org/dev/peps/pep-0020/>`_ principle:
-
-.. code-block:: text
-
-   Explicit is better than implicit
-
-You need to specify how to assemble and where to inject the dependencies explicitly.
-
-The power of the framework is in its simplicity.
-``Dependency Injector`` is a simple tool for the powerful concept.
-
-.. disqus::

docs/main/feedback.rst

@@ -1,8 +0,0 @@
-Feedback
-========
-
-To post a question, bug report, a feature proposal or get some help open a
-`Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_ or leave a comment
-below.
-
-.. disqus::

docs/providers/aggregate.rst

@@ -1,72 +0,0 @@
-.. _aggregate-provider:
-
-Aggregate provider
-==================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Configuration,Injection,
-              Aggregate,Polymorphism,Environment Variable,Flexibility
-   :description: Aggregate provider aggregates other providers.
-                 This page demonstrates how to implement the polymorphism and increase the
-                 flexibility of your application using the Aggregate provider.
-
-:py:class:`Aggregate` provider aggregates a group of other providers.
-
-.. currentmodule:: dependency_injector.providers
-
-.. literalinclude:: ../../examples/providers/aggregate.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 24-27
-
-Each provider in the ``Aggregate`` is associated with a key. You can call aggregated providers by providing
-their key as a first argument. All positional and keyword arguments following the key will be forwarded to
-the called provider:
-
-.. code-block:: python
-
-   yaml_reader = container.config_readers("yaml", "./config.yml", foo=...)
-
-You can also retrieve an aggregated provider by providing its key as an attribute name:
-
-.. code-block:: python
-
-   yaml_reader = container.config_readers.yaml("./config.yml", foo=...)
-
-To retrieve a dictionary of aggregated providers, use ``.providers`` attribute:
-
-.. code-block:: python
-
-   container.config_readers.providers == {
-       "yaml": <YAML provider>,
-       "json": <JSON provider>,
-   }
-
-.. note::
-   You can not override the ``Aggregate`` provider.
-
-.. note::
-   When you inject the ``Aggregate`` provider, it is passed "as is".
-
-To use non-string keys or string keys with ``.`` and ``-``, provide a dictionary as a positional argument:
-
-.. code-block:: python
-
-   aggregate = providers.Aggregate({
-       SomeClass: providers.Factory(...),
-       "key.with.periods": providers.Factory(...),
-       "key-with-dashes": providers.Factory(...),
-   })
-
-.. seealso::
-   :ref:`selector-provider` to make injections based on a configuration value, environment variable, or a result of a callable.
-
-   ``Aggregate`` provider is different from the :ref:`selector-provider`. ``Aggregate`` provider doesn't select which provider
-   to inject and doesn't have a selector. It is a group of providers and is always injected "as is". The rest of the interface
-   of both providers is similar.
-
-.. note::
-   ``Aggregate`` provider is a successor of :ref:`factory-aggregate-provider` provider. ``Aggregate`` provider doesn't have
-   a restriction on the provider type, while ``FactoryAggregate`` aggregates only ``Factory`` providers.
-
-.. disqus::

docs/providers/async.rst

@@ -1,110 +0,0 @@
-.. _async-injections:
-
-Asynchronous injections
-=======================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Providers,Async,Injections,Asynchronous,Await,
-              Asyncio
-   :description: Dependency Injector providers support asynchronous injections. This page
-                 demonstrates how make asynchronous dependency injections in Python.
-
-Providers support asynchronous injections.
-
-.. literalinclude:: ../../examples/providers/async.py
-   :language: python
-   :emphasize-lines: 26-29
-   :lines: 3-
-
-If provider has any awaitable injections it switches into async mode. In async mode provider always returns awaitable.
-This causes a cascade effect:
-
-.. code-block:: bash
-
-   provider1()              <── Async mode enabled <──┐
-   │                                                  │
-   ├──> provider2()                                   │
-   │                                                  │
-   ├──> provider3()         <── Async mode enabled <──┤
-   │    │                                             │
-   │    └──> provider4()    <── Async provider ───────┘
-   │
-   └──> provider5()
-        │
-        └──> provider6()
-
-In async mode provider prepares injections asynchronously.
-
-If provider has multiple awaitable dependencies, it will run them concurrently. Provider will wait until all
-dependencies are ready and inject them afterwards.
-
-.. code-block:: bash
-
-   provider1()
-   │
-   ├──> provider2()         <── Async mode enabled
-   │
-   ├──> provider3()         <── Async mode enabled
-   │
-   └──> provider4()         <── Async mode enabled
-
-Here is what provider will do for the previous example:
-
-.. code-block:: python
-
-   injections = await asyncio.gather(
-       provider2(),
-       provider3(),
-       provider4(),
-   )
-   await provider1(*injections)
-
-Overriding behaviour
---------------------
-
-In async mode provider always returns awaitable. It applies to the overriding too. If provider in async mode is
-overridden by a provider that doesn't return awaitable result, the result will be wrapped into awaitable.
-
-.. literalinclude:: ../../examples/providers/async_overriding.py
-   :language: python
-   :emphasize-lines: 19-24
-   :lines: 3-
-
-Async mode mechanics and API
-----------------------------
-
-By default provider's async mode is undefined.
-
-When provider async mode is undefined, provider will automatically select the mode during the next call.
-If the result is awaitable, provider will enable async mode, if not - disable it.
-
-If provider async mode is enabled, provider always returns awaitable. If the result is not awaitable,
-provider wraps it into awaitable explicitly. You can safely ``await`` provider in async mode.
-
-If provider async mode is disabled, provider behaves the regular way. It doesn't do async injections
-preparation or non-awaitables to awaitables conversion.
-
-Once provider async mode is enabled or disabled, provider will stay in this state. No automatic switching
-will be done.
-
-.. image:: images/async_mode.png
-
-You can also use following methods to change provider's async mode manually:
-
-- ``Provider.enable_async_mode()``
-- ``Provider.disable_async_mode()``
-- ``Provider.reset_async_mode()``
-
-To check the state of provider's async mode use:
-
-- ``Provider.is_async_mode_enabled()``
-- ``Provider.is_async_mode_disabled()``
-- ``Provider.is_async_mode_undefined()``
-
-See also:
-
-- Wiring :ref:`async-injections-wiring`
-- Resource provider :ref:`resource-async-initializers`
-- :ref:`fastapi-redis-example`
-
-.. disqus::

docs/providers/callable.rst

@@ -1,20 +0,0 @@
-Callable provider
-=================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Function,Method,Example
-   :description: Callable provider helps to make dependencies injection into functions. This page
-                 demonstrates how to use a Callable provider.
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`Callable` provider calls a function, a method or another callable.
-
-.. literalinclude:: ../../examples/providers/callable.py
-   :language: python
-   :lines: 3-
-
-``Callable`` provider handles an injection of the dependencies the same way like a
-:ref:`factory-provider`.
-
-.. disqus::

docs/providers/configuration.rst

@@ -1,579 +0,0 @@
-.. _configuration-provider:
-
-Configuration provider
-======================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Configuration,Injection,
-              Option,Ini,Json,Yaml,Pydantic,Dict,Environment Variable Interpolation,
-              Environment Variable Substitution,Environment Variable in Config,
-              Environment Variable in YAML file,Environment Variable in INI file,Default,Load,Read
-   :description: Configuration provides configuration options to the other providers. This page
-                 demonstrates how to use Configuration provider to inject the dependencies, load
-                 a configuration from an ini or yaml file, a dictionary, an environment variable,
-                 or a pydantic settings object. This page also describes how to substitute (interpolate)
-                 environment variables in YAML and INI configuration files.
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`Configuration` provider provides configuration options to the other providers.
-
-.. literalinclude:: ../../examples/providers/configuration/configuration.py
-   :language: python
-   :emphasize-lines: 7,12-13
-   :lines: 3-
-
-It implements the principle "use first, define later".
-
-.. contents::
-   :local:
-   :backlinks: none
-
-Loading from an INI file
-------------------------
-
-``Configuration`` provider can load configuration from an ``ini`` file using the
-:py:meth:`Configuration.from_ini` method:
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_ini.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12
-
-where ``examples/providers/configuration/config.ini`` is:
-
-.. literalinclude:: ../../examples/providers/configuration/config.ini
-   :language: ini
-
-Alternatively, you can provide a path to the INI file over the configuration provider argument. In that case,
-the container will call ``config.from_ini()`` automatically:
-
-.. code-block:: python
-   :emphasize-lines: 3
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration(ini_files=["./config.ini"])
-
-
-   if __name__ == "__main__":
-       container = Container()  # Config is loaded from ./config.ini
-
-
-:py:meth:`Configuration.from_ini` method supports environment variables interpolation.
-
-.. code-block:: ini
-
-   [section]
-   option1 = ${ENV_VAR}
-   option2 = ${ENV_VAR}/path
-   option3 = ${ENV_VAR:default}
-
-See also: :ref:`configuration-envs-interpolation`.
-
-Loading from a YAML file
-------------------------
-
-``Configuration`` provider can load configuration from a ``yaml`` file using the
-:py:meth:`Configuration.from_yaml` method:
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_yaml.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12
-
-where ``examples/providers/configuration/config.yml`` is:
-
-.. literalinclude:: ../../examples/providers/configuration/config.yml
-   :language: ini
-
-Alternatively, you can provide a path to the YAML file over the configuration provider argument. In that case,
-the container will call ``config.from_yaml()`` automatically:
-
-.. code-block:: python
-   :emphasize-lines: 3
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration(yaml_files=["./config.yml"])
-
-
-   if __name__ == "__main__":
-       container = Container()  # Config is loaded from ./config.yml
-
-:py:meth:`Configuration.from_yaml` method supports environment variables interpolation.
-
-.. code-block:: ini
-
-   section:
-     option1: ${ENV_VAR}
-     option2: ${ENV_VAR}/path
-     option3: ${ENV_VAR:default}
-
-See also: :ref:`configuration-envs-interpolation`.
-
-:py:meth:`Configuration.from_yaml` method uses custom version of ``yaml.SafeLoader``.
-To use another loader use ``loader`` argument:
-
-.. code-block:: python
-
-   import yaml
-
-
-   container.config.from_yaml("config.yml", loader=yaml.UnsafeLoader)
-
-.. note::
-
-   Loading of a yaml configuration requires ``PyYAML`` package.
-
-   You can install the ``Dependency Injector`` with an extra dependency::
-
-      pip install dependency-injector[yaml]
-
-   or install ``PyYAML`` directly::
-
-      pip install pyyaml
-
-   *Don't forget to mirror the changes in the requirements file.*
-
-Loading from a JSON file
-------------------------
-
-``Configuration`` provider can load configuration from a ``json`` file using the
-:py:meth:`Configuration.from_json` method:
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_json.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12
-
-where ``examples/providers/configuration/config.json`` is:
-
-.. literalinclude:: ../../examples/providers/configuration/config.json
-   :language: json
-
-Alternatively, you can provide a path to a json file over the configuration provider argument. In that case,
-the container will call ``config.from_json()`` automatically:
-
-.. code-block:: python
-   :emphasize-lines: 3
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration(json_files=["./config.json"])
-
-
-   if __name__ == "__main__":
-       container = Container()  # Config is loaded from ./config.json
-
-:py:meth:`Configuration.from_json` method supports environment variables interpolation.
-
-.. code-block:: json
-
-   {
-       "section": {
-           "option1": "${ENV_VAR}",
-           "option2": "${ENV_VAR}/path",
-           "option3": "${ENV_VAR:default}"
-       }
-   }
-
-See also: :ref:`configuration-envs-interpolation`.
-
-Loading from a Pydantic settings
---------------------------------
-
-``Configuration`` provider can load configuration from a ``pydantic_settings.BaseSettings`` object using the
-:py:meth:`Configuration.from_pydantic` method:
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_pydantic.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 32
-
-To get the data from pydantic settings ``Configuration`` provider calls its ``model_dump()`` method.
-If you need to pass an argument to this call, use ``.from_pydantic()`` keyword arguments.
-
-.. code-block:: python
-
-   container.config.from_pydantic(Settings(), exclude={"optional"})
-
-Alternatively, you can provide a ``pydantic_settings.BaseSettings`` object over the configuration provider argument. In that case,
-the container will call ``config.from_pydantic()`` automatically:
-
-.. code-block:: python
-   :emphasize-lines: 3
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration(pydantic_settings=[Settings()])
-
-
-   if __name__ == "__main__":
-       container = Container()  # Config is loaded from Settings()
-
-
-.. note::
-
-   ``Dependency Injector`` doesn't install ``pydantic-settings`` by default.
-
-   You can install the ``Dependency Injector`` with an extra dependency::
-
-      pip install dependency-injector[pydantic2]
-
-   or install ``pydantic-settings`` directly::
-
-      pip install pydantic-settings
-
-   *Don't forget to mirror the changes in the requirements file.*
-
-.. note::
-
-   For backward-compatibility, Pydantic v1 is still supported.
-   Passing ``pydantic.BaseSettings`` instances will work just as fine as ``pydantic_settings.BaseSettings``.
-
-Loading from a dictionary
--------------------------
-
-``Configuration`` provider can load configuration from a Python ``dict`` using the
-:py:meth:`Configuration.from_dict` method:
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_dict.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12-19
-
-Loading from an environment variable
-------------------------------------
-
-``Configuration`` provider can load configuration from an environment variable using the
-:py:meth:`Configuration.from_env` method:
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_env.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 18-20
-
-You can use ``as_`` argument for the type casting of an environment variable value:
-
-.. code-block:: python
-   :emphasize-lines: 2,6,10
-
-   # API_KEY=secret
-   container.config.api_key.from_env("API_KEY", as_=str, required=True)
-   assert container.config.api_key() == "secret"
-
-   # SAMPLING_RATIO=0.5
-   container.config.sampling.from_env("SAMPLING_RATIO", as_=float, required=True)
-   assert container.config.sampling() == 0.5
-
-   # TIMEOUT undefined, default is used
-   container.config.timeout.from_env("TIMEOUT", as_=int, default=5)
-   assert container.config.timeout() == 5
-
-
-Loading a value
----------------
-
-``Configuration`` provider can load configuration value using the
-:py:meth:`Configuration.from_value` method:
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_value.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 14-15
-
-Loading from the multiple sources
----------------------------------
-
-``Configuration`` provider can load configuration from the multiple sources. Loaded
-configuration is merged recursively over the existing configuration.
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_multiple.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12-13
-
-where ``examples/providers/configuration/config.local.yml`` is:
-
-.. literalinclude:: ../../examples/providers/configuration/config.local.yml
-   :language: ini
-
-.. _configuration-envs-interpolation:
-
-Using environment variables in configuration files
---------------------------------------------------
-
-``Configuration`` provider supports environment variables interpolation in configuration files.
-Use ``${ENV_NAME}`` in the configuration file to substitute value from environment
-variable ``ENV_NAME``.
-
-.. code-block:: ini
-
-   section:
-     option: ${ENV_NAME}
-
-You can also specify a default value using ``${ENV_NAME:default}`` format. If environment
-variable ``ENV_NAME`` is undefined, configuration provider will substitute value ``default``.
-
-.. code-block:: ini
-
-   [section]
-   option = ${ENV_NAME:default}
-
-If you'd like to specify a default value for environment variable inside of the application you can use
-``os.environ.setdefault()``.
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_env_interpolation_os_default.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12
-
-If environment variable is undefined and doesn't have a default, ``Configuration`` provider
-will replace it with an empty value. This is a default behavior. To raise an error on
-undefined environment variable that doesn't have a default value, pass argument
-``envs_required=True`` to a configuration reading method:
-
-.. code-block:: python
-
-   container.config.from_yaml("config.yml", envs_required=True)
-
-See also: :ref:`configuration-strict-mode`.
-
-.. note::
-   ``Configuration`` provider makes environment variables interpolation before parsing. This preserves
-   original parser behavior. For instance, undefined environment variable in YAML configuration file
-   will be replaced with an empty value and then YAML parser will load the file.
-
-   Original configuration file:
-
-   .. code-block:: ini
-
-      section:
-        option: ${ENV_NAME}
-
-   Configuration file after interpolation where ``ENV_NAME`` is undefined:
-
-   .. code-block:: ini
-
-      section:
-        option:
-
-   Configuration provider after parsing interpolated YAML file contains ``None`` in
-   option ``section.option``:
-
-   .. code-block:: python
-
-      assert container.config.section.option() is None
-
-If you want to disable environment variables interpolation, pass ``envs_required=None``:
-
-.. code-block:: yaml
-   :caption: templates.yml
-
-   template_string: 'Hello, ${name}!'
-
-.. code-block:: python
-
-   >>> container.config.from_yaml("templates.yml", envs_required=None)
-   >>> container.config.template_string()
-   'Hello, ${name}!'
-
-Mandatory and optional sources
-------------------------------
-
-By default, methods ``.from_yaml()`` and ``.from_ini()`` ignore errors if configuration file does not exist.
-You can use this to specify optional configuration files.
-
-If configuration file is mandatory, use ``required`` argument. Configuration provider will raise an error
-if required file does not exist.
-
-You can also use ``required`` argument when loading configuration from dictionaries and environment variables.
-
-Mandatory YAML file:
-
-.. code-block:: python
-
-   container.config.from_yaml("config.yaml", required=True)
-
-Mandatory INI file:
-
-.. code-block:: python
-
-   container.config.from_ini("config.ini", required=True)
-
-Mandatory dictionary:
-
-.. code-block:: python
-
-   container.config.from_dict(config_dict, required=True)
-
-Mandatory environment variable:
-
-.. code-block:: python
-
-   container.config.api_key.from_env("API_KEY", required=True)
-
-See also: :ref:`configuration-strict-mode`.
-
-Specifying the value type
--------------------------
-
-You can specify the type of the injected configuration value explicitly.
-
-This helps when you read the value from an ini file or an environment variable and need to
-convert it into an ``int`` or a ``float``.
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_type.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 19
-
-``Configuration`` provider has next helper methods:
-
-- ``.as_int()``
-- ``.as_float()``
-- ``.as_(callback, *args, **kwargs)``
-
-The last method ``.as_(callback, *args, **kwargs)`` helps to implement other conversions.
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_type_custom.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 18
-
-With the ``.as_(callback, *args, **kwargs)`` you can specify a function that will be called
-before the injection. The value from the config will be passed as a first argument. The returned
-value will be injected. Parameters ``*args`` and ``**kwargs`` are handled as any other injections.
-
-.. _configuration-strict-mode:
-
-Strict mode and required options
---------------------------------
-
-You can use configuration provider in strict mode. In strict mode configuration provider raises an error
-on access to any undefined option.
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_strict.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12
-
-Methods ``.from_*()`` in strict mode raise an exception if configuration file does not exist or
-configuration data is undefined:
-
-.. code-block:: python
-   :emphasize-lines: 10,15,20,25,30
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration(strict=True)
-
-
-   if __name__ == "__main__":
-       container = Container()
-
-       try:
-           container.config.from_yaml("does-not_exist.yml")  # raise exception
-       except FileNotFoundError:
-           ...
-
-       try:
-           container.config.from_ini("does-not_exist.ini")  # raise exception
-       except FileNotFoundError:
-           ...
-
-       try:
-           container.config.from_pydantic(EmptySettings())  # raise exception
-       except ValueError:
-           ...
-
-       try:
-           container.config.from_env("UNDEFINED_ENV_VAR")  # raise exception
-       except ValueError:
-           ...
-
-       try:
-           container.config.from_dict({})  # raise exception
-       except ValueError:
-           ...
-
-Environment variables interpolation in strict mode raises an exception when encounters
-an undefined environment variable without a default value.
-
-.. code-block:: ini
-
-   section:
-     option: ${UNDEFINED}
-
-.. code-block:: python
-
-       try:
-           container.config.from_yaml("undefined_env.yml")  # raise exception
-       except ValueError:
-           ...
-
-You can override ``.from_*()`` methods behaviour in strict mode using ``required`` argument:
-
-.. code-block:: python
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration(strict=True)
-
-
-   if __name__ == "__main__":
-       container = Container()
-
-       container.config.from_yaml("config.yml")
-       container.config.from_yaml("config.local.yml", required=False)
-
-You can also use ``.required()`` option modifier when making an injection. It does not require to switch
-configuration provider to strict mode.
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_required.py
-   :language: python
-   :lines: 11-20
-   :emphasize-lines: 8-9
-
-.. note::
-
-   Modifier ``.required()`` should be specified before type modifier ``.as_*()``.
-
-Aliases
--------
-
-You can use ``Configuration`` provider with a context manager to create aliases.
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_alias.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 14,22
-
-.. note::
-
-   Library ``environs`` is a 3rd party library. You need to install it
-   separately::
-
-      pip install environs
-
-   Documentation is available on GitHub: https://github.com/sloria/environs
-
-Injecting invariants
---------------------
-
-You can inject invariant configuration options based on the value of the other configuration
-option.
-
-To use that you should provide the switch-value as an item of the configuration option that
-contains sections ``config.options[config.switch]``:
-
-- When the value of the ``config.switch`` is ``A``, the ``config.options.A`` is injected
-- When the value of the ``config.switch`` is ``B``, the ``config.options.B`` is injected
-
-.. literalinclude:: ../../examples/providers/configuration/configuration_itemselector.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 15,30-31,38
-
-.. disqus::

docs/providers/coroutine.rst

@@ -1,27 +0,0 @@
-Coroutine provider
-==================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Coroutine,Asynchronous,
-              Asyncio,Example
-   :description: Coroutine provider creates a coroutine. This page demonstrates how to use a
-                 Coroutine provider.
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`Coroutine` provider creates a coroutine.
-
-.. literalinclude:: ../../examples/providers/coroutine.py
-   :language: python
-   :lines: 3-
-
-.. note::
-   The example works on Python 3.7+. For earlier versions use ``loop.run_until_complete()``.
-
-``Coroutine`` provider handles an injection of the dependencies the same way like a
-:ref:`factory-provider`.
-
-.. note::
-   ``Coroutine`` provider returns ``True`` for ``asyncio.iscoroutinefunction()`` check.
-
-.. disqus::

docs/providers/custom.rst

@@ -1,49 +0,0 @@
-.. _create-provider:
-
-Creating a custom provider
-==========================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Custom provider, Create
-   :description: This page demonstrates how to create a custom provider.
-
-.. currentmodule:: dependency_injector.providers
-
-You can create a custom provider.
-
-To create a custom provider you need to follow these rules:
-
-1. New provider class should inherit :py:class:`Provider`.
-2. You need to implement the ``Provider._provide()`` method.
-3. You need to implement the ``Provider.__deepcopy__()`` method. It should return an
-   equivalent copy of a provider. All providers must be copied with the ``deepcopy()`` function
-   from the ``providers`` module. It's essential to pass ``memo`` into ``deepcopy`` in order to keep
-   the preconfigured ``args`` and ``kwargs`` of stored providers. After the a new provider object
-   is created, use ``Provider._copy_overriding()`` method to copy all overriding providers. See the
-   example below.
-4. If new provider has a ``__init__()`` method, it should call the parent
-   ``Provider.__init__()``.
-5. If new provider stores any other providers, these providers should be listed in
-   ``.related`` property. Property ``.related`` also should yield providers from parent
-   ``.related`` property.
-
-.. literalinclude:: ../../examples/providers/custom_factory.py
-   :language: python
-   :lines: 3-
-
-.. note::
-   1. Prefer delegation over inheritance. If you choose between inheriting a ``Factory`` or
-      inheriting a ``Provider`` and use ``Factory`` internally - the last is better.
-   2. When creating a new provider follow the ``Factory``-like injections style. Consistency matters.
-   3. Use the ``__slots__`` attribute to make sure nothing could be attached to your provider. You
-      will also save some memory.
-
-.. note::
-   If you don't find needed provider in the ``providers`` module and experience troubles creating
-   one by your own - open a
-   `Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_.
-
-   I'll help you to resolve the issue if that's possible. If the new provider can be useful for
-   others I'll include it into the ``providers`` module.
-
-.. disqus::

docs/providers/dependency.rst

@@ -1,38 +0,0 @@
-.. _dependency-provider:
-
-Dependency provider
-===================
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`Dependency` provider is a placeholder for a dependency of a certain type.
-
-To specify a type of the dependency use ``instance_of`` argument: ``Dependency(instance_of=SomeClass)``.
-Dependency provider will control that returned object is an instance of ``instance_of`` type.
-
-.. literalinclude:: ../../examples/providers/dependency.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 26,35-36
-
-To provide a dependency you need to override the ``Dependency`` provider. You can call
-provider ``.override()`` method or provide an overriding provider when creating a container.
-See :ref:`provider-overriding`. If you don't provide a dependency, ``Dependency`` provider
-will raise an error:
-
-.. literalinclude:: ../../examples/providers/dependency_undefined_error.py
-   :language: python
-   :lines: 18-
-
-You also can provide a default for the dependency. To provide a default use ``default`` argument:
-``Dependency(..., default=...)``. Default can be a value or a provider. If default is not a provider,
-dependency provider will wrap it into the ``Object`` provider.
-
-.. literalinclude:: ../../examples/providers/dependency_default.py
-   :language: python
-   :lines: 16-23
-   :emphasize-lines: 3
-
-See also: :ref:`check-container-dependencies`.
-
-.. disqus::

docs/providers/dict.rst

@@ -1,37 +0,0 @@
-Dict provider
-=============
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Dict,Injection
-   :description: Dict provider helps to inject a dictionary of the dependencies. This page demonstrates
-                 how to use Dict provider.
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`Dict` provider provides a dictionary of values.
-
-.. literalinclude:: ../../examples/providers/dict.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 21-24
-
-``Dict`` provider handles keyword arguments the same way as a :ref:`factory-provider`.
-
-To use non-string keys or keys with ``.`` and ``-`` provide a dictionary as a positional argument:
-
-.. code-block:: python
-
-   providers.Dict({
-       SomeClass: providers.Factory(...),
-       "key.with.periods": providers.Factory(...),
-       "key-with-dashes": providers.Factory(...),
-   })
-
-Example:
-
-.. literalinclude:: ../../examples/providers/dict_non_string_keys.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 40-43
-
-.. disqus::

docs/providers/factory.rst

@@ -1,242 +0,0 @@
-.. _factory-provider:
-
-Factory provider
-================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Factory,Abstract Factory,
-              Pattern,Example,Aggregate
-   :description: Factory provider helps to implement dependency injection in Python. This page
-                 demonstrates how to use Factory provider, inject the dependencies, and assemble
-                 object graphs passing the injections deep inside. It also provides the examples
-                 of the Abstract Factory pattern & provider and Factories Aggregation pattern.
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`Factory` provider creates new objects.
-
-.. literalinclude:: ../../examples/providers/factory.py
-   :language: python
-   :lines: 3-
-
-The first argument of the ``Factory`` provider is a class, a factory function or a method
-that creates an object.
-
-The rest of the ``Factory`` positional and keyword arguments are the dependencies.
-``Factory`` injects the dependencies every time when creates a new object. The dependencies are
-injected following these rules:
-
-+ If the dependency is a provider, this provider is called and the result of the call is injected.
-+ If you need to inject the provider itself, you should use the ``.provider`` attribute. More at
-  :ref:`factory_providers_delegation`.
-+ All other dependencies are injected *"as is"*.
-+ Positional context arguments are appended after ``Factory`` positional dependencies.
-+ Keyword context arguments have the priority over the ``Factory`` keyword dependencies with the
-  same name.
-
-.. image:: images/factory_init_injections.png
-
-.. literalinclude:: ../../examples/providers/factory_init_injections.py
-   :language: python
-   :lines: 3-
-
-``Factory`` provider can inject attributes. Use ``.add_attributes()`` method to specify
-attribute injections.
-
-.. literalinclude:: ../../examples/providers/factory_attribute_injections.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 18-18
-
-Passing arguments to the underlying providers
----------------------------------------------
-
-``Factory`` provider can pass the arguments to the underlying providers. This helps when you need
-to assemble a nested objects graph and pass the arguments deep inside.
-
-Consider the example:
-
-.. image:: images/factory_init_injections_underlying.png
-
-To create an ``Algorithm`` you need to provide all the dependencies: ``ClassificationTask``,
-``Loss``, and ``Regularizer``. The last object in the chain, the ``Regularizer`` has a dependency
-on the ``alpha`` value. The ``alpha`` value varies from algorithm to algorithm:
-
-.. code-block:: python
-
-   Algorithm(
-       task=ClassificationTask(
-           loss=Loss(
-               regularizer=Regularizer(
-                   alpha=alpha,  # <-- the dependency
-               ),
-           ),
-       ),
-   )
-
-
-``Factory`` provider helps to deal with the such assembly. You need to create the factories for
-all the classes and use special double-underscore ``__`` syntax for passing the ``alpha`` argument:
-
-.. literalinclude:: ../../examples/providers/factory_init_injections_underlying.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 44,49
-
-When you use ``__`` separator in the name of the keyword argument the ``Factory`` looks for
-the dependency with the same name as the left part of the ``__`` expression.
-
-.. code-block:: none
-
-   <dependency>__<keyword for the underlying provider>=<value>
-
-If ``<dependency>`` is found the underlying provider will receive the
-``<keyword for the underlying provider>=<value>`` as an argument.
-
-.. _factory_providers_delegation:
-
-Passing providers to the objects
---------------------------------
-
-When you need to inject the provider itself, but not the result of its call, use the ``.provider``
-attribute of the provider that you're going to inject.
-
-.. image:: images/factory_delegation.png
-
-.. literalinclude:: ../../examples/providers/factory_delegation.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 28
-
-.. note:: Any provider has a ``.provider`` attribute.
-
-.. _factory-string-imports:
-
-String imports
---------------
-
-``Factory`` provider can handle string imports:
-
-.. code-block:: python
-
-   class Container(containers.DeclarativeContainer):
-
-       service = providers.Factory("myapp.mypackage.mymodule.Service")
-
-You can also make a relative import:
-
-.. code-block:: python
-
-   # in myapp/container.py
-
-   class Container(containers.DeclarativeContainer):
-
-       service = providers.Factory(".mypackage.mymodule.Service")
-
-or import a member of the current module just specifying its name:
-
-.. code-block:: python
-
-   class Service:
-       ...
-
-
-   class Container(containers.DeclarativeContainer):
-
-       service = providers.Factory("Service")
-
-.. note::
-   ``Singleton``, ``Callable``, ``Resource``, and ``Coroutine`` providers handle string imports
-   the same way as a ``Factory`` provider.
-
-.. _factory-specialize-provided-type:
-
-Specializing the provided type
-------------------------------
-
-You can create a specialized ``Factory`` provider that provides only specific type. For doing
-this you need to create a subclass of the ``Factory`` provider and define the ``provided_type``
-class attribute.
-
-.. literalinclude:: ../../examples/providers/factory_provided_type.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 12-14
-
-.. _abstract-factory:
-
-Abstract factory
-----------------
-
-:py:class:`AbstractFactory` provider helps when you need to create a provider of some base class
-and the particular implementation is not yet know. ``AbstractFactory`` provider is a ``Factory``
-provider with two peculiarities:
-
-+ Provides only objects of a specified type.
-+ Must be overridden before usage.
-
-.. image:: images/abstract_factory.png
-    :width: 100%
-    :align: center
-
-.. literalinclude:: ../../examples/providers/abstract_factory.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 34
-
-.. _factory-aggregate-provider:
-
-Factory aggregate
------------------
-
-:py:class:`FactoryAggregate` provider aggregates multiple factories.
-
-.. seealso::
-   :ref:`aggregate-provider` – it's a successor of ``FactoryAggregate`` provider that can aggregate
-   any type of provider, not only ``Factory``.
-
-The aggregated factories are associated with the string keys. When you call the
-``FactoryAggregate`` you have to provide one of the these keys as a first argument.
-``FactoryAggregate`` looks for the factory with a matching key and calls it with the rest of the arguments.
-
-.. image:: images/factory_aggregate.png
-    :width: 100%
-    :align: center
-
-.. literalinclude:: ../../examples/providers/factory_aggregate.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 33-37,47
-
-You can get a dictionary of the aggregated providers using ``.providers`` attribute.
-To get a game provider dictionary from the previous example you can use
-``game_factory.providers`` attribute.
-
-You can also access an aggregated factory as an attribute. To create the ``Chess`` object from the
-previous example you can do ``chess = game_factory.chess("John", "Jane")``.
-
-.. note::
-   You can not override the ``FactoryAggregate`` provider.
-
-.. note::
-   When you inject the ``FactoryAggregate`` provider it is passed "as is".
-
-To use non-string keys or string keys with ``.`` and ``-``, you can provide a dictionary as a positional argument:
-
-.. code-block:: python
-
-   providers.FactoryAggregate({
-       SomeClass: providers.Factory(...),
-       "key.with.periods": providers.Factory(...),
-       "key-with-dashes": providers.Factory(...),
-   })
-
-Example:
-
-.. literalinclude:: ../../examples/providers/factory_aggregate_non_string_keys.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 30-33,39-40
-
-
-.. disqus::

docs/providers/index.rst

@@ -1,57 +0,0 @@
-.. _providers:
-
-Providers
-=========
-
-Providers help to assemble the objects. They create objects and inject the dependencies.
-
-Each provider is a callable. You call the provider like a function when you need to create an
-object. Provider retrieves the underlying dependencies and inject them into the created object.
-It causes the cascade effect that helps to assemble object graphs. See ``Factory``, ``Singleton``,
-``Callable`` and other provider docs below.
-
-.. code-block:: bash
-
-   provider1()
-   │
-   ├──> provider2()
-   │
-   ├──> provider3()
-   │    │
-   │    └──> provider4()
-   │
-   └──> provider5()
-        │
-        └──> provider6()
-
-Another providers feature is an overriding. You can override any provider with another provider.
-This helps in testing. This also helps in overriding API clients with stubs for the development
-or staging environment. See the example at :ref:`provider-overriding`.
-
-If you need to inject not the whole object but the parts see :ref:`provided-instance`.
-
-To create a new provider see :ref:`create-provider`.
-
-Providers module API docs - :py:mod:`dependency_injector.providers`
-
-..  toctree::
-    :maxdepth: 2
-
-    factory
-    singleton
-    callable
-    coroutine
-    object
-    list
-    dict
-    configuration
-    resource
-    aggregate
-    selector
-    dependency
-    overriding
-    provided_instance
-    inject_self
-    custom
-    async
-    typing_mypy

docs/providers/inject_self.rst

@@ -1,20 +0,0 @@
-Injecting container "self"
-==========================
-
-You can inject container "self" into container providers.
-
-.. literalinclude:: ../../examples/containers/inject_self.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 20, 26
-
-To inject container "self" you need to define ``Self`` provider. Container can have only one ``Self`` provider.
-
-Usually you will use name ``__self__``.
-You can also use different name. When you use different name container will also reference
-defined ``Self`` provider in ``.__self__`` attribute.
-
-Provider ``Self`` is not listed in container ``.providers`` attributes.
-
-.. disqus::
-

docs/providers/list.rst

@@ -1,23 +0,0 @@
-List provider
-=============
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,List,Injection
-   :description: List provider helps to inject a list of the dependencies. This page demonstrates
-                 how to use a List provider.
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`List` provider provides a list of values.
-
-.. literalinclude:: ../../examples/providers/list.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 21-24
-
-``List`` provider handles positional arguments the same way as a :ref:`factory-provider`.
-
-.. note::
-    Keyword argument are not supported.
-
-.. disqus::

docs/providers/object.rst

@@ -1,17 +0,0 @@
-Object provider
-===============
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Object
-   :description: Object provider provides an object "as is". This page demonstrates how to use an
-                 Object provider.
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`Object` provider returns an object "as is".
-
-.. literalinclude:: ../../examples/providers/object.py
-   :language: python
-   :lines: 3-
-
-.. disqus::

docs/providers/overriding.rst

@@ -1,43 +0,0 @@
-.. _provider-overriding:
-
-Provider overriding
-===================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Override,Test,Unit
-   :description: This page demonstrates how to implement providers overriding. This helps in
-                 testing and configuring the system for the multiple environments.
-
-.. currentmodule:: dependency_injector.providers
-
-You can override any provider with another provider.
-
-When provider is overridden it calls to the overriding provider instead of providing
-the object by its own.
-
-This helps in testing. This also helps in overriding API clients with stubs for the development
-or staging environment.
-
-To override a provider you need to call the ``Provider.override()`` method. This method receives
-a single argument called ``overriding``.  If the ``overriding`` value is a provider, this provider
-is called instead of the original. If value is not a provider, this value is returned instead of
-calling the original provider.
-
-.. image:: images/overriding.png
-    :width: 80%
-    :align: center
-
-.. literalinclude:: ../../examples/providers/overriding.py
-   :language: python
-   :lines: 3-
-
-You can override a provider multiple times. In that case the latest ``overriding`` value will be
-used. The rest of the overriding values will form a stack.
-
-To reset an overriding you can use the ``Provider.reset_override()`` or
-``Provider.reset_last_overriding()`` methods.
-
-You can use a context manager for overriding a provider ``with Provider.override():``. The
-overriding will be reset when context closed.
-
-.. disqus::

docs/providers/provided_instance.rst

@@ -1,38 +0,0 @@
-.. _provided-instance:
-
-Injecting provided object attributes, items, or call its methods
-================================================================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Attribute,Method,Call
-   :description: This page demonstrates how to inject attributes, items or call method of the
-                 provided instance.
-
-.. currentmodule:: dependency_injector.providers
-
-You can inject provided object attribute, item or result of its method call.
-
-.. literalinclude:: ../../examples/providers/provided_instance.py
-   :language: python
-   :emphasize-lines: 28-34
-   :lines: 3-
-
-To use the feature you should use the ``.provided`` attribute of the injected provider. This
-attribute helps to specify what happens with the provided instance before the injection. You can
-use any combination of the following:
-
-- an attribute of the provided object
-- an item of the provided object
-- a call of the provided object method
-
-When you use a call of the provided instance method you can specify the injections for this
-method like you do with any other provider.
-
-You can do nested constructions:
-
-.. literalinclude:: ../../examples/providers/provided_instance_complex.py
-   :language: python
-   :emphasize-lines: 26-32
-   :lines: 3-
-
-.. disqus::

docs/providers/resource.rst

@@ -1,520 +0,0 @@
-.. _resource-provider:
-
-Resource provider
-=================
-
-.. meta::
-   :keywords: Python,DI,Dependency injection,IoC,Inversion of Control,Resource,Injection,
-              Logging,Event Loop,Thread Pool
-   :description: Resource provider provides a component with initialization and shutdown. It works
-                 well for configuring logging, event loop, thread or process pool, etc.
-                 This page demonstrates how to use resource provider.
-
-.. currentmodule:: dependency_injector.providers
-
-:py:class:`Resource` provider provides a component with initialization and shutdown.
-
-.. literalinclude:: ../../examples/providers/resource.py
-   :language: python
-   :lines: 3-
-
-Resource providers help to initialize and configure logging, event loop, thread or process pool, etc.
-
-Resource provider is similar to ``Singleton``. Resource initialization happens only once.
-You can make injections and use provided instance the same way like you do with any other provider.
-
-.. code-block:: python
-   :emphasize-lines: 12
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration()
-
-       thread_pool = providers.Resource(
-           init_thread_pool,
-           max_workers=config.max_workers,
-       )
-
-       dispatcher = providers.Factory(
-           TaskDispatcher,
-           executor=thread_pool,
-       )
-
-Container has an interface to initialize and shutdown all resources at once:
-
-.. code-block:: python
-
-   container = Container()
-   container.init_resources()
-   container.shutdown_resources()
-
-You can also initialize and shutdown resources one-by-one using ``init()`` and
-``shutdown()`` methods of the provider:
-
-.. code-block:: python
-
-   container = Container()
-   container.thread_pool.init()
-   container.thread_pool.shutdown()
-
-When you call ``.shutdown()`` method on a resource provider, it will remove the reference to the initialized resource,
-if any, and switch to uninitialized state. Some of resource initializer types support specifying custom
-resource shutdown.
-
-Resource provider supports 4 types of initializers:
-
-- Function
-- Context Manager
-- Generator (legacy)
-- Subclass of ``resources.Resource`` (legacy)
-
-Function initializer
---------------------
-
-Function is the most common way to specify resource initialization:
-
-.. code-block:: python
-
-   def init_resource(argument1=..., argument2=...):
-       return SomeResource()
-
-
-   class Container(containers.DeclarativeContainer):
-
-       resource = providers.Resource(
-           init_resource,
-           argument1=...,
-           argument2=...,
-       )
-
-Function initializer may not return a value. This often happens when
-you configure global resource:
-
-.. code-block:: python
-
-   import logging.config
-
-
-   class Container(containers.DeclarativeContainer):
-
-       configure_logging = providers.Resource(
-           logging.config.fileConfig,
-           fname="logging.ini",
-       )
-
-Function initializer does not provide a way to specify custom resource shutdown.
-
-Context Manager initializer
----------------------------
-
-This is an extension to the Function initializer. Resource provider automatically detects if the initializer returns a
-context manager and uses it to manage the resource lifecycle.
-
-.. code-block:: python
-
-   from dependency_injector import containers, providers
-
-   class DatabaseConnection:
-       def __init__(self, host, port, user, password):
-           self.host = host
-           self.port = port
-           self.user = user
-           self.password = password
-
-       def __enter__(self):
-           print(f"Connecting to {self.host}:{self.port} as {self.user}")
-           return self
-
-       def __exit__(self, exc_type, exc_val, exc_tb):
-           print("Closing connection")
-
-
-   class Container(containers.DeclarativeContainer):
-
-       config = providers.Configuration()
-       db = providers.Resource(
-           DatabaseConnection,
-           host=config.db.host,
-           port=config.db.port,
-           user=config.db.user,
-           password=config.db.password,
-       )
-
-Generator initializer (legacy)
-------------------------------
-
-Resource provider can use 2-step generators:
-
-- First step of generator is an initialization phase
-- The second is step is a shutdown phase
-
-.. code-block:: python
-
-   def init_resource(argument1=..., argument2=...):
-       resource = SomeResource()  # initialization
-
-       yield resource
-
-       # shutdown
-       ...
-
-
-   class Container(containers.DeclarativeContainer):
-
-       resource = providers.Resource(
-           init_resource,
-           argument1=...,
-           argument2=...,
-       )
-
-Generator initialization phase ends on the first ``yield`` statement. You can return a
-resource object using ``yield resource`` like in the example above. Returning of the
-object is not mandatory. You can leave ``yield`` statement empty:
-
-.. code-block:: python
-
-   def init_resource(argument1=..., argument2=...):
-       # initialization
-       ...
-
-       yield
-
-       # shutdown
-       ...
-
-
-   class Container(containers.DeclarativeContainer):
-
-       resource = providers.Resource(
-           init_resource,
-           argument1=...,
-           argument2=...,
-       )
-
-.. note::
-
-   Generator initializers are automatically wrapped with ``contextmanager`` or ``asynccontextmanager`` decorator when
-   provided to a ``Resource`` provider.
-
-Subclass initializer (legacy)
------------------------------
-
-You can create resource initializer by implementing a subclass of the ``resources.Resource``:
-
-.. code-block:: python
-
-   from dependency_injector import resources
-
-
-   class MyResource(resources.Resource):
-
-       def init(self, argument1=..., argument2=...) -> SomeResource:
-           return SomeResource()
-
-       def shutdown(self, resource: SomeResource) -> None:
-           # shutdown
-           ...
-
-
-   class Container(containers.DeclarativeContainer):
-
-       resource = providers.Resource(
-           MyResource,
-           argument1=...,
-           argument2=...,
-       )
-
-Subclass must implement two methods: ``init()`` and ``shutdown()``.
-
-Method ``init()`` receives arguments specified in resource provider.
-It performs initialization and returns resource object. Returning of the object
-is not mandatory.
-
-Method ``shutdown()`` receives resource object returned from ``init()``. If ``init()``
-didn't return an object ``shutdown()`` method will be called anyway with ``None`` as a
-first argument.
-
-.. code-block:: python
-
-   from dependency_injector import resources
-
-
-   class MyResource(resources.Resource):
-
-       def init(self, argument1=..., argument2=...) -> None:
-           # initialization
-           ...
-
-       def shutdown(self, _: None) -> None:
-           # shutdown
-           ...
-
-
-.. _resource-provider-wiring-closing:
-
-Scoping Resources using specialized subclasses
-----------------------------------------------
-
-You can use specialized subclasses of ``Resource`` provider to initialize and shutdown resources by type.
-Allowing for example to only initialize a subgroup of resources.
-
-.. code-block:: python
-
-   class ScopedResource(resources.Resource):
-       pass
-
-   def init_service(name) -> Service:
-      print(f"Init {name}")
-      yield Service()
-      print(f"Shutdown {name}")
-
-   class Container(containers.DeclarativeContainer):
-
-       scoped = ScopedResource(
-           init_service,
-           "scoped",
-       )
-
-       generic = providers.Resource(
-           init_service,
-           "generic",
-       )
-
-
-To initialize resources by type you can use ``init_resources(resource_type)`` and ``shutdown_resources(resource_type)``
-methods adding the resource type as an argument:
-
-.. code-block:: python
-
-   def main():
-       container = Container()
-       container.init_resources(ScopedResource)
-       #  Generates:
-       # >>> Init scoped
-
-       container.shutdown_resources(ScopedResource)
-       #  Generates:
-       # >>> Shutdown scoped
-
-
-And to initialize all resources you can use ``init_resources()`` and ``shutdown_resources()`` without arguments:
-
-.. code-block:: python
-
-   def main():
-       container = Container()
-       container.init_resources()
-       #  Generates:
-       # >>> Init scoped
-       # >>> Init generic
-
-       container.shutdown_resources()
-       #  Generates:
-       # >>> Shutdown scoped
-       # >>> Shutdown generic
-
-
-It works using the ``traverse()`` method to find all resources of the specified type, selecting all resources
-which are instances of the specified type.
-
-
-Resources, wiring, and per-function execution scope
----------------------------------------------------
-
-You can compound ``Resource`` provider with :ref:`wiring` to implement per-function
-execution scope. For doing this you need to use additional ``Closing`` marker from
-``wiring`` module.
-
-.. literalinclude:: ../../examples/wiring/flask_resource_closing.py
-   :language: python
-   :lines: 3-
-   :emphasize-lines: 22
-
-Framework initializes and injects the resource into the function. With the ``Closing`` marker
-framework calls resource ``shutdown()`` method when function execution is over.
-
-The example above produces next output:
-
-.. code-block:: bash
-
-   Init service
-   Shutdown service
-   127.0.0.1 - - [29/Oct/2020 22:39:40] "GET / HTTP/1.1" 200 -
-   Init service
-   Shutdown service
-   127.0.0.1 - - [29/Oct/2020 22:39:41] "GET / HTTP/1.1" 200 -
-   Init service
-   Shutdown service
-   127.0.0.1 - - [29/Oct/2020 22:39:41] "GET / HTTP/1.1" 200 -
-
-.. _resource-async-initializers:
-
-Asynchronous initializers
--------------------------
-
-When you write an asynchronous application, you might need to initialize resources asynchronously. Resource
-provider supports asynchronous initialization and shutdown.
-
-Asynchronous function initializer:
-
-.. code-block:: python
-
-   async def init_async_resource(argument1=..., argument2=...):
-       return await connect()
-
-
-   class Container(containers.DeclarativeContainer):
-
-       resource = providers.Resource(
-           init_resource,
-           argument1=...,
-           argument2=...,
-       )
-
-Asynchronous Context Manager initializer:
-
-.. code-block:: python
-
-   @asynccontextmanager
-   async def init_async_resource(argument1=..., argument2=...):
-       connection = await connect()
-       yield connection
-       await connection.close()
-
-
-   class Container(containers.DeclarativeContainer):
-
-       resource = providers.Resource(
-           init_async_resource,
-           argument1=...,
-           argument2=...,
-       )
-
-Asynchronous subclass initializer:
-
-.. code-block:: python
-
-   from dependency_injector import resources
-
-
-   class AsyncConnection(resources.AsyncResource):
-
-       async def init(self, argument1=..., argument2=...):
-           yield await connect()
-
-       async def shutdown(self, connection):
-           await connection.close()
-
-
-   class Container(containers.DeclarativeContainer):
-
-       resource = providers.Resource(
-           AsyncConnection,
-           argument1=...,
-           argument2=...,
-       )
-
-When you use resource provider with asynchronous initializer you need to call its ``__call__()``,
-``init()``, and ``shutdown()`` methods asynchronously:
-
-.. code-block:: python
-
-   import asyncio
-
-
-   class Container(containers.DeclarativeContainer):
-
-       connection = providers.Resource(init_async_connection)
-
-
-   async def main():
-       container = Container()
-       connection = await container.connection()
-       connection = await container.connection.init()
-       connection = await container.connection.shutdown()
-
-
-   if __name__ == "__main__":
-       asyncio.run(main())
-
-Container ``init_resources()`` and ``shutdown_resources()`` methods should be used asynchronously if there is
-at least one asynchronous resource provider:
-
-.. code-block:: python
-
-   import asyncio
-
-
-   class Container(containers.DeclarativeContainer):
-
-       connection1 = providers.Resource(init_async_connection)
-
-       connection2 = providers.Resource(init_sync_connection)
-
-
-   async def main():
-       container = Container()
-       await container.init_resources()
-       await container.shutdown_resources()
-
-
-   if __name__ == "__main__":
-       asyncio.run(main())
-
-See also:
-
-- Provider :ref:`async-injections`
-- Wiring :ref:`async-injections-wiring`
-- :ref:`fastapi-redis-example`
-
-ASGI Lifespan Protocol Support
-------------------------------
-
-The :mod:`dependency_injector.ext.starlette` module provides a :class:`~dependency_injector.ext.starlette.Lifespan`
-class that integrates resource providers with ASGI applications using the `Lifespan Protocol`_. This allows resources to
-be automatically initialized at application startup and properly shut down when the application stops.
-
-.. code-block:: python
-
-    from contextlib import asynccontextmanager
-    from dependency_injector import containers, providers
-    from dependency_injector.wiring import Provide, inject
-    from dependency_injector.ext.starlette import Lifespan
-    from fastapi import FastAPI, Request, Depends, APIRouter
-
-    class Connection: ...
-
-    @asynccontextmanager
-    async def init_database():
-        print("opening database connection")
-        yield Connection()
-        print("closing database connection")
-
-    router = APIRouter()
-
-    @router.get("/")
-    @inject
-    async def index(request: Request, db: Connection = Depends(Provide["db"])):
-        # use the database connection here
-        return "OK!"
-
-    class Container(containers.DeclarativeContainer):
-        __self__ = providers.Self()
-        db = providers.Resource(init_database)
-        lifespan = providers.Singleton(Lifespan, __self__)
-        app = providers.Singleton(FastAPI, lifespan=lifespan)
-        _include_router = providers.Resource(
-            app.provided.include_router.call(),
-            router,
-        )
-
-    if __name__ == "__main__":
-        import uvicorn
-
-        container = Container()
-        app = container.app()
-        uvicorn.run(app, host="localhost", port=8000)
-
-.. _Lifespan Protocol: https://asgi.readthedocs.io/en/latest/specs/lifespan.html
-
-.. disqus::