8000 Merge branch 'release/3.37.0' into master · bimec/python-dependency-injector@2cf5efa · GitHub
[go: up one dir, main page]
Skip to content

Commit 2cf5efa

Browse files
rmk135rmk135
committed
Merge branch 'release/3.37.0' into master
2 parents f5758d8 + 5f7d978 commit 2cf5efa

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

47 files changed

+588
-426
lines changed

‎README.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ What is ``Dependency Injector``?
5252

5353
``Dependency Injector`` is a dependency injection framework for Python.
5454

55-
It helps you in implementing the dependency injection principle.
55+
It helps implementing the dependency injection principle.
5656

5757
What is dependency injection?
5858
-----------------------------

‎docs/containers/index.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _containers:
2+
13
Containers
24
==========
35

‎docs/images/internals.png

-8.07 KB
Binary file not shown.

‎docs/index.rst

Lines changed: 37 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -64,22 +64,49 @@ Dependency Injector --- Dependency injection framework for Python
6464

6565
``Dependency Injector`` is a dependency injection framework for Python.
6666

67-
It stands on two principles:
67+
It helps implementing the dependency injection principle.
6868

69-
- Explicit is better than implicit (PEP20).
70-
- Do no magic to your code.
69+
Key features of the ``Dependency Injector``:
7170

72-
How does it different from the other frameworks?
71+
- **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
72+
``List``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help assembling your
73+
objects. See :ref:`providers`.
74+
- **Overriding**. Can override any provider by another provider on the fly. This helps in testing
75+
and configuring dev / stage environment to replace API clients with stubs etc. See
76+
:ref:`provider-overriding`.
77+
- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables
78+
and dictionaries. See :ref:`configuration-provider`.
79+
- **Containers**. Provides declarative and dynamic containers. See :ref:`containers`.
80+
- **Performance**. Fast. Written in ``Cython``.
81+
- **Maturity**. Mature and production-ready. Well-tested, documented and supported.
7382

74-
- **No autowiring.** The framework does NOT do any autowiring / autoresolving of the dependencies. You need to specify everything explicitly. Because *"Explicit is better than implicit" (PEP20)*.
75-
- **Does not pollute your code.** Your application does NOT know and does NOT depend on the framework. No ``@inject`` decorators, annotations, patching or any other magic tricks.
83+
.. code-block:: python
7684
77-
``Dependency Injector`` makes a simple contract with you:
85+
from dependency_injector import containers, providers
7886
79-
- You tell the framework how to assemble your objects
80-
- The framework does it for you
8187
82-
The power of the ``Dependency Injector`` is in its simplicity and straightforwardness. It is a simple tool for the powerful concept.
88+
class Container(containers.DeclarativeContainer):
89+
90+
config = providers.Configuration()
91+
92+
api_client = providers.Singleton(
93+
ApiClient,
94+
api_key=config.api_key,
95+
timeout=config.timeout.as_int(),
96+
)
97+
98+
service = providers.Factory(
99+
Service,
100+
api_client=api_client,
101+
)
102+
103+
104+
if __name__ == '__main__':
105+
container = Container()
106+
container.config.api_key.from_env('API_KEY')
107+
container.config.timeout.from_env('TIMEOUT')
108+
109+
service = container.service()
83110
84111
With the ``Dependency Injector`` you keep **application structure in one place**.
85112
This place is called **the container**. You use the container to manage all the components of the

‎docs/introduction/index.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,4 +17,3 @@ dependency injection pattern, inversion of control principle and
1717
what_is_di
1818
di_in_python
1919
key_features
20-
structure

‎docs/introduction/key_features.rst

Lines changed: 19 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -3,66 +3,33 @@ Key features
33

44
.. meta::
55
:keywords: Python,DI,Dependency injection,IoC,Inversion of Control
6-
:description: This article describes key features of "Dependency Injector"
7-
framework. It also provides some cases and recommendations
8-
about usage of "Dependency Injector" framework.
6+
:description: This article describes key features of the Dependency Injector
7+
framework.
98

9+
Key features of the ``Dependency Injector``:
1010

11-
``Dependency Injector`` is a dependency injection framework for Python.
12-
It was designed to be a unified and developer-friendly tool that helps
13-
implement a dependency injection design pattern in a formal, pretty, and
14-
Pythonic way.
11+
- **Providers**. Provides ``Factory``, ``Singleton``, ``Callable``, ``Coroutine``, ``Object``,
12+
``List``, ``Configuration``, ``Dependency`` and ``Selector`` providers that help assembling your
13+
objects. See :ref:`providers`.
14+
- **Overriding**. Can override any provider by another provider on the fly. This helps in testing
15+
and configuring dev / stage environment to replace API clients with stubs etc. See
16+
:ref:`provider-overriding`.
17+
- **Configuration**. Read configuration from ``yaml`` & ``ini`` files, environment variables
18+
and dictionaries. See :ref:`configuration-provider`.
19+
- **Containers**. Provides declarative and dynamic containers. See :ref:`containers`.
20+
- **Performance**. Fast. Written in ``Cython``.
21+
- **Maturity**. Mature and production-ready. Well-tested, documented and supported.
1522

16-
It stands on two principles:
23+
The framework stands on two principles:
1724

18-
- Explicit is better than implicit (PEP20).
19-
- Do no magic to your code.
25+
- **Explicit is better than implicit (PEP20)**.
26+
- **Do not do any magic to your code**.
2027

21-
How does it different from the other frameworks?
28+
How is that different from the other frameworks?
2229

2330
- **No autowiring.** The framework does NOT do any autowiring / autoresolving of the dependencies. You need to specify everything explicitly. Because *"Explicit is better than implicit" (PEP20)*.
2431
- **Does not pollute your code.** Your application does NOT know and does NOT depend on the framework. No ``@inject`` decorators, annotations, patching or any other magic tricks.
2532

26-
``Dependency Injector`` makes a simple contract with you:
27-
28-
- You tell the framework how to build you code
29-
- The framework does it for you
30-
31-
The power of the ``Dependency Injector`` is in its simplicity and straightforwardness. It is a simple tool for the powerful concept.
32-
33-
The key features of the ``Dependency Injector`` framework are:
34-
35-
+ Easy, smart, and Pythonic style.
36-
+ Does NOT pollute client code.
37-
+ Obvious and clear structure.
38-
+ Extensibility and flexibility.
39-
+ High performance.
40-
+ Memory efficiency.
41-
+ Thread safety.
42-
+ Documented.
43-
+ Semantically versioned.
44-
+ Distributed as pre-compiled wheels.
45-
46-
``Dependency Injector`` containers and providers are implemented as C extension
47-
types using ``Cython``.
48-
49-
``Dependency Injector`` framework can be used in the different application types:
50-
51-
+ Web applications based on the ``Flask``, ``Django`` or any other web framework.
52-
+ Asynchronous applications ``asyncio``, ``aiohttp``, ``Tornado``, or ``Twisted``.
53-
+ Standalone frameworks and libraries.
54-
+ GUI applications.
55-
56-
``Dependency Injector`` framework can be integrated on the different project
57-
stages:
58-
59-
+ It can be used in the beginning of the development of a new application.
60-
+ It can be integrated into application that is on its active development stage.
61-
+ It can be used for refactoring of legacy application.
62-
63-
Components of ``Dependency Injector`` framework could be used:
64-
65-
+ In composition with each other.
66-
+ Independently from each other.
33+
The power of the framework is in a simplicity. ``Dependency Injector`` is a simple tool for the powerful concept.
6734

6835
.. disqus::

‎docs/introduction/structure.rst

Lines changed: 0 additions & 50 deletions
This file was deleted.

‎docs/main/changelog.rst

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,14 @@ that were made in every particular version.
77
From version 0.7.6 *Dependency Injector* framework strictly
88
follows `Semantic versioning`_
99

10+
3.37.0
11+
------
12+
- Update index documentation page.
13+
- Make multiple improvements and fixes for the providers documentation.
14+
- Update "Key Features" documentation page.
15+
- Remove "Structure of Dependency Injector" documentation page.
16+
- Edit "Feedback" documentation page.
17+
1018
3.36.0
1119
------
1220
- Update providers overriding documentation and rework examples.

‎docs/main/feedback.rst

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,8 @@
11
Feedback
22
========
33

4-
Feel free to post questions, bugs, feature requests, proposals etc. on
5-
*Dependency Injector* GitHub Issues:
6-
7-
https://github.com/ets-labs/python-dependency-injector/issues
8-
9-
Your feedback is quite important!
10-
4+
To post a question, bug report, a feature proposal or get some help open a
5+
`Github Issue <https://github.com/ets-labs/python-dependency-injector/issues>`_ or leave a comment
6+
below.
117

128
.. disqus::

‎docs/providers/configuration.rst

Lines changed: 33 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
.. _configuration-provider:
2+
13
Configuration provider
24
======================
35

@@ -14,8 +16,8 @@ Configuration provider
1416

1517
.. literalinclude:: ../../examples/providers/configuration/configuration.py
1618
:language: python
17-
:emphasize-lines: 4,9-10
18-
:lines: 4-14
19+
:emphasize-lines: 7,12-13
20+
:lines: 3-
1921

2022
It implements the principle "use first, define later".
2123

@@ -27,8 +29,8 @@ Loading from an INI file
2729

2830
.. literalinclude:: ../../examples/providers/configuration/configuration_ini.py
2931
:language: python
30-
:lines: 3-5,6-
31-
:emphasize-lines: 6
32+
:lines: 3-
33+
:emphasize-lines: 12
3234

3335
where ``examples/providers/configuration/config.ini`` is:
3436

@@ -47,8 +49,8 @@ Loading from a YAML file
4749

4850
.. literalinclude:: ../../examples/providers/configuration/configuration_yaml.py
4951
:language: python
50-
:lines: 3-5,6-
51-
:emphasize-lines: 6
52+
:lines: 3-
53+
:emphasize-lines: 12
5254

5355
where ``examples/providers/configuration/config.yml`` is:
5456

@@ -81,8 +83,8 @@ Loading from a dictionary
8183

8284
.. literalinclude:: ../../examples/providers/configuration/configuration_dict.py
8385
:language: python
84-
:lines: 3-5,6-
85-
:emphasize-lines: 6-13
86+
:lines: 3-
87+
:emphasize-lines: 12-19
8688

8789
Loading from an environment variable
8890
------------------------------------
@@ -92,8 +94,8 @@ Loading from an environment variable
9294

9395
.. literalinclude:: ../../examples/providers/configuration/configuration_env.py
9496
:language: python
95-
:lines: 5-7,13-21
96-
:emphasize-lines: 6-8
97+
:lines: 3-
98+
:emphasize-lines: 18-20
9799

98100
Loading from the multiple sources
99101
---------------------------------
@@ -103,8 +105,8 @@ configuration is merged recursively over the existing configuration.
103105

104106
.. literalinclude:: ../../examples/providers/configuration/configuration_multiple.py
105107
:language: python
106-
:lines: 3-5,6-14
107-
:emphasize-lines: 6-7
108+
:lines: 3-
109+
:emphasize-lines: 12-13
108110

109111
where ``examples/providers/configuration/config.local.yml`` is:
110112

@@ -122,7 +124,7 @@ convert it into an ``int`` or a ``float``.
122124
.. literalinclude:: ../../examples/providers/configuration/configuration_type.py
123125
:language: python
124126
:lines: 3-
125-
:emphasize-lines: 17
127+
:emphasize-lines: 19
126128

127129
``Configuration`` provider has next helper methods:
128130

@@ -135,10 +137,27 @@ The last method ``.as_(callback, *args, **kwargs)`` helps to implement other con
135137
.. literalinclude:: ../../examples/providers/configuration/configuration_type_custom.py
136138
:language: python
137139
:lines: 3-
138-
:emphasize-lines: 16
140+
:emphasize-lines: 18
139141

140142
With the ``.as_(callback, *args, **kwargs)`` you can specify a function that will be called
141143
before the injection. The value from the config will be passed as a first argument. The returned
142144
value will be injected. Parameters ``*args`` and ``**kwargs`` are handled as any other injections.
143145

146+
Injecting invariants
147+
--------------------
148+
149+
You can inject invariant configuration options based on the value of the other configuration
150+
option.
151+
152+
To use that you should provide the switch-value as an item of the configuration option that
153+
contains sections ``config.options[config.switch]``:
154+
155+
- When the value of the ``config.switch`` is ``A``, the ``config.options.A`` is injected
156+
- When the value of the ``config.switch`` is ``B``, the ``config.options.B`` is injected
157+
158+
.. literalinclude:: ../../examples/providers/configuration/configuration_itemselector.py
159+
:language: python
160+
:lines: 3-
161+
:emphasize-lines: 15,30-31,38
162+
144163
.. disqus::

0 commit comments

Comments
 (0)
0