Modern Python Project Template

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

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 with the copier_templates_extensions package. Install it with this command (requires uv):

  uv tool install copier --with copier_templates_extensions

• 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.

• 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 --trust 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!