| Name | ioprocmeta JSON |
| Version |
2.1.1
JSON |
| download |
| home_page | None |
| Summary | A lightweight library providing an ORM class representing the oep ontology. |
| upload_time | 2024-11-27 14:31:26 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | BSD 3-Clause License Copyright (c) 2022, DLR (Deutsches Zentrum für Luft- und Raumfahrt) All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
metadata management
oeo
open energy ontology
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# What is ioprocmeta
ioprocmeta is a library providing interfaces for writing and reading and processing meta data formats like the [Open Energy Platform meta data format 1.5.0](https://github.com/OpenEnergyPlatform/oemetadata).
The library currently implements only the OEP 1.5.0 meta data format, but can be extended to other meta data formats.
ioprocmeta provides:
- class based interface representing hierarchical meta data formats
- serialisation of the meta data into a text format (at the moment json)
- serialisation of the meta data format into python _dict()_
- checks for data consistency on the level of used data types and completeness of information
- provides a default valid meta data structure that can be used as a template
# Installation
ioprocmeta is pip installable via: `pip install ioprocmeta`.
If you use a virtual environment system like conda or virtualenv then the usual ceveats apply. Please activate/source your environment prior to installing ioprocmeta via pip.
Dependencies:
- attrs
- cattrs
# How to use
ioprocmeta provides interface classes, which represent a meta data format. Each class can be instantiated without input and will then contain defaults for all meta data fields.
To access the meta data classes ioprocmeta provides two ways. The first is by direct import:
```python
from ioprocmeta.oep import OEPMeta_1_5_0
meta_data = OEPMeta_1_5_0()
```
Alternatively you can also request a meta data class based on the identifier of the meta data format via the ioprocmeta registry:
```python
import ioprocmeta as prov
MetaDataClass = prov.available_standard_formats['oep150']
meta_data = MetaDataClass()
# the identifier of the meta data format can be accessed like this:
meta_data.type()
```
After creating a meta data instance you can provide information, more precisely set fields with the necessary information.
Here some examples for the oep meta data format in version 1.5.0:
```python
from ioprocmeta.oep import OEPMeta_1_5_0
meta_data = OEPMeta_1_5_0()
meta_data.name = 'Jane Doe'
```
Most meta data formats are hierarchical and have subsections for some of the stored information. To set information in a subsection a method call is usually required:
```python
meta_data.add_contributor(
title='John Doe',
email='John.Doe@doe.net',
date=datetime.date(1970, 1, 1),
_object=None,
comment='Personal correspondance',
)
```
After filling out the meta data field, you most likely would want to write the meta data as a json file to disk:
```python
meta_data.write_json(pathlib.Path('./meta.json'))
```
Alternatively you can also get the json string, if you do not want to write the data immediately to disk:
```python
meta_json = meta_data.as_json()
```
And if you want to make your own serialisation or work with a dictionary in python you can also get the data transformed:
```python
meta_dict = meta_data.as_dict()
```
If you want to know which fields to fill in a specific meta data specification, please look up the corresponding documentation of the meta data specification. There all information should be noted down and also which defaults are acceptable or what should be noted down for missing values.
# Good to know when using ioprocmeta
- subsections are created with interface methods like `add_license()`
- to parse meta data from a json string or a dict, please use the supplied interfaces on the class level with the following syntax: `meta = OEPMeta_1_5_0.from_json(json_data)`.
# Technical / design information
ioprocmeta relies heavily on attrs and cattr library to create an object related mapper to the underlying meta data files.
It provides read and write methods and serialization to json. The meta data objects are classes with attributes representing fields in the meta data specification.
Subsections or hierarchies in the meta data specification are implemented as classes that are integrated into a hierarchical class structure via composition.
One central design decision is, that each subsection in the meta data specification is interfaced with a method in the mother class. This method is responsible for creating an instance of the class representing the subsection and
for setting all values based on the arguments passed to the method.
An example for this is the subsection "license" in the OEP 1.5.0 which is represented by the class __OEPLicense_.
The mother class is in this case __OEPSource_ (section "source" in OEP 1.5.0) has implemented a method _add_license()_.
```python
def add_license(self, name, title, path, instruction, attribution):
...
```
The signature of the method indicates, that the license information required by OEP 1.5.0 is the name, title, path and so on.
The streaming of specific information with special datatypes that are not fundamental like int or bool, requires a special translation or serialisation interface.
The cattr library has a hook interface forseen for this occasion and ioprocmeta implements an appropriate class for this interface called _StructuringConverter_.
This structuring converter implements serialisations for _datetime.date_ and _pathlib.Path_ data types into string and back.
## Design quirks
- Subsections are implemented by generator methods that then create a class instance representing the substructure. The sub classes are not intended to be instantiated directly.
- Parsing methods like _from_dict_ or _from_json_, are implemented as classmethods or in other words as alternative constructors / factories which return a complete instance representing the provided data.
This has implications, as a custom serialisation for data types like _datetime.date_ is needed. Due to the design of attrs and cattrs it is currently necessary
to instantiate the serialisation class after the meta data class object is available. This could be solved by using the post init hook provided by cattrs and which could instantiate a serialisation interface class after the instance is initialized. This approach has two drawbacks. First, all constructor methods like _from_dict_ could not be implemented as classmethods and second the serialisation interface class could not be provided by inheritance. The second point would increase complexity for developers as they would be required to not only inherit from an abstract base class and follow the instructions there but also to have to implement an attrs post init hook to instantiate the serialisation interface. To circumvent this ioprocmeta decided to rely on an injection mechanism based on a decorator. The decorator, defined in the "base.py" module, checks if the __converter_ attribute (defined and inherited from the BaseMeta class) is set (in other words, is not set to None). If this is not the case, the decorator sets the attribute __converter_ to a new instance of the serialisation interface _StructuringConverter()_. This enables ioprocmeta the definition of generic interface class methods for serialisation into dict and json which can be inherited directly from the _BaseMeta_ class. To facilitate cleanup before and after serialisation, post processsing hooks are implemented as classmethods __post_as_dict_cleanup_ and __post_from_dict_cleanup_. These can be overridden in a meta data class definition to clean up fields after parsing a json file for example. Other serialisation methods should therefor be implemented in the BaseMeta class and not in any meta data class. Meta classes should implement, if needed, the hooks __post_as_dict_cleanup_ and __post_from_dict_cleanup_ as abstract class methods.
# License
ioprocmeta is available under BSD 3 clause.
# Contact
The library is developed by Benjamin Fuchs, Jan Buschmann and Felix Nitsch. If you want to get in touch, we recommend the gilab issue system. Or if you want to contact us via email then please refer to [Benjamin.Fuchs@dlr.de](mailto:Benjamin.Fuchs@dlr.de).
Raw data
{
"_id": null,
"home_page": null,
"name": "ioprocmeta",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Benjamin Fuchs <Benjamin.Fuchs@dlr.de>",
"keywords": "metadata management, oeo, open energy ontology",
"author": null,
"author_email": "Benjamin Fuchs <Benjamin.Fuchs@dlr.de>",
"download_url": "https://files.pythonhosted.org/packages/6a/1b/1afa72cfe9d18a87003377b8733a1e4d283c025212d5c4dc51409ecc058d/ioprocmeta-2.1.1.tar.gz",
"platform": null,
"description": "# What is ioprocmeta\n\nioprocmeta is a library providing interfaces for writing and reading and processing meta data formats like the [Open Energy Platform meta data format 1.5.0](https://github.com/OpenEnergyPlatform/oemetadata).\n\nThe library currently implements only the OEP 1.5.0 meta data format, but can be extended to other meta data formats.\n\nioprocmeta provides:\n\n- class based interface representing hierarchical meta data formats\n- serialisation of the meta data into a text format (at the moment json)\n- serialisation of the meta data format into python _dict()_\n- checks for data consistency on the level of used data types and completeness of information\n- provides a default valid meta data structure that can be used as a template\n\n# Installation\n\nioprocmeta is pip installable via: `pip install ioprocmeta`.\n\nIf you use a virtual environment system like conda or virtualenv then the usual ceveats apply. Please activate/source your environment prior to installing ioprocmeta via pip.\n\nDependencies:\n\n- attrs\n- cattrs\n\n# How to use\n\nioprocmeta provides interface classes, which represent a meta data format. Each class can be instantiated without input and will then contain defaults for all meta data fields.\n\nTo access the meta data classes ioprocmeta provides two ways. The first is by direct import:\n\n```python\nfrom ioprocmeta.oep import OEPMeta_1_5_0\n\nmeta_data = OEPMeta_1_5_0()\n\n```\n\nAlternatively you can also request a meta data class based on the identifier of the meta data format via the ioprocmeta registry:\n\n```python\nimport ioprocmeta as prov\n\nMetaDataClass = prov.available_standard_formats['oep150']\nmeta_data = MetaDataClass()\n\n# the identifier of the meta data format can be accessed like this:\nmeta_data.type()\n```\n\nAfter creating a meta data instance you can provide information, more precisely set fields with the necessary information.\nHere some examples for the oep meta data format in version 1.5.0:\n\n```python\nfrom ioprocmeta.oep import OEPMeta_1_5_0\n\nmeta_data = OEPMeta_1_5_0()\n\nmeta_data.name = 'Jane Doe'\n```\n\nMost meta data formats are hierarchical and have subsections for some of the stored information. To set information in a subsection a method call is usually required:\n\n```python\nmeta_data.add_contributor(\n title='John Doe', \n email='John.Doe@doe.net', \n date=datetime.date(1970, 1, 1), \n _object=None, \n comment='Personal correspondance',\n)\n```\n\nAfter filling out the meta data field, you most likely would want to write the meta data as a json file to disk:\n\n```python\nmeta_data.write_json(pathlib.Path('./meta.json'))\n```\n\nAlternatively you can also get the json string, if you do not want to write the data immediately to disk:\n\n```python\nmeta_json = meta_data.as_json()\n```\n\nAnd if you want to make your own serialisation or work with a dictionary in python you can also get the data transformed:\n\n```python\nmeta_dict = meta_data.as_dict()\n```\n\nIf you want to know which fields to fill in a specific meta data specification, please look up the corresponding documentation of the meta data specification. There all information should be noted down and also which defaults are acceptable or what should be noted down for missing values.\n\n# Good to know when using ioprocmeta\n\n- subsections are created with interface methods like `add_license()`\n- to parse meta data from a json string or a dict, please use the supplied interfaces on the class level with the following syntax: `meta = OEPMeta_1_5_0.from_json(json_data)`.\n\n# Technical / design information\n\nioprocmeta relies heavily on attrs and cattr library to create an object related mapper to the underlying meta data files.\nIt provides read and write methods and serialization to json. The meta data objects are classes with attributes representing fields in the meta data specification.\n\nSubsections or hierarchies in the meta data specification are implemented as classes that are integrated into a hierarchical class structure via composition.\n\nOne central design decision is, that each subsection in the meta data specification is interfaced with a method in the mother class. This method is responsible for creating an instance of the class representing the subsection and\nfor setting all values based on the arguments passed to the method.\n\nAn example for this is the subsection \"license\" in the OEP 1.5.0 which is represented by the class __OEPLicense_.\nThe mother class is in this case __OEPSource_ (section \"source\" in OEP 1.5.0) has implemented a method _add_license()_.\n\n```python\ndef add_license(self, name, title, path, instruction, attribution):\n ...\n```\n\nThe signature of the method indicates, that the license information required by OEP 1.5.0 is the name, title, path and so on.\n\nThe streaming of specific information with special datatypes that are not fundamental like int or bool, requires a special translation or serialisation interface.\nThe cattr library has a hook interface forseen for this occasion and ioprocmeta implements an appropriate class for this interface called _StructuringConverter_.\nThis structuring converter implements serialisations for _datetime.date_ and _pathlib.Path_ data types into string and back.\n\n## Design quirks\n\n- Subsections are implemented by generator methods that then create a class instance representing the substructure. The sub classes are not intended to be instantiated directly.\n- Parsing methods like _from_dict_ or _from_json_, are implemented as classmethods or in other words as alternative constructors / factories which return a complete instance representing the provided data.\nThis has implications, as a custom serialisation for data types like _datetime.date_ is needed. Due to the design of attrs and cattrs it is currently necessary\nto instantiate the serialisation class after the meta data class object is available. This could be solved by using the post init hook provided by cattrs and which could instantiate a serialisation interface class after the instance is initialized. This approach has two drawbacks. First, all constructor methods like _from_dict_ could not be implemented as classmethods and second the serialisation interface class could not be provided by inheritance. The second point would increase complexity for developers as they would be required to not only inherit from an abstract base class and follow the instructions there but also to have to implement an attrs post init hook to instantiate the serialisation interface. To circumvent this ioprocmeta decided to rely on an injection mechanism based on a decorator. The decorator, defined in the \"base.py\" module, checks if the __converter_ attribute (defined and inherited from the BaseMeta class) is set (in other words, is not set to None). If this is not the case, the decorator sets the attribute __converter_ to a new instance of the serialisation interface _StructuringConverter()_. This enables ioprocmeta the definition of generic interface class methods for serialisation into dict and json which can be inherited directly from the _BaseMeta_ class. To facilitate cleanup before and after serialisation, post processsing hooks are implemented as classmethods __post_as_dict_cleanup_ and __post_from_dict_cleanup_. These can be overridden in a meta data class definition to clean up fields after parsing a json file for example. Other serialisation methods should therefor be implemented in the BaseMeta class and not in any meta data class. Meta classes should implement, if needed, the hooks __post_as_dict_cleanup_ and __post_from_dict_cleanup_ as abstract class methods.\n\n# License\n\nioprocmeta is available under BSD 3 clause.\n\n# Contact\n\nThe library is developed by Benjamin Fuchs, Jan Buschmann and Felix Nitsch. If you want to get in touch, we recommend the gilab issue system. Or if you want to contact us via email then please refer to [Benjamin.Fuchs@dlr.de](mailto:Benjamin.Fuchs@dlr.de).\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2022, DLR (Deutsches Zentrum f\u00fcr Luft- und Raumfahrt) All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": "A lightweight library providing an ORM class representing the oep ontology.",
"version": "2.1.1",
"project_urls": {
"homepage": "https://gitlab.com/dlr-ve/esy/ioprocmeta"
},
"split_keywords": [
"metadata management",
" oeo",
" open energy ontology"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2db7bc550f66b6598763bebcc2d935ab163f80f4da51358c2fa795c857981e96",
"md5": "ccf0b24adcc9697b8570b12ecbd0d871",
"sha256": "04c1af42f76bae2ce62f9ba45eb9a342f709050e36b4e78a5073f63859a50a9a"
},
"downloads": -1,
"filename": "ioprocmeta-2.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ccf0b24adcc9697b8570b12ecbd0d871",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 10331,
"upload_time": "2024-11-27T14:31:24",
"upload_time_iso_8601": "2024-11-27T14:31:24.181214Z",
"url": "https://files.pythonhosted.org/packages/2d/b7/bc550f66b6598763bebcc2d935ab163f80f4da51358c2fa795c857981e96/ioprocmeta-2.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6a1b1afa72cfe9d18a87003377b8733a1e4d283c025212d5c4dc51409ecc058d",
"md5": "7427214bc03da33541f10392e2849686",
"sha256": "1e78f860302feca585d093ff465be4a7664d7383bf2f2c912e87cd7bf961d6ef"
},
"downloads": -1,
"filename": "ioprocmeta-2.1.1.tar.gz",
"has_sig": false,
"md5_digest": "7427214bc03da33541f10392e2849686",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 174118,
"upload_time": "2024-11-27T14:31:26",
"upload_time_iso_8601": "2024-11-27T14:31:26.179385Z",
"url": "https://files.pythonhosted.org/packages/6a/1b/1afa72cfe9d18a87003377b8733a1e4d283c025212d5c4dc51409ecc058d/ioprocmeta-2.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-27 14:31:26",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "dlr-ve",
"gitlab_project": "esy",
"lcname": "ioprocmeta"
}
