Skip to content

README.md

Latest commit

 

History

History
194 lines (128 loc) · 5.08 KB

README.md

File metadata and controls

194 lines (128 loc) · 5.08 KB

Python Template

Build Status License GitHub release (latest by date)

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

  • 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 uv:

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

    curl -LsSf https://astral.sh/uv/install.sh | sh

  3. Install dependencies:

    uv sync

  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 uv.
  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.14 (switch the .python-version file to your liking)
    • loguru: ^0.7.3 (useful logging package)

  • Development Dependencies:

    • ruff: ^0.14.x (for code linting and formatting)
    • mypy: ^1.x.y (for type checking)
    • pre-commit: ^4.x.y (for managing Git hooks)
    • pytest: ^9.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.14.2

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

Set the local Python version for your project:

pyenv local 3.14.2

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:

uv sync

Then, install the hooks:

uv 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:

uv run pre-commit run <HOOK-ID>

For example, to run the Ruff formatter:

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