Development

Contributing guide for apywire developers.

Getting Started

Prerequisites

Python 3.12 or later
Git
Make (optional but recommended)

Initial Setup

Clone the repository and set up your development environment:

git clone https://github.com/alganet/apywire.git
cd apywire

# Install dev dependencies
uv sync --extra dev

This will:

Create (or update) a .venv project environment
Install all development dependencies including mkdocs, pytest, mypy, etc.

Development Workflow

Running Tests

# Run all tests with pytest
make test

# Run tests with coverage
make coverage

# Run verbose tests
pytest -xvs

The project enforces 95% test coverage or higher. New code should include comprehensive tests.

Testing Conventions

Compiled Code Testing: When testing compiled code, use the pre-instantiated compiled object from the execution namespace instead of manually instantiating the class.
```
exec(code, execd)
wired = execd["compiled"]  # Use this instance
```
Type Safety in Tests: Avoid Any and type: ignore. Use typing.Protocol to define the expected interface of dynamic or compiled objects.
```
class MockConfig(Protocol):
    def config(self) -> Config: ...

execd: dict[str, MockConfig] = {}
```
Coverage: The CI gate enforces a 95% branch-coverage floor (fail_under in pyproject.toml); aim for 100% on new code.
Naming: Use descriptive test names: test_<feature>_<scenario>_<expected_behavior>().

Module Mocking: When testing custom classes, inject them into sys.modules using a try...finally block to ensure cleanup.

class MockModule(ModuleType): ...
sys.modules["mymod"] = MockModule()
try:
    # test code
finally:
    del sys.modules["mymod"]

Code Formatting

The project uses black and isort for code formatting:

# Format all code
make format

This command:

Runs reuse annotate to add SPDX headers
Formats code with black (79-character line length)
Sorts imports with isort

Linting

# Run all linters
make lint

This runs:

reuse lint - Validates SPDX licensing headers
flake8 - Python style checker
mypy - Static type checker

All linting must pass before submitting a pull request.

Building

# Build Cython extension
make build

# Build distribution packages
make dist

The build process compiles apywire/wiring.py to C using Cython for performance.

Complete Check

Run all checks before committing:

make all

This runs: format → lint → coverage → build

Project Structure

apywire/
├── apywire/              # Main package
│   ├── __init__.py       # Public API exports
│   ├── wiring.py         # Base wiring functionality
│   ├── runtime.py        # Runtime wiring implementation
│   ├── compiler.py       # Code generation
│   ├── threads.py        # Thread safety utilities
│   ├── exceptions.py     # Exception classes
│   ├── constants.py      # Constants and configuration
│   └── py.typed          # PEP 561 marker file
├── tests/                # Test suite
│   ├── test_single.py    # Runtime tests
│   ├── test_compile_aio.py  # Async compilation tests
│   ├── test_threading.py    # Thread safety tests
│   ├── test_factory_methods.py  # Factory method tests
│   ├── test_edge_cases.py   # Edge case tests
│   ├── test_stdlib_compat.py  # Stdlib compatibility tests
│   └── test_internals.py    # Internal implementation tests
├── docs/                 # MkDocs documentation
├── pyproject.toml        # Project configuration
├── setup.py              # Build configuration (Cython)
├── Makefile              # Development commands
└── README.md             # Project readme

Code Standards

Type Annotations

apywire uses strict mypy with very aggressive settings:

[tool.mypy]
strict = true
disallow_any_unimported = true
disallow_any_decorated = true
disallow_any_explicit = true
disallow_subclassing_any = true
disallow_any_expr = true
warn_return_any = true

Guidelines:

No Any: Use object instead
Full type annotations on all functions and methods
Type all variables where type can't be inferred
Use type aliases for complex types

Example:

from typing import TypeAlias

# Good
def process(data: dict[str, str]) -> list[str]:
    return list(data.values())

# Bad - missing return type
def process(data: dict[str, str]):
    return list(data.values())

Code Style

Line length: 79 characters (enforced by black)
Imports: Sorted with isort, profile black
Docstrings: Google style
Naming:
- Classes: PascalCase
- Functions/methods: snake_case
- Constants: UPPER_CASE
- Private: _leading_underscore

SPDX Licensing

All source files must have SPDX headers:

# SPDX-FileCopyrightText: 2025 Alexandre Gomes Gaigalas <alganet@gmail.com>
#
# SPDX-License-Identifier: ISC

Run make format to automatically add headers to new files.

Architecture

Core Concepts

Lazy Loading

Objects are instantiated via __getattr__ only when accessed:

def __getattr__(self, name: str):
    if name in self._values:
        return Accessor(lambda: self._values[name])
    # Instantiate and cache...

Placeholder Resolution

Strings like {name} are converted to _WiredRef markers during parsing, and {aio.name} to _AioWiredRef markers:

class _WiredRef:
    __slots__ = ("name",)

class _AioWiredRef:
    __slots__ = ("name",)

def _resolve(self, obj):
    if isinstance(obj, str) and self._is_placeholder(obj):
        ref_name = self._extract_placeholder_name(obj)
        if ref_name.startswith("aio."):
            return _AioWiredRef(ref_name[4:])
        return _WiredRef(ref_name)
    return obj

At instantiation time, _WiredRef markers are resolved to actual objects, and _AioWiredRef markers are resolved to async accessor callables.

Thread Safety

Thread-safe mode uses:

Per-attribute locks: dict[str, threading.Lock]
Global fallback lock: Single threading.Lock
Thread-local state: For lock-related per-thread state used by the thread-safety mixin (mode, held locks)

See apywire/threads.py for details.

Compilation

The compiler generates Python code that:

Imports all required modules
Creates a Compiled class
Generates accessor methods for each wired object
Optionally includes async accessors and thread safety

See apywire/compiler.py for the implementation.

Module Responsibilities

wiring.py: Base class, type system, placeholder parsing
runtime.py: Runtime Wiring implementation, Accessor/AioAccessor
compiler.py: Code generation via WiringCompiler
threads.py: Thread safety mixins and utilities
exceptions.py: Custom exception classes
constants.py: Shared constants (delimiter, placeholder markers)

Testing

Test Organization

test_single.py: Runtime wiring tests (non-thread-safe)
test_threading.py: Thread-safe wiring tests
test_compile_aio.py: Async compilation tests
test_factory_methods.py: Factory method tests
test_edge_cases.py: Edge cases and error handling
test_stdlib_compat.py: Standard library integration
test_internals.py: Internal implementation details

Writing Tests

Test naming convention:

def test_<feature>_<scenario>_<expected_behavior>():
    """Brief description of what is being tested."""
    # Arrange
    spec = {...}

    # Act
    wired = Wiring(spec)
    result = wired.something()

    # Assert
    assert result == expected

Always test:

Runtime behavior
Compiled behavior (when applicable)
Async variants (when applicable)
Thread-safe variants (when applicable)
Error cases

Coverage

Target: 95% branch coverage or higher

Check coverage:

make coverage

View HTML coverage report:

open htmlcov/index.html

Documentation

Building Docs

# Serve docs locally
make docs-serve

# Build static site
make docs-build

Writing Documentation

Use GitHub Flavored Markdown
Include code examples that actually work
Add SPDX headers to all .md files
Use admonitions for important notes:

!!! note
    This is a note

!!! warning
    This is a warning

Pull Request Process

Create a branch from main:
```
git checkout -b feature/my-feature
```
Make changes and ensure tests pass:
```
make all
```

Commit changes with descriptive messages:

git commit -m "Add feature X to handle Y"

Push to GitHub:
```
git push origin feature/my-feature
```
Create pull request on GitHub
Address review feedback if any

Release Process

(For maintainers)

Update version in pyproject.toml
Update CHANGELOG (if present)
Run full test suite: make all
Build distribution: make dist
Tag release: git tag v0.x.x
Push tag: git push origin v0.x.x
Publish to PyPI: make publish

Getting Help

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Full Documentation

License

apywire is licensed under the ISC License. See LICENSE for details.

Next Steps

API Reference - Detailed API documentation
User Guide - Learn how to use apywire
Examples - Practical examples

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Development

Getting Started

Prerequisites

Initial Setup

Development Workflow

Running Tests

Testing Conventions

Code Formatting

Linting

Building

Complete Check

Project Structure

Code Standards

Type Annotations

Code Style

SPDX Licensing

Architecture

Core Concepts

Lazy Loading

Placeholder Resolution

Thread Safety

Compilation

Module Responsibilities

Testing

Test Organization

Writing Tests

Coverage

Documentation

Building Docs

Writing Documentation

Pull Request Process

Release Process

Getting Help

License

Next Steps

FilesExpand file tree

development.md

Latest commit

History

development.md

File metadata and controls

Development

Getting Started

Prerequisites

Initial Setup

Development Workflow

Running Tests

Testing Conventions

Code Formatting

Linting

Building

Complete Check

Project Structure

Code Standards

Type Annotations

Code Style

SPDX Licensing

Architecture

Core Concepts

Lazy Loading

Placeholder Resolution

Thread Safety

Compilation

Module Responsibilities

Testing

Test Organization

Writing Tests

Coverage

Documentation

Building Docs

Writing Documentation

Pull Request Process

Release Process

Getting Help

License

Next Steps