asok 0.1.6

A minimalist, zero-dependency Python web framework.

---

Asok is a cohesive, full-stack Python web framework designed for developer speed, elegant architecture, and production-grade security. Built with a "zero-dependency" philosophy, it unifies server-side logic and client-side reactivity into a single, high-performance package, offering a streamlined and secure development experience from the first line of code.

🌐 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 (~360KB, ~20K lines of code)
• ✅ 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 - ~360KB, ~20K lines of code
• ⌨️ 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 600,000 iterations (OWASP 2023 compliant)
• 📊 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

High-Performance APIs

• 🔌 Native API Engine - Build robust REST APIs with minimal code
• 📑 Auto-OpenAPI - Automatic OpenAPI 3.0 (Swagger) generation for every route
• 🛡️ Bearer Token Auth - Built-in secure authentication for stateless clients
• ⚡ Optimized JSON - High-speed serialization for high-throughput services
• 📑 Live Documentation - Interactive API explorer (Swagger UI) included

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

---

⚖️ Philosophy & Positioning

Asok is built for the modern era of web development, where the boundary between frontend and backend is fluid. While it shares some values with other frameworks, it carves out its own path by providing a unified environment that eliminates the need for a complex "Franken-stack" of multiple tools and dependencies.

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

💡 Note for VS Code Users: For the best developer experience, we highly recommend installing the official Asok VS Code Extension. It provides native autocompletion, reactive snippets, and integrated CLI commands directly in your editor.

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

---

🔒 Production Security Checklist

Asok is built to be secure by default, but production environments require specific configurations to enable all protections.

1. Mandatory Environment Variables

In production (DEBUG=False), Asok enforces strict security checks:

• SECRET_KEY: Must be at least 32 characters long. Use secrets.token_hex(32) to generate one.
• APP_URL: Required for Magic Links to prevent Host Header Injection. Example: https://myapp.com.

2. Secure Defaults

• DEBUG: Default is False. You must explicitly set DEBUG=True in your .env for development.
• Password Hashing: PBKDF2-SHA256 with 600,000 iterations (OWASP 2023 compliant).
• Security Headers: HSTS (1 year), CSP (with nonces), X-Frame-Options (DENY), and X-Content-Type-Options (nosniff) are enabled by default.

3. Recommended .env for Production

ASOK_ENV=production
DEBUG=false
SECRET_KEY=your-64-character-ultra-secure-key-here
APP_URL=https://yourdomain.com
DATABASE_URL=sqlite:///data/prod.db

---

🤝 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 VS Code Extension - Official editor toolkit (autocompletion, snippets, CLI)
• 🛠️ 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
• 🎥 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.