Merge branch 'release/4.48.0'

Author: ZipFile

.editorconfig

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

docs/api/asgi-lifespan.rst

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

docs/api/index.rst

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

docs/conf.py

@@ -72,7 +72,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:

docs/examples/django.rst

@@ -78,7 +78,7 @@ 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: 13
+   :emphasize-lines: 12
 
 Tests
 -----

docs/examples/fastdepends.rst

@@ -0,0 +1,48 @@
+.. _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/index.rst

@@ -22,5 +22,6 @@ Explore the examples to see the ``Dependency Injector`` in action.
     fastapi
     fastapi-redis
     fastapi-sqlalchemy
+    fastdepends
 
 .. disqus::

docs/introduction/key_features.rst

@@ -31,7 +31,7 @@ Key features of the ``Dependency Injector``:
 
 The framework stands on the `PEP20 (The Zen of Python) <https://www.python.org/dev/peps/pep-0020/>`_ principle:
 
-.. code-block:: plain
+.. code-block:: text
 
    Explicit is better than implicit
 

docs/main/changelog.rst

@@ -7,15 +7,31 @@ that were made in every particular version.
 From version 0.7.6 *Dependency Injector* framework strictly
 follows `Semantic versioning`_
 
+4.48.0
+------
+
+- Improve performance of wiring (`#897 <https://github.com/ets-labs/python-dependency-injector/pull/897>`_)
+- Add Context Manager support to Resource provider (`#899 <https://github.com/ets-labs/python-dependency-injector/pull/899>`_)
+- Add support for async generator injections (`#900 <https://github.com/ets-labs/python-dependency-injector/pull/900>`_)
+- Fix unintended dependency on ``typing_extensions`` (`#902 <https://github.com/ets-labs/python-dependency-injector/pull/902>`_)
+- Add support for Fast Depends (`#898 <https://github.com/ets-labs/python-dependency-injector/pull/898>`_)
+- Add ``resource_type`` parameter to init and shutdown resources using specialized providers (`#858 <https://github.com/ets-labs/python-dependency-injector/pull/858>`_)
+
+4.47.1
+------
+
+- Fix typing for wiring marker (`#892 <https://github.com/ets-labs/python-dependency-injector/pull/896>`_)
+- Strip debug symbols in wheels
+
 4.47.0
--------
+------
 
 - Add support for ``Annotated`` type for module and class attribute injection in wiring,
   with updated documentation and examples.
   See discussion:
   https://github.com/ets-labs/python-dependency-injector/pull/721#issuecomment-2025263718
-- Fix ``root`` property shadowing in ``ConfigurationOption`` (`#875 https://github.com/ets-labs/python-dependency-injector/pull/875`_)
-- Fix incorrect monkeypatching during ``wire()`` that could violate MRO in some classes (`#886 https://github.com/ets-labs/python-dependency-injector/pull/886`_)
+- Fix ``root`` property shadowing in ``ConfigurationOption`` (`#875 <https://github.com/ets-labs/python-dependency-injector/pull/875>`_)
+- Fix incorrect monkeypatching during ``wire()`` that could violate MRO in some classes (`#886 <https://github.com/ets-labs/python-dependency-injector/pull/886>`_)
 - ABI3 wheels are now published for CPython.
 - Drop support of Python 3.7.
 
@@ -371,8 +387,8 @@ Many thanks to `ZipFile <https://github.com/ZipFile>`_ for both contributions.
 - Make refactoring of wiring module and tests.
   See PR # `#406 <https://github.com/ets-labs/python-dependency-injector/issues/406>`_.
   Thanks to `@withshubh <https://github.com/withshubh>`_ for the contribution:
-    - Remove unused imports in tests.
-    - Use literal syntax to create data structure in tests.
+  - Remove unused imports in tests.
+  - Use literal syntax to create data structure in tests.
 - Add integration with a static analysis tool `DeepSource <https://deepsource.io/>`_.
 
 4.26.0

docs/providers/resource.rst

@@ -61,11 +61,12 @@ When you call ``.shutdown()`` method on a resource provider, it will remove the
 if any, and switch to uninitialized state. Some of resource initializer types support specifying custom
 resource shutdown.
 
-Resource provider supports 3 types of initializers:
+Resource provider supports 4 types of initializers:
 
 - Function
-- Generator
-- Subclass of ``resources.Resource``
+- Context Manager
+- Generator (legacy)
+- Subclass of ``resources.Resource`` (legacy)
 
 Function initializer
 --------------------
@@ -103,8 +104,44 @@ you configure global resource:
 
 Function initializer does not provide a way to specify custom resource shutdown.
 
-Generator initializer
----------------------
+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:
 
@@ -154,8 +191,13 @@ object is not mandatory. You can leave ``yield`` statement empty:
            argument2=...,
        )
 
-Subclass initializer
---------------------
+.. 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``:
 
@@ -210,6 +252,72 @@ first argument.
 
 .. _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
 ---------------------------------------------------
 
@@ -263,10 +371,11 @@ Asynchronous function initializer:
            argument2=...,
        )
 
-Asynchronous generator initializer:
+Asynchronous Context Manager initializer:
 
 .. code-block:: python
 
+   @asynccontextmanager
    async def init_async_resource(argument1=..., argument2=...):
        connection = await connect()
        yield connection
@@ -358,5 +467,54 @@ See also:
 - 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::