Modern Python Project Template

A modern Python project template using recommended development tools and best practices.

TL;DR

Assuming that you have uv installed (version >=0.7.3)

1. uvx copier copy gh:tsvikas/python-template path/to/project/directory/

2. cd path/to/project/directory/

3. uvx --from rust-just just init

You can shorten these steps if you install copier and just.

Features

This template uses the best development tools while staying simple and uncluttered. Everything is designed to be opt-in, so you can use only what you need and ignore the rest until necessary. Sensible defaults for all included tools are provided.

Code Structure

• Follows modern project layout following best practices
• Optional: Command-line interface with Typer
• Optional: Easy logging with Loguru

Development Tools

• Task automation with Just command runner
• Python dependency management with uv (faster alternative to pip/poetry)
• Optional: Versioning management with uv-dynamic-versioning

Code Quality

• Testing framework with pytest
  • Coverage reports via pytest-coverage
  • Performance benchmarking with pytest-benchmark
  • Additional pytest plugins for a better testing experience
• Code formatting with Black or Ruff formatter
• Documentation formatting with blacken-docs
• Comprehensive linting with Ruff
  • Replaces Flake8, isort, pyupgrade, yesqa, pycln, and dozens of plugins
• Static type checking with MyPy
• Curated .gitignore file
• Formatting and linting run automatically on commit via pre-commit hooks:
  • EditorConfig for consistent formatting across editors
  • Spell checking with codespell and typos
  • Markdown formatting with Mdformat
  • Validation for JSON, TOML, XML, and YAML files
  • Linting for YAML, reStructuredText, and shell scripts
  • Schema checking for pyproject.toml and GitHub configuration files

CI/CD Integration

• Test automation with GitHub Actions
• Dependency updates with Dependabot

Documentation (Coming Soon)

• Documentation generation
• Automatic API documentation

Getting Started

Prerequisites

• git: Obviously.

• uv: After the template is used, this is the only requirement for development. Specifically, contributors to your project can use uv for building, testing, linting, and formatting. See the installation instructions.

• Copier: For the initial creation of the project from this template, and for pulling template updates, you need Copier. Install it with this command (requires uv):

  uv tool install copier

  The template uses copier's user defaults for your name and email.

• All the other developments tools are managed automatically by uv in your vertual environment, ensuring consistent versions across developers via Python's dependency-groups.

• just: Optional but recommended for running tasks with just <taskname> instead of uv run just <taskname>. See the installation instructions, or just run uv tool install rust-just.

• gh: GitHub CLI is not required to use this template, but it is recommended for interacting with GitHub.

Creating a New Project

• Generate a new project with:

copier copy gh:tsvikas/python-template ~/path/to/project/directory/

• Follow the interactive questionnaire to customize your project.
• from the project directory, run just init to initialize the project.

Developing Your Project

After creating your project, run those commands from the project directory:

• Run the test suite: just test
• Run linting and formatting: just lint and just format, or just check to run them both.

See the generated justfile for all available commands.

Contributing

I am excited to see this template being used. Feel free to suggest improvements or tell me about issues. Contributions and Pull Requests are welcome!