Metadata-Version: 2.4
Name: beaverweb
Version: 0.1.0
Summary: A lightweight Python micro web framework built for learning
Author: Kalyan Chimmili
License: MIT License
        
        Copyright (c) 2026 Kalyan Ram Chimmili
        
        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 OF THE SOFTWARE.
        
Project-URL: Homepage, https://kalyanramchimmili.github.io/documentation/beaverWeb/introduction
Project-URL: Documentation, https://kalyanramchimmili.github.io/documentation/beaverWeb/introduction
Project-URL: Repository, https://github.com/kalyanramchimmili/beaverWeb
Keywords: web,framework,http,learning
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jinja2<4.0,>=3.0
Dynamic: license-file

# BeaverWeb 🦫

A lightweight Python micro web framework built for simplicity.

![Python](https://img.shields.io/badge/Python-3.10%2B-blue)  ![License](https://img.shields.io/badge/license-MIT-yellow)

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

## Install

```
pip install beaverweb
```

## Quick start

```python
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:

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

Point at a different folder:

```python
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
```
