Template Repository for Python Packages

A template repository for modern python package development with uv using Pydantic and Polars. Linted with ruff, type checked with ty and pyright, and tested with pytest using GitHub Actions.

Checklist

• Replace YOURUSERNAME and IMAGENAME in .github/workflows/docker-image.yml [or delete file].
• Replace test data in data with your own data [or delete if you don't have test data].
• Adjust .gitignore according to your needs.
• Setup your CITATION.cff according to your needs [or delete file].
• Update attribution in Dockerfile and write image instructions.
• Replace copyright name in LICENSE.
• Update attributions and package configuration in pyproject.toml.
• Update attributions and write your package in src/name_of_your_package.
• Update attributions and write tests in tests/.
• Add your requirements via uv add.
• Document your code using the numpydoc style and Sphinx:
  • Adjust the configuration to your needs in docs/conf.py.
  • Automatically via GitHub Actions:
    • In the file .github/workflows/gh-pages.yml in line 55 replace src/python_pkg_template with src/name_of_your_package. For example, the full line should read as:

      uv run sphinx-apidoc -f -o docs src/name_of_your_package

    • In the repository go to Settings ➡️ Pages ➡️ Build and deployment ➡️ Source ➡️ GitHub Actions.
    • Select the gh-pages.yml / Deploy Documentation to Pages workflow.
  • Or build manually:
    • Install documentation dependencies via:

      uv sync --group docs

    • Build documentation with:

      uv run sphinx-apidoc -f -o docs src/python_pkg_template

      which eventually should be replaced with

      uv run sphinx-apidoc -f -o docs src/name_of_your_package

      and then run

      uv run sphinx-build -b html docs html

    • Publish documentation [optional]!
    • Serving with GitHub pages needs the addition of an empty .nojekyll file to your /html.
• Decide on a type checker and delete the other!
• Adjust this README.md to your needs!

Package Deployment and Workflows

Please consider reading the Python Packaging User Guide!

Important

In order to publish your python package you need to create an account on PyPI and ideally also TestPyPI for staging.

• Setup trusted publishing.
• Replace <NAME-OF-YOUR-PACKAGE> with the name of your package in
  • ...line 37 of .github/workflows/publish-testpypi.yml.
  • ...line 37 of .github/workflows/publish-pypi.yml.
  • ...line 28 of .github/workflows/test-testpypi.yml.
  • ...line 28 of .github/workflows/test-pypi.yml.

Staging and Publishing

Whenever you have a new version of your package ready, go to the Actions tab in your GitHub repository and run the following workflows:

• Run Publish Python Package to TestPyPI (workflow file: publish-testpypi.yml).
• Check that the workflow successfully completes!
• Run Run tests on package from TestPyPI (workflow file: test-testpypi.yml).
• Check that the workflow successfully completes!
• Run Publish Python Package to PyPI (workflow file: publish-pypi.yml).
• Check that the workflow successfully completes!
• Run Run tests on package from PyPI (workflow file: test-pypi.yml).
• Check that the workflow successfully completes!
• Done! Your package was successfully published to TestPyPI and PyPI!

Note

You can omit TestPyPI but staging is generally good practice!

Helpful Commands

• uv:
  • Add a dependency/package [pkg]:

    uv add pkg

  • Upgrade dependencies/packages:

    uv lock --upgrade

  • Update environment:

    uv sync

  • Run python:

    uv run python

  • Run a package script (with arguments):

    uv run battle -h

• ruff:
  • Check and fix (fixable) errors:

    uv run ruff check --config ruff.toml --fix

  • Check (with explicit config file):

    uv run ruff check --config ruff.toml

  • Format code:

    uv run ruff format

  • Format (with explicit config file):

    uv run ruff format --config ruff.toml

• ty:

  uv run ty check --config-file ty.toml

• pyright:

  uv run pyright --warnings

• pytest:

  uv run pytest -c pytest.ini --durations=10 --durations-min=1.0 tests/

Getting Help

• Help for this template:
  • uv: Python project and dependency management.
  • ruff: Python linter and formatter.
  • ty: Python type checker.
  • pyright: Python type checker.
  • pytest: Python testing suit.
  • GitHub Actions: Used for running the above automatically.
• Contact: micha.birklbauer@gmail.com

Important

The below sections should be adjusted and updated by you!

Known Issues

List of known issues

Citing

If you are using PLACEHOLDER please cite:

Very important title
Important Author, and Another Important Author
Journal of Cool Stuff 2023 12 (3), 4567-4589
DOI: 12.3456/cool-stuff

License

• MIT

Contact

• your.mail@mail.com