uv-demo PyPI package

A demo and template for a modern Python package managed by uv. Very useless as a package.

Use this as a template for new projects, or as a reference for how to set up a Python project with the following:

• uv as the Python package manager.
• pre-commit hooks for code formatting, linting, and quality checks.
• GitHub Actions for testing and publishing.
• Multiple Python versions tested with uv -p ${python-version} run pytest [...].
• gh-act for running GitHub Actions locally.
• Justfile with common recipes.
• Documentation with pdoc + GitHub Pages.
• Deptry to highlight missing and unused dependencies.

System Dependencies

• uv
  • curl -LsSf https://astral.sh/uv/install.sh | sh
• just
  • sudo apt install just
  • sudo pacman -S just
  • More installation methods.
• For running GitHub Actions locally
  • Docker
  • gh (GitHub CLI)
    • sudo pacman -S github-cli
    • Others
  • gh-act
    • gh extension install nektos/gh-act

Quick start

This will install all dependencies (uv sync) and run the entrypoint script:

uv run uv-demo

just Recipes

# just --list
Available recipes:
    list                      # List available recipes
    clean                     # Clean up generated files

    [dev]
    install                   # Install pre-commit hooks and development project dependencies with uv
    upgrade                   # Upgrade all project and pre-commit dependencies respecting pyproject.toml constraints [alias: update]
    pre-commit                # Run pre-commit hooks on all files [alias: check]
    deptry                    # Run deptry to check for unused and missing dependencies

    [build]
    build                     # Build the package and run tests
    publish                   # Build and publish the package to PyPI

    [test]
    test *pytest_args         # Simple execution of tests with coverage
    test-lowest *pytest_args  # runs tests with the lowest compatible versions of dependencies, to check compatibility issues
    test-verbose *pytest_args # Run tests with coverage and increased output
    test-all                  # Run static checker and tests for all compatible python versions
    serve-coverage            # Serve the coverage report with a simple HTTP server

    [docs]
    docs                      # Generate and serve documentation
    docs-gen                  # Generate documentation using pdoc
    docs-serve                # Serve the docs with a simple HTTP server

    [ci]
    gact                      # Run the GitHub Actions workflow for all branches
    gact-pull-request         # Run the GitHub Actions workflow for pull requests [alias: gact-pr]
    gact-release              # Run the GitHub Actions workflow for release

Integration with GitHub Actions

See the Upload Python Package workflow file for this package.

Running actions locally

You can use act to run GitHub Actions locally. Use cases:

1. While writing a workflow, to test the workflow locally before pushing to the repository.
2. Run the publishing workflow without setting secrets on GitHub.
3. Before opening a pull request, to check the workflow will pass.

Copy the example secrets file:

cp "config/secrets.env.example" "config/secrets.env"

Then edit the new file to add your secrets.

After that, run just gact to run the GitHub Actions workflow locally.