ashka-lifecycle 0.1.0__tar.gz

ashka_lifecycle-0.1.0/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.3
+Name: ashka-lifecycle
+Version: 0.1.0
+Summary: dishka lifecycle support
+Author: handsome-Druid
+Author-email: handsome-Druid <102826168@qq.com>
+Requires-Dist: dishka>=1.9.0,<=1.10.1
+Requires-Python: >=3.10, <3.15
+Description-Content-Type: text/markdown
+
+# ashka-lifecycle
+
+`ashka-lifecycle` adds an application bootstrap phase to dishka containers. Dependencies
+registered with `AshkaScope.BOOTSTRAP` are created eagerly when the root
+container is initialized, while retaining the dependency, caching, and
+shutdown behavior of dishka's `Scope.APP`. Both synchronous and asynchronous
+containers support explicit initialization and initialization through their
+context managers.
+
+The implementation is designed to keep the integration with dishka minimally
+intrusive. ashka-lifecycle extends the public provider and container construction APIs,
+while leaving dishka's scope and factory implementations unchanged. The
+`AshkaScope.BOOTSTRAP` value is only an ashka-side marker; the provider maps it
+to dishka's native `Scope.APP` instead of introducing a new dishka scope.
+
+ashka-lifecycle maintains its own registry of Bootstrap provider sources and the
+corresponding dependency keys for each container. When a container is entered,
+ashka-lifecycle looks up the registered keys and eagerly resolves them using the existing
+container API. Synchronous containers resolve them one by one, while
+asynchronous containers resolve them concurrently. This keeps the changes
+localized to the public extension points and leaves dishka's existing scope,
+caching, shutdown, and factory behavior in control.
+
+`ashka-lifecycle` can also be installed and used independently from `ashka` as
+an escape hatch. In this mode, manually import `ashka_lifecycle` before
+importing `dishka` to ensure that its patches are applied.
+
+See more details and about how to use:
+
+[English](https://github.com/handsome-Druid/ashka/blob/master/docs/en/features/bootstrap-lifecycle.md)
+[中文](https://github.com/handsome-Druid/ashka/blob/master/docs/zh/features/bootstrap-lifecycle.md)

ashka_lifecycle-0.1.0/README.md

@@ -0,0 +1,31 @@
+# ashka-lifecycle
+
+`ashka-lifecycle` adds an application bootstrap phase to dishka containers. Dependencies
+registered with `AshkaScope.BOOTSTRAP` are created eagerly when the root
+container is initialized, while retaining the dependency, caching, and
+shutdown behavior of dishka's `Scope.APP`. Both synchronous and asynchronous
+containers support explicit initialization and initialization through their
+context managers.
+
+The implementation is designed to keep the integration with dishka minimally
+intrusive. ashka-lifecycle extends the public provider and container construction APIs,
+while leaving dishka's scope and factory implementations unchanged. The
+`AshkaScope.BOOTSTRAP` value is only an ashka-side marker; the provider maps it
+to dishka's native `Scope.APP` instead of introducing a new dishka scope.
+
+ashka-lifecycle maintains its own registry of Bootstrap provider sources and the
+corresponding dependency keys for each container. When a container is entered,
+ashka-lifecycle looks up the registered keys and eagerly resolves them using the existing
+container API. Synchronous containers resolve them one by one, while
+asynchronous containers resolve them concurrently. This keeps the changes
+localized to the public extension points and leaves dishka's existing scope,
+caching, shutdown, and factory behavior in control.
+
+`ashka-lifecycle` can also be installed and used independently from `ashka` as
+an escape hatch. In this mode, manually import `ashka_lifecycle` before
+importing `dishka` to ensure that its patches are applied.
+
+See more details and about how to use:
+
+[English](https://github.com/handsome-Druid/ashka/blob/master/docs/en/features/bootstrap-lifecycle.md)
+[中文](https://github.com/handsome-Druid/ashka/blob/master/docs/zh/features/bootstrap-lifecycle.md)

ashka_lifecycle-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[project]
+name = "ashka-lifecycle"
+version = "0.1.0"
+description = "dishka lifecycle support"
+readme = "README.md"
+requires-python = ">=3.10,<3.15"
+dependencies = ["dishka>=1.9.0,<=1.10.1"]
+
+[[project.authors]]
+name = "handsome-Druid"
+email = "102826168@qq.com"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ashka>=0.8.0",
+    "fastapi>=0.141.1",
+    "httpx2>=2.12.0",
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.16.4",
+]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.coverage.run]
+branch = true
+patch = ["subprocess"]
+
+[tool.coverage.report]
+fail_under = 100
+
+[tool.pytest.ini_options]
+addopts = "-n auto"
+
+[tool.ruff]
+exclude = ["typings"]

ashka_lifecycle-0.1.0/pyproject.toml.orig

@@ -0,0 +1,48 @@
+[project]
+name = "ashka-lifecycle"
+version = "0.1.0"
+description = "dishka lifecycle support"
+readme = "README.md"
+authors = [
+    { name = "handsome-Druid", email = "102826168@qq.com" }
+]
+requires-python = ">=3.10,<3.15"
+dependencies = [
+    "dishka>=1.9.0,<=1.10.1",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ashka>=0.8.0",
+    "fastapi>=0.141.1",
+    "httpx2>=2.12.0",
+    "pyright>=1.1.411",
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
+    "ruff>=0.16.4",
+]
+
+[[tool.uv.index]]
+name = "testpypi"
+url = "https://test.pypi.org/simple/"
+publish-url = "https://test.pypi.org/legacy/"
+explicit = true
+
+[tool.coverage.run]
+branch = true
+patch = ["subprocess"]
+
+[tool.coverage.report]
+fail_under = 100
+
+[tool.pytest.ini_options]
+addopts = "-n auto"
+
+[tool.ruff]
+exclude = ["typings"]

ashka_lifecycle-0.1.0/src/ashka_lifecycle/__init__.py

@@ -0,0 +1,11 @@
+__all__ = [
+    "AshkaScope",
+    "make_async_container",
+    "make_container",
+    "provide",
+]
+
+from .async_container import make_async_container
+from .container import make_container
+from .entities.scope import AshkaScope
+from .provider import provide  # pyright: ignore[reportUnknownVariableType]

ashka_lifecycle-0.1.0/src/ashka_lifecycle/__init__.pyi

@@ -0,0 +1,10 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from .async_container import make_async_container
+from .container import make_container
+from .entities.scope import AshkaScope
+from .provider import provide
+
+__all__ = ["AshkaScope", "make_async_container", "make_container", "provide"]

ashka_lifecycle-0.1.0/src/ashka_lifecycle/async_container.py

@@ -0,0 +1,62 @@
+from asyncio import gather
+from typing import Any, cast
+
+import dishka
+from dishka import AsyncContainer
+from dishka.provider import BaseProvider
+
+from ashka_lifecycle.entities.bootstrap import (
+    bootstrap_keys_by_container,
+    bootstrap_sources,  # pyright: ignore[reportUnknownVariableType]
+)
+
+__all__ = ["make_async_container"]
+
+_aenter = AsyncContainer.__aenter__
+
+
+async def __aenter__(self: AsyncContainer):
+    aenter = await _aenter(self)
+
+    if self in bootstrap_keys_by_container:
+        await gather(
+            *(
+                self.get(key.type_hint, key.component)
+                for key in bootstrap_keys_by_container[self]
+            )
+        )
+
+    return aenter
+
+
+class AsyncContainerType(AsyncContainer):
+    __slots__ = ()
+
+    __aenter__ = __aenter__
+
+    async def init(self) -> None:
+        await self.__aenter__()
+
+
+AsyncContainer.__aenter__ = __aenter__
+AsyncContainer.init = AsyncContainerType.init  # pyright: ignore[reportAttributeAccessIssue]
+
+_make_async_container = dishka.make_async_container
+
+
+def make_async_container(*providers: BaseProvider, **kwargs: Any) -> AsyncContainerType:
+    bootstrap_keys_by_container[
+        async_container := _make_async_container(*providers, **kwargs)
+    ] = [
+        factory.provides.with_component(provider.component)
+        for provider in providers
+        for factory in provider.factories
+        if getattr(factory.source, "__func__", factory.source) in bootstrap_sources
+    ]
+
+    return cast(AsyncContainerType, async_container)
+
+
+dishka.make_async_container = dishka.async_container.make_async_container = (
+    make_async_container
+)

ashka_lifecycle-0.1.0/src/ashka_lifecycle/async_container.pyi

@@ -0,0 +1,25 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from typing import Any
+from dishka import AsyncContainer
+from dishka.provider import BaseProvider
+
+__all__ = ["make_async_container"]
+_aenter = ...
+async def __aenter__(self: AsyncContainer): # -> AsyncContainer:
+    ...
+
+class AsyncContainerType(AsyncContainer):
+    __slots__ = ...
+    __aenter__ = ...
+    async def init(self) -> None:
+        ...
+    
+
+
+_make_async_container = ...
+def make_async_container(*providers: BaseProvider, **kwargs: Any) -> AsyncContainerType:
+    ...
+

ashka_lifecycle-0.1.0/src/ashka_lifecycle/container.py

@@ -0,0 +1,53 @@
+from typing import Any, cast
+
+import dishka
+from dishka import Container
+from dishka.provider import BaseProvider
+
+from ashka_lifecycle.entities.bootstrap import (
+    bootstrap_keys_by_container,
+    bootstrap_sources,  # pyright: ignore[reportUnknownVariableType]
+)
+
+__all__ = ["make_container"]
+
+_enter = Container.__enter__
+
+
+def __enter__(self: Container):
+    enter = _enter(self)
+
+    if self in bootstrap_keys_by_container:
+        for key in bootstrap_keys_by_container[self]:
+            self.get(key.type_hint, key.component)
+
+    return enter
+
+
+class ContainerType(Container):
+    __slots__ = ()
+
+    __enter__ = __enter__
+
+    def init(self) -> None:
+        self.__enter__()
+
+
+Container.__enter__ = __enter__
+Container.init = ContainerType.init  # pyright: ignore[reportAttributeAccessIssue]
+
+_make_container = dishka.make_container
+
+
+def make_container(*providers: BaseProvider, **kwargs: Any) -> ContainerType:
+    bootstrap_keys_by_container[container := _make_container(*providers, **kwargs)] = [
+        factory.provides.with_component(provider.component)
+        for provider in providers
+        for factory in provider.factories
+        if getattr(factory.source, "__func__", factory.source) in bootstrap_sources
+    ]
+
+    return cast(ContainerType, container)
+
+
+dishka.make_container = dishka.container.make_container = make_container

ashka_lifecycle-0.1.0/src/ashka_lifecycle/container.pyi

@@ -0,0 +1,25 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from typing import Any
+from dishka import Container
+from dishka.provider import BaseProvider
+
+__all__ = ["make_container"]
+_enter = ...
+def __enter__(self: Container): # -> Container:
+    ...
+
+class ContainerType(Container):
+    __slots__ = ...
+    __enter__ = ...
+    def init(self) -> None:
+        ...
+    
+
+
+_make_container = ...
+def make_container(*providers: BaseProvider, **kwargs: Any) -> ContainerType:
+    ...
+

ashka_lifecycle-0.1.0/src/ashka_lifecycle/entities/bootstrap.py

@@ -0,0 +1,23 @@
+from weakref import WeakKeyDictionary, WeakSet
+
+from dishka import AsyncContainer, Container, DependencyKey
+from dishka.provider.make_factory import ProvideSource
+
+bootstrap_sources: WeakSet[ProvideSource] = WeakSet()  # pyright: ignore[reportUnknownVariableType]
+
+if all(
+    hasattr(Container_, "__weakref__") for Container_ in (Container, AsyncContainer)
+):
+    bootstrap_keys_by_container: (  # pragma: nocover
+        WeakKeyDictionary[
+            Container | AsyncContainer,
+            list[DependencyKey],
+        ]
+        | dict[
+            Container | AsyncContainer,
+            list[DependencyKey],
+        ]
+    ) = WeakKeyDictionary()
+
+else:
+    bootstrap_keys_by_container = {}  # pragma: nocover

ashka_lifecycle-0.1.0/src/ashka_lifecycle/entities/bootstrap.pyi

@@ -0,0 +1,13 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from weakref import WeakKeyDictionary, WeakSet
+from dishka import AsyncContainer, Container, DependencyKey
+from dishka.provider.make_factory import ProvideSource
+
+bootstrap_sources: WeakSet[ProvideSource] = ...
+if all(hasattr(Container_, "__weakref__") for Container_ in (Container, AsyncContainer)):
+    bootstrap_keys_by_container: (WeakKeyDictionary[Container | AsyncContainer, list[DependencyKey],] | dict[Container | AsyncContainer, list[DependencyKey],]) = ...
+else:
+    bootstrap_keys_by_container = ...

ashka_lifecycle-0.1.0/src/ashka_lifecycle/entities/scope.py

@@ -0,0 +1,7 @@
+from enum import Enum
+
+__all__ = ["AshkaScope"]
+
+
+class AshkaScope(Enum):
+    BOOTSTRAP = "BOOTSTRAP"

ashka_lifecycle-0.1.0/src/ashka_lifecycle/entities/scope.pyi

@@ -0,0 +1,11 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from enum import Enum
+
+__all__ = ["AshkaScope"]
+class AshkaScope(Enum):
+    BOOTSTRAP = ...
+
+

ashka_lifecycle-0.1.0/src/ashka_lifecycle/provider/__init__.py

@@ -0,0 +1,3 @@
+from .make_factory import provide  # pyright: ignore[reportUnknownVariableType]
+
+__all__ = ["provide"]

ashka_lifecycle-0.1.0/src/ashka_lifecycle/provider/__init__.pyi

@@ -0,0 +1,7 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from .make_factory import provide
+
+__all__ = ["provide"]

ashka_lifecycle-0.1.0/src/ashka_lifecycle/provider/make_factory.py

@@ -0,0 +1,54 @@
+from collections.abc import Callable
+from typing import Any, overload
+
+from dishka import BaseScope, Scope
+from dishka import provide as _provide  # pyright: ignore[reportUnknownVariableType]
+from dishka.dependency_source.composite import CompositeDependencySource
+from dishka.provider.make_factory import ProvideSource
+
+from ashka_lifecycle.entities.bootstrap import (
+    bootstrap_sources,  # pyright: ignore[reportUnknownVariableType]
+)
+from ashka_lifecycle.entities.scope import AshkaScope
+
+__all__ = ["provide"]
+
+
+@overload
+def provide(
+    *, scope: BaseScope | AshkaScope | None = None, **kwargs: Any
+) -> Callable[[Callable[..., Any]], CompositeDependencySource]: ...
+
+
+@overload
+def provide(
+    source: ProvideSource,  # pyright: ignore[reportUnknownParameterType]
+    *,
+    scope: BaseScope | AshkaScope | None = None,
+    **kwargs: Any,
+) -> CompositeDependencySource: ...
+
+
+def provide(
+    source: ProvideSource | None = None,  # pyright: ignore[reportUnknownParameterType]
+    *,
+    scope: BaseScope | AshkaScope | None = None,
+    **kwargs: Any,
+) -> (
+    CompositeDependencySource
+    | Callable[
+        [Callable[..., Any]],
+        CompositeDependencySource,
+    ]
+):
+    if scope is not AshkaScope.BOOTSTRAP:
+        return _provide(source, scope=scope, **kwargs)
+
+    def scoped(source: ProvideSource):  # pyright: ignore[reportUnknownParameterType]
+        bootstrap_sources.add(getattr(source, "__func__", source))  # pyright: ignore[reportUnknownArgumentType, reportUnknownMemberType]
+        return _provide(source, scope=Scope.APP, **kwargs)
+
+    if source is not None:
+        return scoped(source)
+
+    return scoped  # pyright: ignore[reportUnknownVariableType]

ashka_lifecycle-0.1.0/src/ashka_lifecycle/provider/make_factory.pyi

@@ -0,0 +1,23 @@
+"""
+This type stub file was generated by pyright.
+"""
+
+from collections.abc import Callable
+from typing import Any, overload
+from dishka import BaseScope
+from dishka.dependency_source.composite import CompositeDependencySource
+from dishka.provider.make_factory import ProvideSource
+from ashka_lifecycle.entities.scope import AshkaScope
+
+__all__ = ["provide"]
+@overload
+def provide(*, scope: BaseScope | AshkaScope | None = ..., **kwargs: Any) -> Callable[[Callable[..., Any]], CompositeDependencySource]:
+    ...
+
+@overload
+def provide(source: ProvideSource, *, scope: BaseScope | AshkaScope | None = ..., **kwargs: Any) -> CompositeDependencySource:
+    ...
+
+def provide(source: ProvideSource | None = ..., *, scope: BaseScope | AshkaScope | None = ..., **kwargs: Any) -> (CompositeDependencySource | Callable[[Callable[..., Any]], CompositeDependencySource,]):
+    ...
+