Asok is a powerful and elegant "zero-dependency" Python micro-framework. Version 0.1.0 introduces a professional modular architecture, file-based routing through the src/pages/ directory, and a comprehensive CLI tool.
📖 → Full Documentation — 44 chapters, from installation to production deployment.
- Zero Dependencies: Relies exclusively on the Python standard library.
- Professional Typing: Full support for PEP 484 type hints for a robust developer experience.
- Modular Package: Install via
pipor by simply dropping theasok/folder into your project. - CLI Tool: Scaffolding (
asok make), Dev Server (asok dev), and assets management. - Local Geolocation: Built-in IP detection and localization without third-party APIs.
- File-based Routing: Your
src/pages/directories define your URLs. - Dynamic Routing: Native support for parameters via
[param]. - Built-in Authentication: Secure sessions via signed cookies (HMAC).
- AsokDB: A mini SQLite ORM with relationships and automatic hashing.
- Template Engine: Jinja-like syntax with inheritance (
extends) and blocks.
Asok was designed to bring the best of both worlds (the lightweight nature of Flask and the batteries-included approach of Django), while adding modern file-based routing (inspired by Next.js/SvelteKit).
| Feature | Asok | Flask | Django |
|---|---|---|---|
| External Dependencies | 0 (Zero) | ~6 (Werkzeug, Jinja...) | ~3 (asgiref, sqlparse...) |
| Philosophy | Batteries Included + Modern | Micro-framework | Megalo-framework |
| Routing System | File-based (src/pages/) |
Decorators (@app.route) |
Centralized (urls.py) |
| Built-in ORM | Yes (AsokDB - optimized SQLite) | No (SQLAlchemy required) | Yes (Full-featured, multi-DB) |
| Generated Admin | Yes, 100% automatic and reactive | No (Flask-Admin required) | Yes, historical and heavy |
| Real-time (WebSockets) | Native (Alive Engine) | No (Flask-SocketIO required) | Complex (Django Channels) |
| Reactive Components | Native (Live Components) | No | No |
| Ideal for | Fast projects, Modern SaaS, Zero devops | Simple APIs, Microservices | Large legacy architectures |
You can install Asok via pip (coming soon) or clone the repo and use the asok/ folder.
asok create my-project
cd my-projectasok dev.
├── wsgi.py # Application entry point
├── src
│ ├── locales/ # JSON translations (en.json, fr.json)
│ ├── middlewares/ # Request interceptors
│ ├── models/ # ORM models (Post.py, User.py)
│ ├── pages/ # YOUR ROUTES (page.py or page.html)
│ │ ├── page.html # Route /
│ │ └── about/
│ │ └── page.html # Route /about
│ └── partials/ # Shared resources
│ ├── css/, js/, images/
│ └── html/ # Layouts and components
Routing is dictated by the structure of the src/pages/ folder. Each folder represents a URL segment, and contains a page.py or page.html file.
src/pages/page.html→/src/pages/about/page.html→/aboutsrc/pages/user/[id]/page.py→/user/123(idparameter)
def render(request):
category = request.params.get('cat')
return f"Shop : {category}"Templates in src/pages/ can inherit from layouts in src/partials/html/.
Layout (src/partials/html/main.html) :
<html>
<body>
{% include 'html/_nav.html' %}
<main>{% block content %}{CONTENT}{% endblock %}</main>
</body>
</html>Page (src/pages/page.html) :
{% extends 'html/main.html' %}
{% block content %}
<h1>Welcome to Asok V2</h1>
{% endblock %}Define your models in src/models/.
from asok import Model, Field, Relation
class User(Model):
name = Field.String()
email = Field.String(unique=True)
password = Field.Password()
posts = Relation.HasMany('Post')- Translation:
{{ __('welcome') }}(looks insrc/locales/). - Validation:
Validator(data).rule('email', 'required|email'). - CSRF:
{{ request.csrf_input() }}automatic in forms.
The administration interface is highly customizable:
admin = Admin(app, site_name="My Platform", favicon="images/logo.svg")The admin automatically detects the source of resources:
- Internal Assets: Files like
admin.cssor the defaultlogo.svgare served from the package. - Project Assets: If you specify a path (e.g.
images/logo.svgoruploads/icon.png), the admin will serve them from your resources folder (src/partials/).
Asok is WSGI compatible. You can use Gunicorn or any other WSGI server:
gunicorn wsgi:appContributions are more than welcome! Asok is built to be simple and transparent, making it a great codebase to dive into.
- Found a bug? Open an Issue.
- Have a feature idea? Start a Discussion.
- Fixed something? Submit a Pull Request.
Make sure to run the tests and linter before submitting your PR:
make lint
make testThis project is licensed under the MIT License - see the LICENSE file for details.
