Getting Started¶
This guide takes you from an empty directory to a running Zeython application with a database, a server-rendered home page and a working account system. Allow about five minutes.
Requirements¶
- Python 3.11 or newer
pipand the standardvenvmodule
No database server is needed to get started: new projects use SQLite.
PostgreSQL and MySQL are supported through the postgres and mysql extras
(see Database & Migrations).
1. Install Zeython¶
Create a virtual environment and install the framework, which also installs
the zeython command:
2. Create a project¶
zeython new generates a complete, runnable application:
my_blog/
├── app/
│ ├── Controllers/ # request handlers
│ ├── Models/ # async Active Record models
│ ├── Middleware/ # ASGI middleware
│ ├── Providers/ # your own service providers
│ ├── Jobs/ # background jobs
│ └── Console/Commands/ # custom CLI commands
├── database/
│ ├── factories/ # model factories for tests and seeding
│ └── seeders/ # seed data, run with `zeython db seed`
├── resources/
│ ├── views/ # Jinja2, Blade and Python views
│ └── css/app.css # Tailwind source
├── routes/
│ └── web.py # route definitions
├── migrations/ # Alembic migrations
├── tests/
├── main.py # application entry point
├── alembic.ini
├── Dockerfile
└── .env.example
main.py is the place to start reading. It constructs the Application
and registers the service providers your app uses. Every capability your
application has is switched on by a line in that file.
3. Create the database¶
A new project includes a User model but no migration for it yet. Generate
the initial migration from your models, then apply it:
4. Run the development server¶
Open http://127.0.0.1:8000. You will see a server-rendered welcome page,
built from the Blade template resources/views/welcome.blade.html and
styled with Tailwind CSS (see Views, Blade and
Frontend & CSS). The server reloads automatically when you
change a file.
5. Make your first authenticated request¶
Every new project ships with session authentication and
CSRF protection enabled. Unsafe requests (POST, PUT,
PATCH, DELETE) must send the CSRF token back in the X-CSRF-Token
header. Any GET request issues that token as a cookie:
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": "correct-horse-battery"}'
curl http://127.0.0.1:8000/users
/users is paginated (see Pagination), so the
response is an envelope such as {"items": [...], "page": 1, "total": 1, ...}
rather than a bare array.
Seeing a database error?
Make sure you ran both commands in step 3.
The users table does not exist until the first migration is applied.
Next steps¶
-
Learn by building
The Tutorial builds a real, tested, multi-model API from this same starting point.
-
Understand the design
Architecture explains the container, service providers and router.
-
Add your own models
Database & Migrations covers models, queries, pagination and transactions.
-
Generate code
The CLI Reference lists every
zeython makegenerator and command.