Template

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://git@github.com/Komorebi-AI/template.git@0.1.0

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