project

A great package.

Sections in this README

• Installation
• Running the main script
• Adding dependencies
• Running test
• Formatting and checking
• Documentation
• Versions
• Publishing your package
• License

Installation

1. Install uv:

2. Install the dependencies, including the dev dependencies

   uv sync

   or install only the runtime dependencies

   uv sync --no-dev

3. Install the prek hook. This will set up prek to run the checks automatically on your files before you commit them.

   uv run prek install

Remember that if the prek checks fail, you can always commit by skipping the checks with git commit --no-verify

Running the main script

Execute the main script with

uv run main_script

Adding dependencies

Add dependencies by running

uv add numpy

if you want to install PyTorch have a look at https://docs.astral.sh/uv/guides/integration/pytorch/

Running tests

Run your tests with

uv run pytest --cov=src ./tests

Formatting and checking

The tools for formatting and linting your code for errors are all bundled with prek. Included are:

• ruff - linting and formatting
• yamlfix - linting and formatting for .yaml files
• various other small fixes and checks (see the .pre-commit-config.yaml file for more information)

It's possible that prek will make changes to your files when it runs the checks, so you should add those changes to your commit before you commit your code. A typical workflow would look like this:

git add -u
git commit -m "My commit message"
# prek will run the checks here; if it makes changes, you'll need to add them to your commit
git add -u
git commit -m "My commit message"
# changes should have all been made by now and the commit should pass if there are no other issues
# if your commit fails again here, you have to fix the issues manually (not everything can be fixed automatically).

One thing that is worth knowing is how to lint your files outside of the context of a commit. You can run the checks manually by running the following command:

uv run prek run --all-files

This will run the checks on all files in your git project, regardless of whether they're staged for commit or not.

Documentation

Generate the documentation locally with

uv run zensical serve

Versions

Versions are managed automatically via hatch-vcs, which follows the versioning scheme from setuptools-scm.

To create a new version, tag the code with git tag <version>, e.g. git tag v0.1.0, and push the tag with git push --tags.

You can check the version by running

uv run hatch version

In python you can see the version with

from project import __version__

print(f"project version is { __version__ }")

Publishing the package

If you're ready to publish your package to PyPI (i.e. you want to be able to run pip install my-package-name from anywhere), follow the uv instructions. In short, they boil down to running:

1. Build the wheel

   uv build

2. Upload the wheel to PyPI

   uv publish

If your package is private and you are using gitlab.ewi.tudelft.nl, you can publish it to it's private registry. This will let you do pip install project. See the instructions here.

License

Distributed under the terms of the GPL license.