Skip to content
/ python-template Public template

A template for Python repositories using Docker

Notifications You must be signed in to change notification settings

Komorebi-AI/python-template

Repository files navigation

Template

testing workflow Checked with mypy pre-commit

Template for Python libraries and applications with Docker packaging. The associated development guide can be found here.

Structure

The repository is structured into the following directories:

  • /template: Python source code
  • /tests: Python code for testing via pytest
  • /data: data folder

Conveniently, a set of workflows via Github Actions are already installed:

  • pre-commit: run pre-commit hooks
  • pytest: automatically discover and runs tests in tests/

Tools:

  • uv: manage dependencies, Python versions and virtual environments
  • ruff: lint and format Python code
  • mypy: check types
  • pytest: run unit tests
  • pre-commit: manage pre-commit hooks
  • prettier: format YAML and Markdown
  • codespell: check spelling in source code

Installation

Application

Install package and pinned dependencies with the uv package manager:

  1. Install uv. See instructions for Windows, Linux or MacOS here.

  2. Clone repository

  3. Install package and dependencies in a virtual environment:

    uv sync
    
  4. Run any command or Python script with uv run, for instance:

    uv run template/main.py
    

    Alternatively, you can also activate the virtual env and run the scripts normally:

    source .venv/bin/activate
    

Library

Install a specific version of the package with pip or uv pip:

pip install git+ssh://[email protected]/Komorebi-AI/[email protected]

Setup development environment (Unix)

Install uv and pre-commit hooks:

make install

uv will automatically create a virtual environment with the specified Python version in .python-version and install the dependencies from uv.lock (both standard and dev dependencies). It will also install the package in editable mode.

Adding new dependencies

Add dependencies with:

uv add <PACKAGE>

Add dev dependencies with:

uv add --dev <PACKAGE>

Remove dependency with:

uv remove <PACKAGE>

In all cases uv will automatically update the uv.lock file and sync the virtual environment. This can also be done manually with:

uv sync

Tools

Run pre-commit hooks

Hooks are run on modified files before any commit. To run them manually on all files use:

make hooks

Run linter and formatter

make ruff

Run tests

make test

Run type checker

make mypy