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#

Contact#

your.mail@mail.com