Skip to content

Getting Started

Requirements

  • Python 3.11+

Install

python -m venv .venv
source .venv/bin/activate
pip install zeython

Scaffold a project

zeython new "My Blog"
cd my_blog
pip install -e .
cp .env.example .env

This generates:

my_blog/
├── app/
│   ├── Controllers/     # request handlers
│   ├── Models/          # async Active Record models
│   └── Middleware/       # ASGI middleware
├── routes/
│   └── web.py           # route definitions
├── migrations/           # Alembic migrations
├── tests/
├── main.py               # application entry point
├── alembic.ini
└── .env.example

Run it

zeython serve

Visit http://127.0.0.1:8000 — you should see a JSON welcome message. Try registering a user and listing them:

curl -X POST http://127.0.0.1:8000/register \
  -H 'Content-Type: application/json' \
  -d '{"name": "Ada", "email": "ada@example.com", "password": "hunter2"}'

curl http://127.0.0.1:8000/users

/users is paginated (see Database & Migrations) — the response is {"items": [...], "page": 1, "total": 1, ...}, not a bare array.

Getting a database error?

A fresh scaffold ships with the User model but no migration file yet — generate and apply the initial one first:

zeython db revision -m "create users table"
zeython db migrate

Next steps

  • Follow the Tutorial to build a real, tested, multi-model app from this same starting point — the fastest way to actually learn the framework.
  • Read Architecture to understand the container, service providers, and router.
  • Read Database & Migrations to add your own models.
  • Read CLI Reference for the full list of zeython make:* generators.