ferrum-rs 0.1.0

Ferrum: A Rust-first web framework with Django-like Python API

Ferrum

Ferrum is a Django-inspired framework with a Rust runtime core and a Python developer API.

What Ferrum currently provides

• Rust-owned HTTP runtime (axum + tokio) bridged to Python via pyo3.
• Django-style management commands (manage.py, startproject, startapp, makemigrations, migrate, showmigrations).
• App registry and settings boot flow via FERRUM_SETTINGS_MODULE, including apps.py discovery and ready() hooks.
• Middleware pipeline from MIDDLEWARE (process_request, process_response, process_exception).
• ORM foundations:
  • Models and fields (CharField, IntegerField, FloatField, BooleanField, ForeignKey, ManyToManyField)
  • QuerySet operations (get, filter, exclude, all, first, last, latest, earliest, exists, count, aggregate, values, values_list, distinct, slicing, create, update, delete, etc.)
  • Expanded lookups (__icontains, __istartswith, __iendswith, __range, __in, __isnull, comparison lookups)
  • Model lifecycle operations (save(update_fields=...), refresh_from_db(), instance delete())
  • Relation loading and traversal (select_related, prefetch_related, reverse managers, M2M manager add/remove/clear/set)
  • Transactions (atomic)
  • App-scoped table naming and migration tracking
• Safer SQL execution defaults:
  • raw SQL runs through app table allowlist checks by default
  • explicit high-trust bypass via unsafe_unchecked=True for migration/operator workflows
• Migration planner features:
  • cross-app dependency graph
  • cycle detection
  • target and fake application (migrate <app> <target> --fake)
  • migration metadata checksums (ferrum_migration_meta) with checksum drift detection
  • deterministic warnings for rename/removal/alter autodiff gaps
• Backend adapter seams:
  • SQLite runtime backend
  • PostgreSQL runtime backend
  • dual-backend ORM parity tests (SQLite + PostgreSQL, PostgreSQL enabled with env)
• Installed app governance:
  • ferrum_installed_apps sync
  • startup drift enforcement when removing apps that still have applied migrations

Quickstart (uv + maturin)

cd /Users/sid/github/ferrum
uv python install 3.14t
uv venv --python 3.14t .venv
source .venv/bin/activate
uv sync

Run tests:

uvx --with pytest python3.14t -m pytest tests/ -q
cargo test -q

Test coverage:

• Python: 98 passing tests (56% coverage)
• Rust: 22 passing tests
• Key modules: middleware 94%, http 86%, models 76%

Run PostgreSQL parity variants by setting:

export FERRUM_TEST_POSTGRES_URL="postgresql://<user>:<pass>@localhost:<port>/<db>"
.venv/bin/pytest -q

Free-threaded Python only (no GIL)

Ferrum only supports free-threaded CPython with no GIL:

• Python version: >=3.14
• Build type: free-threaded (python3.14t / Py_GIL_DISABLED=1)
• Runtime mode: gil_enabled=False

Set up with uv:

cd /Users/sid/github/ferrum
uv python install 3.14t
uv venv --python 3.14t .venv-314t
source .venv-314t/bin/activate
uv pip install -e .
uv pip install maturin
maturin develop

Verify runtime mode:

python -c "import ferrum; print(ferrum.runtime_info())"

Expected when no-GIL is active:

• "free_threaded_build": True
• "gil_enabled": False
• "no_gil_active": True

Ferrum will fail fast at import if any of the above conditions are not met. If needed, force no-GIL mode at runtime with:

PYTHON_GIL=0 python example_project/manage.py runserver 8131

Create a new project

Use ferrum-admin (script entrypoint) or call management directly.

ferrum-admin startproject mysite
cd mysite
python manage.py help

Generated structure:

mysite/
├── manage.py
└── mysite/
    ├── __init__.py
    ├── settings.py
    ├── urls.py
    ├── asgi.py
    └── wsgi.py

Create an app

python manage.py startapp books

This creates:

• books/models.py
• books/apps.py
• books/views.py
• books/urls.py
• books/migrations/

and appends "books" to INSTALLED_APPS.

Re-running startapp books is idempotent and repairs missing scaffold files.

Migrations workflow

python manage.py makemigrations
python manage.py showmigrations
python manage.py migrate

Targeted and fake migration examples:

python manage.py migrate books 0001_initial --fake
python manage.py migrate books 0002_more

Middleware configuration

In settings.py:

MIDDLEWARE = [
    "myproject.middleware.TraceHeaderMiddleware",
    "myproject.middleware.ValueErrorMiddleware",
]

Supported hooks on middleware classes:

• process_request(self, request) -> HttpResponse | None
• process_response(self, request, response) -> HttpResponse
• process_exception(self, request, exc) -> HttpResponse | None

Run server

Default:

python manage.py runserver

• Uses PORT from settings when not passed explicitly.
• You can override with a CLI port: python manage.py runserver 9000.
• Enable stat autoreload in development: python manage.py runserver --reload.

Model lifecycle helpers

book = Book.objects.create(title="Before", pages=100)
book.title = "After"
book.save(update_fields=["title"])
book.refresh_from_db()
book.delete()

Example project in this repo

Reference implementation is in:

• /Users/sid/github/ferrum/example_project/manage.py
• /Users/sid/github/ferrum/example_project/example_project/settings.py
• /Users/sid/github/ferrum/example_project/example_project/urls.py
• /Users/sid/github/ferrum/example_project/demo_app/models.py
• /Users/sid/github/ferrum/example_project/demo_app/views.py
• /Users/sid/github/ferrum/example_project/demo_app/urls.py

Try:

cd /Users/sid/github/ferrum
python example_project/manage.py makemigrations demo_app --name initial
python example_project/manage.py migrate
python example_project/manage.py runserver 8131

Then:

curl -i http://127.0.0.1:8131/books/
curl -i -X POST http://127.0.0.1:8131/books/create/
curl -i http://127.0.0.1:8131/books/1
curl -i -X POST http://127.0.0.1:8131/relationships/seed/
curl -i http://127.0.0.1:8131/books/1/graph/
curl -i http://127.0.0.1:8131/books/1/buyers/
curl -i http://127.0.0.1:8131/buyers/1/books/
curl -i http://127.0.0.1:8131/books/queryset/
curl -i -X POST http://127.0.0.1:8131/books/lifecycle-demo/
curl -i http://127.0.0.1:8131/middleware/42/?q=rust
curl -i http://127.0.0.1:8131/middleware/error/

Roadmap

Roadmap and milestone tracking live in:

• /Users/sid/github/ferrum/FERRUM_ROADMAP.md