Metadata-Version: 2.4
Name: ferrum-orm
Version: 0.1.2
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Rust
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Dist: pydantic>=2.0
Requires-Dist: ferrum-orm[pg] ; extra == 'all'
Requires-Dist: ferrum-orm[mysql] ; extra == 'all'
Requires-Dist: ferrum-orm[sqlite] ; extra == 'all'
Requires-Dist: ferrum-orm[cli] ; extra == 'all'
Requires-Dist: ferrum-orm[dotenv] ; extra == 'all'
Requires-Dist: typer>=0.12 ; extra == 'cli'
Requires-Dist: rich>=13 ; extra == 'cli'
Requires-Dist: ferrum-orm[pg,cli,dotenv] ; extra == 'dev'
Requires-Dist: maturin>=1.7,<2 ; extra == 'dev'
Requires-Dist: pytest>=8 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
Requires-Dist: hypothesis>=6.100 ; extra == 'dev'
Requires-Dist: pytest-benchmark>=4 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: ty>=0.0.49 ; extra == 'dev'
Requires-Dist: import-linter>=2 ; extra == 'dev'
Requires-Dist: testcontainers[postgres]>=4 ; extra == 'dev'
Requires-Dist: pip-audit>=2 ; extra == 'dev'
Requires-Dist: python-dotenv>=1.0 ; extra == 'dotenv'
Requires-Dist: asyncmy>=0.2 ; extra == 'mysql'
Requires-Dist: asyncpg>=0.29 ; extra == 'pg'
Requires-Dist: aiosqlite>=0.19 ; extra == 'sqlite'
Requires-Dist: uuid6>=2024.1 ; extra == 'uuid7'
Provides-Extra: all
Provides-Extra: cli
Provides-Extra: dev
Provides-Extra: dotenv
Provides-Extra: fastapi
Provides-Extra: mysql
Provides-Extra: pg
Provides-Extra: sqlite
Provides-Extra: uuid7
License-File: LICENSE
Summary: Next-generation async ORM for Python with a Rust-powered core
Keywords: orm,async,postgresql,mysql,sqlite,pydantic,rust
License: Apache-2.0
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Bug Tracker, https://github.com/ferrumdb/ferrum/issues
Project-URL: Documentation, https://ferrumdb.github.io/ferrum
Project-URL: Homepage, https://github.com/ferrumdb/ferrum
Project-URL: Repository, https://github.com/ferrumdb/ferrum

# Ferrum

> A next-generation async ORM for Python.
> Rust-powered engine. Pydantic-native models. Django-inspired developer experience.

Ferrum is an async-first ORM designed for modern Python applications.

Built around a Rust-powered core and a Python-native API, Ferrum combines the ergonomics of Django's ORM, the type safety of Pydantic, and the performance of Rust.

## Why Ferrum?

Existing Python ORMs often force developers to choose between:

- Developer experience
- Async support
- Type safety
- Performance

Ferrum aims to provide all four.

### Goals

- Native async from day one
- Pydantic-first models
- Django-inspired ORM experience
- Rust-powered query engine
- PostgreSQL-first architecture (MySQL and SQLite via optional extras)
- Type-safe query construction
- Automatic migrations
- High-performance result hydration
- Production-ready observability

---

## Quick Example

```python
from ferrum import Model


class User(Model):
    id: int
    email: str
    is_active: bool = True


user = await User.objects.create(
    conn,
    email="john@example.com",
)

users = await (
    User.objects
    .filter(is_active=True)
    .order_by("-id")
    .limit(10)
    .all(conn)
)

async with conn.transaction() as tx:
    user = await User.objects.create(tx, email="jane@example.com")
    await AuditLog.objects.create(tx, user_id=user.id, action="signup")
```

---

## Features

### Async First

No synchronous compatibility layer.

Ferrum is designed around modern async Python applications.

```python
users = await User.objects.all(conn)
```

### Pydantic Native

Models are built directly on top of Pydantic.

```python
class User(Model):
    id: int
    email: str
```

No duplicate schema definitions.

### Django-Inspired API

Familiar query interface.

```python
users = await (
    User.objects
    .filter(email__contains="@gmail.com")
    .order_by("-created_at")
    .all(conn)
)
```

### Rust-Powered Core

Performance-critical components are implemented in Rust:

- Query compilation
- SQL generation
- Result decoding
- Schema analysis
- Migration planning

This allows Ferrum to maintain a Pythonic API without sacrificing performance.

## Architecture

```text
┌──────────────────────────┐
│      Python API          │
│  Models / QuerySets      │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│      Ferrum Core         │
│      (Rust Engine)       │
├──────────────────────────┤
│ Query Compiler           │
│ SQL AST                  │
│ Result Decoder           │
│ Migration Planner        │
└────────────┬─────────────┘
             │
             ▼
┌──────────────────────────┐
│       PostgreSQL         │
└──────────────────────────┘
```

## Roadmap

### v0.1

- [ ] PostgreSQL support
- [ ] Basic CRUD operations
- [ ] Async query execution
- [ ] Pydantic models
- [ ] Query builder
- [ ] Type-safe filters

### v0.2

- [ ] Relationships
- [x] Transactions
- [ ] Query optimization
- [ ] Bulk operations

### v0.3

- [ ] Migrations
- [ ] Schema diff engine
- [ ] CLI tools

### v1.0

- [ ] Production-ready stability
- [ ] Advanced relationships
- [ ] Performance benchmarking
- [ ] Full documentation

## Project Status

Ferrum is currently in active development.

The API is not yet stable and breaking changes should be expected until the first public release.

## Installation

```bash
# PostgreSQL (most common)
pip install 'ferrum-orm[pg]'

# PostgreSQL + migrations CLI
pip install 'ferrum-orm[pg,cli]'

# MySQL
pip install 'ferrum-orm[mysql]'

# SQLite + migrations CLI (testing / local dev)
pip install 'ferrum-orm[sqlite,cli]'

# Everything (all drivers + CLI + dotenv)
pip install 'ferrum-orm[all]'

# Core ORM only (no database driver — install a driver extra before connecting)
pip install ferrum-orm
```

Bare `ferrum-orm` installs Pydantic and the Rust core only. Choose a driver extra
(`pg`, `mysql`, or `sqlite`) before calling `ferrum.connect()`.

From source, build the native extension with `maturin develop` (or `mise run dev`).

## Examples

Runnable samples live under [`examples/`](examples/):

- [`examples/simple/`](examples/simple/) — async CRUD script (no web framework)
- [`examples/migrations/`](examples/migrations/) — CLI, plan generation, apply, and forward fix-ups
- [`examples/fastapi_quickstart/`](examples/fastapi_quickstart/) — FastAPI integration

## Contributing

Contributions are welcome.

## License

Apache License 2.0

