Metadata-Version: 2.4
Name: kmhelpers
Version: 0.7.0
Summary: A Python toolkit for managing, compressing, and querying indexes with kmindex
Author-email: Sébastien BELLENOUS <kmhelpers@groupes.renater.fr>
License: GPL-3.0-only
Project-URL: Repository, https://github.com/sebllns/kmhelpers
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: psutil>=5.8.0
Requires-Dist: pyyaml>=5.4
Requires-Dist: click>=8.1
Requires-Dist: matplotlib>=3.5
Requires-Dist: zstandard>=0.19
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Requires-Dist: mike>=2.0; extra == "docs"
Requires-Dist: termynal>=0.12; extra == "docs"
Dynamic: license-file

# kmhelpers

---

<img src="assets/kmhelpers-logo-v1.png" alt="Kmhelpers Logo" width="64" height="64">

A Python toolkit for managing, compressing, and querying [kmindex](https://github.com/tlemane/kmindex) indices efficiently.

**Documentation:** <https://sebllns.github.io/kmhelpers/>

---

## Table of Contents

- [Disclaimers](#disclaimers)
- [Getting Started](#getting-started)
- [Documentation](#documentation)
- [License](#license)
- [Contact](#contact)
- [Changelog](#changelog)
- [Acknowledgements](#acknowledgements)

## Disclaimers

`kmhelpers` is provided "as is", without warranty (see [LICENSE](LICENSE)). Operations that build, update, or compress indices modify data in place, so it might be useful to back up important data beforehand, and if you are not sure of something, [ask here](https://github.com/sebllns/kmhelpers/discussions) before running it.

## Getting started

### Clone the repository and navigate to it

```bash
git clone https://github.com/sebllns/kmhelpers
cd kmhelpers
```

To clone a [released version](https://github.com/sebllns/kmhelpers/releases) directly:

```bash
git clone --branch vX.Y.Z https://github.com/sebllns/kmhelpers
cd kmhelpers
```

### Quick Install with Conda 

This will automatically:
- Install `kmhelpers` Python package
- Install `kmindex` and `ntcard`

**Prerequisites:** Conda (Miniconda or Anaconda) must be installed. If you don't have it, see [Installation Instructions](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html).

```bash
# Create environment with kmindex pre-installed
conda env create -f conda/environment.yml -p ./.env

# Activate the environment
# Run this each time you open a new terminal session before using kmhelpers
conda activate ./.env
```

> **Note:** Once per terminal session, activate the environment before using `kmhelpers`:
> ```bash
> conda activate /path/to/kmhelpers/.env
> ```
> `.env` can be replaced by any path, for example a shared or permanent location like `~/.kmhelpers`:
> ```bash
> conda env create -f conda/environment.yml -p ~/.kmhelpers
> conda activate ~/.kmhelpers
> ```

### Verify Installation

Once the environment has been activated:

```bash
# Check the installed version
kmhelpers --version

# View available commands
kmhelpers --help
```

> **Tip:** `kh` is available as a short alias for `kmhelpers` (e.g. `kh --help`).

```bash

# Check ntcard
ntcard --version

# Check kmtricks
kmtricks --version

# Check kmindex
kmindex --version
```

### Update

To pull the latest changes from the default branch (`main`):

```bash
git pull origin main
```

To check out a [released version](https://github.com/sebllns/kmhelpers/releases) instead:

```bash
git fetch --tags
git checkout vX.Y.Z
```

If your local branch is already tracking a remote branch, you can simply run:

```bash
git pull
```

Check the installed version:

```bash
kmhelpers --version
```

## Documentation

<https://sebllns.github.io/kmhelpers/>

Covers installation, a full tutorial, command reference, core concepts, and the API reference.

## License

This project is licensed under the GNU General Public License - see the [LICENSE](LICENSE) file for details.

Copyright (c) 2026 Sébastien Bellenous, Genscale, INRIA

## Contact

For questions, bug reports, or contributions, please contact:

- **Author**: [Sébastien BELLENOUS](https://github.com/sebllns)
- **Email**: kmhelpers@groupes.renater.fr
- **Repository**: [GitHub](https://github.com/sebllns/kmhelpers)
- **Supervisor**: [Pierre Peterlongo](https://github.com/pierrepeterlongo)

---

**Version**: 0.7.0
**Status**: Development

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for detailed version history.


## Acknowledgements

The authors thank Téo Lemane for developing `kmindex` and for his
responsiveness in addressing feature requests and issues raised during the
development of `kmhelpers`. We acknowledge the GenOuest core facility
(<https://www.genouest.org>) for providing the computing infrastructure.
The work was funded by the Inria Challenge "OmicFinder"
(<https://project.inria.fr/omicfinder/>), and by the state funding managed by the French National Research Agency under the France 2030 program [ANR-22-PEAE-0005].
