template-python

This is a template repository for Python

Prerequisites

• Python 3.10+ (CI tests 3.10 through 3.14)
• uv 0.12.19
• GNU Make
• actionlint for local lint/CI checks (CI uses v1.7.12)
• Docker for the Docker targets

Development instructions

Local development

Use Makefile to run the project locally.

# help
make

# install dependencies for development
make install-deps-dev

# check all configured hooks
make hooks-check

# run tests
make test

# run CI tests
make ci-test

# build the English and Japanese documentation
make ci-test-docs

# launch JupyterLab
make jupyterlab

make install-deps-dev installs all development groups and installs the prek Git hook, replacing a previously installed pre-commit hook. CI uses a smaller dependency set without JupyterLab; the notebook group remains available through make jupyterlab. make lint also runs an offline zizmor check that blocks high-severity GitHub Actions configuration findings. Run uv run --locked zizmor --offline . to review lower-severity findings as well.

Docker development

# build docker image
make docker-build

# run docker container
make docker-run

# run CI tests in docker container
make ci-test-docker

The Docker CI target lints, builds, scans, and runs the image. The Trivy scan currently reports vulnerabilities without failing the build; review its findings before enabling a blocking severity threshold.

The documentation uses Material for MkDocs with mkdocs-static-i18n to publish both languages. A switch to Zensical requires equivalent multilingual output; unsupported MkDocs plugins are not run by Zensical.

Deployment instructions

Docker Hub

To publish the docker image to Docker Hub, you need to create access token and set the following secrets in the repository settings.

gh secret set DOCKERHUB_USERNAME --body $DOCKERHUB_USERNAME
gh secret set DOCKERHUB_TOKEN --body $DOCKERHUB_TOKEN

Azure Static Web Apps

RESOURCE_GROUP_NAME=your-resource-group-name
SWA_NAME=your-static-web-app-name

# Create a static app
az staticwebapp create --name $SWA_NAME --resource-group $RESOURCE_GROUP_NAME

# Retrieve the API key
AZURE_STATIC_WEB_APPS_API_TOKEN=$(az staticwebapp secrets list --name $SWA_NAME --query "properties.apiKey" -o tsv)

# Set the API key as a GitHub secret
gh secret set AZURE_STATIC_WEB_APPS_API_TOKEN --body $AZURE_STATIC_WEB_APPS_API_TOKEN

Refer to the following links for more information:

• Deploying to Azure Static Web App
• Create a static web app: az staticwebapp create