Metadata-Version: 2.5
Name: atomistic-cookbook-utils
Version: 0.1.1
Summary: Shared utilities for recipes in the Atomistic Cookbook.
Project-URL: Homepage, https://atomistic-cookbook.org
Project-URL: Source, https://github.com/lab-cosmo/atomistic-cookbook/tree/main/src/atomistic-cookbook-utils
Project-URL: Issues, https://github.com/lab-cosmo/atomistic-cookbook/issues
Author: The Atomistic Cookbook contributors
License: BSD-3-Clause
Keywords: atomistic,cookbook,utilities
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Requires-Dist: requests>=2.25
Requires-Dist: urllib3>=1.26
Description-Content-Type: text/markdown

# atomistic-cookbook-utils

Small shared utilities used by the recipes in the
[Atomistic Cookbook](https://atomistic-cookbook.org).

The goal is to keep recipe code focused on the science: any boilerplate
that would otherwise be copy-pasted across many recipes lives here.

## Installation

```bash
pip install atomistic-cookbook-utils
```

For a recipe's `environment.yml`, add it under `pip:` with a semantic
version range, e.g.

```yaml
- atomistic-cookbook-utils >=0.1,<0.2
```

## Contents

### `download_with_retry`

Download a file with automatic retries on transient HTTP errors
(429, 500, 502, 503, 504), restarting the download if the connection
breaks while the file is being received. Skips the download if the file
already exists, creates parent directories as needed.

```python
from atomistic_cookbook_utils import download_with_retry

download_with_retry(
    "https://zenodo.org/records/10566825/files/gaas_training.xyz",
    "data/gaas_training.xyz",
)
```

If the `ATOMISTIC_COOKBOOK_CACHE` environment variable points to a
directory, downloads go through a cache in that directory, keyed by URL:
a file that is already in the cache (e.g. because another recipe
downloaded it) is copied from there instead of being downloaded again.
The cookbook CI uses this to share data files across recipes. If the
variable is not set, files are downloaded directly to their destination.
Any problem with the cache directory also falls back to a direct
download, and `overwrite=True` always bypasses the cache.

### `run_command`

Run a shell-like command string without invoking a shell. The string is
split with `shlex.split`, so quoting works as expected; pipes, redirection
and globs do *not* — for those, use `subprocess` directly.

By default the child inherits the parent's stdout and stderr. Pass
`print_output=True` to capture the command's combined output and
re-emit it via `print()` — this makes the output visible in
sphinx-gallery rendered cells (which capture `sys.stdout` but not raw
file-descriptor writes from child processes).

```python
from atomistic_cookbook_utils import run_command

run_command("mtt train options.yaml")
run_command("ls -la", cwd="data", print_output=True)
```

## Source

This package is developed inside the cookbook repository at
`src/atomistic-cookbook-utils/`. See `CONTRIBUTING.rst` at the repo
root for development workflow.
