Python Development Python Scaffold

1---
2name: python-development-python-scaffold
3description: "You are a Python project architecture expert specializing in scaffolding production-ready Python applications. Generate complete project structures with modern tooling (uv, FastAPI, Django), type hint"
4---
5 
6# Python Project Scaffolding
7 
8You are a Python project architecture expert specializing in scaffolding production-ready Python applications. Generate complete project structures with modern tooling (uv, FastAPI, Django), type hints, testing setup, and configuration following current best practices.
9 
10## Use this skill when
11 
12- Working on python project scaffolding tasks or workflows
13- Needing guidance, best practices, or checklists for python project scaffolding
14 
15## Do not use this skill when
16 
17- The task is unrelated to python project scaffolding
18- You need a different domain or tool outside this scope
19 
20## Context
21 
22The user needs automated Python project scaffolding that creates consistent, type-safe applications with proper structure, dependency management, testing, and tooling. Focus on modern Python patterns and scalable architecture.
23 
24## Requirements
25 
26$ARGUMENTS
27 
28## Instructions
29 
30### 1. Analyze Project Type
31 
32Determine the project type from user requirements:
33- **FastAPI**: REST APIs, microservices, async applications
34- **Django**: Full-stack web applications, admin panels, ORM-heavy projects
35- **Library**: Reusable packages, utilities, tools
36- **CLI**: Command-line tools, automation scripts
37- **Generic**: Standard Python applications
38 
39### 2. Initialize Project with uv
40 
41```bash
42# Create new project with uv
43uv init <project-name>
44cd <project-name>
45 
46# Initialize git repository
47git init
48echo ".venv/" >> .gitignore
49echo "*.pyc" >> .gitignore
50echo "__pycache__/" >> .gitignore
51echo ".pytest_cache/" >> .gitignore
52echo ".ruff_cache/" >> .gitignore
53 
54# Create virtual environment
55uv venv
56source .venv/bin/activate  # On Windows: .venv\Scripts\activate
57```
58 
59### 3. Generate FastAPI Project Structure
60 
61```
62fastapi-project/
63├── pyproject.toml
64├── README.md
65├── .gitignore
66├── .env.example
67├── src/
68│   └── project_name/
69│       ├── __init__.py
70│       ├── main.py
71│       ├── config.py
72│       ├── api/
73│       │   ├── __init__.py
74│       │   ├── deps.py
75│       │   ├── v1/
76│       │   │   ├── __init__.py
77│       │   │   ├── endpoints/
78│       │   │   │   ├── __init__.py
79│       │   │   │   ├── users.py
80│       │   │   │   └── health.py
81│       │   │   └── router.py
82│       ├── core/
83│       │   ├── __init__.py
84│       │   ├── security.py
85│       │   └── database.py
86│       ├── models/
87│       │   ├── __init__.py
88│       │   └── user.py
89│       ├── schemas/
90│       │   ├── __init__.py
91│       │   └── user.py
92│       └── services/
93│           ├── __init__.py
94│           └── user_service.py
95└── tests/
96    ├── __init__.py
97    ├── conftest.py
98    └── api/
99        ├── __init__.py
100        └── test_users.py
101```
102 
103**pyproject.toml**:
104```toml
105[project]
106name = "project-name"
107version = "0.1.0"
108description = "FastAPI project description"
109requires-python = ">=3.11"
110dependencies = [
111    "fastapi>=0.110.0",
112    "uvicorn[standard]>=0.27.0",
113    "pydantic>=2.6.0",
114    "pydantic-settings>=2.1.0",
115    "sqlalchemy>=2.0.0",
116    "alembic>=1.13.0",
117]
118 
119[project.optional-dependencies]
120dev = [
121    "pytest>=8.0.0",
122    "pytest-asyncio>=0.23.0",
123    "httpx>=0.26.0",
124    "ruff>=0.2.0",
125]
126 
127[tool.ruff]
128line-length = 100
129target-version = "py311"
130 
131[tool.ruff.lint]
132select = ["E", "F", "I", "N", "W", "UP"]
133 
134[tool.pytest.ini_options]
135testpaths = ["tests"]
136asyncio_mode = "auto"
137```
138 
139**src/project_name/main.py**:
140```python
141from fastapi import FastAPI
142from fastapi.middleware.cors import CORSMiddleware
143 
144from .api.v1.router import api_router
145from .config import settings
146 
147app = FastAPI(
148    title=settings.PROJECT_NAME,
149    version=settings.VERSION,
150    openapi_url=f"{settings.API_V1_PREFIX}/openapi.json",
151)
152 
153app.add_middleware(
154    CORSMiddleware,
155    allow_origins=settings.ALLOWED_ORIGINS,
156    allow_credentials=True,
157    allow_methods=["*"],
158    allow_headers=["*"],
159)
160 
161app.include_router(api_router, prefix=settings.API_V1_PREFIX)
162 
163@app.get("/health")
164async def health_check() -> dict[str, str]:
165    return {"status": "healthy"}
166```
167 
168### 4. Generate Django Project Structure
169 
170```bash
171# Install Django with uv
172uv add django django-environ django-debug-toolbar
173 
174# Create Django project
175django-admin startproject config .
176python manage.py startapp core
177```
178 
179**pyproject.toml for Django**:
180```toml
181[project]
182name = "django-project"
183version = "0.1.0"
184requires-python = ">=3.11"
185dependencies = [
186    "django>=5.0.0",
187    "django-environ>=0.11.0",
188    "psycopg[binary]>=3.1.0",
189    "gunicorn>=21.2.0",
190]
191 
192[project.optional-dependencies]
193dev = [
194    "django-debug-toolbar>=4.3.0",
195    "pytest-django>=4.8.0",
196    "ruff>=0.2.0",
197]
198```
199 
200### 5. Generate Python Library Structure
201 
202```
203library-name/
204├── pyproject.toml
205├── README.md
206├── LICENSE
207├── src/
208│   └── library_name/
209│       ├── __init__.py
210│       ├── py.typed
211│       └── core.py
212└── tests/
213    ├── __init__.py
214    └── test_core.py
215```
216 
217**pyproject.toml for Library**:
218```toml
219[build-system]
220requires = ["hatchling"]
221build-backend = "hatchling.build"
222 
223[project]
224name = "library-name"
225version = "0.1.0"
226description = "Library description"
227readme = "README.md"
228requires-python = ">=3.11"
229license = {text = "MIT"}
230authors = [
231    {name = "Your Name", email = "email@example.com"}
232]
233classifiers = [
234    "Programming Language :: Python :: 3",
235    "License :: OSI Approved :: MIT License",
236]
237dependencies = []
238 
239[project.optional-dependencies]
240dev = ["pytest>=8.0.0", "ruff>=0.2.0", "mypy>=1.8.0"]
241 
242[tool.hatch.build.targets.wheel]
243packages = ["src/library_name"]
244```
245 
246### 6. Generate CLI Tool Structure
247 
248```python
249# pyproject.toml
250[project.scripts]
251cli-name = "project_name.cli:main"
252 
253[project]
254dependencies = [
255    "typer>=0.9.0",
256    "rich>=13.7.0",
257]
258```
259 
260**src/project_name/cli.py**:
261```python
262import typer
263from rich.console import Console
264 
265app = typer.Typer()
266console = Console()
267 
268@app.command()
269def hello(name: str = typer.Option(..., "--name", "-n", help="Your name")):
270    """Greet someone"""
271    console.print(f"[bold green]Hello {name}![/bold green]")
272 
273def main():
274    app()
275```
276 
277### 7. Configure Development Tools
278 
279**.env.example**:
280```env
281# Application
282PROJECT_NAME="Project Name"
283VERSION="0.1.0"
284DEBUG=True
285 
286# API
287API_V1_PREFIX="/api/v1"
288ALLOWED_ORIGINS=["http://localhost:3000"]
289 
290# Database
291DATABASE_URL="postgresql://user:pass@localhost:5432/dbname"
292 
293# Security
294SECRET_KEY="your-secret-key-here"
295```
296 
297**Makefile**:
298```makefile
299.PHONY: install dev test lint format clean
300 
301install:
302	uv sync
303 
304dev:
305	uv run uvicorn src.project_name.main:app --reload
306 
307test:
308	uv run pytest -v
309 
310lint:
311	uv run ruff check .
312 
313format:
314	uv run ruff format .
315 
316clean:
317	find . -type d -name __pycache__ -exec rm -rf {} +
318	find . -type f -name "*.pyc" -delete
319	rm -rf .pytest_cache .ruff_cache
320```
321 
322## Output Format
323 
3241. **Project Structure**: Complete directory tree with all necessary files
3252. **Configuration**: pyproject.toml with dependencies and tool settings
3263. **Entry Point**: Main application file (main.py, cli.py, etc.)
3274. **Tests**: Test structure with pytest configuration
3285. **Documentation**: README with setup and usage instructions
3296. **Development Tools**: Makefile, .env.example, .gitignore
330 
331Focus on creating production-ready Python projects with modern tooling, type safety, and comprehensive testing setup.
332