Metadata-Version: 2.5
Name: fasthep-toolbench
Version: 2026.10.2
Summary: Package for cross-package utility functions
Project-URL: Homepage, https://github.com/FAST-HEP/fasthep-toolbench
Project-URL: Bug Tracker, https://github.com/FAST-HEP/fasthep-toolbench/issues
Project-URL: Discussions, https://github.com/FAST-HEP/fasthep-toolbench/discussions
Project-URL: Changelog, https://github.com/FAST-HEP/fasthep-toolbench/releases
Author-email: Luke Kreczko <kreczko@cern.ch>
License-File: LICENSE
Classifier: Development Status :: 1 - Planning
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: loguru
Requires-Dist: pyyaml
Requires-Dist: sh
Provides-Extra: all
Requires-Dist: httpx; extra == 'all'
Requires-Dist: rich; extra == 'all'
Requires-Dist: tabulate; extra == 'all'
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: pytest-cov>=3; extra == 'dev'
Requires-Dist: pytest>=6; extra == 'dev'
Requires-Dist: rich; extra == 'dev'
Requires-Dist: tabulate; extra == 'dev'
Provides-Extra: display
Requires-Dist: rich; extra == 'display'
Requires-Dist: tabulate; extra == 'display'
Provides-Extra: docs
Requires-Dist: furo>=2023.08.17; extra == 'docs'
Requires-Dist: myst-parser>=0.13; extra == 'docs'
Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: http
Requires-Dist: httpx; extra == 'http'
Provides-Extra: test
Requires-Dist: httpx; extra == 'test'
Requires-Dist: pytest-cov>=3; extra == 'test'
Requires-Dist: pytest>=6; extra == 'test'
Requires-Dist: rich; extra == 'test'
Requires-Dist: tabulate; extra == 'test'
Description-Content-Type: text/markdown

# fasthep-toolbench

[![Actions Status][actions-badge]][actions-link]
[![Documentation Status][rtd-badge]][rtd-link]

[![PyPI version][pypi-version]][pypi-link]
[![PyPI platforms][pypi-platforms]][pypi-link]

[![GitHub Discussion][github-discussions-badge]][github-discussions-link]

<!-- SPHINX-START -->

<!-- prettier-ignore-start -->
[actions-badge]:            https://github.com/FAST-HEP/fasthep-toolbench/workflows/CI/badge.svg
[actions-link]:             https://github.com/FAST-HEP/fasthep-toolbench/actions

[github-discussions-badge]: https://img.shields.io/static/v1?label=Discussions&message=Ask&color=blue&logo=github
[github-discussions-link]:  https://github.com/FAST-HEP/fasthep/discussions
[pypi-link]:                https://pypi.org/project/fasthep-toolbench/
[pypi-platforms]:           https://img.shields.io/pypi/pyversions/fasthep-toolbench
[pypi-version]:             https://img.shields.io/pypi/v/fasthep-toolbench
[rtd-badge]:                https://readthedocs.org/projects/fasthep-toolbench/badge/?version=latest
[rtd-link]:                 https://fasthep-toolbench.readthedocs.io/en/latest/?badge=latest

[fasthep-logo]: https://raw.githubusercontent.com/FAST-HEP/logos-etc/master/fast-hep-black.png
[fasthep-link]: https://github.com/fast-hep/fasthep
<!-- prettier-ignore-end -->

[![fasthep][fasthep-logo]][fasthep-link]

## Introduction

> [!NOTE]
>
> `fasthep-toolbench` is still in early development, which means it is
> incomplete and the API is not yet stable. Please report any issues you find on
> the
> [GitHub issue tracker](https://github.com/FAST-HEP/fasthep-toolbench/issues).

**fasthep-toolbench** is a collection of tools and utilities for FAST-HEP
packages.

## Documentation

This project is in early development. The documentation is available at
[fasthep-toolbench.readthedocs.io](https://fasthep-toolbench.readthedocs.io/en/latest/)
and contains mostly fictional features. The most useful information can be found
in the [FAST-HEP documentation](https://fast-hep.github.io/). It describes the
current status and plans for the FAST-HEP projects, including
`fasthep-toolbench` (see
[Developer's Corner](https://fast-hep.github.io/developers-corner/)).

## Installation

You can install `fasthep-toolbench` using `pip`:

```bash
pip install fasthep-toolbench
```

The core package needs only `loguru`, `pyyaml` and `sh`. Features that use heavier libraries
are optional extras:

| Extra | Installs | Enables |
|---|---|---|
| `display` | `rich`, `tabulate` | `fasthep_toolbench.display` (tables and formatted output), progress spinners |
| `http` | `httpx` | `fasthep_toolbench.http` (downloads) and the tool installers (for example D2) |
| `all` | all of the above | everything |

```bash
pip install "fasthep-toolbench[display,http]"
```

Importing a module that needs a missing extra raises an `ImportError` that names it.
Progress spinners are skipped when `rich` is not installed. A package that imports
`fasthep_toolbench.display` or `fasthep_toolbench.http` (for example `fasthep-cli`, and the
`fasthep` metapackage that installs it) must depend on `fasthep-toolbench[display,http]` (or
`[all]`); packages that only use the command execution, tool registry and environment helpers
can depend on the bare package.

## Environment inspection

`fasthep_toolbench.package` also provides quiet, import-safe helpers that describe the
running environment, using `importlib.metadata` and `git` only (no lock file, `pixi` or
`conda` is needed): `python_info`, `installed_distributions`, `distribution_info`
(including `direct_url.json` data such as the VCS commit of an installed distribution),
`git_state` (its `dirty` flag means tracked files differ from `HEAD`; untracked files are
ignored; git runs with `core.fsmonitor` disabled and without optional locks) and
`find_lockfile`. URLs from `direct_url.json` are recorded without credentials. `fasthep_toolbench.misc` has `file_sha256` and
`file_fingerprint` (full sha256 and size) for hashing files.

## Contributing

You had a look and are interested to contribute? That's great! There are three
main ways to contribute to this project:

1. Head to the
   [issues tab](https://github.com/FAST-HEP/fasthep-toolbench/issues) and see if
   there is anything you can help with.
2. If you have a new feature in mind,
   [please open an issue](https://github.com/FAST-HEP/fasthep-toolbench/issues/new)
   first to discuss it. This way we can ensure that your work is not in vain.
3. You can also help by improving the documentation or fixing typos.

Once you have something to work on, you can have a look at the
[contributing guidelines](./.github/CONTRIBUTING.md). It contains
recommendations for setting up your development environment, testing, and more
(compiled by the Scientific Python Community).

> [!IMPORTANT]
>
> How you customise your development environment is up to you. You like
> [uv](https://github.com/astral-sh/uv)? Be our guest. You prefer
> [nox](https://nox.thea.codes/en/stable/)? That's fine too. You want to use
> <your custom workflow>? Go ahead. We are happy as long as you are happy.
> Ideally you should be able to run `pylint`, `pytest`, and the pre-commit
> hooks. If you can do that, you are good to go.

## License

This project is licensed under the terms of the Apache 2.0 license. See
[LICENSE](./LICENSE) for more details.

## Acknowledgements

Special thanks to the gracious help of FAST-HEP contributors:

<!-- readme: collaborators,contributors -start -->
<table>
	<tbody>
		<tr>
            <td align="center">
                <a href="https://github.com/kreczko">
                    <img src="https://avatars.githubusercontent.com/u/1213276?v=4" width="100;" alt="kreczko"/>
                    <br />
                    <sub><b>Luke Kreczko</b></sub>
                </a>
            </td>
		</tr>
	<tbody>
</table>
<!-- readme: collaborators,contributors -end -->
