Metadata-Version: 2.5
Name: quadkit-contracts
Version: 0.0.3
Summary: Core types and protocols for the Quadkit Framework
Project-URL: Homepage, https://quadkit.dev
Project-URL: Repository, https://github.com/dbtinoy-/quadkit
Project-URL: Documentation, https://quadkit.dev
Project-URL: Issues, https://github.com/dbtinoy-/quadkit/issues
Project-URL: Changelog, https://github.com/dbtinoy-/quadkit/blob/main/CHANGELOG.md
Author-email: Quadkit Framework Team <team@quadkit.dev>
Maintainer-email: Quadkit Framework Team <team@quadkit.dev>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: async,contracts,framework,protocols,python,quadkit
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: ruff>=0.16.4; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=4.0.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Description-Content-Type: text/markdown

# quadkit-contracts

Protocols, shared types, and the exception hierarchy for Quadkit —
with **zero runtime dependencies** beyond `typing-extensions`. Every
published package depends on contracts; no implementation package
defines a protocol another package depends on.

For integration authors who need to bind against Quadkit interfaces
without pulling in the framework — thin adapters import only this
package.

## Installation

```bash
uv add quadkit-contracts
```

Requires **Python >= 3.11**.

## Minimal working example

Protocols are structural: implement the shape, and the container binds
your implementation to the contract.

```python
from typing import Protocol

from quadkit.result import Err, Ok, Result


class UserNotFound(Exception):
    """A domain failure the caller is expected to handle."""


class UserRepository(Protocol):
    async def find_name(self, user_id: str) -> Result[str, UserNotFound]: ...


async def find_name_or_unknown(
    repo: UserRepository, user_id: str
) -> str:
    result = await repo.find_name(user_id)
    return result.match(ok=lambda name: name, err=lambda e: "unknown")
```

The domain-model side — pydantic-based entities and events:

```python
from quadkit.contracts.domain.events import DomainEvent
from quadkit.domain import AggregateRoot


class UserCreated(DomainEvent):
    user_id: str
    email: str


class User(AggregateRoot):
    email: str
```

## Optional extras

| Extra | Contents |
| --- | --- |
| `quadkit-contracts[dev]` / `[test]` | development / test tooling |

## Public API entry points

| Module | Contents |
| --- | --- |
| `quadkit.result` | `Result[T, E]`, `Ok`, `Err`, `as_result()`, `as_result_sync()`, `try_catch()`, `ResultPipeline` |
| `quadkit.contracts.core.di` | `ContainerRegistrarProtocol`, `ContainerResolverProtocol` |
| `quadkit.contracts.core.provider` | `ProviderProtocol`, `ProviderPriority` |
| `quadkit.contracts.core.registry` | `RegistryProtocol`, `StrategyRegistryProtocol`, `BackendRegistryProtocol` |
| `quadkit.contracts.domain.base` | `DomainModelProtocol`, `ID` |
| `quadkit.contracts.domain.events` | `DomainEvent` |
| `quadkit.contracts.exceptions` | `QuadkitError` and the full hierarchy |
| `quadkit.contracts.infra.cache` | `CacheBackendProtocol` |
| `quadkit.contracts.data` | `DatabaseProviderProtocol` |
| `quadkit.contracts.security.secrets` | `SecretStoreProtocol` |

Deep-dive: [contracts](../../docs/concepts/contracts.md) in the docs
set.

## Configuration

None — this package carries types, not behavior.

## Error handling

The taxonomy lives here: `QuadkitError` is the root; `DomainError`
subclasses describe expected business failures (`NotFoundError`,
`ValidationError`, `ConflictError`, `PermissionDeniedError`, ...). The
web layer maps them to HTTP problem responses — see
[error handling](../../docs/guides/error-handling.md).

## Testing

Protocols are tested by conformance: implement the shape, run your
implementation through the behavior callers rely on. `quadkit-testing`
ships the fakes used by the framework's own tests.

## Security

This package ships interfaces and types only — no network, no I/O, no
runtime dependencies. Report vulnerabilities privately per
[SECURITY.md](../../SECURITY.md).

## Stability

Version `0.0.3` in the `0.x` series, released in lockstep with the
other four distributions. **These protocols carry no compatibility
guarantee yet**: minor releases may add, rename, or remove members
while the framework is pre-1.0. Because this package is published
whole, protocols for not-yet-released areas are the most likely to
change; the settled ones are those exercised by `quadkit`,
`quadkit-web`, `quadkit-testing`, and `quadkit-cli`. Pin an exact
version (`quadkit-contracts==0.0.3`) when you depend on these types
directly. Full policy:
[stability and compatibility](../../docs/reference/stability.md).

Issues: <https://github.com/dbtinoy-/quadkit/issues>
