wireme 0.1.0__tar.gz

wireme-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohanad Ghali
+
+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.

wireme-0.1.0/PKG-INFO

@@ -0,0 +1,401 @@
+Metadata-Version: 2.4
+Name: wireme
+Version: 0.1.0
+Summary: Tiny, typed dependency injection built on FastDepends.
+Keywords: dependency-injection,di,fast-depends,typing
+Author: Mohanad Ghali
+Author-email: Mohanad Ghali <mghalix@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: fast-depends[pydantic]>=3.0.8,<4
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/mghalix/wireme
+Project-URL: Repository, https://github.com/mghalix/wireme
+Project-URL: Issues, https://github.com/mghalix/wireme/issues
+Project-URL: Changelog, https://github.com/mghalix/wireme/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# wireme
+
+Tiny, typed dependency injection for Python, powered by FastDepends.
+
+Wireme keeps dependency injection explicit and small:
+
+```python
+from wireme import Wired, override_dependency, wire, wired
+```
+
+- `@wire` enables dependency resolution for a function or method.
+- `wired(factory)` declares how a dependency is created.
+- `Wired()` marks a reusable `Annotated` dependency as caller-optional.
+- `override_dependency()` temporarily replaces a dependency in tests.
+
+## Installation
+
+```bash
+uv add wireme
+```
+
+Wireme requires Python 3.12 or newer.
+
+## Quick start
+
+```python
+from wireme import wire, wired
+
+
+class Database:
+    def write(self, value: str) -> None:
+        print(f"writing: {value}")
+
+
+def get_database() -> Database:
+    return Database()
+
+
+@wire
+def process_text(
+    text: str,
+    database: Database = wired(get_database),
+) -> None:
+    database.write(text)
+
+
+process_text("Hello, world")
+```
+
+Callers only provide application inputs. Wireme resolves `database` automatically.
+Injected parameters are also removed from the public runtime signature:
+
+```python
+import inspect
+
+assert str(inspect.signature(process_text)) == "(text: str) -> None"
+```
+
+## Reusable dependencies
+
+Use `Annotated` when the same dependency appears in multiple callables:
+
+```python
+from typing import Annotated
+
+from wireme import Wired, wire, wired
+
+
+type DatabaseDep = Annotated[Database, wired(get_database)]
+
+
+@wire
+def create_user(
+    username: str,
+    database: DatabaseDep = Wired(),
+) -> None:
+    database.write(username)
+
+
+create_user("mo")
+```
+
+`wired(get_database)` stores the dependency declaration in the annotation.
+`Wired()` tells type checkers and call sites that the argument does not need to be
+passed explicitly.
+
+## Wiring classes
+
+Decorate constructors or methods individually. Do not decorate the class itself.
+
+Use constructor injection when the dependency belongs to the object's state:
+
+```python
+from typing import Annotated
+
+from wireme import Wired, wire, wired
+
+
+type DatabaseDep = Annotated[Database, wired(get_database)]
+
+
+class TextProcessor:
+    @wire
+    def __init__(self, database: DatabaseDep = Wired()) -> None:
+        self._database = database
+
+    def process(self, text: str) -> None:
+        self._database.write(text)
+
+
+TextProcessor().process("Hello from constructor injection")
+```
+
+Use method injection when only a specific operation needs the dependency:
+
+```python
+class TextProcessor:
+    @wire
+    def process(
+        self,
+        text: str,
+        database: DatabaseDep = Wired(),
+    ) -> None:
+        database.write(text)
+
+
+TextProcessor().process("Hello from method injection")
+```
+
+Constructor injection is useful for dependencies shared across multiple methods.
+Method injection keeps the object stateless when only one operation needs the
+dependency.
+
+See [examples/classes.py](https://github.com/mghalix/wireme/blob/main/examples/classes.py) for a complete runnable example.
+
+## Explicit values take precedence
+
+A caller may still provide a dependency explicitly. The passed value wins over
+injection:
+
+```python
+class TestDatabase(Database):
+    pass
+
+
+create_user("mo", TestDatabase())
+```
+
+This is useful for one-off composition. For test suites, prefer
+`override_dependency()` so every nested dependency sees the replacement.
+
+## Test overrides
+
+```python
+from wireme import override_dependency
+
+
+def get_test_database() -> Database:
+    return TestDatabase()
+
+
+with override_dependency(get_database, get_test_database):
+    create_user("mo")
+```
+
+Overrides are restored when the context exits, including after exceptions.
+Nested overrides restore the previous outer override correctly.
+
+The provider is shared at process level. Use overrides for isolated tests and
+application setup, not concurrent request-level mutation.
+
+## Nested dependencies and caching
+
+Factories can depend on other factories:
+
+```python
+from wireme import wire, wired
+
+
+def get_settings() -> Settings:
+    return Settings()
+
+
+def get_database(
+    settings: Settings = wired(get_settings),
+) -> Database:
+    return Database(settings.database_url)
+
+
+@wire
+def operation(database: Database = wired(get_database)) -> None:
+    ...
+```
+
+Dependencies are cached once per wired call by default. Disable caching for a
+specific declaration when every use must create a new value:
+
+```python
+value: Token = wired(create_token, use_cache=False)
+```
+
+## Async and resource dependencies
+
+Async factories are supported:
+
+```python
+async def get_client() -> Client:
+    return await Client.connect()
+
+
+@wire
+async def fetch_user(
+    user_id: str,
+    client: Client = wired(get_client),
+) -> User:
+    return await client.fetch_user(user_id)
+```
+
+Generator and async-generator factories can own resource cleanup:
+
+```python
+from collections.abc import AsyncIterator
+
+
+async def get_client() -> AsyncIterator[Client]:
+    client = await Client.connect()
+    try:
+        yield client
+    finally:
+        await client.close()
+```
+
+Cleanup runs after the wired callable finishes.
+
+## Protocol dependencies
+
+A protocol can describe the dependency interface. When runtime validation is
+active, make the protocol runtime-checkable:
+
+```python
+from typing import Annotated, Protocol, runtime_checkable
+
+from wireme import Wired, wire, wired
+
+
+@runtime_checkable
+class DatabaseLike(Protocol):
+    def write(self, value: str) -> None: ...
+
+
+type DatabaseDep = Annotated[DatabaseLike, wired(get_database)]
+
+
+@wire
+def process(
+    value: str,
+    database: DatabaseDep = Wired(),
+) -> None:
+    database.write(value)
+```
+
+## Build integrations on top of Wireme
+
+Wireme can be the small DI primitive behind a project-specific API. For example,
+a service or plugin registry can expose `wired_service(ServiceType)` while still
+using Wireme for resolution, typing, caching, and overrides.
+
+```python
+import functools
+
+from collections.abc import Callable
+from typing import cast
+
+from wireme import WiremeError, wired
+
+
+class ServiceUnavailableError(WiremeError):
+    pass
+
+
+_services: dict[type[object], object] = {}
+
+
+@functools.cache
+def require_service[T](service_type: type[T]) -> Callable[[], T]:
+    def dependency() -> T:
+        try:
+            service = _services[service_type]
+        except KeyError as error:
+            raise ServiceUnavailableError(
+                f"{service_type.__name__} is not registered."
+            ) from error
+
+        return cast(T, service)
+
+    return dependency
+
+
+def wired_service[T](service_type: type[T]) -> T:
+    return wired(require_service(service_type))
+```
+
+Caching the generated factory gives it stable identity, which is important when
+using `override_dependency()`.
+
+See [`examples/custom_integration.py`](https://github.com/mghalix/wireme/blob/main/examples/custom_integration.py) for a
+complete runnable example.
+
+## Errors
+
+Wireme exposes:
+
+```python
+from wireme import ValidationError, WiremeError
+```
+
+- `WiremeError` is the base error exposed by Wireme.
+- `ValidationError` represents dependency input or result validation failures.
+
+Project-specific DI errors may inherit from `WiremeError`.
+
+## Ruff configuration
+
+Ruff's `B008` rule normally rejects function calls in defaults. Tell Ruff that
+`Wired()` is an immutable marker:
+
+```toml
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["wireme.Wired"]
+```
+
+Declarations using `wired(factory)` may also need your project's normal DI rule
+configuration, depending on which Ruff rules are enabled.
+
+## Public API
+
+| Name                  | Purpose                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `wire`                | Decorate a function or method and enable dependency resolution. |
+| `wired`               | Declare a dependency factory and its resolution options.        |
+| `Wired`               | Mark an `Annotated` dependency as caller-optional.              |
+| `override_dependency` | Temporarily replace a factory, with nested restoration.         |
+| `WiremeError`         | Base error exposed by Wireme.                                   |
+| `ValidationError`     | Dependency validation error.                                    |
+
+## Examples
+
+- [`examples/basic.py`](https://github.com/mghalix/wireme/blob/main/examples/basic.py) covers direct and reusable dependencies.
+- [`examples/classes.py`](https://github.com/mghalix/wireme/blob/main/examples/classes.py) covers constructor and method injection.
+- [`examples/overrides.py`](https://github.com/mghalix/wireme/blob/main/examples/overrides.py) covers isolated test overrides.
+- [`examples/protocols.py`](https://github.com/mghalix/wireme/blob/main/examples/protocols.py) covers interface-based dependencies.
+- [`examples/resources.py`](https://github.com/mghalix/wireme/blob/main/examples/resources.py) covers async resource cleanup.
+- [`examples/custom_integration.py`](https://github.com/mghalix/wireme/blob/main/examples/custom_integration.py) builds a typed service registry integration.
+
+Run any example with:
+
+```bash
+uv run python examples/basic.py
+```
+
+## Why Wireme instead of importing FastDepends directly?
+
+FastDepends provides the resolution engine. Wireme provides a deliberately small,
+opinionated facade with:
+
+- A cohesive `wire`, `wired`, and `Wired` vocabulary.
+- Strong return typing for sync, async, generator, and async-generator factories.
+- Reusable `Annotated` dependencies.
+- Injected parameters hidden from public runtime signatures.
+- Nested-safe dependency overrides.
+- A minimal backend-independent public namespace.
+
+## License
+
+MIT

wireme-0.1.0/README.md

@@ -0,0 +1,375 @@
+# wireme
+
+Tiny, typed dependency injection for Python, powered by FastDepends.
+
+Wireme keeps dependency injection explicit and small:
+
+```python
+from wireme import Wired, override_dependency, wire, wired
+```
+
+- `@wire` enables dependency resolution for a function or method.
+- `wired(factory)` declares how a dependency is created.
+- `Wired()` marks a reusable `Annotated` dependency as caller-optional.
+- `override_dependency()` temporarily replaces a dependency in tests.
+
+## Installation
+
+```bash
+uv add wireme
+```
+
+Wireme requires Python 3.12 or newer.
+
+## Quick start
+
+```python
+from wireme import wire, wired
+
+
+class Database:
+    def write(self, value: str) -> None:
+        print(f"writing: {value}")
+
+
+def get_database() -> Database:
+    return Database()
+
+
+@wire
+def process_text(
+    text: str,
+    database: Database = wired(get_database),
+) -> None:
+    database.write(text)
+
+
+process_text("Hello, world")
+```
+
+Callers only provide application inputs. Wireme resolves `database` automatically.
+Injected parameters are also removed from the public runtime signature:
+
+```python
+import inspect
+
+assert str(inspect.signature(process_text)) == "(text: str) -> None"
+```
+
+## Reusable dependencies
+
+Use `Annotated` when the same dependency appears in multiple callables:
+
+```python
+from typing import Annotated
+
+from wireme import Wired, wire, wired
+
+
+type DatabaseDep = Annotated[Database, wired(get_database)]
+
+
+@wire
+def create_user(
+    username: str,
+    database: DatabaseDep = Wired(),
+) -> None:
+    database.write(username)
+
+
+create_user("mo")
+```
+
+`wired(get_database)` stores the dependency declaration in the annotation.
+`Wired()` tells type checkers and call sites that the argument does not need to be
+passed explicitly.
+
+## Wiring classes
+
+Decorate constructors or methods individually. Do not decorate the class itself.
+
+Use constructor injection when the dependency belongs to the object's state:
+
+```python
+from typing import Annotated
+
+from wireme import Wired, wire, wired
+
+
+type DatabaseDep = Annotated[Database, wired(get_database)]
+
+
+class TextProcessor:
+    @wire
+    def __init__(self, database: DatabaseDep = Wired()) -> None:
+        self._database = database
+
+    def process(self, text: str) -> None:
+        self._database.write(text)
+
+
+TextProcessor().process("Hello from constructor injection")
+```
+
+Use method injection when only a specific operation needs the dependency:
+
+```python
+class TextProcessor:
+    @wire
+    def process(
+        self,
+        text: str,
+        database: DatabaseDep = Wired(),
+    ) -> None:
+        database.write(text)
+
+
+TextProcessor().process("Hello from method injection")
+```
+
+Constructor injection is useful for dependencies shared across multiple methods.
+Method injection keeps the object stateless when only one operation needs the
+dependency.
+
+See [examples/classes.py](https://github.com/mghalix/wireme/blob/main/examples/classes.py) for a complete runnable example.
+
+## Explicit values take precedence
+
+A caller may still provide a dependency explicitly. The passed value wins over
+injection:
+
+```python
+class TestDatabase(Database):
+    pass
+
+
+create_user("mo", TestDatabase())
+```
+
+This is useful for one-off composition. For test suites, prefer
+`override_dependency()` so every nested dependency sees the replacement.
+
+## Test overrides
+
+```python
+from wireme import override_dependency
+
+
+def get_test_database() -> Database:
+    return TestDatabase()
+
+
+with override_dependency(get_database, get_test_database):
+    create_user("mo")
+```
+
+Overrides are restored when the context exits, including after exceptions.
+Nested overrides restore the previous outer override correctly.
+
+The provider is shared at process level. Use overrides for isolated tests and
+application setup, not concurrent request-level mutation.
+
+## Nested dependencies and caching
+
+Factories can depend on other factories:
+
+```python
+from wireme import wire, wired
+
+
+def get_settings() -> Settings:
+    return Settings()
+
+
+def get_database(
+    settings: Settings = wired(get_settings),
+) -> Database:
+    return Database(settings.database_url)
+
+
+@wire
+def operation(database: Database = wired(get_database)) -> None:
+    ...
+```
+
+Dependencies are cached once per wired call by default. Disable caching for a
+specific declaration when every use must create a new value:
+
+```python
+value: Token = wired(create_token, use_cache=False)
+```
+
+## Async and resource dependencies
+
+Async factories are supported:
+
+```python
+async def get_client() -> Client:
+    return await Client.connect()
+
+
+@wire
+async def fetch_user(
+    user_id: str,
+    client: Client = wired(get_client),
+) -> User:
+    return await client.fetch_user(user_id)
+```
+
+Generator and async-generator factories can own resource cleanup:
+
+```python
+from collections.abc import AsyncIterator
+
+
+async def get_client() -> AsyncIterator[Client]:
+    client = await Client.connect()
+    try:
+        yield client
+    finally:
+        await client.close()
+```
+
+Cleanup runs after the wired callable finishes.
+
+## Protocol dependencies
+
+A protocol can describe the dependency interface. When runtime validation is
+active, make the protocol runtime-checkable:
+
+```python
+from typing import Annotated, Protocol, runtime_checkable
+
+from wireme import Wired, wire, wired
+
+
+@runtime_checkable
+class DatabaseLike(Protocol):
+    def write(self, value: str) -> None: ...
+
+
+type DatabaseDep = Annotated[DatabaseLike, wired(get_database)]
+
+
+@wire
+def process(
+    value: str,
+    database: DatabaseDep = Wired(),
+) -> None:
+    database.write(value)
+```
+
+## Build integrations on top of Wireme
+
+Wireme can be the small DI primitive behind a project-specific API. For example,
+a service or plugin registry can expose `wired_service(ServiceType)` while still
+using Wireme for resolution, typing, caching, and overrides.
+
+```python
+import functools
+
+from collections.abc import Callable
+from typing import cast
+
+from wireme import WiremeError, wired
+
+
+class ServiceUnavailableError(WiremeError):
+    pass
+
+
+_services: dict[type[object], object] = {}
+
+
+@functools.cache
+def require_service[T](service_type: type[T]) -> Callable[[], T]:
+    def dependency() -> T:
+        try:
+            service = _services[service_type]
+        except KeyError as error:
+            raise ServiceUnavailableError(
+                f"{service_type.__name__} is not registered."
+            ) from error
+
+        return cast(T, service)
+
+    return dependency
+
+
+def wired_service[T](service_type: type[T]) -> T:
+    return wired(require_service(service_type))
+```
+
+Caching the generated factory gives it stable identity, which is important when
+using `override_dependency()`.
+
+See [`examples/custom_integration.py`](https://github.com/mghalix/wireme/blob/main/examples/custom_integration.py) for a
+complete runnable example.
+
+## Errors
+
+Wireme exposes:
+
+```python
+from wireme import ValidationError, WiremeError
+```
+
+- `WiremeError` is the base error exposed by Wireme.
+- `ValidationError` represents dependency input or result validation failures.
+
+Project-specific DI errors may inherit from `WiremeError`.
+
+## Ruff configuration
+
+Ruff's `B008` rule normally rejects function calls in defaults. Tell Ruff that
+`Wired()` is an immutable marker:
+
+```toml
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["wireme.Wired"]
+```
+
+Declarations using `wired(factory)` may also need your project's normal DI rule
+configuration, depending on which Ruff rules are enabled.
+
+## Public API
+
+| Name                  | Purpose                                                         |
+| --------------------- | --------------------------------------------------------------- |
+| `wire`                | Decorate a function or method and enable dependency resolution. |
+| `wired`               | Declare a dependency factory and its resolution options.        |
+| `Wired`               | Mark an `Annotated` dependency as caller-optional.              |
+| `override_dependency` | Temporarily replace a factory, with nested restoration.         |
+| `WiremeError`         | Base error exposed by Wireme.                                   |
+| `ValidationError`     | Dependency validation error.                                    |
+
+## Examples
+
+- [`examples/basic.py`](https://github.com/mghalix/wireme/blob/main/examples/basic.py) covers direct and reusable dependencies.
+- [`examples/classes.py`](https://github.com/mghalix/wireme/blob/main/examples/classes.py) covers constructor and method injection.
+- [`examples/overrides.py`](https://github.com/mghalix/wireme/blob/main/examples/overrides.py) covers isolated test overrides.
+- [`examples/protocols.py`](https://github.com/mghalix/wireme/blob/main/examples/protocols.py) covers interface-based dependencies.
+- [`examples/resources.py`](https://github.com/mghalix/wireme/blob/main/examples/resources.py) covers async resource cleanup.
+- [`examples/custom_integration.py`](https://github.com/mghalix/wireme/blob/main/examples/custom_integration.py) builds a typed service registry integration.
+
+Run any example with:
+
+```bash
+uv run python examples/basic.py
+```
+
+## Why Wireme instead of importing FastDepends directly?
+
+FastDepends provides the resolution engine. Wireme provides a deliberately small,
+opinionated facade with:
+
+- A cohesive `wire`, `wired`, and `Wired` vocabulary.
+- Strong return typing for sync, async, generator, and async-generator factories.
+- Reusable `Annotated` dependencies.
+- Injected parameters hidden from public runtime signatures.
+- Nested-safe dependency overrides.
+- A minimal backend-independent public namespace.
+
+## License
+
+MIT

wireme-0.1.0/pyproject.toml

@@ -0,0 +1,70 @@
+[project]
+name = "wireme"
+version = "0.1.0"
+description = "Tiny, typed dependency injection built on FastDepends."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mohanad Ghali", email = "mghalix@gmail.com" }]
+keywords = ["dependency-injection", "di", "fast-depends", "typing"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = ["fast-depends[pydantic]>=3.0.8,<4"]
+
+[project.urls]
+Homepage = "https://github.com/mghalix/wireme"
+Repository = "https://github.com/mghalix/wireme"
+Issues = "https://github.com/mghalix/wireme/issues"
+Changelog = "https://github.com/mghalix/wireme/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["basedpyright", "pytest", "pytest-cov", "ruff", "trio"]
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 88
+
+[tool.ruff.lint]
+select = ["B", "E4", "E7", "E9", "F", "I", "N", "RUF", "S", "SIM", "UP"]
+ignore = ["N802", "S101"]
+
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["wireme.Wired", "wireme.wired"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["S101"]
+
+[tool.pytest.ini_options]
+addopts = "-ra --strict-config --strict-markers"
+testpaths = ["tests"]
+
+[tool.coverage.run]
+branch = true
+source = ["wireme"]
+
+[tool.coverage.report]
+fail_under = 100
+show_missing = true
+skip_covered = true
+
+[tool.basedpyright]
+include = ["src", "tests"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportAny = false
+reportExplicitAny = false
+reportPrivateUsage = false

wireme-0.1.0/src/wireme/__init__.py

@@ -0,0 +1,13 @@
+"""Tiny, typed dependency injection built on FastDepends."""
+
+from wireme._errors import ValidationError, WiremeError
+from wireme._impl import Wired, override_dependency, wire, wired
+
+__all__ = (
+    "ValidationError",
+    "Wired",
+    "WiremeError",
+    "override_dependency",
+    "wire",
+    "wired",
+)

wireme-0.1.0/src/wireme/_core.py

@@ -0,0 +1,11 @@
+from fast_depends import Depends as _Depends
+from fast_depends import Provider as _Provider
+from fast_depends import inject as _inject
+from fast_depends.dependencies import Dependant as _Dependant
+
+__all__ = (
+    "_Dependant",
+    "_Depends",
+    "_Provider",
+    "_inject",
+)

wireme-0.1.0/src/wireme/_errors.py

@@ -0,0 +1,4 @@
+from fast_depends.exceptions import FastDependsError as WiremeError
+from fast_depends.exceptions import ValidationError
+
+__all__ = ("ValidationError", "WiremeError")

wireme-0.1.0/src/wireme/_impl.py

@@ -0,0 +1,258 @@
+"""Internal implementation for :mod:`wireme`."""
+
+from __future__ import annotations
+
+import contextlib
+import inspect
+import typing
+from collections.abc import (
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Generator,
+    Iterator,
+)
+
+from ._core import _Dependant, _Depends, _inject, _Provider
+
+
+class _HasSignature(typing.Protocol):
+    """Represent a callable with a customizable runtime signature."""
+
+    __signature__: inspect.Signature
+
+
+_MISSING = object()
+_provider = _Provider()
+
+
+type _DependencyFactory[R] = (
+    Callable[..., Awaitable[R]]
+    | Callable[..., AsyncIterator[R]]
+    | Callable[..., Iterator[R]]
+    | Callable[..., R]
+)
+
+
+def Wired() -> typing.Any:
+    """Mark an annotated dependency as optional for static type checkers."""
+    return ...
+
+
+def _resolve_annotation(
+    annotation: object,
+    /,
+    *,
+    globalns: dict[str, object],
+    localns: dict[str, object],
+) -> object:
+    """Resolve strings and PEP 695 aliases recursively.
+
+    Unresolved forward references become Any in FastDepends' internal
+    signature while remaining unchanged in Wireme's public signature.
+    """
+    while True:
+        if isinstance(annotation, str):
+            try:
+                annotation = eval(annotation, globalns, localns)  # noqa: S307
+            except (AttributeError, NameError, TypeError):
+                return typing.Any
+
+            continue
+
+        if isinstance(annotation, typing.TypeAliasType):
+            annotation = annotation.__value__
+            continue
+
+        return annotation
+
+
+def _is_dependency_parameter(
+    parameter: inspect.Parameter,
+    /,
+    *,
+    globalns: dict[str, object],
+    localns: dict[str, object],
+) -> bool:
+    """Return whether a parameter is supplied through dependency injection."""
+    if isinstance(parameter.default, _Dependant):
+        return True
+
+    annotation = _resolve_annotation(
+        parameter.annotation,
+        globalns=globalns,
+        localns=localns,
+    )
+    if typing.get_origin(annotation) is not typing.Annotated:
+        return False
+
+    return any(
+        isinstance(metadata, _Dependant) for metadata in typing.get_args(annotation)[1:]
+    )
+
+
+def wire[**P, T](func: Callable[P, T], /) -> Callable[P, T]:
+    """Enable dependency injection and hide injected runtime parameters.
+
+    Apply this decorator to functions and methods, not classes.
+    """
+    original_signature = inspect.signature(func)
+
+    frame = inspect.currentframe()
+    try:
+        caller_locals = (
+            dict(frame.f_back.f_locals)
+            if frame is not None and frame.f_back is not None
+            else {}
+        )
+    finally:
+        del frame
+
+    globalns = dict(getattr(func, "__globals__", {}))
+    type_parameters = {
+        parameter.__name__: parameter
+        for parameter in getattr(func, "__type_params__", ())
+    }
+    caller_locals.update(type_parameters)
+
+    resolved_parameters = tuple(
+        parameter.replace(
+            annotation=_resolve_annotation(
+                parameter.annotation,
+                globalns=globalns,
+                localns=caller_locals,
+            )
+        )
+        for parameter in original_signature.parameters.values()
+    )
+
+    resolved_signature = original_signature.replace(
+        parameters=resolved_parameters,
+        return_annotation=_resolve_annotation(
+            original_signature.return_annotation,
+            globalns=globalns,
+            localns=caller_locals,
+        ),
+    )
+
+    previous_signature = getattr(func, "__signature__", _MISSING)
+    typing.cast("_HasSignature", func).__signature__ = resolved_signature
+
+    try:
+        wrapped = _inject(func, dependency_provider=_provider)
+    finally:
+        if previous_signature is _MISSING:
+            delattr(func, "__signature__")
+        else:
+            typing.cast("_HasSignature", func).__signature__ = typing.cast(
+                "inspect.Signature",
+                previous_signature,
+            )
+
+    public_parameters = tuple(
+        original_parameter
+        for original_parameter, resolved_parameter in zip(
+            original_signature.parameters.values(),
+            resolved_signature.parameters.values(),
+            strict=True,
+        )
+        if not _is_dependency_parameter(
+            resolved_parameter,
+            globalns=globalns,
+            localns=caller_locals,
+        )
+    )
+
+    typing.cast("_HasSignature", wrapped).__signature__ = original_signature.replace(
+        parameters=public_parameters
+    )
+
+    return wrapped
+
+
+@typing.overload
+def wired[**P, R](
+    factory: Callable[P, Awaitable[R]],
+    /,
+    *,
+    use_cache: bool = True,
+    cast: bool = True,
+    cast_result: bool = False,
+) -> R: ...
+
+
+@typing.overload
+def wired[**P, R](
+    factory: Callable[P, AsyncIterator[R]],
+    /,
+    *,
+    use_cache: bool = True,
+    cast: bool = True,
+    cast_result: bool = False,
+) -> R: ...
+
+
+@typing.overload
+def wired[**P, R](
+    factory: Callable[P, Iterator[R]],
+    /,
+    *,
+    use_cache: bool = True,
+    cast: bool = True,
+    cast_result: bool = False,
+) -> R: ...
+
+
+@typing.overload
+def wired[**P, R](
+    factory: Callable[P, R],
+    /,
+    *,
+    use_cache: bool = True,
+    cast: bool = True,
+    cast_result: bool = False,
+) -> R: ...
+
+
+def wired(
+    factory: Callable[..., object],
+    /,
+    *,
+    use_cache: bool = True,
+    cast: bool = True,
+    cast_result: bool = False,
+) -> typing.Any:
+    """Declare a dependency resolved by a callable."""
+    return _Depends(
+        factory,
+        use_cache=use_cache,
+        cast=cast,
+        cast_result=cast_result,
+    )
+
+
+@contextlib.contextmanager
+def override_dependency[R](
+    original: _DependencyFactory[R],
+    replacement: _DependencyFactory[R],
+    /,
+) -> Generator[None, None, None]:
+    """Temporarily replace a dependency factory.
+
+    Nested overrides are restored correctly. Overrides modify a shared provider,
+    so use them for isolated tests and application setup, not concurrent
+    request-level mutation.
+    """
+    previous_override = _provider.overrides.get(original, _MISSING)
+    _provider.override(original, replacement)
+
+    try:
+        yield
+    finally:
+        if previous_override is _MISSING:
+            _provider.overrides.pop(original, None)
+        else:
+            _provider.overrides[original] = typing.cast(
+                "typing.Any",
+                previous_override,
+            )