wireup 2.3.0__tar.gz → 2.5.0__tar.gz

wireup-2.5.0/.agent/rules.md

@@ -0,0 +1,3 @@
+# Agent Rules
+
+1. **Stdout/Stderr Redirection**: The `run_command` tool has a bug where it cannot reliably capture stdout/stderr directly. YOU MUST ALWAYS redirect output to a file (e.g., `cmd > output.txt 2>&1`) and then read that file using `view_file` or `read_resource` to inspect the output. Never rely on the `output` field of `run_command` or `command_status`.

wireup-2.5.0/.agent/workflows/context.md

@@ -0,0 +1,158 @@
+# Wireup - Dependency Injection Framework for Python
+
+Wireup is a type-safe dependency injection framework for Python 3.8+ with async support and framework integrations.
+
+## Core Architecture
+
+Wireup follows a container-based DI pattern with three main components:
+
+- **Container**: Central registry that resolves dependencies (`create_sync_container`/`create_async_container`)
+- **Injectables**: Classes/functions marked with `@injectable` decorator 
+- **Configuration**: Configuration values injected via `config`
+
+Key modules:
+- `wireup/ioc/` - Core container and service registry implementation
+- `wireup/integration/` - Framework integrations (FastAPI, Django, Flask, etc.)
+- `wireup/_annotations.py` - Core decorators (`@injectable`, `@abstract`, `Inject`, `Injected`)
+
+## Development Workflows
+
+### Testing
+- Use `make test` for unit tests (runs `pytest test/unit`)
+- Tests use parameterized containers (both sync/async) via `conftest.py`
+- Test services are in `test/unit/services/` with clear module structure
+- Override services in tests using `container.override.service(target=Original, new=mock)`
+- Integration tests are in `test/integration/` for framework-specific testing
+
+### Linting & Type Checking
+- `make lint` - Runs formatting, ruff, and mypy checks
+- `make format` - Auto-format code with ruff
+- Strict mypy compliance required (`mypy wireup --strict`)
+- Ruff configured for Python 3.8+ with comprehensive rule set
+- Note: `tool.mypy` excludes `wireup.integration` directory
+
+### Building & Documentation
+- Poetry-based project (`poetry install`, `poetry build`)
+- Documentation via MkDocs Material (`make docs-deploy version=X.Y.Z`)
+- Use `z_test_*.py` files for experimentation and examples
+- Profile performance with `make profile ./profile_tests <num_runs>`
+
+## Key Patterns
+
+### Injectable Registration
+```python
+@injectable  # Singleton by default
+class Database: ...
+
+@injectable(lifetime="scoped")  # Per-request/scope
+class RequestContext: ...
+
+@injectable(lifetime="transient")  # Always new instance
+class OrderProcessor: ...
+```
+
+### Interface-Implementation Binding
+```python
+@abstract
+class Cache: ...
+
+@injectable(qualifier="redis")
+class RedisCache(Cache): ...
+
+# Inject specific implementation
+def handler(cache: Annotated[Cache, Inject(qualifier="redis")]): ...
+```
+
+### Factory Functions with Cleanup
+```python
+@injectable
+def database_factory() -> Iterator[Database]:
+    db = Database()
+    try:
+        yield db
+    finally:
+        db.close()
+```
+
+### Function Injection
+```python
+@inject_from_container(container)
+def process_data(service: Injected[UserService]):
+    # UserService automatically injected
+    pass
+```
+
+### Configuration Injection
+```python
+@injectable
+class Database:
+    def __init__(self, db_url: Annotated[str, Inject(config="db_url")]) -> None:
+        self.db_url = db_url
+
+# Templated string configuration
+@injectable  
+class Logger:
+    def __init__(self, prefix: Annotated[str, Inject(expr="app-${env_name}")]) -> None:
+        self.prefix = prefix
+```
+
+## Framework Integration Notes
+
+- Integrations are in `wireup/integration/` with separate files per framework
+- Setup pattern: `wireup.integration.{framework}.setup(container, app)`
+- FastAPI integration auto-wraps `Inject()` with `Depends()` for compatibility
+- All integrations validate dependencies at startup, not runtime
+
+## Error Handling & Validation
+
+Wireup validates dependencies early to catch configuration errors:
+
+```python
+# Container creation fails with clear error messages
+@injectable
+class Foo:
+    def __init__(self, unknown: NotManagedByWireup) -> None:
+        pass
+
+container = wireup.create_sync_container(service_modules=[Foo])
+# ❌ Parameter 'unknown' of 'Foo' depends on an unknown injectable 'NotManagedByWireup'
+```
+
+Common error types:
+- `UnknownServiceRequestedError` - Missing injectable registration
+- `DuplicateServiceRegistrationError` - Same injectable registered twice
+- `DuplicateQualifierForInterfaceError` - Qualifier conflicts
+
+## Testing Conventions
+
+- Use `Container = Union[SyncContainer, AsyncContainer]` type hint for parameterized tests
+- Service modules for tests use clear hierarchical imports
+- Test both sync and async containers with same test logic via fixtures
+- Mock external dependencies using container overrides, not monkey patching
+
+## Container Usage Patterns
+
+### Service Discovery
+```python
+# Auto-discover injectables from modules
+container = wireup.create_sync_container(service_modules=[services])
+
+# Explicit injectable registration
+container = wireup.create_sync_container(service_modules=[Database, UserService])
+```
+
+### Scoped Containers
+Use scoped containers for request-scoped injectables:
+```python
+with container.request_scope() as scoped:
+    # All scoped services share same instance within this block
+    service = scoped.get(RequestScopedService)
+```
+
+## File Organization
+
+- `z_test_*.py` - Experimental/example files (not actual tests)
+- `test/unit/` - Unit tests with services in subfolders
+- `test/integration/` - Integration tests
+- `wireup/ioc/` - Core DI implementation
+- `docs/pages/` - MkDocs documentation source

wireup-2.5.0/.github/contributing.md

@@ -0,0 +1,44 @@
+# Contributing
+
+## Setup
+
+```bash
+git clone https://github.com/maldoinc/wireup.git
+cd wireup
+
+python -m venv .venv
+source .venv/bin/activate
+make install
+```
+
+## Development Workflow
+
+```bash
+make lint     # Run ruff & mypy checks
+make test     # Run unit tests
+make format   # Format code
+```
+
+### Making Changes
+
+```bash
+git checkout -b feature/your-feature-name
+# work on the change
+make lint test
+```
+
+
+## Project Structure
+
+- `wireup/ioc/` - Dependency injection implementation
+- `wireup/integration/` - Framework integrations (FastAPI, Django, etc.)
+- `test/unit/` - Unit tests
+- `test/integration/` - Integration tests
+- `docs/` - Docs
+
+## Guidelines
+
+- **Python Support**: Target Python 3.8+ compatibility
+- **Dependencies**: No new dependencies without approval
+- **Documentation**: Update docs for user-facing changes
+- **Testing**: Maintain test coverage for new code

wireup-2.5.0/.github/workflows/run_all.yml

@@ -0,0 +1,61 @@
+name: Run tests
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.8"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: make install
+      - name: Lint
+        run: make check-ruff
+      - name: Check formatting
+        run: make check-fmt
+      - name: Check typing
+        run: make check-mypy
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.14"
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: make install
+      - name: Check documentation
+        run: make check-docs
+      - name: Build documentation
+        run: make build-docs
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v3
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: make install
+      - name: Run tests
+        run: make test

wireup-2.5.0/.github/workflows/run_integration_tests.yml

@@ -0,0 +1,23 @@
+name: Integration tests
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+    branches: ["master"]
+jobs:
+  test:
+    name: Run Tox
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v3
+    - name: Set up Python
+      uses: actions/setup-python@v4
+      with:
+        python-version: "3.13"
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+    - name: Install dependencies
+      run: make install
+    - name: Run tox
+      run: uv run tox

wireup-2.5.0/.gitignore

@@ -0,0 +1,10 @@
+.venv
+.ruff_cache
+.idea
+.tox
+dist
+docs/site
+__pycache__
+.mypy_cache
+.coverage
+coverage.xml

wireup-2.5.0/.vscode/launch.json

@@ -0,0 +1,26 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python Debugger: Module",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "wireup_benchmarks.app"
+        },
+        {
+            "name": "Python Debugger: Django",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/test/integration/djangoproj/manage.py",
+            "args": [
+                "runserver",
+                "8080"
+            ],
+            "django": true,
+            "justMyCode": false
+        }
+    ]
+}

wireup-2.5.0/.vscode/settings.json

@@ -0,0 +1,18 @@
+{
+    "python.testing.pytestArgs": [
+        "-s",
+        "test",
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "python.analysis.autoImportCompletions": true,
+    "debugpy.debugJustMyCode": false,
+    "python-envs.defaultEnvManager": "ms-python.python:venv",
+    "python-envs.pythonProjects": [],
+    "cursorpyright.analysis.autoImportCompletions": true,
+    "cSpell.words": [
+        "asyncio",
+        "Codegen",
+        "pyrefly"
+    ],
+}

wireup-2.5.0/Makefile

@@ -0,0 +1,51 @@
+.PHONY: install lint check-fmt check-ruff check-mypy test profile fix format docs-deploy publish
+
+ifdef GITHUB_ACTIONS
+RUFF_ARGS := --output-format github
+endif
+
+install:
+	pip install uv
+	uv sync --group dev
+
+lint: check-fmt check-ruff check-mypy check-docs
+
+check-fmt:
+	uv run ruff format . --check
+
+check-ruff:
+	uv run ruff check wireup test $(RUFF_ARGS)
+
+check-mypy:
+	uv run mypy wireup --strict
+
+check-docs:
+	find docs -name "*.md" -not -path "docs/pages/class/*" | xargs uv run --python 3.14 mdformat --wrap 120 --check
+
+test:
+	uv run pytest test/unit
+
+profile ./profile_tests $(num_runs):
+	uv run python ./profile_tests.py $(num_runs)
+
+format: format-docs
+	uv run ruff format .
+
+fix:
+	uv run ruff wireup --fix
+
+format-docs:
+	find docs -name "*.md" -not -path "docs/pages/class/*" | xargs uv run --python 3.14 mdformat --wrap 120
+	find docs -name "*.md" -not -path "docs/pages/class/*" | xargs uv run --python 3.14 blacken-docs -l 80 || true
+
+build-docs:
+	uv run --python 3.14 mkdocs build --strict -f docs/mkdocs.yml
+
+
+# make docs-deploy version=...
+docs-deploy $(version):
+	cd docs && uv run mike deploy --push --update-aliases $(version) latest
+
+publish:
+	uv build
+	uv publish