APSO Python Service Template

A FastAPI service template for APSO CLI with SQLAlchemy 2.0 and async support.

Stack

• Framework: FastAPI
• ORM: SQLAlchemy 2.0 (async)
• Validation: Pydantic v2
• Migrations: Alembic
• Database: PostgreSQL (asyncpg driver)

Project Structure

.
├── app/
│   ├── __init__.py
│   ├── main.py               # Application entry point
│   ├── database.py           # Database configuration
│   ├── autogen/              # Auto-generated code (DO NOT EDIT)
│   │   ├── models/           # SQLAlchemy models
│   │   ├── routers/          # FastAPI routers
│   │   ├── schemas/          # Pydantic schemas
│   │   └── services/         # Service layer
│   └── extensions/           # Custom/manual code
│       └── middleware/       # Custom middleware
├── tests/                    # Test files
├── alembic/                  # Database migrations
├── .apsorc                   # APSO configuration
├── .env.example              # Environment template
├── Dockerfile                # Docker build configuration
├── pyproject.toml            # Project configuration
└── README.md

Getting Started

Prerequisites

• Python 3.11+
• PostgreSQL database
• Docker (optional)

Local Development

1. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

   pip install -e ".[dev]"

3. Copy environment file:

   cp .env.example .env

4. Update .env with your database credentials.

5. Run the server:

   python -m app.main

   Or with uvicorn:

   uvicorn app.main:app --reload --host 0.0.0.0 --port 3000

Docker

Build and run with Docker:

docker build -t my-api .
docker run -p 3000:3000 --env-file .env my-api

API Documentation

Swagger documentation is available at: http://localhost:3000/_docs ReDoc documentation is available at: http://localhost:3000/_redoc

APSO CLI Integration

This template is designed to work with the APSO CLI. To add entities:

apso scaffold

The CLI will generate:

• Models in app/autogen/models/
• Schemas in app/autogen/schemas/
• Routers in app/autogen/routers/
• Services in app/autogen/services/

Extending the Template

Add custom code in the app/extensions/ folder:

• Custom middleware in app/extensions/middleware/
• Create additional folders as needed for your custom logic

Important: Never modify files in the app/autogen/ folder as they will be overwritten by the APSO CLI.

Database Migrations

Create a new migration:

alembic revision --autogenerate -m "Description of changes"

Apply migrations:

alembic upgrade head

Rollback one migration:

alembic downgrade -1

Testing

Run tests:

pytest

Run tests with coverage:

pytest --cov=app --cov-report=html

Code Quality

Format code:

black app tests

Lint code:

ruff check app tests

Type checking:

mypy app

License

MIT