Skip to content

Commit

Permalink
feat: Add a section on hatch as an environment manager and task runner (
Browse files Browse the repository at this point in the history
#79)

Add a section on hatch to the task runners episode.

related PRs:
- requires #71
  • Loading branch information
hollandjg authored Jul 17, 2024
1 parent 70c2717 commit 9dfe457
Showing 1 changed file with 68 additions and 0 deletions.
68 changes: 68 additions & 0 deletions _episodes/01-environment.md
Original file line number Diff line number Diff line change
Expand Up @@ -460,7 +460,75 @@ which will fallback to `virtualenv` if `uv` is not installed
> How does the execution time change?
{:.challenge}
### Hatch
Hatch is a Python "Project Manager" which can:
- build packages,
- manage virtual environments,
- manage multiple python versions for a project,
- run tests using `pytest`,
- run static analysis on code using `ruff`,
- **execute scripts with specific dependencies and python versions** (this is the "task runner" part)
- publish packages to PyPI,
- help bump version numbers of packages,
- use templates to create new python projects
To initialize an existing project for `hatch`,
enter the directory containing the project and run the following:
```bash
hatch new --init
```
This will interactively guide you through the setup process.
To run tests using `hatch`, run the following:
```bash
hatch test
```
This will:
- create a python environment in which your tests will run, then
- run the tests.
Alongside built-in commands like `test`, `hatch` allows adding custom scripts.
For instance, to add an environment and scripts
for viewing and publishing the Material for MkDocs documentation,
you can add the following lines to the `pyproject.toml` file:
```toml
[tool.hatch.envs.doc]
dependencies = [
"mkdocs-material",
"mkdocstrings[python]"
]
[tool.hatch.envs.doc.scripts]
serve = "mkdocs serve --dev-addr localhost:8000"
build = "mkdocs build --clean --strict --verbose"
deploy = "mkdocs gh-deploy"
```
This specifies a new environment `doc`
with the `mkdocs-material` and `mkdocstrings` dependencies needed, and
scripts `serve`, `build` and `deploy` defined within that environment.
Then to view the documentation locally, run `hatch run <ENV>:<SCRIPT>`, e.g.:
```bash
hatch run doc:serve
```
to run the preview server, or
```bash
hatch run doc:build
```
to build the documentation, ready for deployment.
The key benefits here are that:
- these scripts run within an isolated environment,
- the simple commands like `hatch run doc:serve` allow the developer to
use arguments like `--dev-addr localhost:8000` without needing to remember or think about them.
The developer must decide whether these benefits outweigh
the added complexity of an additional layer of abstraction,
which will hinder debugging if something goes wrong.
{% include links.md %}

0 comments on commit 9dfe457

Please sign in to comment.