Python Boilerplate

Lightweight Python project scaffold with:

• environment configuration via pydantic-settings
• SQLAlchemy database base/session wiring
• Docker-ready runtime image

Tech Stack

• Python 3.12
• pydantic / pydantic-settings
• sqlalchemy + psycopg
• alembic (dependency included)

Project Structure

.
├── app/
│   ├── constants/
│   ├── dependencies.py
│   ├── events/
│   ├── exceptions/
│   ├── models/
│   ├── schemas/
│   ├── services/
│   ├── tasks/
│   └── utils/
├── config/
│   ├── app.py
│   └── database.py
├── main.py
├── requirements.txt
└── Dockerfile

Prerequisites

• Python 3.12+
• pip
• Docker (optional)
• PostgreSQL (if using config/database.py)

Local Setup

1. Create a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate

2. Install dependencies:

   pip install -r requirements.txt

3. Configure environment:

   cp .env.example .env

4. Run the app:

   python main.py

Environment Variables

Current .env.example contains:

APP_NAME=APP_NAME
APP_ENV=local
LOG_LEVEL=INFO

config/database.py also expects these DB values:

DB_HOST=localhost
DB_PORT=5432
DB_DATABASE=app
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_SCHEMA=public

If you plan to use DB utilities, add these variables to .env and define matching fields in config/app.py (Settings class).

Docker

Build image:

docker build -t python-boilerplate .

Run container:

docker run --rm --env-file .env python-boilerplate

The container entrypoint runs:

python main.py

Notes

• main.py is currently empty; add your application entrypoint there.
• alembic is installed but migration config/files are not scaffolded yet.