Metadata-Version: 2.4
Name: hestia_earth_converters
Version: 0.2.3
Summary: HESTIA's set of file converters
Home-page: https://gitlab.com/hestia-earth/hestia-convert-base
Author: @ToffeeLabs
Author-email: community@hestia.earth
License: MIT
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Werkzeug
Requires-Dist: pydantic==2.*
Requires-Dist: pydantic_core==2.*
Requires-Dist: hestia-earth-schema>=38.3.1
Requires-Dist: hestia-earth-utils>=0.17.25
Requires-Dist: python-dateutil
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: setuptools
Provides-Extra: simapro
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "simapro"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "simapro"
Requires-Dist: hestia-earth-flowmaps>=0.1.18; extra == "simapro"
Requires-Dist: bw_simapro_csv==0.4.2; extra == "simapro"
Requires-Dist: pydantic==2.*; extra == "simapro"
Requires-Dist: pydantic[email]; extra == "simapro"
Requires-Dist: requests; extra == "simapro"
Requires-Dist: unidecode; extra == "simapro"
Provides-Extra: coolfarm
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "coolfarm"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "coolfarm"
Requires-Dist: hestia-earth-flowmaps>=0.1.18; extra == "coolfarm"
Requires-Dist: pydantic==2.*; extra == "coolfarm"
Provides-Extra: openlca
Requires-Dist: olca_schema==2.4.0; extra == "openlca"
Requires-Dist: hestia-earth-utils[lsrs]>=0.17.25; extra == "openlca"
Requires-Dist: joblib~=1.5.2; extra == "openlca"
Requires-Dist: email-validator==2.3.0; extra == "openlca"
Requires-Dist: hestia-earth-models>=0.85.0; extra == "openlca"
Requires-Dist: hestia-earth-flowmaps>=0.1.18; extra == "openlca"
Requires-Dist: pydantic-settings; extra == "openlca"
Requires-Dist: filelock; extra == "openlca"
Provides-Extra: lsrs
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "lsrs"
Requires-Dist: hestia-earth-utils[lsrs]>=0.17.25; extra == "lsrs"
Requires-Dist: pydantic==2.*; extra == "lsrs"
Provides-Extra: klim
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "klim"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "klim"
Requires-Dist: hestia-earth-flowmaps>=0.1.18; extra == "klim"
Requires-Dist: pydantic==2.*; extra == "klim"
Provides-Extra: fcc
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "fcc"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "fcc"
Requires-Dist: hestia-earth-flowmaps>=0.1.14; extra == "fcc"
Requires-Dist: pydantic==2.*; extra == "fcc"
Requires-Dist: openpyxl>=3.1; extra == "fcc"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# HESTIA Converters

> Library to convert from/to the [HESTIA](https://www.hestia.earth) format.

## Quick start

Install the base library and the converter you need. Each converter is its own install extra, so you only pull the dependencies of the formats you use:

```sh
pip install hestia-earth-converters
pip install "hestia-earth-converters[SimaPro]"
```

`hestia-convert --help` is generated from the converters you installed, so it always lists exactly the formats and options available to you.

```sh
# a HESTIA ImpactAssessment, downloaded by id, as a SimaPro CSV
hestia-convert --output-folder out --input-format HESTIA --output-format SimaPro \
  --hestia-impact-id cocoaSeedWhole-ghana-2010-2025-20250916

# a file on disk, converted to HESTIA nodes
hestia-convert --output-folder out --input-format OpenLCA --output-format HESTIA \
  --input-file export.zip
```

**Some data needs an API key**, as does downloading any node with `--hestia-impact-id`. Create an account, copy the key from the "API Access" section of https://www.hestia.earth/profile, and set it as the `API_ACCESS_TOKEN` environment variable.

**Where no converter goes straight from one format to another, the CLI runs the pair that does, by way of HESTIA.** So every input format reaches LSRS:

```sh
hestia-convert --output-folder out --input-format Klim --output-format LSRS \
  --input-file farm.zip
```

runs `Klim -> HESTIA`, then `HESTIA -> LSRS` over what it wrote. The intermediate HESTIA files stay in `--output-folder` — they are output too, and they are what makes a chained run debuggable. `--filter-by-name` names a result of the *first* leg, and the rest of the chain sees only what it selected.

These flags apply to every conversion. Each converter adds more of its own, prefixed with its name; its README lists them.

| Flag | Description |
| --- | --- |
| `--output-folder` | Output files folder (**required**) |
| `--input-format` | Format to read (**required**) |
| `--output-format` | Format to write (**required**) |
| `--input-file` | Path to the input file |
| `--hestia-impact-id` | One or more HESTIA ImpactAssessment ids to download and convert |
| `--mapping-files-directory` | Folder of `.csv` mapping files (default: `hestia-flowmaps`, downloaded if absent) |
| `--skip-existing` | Do not overwrite files already written |
| `--filter-by-name` | Names to filter results on (in quotes) |
| `--verbose` | Verbose logging |
| `--debug-file` | Write conversion logs to a debug file |

## Converters

| Format | Directions | Install extra | Docs |
| --- | --- | --- | --- |
| [Cool Farm Platform](https://coolfarmtool.org) | Cool Farm ⇄ HESTIA | `[CoolFarm]` | [README](hestia_earth/converters/coolfarm/README.md) |
| [Farm Carbon Calculator](https://farmcarbontoolkit.org.uk/farm-carbon-calculator/) | FCC ⇄ HESTIA | `[FCC]` | [README](hestia_earth/converters/fcc/README.md) |
| [KLIM](https://klim.eco) | Klim → HESTIA | `[Klim]` | [README](hestia_earth/converters/klim/README.md) |
| [LSRS reporting spreadsheet](https://ghgprotocol.org/land-sector-and-removals-guidance) | HESTIA → LSRS | `[LSRS]` | [README](hestia_earth/converters/lsrs/README.md) |
| [openLCA](https://www.openlca.org) | openLCA ⇄ HESTIA, openLCA → LSRS | `[OpenLCA]` | [README](hestia_earth/converters/openlca/README.md) |
| [SimaPro](https://simapro.com) | HESTIA → SimaPro | `[SimaPro]` | [README](hestia_earth/converters/simapro/README.md) |

Term mappings come from [hestia-convert-flowmaps](https://gitlab.com/hestia-earth/hestia-convert-flowmaps), downloaded automatically unless `--mapping-files-directory` points elsewhere. Errors and omissions in a mapping belong in [an issue on that repository](https://gitlab.com/hestia-earth/hestia-convert-flowmaps/-/issues/new?description_template=bug).

Adding a converter? See **[CONVERTER_BLUEPRINT.md](CONVERTER_BLUEPRINT.md)**. Contributing? See **[CONTRIBUTING.md](CONTRIBUTING.md)**.
