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#

Contact#

your.mail@mail.com