fluxium 0.1.0__tar.gz

fluxium-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a welcoming experience for everyone, regardless of background, experience level, gender, identity, nationality, ethnicity, religion, or any other personal characteristic.
+
+## Our Standards
+
+**Positive behaviour includes:**
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experience
+- Gracefully accepting constructive feedback
+- Focusing on what is best for the community
+- Showing empathy toward other community members
+
+**Unacceptable behaviour includes:**
+
+- Harassment or discriminatory language of any kind
+- Personal attacks or insults
+- Trolling or deliberately disruptive behaviour
+- Publishing others' private information without permission
+
+## Enforcement
+
+Instances of unacceptable behaviour may be reported by opening a private issue or contacting the maintainers directly. All reports will be reviewed and addressed promptly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

fluxium-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to Fluxium
+
+Fluxium is primarily a learning project, but contributions are welcome. If you have found a bug, want to improve performance, or want to add something useful, open an issue first so we can talk through the approach before you write code.
+
+---
+
+## Getting started
+
+Fork the repository and clone it:
+
+```bash
+git clone https://github.com/sidx0/fluxium
+cd fluxium
+```
+
+Set up a virtual environment:
+
+```bash
+python -m venv venv
+source venv/bin/activate      # Windows: venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+Run the tests to confirm everything is working:
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## What to work on
+
+Bug fixes are always welcome, especially in the HTTP parser, ORM, or DI system. If you have a performance improvement, include benchmarks before and after so the change can be evaluated. New layers should follow the pattern of existing ones — zero mandatory dependencies, testable in isolation.
+
+If you want to add a feature, open an issue describing what problem it solves before writing code. That way you do not spend time on something that might not fit the project's direction.
+
+---
+
+## Making a change
+
+Create a branch:
+
+```bash
+git checkout -b fix/describe-the-fix
+```
+
+Write tests for your change. Tests are in `tests/` and use pytest-asyncio for async cases:
+
+```python
+import pytest
+from flux import Flux
+
+@pytest.mark.asyncio
+async def test_something():
+    app = Flux()
+    ...
+```
+
+Make sure the full test suite passes before submitting:
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+## Pull request checklist
+
+- Tests pass
+- New behaviour has test coverage
+- No new mandatory dependencies
+- The PR description explains what the change does and why
+
+---
+
+## Reporting bugs
+
+Open an issue with:
+
+- Fluxium version (`fluxium version`)
+- Python version and OS
+- A minimal example that reproduces the problem
+- The full traceback if there is one
+
+---
+
+## Code style
+
+Type hints on all public functions. `async def` for anything that does I/O. Keep modules focused — each file should do one thing. Docstrings on public classes and functions.
+
+No external formatters are required, but the code should be consistent with what is already there.

fluxium-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Flux Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fluxium-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include LICENSE
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include flux/py.typed
+recursive-include flux *.py
+recursive-include docs *.md
+recursive-include examples *.py

fluxium-0.1.0/PKG-INFO

@@ -0,0 +1,408 @@
+Metadata-Version: 2.4
+Name: fluxium
+Version: 0.1.0
+Summary: A zero-dependency async Python web framework
+Project-URL: Homepage, https://github.com/sidx0/fluxium
+Project-URL: Repository, https://github.com/sidx0/fluxium
+Project-URL: Documentation, https://github.com/sidx0/fluxium/tree/main/docs
+Project-URL: Bug Tracker, https://github.com/sidx0/fluxium/issues
+Project-URL: Changelog, https://github.com/sidx0/fluxium/blob/main/CHANGELOG.md
+Keywords: web,framework,asyncio,http,async,backend
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: jwt
+Requires-Dist: PyJWT>=2.8; extra == "jwt"
+Provides-Extra: templates
+Requires-Dist: Jinja2>=3.1; extra == "templates"
+Provides-Extra: all
+Requires-Dist: PyJWT>=2.8; extra == "all"
+Requires-Dist: Jinja2>=3.1; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: PyJWT>=2.8; extra == "dev"
+Requires-Dist: Jinja2>=3.1; extra == "dev"
+
+<p align="center">
+  <img src="logo.png" alt="Fluxium" width="220">
+</p>
+
+<h1 align="center">Fluxium</h1>
+
+<p align="center">
+  An async Python web framework written from scratch.<br>
+  No Starlette. No Pydantic. No Uvicorn. Just Python.
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/fluxium"><img src="https://img.shields.io/pypi/v/fluxium?color=1a1a1a&style=flat-square" alt="PyPI"></a>
+  <a href="https://github.com/sidx0/fluxium/actions"><img src="https://github.com/sidx0/fluxium/actions/workflows/tests.yml/badge.svg" alt="Tests"></a>
+  <img src="https://img.shields.io/badge/python-3.10+-1a1a1a?style=flat-square" alt="Python">
+  <img src="https://img.shields.io/badge/dependencies-zero-d4a017?style=flat-square" alt="Zero dependencies">
+  <img src="https://img.shields.io/badge/license-MIT-1a1a1a?style=flat-square" alt="MIT">
+</p>
+
+---
+
+Fluxium implements the entire HTTP stack in pure Python: the parser, header container, connection pool, router, middleware pipeline, dependency injection engine, ORM, authentication, WebSocket support, background task queue, and Prometheus metrics — all without a single mandatory third-party dependency.
+
+It started as an experiment to understand what a web framework actually does underneath. The result is fast, readable at every layer, and ships more built-in functionality than most frameworks that rely on an ecosystem of external packages.
+
+```python
+from flux import Flux
+
+app = Flux()
+
+@app.get("/")
+async def index():
+    return {"message": "Hello from Fluxium"}
+
+app.run(port=8000)
+```
+
+```bash
+pip install fluxium
+fluxium new myproject
+cd myproject && python main.py
+```
+
+---
+
+## Design
+
+Most Python frameworks are layers on top of other layers. FastAPI wraps Starlette. Starlette wraps anyio and h11. The code that actually moves bytes around lives several packages away from the thing you called `pip install` on.
+
+Fluxium owns the whole stack. The HTTP parser uses `memoryview` slices to avoid copying bytes during header parsing. The router compiles route patterns into named-group regexes at registration time and caches matches in a dictionary. The middleware pipeline is built as a flat chain of closures rather than a recursive call stack. The in-process loopback client calls the app's dispatch function directly, skipping TCP and serialisation entirely.
+
+Everything has a reason. Everything is readable.
+
+---
+
+## Performance
+
+Benchmarks run in-process on a single core. No real TCP.
+
+| Operation | Throughput | Mean latency |
+|---|---|---|
+| HTTP parse, GET | 140,026 / sec | 7.1 µs |
+| HTTP parse, POST + JSON body | 124,527 / sec | 8.0 µs |
+| Route match, warm cache | 986,564 / sec | 1.0 µs |
+| JSONResponse build and encode | 222,480 / sec | 4.5 µs |
+| Full in-process dispatch | 39,171 / sec | 25.5 µs |
+
+Compared to Flask on the same in-process test harness:
+
+| Metric | Flask | Fluxium |
+|---|---|---|
+| GET dispatch | 5,831 / sec | 70,142 / sec |
+| URL routing | 206,654 / sec | 6,367,537 / sec |
+| Memory per request | 12 KB | 4 KB |
+| Import time | 255 ms | 16 ms |
+
+The gap comes from abstraction count, not optimization tricks. Flask builds a full Werkzeug request context on every request. Fluxium wraps a parsed bytearray.
+
+```bash
+python -m flux benchmark
+```
+
+---
+
+## Installation
+
+```bash
+pip install fluxium
+```
+
+Optional extras:
+
+```bash
+pip install "fluxium[jwt]"        # PyJWT for token signing
+pip install "fluxium[templates]"  # Jinja2 for template rendering
+pip install "fluxium[all]"        # both
+```
+
+Neither extra is required. JWT falls back to stdlib HMAC-SHA256. Templates fall back to a built-in engine.
+
+---
+
+## Features
+
+### Core engine
+
+- HTTP/1.1 parser with zero-copy header parsing via `memoryview`
+- Compiled regex router with typed path parameters — `{id:int}`, `{slug:str}`, `{uid:uuid}`, `{file:path}`
+- Route match cache — warm lookups at roughly one million per second
+- Non-recursive async middleware pipeline, safe at any depth
+- Type-hint driven dependency injection with per-request scope
+- Schema auto-injection — body is parsed and validated before the handler runs
+- Async connection pool with keep-alive and idle reaping
+- In-process loopback client — same-process calls skip TCP entirely
+
+### Full-stack layers
+
+Every layer runs on Python's standard library. Optional dependencies improve but never block.
+
+| Layer | Description |
+|---|---|
+| `flux.orm` | Async SQLite ORM. Model, QuerySet, auto-migrations, thread-safe transactions. |
+| `flux.auth` | JWT tokens, PBKDF2 password hashing, `@requires_auth`, `@requires_role`. |
+| `flux.schema` | Validation with type coercion, constraints, mutable-default safety, 422 auto-response. |
+| `flux.openapi` | Auto-generated OpenAPI 3.0 spec. Swagger UI at `/docs`, ReDoc at `/redoc`. |
+| `flux.websocket` | RFC 6455 WebSocket with full fragmented-frame reassembly. |
+| `flux.tasks` | Async priority task queue with configurable retry and exponential backoff. |
+| `flux.observability` | Prometheus-compatible counters, histograms, structured JSON logging. |
+| `flux.config` | `Settings` class that reads from environment variables and `.env` files with type coercion. |
+| `flux.security` | Token-bucket rate limiter, CSRF protection, security headers, HTML sanitizer. |
+| `flux.templates` | Jinja2 integration with a built-in fallback engine. |
+| `flux.plugins` | Plugin lifecycle — `on_install`, `on_startup`, `on_shutdown`. |
+
+---
+
+## Usage
+
+### Path parameters
+
+```python
+@app.get("/users/{id:int}")
+async def get_user(id: int):
+    return {"id": id}
+
+@app.get("/files/{path:path}")
+async def get_file(path: str):
+    return {"path": path}
+```
+
+Supported types: `int`, `float`, `str` (default), `path`, `uuid`. A non-matching value returns 404 — no manual validation needed.
+
+### Request body validation
+
+```python
+from flux.schema import Schema, Field
+from typing import Optional
+
+class CreatePost(Schema):
+    title:    str = Field(min_length=1, max_length=200)
+    body:     str = Field(default="")
+    priority: int = Field(default=1, min_value=1, max_value=5)
+    tags:     list = Field(default=[])
+
+@app.post("/posts")
+async def create_post(data: CreatePost):
+    return {"title": data.title, "priority": data.priority}
+```
+
+If validation fails the handler is not called. The client receives a structured 422 response listing every field that failed and why.
+
+### Authentication
+
+```python
+from flux.auth import AuthConfig, AuthUser, requires_auth, requires_role
+
+app.auth = AuthConfig(secret="your-secret-key", token_ttl=86400)
+
+@app.post("/login")
+async def login(request):
+    data = request.json()
+    user = await User.filter(username=data["username"]).first()
+    if not user or not verify_password(data["password"], user.password_hash):
+        from flux.server.response import ErrorResponse
+        return ErrorResponse(401, "Invalid credentials")
+    token = app.auth.issue_token(user.id, roles=[user.role], username=user.username)
+    return {"token": token}
+
+@app.get("/me")
+@requires_auth
+async def me(user: AuthUser):
+    return {"id": user.id, "username": user.username}
+
+@app.delete("/admin/users/{id:int}")
+@requires_role("admin")
+async def delete_user(id: int, user: AuthUser):
+    await User.filter(id=id).delete()
+    return None
+```
+
+### Database
+
+```python
+from flux.orm import Database, Model, Integer, String, Boolean, auto_migrate
+
+db = Database("sqlite:///app.db")
+
+class Post(Model):
+    id      = Integer(primary_key=True)
+    title   = String(nullable=False)
+    status  = String(default="draft")
+    visible = Boolean(default=True)
+
+Post.bind(db)
+
+@app.on_startup
+async def startup():
+    await auto_migrate(Post)
+```
+
+```python
+post   = await Post.create(title="First post")
+posts  = await Post.filter(status="draft").order_by("-id").limit(20).all()
+count  = await Post.all().count()
+
+await Post.filter(id=post.id).update(status="published")
+await post.delete()
+
+async with db.transaction():
+    await Account.filter(id=from_id).update(balance=new_balance_from)
+    await Account.filter(id=to_id).update(balance=new_balance_to)
+```
+
+### Background tasks
+
+```python
+from flux.tasks import TaskQueue
+
+tq = TaskQueue(workers=4)
+app.di.register(TaskQueue, lambda: tq)
+
+@app.on_startup
+async def startup():
+    await tq.start()
+
+@app.on_shutdown
+async def shutdown():
+    await tq.stop(wait=True)
+
+@app.post("/register")
+async def register(data: RegisterInput, tq: TaskQueue):
+    user = await User.create(...)
+    await tq.enqueue(send_welcome_email, user.email)
+    return JSONResponse(user.to_dict(), status_code=201)
+```
+
+### WebSocket
+
+```python
+from flux.websocket import WebSocket, WebSocketDisconnect
+
+@app.websocket("/ws")
+async def handler(ws: WebSocket):
+    await ws.accept()
+    try:
+        while True:
+            message = await ws.receive_text()
+            await ws.send_json({"echo": message})
+    except WebSocketDisconnect:
+        pass
+```
+
+### Full application setup
+
+```python
+from flux import Flux
+from flux.auth import AuthConfig
+from flux.plugins import CORSPlugin
+from flux.observability import observability_middleware, mount_metrics
+from flux.security import RateLimiter, security_headers_middleware
+
+app = Flux(title="My API", version="1.0.0")
+app.auth = AuthConfig(secret="change-in-production")
+
+app.install(CORSPlugin(allow_origins="*"))
+app.add_middleware(observability_middleware)
+app.add_middleware(RateLimiter(requests_per_second=100))
+app.add_middleware(security_headers_middleware)
+mount_metrics(app)
+app.mount_docs()
+
+app.run(port=8000)
+```
+
+---
+
+## CLI
+
+```bash
+fluxium new myapp           # scaffold a complete project
+fluxium run myapp:app       # start the development server
+fluxium run myapp:app --reload   # with hot reload on file changes
+fluxium routes myapp:app    # print all registered routes
+fluxium version
+```
+
+`flux` works as an alias for all commands.
+
+---
+
+## Project layout
+
+```
+fluxium/
+  flux/
+    core/           HTTP parser, headers, connection pool
+    server/         Router, middleware, DI, request, response
+    client/         Async HTTP client and loopback
+    orm/            SQLite ORM
+    auth/           JWT, password hashing, RBAC
+    schema/         Validation engine
+    openapi/        OpenAPI spec and UI
+    websocket/      RFC 6455 implementation
+    tasks/          Background task queue
+    observability/  Prometheus metrics and structured logging
+    config/         Environment-based configuration
+    security/       Rate limiting, CSRF, security headers
+    templates/      Template rendering
+    plugins/        Plugin lifecycle
+  examples/
+    example_app.py       Minimal working example
+    fullstack_app.py     All layers in one file
+    taskflow_demo.py     Complete task manager with browser UI
+  tests/
+  docs/
+    architecture.md
+    getting_started.md
+    internals.md
+```
+
+---
+
+## Documentation
+
+- [Getting Started](docs/getting_started.md)
+- [Architecture](docs/architecture.md)
+- [Internals](docs/internals.md)
+
+---
+
+## Requirements
+
+- Python 3.10 or later
+- No mandatory dependencies
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+---
+
+<p align="center">
+  Built by <a href="https://github.com/sidx0">Siddhant B</a>
+</p>