python-app-setup

Python App Setup Skill

Defines the required setup conventions, project structure, and boilerplate rules for Python applications in this workspace.

Required Project Structure

All Python applications must adhere to the following file layout:

project/
├── .gitea/
│   └── workflows/
│       └── cicd.yaml
├── Dockerfile
├── docker-compose.yaml
├── version.ini
├── pyproject.toml
├── pytest.ini
├── openapi.yaml (required for FastAPI apps)
├── README.md
├── INSTALL.md
├── SYSTEM.md
├── alembic.ini (if database required)
├── app/
│   ├── __init__.py
│   └── main.py
├── alembic/ (if database required)
├── helm-chart/ (required for CI/CD Helm packaging)
└── tests/
    ├── __init__.py
    └── test_main.py

---

Architecture & Framework Requirements

1. Framework Selection

• FastAPI: Preferred for traditional REST APIs and HTTP microservices.
• FastMCP: Preferred for Model Context Protocol (MCP) servers (stdio/SSE transport).

2. OpenAPI Specification

• Generate an openapi.yaml file matching valid OpenAPI 3.x specification.
• For FastAPI apps:
  • Expose /openapi.yaml endpoint.
  • Enable Swagger UI at /docs.
• For FastMCP servers:
  • Document tool/resource schemas clearly; expose REST endpoints/OpenAPI spec if standard HTTP transport is enabled.

3. Docker & Container Registry Standards

• Base image: python:3.11-slim (or Python 3.11+).
• Use multi-stage builds for production images and include a container healthcheck.
• Default container port: 8000.
• CRITICAL: The final line of the Dockerfile MUST end with a comment referencing the team container registry:

  #harbor.freshbrewed.science/library/<app-name>
  

4. Version Configuration (version.ini)

• Include a root-level version.ini initialized to version 0.1:

  [version]
  version = 0.1
  

5. Database & Migrations (Alembic)

• If the application requires a database, use Alembic for schema migrations.
• Include alembic.ini and a populated alembic/ migration directory.