classapi 0.1.0

Add your description here

ClassApi

ClassApi is a small convenience layer on top of FastAPI that enables class-based views (CBV). It preserves FastAPI's features (typing, dependencies, automatic docs) while letting you organize handlers as classes.

Key features

• Use BaseView as a base class for handlers (get, post, put, ...).
• Support for pre_process and pre_<method> hooks to validate or transform requests.
• Register route modules by module path (supports relative module paths like .src.urls).
• Combined signatures from pre_process and the handler method are exposed to FastAPI for documentation and form generation.

Development setup (using uv helper)

1. Create a virtual environment:

python -m venv .venv

2. Use your uv helper to run pip inside the project environment and install dependencies:

uv run pip install fastapi uvicorn
# or install from requirements: uv run pip install -r requirements.txt

Quickstart Create main.py:

from classapi import ClassApi

app = ClassApi()

app.include_routers(".src.urls")

Example routes and views layout (tests/app_test/src):

# tests/app_test/src/urls.py
from .views import HelloWorldView

urls = [
	{"path": "/hello", "view": HelloWorldView}
]

# tests/app_test/src/views.py
from classapi import View, Header, HTTPException
from typing import Annotated

class ValidateUser(BaseView):
	def pre_process(self, jwt: Annotated[str | None, Header()] = None):
		if jwt != "valid_jwt":
			raise HTTPException(status_code=401, detail="Unauthorized")

class HelloWorldView(ValidateUser, BaseView):
	methods = ["GET"]

	def get(self, name: str = "World"):
		return {"Hello": name}

Supported urls formats

• Dict entries: {"path": "/x", "view": MyView, ...fastapi kwargs...} — extra kwargs (e.g. response_model) are forwarded to add_api_route.
• Tuple/list entries: ("/x", MyView).
• You may use relative imports from the calling module: app.include_routers(".src.urls").

View classes

• Define HTTP methods: get, post, put, delete, patch.
• Limit exposed methods with methods = ["GET"] on the class.
• Hooks:
  • pre_process(self, ...) — runs before any handler.
  • pre_get(self, ...), pre_post(...), ... — run before a specific handler.
• Signatures from pre_process, pre_<method> and the handler itself are merged and exposed to FastAPI; annotate parameters with Annotated[..., Header()], Cookie(), etc., to appear correctly in /docs.

Example: header extraction in pre_process:

def pre_process(self, jwt: Annotated[str|None, Header()] = None):
	...

If you accidentally place Annotated[...] as a default (e.g. jwt = Annotated[...]), ClassApi attempts to normalize it so FastAPI recognizes the dependency. Still, annotate parameters properly when possible.

Running the app

• Use uv to run the app with reload during development:

uv run uvicorn tests.app_test.main:app --reload

or, if you use the helper script test_init.py at the repository root:

uv run .\test_init.py

Debugging endpoint signatures If docs don't show expected parameters, you can inspect endpoint signatures at runtime:

for r in app.routes:
	print(r.path, getattr(r.endpoint, '__signature__', None))

Editor integration (VSCode / Pylance) Pylance is a static analyzer and doesn't pick up runtime-generated signatures. To get editor hovers that match your runtime docs, create a .pyi stub next to your views module describing the public signatures (this does not change runtime behavior).

Contributing

• Open issues or PRs.
• Add tests under tests/ and run them with pytest.

---

If you want, I can generate a views.pyi stub for your views, add example tests, or add a minimal pyproject.toml. Which should I do next?