Metadata-Version: 2.4
Name: alchemiq
Version: 0.1.0
Summary: The data layer for async FastAPI microservices: Django-style models, transactional outbox, caching, and ClickHouse - built on SQLAlchemy 2.0
Project-URL: Homepage, https://github.com/TrifoN-off/alchemiq
Project-URL: Documentation, https://alchemiq.readthedocs.io
Project-URL: Repository, https://github.com/TrifoN-off/alchemiq
Project-URL: Issues, https://github.com/TrifoN-off/alchemiq/issues
Project-URL: Changelog, https://github.com/TrifoN-off/alchemiq/blob/main/CHANGELOG.md
Author-email: Trifonov Nikita <trifonov.nikit@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: async,clickhouse,django-orm,fastapi,orm,postgresql,sqlalchemy
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Database
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0
Requires-Dist: sqlalchemy[asyncio]>=2.0
Provides-Extra: all
Requires-Dist: alembic>=1.13; extra == 'all'
Requires-Dist: argon2-cffi>=23.0; extra == 'all'
Requires-Dist: asyncpg>=0.29; extra == 'all'
Requires-Dist: clickhouse-connect[async]>=0.8; extra == 'all'
Requires-Dist: clickhouse-sqlalchemy>=0.3; extra == 'all'
Requires-Dist: cryptography>=42.0; extra == 'all'
Requires-Dist: email-validator>=2.0; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: faststream>=0.5; extra == 'all'
Requires-Dist: phonenumbers>=8.13; extra == 'all'
Requires-Dist: redis>=5.0; extra == 'all'
Requires-Dist: taskiq-aio-pika>=0.4; extra == 'all'
Requires-Dist: taskiq>=0.11; extra == 'all'
Provides-Extra: argon2
Requires-Dist: argon2-cffi>=23.0; extra == 'argon2'
Provides-Extra: bcrypt
Requires-Dist: bcrypt>=4.0; extra == 'bcrypt'
Provides-Extra: clickhouse
Requires-Dist: clickhouse-connect[async]>=0.8; extra == 'clickhouse'
Requires-Dist: clickhouse-sqlalchemy>=0.3; extra == 'clickhouse'
Provides-Extra: crypto
Requires-Dist: cryptography>=42.0; extra == 'crypto'
Provides-Extra: email
Requires-Dist: email-validator>=2.0; extra == 'email'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.110; extra == 'fastapi'
Provides-Extra: faststream
Requires-Dist: faststream>=0.5; extra == 'faststream'
Provides-Extra: migrations
Requires-Dist: alembic>=1.13; extra == 'migrations'
Provides-Extra: outbox
Requires-Dist: taskiq-aio-pika>=0.4; extra == 'outbox'
Requires-Dist: taskiq>=0.11; extra == 'outbox'
Provides-Extra: phone
Requires-Dist: phonenumbers>=8.13; extra == 'phone'
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29; extra == 'postgres'
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == 'redis'
Description-Content-Type: text/markdown

# alchemiq

The data layer for async FastAPI microservices: Django-style models, transactional
outbox, caching, and ClickHouse - built on SQLAlchemy 2.0.

[![PyPI version](https://img.shields.io/pypi/v/alchemiq)](https://pypi.org/project/alchemiq/)
[![Python](https://img.shields.io/pypi/pyversions/alchemiq)](https://pypi.org/project/alchemiq/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Docs](https://readthedocs.org/projects/alchemiq/badge/?version=latest)](https://alchemiq.readthedocs.io)
[![CI](https://github.com/TrifoN-off/alchemiq/actions/workflows/ci.yml/badge.svg)](https://github.com/TrifoN-off/alchemiq/actions)

---

## 30-second example

```python
import alchemiq
from alchemiq import Model, Repository
from alchemiq.types import PK, Email

class User(Model):
    id: PK[int]
    name: str
    email: Email

alchemiq.configure("postgresql+asyncpg://user:password@localhost/mydb")
await alchemiq.create_all()

users = Repository(User)
user  = await users.create(name="Ada Lovelace", email="ada@example.com")
found = await users.get(id=user.id)
print(found.name)  # Ada Lovelace
```

---

## Features

- **Async PostgreSQL and ClickHouse** - a single query DSL covers both backends.
- **Django-flavoured models** - declare fields with plain type annotations; `Q` objects, `QuerySet`
  chaining, `order_by`, `limit`, and `offset` work exactly as you would expect.
- **Repository + UnitOfWork** - full CRUD, bulk operations, cursor/keyset pagination, and
  aggregations (`Count`, `Sum`, `Avg`, `Min`, `Max`) out of the box.
- **Soft-delete and optimistic locking** - opt in per model via a `Meta` class.
- **Signals** - async pre/post hooks for create, update, and delete lifecycle events.
- **Serialization** - `to_dict`, `to_schema`, `to_pydantic` with field inclusion/exclusion.
- **Outbox + Relay** - atomic event capture in the same transaction, published to any broker
  (RabbitMQ, Kafka, NATS) via TaskIQ or FastStream.
- **FastAPI integration** - auto-generated CRUD router, DI-ready repository and UoW providers,
  Pydantic schema generation, and a `/health/ready` · `/health/live` router.
- **FastStream consumer DI** - inject sessions, UoW, and repositories into message handlers.
- **Redis caching** - per-repository cache with automatic invalidation on write.
- **Migrations** - Alembic wrapper for PostgreSQL; a custom engine for ClickHouse.
- **Scaffolding** - `alchemiq init` generates a production-ready layered project skeleton.

---

## Installation

```bash
pip install "alchemiq[all]"
```

| Extra | Installs |
|---|---|
| `email` | `email-validator` |
| `phone` | `phonenumbers` |
| `argon2` | `argon2-cffi` |
| `bcrypt` | `bcrypt` (not in `all`) |
| `crypto` | `cryptography` |
| `outbox` | `taskiq`, `taskiq-aio-pika` |
| `fastapi` | `fastapi` |
| `faststream` | `faststream` |
| `redis` | `redis` |
| `postgres` | `asyncpg` (the PostgreSQL driver) |
| `clickhouse` | `clickhouse-connect[async]`, `clickhouse-sqlalchemy` |
| `migrations` | `alembic` |
| `all` | all of the above except `bcrypt` |

---

## Documentation

Full guide and API reference: **<https://alchemiq.readthedocs.io>**

---

## Links

- Source: <https://github.com/TrifoN-off/alchemiq>
- Changelog: [CHANGELOG.md](CHANGELOG.md)
- License: MIT - see [LICENSE](LICENSE)

---

## What's not in v1

`alchemiq` v1 does not include a visual admin, MySQL/SQLite support, synchronous mode,
multi-database routing, audit logs, geolocation fields, or file-field storage adapters.

See the [What's not in v1](https://alchemiq.readthedocs.io/guide/whats-not-in-v1.html) guide
for the full list and the reasoning behind each deferral.
