################################
Heimdall - Heurist XML connector
################################
.. image:: https://img.shields.io/badge/license-AGPL3.0-informational?logo=gnu&color=success
:target: https://www.gnu.org/licenses/agpl-3.0.html
.. image:: https://www.repostatus.org/badges/latest/unsupported.svg
:target: https://www.repostatus.org/#project-statuses
.. image:: https://img.shields.io/badge/documentation-api-green
:target: https://datasphere.readthedocs.io/projects/heimdall/
.. image:: https://gitlab.huma-num.fr/datasphere/heimdall/connectors/heurist/badges/main/pipeline.svg
:target: https://gitlab.huma-num.fr/datasphere/heimdall/connectors/heurist/pipelines/latest
.. image:: https://gitlab.huma-num.fr/datasphere/heimdall/connectors/heurist/badges/main/coverage.svg
:target: https://datasphere.gitpages.huma-num.fr/heimdall/connectors/heurist/coverage/index.html
*************
What is this?
*************
`Heimdall <https://datasphere.readthedocs.io/projects/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 <https://gitlab.huma-num.fr/datasphere/heimdall/python>`_, to retrieve any data exported from Heurist.
You can then aggregate this data into your research corpus easily, for example using other Heimdall connectors.
| Take note, however that some legal restrictions might apply to data retrieved from any scientific database.
| Plus, if at the end of your project, you share your data, please cite the original data properly.
*****************
How can I use it?
*****************
Setup
=====
This pyHeimdall connector is available as a `PyPI package <https://pypi.org/project/pyheimdall-heurist/>`_ named ``pyheimdall-heurist``.
You can install it using the `pip <https://pip.pypa.io/en/stable/>`_ package manager:
.. code-block:: bash
pip install pyheimdall-heurist
You can use `pip <https://pip.pypa.io/en/stable/>`_ to either upgrade or uninstall this connector, too:
.. code-block:: bash
pip install --upgrade pyheimdall-heurist
pip uninstall pyheimdall-heurist
Usage
=====
.. code-block:: python
import heimdall
tree = heimdall.getDatabase(format='heurist:xml', url='Export_db_AAAAMMDDHHMMSS.xml')
heimdall.createDatabase(tree, format='csv', url='.')
Please note that you shouldn't use ``pyheimdall-heurist`` functions directly.
As long as the package is installed on your system, pyHeimdall will automatically discover its features and allow you to use them as long as any other `default <https://gitlab.huma-num.fr/datasphere/heimdall/python/-/tree/main/src/heimdall/connectors>`_ or `external <https://gitlab.huma-num.fr/datasphere/heimdall/connectors>`_ connector.
*************
Is it tested?
*************
Well, yes … and no.
| As you can see in our badge list, or in this `coverage report <https://datasphere.gitpages.huma-num.fr/heimdall/connectors/heurist/coverage/index.html>`_, the code coverage by our unit tests is not too shabby.
However, to validate their behaviour, these tests take the file ``/tests/resources/heurist.xml`` as an input, which simulates an exported XML ("HML") file from Heurist.
| And this is where the problem lies.
| At the time of writing (early 2025), Heurist still has an outdated comunity management and is full of undocumented behaviours.
Among these, the "HML" file remains unspecified, the link to its XSD is broken, and Heurist doesn't even behave as expected, when one feeds it its own output.
So, this connector really tries its best to deduce how stuff seems to work in most cases.
| This as two limits, though.
* 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 everybody seems fine today, 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.
| Unit testing with a static test file is, of course, not ideal.
But (you know the drill: "at time of writing") Heurist is devoid of any machine-usable API, let alone RESTful.
So there isn't really any other choice.
| As you may understand, by design of its own creator, third party softwares trying to be interoperable with Heurist are just … well, f•••ed.
| To conclude: depending on when you read this, you can install this connector, try to load a recently exported XML (HML) file, and if it doesn't work, you're probably f•••ed, too.
| That is, unless you contribute, of course.
*********************
How can I contribute?
*********************
PyHeimdall welcomes any feedback or proposal.
Details can be accessed `here <https://gitlab.huma-num.fr/datasphere/heimdall/python/-/blob/main/CONTRIBUTING.rst>`_
*******
License
*******
`GNU Affero General Public License version 3.0 or later <https://choosealicense.com/licenses/agpl/>`_
Raw data
{
"_id": null,
"home_page": null,
"name": "pyheimdall-heurist",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "databases, hera, interoperability",
"author": null,
"author_email": "R\u00e9gis Witz <regis.witz@cnrs.fr>",
"download_url": "https://files.pythonhosted.org/packages/37/39/76197d104d671bca3aafb5e5880998542f8c53654ec4be2cb93555e0a090/pyheimdall_heurist-1.2.0.tar.gz",
"platform": null,
"description": "################################\nHeimdall - Heurist XML connector\n################################\n\n.. image:: https://img.shields.io/badge/license-AGPL3.0-informational?logo=gnu&color=success\n :target: https://www.gnu.org/licenses/agpl-3.0.html\n.. image:: https://www.repostatus.org/badges/latest/unsupported.svg\n :target: https://www.repostatus.org/#project-statuses\n.. image:: https://img.shields.io/badge/documentation-api-green\n :target: https://datasphere.readthedocs.io/projects/heimdall/\n.. image:: https://gitlab.huma-num.fr/datasphere/heimdall/connectors/heurist/badges/main/pipeline.svg\n :target: https://gitlab.huma-num.fr/datasphere/heimdall/connectors/heurist/pipelines/latest\n.. image:: https://gitlab.huma-num.fr/datasphere/heimdall/connectors/heurist/badges/main/coverage.svg\n :target: https://datasphere.gitpages.huma-num.fr/heimdall/connectors/heurist/coverage/index.html\n\n*************\nWhat is this?\n*************\n\n`Heimdall <https://datasphere.readthedocs.io/projects/heimdall/>`_ is a tool for converting more easily one or more databases from one format to another.\nIt leverages modules called \"connectors\", responsible for conversion of data between specific databases schemas and the HERA format.\n\nThis repository contains a connector to Heurist's own XML export format (HML).\n\n********************\nWhy should I use it?\n********************\n\nYou can use this connector, along with the `pyheimdall software <https://gitlab.huma-num.fr/datasphere/heimdall/python>`_, to retrieve any data exported from Heurist.\nYou can then aggregate this data into your research corpus easily, for example using other Heimdall connectors.\n\n| Take note, however that some legal restrictions might apply to data retrieved from any scientific database.\n| Plus, if at the end of your project, you share your data, please cite the original data properly.\n\n*****************\nHow can I use it?\n*****************\n\nSetup\n=====\n\nThis pyHeimdall connector is available as a `PyPI package <https://pypi.org/project/pyheimdall-heurist/>`_ named ``pyheimdall-heurist``.\nYou can install it using the `pip <https://pip.pypa.io/en/stable/>`_ package manager:\n\n.. code-block:: bash\n\n pip install pyheimdall-heurist\n\nYou can use `pip <https://pip.pypa.io/en/stable/>`_ to either upgrade or uninstall this connector, too:\n\n.. code-block:: bash\n\n pip install --upgrade pyheimdall-heurist\n pip uninstall pyheimdall-heurist\n\n\n\nUsage\n=====\n\n.. code-block:: python\n\n import heimdall\n\n tree = heimdall.getDatabase(format='heurist:xml', url='Export_db_AAAAMMDDHHMMSS.xml')\n heimdall.createDatabase(tree, format='csv', url='.')\n\nPlease note that you shouldn't use ``pyheimdall-heurist`` functions directly.\nAs long as the package is installed on your system, pyHeimdall will automatically discover its features and allow you to use them as long as any other `default <https://gitlab.huma-num.fr/datasphere/heimdall/python/-/tree/main/src/heimdall/connectors>`_ or `external <https://gitlab.huma-num.fr/datasphere/heimdall/connectors>`_ connector.\n\n*************\nIs it tested?\n*************\n\nWell, yes \u2026 and no.\n\n| As you can see in our badge list, or in this `coverage report <https://datasphere.gitpages.huma-num.fr/heimdall/connectors/heurist/coverage/index.html>`_, the code coverage by our unit tests is not too shabby.\n However, to validate their behaviour, these tests take the file ``/tests/resources/heurist.xml`` as an input, which simulates an exported XML (\"HML\") file from Heurist.\n| And this is where the problem lies.\n| At the time of writing (early 2025), Heurist still has an outdated comunity management and is full of undocumented behaviours.\n Among these, the \"HML\" file remains unspecified, the link to its XSD is broken, and Heurist doesn't even behave as expected, when one feeds it its own output.\n So, this connector really tries its best to deduce how stuff seems to work in most cases.\n| This as two limits, though.\n\n* First, those assumptions can be wrong, or incomplete.\n Still at the time of writing, the Heurist core development team seems unable to document its own output, so \u2026 well.\n* Second, even if everybody seems fine today, the Heurist core development team is known to force unto its userbase new (sometimes breaking) updates without any prior notice, documentation or regression testing.\n 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.\n\n| Unit testing with a static test file is, of course, not ideal.\n But (you know the drill: \"at time of writing\") Heurist is devoid of any machine-usable API, let alone RESTful.\n So there isn't really any other choice.\n| As you may understand, by design of its own creator, third party softwares trying to be interoperable with Heurist are just \u2026 well, f\u2022\u2022\u2022ed.\n\n| To conclude: depending on when you read this, you can install this connector, try to load a recently exported XML (HML) file, and if it doesn't work, you're probably f\u2022\u2022\u2022ed, too.\n| That is, unless you contribute, of course.\n\n*********************\nHow can I contribute?\n*********************\n\nPyHeimdall welcomes any feedback or proposal.\nDetails can be accessed `here <https://gitlab.huma-num.fr/datasphere/heimdall/python/-/blob/main/CONTRIBUTING.rst>`_\n\n*******\nLicense\n*******\n\n`GNU Affero General Public License version 3.0 or later <https://choosealicense.com/licenses/agpl/>`_\n",
"bugtrack_url": null,
"license": "aGPL",
"summary": "Heurist connector for pyHeimdall",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://gitlab.huma-num.fr/datasphere/heimdall/connectors/heurist/",
"Issues": "https://gitlab.huma-num.fr/datasphere/heimdall/python/-/issues"
},
"split_keywords": [
"databases",
" hera",
" interoperability"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6b23e54d47f1de748a64e5bf6a307a2fe3a42277bde99dd754d6b6a26daea160",
"md5": "8e113ffab528019a677f520cc979357c",
"sha256": "550959406040efe9227def7dc925bc62d2fb8aa74dab60b514cc206782283d09"
},
"downloads": -1,
"filename": "pyheimdall_heurist-1.2.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "8e113ffab528019a677f520cc979357c",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 21023,
"upload_time": "2025-09-12T12:19:03",
"upload_time_iso_8601": "2025-09-12T12:19:03.333458Z",
"url": "https://files.pythonhosted.org/packages/6b/23/e54d47f1de748a64e5bf6a307a2fe3a42277bde99dd754d6b6a26daea160/pyheimdall_heurist-1.2.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "373976197d104d671bca3aafb5e5880998542f8c53654ec4be2cb93555e0a090",
"md5": "60ca320d9781c1ed23fc025fffee58bd",
"sha256": "0c75ffe8e3f26129db4cbaa6d5d5d797788b4e51c293bb1bf847b13a1c53ae3d"
},
"downloads": -1,
"filename": "pyheimdall_heurist-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "60ca320d9781c1ed23fc025fffee58bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 19820,
"upload_time": "2025-09-12T12:19:05",
"upload_time_iso_8601": "2025-09-12T12:19:05.028255Z",
"url": "https://files.pythonhosted.org/packages/37/39/76197d104d671bca3aafb5e5880998542f8c53654ec4be2cb93555e0a090/pyheimdall_heurist-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 12:19:05",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "pyheimdall-heurist"
}
JSON