```markdown
# ZeeFast ⚡

**ZeeFast** is a lightweight experimental Python web framework inspired by **FastAPI**. 


It is built from scratch to understand how modern ASGI frameworks work internally, including routing, dependency injection, middleware, query parsing, and response handling.

This project is educational and experimental—not intended for production use.

---

# 🚀 Features

- ASGI-compatible (runs on **Uvicorn**)
- FastAPI-style decorators (`@app.get`, `@app.post`, etc.)
- Path parameters (`/user/{id}`)
- Query parameter auto-parsing (`/search?q=python&page=2`)
- Dependency Injection (`Depends` system)
- Response system (HTML, JSON, Plain Text)
- APIRouter (route grouping like FastAPI)
- Middleware system
- Status code module like FastAPI

---

# 📁 Project Structure

```

zeefast/
│
├── zeefast/
│   ├── app.py              # Core ZeeFast ASGI app
│   ├── request.py          # Request parsing
│   ├── response.py         # Response classes
│   ├── status.py            # HTTP status codes
│   ├── depends.py            # Dependency Injection system
│   ├── api_router.py         # APIRouter implementation
│   ├── middleware.py          # Middleware system
│   └── exceptions.py          # Custom exceptions
│
├── README.md
└── pyproject.toml / setup.py

````

---

# 🧠 Core Concepts

## 1️⃣ ASGI Application
ZeeFast is an ASGI callable:

```python
async def __call__(self, scope, receive, send):
    ...
````

Uvicorn calls this function for every request.

---

## 2️⃣ Routing

```python
app = ZeeFast()

@app.get("/hello")
def hello():
    return "Hello World"
```

### Path Parameters

```python
@app.get("/user/{id}")
def get_user(id: int):
    return {"user_id": id}
```

Internally converted to regex:

```
/user/{id} → ^/user/(?P<id>[^/]+)$
```

---

## 3️⃣ Query Parameters (FastAPI-style)

```python
@app.get("/search")
def search(q: str, page: int = 1):
    return {"query": q, "page": page}
```

Request:

```
/search?q=python&page=2
```

ZeeFast automatically injects query params into function arguments.

---

## 4️⃣ Response System

### Base Response

```python
class Response:
    def __init__(self, content, status=200, headers=None):
        ...
```

### Built-in Responses

```python
JsonResponse({...})
HtmlResponse("<h1>Hello</h1>")
PlainTextResponse("Hello")
RedirectResponse("/login")
```

FastAPI-style auto conversion:

| Return Type | Response Type |
| ----------- | ------------- |
| dict        | JSONResponse  |
| str         | HTMLResponse  |
| Response    | Used directly |

---

## 5️⃣ Dependency Injection (Depends)

```python
from zeefast.depends import Depends

def get_db():
    return "DB Connection"

@app.get("/items")
def read_items(db = Depends(get_db)):
    return {"db": db}
```

ZeeFast inspects function signature and executes dependencies automatically.

---

## 6️⃣ APIRouter (Route Groups)

```python
router = APIRouter(prefix="/api")

@router.get("/users")
def users():
    return ["A", "B"]

app.include_router(router)
```

Equivalent route:

```
/api/users
```

---

## 7️⃣ Middleware System

```python
@app.middleware
async def logger(request, call_next):
    print("Request:", request.path)
    response = await call_next(request)
    return response
```

Middleware wraps request → response pipeline.

---

## 8️⃣ Status Codes

```python
from zeefast.status import status

status.HTTP_200_OK
status.HTTP_404_NOT_FOUND
```

Based on Python `http.HTTPStatus`.

---

# 🧪 Example App

```python
from zeefast.app import ZeeFast

app = ZeeFast()

@app.get("/")
def home():
    return "Hello ZeeFast"

@app.get("/user/{id}")
def user(id: int):
    return {"id": id}

@app.get("/search")
def search(q: str, page: int = 1):
    return {"q": q, "page": page}
```

Run:

```bash
uvicorn test:app --reload
```

---

# 🎯 Goals of ZeeFast

* Learn how FastAPI internals work
* Learn ASGI protocol
* Learn routing internals
* Learn DI system design
* Learn middleware pipelines
* Build a micro framework from scratch

---

# ⚠️ Disclaimer

ZeeFast is **NOT production ready**.

Missing:

* Pydantic validation
* OpenAPI docs
* Security layers
* High-performance routing
* Async dependency graphs

This is purely an **educational framework**.

---

# 🧑‍💻 Author

**Zeeshan Aftab**
Software Engineering Student | AI & Backend Developer
Pakistan 🇵🇰

---

# ⭐ Future Roadmap

* [ ] Request body parsing (JSON, form, file upload)
* [ ] Pydantic-like validation
* [ ] OpenAPI schema generator
* [ ] WebSocket support
* [ ] Template engine (Jinja-like)
* [ ] CLI tool: `zeefast run app:app`

---

# 📜 License

MIT License

```
```

Made by Zeeshan Aftab