py-manage

A personal, opinionated guide to managing Python projects. This guide originally recommended using pyenv, pipx, and poetry for managing Python projects. However, with the advent and continued development of uv, it is now the preferred tool.

Additional literature can be found below:

• "Python Project Management Primer Revisited".
• "Python Project Management Primer".
• "Optimizing Docker Images for Python Production Services".

Table of Contents

1. Tooling
2. Dockerfile Optimizations
3. Standard Project Structure
4. Mono-Repository Structure
5. Workflows
   1. Starting a New Project
   2. Installing an Existing Project
   3. Developing Locally
   4. Building Docker Images
   5. Running Docker Containers Locally
   6. CI/CD

Tooling

• Use uv to manage Python versions, install and run tools in isolation, and handle project dependencies and packaging.
• [minor] use ruff as a linter/formatter.

Dockerfile Optimizations

This guide recommends the following techniques:

• Multi-stage builds:
• • To parallelize builds to increase speed.
• • To separate build and runtime stages to reduce final image size.
• Effective cache utilization to speed-up build times by:
• • Positioning expensive layers early.
• • Placing frequently changing layers last.
• • Keeping layers small (including only necessary files and dependencies).
• • Minimizing layer count.

Examples could be found in both, standard and monorepo structures.

Standard Project Structure

For details on the standard project structure, refer to the standard structure documentation.

Mono-Repository Structure

For details on the mono-repository structure, refer to the mono-repository structure documentation.

Workflows

• Installing Python.
• Using tools.
• Working on projects.
• Publishing a package.
• Using uv in Docker.
• Using uv in GitHub Actions.

Building Docker Images

Follow these steps to build Docker images for services:

# Inside the service directory
export IMAGE_TAG=python-service-x
docker build -f Dockerfile -t $IMAGE_TAG .

Running Docker Containers Locally

Follow these steps to run Docker containers locally:

# Be sure to have built the Docker image before
export IMAGE_TAG=python-service-x
docker run -p 8080:8080 --name local $IMAGE_TAG

CI/CD

For details on CI/CD workflows, refer to the respective documentation:

• Standard structure CI/CD workflows.
• Mono-repository structure CI/CD workflows.