asok 0.1.3

A minimalist, zero-dependency Python web framework.

---

Asok is a powerful and elegant "zero-dependency" Python web framework that brings modern development patterns to Python. Built with security-first principles, it combines the simplicity of Flask with the batteries-included approach of Django, while introducing Next.js-style file-based routing.

🌐 Official Website & Documentation | 📖 Quick Start Guide | 💬 Join Discord | 🎥 YouTube Tutorials

---

🎯 Why Asok?

Zero Dependencies, Maximum Power

Unlike other Python frameworks, Asok requires zero external dependencies - just Python 3.10+. No Werkzeug, no Jinja2, no SQLAlchemy. Everything is built from the Python standard library, making it:

• ✅ Extremely lightweight (~200KB)
• ✅ Dead simple to audit (security teams love it)
• ✅ Forever stable (no dependency hell)
• ✅ Fast to install (< 1 second)

Modern Developer Experience

# File-based routing like Next.js
src/pages/blog/[slug]/page.py  →  /blog/hello-world

# Reactive components out of the box
<div asok-state="{ count: 0 }">
  <button asok-on:click="count++">{{ count }}</button>
</div>

# Admin interface in 2 lines
admin = Admin(app)

Production-Ready Security

• 🔒 OWASP Top 10 protections built-in
• 🔒 Automatic CSRF tokens with rotation
• 🔒 SQL injection prevention via parameterized queries
• 🔒 XSS protection with auto-escaping templates
• 🔒 Secure sessions (HttpOnly, SameSite=Strict, HMAC-signed)
• 🔒 10/10 security score in comprehensive audits

---

✨ Key Features

Core Framework

• 🚀 Zero Dependencies - Pure Python stdlib, no external packages
• 💎 Full Type Hints - Complete PEP 484 support for IDE autocomplete
• 📦 Tiny Footprint - ~200KB, installs in < 1 second
• ⌨️ Powerful CLI - Scaffolding, migrations, dev server, production builds
• 🛣️ File-based Routing - Next.js-style routing (src/pages/ → URLs)
• ⛓️ Dynamic Routes - Parameters via [id], [slug:slug] patterns

Database & ORM

• 🗄️ Built-in ORM - SQLite with relations, migrations, soft deletes
• 🔍 Full-Text Search - FTS5 integration for lightning-fast search
• 🔐 Auto Password Hashing - PBKDF2-SHA256 with 100k iterations
• 📊 Query Builder - Fluent API with eager loading

Templates & Frontend

• 🎨 Template Engine - Jinja-compatible with inheritance and macros
• ⚡ Reactive Components - Client-side reactivity (< 3KB, no build step)
• 🔄 Live Components - Server-driven real-time updates via WebSockets
• 💨 HTML Streaming - Chunked responses for instant TTFB
• 🎭 Transitions - Built-in fade/slide/scale animations

Security (10/10 Score)

• 🔒 CSRF Protection - Auto-rotation, HMAC validation, SameSite=Strict
• 🔒 XSS Prevention - Auto-escaping templates, CSP nonces
• 🔒 SQL Injection - Parameterized queries, column validation
• 🔒 Secure Sessions - HttpOnly, Secure flags, HMAC-signed
• 🔒 Path Traversal - Absolute path validation

Admin & Developer Tools

• 👨‍💼 Auto Admin - Django-style admin in 2 lines of code
• 🌍 i18n Ready - Multi-language support with JSON translations
• 📧 Email Service - SMTP integration with templates
• 📦 Production Build - Bytecode compilation, minification, WebP conversion
• 🧪 Testing Tools - Built-in test client, fixtures support

---

⚖️ Asok vs Django vs Flask

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

---

🛠️ Installation & Setup

1. Installation

You can install Asok via pip:

pip install asok

or clone the repo and use the asok/ folder.

2. Create a project

asok create my-project
cd my-project

3. Start the server

asok dev

---

🏗️ Project Structure

├── src
│   ├── components                # Reactive components
│   ├── locales                   # JSON translations (en.json, fr.json, ...)
│   │   ├── en.json                  
│   │   └── fr.json
│   ├── middlewares               # Request interceptors
│   ├── models                    # ORM models (Post.py, User.py)
│   ├── pages                     # YOUR ROUTES (page.py, page.html)
│   │   ├── page.html
│   │   └── page.py
│   └── partials                  # css, js, images, html, uploads
│       ├── css
│       │   └── base.css
│       ├── html
│       │   └── base.html
│       ├── images
│       │   └── logo.svg
│       ├── js
│       │   └── base.js
│       └── uploads
└── wsgi.py                # Application entry point

---

🛣️ Routing

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 → /about
• src/pages/user/[id]/page.py → /user/123 (id parameter)
• src/pages/blog/[slug:slug]/page.py → /blog/my-post-slug

Dynamic Page Example (src/pages/shop/[cat]/page.py)

from asok import Request 

def render(request: Request):
    category = request.params.get('cat')
    return f"Shop : {category}"

---

🎨 Templates & Inheritance

Templates in src/pages/ can inherit from layouts in src/partials/html/.

Layout (src/partials/html/base.html) :

<!DOCTYPE html>
<html lang="{{ request.lang }}">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link rel="icon" href="{{ static('images/logo.svg') }}" type="image/svg+xml">
    <title>{% block title %}{% endblock %} &mdash; my-project</title>
    <link rel="stylesheet" href="{{ static('css/base.css') }}">
    <script defer src="{{ static('js/base.js') }}"></script>
</head>
<body>
    <main>{% block main %}{% endblock %}</main>
</body>
</html>

Page (src/pages/page.html) :

{% extends "html/base.html" %}
{% block title %}Welcome{% endblock %}

{% block main %}
    <div class="container">
        <img src="{{ static('images/logo.svg') }}" alt="Logo Asok">
        <h1>Welcome to Asok</h1>
        <p>No dependencies—just Python’s standard library</p>
        <p>Edit <code>src/pages/page.html</code> to get started.</p>
    </div>
{% endblock %}

---

🗄️ AsokDB (The ORM)

Define your models in src/models/.

from asok import Field, Model

class User(Model):
    email = Field.String(unique=True, nullable=False)
    password = Field.Password()
    name = Field.String()
    is_admin = Field.Boolean(default=False)
    created_at = Field.CreatedAt()

---

🌍 i18n & Validation

• Translation: {{ __('welcome') }} (looks in src/locales/).
• Validation: Validator(data).rule('email', 'required|email').
• CSRF: {{ request.csrf_input() }} automatic in forms.

---

🎨 Admin Customization

The administration interface is highly customizable:

admin = Admin(app, site_name="My Platform", favicon="images/logo.svg")

Asset Resolution (Smart Resolution)

The admin automatically detects the source of resources:

• Internal Assets: Files like admin.css or the default logo.svg are served from the package.
• Project Assets: If you specify a path (e.g. images/logo.svg or uploads/icon.png), the admin will serve them from your resources folder (src/partials/).

---

🚀 Towards Production

Asok is WSGI compatible. You can use Gunicorn or any other WSGI server:

gunicorn wsgi:app

---

🤝 Contributing

We ❤️ contributions! Asok is built to be simple, transparent, and fun to hack on. Whether you're a Python beginner or expert, there's a place for you here.

🌟 Ways to Contribute

• 🐛 Report bugs - Found an issue? Open a bug report
• 💡 Suggest features - Have an idea? Start a discussion
• 📝 Improve docs - Spot a typo? Docs are in asok-docs
• 🔧 Submit PRs - Fixed something? Send a pull request
• ⭐ Star the repo - Show your support!
• 💬 Help others - Answer questions in Discussions

🚀 Quick Start for Contributors

# 1. Fork and clone the repo
git clone https://github.com/YOUR_USERNAME/asok.git
cd asok

# 2. Create a virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# 3. Install dependencies (dev mode)
pip install -e .

# 4. Run the test suite (353 tests should pass!)
python -m pytest

# 5. Create a branch for your feature
git checkout -b feature/amazing-feature

# 6. Make your changes and test
python -m pytest -v

# 7. Commit and push
git commit -m "feat: add amazing feature"
git push origin feature/amazing-feature

📖 Read our full Contributing Guide for code style, commit conventions, and more.

🏆 Contributors

Thanks to all our amazing contributors! 🎉

---

🌐 Ecosystem

Explore the Asok ecosystem:

• 🛠️ Asok Examples - Ready-to-use projects and templates
• 🧪 Asok Lab - Experimental features, benchmarks, playground
• 📖 Asok Docs - Documentation and website source
• 🎓 Asok Tutorials - Step-by-step learning paths

---

💬 Community & Support

Join our growing community:

• 💬 Discord Server - Real-time chat, help, and discussions
• 🐦 Twitter/X - News and updates
• 📖 GitHub Discussions - Q&A, feature requests, show & tell
• 📧 Newsletter - Monthly updates and tips
• 🎥 YouTube Channel - Tutorials and demos

Need help?

• 📚 Check the documentation
• 🔍 Search existing issues
• 💬 Ask in Discord or Discussions

---

🗺️ Roadmap

Asok is actively developed with exciting features planned:

v0.2.0 (Q2 2026) - Enterprise Features

• PostgreSQL & MySQL support, advanced ORM relationships
• WebSocket rooms for real-time collaboration
• Background job queue system
• Plugin ecosystem & CLI enhancements

v0.3.0 (Q3 2026) - Modern Stack

• GraphQL API support with auto-generated schemas
• Server-side rendering (SSR) & static site generation
• Built-in monitoring & observability tools
• Full async/await support (ASGI)

See the detailed roadmap for complete feature lists, timelines, and how to contribute to planning.

---

⭐ Star History

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.