Home

Welcome to our opinionated Template Python Repository. This repository is aimed at providing a ready-to-go template for Python packages and applications. In this document, we provide detailed explanations for our choice of tools, highlighting their benefits and functionalities. Additionally, we include links for further reading, enabling you to delve deeper into the capabilities and features of these tools.

Package Manager: Poetry

In our template, we've opted for Poetry as our preferred Python package manager, among others like pip, conda, and pipenv. Our choice leans towards Poetry because it seamlessly integrates the creation of dependency files (pyproject.toml, poetry.lock) with the setup of virtual environments. This integration offers a key advantage: it ensures consistency between your virtual environment and your dependency files, eliminating the chance of divergence. Consequently, this facilitates maintaining uniform virtual environments among team members and provides a version-controlled record of specific package versions used throughout the project's history.

While Poetry is our primary choice, we acknowledge a specific scenario where Conda might be more suitable. Since Poetry limits installations to packages available on PyPi or Git repositories, it can't access some packages that are exclusive to Conda. In situations where these exclusive packages are required, transitioning to Conda would be the practical solution.

Code formatting: Ruff

Ruff is a code formatter that coalesces the checks of many other tools (e.g. black, isort, flake8) into a single tool. It can check correctness of your docstrings, import sorting, code styling and various other things. Ruff is exceptionally fast, making it a great tool even in large projects. We utilize Ruff primarily to guarantee a consistent coding style across our projects, leveraging its wide-ranging checks and rapid performance to maintain high-quality code standards.

Type checking: Mypy

Have you ever encountered the issue of attempting to add an element to a list, only to later discover that the variable in question was, in fact, a tuple? Mistakes related to incorrect data types are common in programming and can be challenging to detect manually. This is where type hinting and Mypy come into play. By adding type hints to your code, you enable Mypy to accurately determine the intended data type for each variable. Mypy then thoroughly analyzes your codebase, identifying and flagging any errors that stem from type mismatches. This process enhances the reliability and accuracy of your code, ensuring that such common yet elusive errors are caught and rectified promptly.

Ensuring consistent commits: pre-commit

Pre-commit is a tool that evaluates files before they are allowed to be committed to a repository. This tool offers an array of pre-configured actions that can be effortlessly incorporated into .pre-commit.config.yaml. Additionally, it allows for the creation of custom actions through scripts housed within the repository. Typically, we employ pre-commit actions to maintain a uniform coding style across our projects. The pre-configured tools include Ruff for code formatting, MyPy as a type checker, several generic hooks for uniform formatting of non-python files, and a check to ensure consistency in the extension of all .yaml files.