Hatch

Hatch is a quite new »egg« in the ecosystem of PyPA as a Python project manager (v1.0.0 is from April 2022). However, it is the Pathon project manager of choice for me and therefore for Workflow Tutor, despite the fact, that I could not find a concise tutorial at the time of writing (August 2024).

It has an excellent reference documentation, but it took me some time to understand the concept. Therefore, a few sentences about the:

Concept

The main building blocks of a Python project, besides the source code for the project itself, are the Python interpreter (version) used, and typically a project-dependent virtual environment, which contains all the libraries and software used. To have a smooth development experience, the setup should allow the so called dev mode or editable builds.

Hatch allows to combine these building blocks individually, meaning a specific virtual environment, e.g. for production or development, might be combined with a special version of Python for a dev or production run. As a consequence, it is very easy to create so called test matrices to test your source code against different operating conditions.

Keeping this idea in mind, it might be easier to follow the documentation of Hatch, especially the Walkthrough.

Every Day Commands

hatch new <project name>          # Not really every day, but the start of a Python project
hatch shell [<venv>]                # Run a shell in a certain virtual environment [default]
hatch run docs:serve                # Run the local MkDocs server
hatch run docs:build                # Build the documentation
hatch run [<venv>]:<command>    # Run <command> in <venv> [default]
hatch env remove [<venv>]       # Remove a <venv> [default], will be recreated if used
hatch env prune                 # Removes all virtual environments
hatch python update all         # Updates all installed versions of Python

The best and simplest way to update all dependencies of a virtual environment is to remove it, and start a shell or run it again.

Version control

The most practical way for me to deal with versions turned out to start a new version immediately after publishing the one before:

hatch version                     # Show the current version, if necessary
hatch version x.y.z             # Write the new version
hatch version dev               # Add a development marker to the current version
hatch version release           # Create the version to release the project

Build & Publish

hatch build -c                  # Creates a source package and a wheel in
                                # a clean environment (-c) in the subdir dist/
hatch publish                   # Publishes the artifacts on PyPI from folder dist/