Metadata-Version: 2.1
Name: omi
Version: 0.2.0
Summary: A library to process and translate open energy metadata.
Home-page: https://github.com/OpenEnergyPlatform/omi
Author: Martin Glauer
Author-email: martinglauer89@gmail.com
License: AGPL-3.0
Project-URL: Documentation, https://omi.readthedocs.io/
Project-URL: Changelog, https://omi.readthedocs.io/en/latest/changelog.html
Project-URL: Issue Tracker, https://github.com/MGlauer/omi/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Operating System :: Unix
Classifier: Operating System :: POSIX
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Utilities
Requires-Python: >=3.5
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: click
Requires-Dist: rdfLib
Requires-Dist: python-dateutil
Requires-Dist: jsonschema
Requires-Dist: oemetadata>=1.5.2
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"

==================================================
Open Energy Family - Open Metadata Integration OMI
==================================================

Overview
========



A library to process and translate open energy metadata.

* Free software: AGPL-3.0

Installation
============

::

    pip install omi

Documentation
=============


https://omi.readthedocs.io/

Usage
=====

**Parse, Compile, Render, Convert and Validate**
Omi can read(parse), compile, Render(json compilant), convert(convert metadata from v1.4 to v1.5 structure) and validate - a json 
file or object that is compliant with the oemetadata spec. This is usefull to do various operations that help to integrate with - as 
well as in interact with the oemetadata. Some parts of this tool might still be volatile but the code quality is conventionsly improved 
as this module is a core component of the oeplatfroms metadata integration system.

Check if omi is able to read a oemetadata file (for version 1.4 and 1.5)
CLI - oemetadata version 1.5::

    omi translate -f oep-v1.5 examples/data/metadata_v15.json

CLI - oemetadata version 1.4::

    omi translate -f oep-v1.4 -t oep-v1.4 examples/data/metadata_v14.json

omi is able to read a JSON file and parse it into one of the internal Python structures (depending on the oemetadata version). 
The OEPMetadata Python object can then be compiled and converted back to JSON. You can manipulate a successfully parsed 
OEPMetadata object.

Module usage::

    from omi.dialects.oep.dialect import OEP_V_1_3_Dialect, OEP_V_1_4_Dialect, OEP_V_1_5_Dialect
    inp = '{"id":"unique_id"}' #or read from json file
    dialect1_5 = OEP_V_1_5_Dialect()
    parsed = dialect1_5.parse(input)
    print(parsed)
    parsed.identifier = "another_unique_id"
    compiled = dialect1_5.compile(parsed)
    print(compiled)


**Conversion**

To ease the conversion of oemetadata from the outdated version 1.4 to the latest version, we provide
conversion functionality. The following example shows how to convert the oemetadata from v1.4 to v1.5
by using a CLI command.

CLI - oemetadata conversion from v1.4 to v1.5::

    omi convert -i {input/path} -o {output/path} 

**Validation**

The validation is based on `jsonschema`. We release a schema with each `oemetadata` release, that schema
can be used to validate the user metadata. The dialect currently does not support direct access on to the
validation. This will be updated soon.
This will create a report.json containing information to debug possible errors. The parser.validate() takes
two arguments the first one is the metadata and the second optional one is the schmea. By default (if no schema is passed)
the validation will try to get the matching schema for the current metadata.

Module usage::

    # You can import the JSONParser directly like this:
    import json
    from omi.dialects.oep.parser import JSONParser

    with open("tests/data/metadata_v15.json", "r", encoding="utf-8") as f:
        metadata = json.load(f)

    parser = JSONParser()
    parser.validate(metadata)
    
    # check if your metadata is valid for the given schmea 
    schema = ... get a schema or import form oemetadata module
    parser.is_valid(metadata, schema)

**Additional Fields - not related to the OEMetadata specification**

Sometimes it is necessary to store additional key-value pairs along with the keys included in the OEMetadata specification.
OMI's compiler methods are capable of handling additional arguments or key-value arguments, but this must be 
be explicitly specified. 

To add additional key-value pairs, you must: 

    NOTE: If you save the renderer return value in a json file and try to parse the file, the extra field is not included.
          You must read the json file using Python and then add the extra field back oemetadata object as shown below. 

1 Parse the oemetadata from json file / variable into omis internal structure::

    from omi.dialects.oep.dialect import OEP_V_1_5_Dialect

    min_inp = '{"id":"unique_id"} # or read from json file
    minimal_oemetadata15 = OEP_V_1_5_Dialect.parse(min_inp)

2 Now you can get(from json file)/define the additional data::

    data = "test"

3 And add it to the OEMetadata object that was parsed in step 1 by ading a key-value argument::

    compiled = OEP_V_1_5_Dialect.compile(minimal_oemetadata15, _additionalField=data)
    rendered = OEP_V_1_5_Dialect.render(compiled)

Development
===========

To install additional dependencies for development::

    pip install -e .[dev]

We encourage the use of pre-commit-hooks in this project. Those enforce some
formatting conventions (e.g. the use of `isort` and `black`). To enable hooks::

    pre-commit install

To run the all tests run::

    tox

Note, to combine the coverage data from all the tox environments run:

.. list-table::
    :widths: 10 90
    :stub-columns: 1

    - - Windows
      - ::

            set PYTEST_ADDOPTS=--cov-append
            tox

    - - Other
      - ::

            PYTEST_ADDOPTS=--cov-append tox


Changelog
=========

current (2024-XX-XX)
--------------------
* 

0.2.0 (2024-01-25)
--------------------
* Introduce OMIT_NONE_FIELDS in JSONCompiler class to ease removing / keeping none values in the metadata. By default None values are kept. (#72)[https://github.com/OpenEnergyPlatform/omi/pull/72]

0.1.2 (2023-01-27)
--------------------
* Fix datetime parser (PR#87)

0.1.1 (2022-11-29)
--------------------
* update parser for v15 to handle former v13 key names, also update outdated License (data-)class in oem_v15 structure. (PR#77)
* change the validation to return a report and enable report file creation option to the arguments of validation method. (PR#81)

0.1.0 (2022-11-18)
--------------------
* Add validation and helper functionality - validation based on json schema and the oemetadata schema files that are published for each release (PR#63)

0.0.9 (2022-10-31)
--------------------

* Fix bug that is raised if the input oemetadata does not contain the key _comment (PR#74) 

0.0.8 (2022-10-20)
--------------------

* Add conversion to translate oemetadata from v1.4 to v1.5
* Add conversion option to OMIs CLI application
* Add conversion additional script that converts oemetadata from v1.4 to v1.5 without using OMI. thanks to @chrwm

* Fix oeo related isAbout and valueReference field names (PR#65)
* Introduce github actions: Add automation worfklows for pypi publish for test and official (PR#67)
* Introduce new directory and provide some use cases and example implementation for omi usage and improve general code quality (PR#61)
* Reintroduce automated testing (CI) that icludes omi unit test (parser, compiler) and more (PR#69)

0.0.7 (2022-06-02)
------------------

* Add oem_structure module: Introcude support for multipe OEMetadata structure representations
* add new Dialect for OEM v15
* Full support (except for validation) for OEP-Metadata v1.5


0.0.6 (2020-07-08)
------------------

* Fix compilation of null values
* Fix parsing of lists


0.0.5 (2020-05-12)
------------------

* Fixed compiler for None in date fields


0.0.4 (2019-12-06)
------------------

* Improved documentation
* Full support of OEP-Metadata 1.4
* Support for optional fields in metadata strings
