Python Template

This is a template project for Python, designed to streamline the creation of Python projects using (What I think are) best practices.

Table of Contents

• Features
• Getting Started
• CI/CD Workflow
  • Workflow File
• Dependencies
  • Optional: Pyenv
• Code Quality
• Pre-commit Hooks
  • Pre-commit Hooks Configuration
  • Run the Hooks Locally
• License

Features

• Code formatting and linting using Ruff.
• Type checking with Mypy.
• Pre-commit hooks to maintain code quality.

Getting Started

Follow these steps to get started with this template:

1. Clone the repository or use the template directly via GitHub.

2. Install Poetry:

   Ensure you have Poetry installed. If not, you can install it using:

   pip install poetry

   Note: This template is set up using Poetry version 1.8.5.

3. Install dependencies:

   poetry install

4. Ready to Implement:

   You are now ready to implement your project. Keep in mind that this is a base template and not a fully functioning application.

CI/CD Workflow

This project includes a continuous integration (CI) workflow that is triggered on every push and pull request, using GitHub Actions to run the following jobs:

1. Setup: Checks out the code, sets up Python, and installs dependencies using Poetry.
2. Format: Formats the code with Ruff.
3. Lint: Runs linting on the codebase with Ruff.
4. Type Check: Checks for type consistency using Mypy.
5. Create Release: Automatically creates a GitHub release when code is pushed to the main branch.

Workflow File

The main CI workflow is defined in .github/workflows/main.yml.

Note: This workflow will only create a release tag based on your pyproject.toml version number. If the version has not been bumped, it will not create a new release.

Dependencies

This project includes the following dependencies:

• Core Dependencies:

  • python: ^3.13 (switch the .python-version file to your liking)
  • loguru: ^0.7.3 (useful logging package)

• Development Dependencies:

  • ruff: ^0.8.x (for code linting and formatting)
  • mypy: ^1.x.y (for type checking)
  • pre-commit: ^4.x.y (for managing Git hooks)
  • pytest: ^8.x.y (for unit testing)

Optional: Pyenv

Useful pyenv commands

Updating pyenv will refresh the Python mirrors to find the latest Python versions available:

pyenv update

List all available Python versions:

pyenv install --list

Download & install a specific Python version:

pyenv install 3.13.3

List the global Python version set by your system:

pyenv global

List the Python version set for your project/folder:

pyenv local

Set the global Python version for your system:

pyenv global 3.13.3

Set the local Python version for your project:

pyenv local 3.13.3

Feel free to utilize Pyenv and modify the .python-version file to your preference.

Code Quality

This repository employs several tools to ensure code quality:

• Ruff: A fast Python linter and formatter that enforces a consistent style and detects potential errors.
• Mypy: A static type checker for Python that ensures type safety.

Pre-commit Hooks

To set up pre-commit hooks for automatic formatting and linting on commit, ensure pre-commit is installed:

poetry install

Then, install the hooks:

poetry run pre-commit install

Once installed, the hooks will run automatically before each commit.

Pre-commit Hooks Configuration

This repository uses pre-commit hooks to enforce code quality and standards before committing changes. Here’s an overview of the configured hooks:

1. Commitlint Hook

• Purpose: Ensures commit messages adhere to defined conventions for consistency and clarity.

2. Local Hooks

• Ruff Format: Automatically formats Python code according to specified rules.
• Ruff Lint: Performs linting to catch potential errors and maintain coding standards.
• Mypy Type Check: Checks type annotations for consistency and correctness in Python code.
• Pytest: Runs the tests found in the /tests folder.

Run the Hooks Locally

You can run specific hooks manually using:

poetry run pre-commit run <HOOK-ID>

For example, to run the Ruff formatter:

poetry run pre-commit run ruff-format

For more information on pre-commit, visit pre-commit.com.

License

This project is licensed under the MIT License. See the LICENSE file for details.