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
├── resources/
│   ├── views/            # Jinja2 templates
│   └── css/app.css       # Tailwind source
├── 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'll see a real server-rendered welcome page (Blade, from resources/views/welcome.blade.html), styled with Tailwind CSS, not just a JSON blob; see Views, Blade, and Frontend & CSS. Try registering a user and listing them. CSRF protection is on by default and needs its token back via a header on every unsafe request, even the very first one — a plain GET hands you that token as a cookie (see CSRF Protection):

curl -c cookies.txt http://127.0.0.1:8000/ -o /dev/null
CSRF=$(grep csrf_token cookies.txt | awk '{print $NF}')

curl -b cookies.txt -H "X-CSRF-Token: $CSRF" -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.