Add config.from_env(as_=...) (ets-labs#541)

* Add implementation and typing stub

* Add unit tests

* Update demo example

* Add typing tests

* Update changelog

* Update docs

* Add tests for an empty environment variable

* Improve wording in di_in_python.rst

* Update wording in changelog and docs

* Update doc blocks

Author: rmk135

README.rst

@@ -90,7 +90,7 @@ Key features of the ``Dependency Injector``:
        api_client = providers.Singleton(
            ApiClient,
            api_key=config.api_key,
-           timeout=config.timeout.as_int(),
+           timeout=config.timeout,
        )
 
        service = providers.Factory(
@@ -106,8 +106,8 @@ Key features of the ``Dependency Injector``:
 
    if __name__ == "__main__":
        container = Container()
-       container.config.api_key.from_env("API_KEY")
-       container.config.timeout.from_env("TIMEOUT")
+       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

docs/index.rst

@@ -96,7 +96,7 @@ Key features of the ``Dependency Injector``:
        api_client = providers.Singleton(
            ApiClient,
            api_key=config.api_key,
-           timeout=config.timeout.as_int(),
+           timeout=config.timeout,
        )
 
        service = providers.Factory(
@@ -112,8 +112,8 @@ Key features of the ``Dependency Injector``:
 
    if __name__ == "__main__":
        container = Container()
-       container.config.api_key.from_env("API_KEY")
-       container.config.timeout.from_env("TIMEOUT")
+       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

docs/introduction/di_in_python.rst

@@ -150,7 +150,7 @@ What does the Dependency Injector do?
 -------------------------------------
 
 With the dependency injection pattern objects loose the responsibility of assembling
-the dependencies. The ``Dependency Injector`` absorbs that responsibilities.
+the dependencies. The ``Dependency Injector`` absorbs that responsibility.
 
 ``Dependency Injector`` helps to assemble and inject the dependencies.
 
@@ -172,7 +172,7 @@ the dependency.
        api_client = providers.Singleton(
            ApiClient,
            api_key=config.api_key,
-           timeout=config.timeout.as_int(),
+           timeout=config.timeout,
        )
 
        service = providers.Factory(
@@ -188,8 +188,8 @@ the dependency.
 
    if __name__ == "__main__":
        container = Container()
-       container.config.api_key.from_env("API_KEY")
-       container.config.timeout.from_env("TIMEOUT")
+       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

docs/main/changelog.rst

@@ -9,6 +9,8 @@ follows `Semantic versioning`_
 
 Development version
 -------------------
+- Add argument ``as_`` to the ``config.from_env()`` method for the explicit type casting
+  of an environment variable value, e.g.: ``config.timeout.from_env("TIMEOUT", as_=int)``.
 - Add ``.providers`` attribute to the ``FactoryAggregate`` provider. It is an alias for
   ``FactoryAggregate.factories`` attribute.
 - Add ``.set_providers()`` method to the ``FactoryAggregate`` provider. It is an alias for

docs/providers/configuration.rst

@@ -205,6 +205,24 @@ Loading from an environment variable
    :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
 ---------------
 

examples/demo/with_di.py

@@ -13,7 +13,7 @@ class Container(containers.DeclarativeContainer):
     api_client = providers.Singleton(
         ApiClient,
         api_key=config.api_key,
-        timeout=config.timeout.as_int(),
+        timeout=config.timeout,
     )
 
     service = providers.Factory(
@@ -29,8 +29,8 @@ def main(service: Service = Provide[Container.service]):
 
 if __name__ == "__main__":
     container = Container()
-    container.config.api_key.from_env("API_KEY")
-    container.config.timeout.from_env("TIMEOUT")
+    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