Metadata-Version: 2.4
Name: python-repositories
Version: 0.3.1
Summary: Various python repository interfaces exposed as a python package.
Author-email: Brian Bjarke Jensen <schnitzelen@gmail.com>
License: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Requires-Dist: python-utils>=0.1.0
Requires-Dist: structlog>=25.4.0
Provides-Extra: minio
Requires-Dist: minio>=7.2.16; extra == 'minio'
Provides-Extra: redis
Requires-Dist: redis>=6.4.0; extra == 'redis'
Description-Content-Type: text/markdown

# python-repositories

Unified repository interfaces and technology-specific adapters for Python projects.

Subclass an adapter in your own repository to add domain-specific methods while reusing connection management and CRUD operations.

## Architecture

| Layer            | Responsibility                                                    |
| ---------------- | ----------------------------------------------------------------- |
| **Interfaces**   | Abstract contracts for connection, context, and CRUD              |
| **Adapters**     | Technology-specific base classes (`RedisAdapter`, `MinioAdapter`) |
| **Your project** | Subclass an adapter and add domain methods                        |

## Optional dependencies

Install with the extras you need:

```bash
uv add python-repositories[redis]
uv add python-repositories[minio]
uv add python-repositories[redis,minio]
```

### Redis (`JsonRepositoryInterface`)

Requires Redis with the RedisJSON module (e.g. redis-stack).

| Environment variable | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `REDIS_URI`          | Redis connection URL (e.g. `redis://localhost:6379`) |

### MinIO (`ObjectRepositoryInterface`)

| Environment variable | Description                                 |
| -------------------- | ------------------------------------------- |
| `MINIO_ENDPOINT`     | MinIO server endpoint                       |
| `MINIO_ACCESS_KEY`   | Access key                                  |
| `MINIO_SECRET_KEY`   | Secret key                                  |
| `MINIO_BUCKET`       | Bucket name (created on connect if missing) |

## Quick start

### JSON documents with Redis

```python
from python_repositories.examples.user_json_repository import UserJsonRepository

with UserJsonRepository() as repo:
    repo.save_user("alice", {"name": "Alice", "email": "alice@example.com"})
    user = repo.get_user("alice")
    repo.delete_user("alice")
```

### Binary objects with MinIO

```python
from io import BytesIO

from python_repositories.examples.artifact_object_repository import (
    ArtifactObjectRepository,
)

with ArtifactObjectRepository() as repo:
    repo.store_artifact("report-1", BytesIO(b"pdf bytes here"))
    data = repo.get_artifact("report-1")
```

### Subclassing in your own project

```python
from python_repositories import RedisAdapter

class UserRepository(RedisAdapter):
    def _key(self, user_id: str) -> str:
        return f"user:{user_id}"

    def get_user(self, user_id: str) -> dict | None:
        return self.get(self._key(user_id))

    def save_user(self, user_id: str, user: dict) -> None:
        self.set(self._key(user_id), user)
```

## Public API

```python
from python_repositories import (
    ConnectionAwareInterface,
    ContextAwareInterface,
    JsonRepositoryInterface,
    ObjectRepositoryInterface,
    RedisAdapter,
    MinioAdapter,
)
```

## Development

```bash
uv sync --all-extras
uv run pre-commit install   # once per clone — runs hooks on git commit
uv run pytest tests/integration/ -v
```

`pre-commit` is included in the dev dependency group. `uv sync` installs the CLI, but git does not run hooks until you install them with `pre-commit install` (one time per clone). After that, commits run the checks defined in [`.pre-commit-config.yaml`](.pre-commit-config.yaml) (ruff, mypy, pyupgrade, prettier, and general file hygiene).

To run all hooks manually without committing:

```bash
uv run pre-commit run --all-files
```

Integration tests require Docker (testcontainers).
