Metadata-Version: 2.4
Name: hestia_earth_converters
Version: 0.2.8
Summary: HESTIA's set of file converters
Home-page: https://gitlab.com/hestia-earth/hestia-convert-base
Author: HESTIA Team
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: agrecalc
Requires-Dist: hestia-earth-schema>=38.3.1; extra == "agrecalc"
Requires-Dist: hestia-earth-utils>=0.17.25; extra == "agrecalc"
Requires-Dist: hestia-earth-flowmaps>=0.1.14; extra == "agrecalc"
Requires-Dist: pydantic==2.*; extra == "agrecalc"
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.

## Install

**Install one converter, not all of them.** Each converter is its own install extra, named in the [Converters](#converters) table below, and installing it is the whole install — the extra brings the base library and the `hestia-convert` command with it:

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

Several converters go in one pair of brackets, comma-separated:

```sh
pip install "hestia-earth-converters[Klim,LSRS]"
```

Keep the quotes. `zsh` reads an unquoted `[SimaPro]` as a glob and refuses the command with `no matches found`; `bash` happens to pass it through, so quoting is what works in both.

Add a format later by running the same command again with the new extra. Nothing else needs redoing: the next conversion notices the new converter and downloads the flowmap bundles it needs.

**A conversion that needs an extra you do not have stops before it reads anything**, and names the command that fixes it — `hestia-convert --help` lists every format the package ships, not the subset you installed:

```
Please install 'hestia-earth-converters[OpenLCA]' first (No module named 'olca_schema').
```

**A chained conversion needs the extra at each end.** `Klim -> LSRS` runs `Klim -> HESTIA` and then `HESTIA -> LSRS`, so it wants `[Klim,LSRS]`; both are checked before the first leg writes a file.

**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.

Working on the converters themselves rather than using them? [CONTRIBUTING.md](CONTRIBUTING.md#setup) sets up a source checkout.

## Quick start

```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
```

**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

The extra in the third column is what goes in the brackets of `pip install "hestia-earth-converters[...]"`; each converter's page opens with its own install command.

| Format | Directions | Install extra | Docs |
| --- | --- | --- | --- |
| [Agrecalc](https://www.agrecalc.com/) | Agrecalc ⇄ HESTIA | `[Agrecalc]` | [README](hestia_earth/converters/agrecalc/README.md) |
| [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.

Or say what to leave out, which is what CI does — a set stated this way needs no edit when a converter is added, because its bundle is included the moment the pinned version carries it:

```sh
python download_flowmaps.py --exclude-bundle other --version-filepath tests/flowmaps-version.txt
```

`other` is the one nothing loads: it unpacks into `FlowMaps/other_flowmaps/`, and `get_all_flowmapping()` iterates `FlowMaps/` non-recursively. It is also 143MB of the 185MB archive, so excluding it alone is most of the saving.

**A download that fails costs nothing.** The new copy is built in `hestia-flowmaps.download` and swaps in only once it is complete, so the folder a conversion reads is either the previous version or the whole new one — never the remains of a download that died half way. The same is true of `--update-flowmaps`: if it cannot fetch the new version, the conversion runs on the copy already on disk and warns which version that is.

**`--require-converter-bundles` fails a download that left a converter without flowmaps**, naming the bundle and the files. Worth it because the absence is otherwise silent: a conversion with no maps does not fail, it writes a document stripped of every mapped node. Which bundles count is the published list's own answer — each one names the install extra it belongs to — so a converter added later is covered without being named here, and one that reads no flowmaps is never asked for.

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