wireup 0.16.0__tar.gz → 1.0.1__tar.gz

wireup-1.0.1/PKG-INFO

@@ -0,0 +1,272 @@
+Metadata-Version: 2.1
+Name: wireup
+Version: 1.0.1
+Summary: Python Dependency Injection Library
+Home-page: https://github.com/maldoinc/wireup
+License: MIT
+Keywords: flask,django,injector,dependency injection,dependency injection container,dependency injector
+Author: Aldo Mateli
+Author-email: aldo.mateli@gmail.com
+Requires-Python: >=3.8,<4.0
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Flask
+Classifier: Framework :: aiohttp
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: typing_extensions (>=4.7,<5.0)
+Project-URL: Changelog, https://github.com/maldoinc/wireup/releases
+Project-URL: Documentation, https://maldoinc.github.io/wireup/
+Project-URL: Repository, https://github.com/maldoinc/wireup
+Description-Content-Type: text/markdown
+
+<div align="center">
+<h1>Wireup</h1>
+<p>Performant, concise and type-safe Dependency Injection for Python 3.8+</p>
+
+[![GitHub](https://img.shields.io/github/license/maldoinc/wireup)](https://github.com/maldoinc/wireup)
+[![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/maldoinc/wireup/run_all.yml)](https://github.com/maldoinc/wireup)
+[![Coverage](https://img.shields.io/codeclimate/coverage/maldoinc/wireup?label=Coverage)](https://codeclimate.com/github/maldoinc/wireup)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/wireup)](https://pypi.org/project/wireup/)
+[![PyPI - Version](https://img.shields.io/pypi/v/wireup)](https://pypi.org/project/wireup/)
+
+<p><a target="_blank" href="https://maldoinc.github.io/wireup">📚 Documentation</a> | <a target="_blank" href="https://github.com/maldoinc/wireup-demo">🎮 Demo Application</a></p>
+</div>
+
+
+> [!NOTE]  
+> Wireup 1.0 has been released, featuring support for scoped lifetimes, a simplified API, enhanced type safety, and improved documentation.
+> Refer to the [Upgrading Guide](https://maldoinc.github.io/wireup/latest/upgrading/) for instructions on upgrading from version 0.x to 1.0.
+---
+
+Dependency Injection (DI) is a design pattern where dependencies are provided externally rather than created within objects. Wireup automates dependency management using Python's type system, with support for async, generators and modern Python features.
+
+## Features
+
+### ✨ Simple & Type-Safe DI
+
+Inject services and configuration using a clean and intuitive syntax.
+
+```python
+@service
+class Database:
+    pass
+
+@service
+class UserService:
+    def __init__(self, db: Database) -> None:
+        self.db = db
+
+container = wireup.create_sync_container(services=[Database, UserService])
+user_service = container.get(UserService) # ✅ Dependencies resolved.
+```
+
+<details>
+<summary>Example With Configuration</summary>
+
+```python
+@service
+class Database:
+    def __init__(self, db_url: Annotated[str, Inject(param="db_url")]) -> None:
+        self.db_url = db_url
+
+container = wireup.create_sync_container(
+    services=[Database], 
+    parameters={"db_url": os.environ["APP_DB_URL"]}
+)
+database = container.get(Database) # ✅ Dependencies resolved.
+```
+
+</details>
+
+### 🎯 Function Injection
+
+Inject dependencies directly into functions with a simple decorator.
+
+```python
+@inject_from_container(container)
+def process_users(service: Injected[UserService]):
+    # ✅ UserService injected.
+    pass
+```
+
+### 📝 Interfaces & Abstract Classes
+
+Define abstract types and have the container automatically inject the implementation.
+
+```python
+@abstract
+class Notifier(abc.ABC):
+    pass
+
+@service
+class SlackNotifier(Notifier):
+    pass
+
+notifier = container.get(Notifier)
+# ✅ SlackNotifier instance.
+```
+
+
+### 🔄 Managed Service Lifetimes
+
+Declare dependencies as singletons, scoped, or transient to control whether to inject a fresh copy or reuse existing instances.
+
+
+```python
+# Singleton: One instance per application. `@service(lifetime="singleton")` is the default.
+@service
+class Database:
+    pass
+
+# Scoped: One instance per scope/request, shared within that scope/request.
+@service(lifetime="scoped")
+class RequestContext:
+    def __init__(self) -> None:
+        self.request_id = uuid4()
+
+# Transient: When full isolation and clean state is required.
+# Every request to create transient services results in a new instance.
+@service(lifetime="transient")
+class OrderProcessor:
+    pass
+```
+
+
+### 🏭 Flexible Creation Patterns
+
+Defer instantiation to specialized factories when complex initialization or cleanup is required.
+Full support for async and generators. Wireup handles cleanup at the correct time depending on the service lifetime.
+
+**Synchronous**
+
+```python
+class WeatherClient:
+    def __init__(self, client: requests.Session) -> None:
+        self.client = client
+
+@service
+def weather_client_factory() -> Iterator[WeatherClient]:
+    with requests.Session() as session:
+        yield WeatherClient(client=session)
+```
+
+**Async**
+
+```python
+class WeatherClient:
+    def __init__(self, client: aiohttp.ClientSession) -> None:
+        self.client = client
+
+@service
+async def weather_client_factory() -> AsyncIterator[WeatherClient]:
+    async with aiohttp.ClientSession() as session:
+        yield WeatherClient(client=session)
+```
+
+
+### 🛡️ Improved Safety
+
+Wireup is mypy strict compliant and will not introduce type errors in your code. It will also warn you at the earliest possible stage about configuration errors to avoid surprises.
+
+**Container Creation**
+
+The container will raise errors at creation time about missing dependencies or other issues.
+
+```python
+@service
+class Foo:
+    def __init__(self, unknown: NotManagedByWireup) -> None:
+        pass
+
+container = wireup.create_sync_container(services=[Foo])
+# ❌ Parameter 'unknown' of 'Foo' depends on an unknown service 'NotManagedByWireup'.
+```
+
+**Function Injection**
+
+Injected functions will raise errors at module import time rather than when called.
+
+```python
+@inject_from_container(container)
+def my_function(oops: Injected[NotManagedByWireup]):
+    pass
+
+# ❌ Parameter 'oops' of 'my_function' depends on an unknown service 'NotManagedByWireup'.
+```
+
+**Integrations**
+
+Wireup integrations assert that requested injections in the framework are valid.
+
+```python
+@app.get("/")
+def home(foo: Injected[NotManagedByWireup]):
+    pass
+
+wireup.integration.flask.setup(container, app)
+# ❌ Parameter 'foo' of 'home' depends on an unknown service 'NotManagedByWireup'.
+```
+
+### 📍 Framework-Agnostic
+
+Wireup provides its own Dependency Injection mechanism and is not tied to specific frameworks. Use it anywhere you like.
+
+### 🔗 Share Services Between Application and CLI
+
+Share the service layer between your web application and its accompanying CLI using Wireup.
+
+### 🔌 Native Integration with Django, FastAPI, or Flask
+
+Integrate with popular frameworks for a smoother developer experience.
+Integrations manage request scopes, injection in endpoints, and lifecycle of services.
+
+```python
+app = FastAPI()
+container = wireup.create_async_container(services=[UserService, Database])
+
+@app.get("/")
+def users_list(user_service: Injected[UserService]):
+    pass
+
+wireup.integration.fastapi.setup(container, app)
+```
+
+### 🧪 Simplified Testing
+
+Wireup does not patch your services and lets you test them in isolation.
+
+If you need to use the container in your tests, you can have it create parts of your services
+or perform dependency substitution.
+
+```python
+with container.override.service(target=Database, new=in_memory_database):
+    # The /users endpoint depends on Database.
+    # During the lifetime of this context manager, requests to inject `Database`
+    # will result in `in_memory_database` being injected instead.
+    response = client.get("/users")
+```
+
+## 📚 Documentation
+
+For more information [check out the documentation](https://maldoinc.github.io/wireup)
+
+## 🎮 Demo application
+
+A demo flask application is available at [maldoinc/wireup-demo](https://github.com/maldoinc/wireup-demo)
+

{wireup-0.16.0 → wireup-1.0.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "wireup"
-version = "0.16.0"
+version = "1.0.1"
 description = "Python Dependency Injection Library"
 authors = ["Aldo Mateli <aldo.mateli@gmail.com>"]
 license = "MIT"
@@ -45,10 +45,10 @@ Changelog = "https://github.com/maldoinc/wireup/releases"
 
 [tool.poetry.dependencies]
 python = "^3.8"
-graphlib2 = { version = "^0.4.7", python = ">=3.8,<3.9" }
+typing_extensions = "^4.7"
 
 [tool.poetry.group.dev.dependencies]
-ruff = "0.8.6"
+ruff = "0.11.0"
 setuptools = "^68.0.0"
 mkdocs = "^1.5.2"
 mkdocs-material = "^9.4.14"
@@ -74,14 +74,12 @@ lint.ignore = [
     "PT009",  # Prefer using assertEqual instead of plain asserts
     "TD003",  # Exclude "missing issue link for todos",
     "FIX002", # Disable "Line contains to do, consider resolving the issue". It will be done, in due time.
-    "D100",   # Disable undocumented public module. The definitions themselves will be documented
-    "D101",
-    "D102",
-    "D104",   # Same as above, disable missing docstring in public package,
+    "D",
     "D203",   # Ignore "one blank line before class". Using "no blank lines before class rule".
     "D213",   # Disable "Summary must go into next line"
     "D107",   # Disable required docs for __init. Can be redundant if class also has them.
     "A003",   # Disable "shadows builtin". OverrideManager.set was flagged by this
+    "SLF001", # Allow usage of _fields.
     "FA100",  # Don't recommend __future__ annotations.
     # Disable as they may cause conflicts with ruff formatter
     "COM812",
@@ -103,6 +101,7 @@ lint.ignore = [
     "SIM117",
     "S101",
     "PLR2004",
+    "PLR0913",
 ]
 
 

wireup-1.0.1/readme.md

@@ -0,0 +1,234 @@
+<div align="center">
+<h1>Wireup</h1>
+<p>Performant, concise and type-safe Dependency Injection for Python 3.8+</p>
+
+[![GitHub](https://img.shields.io/github/license/maldoinc/wireup)](https://github.com/maldoinc/wireup)
+[![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/maldoinc/wireup/run_all.yml)](https://github.com/maldoinc/wireup)
+[![Coverage](https://img.shields.io/codeclimate/coverage/maldoinc/wireup?label=Coverage)](https://codeclimate.com/github/maldoinc/wireup)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/wireup)](https://pypi.org/project/wireup/)
+[![PyPI - Version](https://img.shields.io/pypi/v/wireup)](https://pypi.org/project/wireup/)
+
+<p><a target="_blank" href="https://maldoinc.github.io/wireup">📚 Documentation</a> | <a target="_blank" href="https://github.com/maldoinc/wireup-demo">🎮 Demo Application</a></p>
+</div>
+
+
+> [!NOTE]  
+> Wireup 1.0 has been released, featuring support for scoped lifetimes, a simplified API, enhanced type safety, and improved documentation.
+> Refer to the [Upgrading Guide](https://maldoinc.github.io/wireup/latest/upgrading/) for instructions on upgrading from version 0.x to 1.0.
+---
+
+Dependency Injection (DI) is a design pattern where dependencies are provided externally rather than created within objects. Wireup automates dependency management using Python's type system, with support for async, generators and modern Python features.
+
+## Features
+
+### ✨ Simple & Type-Safe DI
+
+Inject services and configuration using a clean and intuitive syntax.
+
+```python
+@service
+class Database:
+    pass
+
+@service
+class UserService:
+    def __init__(self, db: Database) -> None:
+        self.db = db
+
+container = wireup.create_sync_container(services=[Database, UserService])
+user_service = container.get(UserService) # ✅ Dependencies resolved.
+```
+
+<details>
+<summary>Example With Configuration</summary>
+
+```python
+@service
+class Database:
+    def __init__(self, db_url: Annotated[str, Inject(param="db_url")]) -> None:
+        self.db_url = db_url
+
+container = wireup.create_sync_container(
+    services=[Database], 
+    parameters={"db_url": os.environ["APP_DB_URL"]}
+)
+database = container.get(Database) # ✅ Dependencies resolved.
+```
+
+</details>
+
+### 🎯 Function Injection
+
+Inject dependencies directly into functions with a simple decorator.
+
+```python
+@inject_from_container(container)
+def process_users(service: Injected[UserService]):
+    # ✅ UserService injected.
+    pass
+```
+
+### 📝 Interfaces & Abstract Classes
+
+Define abstract types and have the container automatically inject the implementation.
+
+```python
+@abstract
+class Notifier(abc.ABC):
+    pass
+
+@service
+class SlackNotifier(Notifier):
+    pass
+
+notifier = container.get(Notifier)
+# ✅ SlackNotifier instance.
+```
+
+
+### 🔄 Managed Service Lifetimes
+
+Declare dependencies as singletons, scoped, or transient to control whether to inject a fresh copy or reuse existing instances.
+
+
+```python
+# Singleton: One instance per application. `@service(lifetime="singleton")` is the default.
+@service
+class Database:
+    pass
+
+# Scoped: One instance per scope/request, shared within that scope/request.
+@service(lifetime="scoped")
+class RequestContext:
+    def __init__(self) -> None:
+        self.request_id = uuid4()
+
+# Transient: When full isolation and clean state is required.
+# Every request to create transient services results in a new instance.
+@service(lifetime="transient")
+class OrderProcessor:
+    pass
+```
+
+
+### 🏭 Flexible Creation Patterns
+
+Defer instantiation to specialized factories when complex initialization or cleanup is required.
+Full support for async and generators. Wireup handles cleanup at the correct time depending on the service lifetime.
+
+**Synchronous**
+
+```python
+class WeatherClient:
+    def __init__(self, client: requests.Session) -> None:
+        self.client = client
+
+@service
+def weather_client_factory() -> Iterator[WeatherClient]:
+    with requests.Session() as session:
+        yield WeatherClient(client=session)
+```
+
+**Async**
+
+```python
+class WeatherClient:
+    def __init__(self, client: aiohttp.ClientSession) -> None:
+        self.client = client
+
+@service
+async def weather_client_factory() -> AsyncIterator[WeatherClient]:
+    async with aiohttp.ClientSession() as session:
+        yield WeatherClient(client=session)
+```
+
+
+### 🛡️ Improved Safety
+
+Wireup is mypy strict compliant and will not introduce type errors in your code. It will also warn you at the earliest possible stage about configuration errors to avoid surprises.
+
+**Container Creation**
+
+The container will raise errors at creation time about missing dependencies or other issues.
+
+```python
+@service
+class Foo:
+    def __init__(self, unknown: NotManagedByWireup) -> None:
+        pass
+
+container = wireup.create_sync_container(services=[Foo])
+# ❌ Parameter 'unknown' of 'Foo' depends on an unknown service 'NotManagedByWireup'.
+```
+
+**Function Injection**
+
+Injected functions will raise errors at module import time rather than when called.
+
+```python
+@inject_from_container(container)
+def my_function(oops: Injected[NotManagedByWireup]):
+    pass
+
+# ❌ Parameter 'oops' of 'my_function' depends on an unknown service 'NotManagedByWireup'.
+```
+
+**Integrations**
+
+Wireup integrations assert that requested injections in the framework are valid.
+
+```python
+@app.get("/")
+def home(foo: Injected[NotManagedByWireup]):
+    pass
+
+wireup.integration.flask.setup(container, app)
+# ❌ Parameter 'foo' of 'home' depends on an unknown service 'NotManagedByWireup'.
+```
+
+### 📍 Framework-Agnostic
+
+Wireup provides its own Dependency Injection mechanism and is not tied to specific frameworks. Use it anywhere you like.
+
+### 🔗 Share Services Between Application and CLI
+
+Share the service layer between your web application and its accompanying CLI using Wireup.
+
+### 🔌 Native Integration with Django, FastAPI, or Flask
+
+Integrate with popular frameworks for a smoother developer experience.
+Integrations manage request scopes, injection in endpoints, and lifecycle of services.
+
+```python
+app = FastAPI()
+container = wireup.create_async_container(services=[UserService, Database])
+
+@app.get("/")
+def users_list(user_service: Injected[UserService]):
+    pass
+
+wireup.integration.fastapi.setup(container, app)
+```
+
+### 🧪 Simplified Testing
+
+Wireup does not patch your services and lets you test them in isolation.
+
+If you need to use the container in your tests, you can have it create parts of your services
+or perform dependency substitution.
+
+```python
+with container.override.service(target=Database, new=in_memory_database):
+    # The /users endpoint depends on Database.
+    # During the lifetime of this context manager, requests to inject `Database`
+    # will result in `in_memory_database` being injected instead.
+    response = client.get("/users")
+```
+
+## 📚 Documentation
+
+For more information [check out the documentation](https://maldoinc.github.io/wireup)
+
+## 🎮 Demo application
+
+A demo flask application is available at [maldoinc/wireup-demo](https://github.com/maldoinc/wireup-demo)

wireup-1.0.1/wireup/__init__.py

@@ -0,0 +1,25 @@
+from wireup._annotations import Inject, Injected, abstract, service
+from wireup._decorators import inject_from_container
+from wireup.ioc.container import (
+    create_async_container,
+    create_sync_container,
+)
+from wireup.ioc.container.async_container import AsyncContainer
+from wireup.ioc.container.sync_container import SyncContainer
+from wireup.ioc.parameter import ParameterBag
+from wireup.ioc.types import ParameterReference, ServiceOverride
+
+__all__ = [
+    "AsyncContainer",
+    "Inject",
+    "Injected",
+    "ParameterBag",
+    "ParameterReference",
+    "ServiceOverride",
+    "SyncContainer",
+    "abstract",
+    "create_async_container",
+    "create_sync_container",
+    "inject_from_container",
+    "service",
+]