Metadata-Version: 2.4
Name: hestia_earth_converters
Version: 0.2.4
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) |
| `--update-flowmaps` | Download the flowmaps when a newer version is published, rather than only warning |
| `--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).

**A run that had to drop a flow says so, and leaves you the list.** What the flowmaps do not cover is written to `missing-flowmaps.txt` — one line per flow, deduplicated, with the name and unit the source states for it — and the run ends by naming that file and the issue tracker to attach it to. Nothing is written when everything mapped. `--missing-flowmaps-file` puts it somewhere else.

```
# 8 flow(s) this conversion could not map, and so dropped.
# conversion: FCC -> HESTIA
# flowmaps: 20260821-8550eee8
...
# direction	nomenclature	flow	name	unit
to HESTIA	FCC	proc_00141	On-farm processing (i.e. veg boxes) - Water ... - Mains water ...	m3
```

The file is a record of one run against one version of the flowmaps, so it is gitignored rather than committed.

**Every run checks whether a newer version has been published** and warns if so, naming the version in use and the current one. It does not download it: a flowmap version is part of what produced a result, so the same command keeps giving the same answer until you say otherwise. Pass `--update-flowmaps` to take the new version instead.

The check reads a single 18-byte file and is advisory only — if it cannot be reached, the conversion runs on what is already on disk. Only the default `hestia-flowmaps` folder is checked; a folder you name is yours, whether it is edited or deliberately pinned. The version in use is recorded in `hestia-flowmaps/version.txt`, so a folder assembled before that file existed reports as unrecorded until it is next downloaded.


**Only the bundles your install needs are downloaded.** The flowmaps are published per nomenclature, and each bundle belongs to an install extra — someone who installed `[FCC]` gets the four FCC maps rather than all 101, which is 40KB instead of 22MB compressed. The whole archive is still what you get when the extras cannot be worked out, such as a source checkout with nothing installed. To choose the set yourself:

```sh
python download_flowmaps.py --bundle fcc klim --version-filepath tests/flowmaps-version.txt
```

Bundles unpack into the same folder, so several combine. An unknown name is refused before anything downloads, and the published names are listed in the error.

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