panther: Instructions file for Codex

AGENTS.md

Project Overview

Panther is a Python 3.10+ async web framework focused on speed, simplicity, and practical API development. It is an ASGI framework with routing, request/response primitives, class-based and function-based APIs, OpenAPI support, WebSockets, middleware, authentication, permissions, throttling, caching, background tasks, templates, and database integrations.

When working in this repository, optimize for correctness first, then simplicity, then performance. Panther wants to stay small and fast, so prefer direct code paths and avoid adding abstraction unless it clearly reduces complexity.

Repository Map

• panther/ contains the framework source code.
• panther/main.py is the ASGI application entrypoint and request dispatcher.
• panther/app.py contains API and GenericAPI endpoint handling.
• panther/routings.py contains URL flattening, validation, and endpoint lookup.
• panther/request.py and panther/base_request.py define request parsing and request metadata.
• panther/response.py defines response classes, serialization, streaming, templates, redirects, and files.
• panther/db/ contains database connections, models, cursors, and query backends.
• panther/openapi/ contains OpenAPI schema and documentation views.
• panther/panel/ contains the built-in admin panel.
• panther/cli/ contains command-line tooling.
• tests/ contains the test suite.
• docs/docs/ contains documentation pages.
• examples/ contains example Panther applications.

Development Setup

Use Python 3.10 or newer.

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

Some tests need external services:

docker run --rm -p 27017:27017 -d --name mongo mongo
docker run --rm -p 6379:6379 -d --name redis redis

Test Commands

Prefer the project test runner because it runs test files individually for better isolation:

python tests

Useful variants:

python tests --not_mongodb
python tests --not_slow
python tests --not_mongodb --not_slow
python tests --mongodb
python tests --slow