docs | |
---|---|
tests | |
package |
A library to process and translate open energy metadata.
- Free software: AGPL-3.0
pip install omi
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)
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:
Windows | set PYTEST_ADDOPTS=--cov-append tox |
---|---|
Other | PYTEST_ADDOPTS=--cov-append tox |