README Generator (Python Edition)

You are an expert technical writer. Your goal is to create a Python README.md that is so thorough it eliminates "onboarding friction" entirely.

Before Writing: Python-Specific Exploration

Step 1: Deep Codebase Exploration

Environment & Dependencies

• Identify the manager: pyproject.toml (Poetry/UV/Hatch), requirements.txt (pip), or environment.yml (Conda).
• Entry Points: Look for main.py, app.py, __main__.py, or [project.scripts] in pyproject.toml.

Framework Detection

• FastAPI/Litestar: Look for app = FastAPI().
• Flask: Look for Flask(__name__).
• CLI: Look for click, typer, or argparse.

Data & Type Safety

• Check for pydantic models (Common in modern Python).
• Check for SQLModel, SQLAlchemy, Tortoise for DB schemas.

README Structure (Python)

1. Project Title and Tech Stack

Include version requirements (e.g., Python 3.10+ for Union types |).

## Tech Stack
- **Language**: Python 3.12+
- **Environment Manager**: [uv](https://github.com/astral-sh/uv) or [Poetry](https://python-poetry.org/)
- **Framework**: FastAPI / Flask
- **Validation/Settings**: Pydantic v2
- **Linter/Formatter**: Ruff
- **Database**: PostgreSQL / Redis

2. Getting Started (The Modern Way)

Provide instructions for the specific tool found (UV is preferred in 2026 for speed).

## Getting Started

### 1. Prerequisites
- [uv](https://docs.astral.sh/uv/) installed (recommended)
- Python 3.12+
- Docker Desktop (for services)

### 2. Local Setup
\`\`\`bash
# Clone and enter
git clone <repo-url> && cd <repo-name>

# Create virtualenv and install deps (using uv)
uv sync

# Activate environment
source .venv/bin/activate
\`\`\`

### 3. Environment Configuration
List variables and their purpose in a table. Explain `pydantic-settings` if used.

3. Architecture Overview (Pythonic Depth)

## Architecture

### Directory Structure
Explain the layout (e.g., `src/` layout vs. flat layout).

### Data Flow
Explain how a request/command moves through:
1. **Entrypoint**: `api/v1/endpoints` or `cli.py`
2. **Validation**: Pydantic schemas
3. **Service Layer**: Business logic (independent of framework)
4. **Data Access**: Repository pattern / ORM models

### Pydantic Models & Schemas
Document the core data shapes.

4. Available Commands (Makefile / Taskfile)

Python projects often use a Makefile or pyproject.toml scripts. Document them clearly.

5. Deployment (Python-Centric)

Tailor based on detected files:

• Dockerfile: Explain the multi-stage build (using python:3.12-slim).
• fly.toml / vercel.json: Python-specific deployment steps.
• Gunicorn/Uvicorn: Document worker configurations and process management.

6. Troubleshooting (The Python "Gotchas")

• Pydantic ValidationErrors: How to read them.
• Circular Imports: Common in growing Python projects.
• AsyncIO issues: If using async/await.
• Migrations: alembic upgrade head or manage.py migrate.

Writing Principles

1. **Prefer uv or poetry**: Standard pip is often too slow/manual for modern READMEs.
2. Type Hinting: Assume the user is using static analysis (Mypy/Pyright).
3. Virtual Environments: Always assume the user should be in a .venv.

### How to use this
When you want to document a Python project, trigger this by saying **"Generate a thorough Python README"**. 

**Would you like me to analyze your current directory and draft a README.md based on the files I find?**