nuke-di 1.0.0__tar.gz

nuke_di-1.0.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+.DS_Store
+.idea/
+.vscode/

nuke_di-1.0.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and the project adheres to [Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-10-08
+
+First public release, extracted from the `nuke.di` package of the nuke framework.
+
+### Added
+
+- `Client` / `NotSingletonClient` base classes with async `connect()` / `disconnect()` hooks.
+- `Dependencies` container and the global `DI` instance: `resolve`, `inject`, `mock`, `flush`,
+  `connect` / `disconnect` and `async with` support.
+- `client_dataclass` decorator.
+- `CONNECT_TIMEOUT_SECONDS` setting and `DependenciesSettings`.
+
+### Changed compared to `nuke.di`
+
+- No runtime dependencies: settings no longer use `pydantic-settings`, logging uses the standard
+  `logging` module under the `nuke_di` logger.
+- Clients no longer get a per-class `_logger` attribute.
+
+[1.0.0]: https://github.com/troyan-dy/nuke-di/releases/tag/v1.0.0

nuke_di-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dmitriy Troyan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nuke_di-1.0.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.5
+Name: nuke-di
+Version: 1.0.0
+Summary: Simplest type-hint based dependency injection for async Python projects
+Project-URL: Homepage, https://github.com/troyan-dy/nuke-di
+Project-URL: Repository, https://github.com/troyan-dy/nuke-di
+Project-URL: Issues, https://github.com/troyan-dy/nuke-di/issues
+Project-URL: Changelog, https://github.com/troyan-dy/nuke-di/blob/master/CHANGELOG.md
+Author: Dmitriy Troyan
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,dependency-injection,di,ioc,type-hints
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# nuke-di
+
+[![PyPI](https://img.shields.io/pypi/v/nuke-di)](https://pypi.org/project/nuke-di/)
+[![Python](https://img.shields.io/pypi/pyversions/nuke-di)](https://pypi.org/project/nuke-di/)
+[![CI](https://github.com/troyan-dy/nuke-di/actions/workflows/ci.yml/badge.svg)](https://github.com/troyan-dy/nuke-di/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/nuke-di)](LICENSE)
+
+The simplest dependency injection for async Python projects.
+
+Dependencies are declared with plain type hints. `nuke-di` builds the dependency tree,
+creates every client once and drives its async lifecycle: `connect()` on startup and
+`disconnect()` on shutdown, in reverse order.
+
+It was extracted from the DI layer of a production Python microservice framework
+and has no runtime dependencies.
+
+## Installation
+
+```bash
+pip install nuke-di
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+import asyncio
+
+from nuke_di import DI, Client
+
+
+class Database(Client):
+    async def connect(self) -> None:
+        print("database: connected")
+
+    async def disconnect(self) -> None:
+        print("database: disconnected")
+
+    async def fetch_user(self, user_id: int) -> str:
+        return f"user-{user_id}"
+
+
+class UserService(Client):
+    def __init__(self, db: Database) -> None:
+        self._db = db
+
+    async def greet(self, user_id: int) -> str:
+        return f"Hello, {await self._db.fetch_user(user_id)}!"
+
+
+async def handler(user_id: int, users: UserService) -> str:
+    return await users.greet(user_id)
+
+
+async def main() -> None:
+    injected = DI.inject(handler)  # resolves UserService -> Database
+
+    async with DI:  # connect() every client, disconnect() on exit
+        print(await injected(42))
+
+
+asyncio.run(main())
+```
+
+```text
+database: connected
+Hello, user-42!
+database: disconnected
+```
+
+## Concepts
+
+### Clients
+
+Every dependency is a subclass of one of two base classes:
+
+| Base class           | Instances                                          |
+|----------------------|----------------------------------------------------|
+| `Client`             | Singleton: one instance per `Dependencies`         |
+| `NotSingletonClient` | A new instance for every consumer that declares it |
+
+Override the async `connect()` / `disconnect()` methods to open and release resources
+such as connection pools:
+
+```python
+class Redis(Client):
+    def __init__(self) -> None:
+        self._pool: Pool | None = None
+
+    async def connect(self) -> None:
+        self._pool = await create_pool()
+
+    async def disconnect(self) -> None:
+        if self._pool is not None:
+            await self._pool.close()
+            self._pool = None
+```
+
+### Composition
+
+A client declares its own dependencies in `__init__`. Only arguments annotated with a
+client type are injected; resolution is recursive.
+
+```python
+class BusinessLogic(Client):
+    def __init__(self, pg: Postgres, grpc: GrpcClient) -> None:
+        self._pg = pg
+        self._grpc = grpc
+```
+
+### Container
+
+`Dependencies` is the container. `DI` is a ready-to-use global instance; create your own
+when you need isolation, e.g. in tests.
+
+| Method               | Description                                                             |
+|----------------------|-------------------------------------------------------------------------|
+| `resolve(cls)`       | Build `cls` and its dependency tree. Idempotent for `Client`.           |
+| `inject(func)`       | Return `functools.partial(func, ...)` with client arguments bound.      |
+| `connect()`          | Call `connect()` on every resolved client, in resolution order.         |
+| `disconnect()`       | Call `disconnect()` in reverse order, then `flush()` the container.     |
+| `async with`         | `connect()` on enter, `disconnect()` on exit.                           |
+| `mock(cls, new=None)`| Register a replacement for `cls` (an autospec mock by default).         |
+| `flush()`            | Forget every resolved client.                                           |
+
+`resolve`, `inject`, `mock` and `flush` only work while the container is disconnected:
+the whole tree is built before startup.
+
+A failing `disconnect()` is logged and does not stop the other clients from shutting down.
+
+### Dataclass clients
+
+`client_dataclass` turns a class into a `Client` and a dataclass at once, so the fields
+become the injected dependencies:
+
+```python
+from nuke_di import client_dataclass
+
+
+@client_dataclass(frozen=True)
+class Checkout:
+    pg: Postgres
+    payments: PaymentsClient
+```
+
+It accepts the same keyword arguments as `dataclasses.dataclass`.
+
+## Testing
+
+Register mocks before the tree is resolved; every consumer then receives the mock.
+
+```python
+from unittest.mock import call
+
+from nuke_di import Dependencies
+
+
+async def test_greet() -> None:
+    deps = Dependencies()
+    db = deps.mock(Database)
+    db.fetch_user.return_value = "alice"
+
+    users = deps.resolve(UserService)
+    async with deps:
+        assert await users.greet(1) == "Hello, alice!"
+
+    assert db.fetch_user.await_args_list == [call(1)]
+```
+
+## Configuration
+
+| Environment variable      | Default | Description                                        |
+|---------------------------|---------|----------------------------------------------------|
+| `CONNECT_TIMEOUT_SECONDS` | `30`    | Timeout for a single client's `connect()`, seconds |
+
+The value is read when a `Dependencies` instance is created. You can also pass it explicitly:
+
+```python
+from nuke_di import Dependencies, DependenciesSettings
+
+deps = Dependencies(settings=DependenciesSettings(connect_timeout=5))
+```
+
+## Errors
+
+| Exception                   | Raised when                                               |
+|-----------------------------|-----------------------------------------------------------|
+| `InitializeDependencyError` | A client's `__init__` raised                              |
+| `ConnectError`              | A client's `connect()` raised, or the container state is wrong (e.g. resolving after connect) |
+| `ConnectTimeoutError`       | A client's `connect()` exceeded `CONNECT_TIMEOUT_SECONDS` |
+
+`InitializeDependencyError` and `ConnectError` derive from `SystemExit`: an application
+whose dependencies cannot start is expected to stop. Catch them explicitly if you need
+different behavior; the original exception is available as `__cause__`.
+
+`nuke-di` logs through the standard `logging` module under the `nuke_di` logger.
+
+## Development
+
+```bash
+uv sync
+uv run pytest --cov
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+## License
+
+[MIT](LICENSE)

nuke_di-1.0.0/README.md

@@ -0,0 +1,210 @@
+# nuke-di
+
+[![PyPI](https://img.shields.io/pypi/v/nuke-di)](https://pypi.org/project/nuke-di/)
+[![Python](https://img.shields.io/pypi/pyversions/nuke-di)](https://pypi.org/project/nuke-di/)
+[![CI](https://github.com/troyan-dy/nuke-di/actions/workflows/ci.yml/badge.svg)](https://github.com/troyan-dy/nuke-di/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/nuke-di)](LICENSE)
+
+The simplest dependency injection for async Python projects.
+
+Dependencies are declared with plain type hints. `nuke-di` builds the dependency tree,
+creates every client once and drives its async lifecycle: `connect()` on startup and
+`disconnect()` on shutdown, in reverse order.
+
+It was extracted from the DI layer of a production Python microservice framework
+and has no runtime dependencies.
+
+## Installation
+
+```bash
+pip install nuke-di
+```
+
+Requires Python 3.11+.
+
+## Quick start
+
+```python
+import asyncio
+
+from nuke_di import DI, Client
+
+
+class Database(Client):
+    async def connect(self) -> None:
+        print("database: connected")
+
+    async def disconnect(self) -> None:
+        print("database: disconnected")
+
+    async def fetch_user(self, user_id: int) -> str:
+        return f"user-{user_id}"
+
+
+class UserService(Client):
+    def __init__(self, db: Database) -> None:
+        self._db = db
+
+    async def greet(self, user_id: int) -> str:
+        return f"Hello, {await self._db.fetch_user(user_id)}!"
+
+
+async def handler(user_id: int, users: UserService) -> str:
+    return await users.greet(user_id)
+
+
+async def main() -> None:
+    injected = DI.inject(handler)  # resolves UserService -> Database
+
+    async with DI:  # connect() every client, disconnect() on exit
+        print(await injected(42))
+
+
+asyncio.run(main())
+```
+
+```text
+database: connected
+Hello, user-42!
+database: disconnected
+```
+
+## Concepts
+
+### Clients
+
+Every dependency is a subclass of one of two base classes:
+
+| Base class           | Instances                                          |
+|----------------------|----------------------------------------------------|
+| `Client`             | Singleton: one instance per `Dependencies`         |
+| `NotSingletonClient` | A new instance for every consumer that declares it |
+
+Override the async `connect()` / `disconnect()` methods to open and release resources
+such as connection pools:
+
+```python
+class Redis(Client):
+    def __init__(self) -> None:
+        self._pool: Pool | None = None
+
+    async def connect(self) -> None:
+        self._pool = await create_pool()
+
+    async def disconnect(self) -> None:
+        if self._pool is not None:
+            await self._pool.close()
+            self._pool = None
+```
+
+### Composition
+
+A client declares its own dependencies in `__init__`. Only arguments annotated with a
+client type are injected; resolution is recursive.
+
+```python
+class BusinessLogic(Client):
+    def __init__(self, pg: Postgres, grpc: GrpcClient) -> None:
+        self._pg = pg
+        self._grpc = grpc
+```
+
+### Container
+
+`Dependencies` is the container. `DI` is a ready-to-use global instance; create your own
+when you need isolation, e.g. in tests.
+
+| Method               | Description                                                             |
+|----------------------|-------------------------------------------------------------------------|
+| `resolve(cls)`       | Build `cls` and its dependency tree. Idempotent for `Client`.           |
+| `inject(func)`       | Return `functools.partial(func, ...)` with client arguments bound.      |
+| `connect()`          | Call `connect()` on every resolved client, in resolution order.         |
+| `disconnect()`       | Call `disconnect()` in reverse order, then `flush()` the container.     |
+| `async with`         | `connect()` on enter, `disconnect()` on exit.                           |
+| `mock(cls, new=None)`| Register a replacement for `cls` (an autospec mock by default).         |
+| `flush()`            | Forget every resolved client.                                           |
+
+`resolve`, `inject`, `mock` and `flush` only work while the container is disconnected:
+the whole tree is built before startup.
+
+A failing `disconnect()` is logged and does not stop the other clients from shutting down.
+
+### Dataclass clients
+
+`client_dataclass` turns a class into a `Client` and a dataclass at once, so the fields
+become the injected dependencies:
+
+```python
+from nuke_di import client_dataclass
+
+
+@client_dataclass(frozen=True)
+class Checkout:
+    pg: Postgres
+    payments: PaymentsClient
+```
+
+It accepts the same keyword arguments as `dataclasses.dataclass`.
+
+## Testing
+
+Register mocks before the tree is resolved; every consumer then receives the mock.
+
+```python
+from unittest.mock import call
+
+from nuke_di import Dependencies
+
+
+async def test_greet() -> None:
+    deps = Dependencies()
+    db = deps.mock(Database)
+    db.fetch_user.return_value = "alice"
+
+    users = deps.resolve(UserService)
+    async with deps:
+        assert await users.greet(1) == "Hello, alice!"
+
+    assert db.fetch_user.await_args_list == [call(1)]
+```
+
+## Configuration
+
+| Environment variable      | Default | Description                                        |
+|---------------------------|---------|----------------------------------------------------|
+| `CONNECT_TIMEOUT_SECONDS` | `30`    | Timeout for a single client's `connect()`, seconds |
+
+The value is read when a `Dependencies` instance is created. You can also pass it explicitly:
+
+```python
+from nuke_di import Dependencies, DependenciesSettings
+
+deps = Dependencies(settings=DependenciesSettings(connect_timeout=5))
+```
+
+## Errors
+
+| Exception                   | Raised when                                               |
+|-----------------------------|-----------------------------------------------------------|
+| `InitializeDependencyError` | A client's `__init__` raised                              |
+| `ConnectError`              | A client's `connect()` raised, or the container state is wrong (e.g. resolving after connect) |
+| `ConnectTimeoutError`       | A client's `connect()` exceeded `CONNECT_TIMEOUT_SECONDS` |
+
+`InitializeDependencyError` and `ConnectError` derive from `SystemExit`: an application
+whose dependencies cannot start is expected to stop. Catch them explicitly if you need
+different behavior; the original exception is available as `__cause__`.
+
+`nuke-di` logs through the standard `logging` module under the `nuke_di` logger.
+
+## Development
+
+```bash
+uv sync
+uv run pytest --cov
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+## License
+
+[MIT](LICENSE)

nuke_di-1.0.0/pyproject.toml

@@ -0,0 +1,75 @@
+[project]
+name = "nuke-di"
+version = "1.0.0"
+description = "Simplest type-hint based dependency injection for async Python projects"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Dmitriy Troyan" }]
+requires-python = ">=3.11"
+dependencies = []
+keywords = ["di", "dependency-injection", "asyncio", "ioc", "type-hints"]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/troyan-dy/nuke-di"
+Repository = "https://github.com/troyan-dy/nuke-di"
+Issues = "https://github.com/troyan-dy/nuke-di/issues"
+Changelog = "https://github.com/troyan-dy/nuke-di/blob/master/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+  "mypy>=1.13",
+  "pytest>=8.3",
+  "pytest-asyncio>=0.24",
+  "pytest-cov>=6.0",
+  "ruff>=0.8",
+]
+
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "CHANGELOG.md", "README.md", "LICENSE"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/nuke_di"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "N", "B", "A", "UP", "ASYNC", "S", "RUF"]
+ignore = ["S101"]
+
+[tool.mypy]
+files = ["src", "tests"]
+strict = true
+disallow_any_generics = false
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["nuke_di"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true

nuke_di-1.0.0/src/nuke_di/__init__.py

@@ -0,0 +1,18 @@
+from nuke_di.core import DI, Dependencies
+from nuke_di.dataclass import client_dataclass
+from nuke_di.errors import ConnectError, ConnectTimeoutError, InitializeDependencyError, InvalidSignatureError
+from nuke_di.options import DependenciesSettings
+from nuke_di.types import Client, NotSingletonClient
+
+__all__ = (
+    "DI",
+    "Client",
+    "ConnectError",
+    "ConnectTimeoutError",
+    "Dependencies",
+    "DependenciesSettings",
+    "InitializeDependencyError",
+    "InvalidSignatureError",
+    "NotSingletonClient",
+    "client_dataclass",
+)

nuke_di-1.0.0/src/nuke_di/core.py

@@ -0,0 +1,148 @@
+import asyncio
+import inspect
+import logging
+from collections import OrderedDict
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from functools import partial
+from typing import Any, TypeVar, cast, get_type_hints
+from unittest.mock import create_autospec
+
+from nuke_di.errors import ConnectError, ConnectTimeoutError, InitializeDependencyError, InvalidSignatureError
+from nuke_di.options import DependenciesSettings
+from nuke_di.types import Client, NotSingletonClient
+from nuke_di.utils import isa, select_values, sname, walk_values
+
+logger = logging.getLogger(__name__)
+isclient = isa(Client)
+isnotsingleton = isa(NotSingletonClient)
+
+CT = TypeVar("CT", bound=NotSingletonClient)
+
+
+@dataclass(repr=False)
+class Dependencies:
+    clients: OrderedDict[type[NotSingletonClient], NotSingletonClient] = field(default_factory=OrderedDict)
+    connect_clients: list[NotSingletonClient] = field(default_factory=list)
+    settings: DependenciesSettings = field(default_factory=DependenciesSettings)
+    connected: bool = field(default=False, init=False)
+
+    async def __aenter__(self) -> None:
+        await self.connect()
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.disconnect()
+
+    def flush(self) -> None:
+        if self.connected is True:
+            raise ConnectError("already connected")
+
+        self.clients = OrderedDict()
+        self.connect_clients = []
+
+    async def connect(self) -> None:
+        if self.connected is True:
+            raise ConnectError("already connected")
+
+        self.connected = True
+
+        for client in self.connect_clients:
+            name = sname(client)
+            logger.debug("Connecting client %s", name)
+            try:
+                await asyncio.wait_for(client.connect(), timeout=self.settings.connect_timeout)
+
+            except TimeoutError as exc:
+                logger.exception("Timeout occurred connecting client %s", name)
+                raise ConnectTimeoutError(f"Timeout occurred connecting client {name}") from exc
+
+            except Exception as e:
+                logger.exception("Error occurred connecting client %s", name)
+                raise ConnectError(f"Error occurred connecting client {name}") from e
+
+    async def disconnect(self) -> None:
+        if self.connected is False:
+            raise ConnectError("already disconnected")
+
+        self.connected = False
+
+        for client in reversed(self.connect_clients):
+            name = sname(client)
+            logger.debug("Disconnecting client %s", name)
+            try:
+                await client.disconnect()
+            except Exception:
+                # The client failed, but the rest still have to be stopped
+                logger.exception("Failed to disconnect client %s", name)
+
+        self.flush()
+
+    def resolve(self, cls: type[CT]) -> CT:
+        """
+        Idempotent operation.
+        """
+        if self.connected is True:
+            raise ConnectError("already connected")
+
+        inst = self.clients.get(cls)
+        if inst is not None:
+            return cast(CT, inst)
+
+        name = sname(cls)
+        logger.debug('Resolving dependency "%s"', name)
+
+        # A client may appear in the class annotations but not in __init__,
+        # which means it is not _our_ dependency
+        type_hints = get_type_hints(cls.__init__)
+        type_hints.pop("self", None)
+
+        deps = select_values(isnotsingleton, type_hints)
+
+        init = dict(walk_values(self.resolve, deps))
+        try:
+            inst = cls(**init)
+        except Exception as e:
+            logger.exception("Error occurred during initialize client %s", name)
+            raise InitializeDependencyError(f"Error occurred during initialize client {name}") from e
+
+        if isclient(cls):
+            self.clients[cls] = inst
+
+        self.connect_clients.append(inst)
+        return inst
+
+    def inject(self, func: Callable) -> Callable:
+        """
+        Bind the dependencies from the signature of `func`.
+
+        note: `func` may be a function or a class.
+        """
+        if self.connected is True:
+            raise ConnectError("already connected")
+
+        signature = self._inspect(func)
+        return partial(func, **signature)
+
+    def mock(self, cls: type[CT], new: CT | None = None) -> CT:
+        if self.connected is True:
+            raise ConnectError("already connected")
+        return self.clients.setdefault(cls, new or create_autospec(cls))  # type: ignore[return-value]
+
+    def _inspect(self, func: Callable) -> dict[str, NotSingletonClient]:
+        logger.debug('Parsing signature of func "%s"', sname(func))
+        signature: dict[str, NotSingletonClient] = {}
+
+        sig: dict[str, Any] = get_type_hints(func)
+        sig.pop("return", None)
+
+        for key, value in sig.items():
+            if value is inspect.Parameter.empty:
+                raise InvalidSignatureError("Arguments without type hints are restricted")
+
+            if isnotsingleton(value):
+                signature[key] = self.resolve(value)
+
+        return signature
+
+
+DI = Dependencies()

nuke_di-1.0.0/src/nuke_di/dataclass.py

@@ -0,0 +1,32 @@
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any, TypeVar, dataclass_transform
+
+from nuke_di.types import Client, NotSingletonClient
+
+C = TypeVar("C")
+CT = TypeVar("CT", bound=NotSingletonClient)
+
+
+@dataclass_transform()
+def client_dataclass(_cls: type | None = None, **dataclass_kwargs: Any) -> Callable[[type[C]], type[CT]]:
+    """
+    Decorator that makes a class a `Client` subclass and a dataclass.
+
+    Accepts the same keyword arguments as `dataclasses.dataclass`.
+    """
+
+    def decorator(cls: type[C]) -> type[CT]:
+        if not issubclass(cls, Client):
+            attrs = {name: value for name, value in cls.__dict__.items() if name not in {"__dict__", "__weakref__"}}
+            new_cls = type(cls.__name__, (cls, Client), attrs)
+        else:
+            new_cls = cls
+
+        return dataclass(**dataclass_kwargs)(new_cls)
+
+    if inspect.isclass(_cls):
+        return decorator(_cls)
+
+    return decorator

nuke_di-1.0.0/src/nuke_di/errors.py

@@ -0,0 +1,26 @@
+class InvalidSignatureError(TypeError):
+    """
+    A signature contains an argument without a type hint.
+    """
+
+
+class ConnectError(SystemExit):
+    """
+    An error occurred while connecting clients.
+
+    It is a `SystemExit` on purpose: a client that failed to start should stop the application.
+    """
+
+
+class ConnectTimeoutError(ConnectError):
+    """
+    A client did not finish connecting in time.
+
+    The timeout is set by the `CONNECT_TIMEOUT_SECONDS` environment variable.
+    """
+
+
+class InitializeDependencyError(SystemExit):
+    """
+    A dependency raised an exception during initialization.
+    """

nuke_di-1.0.0/src/nuke_di/options.py

@@ -0,0 +1,14 @@
+import os
+from dataclasses import dataclass, field
+
+CONNECT_TIMEOUT_ENV = "CONNECT_TIMEOUT_SECONDS"
+DEFAULT_CONNECT_TIMEOUT = 30.0
+
+
+def _connect_timeout_from_env() -> float:
+    return float(os.environ.get(CONNECT_TIMEOUT_ENV, DEFAULT_CONNECT_TIMEOUT))
+
+
+@dataclass
+class DependenciesSettings:
+    connect_timeout: float = field(default_factory=_connect_timeout_from_env)

nuke_di-1.0.0/src/nuke_di/types.py

@@ -0,0 +1,24 @@
+class NotSingletonClient:
+    """
+    Base class for dependencies managed by `Dependencies`.
+
+    A new instance is created for every consumer that declares it.
+    """
+
+    async def connect(self) -> None:
+        """
+        Override this method to run an action after `__init__`.
+        """
+
+    async def disconnect(self) -> None:
+        """
+        Override this method to run an action before the object is dropped.
+        """
+
+
+class Client(NotSingletonClient):
+    """
+    Singleton client.
+
+    It is cached on resolution, so every consumer receives the same instance.
+    """

nuke_di-1.0.0/src/nuke_di/utils.py

@@ -0,0 +1,28 @@
+import inspect
+from collections.abc import Callable, Iterable, Iterator
+from typing import Any
+
+
+def iteritems(col: Any) -> Any:
+    if isinstance(col, dict):
+        return col.items()
+    return col
+
+
+def select_values(pred: Callable[[Any], bool], col: Iterable) -> Iterator:
+    return (i for i in iteritems(col) if pred(i[1]))
+
+
+def walk_values(prim: Callable[[Any], Any], col: Iterable) -> Iterator:
+    return ((k, prim(v)) for k, v in iteritems(col))
+
+
+def sname(obj: Any) -> str:
+    try:
+        return obj.__name__  # type: ignore[no-any-return]
+    except AttributeError:
+        return sname(obj.__class__)
+
+
+def isa(*types: type) -> Callable[[Any], bool]:
+    return lambda o: inspect.isclass(o) and issubclass(o, types)

nuke_di-1.0.0/tests/test_client_dataclass.py

@@ -0,0 +1,65 @@
+from dataclasses import FrozenInstanceError, is_dataclass
+
+import pytest
+
+from nuke_di import Client, Dependencies, NotSingletonClient, client_dataclass
+
+
+@client_dataclass
+class A:
+    pass
+
+
+class B(Client):
+    pass
+
+
+class C(NotSingletonClient):
+    pass
+
+
+@client_dataclass(frozen=True)
+class MyClient:
+    b: B
+    c: C
+    a: A
+
+    def get_a(self) -> A:
+        return self.a
+
+    def get_b(self) -> B:
+        return self.b
+
+    def get_c(self) -> C:
+        return self.c
+
+
+@pytest.fixture
+def my_client() -> MyClient:
+    di = Dependencies()
+    return di.resolve(MyClient)  # type: ignore[type-var]
+
+
+def test_methods(my_client: MyClient) -> None:
+    assert type(my_client.get_b()) is B
+    assert type(my_client.get_c()) is C
+    assert type(my_client.get_a()) is A
+
+
+def test_is_dataclass(my_client: MyClient) -> None:
+    assert is_dataclass(my_client)
+
+
+def test_dataclass_init(my_client: MyClient) -> None:
+    assert type(my_client.b) is B
+    assert type(my_client.c) is C
+    assert type(my_client.a) is A
+
+
+def test_frozen(my_client: MyClient) -> None:
+    with pytest.raises(FrozenInstanceError):
+        my_client.a = 9090  # type: ignore[assignment,misc]
+
+
+def test_client_inheritance(my_client: MyClient) -> None:
+    assert getattr(my_client, "connect", False)

nuke_di-1.0.0/tests/test_errors.py

@@ -0,0 +1,108 @@
+import asyncio
+
+import pytest
+
+from nuke_di import (
+    Client,
+    ConnectError,
+    ConnectTimeoutError,
+    Dependencies,
+    DependenciesSettings,
+    InitializeDependencyError,
+)
+
+
+class SlowClient(Client):
+    async def connect(self) -> None:
+        await asyncio.sleep(1)
+
+
+class BrokenConnectClient(Client):
+    async def connect(self) -> None:
+        raise RuntimeError("boom")
+
+
+class BrokenInitClient(Client):
+    def __init__(self) -> None:
+        raise RuntimeError("boom")
+
+
+class BrokenDisconnectClient(Client):
+    async def disconnect(self) -> None:
+        raise RuntimeError("boom")
+
+
+class TrackedClient(Client):
+    disconnected = False
+
+    async def disconnect(self) -> None:
+        TrackedClient.disconnected = True
+
+
+async def test_connect_timeout() -> None:
+    dep = Dependencies(settings=DependenciesSettings(connect_timeout=0.01))
+    dep.resolve(SlowClient)
+
+    with pytest.raises(ConnectTimeoutError):
+        await dep.connect()
+
+
+async def test_connect_error() -> None:
+    dep = Dependencies()
+    dep.resolve(BrokenConnectClient)
+
+    with pytest.raises(ConnectError) as exc_info:
+        await dep.connect()
+
+    assert not isinstance(exc_info.value, ConnectTimeoutError)
+    assert isinstance(exc_info.value.__cause__, RuntimeError)
+
+
+def test_initialize_error() -> None:
+    dep = Dependencies()
+
+    with pytest.raises(InitializeDependencyError):
+        dep.resolve(BrokenInitClient)
+
+
+async def test_disconnect_continues_after_failure() -> None:
+    dep = Dependencies()
+    # disconnect goes in reverse order, so the broken client is stopped first
+    dep.resolve(TrackedClient)
+    dep.resolve(BrokenDisconnectClient)
+
+    async with dep:
+        pass
+
+    assert TrackedClient.disconnected
+    assert dep.connect_clients == []
+
+
+async def test_connected_state_guards() -> None:
+    dep = Dependencies()
+
+    with pytest.raises(ConnectError):
+        await dep.disconnect()
+
+    async with dep:
+        with pytest.raises(ConnectError):
+            await dep.connect()
+        with pytest.raises(ConnectError):
+            dep.resolve(TrackedClient)
+        with pytest.raises(ConnectError):
+            dep.inject(test_initialize_error)
+        with pytest.raises(ConnectError):
+            dep.mock(TrackedClient)
+
+
+def test_settings_from_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CONNECT_TIMEOUT_SECONDS", "5")
+
+    assert DependenciesSettings().connect_timeout == 5
+    assert Dependencies().settings.connect_timeout == 5
+
+
+def test_settings_default(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("CONNECT_TIMEOUT_SECONDS", raising=False)
+
+    assert DependenciesSettings().connect_timeout == 30

nuke_di-1.0.0/tests/test_flush.py

@@ -0,0 +1,57 @@
+import pytest
+
+from nuke_di import Client, Dependencies, NotSingletonClient
+from nuke_di.errors import ConnectError
+
+
+class InnerDeps(NotSingletonClient):
+    pass
+
+
+class PublicClient(Client):
+    def __init__(self, inner: InnerDeps):
+        self.inner = inner
+
+    async def add(self, a: int, b: int) -> int:
+        return a + b
+
+
+class NewPublicClient(PublicClient):
+    pass
+
+
+async def test_cached_client() -> None:
+    dep = Dependencies()
+
+    client_1 = dep.resolve(PublicClient)
+    client_2 = dep.resolve(PublicClient)
+
+    assert client_1 is client_2
+
+
+async def test_not_singleton_client() -> None:
+    dep = Dependencies()
+
+    client_1 = dep.resolve(PublicClient)
+    client_2 = dep.resolve(NewPublicClient)
+
+    assert client_1.inner is not client_2.inner
+
+
+async def test_flush() -> None:
+    dep = Dependencies()
+
+    client_1 = dep.resolve(PublicClient)
+    dep.flush()
+    client_2 = dep.resolve(PublicClient)
+
+    assert client_1 is not client_2
+
+
+async def test_flush_on_connected() -> None:
+    dep = Dependencies()
+    dep.resolve(PublicClient)
+
+    async with dep:
+        with pytest.raises(ConnectError):
+            dep.flush()

nuke_di-1.0.0/tests/test_inject.py

@@ -0,0 +1,28 @@
+from nuke_di import Client, Dependencies, NotSingletonClient
+
+
+class InnerDeps(NotSingletonClient):
+    def number(self) -> int:
+        return 1
+
+
+class PublicClient(Client):
+    def __init__(self, inner: InnerDeps):
+        self.inner = inner
+
+    async def add(self, a: int, b: int) -> int:
+        return a + b
+
+
+async def any_func(a: int, adder: PublicClient, inner: InnerDeps) -> int:
+    assert adder.inner is not inner
+
+    return await adder.add(a, inner.number())
+
+
+async def test_inject() -> None:
+    dep = Dependencies()
+    new_func = dep.inject(any_func)
+
+    async with dep:
+        assert (await new_func(1)) == 2

nuke_di-1.0.0/tests/test_mock.py

@@ -0,0 +1,57 @@
+from collections.abc import AsyncGenerator
+from unittest.mock import call
+
+import pytest
+
+from nuke_di import DI, Client, Dependencies
+
+
+class InnerDeps(Client):
+    pass
+
+
+class PublicClient(Client):
+    def __init__(self, inner: InnerDeps):
+        self.inner = inner
+
+    async def add(self, a: int, b: int) -> int:
+        return a + b
+
+
+async def test_cached_client() -> None:
+    dep = Dependencies()
+
+    mocked_client = dep.mock(PublicClient)
+
+    client_1 = dep.resolve(PublicClient)
+
+    async with dep:
+        await client_1.add(1, 2)
+
+    assert mocked_client.add.await_args_list == [call(1, 2)]  # type: ignore
+
+
+@pytest.fixture()
+async def app_like_fixture() -> AsyncGenerator[Dependencies, None]:
+    DI.resolve(PublicClient)
+    async with DI:
+        yield DI
+
+
+@pytest.fixture
+async def mock_client() -> PublicClient:
+    """
+    Example of a fixture that mocks a dependency.
+
+    This fixture must come first in the test arguments or via @pytest.mark.usefixtures,
+    so that the mock is registered before the dependency tree is resolved.
+    """
+    return DI.mock(PublicClient)
+
+
+async def test_with_fixture(mock_client: PublicClient, app_like_fixture: Dependencies) -> None:
+    cli: PublicClient = app_like_fixture.clients[PublicClient]  # type: ignore
+
+    await cli.add(1, 2)
+
+    assert mock_client.add.await_args_list == [call(1, 2)]  # type: ignore

nuke_di-1.0.0/tests/test_resolve.py

@@ -0,0 +1,81 @@
+from unittest.mock import AsyncMock, call
+
+from nuke_di import Client, Dependencies, NotSingletonClient
+
+
+class InnerDeps(NotSingletonClient):
+    connect = AsyncMock()
+    disconnect = AsyncMock()
+
+
+class PublicClient(Client):
+    connect = AsyncMock()
+    disconnect = AsyncMock()
+
+    def __init__(self, inner: InnerDeps):
+        self.inner = inner
+
+
+class NewPublicClient(PublicClient):
+    connect = AsyncMock()
+    disconnect = AsyncMock()
+
+
+async def test_connecting() -> None:
+    dep = Dependencies()
+    cli = dep.resolve(PublicClient)
+    new_cli = dep.resolve(NewPublicClient)
+
+    assert isinstance(cli, PublicClient)
+    assert isinstance(new_cli, NewPublicClient)
+    # resolving, not connecting
+    assert cli.connect.await_args_list == []
+    assert cli.disconnect.await_args_list == []
+
+    assert new_cli.connect.await_args_list == []
+    assert new_cli.disconnect.await_args_list == []
+
+    assert cli.inner.connect.await_args_list == []
+    assert cli.inner.disconnect.await_args_list == []
+
+    async with dep:
+        # connecting
+        assert cli.connect.await_args_list == [call()]
+        assert cli.disconnect.await_args_list == []
+
+        assert new_cli.connect.await_args_list == [call()]
+        assert new_cli.disconnect.await_args_list == []
+
+        assert cli.inner.connect.await_args_list == [call(), call()]
+        assert cli.inner.disconnect.await_args_list == []
+
+        assert cli.inner is not new_cli.inner
+
+    # disconnecting
+    assert cli.connect.await_args_list == [call()]
+    assert cli.disconnect.await_args_list == [call()]
+
+    assert new_cli.connect.await_args_list == [call()]
+    assert new_cli.disconnect.await_args_list == [call()]
+
+    assert cli.inner.connect.await_args_list == [call(), call()]
+    assert cli.inner.disconnect.await_args_list == [call(), call()]
+
+
+class TypedSelfClient(Client):
+    connect = AsyncMock()
+    disconnect = AsyncMock()
+
+    def __init__(self: "TypedSelfClient") -> None:
+        pass
+
+
+async def test_typed_self() -> None:
+    dep = Dependencies()
+    cli = dep.resolve(TypedSelfClient)
+
+    async with dep:
+        pass
+
+    assert cli.connect.await_args_list == [call()]
+    assert cli.disconnect.await_args_list == [call()]