BeaverWeb 🦫

A lightweight Python micro web framework built for simplicity.

📖 Docs: https://kalyanramchimmili.github.io/documentation/beaverWeb/introduction

Install

pip install beaverweb

Quick start

from beaver import App, Response, JSONResponse, HTMLResponse, Redirect

app = App()


@app.get("/")
def home(req):
    return app.render_template("welcome.html")


@app.get("/hello")
def hello(req):
    name = req.query_params.get("name", "stranger")
    return Response(f"Hello, {name}!")


@app.get("/users/{id}")
def user_detail(req):
    return JSONResponse({"id": req.path_params["id"]})


@app.post("/echo")
def echo(req):
    return JSONResponse(req.json() or {})


if __name__ == "__main__":
    app.run()

Run it and hit an endpoint:

python example.py
curl http://127.0.0.1:5000/hello?name=HelloWorld

🛠 What's implemented

• Dynamic Routing: Direct decorators (@app.get, @app.post, @app.put, @app.patch, @app.delete).
• Manual Segment Extraction: Clean path parameter parsing via @app.get("/users/{id}") exposed on req.path_params.
• Multi-Value Query Strings: Web-standard MultiDict parser allowing .get("id") for single values and .getlist("tag") for multi-value targets.
• Stream Flow Safety: Full-body reading with Content-Length validation to eliminate data truncation across network frames.
• Engine Isolation: Managed concurrency handling utilizing a custom reusable ThreadPoolExecutor layer, configurable via app.run(max_workers=100).
• Unified Error Mapping: Standardized server-level exception wrapping delivering 400 Bad Request, 404 Not Found, and 500 Internal Server Error statuses alongside direct terminal logging stack traces.
• Templating: Jinja2 rendering, configurable via App(templates_dir="views").

What's not (yet)

• WSGI / ASGI Spec Compliance (runs on a native core socket loop)
• Request validation via Type Hints / Dependency Injection
• Chunked Transfer-Encoding structures
• Custom middleware chains

Templating

BeaverWeb ships integrated with the Jinja2 template engine. Put your templates in a templates/ directory next to your app:

your-project/
├── example.py
└── templates/
    ├── welcome.html
    ├── 404.html
    └── 500.html

Render them from a handler:

@app.get("/")
def home(req):
    return app.render_template("welcome.html", name="World")

Point at a different folder:

app = App(templates_dir="views")

Auto-escaping is on for .html and .xml files by default.

Behavior notes

• Route precedence: first-registered wins. If you register both /users/me and /users/{id}, put the static one first — otherwise the dynamic route captures me as an id.
• Trailing slashes are lenient. /hello, /hello/, and /hello// all match a route registered as /hello. / and // both hit the root.
• Double leading slashes hit a 404. //hello gets parsed by urllib.parse.urlsplit as authority hello + empty path, not as path /hello.
• Method mismatch returns 405 with an Allow header listing every method registered on that path.
• Requests larger than Content-Length get trimmed. Extra bytes on the socket are dropped.

Project layout

beaver/
├── __init__.py     # public API
├── request.py      # bytes -> Request
├── response.py     # Response -> bytes
└── app.py          # routes, decorators, socket loop, dispatch, templates

• Requires Python 3.10+
• Dependencies: jinja2

🧪 Testing Suite

• The framework is verified using standard library assertions. To run the automated validation suites:

python -m unittest discover