What is this?

Heimdall is a tool for converting more easily one or more databases from one format to another. It leverages modules called “connectors”, responsible for conversion of data between specific databases schemas and the HERA format.

This repository contains a connector to Heurist’s own XML export format (HML).

Why should I use it?

You can use this connector, along with the pyheimdall software, to retrieve any data exported from Heurist. You can then aggregate this data into your research corpus easily, for example using other Heimdall connectors.

How can I use it?

pip install pyheimdall-heurist

pip install --upgrade pyheimdall-heurist
pip uninstall pyheimdall-heurist

import heimdall

db = heimdall.getDatabase(format='heurist:api', url=…, login=…, password=…)
heimdall.createDatabase(db, format='csv', url='.')  # or any other format

Is it tested?

Well, yes… and no.

As you can see in our badge list, or in this coverage report, the code coverage by our unit tests is not too shabby.

The heurist:api format is tested each week, so it’ll work… until Heurist will make it break. Then, you’ll at least know if you can rely on it using the pipeline badge just up there.

• First, those assumptions can be wrong, or incomplete. Still at the time of writing, the Heurist core development team seems unable to document its own output, so… well.

• Second, even if everything seems fine today in your eyes, the Heurist core development team is known to force unto its userbase new (sometimes breaking) updates without any prior notice, documentation or regression testing. Of course, this means that the /test/resources/heurist.xml file may become outdated with time, and this connector won’t automagically warn you of any problem.

How can I contribute?

PyHeimdall welcomes any feedback or proposal. See here for details.

Are there any alternatives?

Yup. There is the Heurist API & Data Pipeline, which allows you to free up your data from Heurist and export it to DuckDB or CSV.

There are many other tools, self-managed or not, with functional scopes comparable to Heurist. For example these days, people seem to enjoy Grist, or Omeka if you’re into CDNs. As it happens, there is a heimdall connector for both: pyheimdall-grist and pyheimdall-omeka.

License

GNU Affero General Public License version 3.0 or later