Python Starter

A minimalist template for starting a new Python project.

This template provides a basic Python project containing an example package with built-in support for formatting, linting, testing, and continuous integration.

Key Features

• Uses uv as the package manager.
• Supports formatting and linting with Ruff, and testing with Pytest.
• Fixes formatting and linting during pre-commit hooks using Lefthook.
• Preconfigured workflows for Dependabot and GitHub Actions.

Usage

This guide explains how to use this template to start a new Python project, from creation to release.

Create a New Project

Follow this link to create a new project based on this template. For more information about creating a repository from a template on GitHub, refer to this documentation.

Alternatively, you can clone this repository locally to begin using this template.

Set Up Tools

Set Up Package Manager

This template uses uv as the package manager. If uv is not installed, follow this guide to install it. Then, synchronize the project dependencies with:

uv sync

For more information on uv, including adding dependencies or running tools, refer to this documentation.

Set Up Git Hooks

This template uses Lefthook to manage Git hooks, especially for the pre-commit hook. Lefthook will be installed as a development dependency by the package manager, and the pre-commit hook can be installed with:

uv run lefthook install

After that, each commit to the project will trigger a hook that checks for formatting and linting. This ensures that committed files follow the specified rules.

For more information on Lefthook and how it manages hooks, refer to this documentation.

Developing the Project

Choose a License

By default, this template is unlicensed. Before modifying this template, it is recommended to replace the LICENSE file with the license that will be used by the new project. For more information about licensing a repository, refer to this documentation.

Alternatively, you can remove the LICENSE file or leave it as is to keep the new project unlicensed.

Writing the Package

Modify the source files under the src directory to start writing the package. If you're new to Python, refer to this documentation for guidance.

You can replace the src/bonacci directory with your package name. You can also add as many packages as you want to the src directory. Just make sure to update the contents of the pyproject.toml file according to your package information.

Testing the Package

Test files in this template are named test_*.py and located in the tests directory. Write the necessary tests for your package and run them with:

uv run pytest -v --cov

This template uses Pytest as the testing framework. For more information on testing with Pytest, refer to this documentation.

Push the Changes

After writing and testing the package, commit the changes and push them to GitHub. Each push to the main branch will trigger a GitHub Actions workflow for continuous integration. For more details on GitHub Actions workflows, refer to this documentation.

Instead of pushing directly to the main branch, it is recommended to push to a separate branch and then create a pull request to merge into main. This allows changes to be reviewed and checked by GitHub Actions before merging. For more details on pull requests, refer to this documentation.

Releasing the Project

Specify Version Number

Update the version number of the package in the pyproject.toml file to match the version you plan to release. The version number usually follows the semantic versioning system. Refer to this documentation for more information on versioning in Python projects.

Build the Package

Before releasing, check if the package can be built with:

uv build

This will create a source tarball and wheel distribution of the package under the dist directory. You can verify the contents of the package or install it locally to ensure that it is built correctly. For more information on building the package, refer to this documentation.

Release on GitHub

Create a new tag in the main branch corresponding to the version number of the release, and then draft a new release using that tag. You can also include the source tarball and wheel distribution as assets in the release. Refer to this documentation for more information on managing releases on GitHub.

Publish on PyPI

Run the following command to publish the package to PyPI:

uv publish

The command will prompt you to enter your username or token for publishing on PyPI. After publishing, wait a few minutes for the package to become available on PyPI. For more information on publishing to PyPI, refer to this documentation.