Metadata-Version: 2.4
Name: buraq
Version: 1.0.0
Summary: A high-performance Django-like framework built on FastAPI
License: MIT
License-File: LICENSE
Keywords: async,django-like,fastapi,framework,web
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.2.0
Requires-Dist: aiosmtplib>=3.0.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: asyncpg>=0.29.0
Requires-Dist: email-validator>=2.1.0
Requires-Dist: fastapi>=0.111.0
Requires-Dist: granian>=1.5.0
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: orjson>=3.10.0
Requires-Dist: pydantic-settings>=2.3.0
Requires-Dist: pydantic[email]>=2.7.0
Requires-Dist: pyjwt[crypto]>=2.8.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: redis[hiredis]>=5.0.0
Requires-Dist: secure>=0.3.0
Requires-Dist: slowapi>=0.1.9
Requires-Dist: sqladmin>=0.18.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.0
Requires-Dist: sqlmodel>=0.0.19
Requires-Dist: typer>=0.12.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: memcached
Requires-Dist: aiomcache>=0.8.0; extra == 'memcached'
Provides-Extra: mysql
Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
Provides-Extra: production
Requires-Dist: gunicorn>=22.0.0; extra == 'production'
Requires-Dist: whitenoise>=6.7.0; extra == 'production'
Provides-Extra: sqlite
Requires-Dist: aiosqlite>=0.20.0; extra == 'sqlite'
Description-Content-Type: text/markdown

# Buraq

**A high-performance, batteries-included Python web framework — built for AI applications, high-traffic APIs, and developers who know Django.**

Buraq delivers Rust-powered performance at every layer — Granian ASGI server, orjson, asyncpg, uv — with a complete full-stack framework: ORM, admin, forms, auth, migrations, templates, signals, cache, and email. All async, all fast.

If you know Django, you already know Buraq. Same views, same URLs, same templates, same ORM patterns — just add `await`. Built on FastAPI and SQLAlchemy 2.0 under the hood, so you get auto-generated API docs, Pydantic validation, and Rust-level performance out of the box.

[![PyPI version](https://img.shields.io/pypi/v/buraq.svg)](https://pypi.org/project/buraq/)
[![Python](https://img.shields.io/pypi/pyversions/buraq.svg)](https://pypi.org/project/buraq/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![CI](https://github.com/nezanuha/buraq/actions/workflows/ci.yml/badge.svg)](https://github.com/nezanuha/buraq/actions/workflows/ci.yml)

---

## Why Buraq?

Modern applications — especially AI backends, LLM APIs, and real-time services — need a framework that handles thousands of concurrent requests without blocking. They also need the full stack: ORM, auth, admin, migrations, cache, and email — not just a router.

At the same time, Python web developers coming from Django shouldn't have to give up familiar patterns just to get async performance. Switching to a low-level async framework means losing everything Django provides out of the box.

Buraq solves both problems. A complete, batteries-included web framework with Rust-powered performance at every layer — and zero re-learning curve for Django developers.

---

## Django Developers: Migrate in Minutes

Buraq is intentionally designed to mirror Django's API. Your existing knowledge transfers directly.

| Django | Buraq |
|---|---|
| `from django.urls import path` | `from buraq.urls import path` |
| `from django.shortcuts import render, redirect` | `from buraq.shortcuts import render, redirect` |
| `from django.views.generic import ListView` | `from buraq.views.generic import ListView` |
| `from django import forms` | `from buraq.forms import ModelForm` |
| `from django.db import models` | `from buraq import models` |
| `from django.contrib.auth.decorators import login_required` | `from buraq.decorators import login_required` |
| `from django.contrib import messages` | `from buraq.contrib.messages import success, error` |
| `python manage.py runserver` | `buraq runserver` |
| `python manage.py makemigrations` | `buraq makemigrations` |
| `python manage.py migrate` | `buraq migrate` |
| `python manage.py startapp` | `buraq startapp` |
| `python manage.py createsuperuser` | `buraq createsuperuser` |
| `python manage.py collectstatic` | `buraq collectstatic` |

The only difference: add `async`/`await` to your views and ORM calls.

```python
# Django
def post_list(request):
    posts = Post.objects.filter(published=True).order_by("-created_at")
    return render(request, "posts/list.html", {"posts": posts})

# Buraq — same pattern, truly async
async def post_list(request):
    posts = await Post.objects.filter(published=True).order_by("-created_at")
    return render(request, "posts/list.html", {"posts": posts})
```

---

## Quick Start

```bash
pip install buraq
buraq startproject myproject
cd myproject
buraq migrate
buraq runserver
```

Visit `http://127.0.0.1:8000` — your project is running.  
Visit `http://127.0.0.1:8000/api/docs` — Swagger UI, auto-generated.

---

## Everything Included

### ORM & Database
```python
from buraq import models

class Post(models.Model):
    title        = models.CharField(max_length=200)
    slug         = models.SlugField(unique=True)
    content      = models.TextField()
    is_published = models.BooleanField(default=False)
    created_at   = models.DateTimeField(auto_now_add=True)
    author       = models.ForeignKey("auth.User", on_delete=models.CASCADE)
```

```bash
buraq makemigrations
buraq migrate
```

### URLs
```python
from buraq.urls import path, include

urlpatterns = [
    path("/posts",          views.PostListView.as_view(),   name="post_list"),
    path("/posts/new",      views.PostCreateView.as_view(), name="post_create"),
    path("/posts/<int:pk>", views.PostDetailView.as_view(), name="post_detail"),
    path("/api",            include("myapp.api_urls")),
]
```

### Class-Based Views
```python
from buraq.views.generic import ListView, DetailView, CreateView, UpdateView, DeleteView

class PostListView(ListView):
    model         = Post
    template_name = "posts/list.html"
    paginate_by   = 10

class PostCreateView(CreateView):
    model         = Post
    form_class    = PostForm
    template_name = "posts/form.html"
    success_url   = "/posts"
```

### Function-Based Views
```python
from buraq.shortcuts import render, redirect, get_object_or_404
from buraq.contrib.messages import success
from buraq.decorators import login_required

@login_required
async def post_create(request):
    form = PostForm(await request.form())
    if form.is_valid():
        await form.save()
        success(request, "Post created successfully.")
        return redirect("/posts")
    return render(request, "posts/form.html", {"form": form})
```

### Forms & ModelForm
```python
from buraq.forms import ModelForm, CharField, BooleanField

class PostForm(ModelForm):
    class Meta:
        model  = Post
        fields = ["title", "slug", "content", "is_published"]
```

### Templates (Jinja2)
```html
{% extends "base.html" %}

{% block content %}
  {% for post in posts %}
    <h2><a href="/posts/{{ post.id }}">{{ post.title }}</a></h2>
  {% endfor %}

  {% if messages %}
    {% for message in messages %}
      <div class="alert">{{ message }}</div>
    {% endfor %}
  {% endif %}
{% endblock %}
```

### Authentication
```python
from buraq.contrib.auth import authenticate, login, logout
from buraq.decorators import login_required

async def login_view(request):
    user = await authenticate(request, username=username, password=password)
    if user:
        await login(request, user)
        return redirect("/dashboard")
```

### Signals
```python
from buraq.signals import post_save

@post_save.connect(sender=Post)
async def on_post_saved(sender, instance, created, **kwargs):
    if created:
        await notify_subscribers(instance)
```

### Cache
```python
from buraq.contrib.cache import cache

await cache.set("key", value, timeout=300)
value = await cache.get("key")
```

### Email
```python
from buraq.contrib.email import send_mail

await send_mail(
    subject="Welcome to Buraq",
    message="Thanks for signing up.",
    to=["user@example.com"],
)
```

---

## Performance

Buraq is built on the fastest available Python components at every layer:

| Layer            | Library              | Benefit                          |
|------------------|----------------------|----------------------------------|
| ASGI server      | Granian (Rust)       | Faster than uvicorn on all platforms |
| Web framework    | FastAPI              | ASGI-native, Pydantic v2         |
| Database driver  | asyncpg              | Fastest async PostgreSQL driver  |
| ORM              | SQLAlchemy 2.0       | Native async, no sync wrapper    |
| JSON             | orjson (Rust)        | 3–10× faster than stdlib json    |
| Password hashing | Argon2id             | PHC winner — memory-hard, fast to verify |
| Package manager  | uv (Rust)            | 10–100× faster than pip          |

---

## Features at a Glance

- **Async ORM** with SQLAlchemy 2.0 — `await Model.objects.filter(...)`
- **Alembic migrations** — `buraq makemigrations` / `buraq migrate`
- **`path()` URL routing** with type-safe converters
- **Class-based views** — ListView, DetailView, CreateView, UpdateView, DeleteView
- **ModelForm** with field validation and `await form.save()`
- **Jinja2 templates** with Django-compatible template tags
- **Built-in auth** — JWT + session, login/register/logout
- **Auto admin panel** via SQLAdmin — `buraq createsuperuser`
- **Flash messages** backed by session storage
- **Signals** — `post_save`, `pre_delete`, custom signals
- **Cache backends** — Redis, Memcached, in-memory (all async)
- **Email backends** — SMTP, console, file (all async)
- **Static files** — WhiteNoise + `buraq collectstatic`
- **Rate limiting** via SlowAPI
- **Security headers** via the `secure` package
- **CORS middleware**
- **orjson** for all JSON responses
- **Granian** ASGI server built-in, falls back to uvicorn
- **Auto API docs** — Swagger UI and ReDoc at `/api/docs`

---

## Documentation

Full documentation: [buraqproject.com/docs/1.0](https://buraqproject.com/docs/1.0)

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) — contributions are welcome.

## Changelog

See [CHANGELOG.md](CHANGELOG.md).

## License

MIT — see [LICENSE](LICENSE)
