cdp-python-backend-template

This is work-in-progress. See To Do List

• cdp-python-backend-template
  • Requirements
    • Python
    • Linting and Formatting
    • Docker
  • Local development
    • Setup & Configuration
    • Development
    • Testing
    • Production Mode
  • API endpoints
  • Custom Cloudwatch Metrics
  • Pipelines
    • Dependabot
    • SonarCloud
  • Licence
    • About the licence

Requirements

Python

Please install python >= 3.12 and pipx in your environment. This template uses uv to manage the environment and dependencies.

# install uv via pipx
pipx install uv

# sync dependencies
uv sync

# source python venv
source .venv/bin/activate

# install the pre-commit hooks
pre-commit install

This opinionated template uses the Fast API Python API framework.

Environment Variable Configuration

The application uses Pydantic's BaseSettings for configuration management in app/config.py, automatically mapping environment variables to configuration fields.

In CDP, environment variables and secrets need to be set using CDP conventions. See links below:

• CDP App Config
• CDP Secrets

For local development - see instructions below.

Linting and Formatting

This project uses Ruff for linting and formatting Python code.

Running Ruff

To run Ruff from the command line:

# Run linting with auto-fix
uv run ruff check . --fix

# Run formatting
uv run ruff format .

Pre-commit Hooks

This project uses pre-commit to run linting and formatting checks automatically before each commit.

The pre-commit configuration is defined in .pre-commit-config.yaml

To set up pre-commit hooks:

# Set up the git hooks
pre-commit install

To run the hooks manually on all files:

pre-commit run --all-files

VS Code Configuration

For the best development experience, configure VS Code to use Ruff:

1. Install the Ruff extension for VS Code
2. Configure your VS Code settings (.vscode/settings.json):

{
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.fixAll.ruff": "explicit",
        "source.organizeImports.ruff": "explicit"
    },
    "ruff.lint.run": "onSave",
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    }
}

This configuration will:

• Format your code with Ruff when you save a file
• Fix linting issues automatically when possible
• Organize imports according to isort rules

Ruff Configuration

Ruff is configured in the .ruff.toml file

Docker

This repository uses Docker throughput its lifecycle i.e. both for local development and the environments. A benefit of this is that environment variables & secrets are managed consistently throughout the lifecycle

See the Dockerfile and compose.yml for details

Local development

Setup & Configuration

Follow the convention below for environment variables and secrets in local development.

Note that it does not use .env or python-dotenv as this is not the convention in the CDP environment.

Environment variables: compose/aws.env.

Secrets: compose/secrets.env. You need to create this, as it's excluded from version control.

Libraries: Ensure the python virtual environment is configured and libraries are installed using uv sync, as above

Pre-Commit Hooks: Ensure you install the pre-commit hooks, as above

Development

This app can be run locally by either using the Docker Compose project or via the provided script scripts/start_dev_server.sh.

Using Docker Compose

To run the application using Docker Compose, you can use the following command:

docker compose --profile service up --build

If you want to enable hot-reloading, you can press the w key once the compose project is running to enable watch mode.

Using the provided script

To run the application using the provided script, you can execute:

./scripts/start_dev_server.sh

This script will:

• Check if Docker is running
• Start dependent services with Docker Compose (Localstack, MongoDB)
• Set up environment variables for local development
• Load configuration from compose/aws.env and compose/secrets.env
• Verify the Python virtual environment is set up
• Start the FastAPI application with hot-reload enabled

The service will then run on http://localhost:8085

Testing

Ensure the python virtual environment is configured and libraries are installed using uv sync, as above

Testing follows the FastApi documented approach; using pytest & starlette.

To test the application run:

uv run pytest

API endpoints

Endpoint	Description
GET: /docs	Automatic API Swagger docs
GET: /health	Health check endpoint
GET: /example/test	Simple example endpoint
GET: /example/db	Database query example
GET: /example/http	HTTP client example

Custom Cloudwatch Metrics

Uses the aws embedded metrics library. An example can be found in metrics.py

In order to make this library work in the environments, the environment variable AWS_EMF_ENVIRONMENT=local is set in the app config. This tells the library to use the local cloudwatch agent that has been configured in CDP, and uses the environment variables set up in CDP AWS_EMF_AGENT_ENDPOINT, AWS_EMF_LOG_GROUP_NAME, AWS_EMF_LOG_STREAM_NAME, AWS_EMF_NAMESPACE, AWS_EMF_SERVICE_NAME

Pipelines

Dependabot

We have added an example dependabot configuration file to the repository. You can enable it by renaming the .github/example.dependabot.yml to .github/dependabot.yml

SonarCloud

Instructions for setting up SonarCloud can be found in sonar-project.properties

Licence

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the licence

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.