Template Repository for Python Scripts

A template repository for modern python development with uv using Pydantic, Polars, and Streamlit. 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 .gitattributes according to your needs [or delete file].
• 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 attribution and write your script in main.py.
• Update attribution and write your gui in app.py.
• Update attribution and write tests in tests/test_main.py.
• Add your requirements via uv add and to requirements.txt.
• 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 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 Sphinx, the PyData theme, and extensions:

      pip install sphinx pydata-sphinx-theme myst-parser sphinx-copybutton

    • Build documentation with:

      sphinx-apidoc -f -o docs .
      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!

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 script (with arguments):

    uv run main.py -h

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

    ruff check --fix

  • Check (with explicit config file):

    ruff check --config ruff.toml

  • Format code:

    ruff format

  • Format (with explicit config file):

    ruff format --config ruff.toml

• ty:

  ty check --config-file ty.toml

• pyright:

  pyright

• pytest:

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

• streamlit:

  uv run streamlit run app.py

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