diff --git a/README.rst b/README.rst index a95be39e..c2de8d1d 100644 --- a/README.rst +++ b/README.rst @@ -16,6 +16,9 @@ dependency injection pattern in formal, pretty, Pythonic way. + Documentation. + Semantic versioning. +*Dependency Injector* providers are implemented as C extension types using +Cython. + Status ------ diff --git a/docs/api/index.rst b/docs/api/index.rst index 1f1df940..132cdd5d 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -7,5 +7,4 @@ API Documentation top_level providers containers - utils errors diff --git a/docs/api/providers.rst b/docs/api/providers.rst index c86ca0c3..b5f3ecc1 100644 --- a/docs/api/providers.rst +++ b/docs/api/providers.rst @@ -1,10 +1,6 @@ ``dependency_injector.providers`` --------------------------------- -.. image:: /images/providers/providers_class_diagram.png - :width: 100% - :align: center - .. automodule:: dependency_injector.providers :members: :inherited-members: diff --git a/docs/containers/index.rst b/docs/containers/index.rst index 55e06f17..93bee78a 100644 --- a/docs/containers/index.rst +++ b/docs/containers/index.rst @@ -17,7 +17,7 @@ Also, for both of these and some other cases, it might be useful to attach some init / shutdown functionality or something else, that deals with group of providers. -Containers module API docs - :py:mod:`dependency_injector.containers`. +Containers package API docs - :py:mod:`dependency_injector.containers`. .. toctree:: :maxdepth: 2 diff --git a/docs/images/providers/providers_class_diagram.png b/docs/images/providers/providers_class_diagram.png deleted file mode 100644 index c4a0cb72..00000000 Binary files a/docs/images/providers/providers_class_diagram.png and /dev/null differ diff --git a/docs/index.rst b/docs/index.rst index 534e291b..11bfe188 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,22 +8,33 @@ Dependency Injector --- Dependency injection microframework for Python :description: Dependency Injector is a dependency injection microframework for Python. It was designed to be unified, developer-friendly tool that helps to implement dependency injection pattern in - formal, pretty, Pythonic way. + formal, pretty, Pythonic way. Dependency Injector framework + key features are: Easy, smart, pythonic style; Obvious, clear + structure; Extensibility and flexibility; High performance; + Memory efficiency; Thread safety; Documentation; Semantic + versioning; Dependency Injector providers are implemented as + C extension types using Cython. + +.. _index: *Dependency Injector* is a dependency injection microframework for Python. It was designed to be unified, developer-friendly tool that helps to implement -dependency injection pattern in formal, pretty, Pythonic way. +dependency injection pattern in formal, pretty, Pythonic way. *Dependency Injector* framework key features are: + Easy, smart, pythonic style. + Obvious, clear structure. + Extensibility and flexibility. ++ High performance. + Memory efficiency. + Thread safety. + Documentation. + Semantic versioning. +*Dependency Injector* providers are implemented as C extension types using +Cython. + Status ------ diff --git a/docs/introduction/di_in_python.rst b/docs/introduction/di_in_python.rst index c7cf6b91..8dc370f3 100644 --- a/docs/introduction/di_in_python.rst +++ b/docs/introduction/di_in_python.rst @@ -121,7 +121,7 @@ code for specification of dependencies. Nevertheless, this disadvantage could be easily avoided by creating inversion of control container (IoC container). Example of creation of several inversion of control containers (IoC containers) -using *Dependency Injector*: +using :doc:`Dependency Injector <../index>`: .. literalinclude:: ../../examples/miniapps/engines_cars/example_ioc_containers.py :language: python diff --git a/docs/main/changelog.rst b/docs/main/changelog.rst index b94cbbda..1ef7253b 100644 --- a/docs/main/changelog.rst +++ b/docs/main/changelog.rst @@ -9,16 +9,40 @@ follows `Semantic versioning`_ Development version ------------------- -- Add ``dependency_injector.injections`` module (C extension). -- Transfer ``dependency_injector.utils`` module to Cython (C extension). -- Transfer ``dependency_injector.errors`` module to Cython (C extension). -- Remove ``@inject`` decorator. -- Add makefile (``clean``, ``test``, ``build``, ``install``, ``uninstall`` - & ``publish`` commands). -- Update repository structure: +- **Providers** - - Sources are moved under ``src``. - - Tests are moved under ``tests/unit``. + 1. All providers from ``dependency_injector.providers`` package are + implemented as C extension types using Cython. + 2. Add ``BaseSingleton`` super class for all singleton providers. + 3. Make ``Singleton`` provider not thread-safe. It makes performance of + ``Singleton`` provider 10x times faster. + 4. Add ``ThreadSafeSingleton`` provider - thread-safe version of + ``Singleton`` provider. + 5. Add ``ThreadLocalSingleton`` provider - ``Singleton`` provider that uses + thread-local storage. + 6. Remove ``provides`` attribute from ``Factory`` and ``Singleton`` + providers. + 7. Add ``set_args()`` and ``clear_args()`` methods for ``Callable``, + ``Factory`` and ``Singleton`` providers. + +- **Containers** + + 1. Module ``dependency_injector.containers`` was splitted into submodules + without any functional changes. + +- **Utils** + + 1. Module ``dependency_injector.utils`` is splitted into + ``dependency_injector.containers`` and ``dependency_injector.providers``. + +- **Miscellaneous** + + 1. Remove ``@inject`` decorator. + 2. Add makefile (``clean``, ``test``, ``build``, ``install``, ``uninstall`` + & ``publish`` commands). + 3. Update repository structure: + 1. Sources are moved under ``src/`` folder. + 2. Tests are moved under ``tests/unit/`` folder. .. - No features. diff --git a/docs/main/installation.rst b/docs/main/installation.rst index 1a3e0cd1..abfff964 100644 --- a/docs/main/installation.rst +++ b/docs/main/installation.rst @@ -12,8 +12,13 @@ framework can be installed from PyPi_: pip install dependency_injector # Installing particular version: - pip install dependency_injector==2.0.0 + pip install dependency-injector==3.0.0 +.. note:: + Some components of *Dependency Injector* are implemented as C extension types. + *Dependency Injector* is distributed as an archive with a source code, so + C compiler and Python header files are required for the installation. + Sources can be cloned from GitHub_: .. code-block:: bash @@ -30,7 +35,7 @@ Verification of currently installed version could be done using >>> from dependency_injector import VERSION >>> VERSION - '2.0.0' + '3.0.0' .. _PyPi: https://pypi.python.org/pypi/dependency_injector .. _GitHub: https://github.com/ets-labs/python-dependency-injector diff --git a/docs/providers/index.rst b/docs/providers/index.rst index 621959e3..a4fdc4ab 100644 --- a/docs/providers/index.rst +++ b/docs/providers/index.rst @@ -12,16 +12,7 @@ Current documentation section consists from description of standard providers library and some useful information like overriding of providers and writing of custom providers. -All providers are validated in multithreading environment and considered to -be thread safe. - -+ Base providers class is: :py:class:`dependency_injector.providers.Provider` -+ Providers module API docs: :py:mod:`dependency_injector.providers` -+ Providers class diagram: - -.. image:: /images/providers/providers_class_diagram.png - :width: 100% - :align: center +Providers package API docs - :py:mod:`dependency_injector.providers` .. toctree:: :maxdepth: 2 diff --git a/docs/providers/singleton.rst b/docs/providers/singleton.rst index 6e0a88a6..81573319 100644 --- a/docs/providers/singleton.rst +++ b/docs/providers/singleton.rst @@ -21,7 +21,7 @@ Singleton providers resetting Created and memorized by :py:class:`Singleton` instance can be reset. Reset of :py:class:`Singleton`'s memorized instance is done by clearing reference to -it. Further lifecycle of memorized instance is out of :py:class:`Singleton` +it. Further lifecycle of memorized instance is out of :py:class:`Singleton` provider's control and dependes on garbage collection strategy. Example: @@ -33,15 +33,15 @@ Example: Singleton providers and injections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:py:class:`Singleton` provider extends :py:class:`Factory` provider, so, all -of the rules about injections are the same, as for :py:class:`Factory` -provider. +:py:class:`Singleton` provider has same interface as :py:class:`Factory` +provider, so, all of the rules about injections are the same, as for +:py:class:`Factory` provider. .. note:: Due that :py:class:`Singleton` provider creates specified class instance only on the first call, all injections are done once, during the first - call, also. Every next call, while instance has been already created + call. Every next call, while instance has been already created and memorized, no injections are done, :py:class:`Singleton` provider just returns memorized earlier instance. @@ -81,10 +81,12 @@ Specialization of :py:class:`Singleton` providers is the same as Singleton providers and multi-threading ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:py:class:`Singleton` provider is thread-safe and could be used in -multi-threading applications without any negative impact. Race condition on -singleton's initialization is escaped by using a global reentrant mutex - -:py:obj:`dependency_injector.utils.GLOBAL_LOCK`. +:py:class:`Singleton` provider is NOT thread-safe and should be used in +multi-threading applications with manually controlled locking. + +:py:class:`ThreadSafeSingleton` is a thread-safe version of +:py:class:`Singleton` and could be used in multi-threading applications +without any additional locking. Also there could be a need to use thread-scoped singletons and there is a special provider for such case - :py:class:`ThreadLocalSingleton`.