2 min read

Getting Started#

Asok is a zero-dependency Python framework that combines the simplicity of Flask, the included batteries of Django, and the modern file-based routing of Next.js/SvelteKit.

Installation#

pip install asok

Create a project#

Asok features a smart interactive CLI. Just run the create command and it will guide you through the setup:

asok create myapp
# ? Add Tailwind CSS support? [y/N]: y
# ? Add Admin interface? [y/N]: y
# ? Add Image Optimization (WebP)? [y/N]: y

If you prefer to skip questions, use flags: asok create myapp --tailwind --admin --image.

Run the server:

asok dev

Open http://127.0.0.1:8000 — your app is running with live browser reload. Edit any file and the browser refreshes automatically.

Want a different port? Use asok dev -p 3000. If the port is busy, Asok finds the next free one automatically.

Project structure#

myapp/
├── .env                        # Environment variables
├── src
│   ├── components               # Reactive (Live) Components
│   ├── locales                  # Translation files (en.json, fr.json)
│   │   ├── en.json
│   │   └── fr.json
│   ├── middlewares              # Middleware handlers
│   ├── models                   # Database models
│   │   └── user.py
│   ├── pages                    # Routes (file-based)
│   │   ├── page.html
│   │   └── page.py
│   └── partials                 # Shared assets
│       ├── css
│       │   └── base.css
│       ├── html
│       │   └── base.html
│       ├── images
│       │   └── logo.svg
│       ├── js
│       │   └── base.js
│       └── uploads
└── wsgi.py                   # Entry point

How it works#

A request arrives at /contact
Asok looks for src/pages/contact/page.py (or page.html)
It calls the render(request) function
Your function returns HTML via request.html('page.html')
Asok sends the response

That's it. No decorators, no app.route(), no configuration file. Your folder structure is your routing.

Minimal example#

# src/pages/page.py
from asok import Request

def render(request: Request):
    return request.html('page.html')

<!-- src/pages/page.html -->
<h1>Hello, Asok!</h1>

Configuration#

All config goes in .env:

DEBUG=true
SECRET_KEY=change-me-in-production

Access in code:

request.env('SECRET_KEY')
request.env('DEBUG')  # Returns True (auto-cast)

What's included (zero dependencies)#

Feature	How
Routing	Folder-based, automatic
Database	SQLite ORM built-in
Templates	Jinja2-like syntax
Forms	Declarative, auto-validated
Auth	Login/logout/sessions
i18n	JSON locale files
Mail	SMTP via stdlib
Cache	Memory or file-based
CSRF	Automatic protection
CLI	Generators, migrations, seeder
Testing	WSGI test client

Everything runs on the Python standard library. No pip install needed beyond asok itself.

Was this page helpful?

Next Routing