A demo repository showcasing Python project development and packaging best practices using uv. This project demonstrates project structure, dependency management, containerization with Docker and automated code quality, security scanning and deployment workflows using GitHub Actions (GHA).

Table of Contents

• Project Overview
• Getting Started
• Development Setup
• Development Workflow
• Documentation
• Acknowledgements
• License

This repository serves as a demonstration and learning resource. To use this as a template for new projects, refer to the setup guide in the documentation.

• Python packaging:
  • Dependency management with uv
  • Automated versioning using setuptools-scm
• GHA workflows for CI/CD and security:
  • Code quality checks with pre-commit, ruff, mypy, and pytest
  • Security scans with Safety, CodeQL, Dependabot, and Zizmor
  • Python package deployment to Test PyPI
  • Container image deployment to GitHub Container Registry
• Developer tools: VS Code integration, development containers, Taskfile automation

• .github/workflows - GHA for CI/CD pipelines, security scanning and dependency updates (see GitHub Actions Workflows).
• pyproject.toml - Python package config, dependencies, and build settings
• Taskfile.yml - Automated tasks for setting up the dev environment, running code quality checks and more. Run task help to see all available tasks or refer to the Command Cheatsheet.

Full overview of the repository structure is available in the Repository Structure documentation.

Job	Status	Description
CI Python		Code quality checks, testing, coverage
CD Python		Package deployment to Test PyPI
CI Docker		Build and test Docker image
CD Docker		Container deployment to GitHub Registry
Security Scan - Safety		Python dependency vulnerability scanning
Security Scan - CodeQL		Python and GHA security analysis
Security Scan - Zizmor		GHA workflow security scan
Dependabot		Automated dependency updates

Results of the security scans are visible in the Security tab of the GitHub repository.

The uv-demo package is a minimal package with a single function that prints the package name. You can install this package from Test PyPI or pull the containerized version from GHCR. The main purpose of this repository is to explore development tools and observe the CI/CD pipeline in action. To get started, follow the steps in the Development Workflow section.

Install the demo package from Test PyPI:

pip install -i https://test.pypi.org/simple/ uv-demo

import uv_demo
uv_demo.main()
# > Hello from uv-demo!
# > Version: 0.0.1

Or pull and run the container:

docker pull ghcr.io/ac-willeke/uv-demo:latest

docker run --rm ghcr.io/ac-willeke/uv-demo:latest
# > Hello from uv-demo!
# > Version: 0.0.1

The following steps configure your development environment using VS Code Dev Containers. For local setup without containers, refer to the setup guide in the documentation.

• Docker
• Visual Studio Code
• VS Code Dev Containers extension

1. Open the project: Clone and open the project folder in VS Code or use GitHub Codespaces.

2. Start the devcontainer: When prompted, reopen the folder in the Devcontainer. If not prompted, manually trigger it via the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and select "Dev Containers: Reopen in Container".

3. Automatic setup: The devcontainer automatically:

   • Configures VS Code with recommended settings and extensions per devcontainer.json
   • Installs development tools: Git, uv, pre-commit, Task
   • Sets up the Python environment with dependencies in .venv via task dev-setup, which runs uv sync --dev and executes code quality checks and test coverage

4. Test the installation with Task commands:

   Task is used to automate common development tasks (see Taskfile.yml).

   # Test the package
   task run
   # or
   uv run uv-demo
   
   # Run quality checks
   task check
   
   # Run local CI workflow
   task ci-local
   
   # Clean up
   task clean

5. Test the notebook: Open notebooks/demo.ipynb and select the .venv kernel. If you have problems activating the .venv refer to the setup guide.

6. Configure the GitHub Repository: If you fork this repository or use it to create your a new repository from scratch, you'll need to configure your GitHub repository to connect with Test PyPI, Safety and Code Coverage. Also, verify that your security scans are properly set up. See the GitHub Repository Configuration section in the setup guide for instructions.

Follow PEP8, use type hints, and include docstrings in reStructuredText format. All quality checks are automated through Task commands, pre-commit hooks and CI workflows.

See the Code Quality and Security Standards guide to see which rules are enforced in this repo.

The repository includes automated workflows for code quality, security, and deployment:

The demo workflows can be customized or removed based on your specific project requirements. At minimum, I recommend including the CI Python workflow for code quality and testing, as well as the Security workflows: CodeQL, Safety, and Zizmor.

Use these commands for local development and testing:

# Setup and quality checks
task install          # Install dependencies and setup environment
task check            # Run all quality checks
task ci-local         # Simulate CI pipeline locally

# Testing and running
task test             # Run test suite
task run              # Run the demo package
task run-docker       # Run in Docker container

# Code formatting and security
task format           # Format code with ruff
task security         # Run security scans

For more commands see: Command Cheatsheet

The main branch is protected with the following rules:

• Require pull request reviews before merging
• Require status checks to pass before merging
• Require branches to be up to date before merging

This project incorporates best practices from the Python and DevOps communities, including:

• Astral-sh's uv Documentation and Docker configuration example astral-sh/uv-docker-example
• Eric Riddoch's Taking Python to Production course
• Marvelous MLOps MLOps with Databricks course

This project is licensed under the MIT License - see the LICENSE file for details.