=============
DataModelDict
=============
Introduction
------------
The DataModelDict class is used for handling data models that have equivalent
representations in XML, JSON, and Python. Constructing data models in this
way is convenient as it supports compatibility across different software
tools, such as different types of databases.
The DataModelDict class:
- is a child of OrderedDict,
- has methods for converting to/from XML and JSON,
- has methods for searching through elements, and
- has methods that help with constructing and interacting with compliant data
models.
Setup
-----
The code has no requirements that limit which systems it can be used on, i.e.
it should work on Linux, Mac and Windows computers.
The latest release can be installed using pip::
pip install DataModelDict
The code and all documentation is hosted on GitHub and can be directly
downloaded at `https://github.com/usnistgov/DataModelDict`_.
.. _https://github.com/usnistgov/DataModelDict:
https://github.com/usnistgov/DataModelDict
Conversions
-----------
Some considerations need to be taken into account for designing data models
that allow for exact reversible transformations between the three formats:
- Valid, full XML requires that there is exactly one root element. In other
words, the top-level DataModelDict of a data model can have only one key.
- Do not use lists of lists for representing data. The XML conversions are
only reversible for lists of values or lists of dictionaries. Future
updates may allow this.
- Avoid using XML attributes if possible. While the XML conversions do
reversibly handle attributes, it complicates the Python and JSON
representations.
- Embedded XML content, i.e. "text with <embed>embedded</embed> content",
might not be reversible:
- If this is in a Python/JSON value, converting to XML gives "text with
&lt;embed&gt;embedded&lt;/embed&gt; content". This is
reversible.
- If this is an XML text field, parsing to Python pulls the embedded
elements out of the text, which is not reversible!
- XML subelements of the same name within an element should be given
consecutively. When parsed, all values of subelements of the same name are
collected together in a list. This will alter the original order of
subelements if matching names were not originally consecutive.
Conversion from Python to JSON
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Python-JSON conversions use the standard Python JSON library. In
converting from Python to JSON, all elements of the DataModelDict must be an
instance of a supported data type.
================ =========
Python JSON
================ =========
dict object
list, tuple array
str string
int, float number
True true
False false
None null
np.nan NaN
np.inf Infinity
-np.inf -Infinity
================ =========
As DataModelDict is a child of OrderedDict, it registers as being an instance
of dict. Any other objects would first need to be converted to one of these
types, e.g. a numpy array would need to be converted to a list.
Conversion from Python to XML
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Python-XML conversions use the xmltodict Python package. The XML content
is constructed based on the Python data types.
================ ================
Python XML
================ ================
dict subelement
list, tuple repeated element
str text
int, float repr(val)
True 'true'
False 'false'
None ''
np.nan 'NaN'
np.inf 'Infinity'
-np.inf '-Infinity'
================ ================
Some characters in the XML text fields will also be converted to avoid
conflicts.
- XML limited characters such as <, > and & are converted to their
HTML entities.
- \\n, \\t, \\r are converted to \\\\n, \\\\t, and \\\\r
Any dictionary keys starting with '@' will be converted into XML attributes,
and the dictionary key '#text' is interpreted as the text value of the
element.
Conversion from JSON to Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Python-JSON conversions use the standard Python JSON library. In
converting from JSON to Python, the conversions of types is straight-forward.
============= =============
JSON Python
============= =============
object DataModelDict
array list
string str
number (int) int
number (real) float
true True
false False
null None
NaN np.nan
Infinity np.inf
-Infinity -np.inf
============= =============
Conversion from XML to Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Python-XML conversions use the xmltodict Python package. The text fields
will be interpreted based on the following sequential tests:
======================================== ========
XML text Python
======================================== ========
text == 'True' or 'true' True
text == 'False' or 'false' False
text == '' None
text == 'NaN' np.nan
text == 'Infinity' np.inf
text == '-Infinity' -np.inf
try int(text) and text == str(int(text)) int
try float(text) float
otherwise str
======================================== ========
The int conversion test was updated for version 0.9.8 to check that the values
can reversably be changed back into a str. This is necessary to properly
handle values, such as journal page numbers, that may contain leading zeroes.
The reverse conversions are done for the special characters mentioned in the
Conversion from Python to XML section above.
Any 'attr' attribute fields are converted to elements named '\@attr' and
corresponding '#text' elements are created if needed.
Code Documentation
------------------
=============
DataModelDict
=============
Introduction
------------
The DataModelDict class is used for handling data models that have equivalent
representations in XML, JSON, and Python. Constructing data models in this
way is convenient as it supports compatibility across different software
tools, such as different types of databases.
The DataModelDict class:
- is a child of OrderedDict,
- has methods for converting to/from XML and JSON,
- has methods for searching through elements, and
- has methods that help with constructing and interacting with compliant data
models.
Setup
-----
The code has no requirements that limit which systems it can be used on, i.e.
it should work on Linux, Mac and Windows computers.
The latest release can be installed using pip::
pip install DataModelDict
The code and all documentation is hosted on GitHub and can be directly
downloaded at `https://github.com/usnistgov/DataModelDict`_.
.. _https://github.com/usnistgov/DataModelDict:
https://github.com/usnistgov/DataModelDict
Conversions
-----------
Some considerations need to be taken into account for designing data models
that allow for exact reversible transformations between the three formats:
- Valid, full XML requires that there is exactly one root element. In other
words, the top-level DataModelDict of a data model can have only one key.
- Do not use lists of lists for representing data. The XML conversions are
only reversible for lists of values or lists of dictionaries. Future
updates may allow this.
- Avoid using XML attributes if possible. While the XML conversions do
reversibly handle attributes, it complicates the Python and JSON
representations.
- Embedded XML content, i.e. "text with <embed>embedded</embed> content",
might not be reversible:
- If this is in a Python/JSON value, converting to XML gives "text with
&lt;embed&gt;embedded&lt;/embed&gt; content". This is
reversible.
- If this is an XML text field, parsing to Python pulls the embedded
elements out of the text, which is not reversible!
- XML subelements of the same name within an element should be given
consecutively. When parsed, all values of subelements of the same name are
collected together in a list. This will alter the original order of
subelements if matching names were not originally consecutive.
Conversion from Python to JSON
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Python-JSON conversions use the standard Python JSON library. In
converting from Python to JSON, all elements of the DataModelDict must be an
instance of a supported data type.
================ =========
Python JSON
================ =========
dict object
list, tuple array
str string
int, float number
True true
False false
None null
np.nan NaN
np.inf Infinity
-np.inf -Infinity
================ =========
As DataModelDict is a child of OrderedDict, it registers as being an instance
of dict. Any other objects would first need to be converted to one of these
types, e.g. a numpy array would need to be converted to a list.
Conversion from Python to XML
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Python-XML conversions use the xmltodict Python package. The XML content
is constructed based on the Python data types.
================ ================
Python XML
================ ================
dict subelement
list, tuple repeated element
str text
int, float repr(val)
True 'true'
False 'false'
None ''
np.nan 'NaN'
np.inf 'Infinity'
-np.inf '-Infinity'
================ ================
Some characters in the XML text fields will also be converted to avoid
conflicts.
- XML limited characters such as <, > and & are converted to their
HTML entities.
- \\n, \\t, \\r are converted to \\\\n, \\\\t, and \\\\r
Any dictionary keys starting with '@' will be converted into XML attributes,
and the dictionary key '#text' is interpreted as the text value of the
element.
Conversion from JSON to Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Python-JSON conversions use the standard Python JSON library. In
converting from JSON to Python, the conversions of types is straight-forward.
============= =============
JSON Python
============= =============
object DataModelDict
array list
string str
number (int) int
number (real) float
true True
false False
null None
NaN np.nan
Infinity np.inf
-Infinity -np.inf
============= =============
Conversion from XML to Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The Python-XML conversions use the xmltodict Python package. The text fields
will be interpreted based on the following sequential tests:
======================================== ========
XML text Python
======================================== ========
text == 'True' or 'true' True
text == 'False' or 'false' False
text == '' None
text == 'NaN' np.nan
text == 'Infinity' np.inf
text == '-Infinity' -np.inf
try int(text) and text == str(int(text)) int
try float(text) float
otherwise str
======================================== ========
The int conversion test was updated for version 0.9.8 to check that the values
can reversably be changed back into a str. This is necessary to properly
handle values, such as journal page numbers, that may contain leading zeroes.
The reverse conversions are done for the special characters mentioned in the
Conversion from Python to XML section above.
Any 'attr' attribute fields are converted to elements named '\@attr' and
corresponding '#text' elements are created if needed.
Class Documentation
-------------------
**class DataModelDict.DataModelDict(*args, kwargs)**
Bases: ``collections.OrderedDict``
Class for handling json/xml equivalent data structures.
**append(key, value)**
Adds a value for element key by either adding key to the
dictionary or appending the value as a list to any current
value.
:Parameters:
* **key** (*str*) – The dictionary key.
* **value** – The value to add to the dictionary key. If
key exists, the element is converted to a list if needed
and value is appended.
**aslist(key)**
Gets the value of a dictionary key as a list. Useful for
elements whose values may or may not be lists.
:Parameters:
**key** (*str*) – Dictionary key
:Returns:
The dictionary’s element value or [value] depending on if it
already is a list.
:Return type:
list
**find(key, yes={}, no={})**
Return the value of a subelement at any level uniquely
identified by the specified conditions.
:Parameters:
* **key** (*str*) – Dictionary key to search for.
* **yes** (*dict*) – Key-value terms which the subelement
must have to be considered a match.
* **no** (*dict*) – Key-value terms which the subelement
must not have to be considered a match.
:Returns:
The value of the uniquely identified subelement.
:Return type:
any
:Raises:
**ValueError** – If exactly one matching subelement is not
identified.
**finds(key, yes={}, no={})**
Finds the values of all subelements at any level identified by
the specified conditions.
:Parameters:
* **key** (*str*) – Dictionary key to search for.
* **yes** (*dict*) – Key-value terms which the subelement
must have to be considered a match.
* **no** (*dict*) – Key-value terms which the subelement
must not have to be considered a match.
:Returns:
The values of any matching subelements.
:Return type:
list
**iteraslist(key)**
Iterates through the values of a dictionary key. Useful for
elements whose values may or may not be lists.
:Parameters:
**key** (*str*) – Dictionary key
:Yields:
*any* – The dictionary’s value or each element in value if
value is a list.
**iterfinds(key, yes={}, no={})**
Iterates over the values of all subelements at any level
identified by the specified conditions.
:Parameters:
* **key** (*str*) – Dictionary key to search for.
* **yes** (*dict*) – Key-value terms which the subelement
must have to be considered a match.
* **no** (*dict*) – Key-value terms which the subelement
must not have to be considered a match.
:Yields:
*any* – The values of any matching subelements.
**iterpaths(key, yes={}, no={})**
Iterates over the path lists to all elements at any level
identified by the specified conditions.
:Parameters:
* **key** (*str*) – Dictionary key to search for.
* **yes** (*dict*) – Key-value terms which the subelement
must have to be considered a match.
* **no** (*dict*) – Key-value terms which the subelement
must not have to be considered a match.
:Yields:
*list of str* – The path lists to any matching subelements.
**itervaluepaths()**
Iterates over path lists to all value elements at any level.
:Yields:
*list* – The path lists to all value subelements.
**json(fp=None, *args, kwargs)**
Converts the DataModelDict to JSON content.
:Parameters:
* **fp** (*file-like object or None, optional*) – An
open file to write the content to. If None (default),
then the content is returned as a str.
* ***args** (*any*) – Any other positional arguments
accepted by json.dump(s)
* ****kwargs** (*any*) – Any other keyword arguments
accepted by json.dump(s)
:Returns:
The JSON content (only returned if fp is None).
:Return type:
str, optional
**load(model, format=None)**
Read in values from a json/xml string or file-like object.
:Parameters:
* **model** (*str or file-like object*) – The XML or
JSON content to read. This is allowed to be either a file
path, a string representation, or an open file-like object
in byte mode.
* **format** (*str or None, optional*) – Allows for
the format of the content to be explicitly stated (‘xml’
or ‘json’). If None (default), will try to determine
which format based on if the first character of model is
‘<’ or ‘{‘.
:Raises:
**ValueError** – If format is None and unable to identify
XML/JON content, or if format is not equal to ‘xml’ or
‘json’.
**path(key, yes={}, no={})**
Return the path list of a subelement at any level uniquely
identified by the specified conditions. Issues an error if
either no match, or multiple matches are found.
:Parameters:
* **key** (*str*) – Dictionary key to search for.
* **yes** (*dict*) – Key-value terms which the subelement
must have to be considered a match.
* **no** (*dict*) – Key-value terms which the subelement
must not have to be considered a match.
:Returns:
The subelement path list to the uniquely identified
subelement.
:Return type:
list of str
:Raises:
**ValueError** – If exactly one matching subelement is not
identified.
**paths(key, yes={}, no={})**
Return a list of all path lists of all elements at any level
identified by the specified conditions.
:Parameters:
* **key** (*str*) – Dictionary key to search for.
* **yes** (*dict*) – Key-value terms which the subelement
must have to be considered a match.
* **no** (*dict*) – Key-value terms which the subelement
must not have to be considered a match.
:Returns:
The path lists for any matching subelements.
:Return type:
list
**xml(fp=None, indent=None, kwargs)**
Return the DataModelDict as XML content.
:Parameters:
* **fp** (*file-like object or None, optional*) – An
open file to write the content to. If None (default),
then the content is returned as a str.
* **indent** (*int, str or None, optional*) – If
int, number of spaces to indent lines. If str, will use
that as the indentation. If None (default), the content
will be inline.
* ****kwargs** (*any*) – Other keywords supported by
xmltodict.unparse, except for output which is replaced by
fp, and preprocessor, which is controlled.
:Returns:
The XML content (only returned if fp is None).
:Return type:
str, optional
**DataModelDict.joinpath(path: list, delimiter: str = '.',
openbracket: str = '[', closebracket: str = ']') -> str**
Takes a path as a list and transforms it into a string.
:Parameters:
* **path** (*list*) – The path list to join.
* **delimiter** (*str*) – The delimiter between subsequent
element names.
* **openbracket** (*str*) – The opening indicator of list
indices.
* **closebracket** (*str*) – The closing indicator of list
indices.
:Return type:
The path as a delimited string.
**DataModelDict.parsepath(pathstr: str, delimiter: str = '.',
openbracket: str = '[', closebracket: str = ']') -> list**
Takes a path as a string and parses it into a list of terms.
:Parameters:
* **pathstr** (*str*) – The path string to parse.
* **delimiter** (*str*) – The delimiter between subsequent
element names.
* **openbracket** (*str*) – The opening indicator of list
indices.
* **closebracket** (*str*) – The closing indicator of list
indices.
:Returns:
The path as a list.
:Return type:
list
**DataModelDict.uber_open_rmode(data: Union[str, bytes, pathlib.Path,
io.IOBase]) -> io.IOBase**
Provides a uniform means of reading data from files, file-like
objects, and string/bytes content.
:Parameters:
**data** (*file-like object, file path, or str/bytes
file content*) – The data that will be opened for reading.
:Returns:
An open file-like object that is in a bytes read mode. If a
file-like object is given, it is passed through after checking
that it is for bytes content. If a file path is given, the file
is opened in ‘rb’ mode. If bytes or string content is given,
the content is returned in a BytesIO object.
:Return type:
file-like object
:Raises:
* **ValueError** – If a file-like object in text mode is given.
* **TypeError** – If data is not a file-like object, bytes, str
or Path.
* **FileNotFoundError** – If data is a pathlib.Path object and
is not an existing file.
Raw data
{
"_id": null,
"home_page": "https://github.com/usnistgov/DataModelDict/",
"name": "DataModelDict",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "json,xml,dictionary",
"author": "Lucas Hale",
"author_email": "lucas.hale@nist.gov",
"download_url": "https://files.pythonhosted.org/packages/51/da/c5709322a1ddab201d37e2614edb1a90c6b64d5c0f02f9eae70f26847075/DataModelDict-0.9.9.tar.gz",
"platform": "",
"description": "=============\nDataModelDict\n=============\n\nIntroduction\n------------\n\nThe DataModelDict class is used for handling data models that have equivalent\nrepresentations in XML, JSON, and Python. Constructing data models in this\nway is convenient as it supports compatibility across different software\ntools, such as different types of databases.\n\nThe DataModelDict class:\n\n- is a child of OrderedDict,\n- has methods for converting to/from XML and JSON, \n- has methods for searching through elements, and\n- has methods that help with constructing and interacting with compliant data\n models.\n\nSetup\n-----\n\nThe code has no requirements that limit which systems it can be used on, i.e.\nit should work on Linux, Mac and Windows computers.\n\nThe latest release can be installed using pip::\n\n pip install DataModelDict\n\nThe code and all documentation is hosted on GitHub and can be directly\ndownloaded at `https://github.com/usnistgov/DataModelDict`_.\n\n.. _https://github.com/usnistgov/DataModelDict: \n https://github.com/usnistgov/DataModelDict\n\nConversions\n-----------\n\nSome considerations need to be taken into account for designing data models\nthat allow for exact reversible transformations between the three formats:\n\n- Valid, full XML requires that there is exactly one root element. In other\n words, the top-level DataModelDict of a data model can have only one key.\n- Do not use lists of lists for representing data. The XML conversions are\n only reversible for lists of values or lists of dictionaries. Future\n updates may allow this.\n- Avoid using XML attributes if possible. While the XML conversions do\n reversibly handle attributes, it complicates the Python and JSON\n representations.\n- Embedded XML content, i.e. \"text with <embed>embedded</embed> content\",\n might not be reversible:\n\n - If this is in a Python/JSON value, converting to XML gives \"text with\n &lt;embed&gt;embedded&lt;/embed&gt; content\". This is\n reversible.\n - If this is an XML text field, parsing to Python pulls the embedded\n elements out of the text, which is not reversible!\n\n- XML subelements of the same name within an element should be given\n consecutively. When parsed, all values of subelements of the same name are\n collected together in a list. This will alter the original order of\n subelements if matching names were not originally consecutive. \n\nConversion from Python to JSON\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Python-JSON conversions use the standard Python JSON library. In\nconverting from Python to JSON, all elements of the DataModelDict must be an\ninstance of a supported data type.\n\n================ =========\nPython JSON \n================ =========\ndict object \nlist, tuple array \nstr string \nint, float number \nTrue true \nFalse false \nNone null \nnp.nan NaN \nnp.inf Infinity \n-np.inf -Infinity\n================ =========\n\nAs DataModelDict is a child of OrderedDict, it registers as being an instance\nof dict. Any other objects would first need to be converted to one of these\ntypes, e.g. a numpy array would need to be converted to a list.\n\nConversion from Python to XML\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Python-XML conversions use the xmltodict Python package. The XML content\nis constructed based on the Python data types.\n\n================ ================\nPython XML \n================ ================\ndict subelement \nlist, tuple repeated element\nstr text \nint, float repr(val) \nTrue 'true' \nFalse 'false' \nNone '' \nnp.nan 'NaN' \nnp.inf 'Infinity' \n-np.inf '-Infinity' \n================ ================\n\nSome characters in the XML text fields will also be converted to avoid\nconflicts.\n\n- XML limited characters such as <, > and & are converted to their\n HTML entities.\n- \\\\n, \\\\t, \\\\r are converted to \\\\\\\\n, \\\\\\\\t, and \\\\\\\\r\n\nAny dictionary keys starting with '@' will be converted into XML attributes,\nand the dictionary key '#text' is interpreted as the text value of the\nelement.\n\nConversion from JSON to Python\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Python-JSON conversions use the standard Python JSON library. In\nconverting from JSON to Python, the conversions of types is straight-forward.\n\n============= =============\nJSON Python \n============= =============\nobject DataModelDict\narray list \nstring str \nnumber (int) int \nnumber (real) float \ntrue True \nfalse False \nnull None \nNaN np.nan \nInfinity np.inf \n-Infinity -np.inf \n============= =============\n\nConversion from XML to Python\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Python-XML conversions use the xmltodict Python package. The text fields\nwill be interpreted based on the following sequential tests:\n\n======================================== ========\nXML text Python \n======================================== ========\ntext == 'True' or 'true' True \ntext == 'False' or 'false' False \ntext == '' None \ntext == 'NaN' np.nan \ntext == 'Infinity' np.inf \ntext == '-Infinity' -np.inf \ntry int(text) and text == str(int(text)) int \ntry float(text) float \notherwise str \n======================================== ========\n\nThe int conversion test was updated for version 0.9.8 to check that the values\ncan reversably be changed back into a str. This is necessary to properly\nhandle values, such as journal page numbers, that may contain leading zeroes.\n\nThe reverse conversions are done for the special characters mentioned in the\nConversion from Python to XML section above.\n\nAny 'attr' attribute fields are converted to elements named '\\@attr' and\ncorresponding '#text' elements are created if needed.\n\nCode Documentation\n------------------\n\n=============\nDataModelDict\n=============\n\nIntroduction\n------------\n\nThe DataModelDict class is used for handling data models that have equivalent\nrepresentations in XML, JSON, and Python. Constructing data models in this\nway is convenient as it supports compatibility across different software\ntools, such as different types of databases.\n\nThe DataModelDict class:\n\n- is a child of OrderedDict,\n- has methods for converting to/from XML and JSON, \n- has methods for searching through elements, and\n- has methods that help with constructing and interacting with compliant data\n models.\n\nSetup\n-----\n\nThe code has no requirements that limit which systems it can be used on, i.e.\nit should work on Linux, Mac and Windows computers.\n\nThe latest release can be installed using pip::\n\n pip install DataModelDict\n\nThe code and all documentation is hosted on GitHub and can be directly\ndownloaded at `https://github.com/usnistgov/DataModelDict`_.\n\n.. _https://github.com/usnistgov/DataModelDict: \n https://github.com/usnistgov/DataModelDict\n\nConversions\n-----------\n\nSome considerations need to be taken into account for designing data models\nthat allow for exact reversible transformations between the three formats:\n\n- Valid, full XML requires that there is exactly one root element. In other\n words, the top-level DataModelDict of a data model can have only one key.\n- Do not use lists of lists for representing data. The XML conversions are\n only reversible for lists of values or lists of dictionaries. Future\n updates may allow this.\n- Avoid using XML attributes if possible. While the XML conversions do\n reversibly handle attributes, it complicates the Python and JSON\n representations.\n- Embedded XML content, i.e. \"text with <embed>embedded</embed> content\",\n might not be reversible:\n\n - If this is in a Python/JSON value, converting to XML gives \"text with\n &lt;embed&gt;embedded&lt;/embed&gt; content\". This is\n reversible.\n - If this is an XML text field, parsing to Python pulls the embedded\n elements out of the text, which is not reversible!\n\n- XML subelements of the same name within an element should be given\n consecutively. When parsed, all values of subelements of the same name are\n collected together in a list. This will alter the original order of\n subelements if matching names were not originally consecutive. \n\nConversion from Python to JSON\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Python-JSON conversions use the standard Python JSON library. In\nconverting from Python to JSON, all elements of the DataModelDict must be an\ninstance of a supported data type.\n\n================ =========\nPython JSON \n================ =========\ndict object \nlist, tuple array \nstr string \nint, float number \nTrue true \nFalse false \nNone null \nnp.nan NaN \nnp.inf Infinity \n-np.inf -Infinity\n================ =========\n\nAs DataModelDict is a child of OrderedDict, it registers as being an instance\nof dict. Any other objects would first need to be converted to one of these\ntypes, e.g. a numpy array would need to be converted to a list.\n\nConversion from Python to XML\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Python-XML conversions use the xmltodict Python package. The XML content\nis constructed based on the Python data types.\n\n================ ================\nPython XML \n================ ================\ndict subelement \nlist, tuple repeated element\nstr text \nint, float repr(val) \nTrue 'true' \nFalse 'false' \nNone '' \nnp.nan 'NaN' \nnp.inf 'Infinity' \n-np.inf '-Infinity' \n================ ================\n\nSome characters in the XML text fields will also be converted to avoid\nconflicts.\n\n- XML limited characters such as <, > and & are converted to their\n HTML entities.\n- \\\\n, \\\\t, \\\\r are converted to \\\\\\\\n, \\\\\\\\t, and \\\\\\\\r\n\nAny dictionary keys starting with '@' will be converted into XML attributes,\nand the dictionary key '#text' is interpreted as the text value of the\nelement.\n\nConversion from JSON to Python\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Python-JSON conversions use the standard Python JSON library. In\nconverting from JSON to Python, the conversions of types is straight-forward.\n\n============= =============\nJSON Python \n============= =============\nobject DataModelDict\narray list \nstring str \nnumber (int) int \nnumber (real) float \ntrue True \nfalse False \nnull None \nNaN np.nan \nInfinity np.inf \n-Infinity -np.inf \n============= =============\n\nConversion from XML to Python\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe Python-XML conversions use the xmltodict Python package. The text fields\nwill be interpreted based on the following sequential tests:\n\n======================================== ========\nXML text Python \n======================================== ========\ntext == 'True' or 'true' True \ntext == 'False' or 'false' False \ntext == '' None \ntext == 'NaN' np.nan \ntext == 'Infinity' np.inf \ntext == '-Infinity' -np.inf \ntry int(text) and text == str(int(text)) int \ntry float(text) float \notherwise str \n======================================== ========\n\nThe int conversion test was updated for version 0.9.8 to check that the values\ncan reversably be changed back into a str. This is necessary to properly\nhandle values, such as journal page numbers, that may contain leading zeroes.\n\nThe reverse conversions are done for the special characters mentioned in the\nConversion from Python to XML section above.\n\nAny 'attr' attribute fields are converted to elements named '\\@attr' and\ncorresponding '#text' elements are created if needed.\n\nClass Documentation\n-------------------\n\n**class DataModelDict.DataModelDict(*args, kwargs)**\n\n Bases: ``collections.OrderedDict``\n\n Class for handling json/xml equivalent data structures.\n\n **append(key, value)**\n\n Adds a value for element key by either adding key to the\n dictionary or appending the value as a list to any current\n value.\n\n :Parameters:\n * **key** (*str*) \u00e2\u20ac\u201c The dictionary key.\n\n * **value** \u00e2\u20ac\u201c The value to add to the dictionary key. If\n key exists, the element is converted to a list if needed\n and value is appended.\n\n **aslist(key)**\n\n Gets the value of a dictionary key as a list. Useful for\n elements whose values may or may not be lists.\n\n :Parameters:\n **key** (*str*) \u00e2\u20ac\u201c Dictionary key\n\n :Returns:\n The dictionary\u00e2\u20ac\u2122s element value or [value] depending on if it\n already is a list.\n\n :Return type:\n list\n\n **find(key, yes={}, no={})**\n\n Return the value of a subelement at any level uniquely\n identified by the specified conditions.\n\n :Parameters:\n * **key** (*str*) \u00e2\u20ac\u201c Dictionary key to search for.\n\n * **yes** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must have to be considered a match.\n\n * **no** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must not have to be considered a match.\n\n :Returns:\n The value of the uniquely identified subelement.\n\n :Return type:\n any\n\n :Raises:\n **ValueError** \u00e2\u20ac\u201c If exactly one matching subelement is not\n identified.\n\n **finds(key, yes={}, no={})**\n\n Finds the values of all subelements at any level identified by\n the specified conditions.\n\n :Parameters:\n * **key** (*str*) \u00e2\u20ac\u201c Dictionary key to search for.\n\n * **yes** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must have to be considered a match.\n\n * **no** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must not have to be considered a match.\n\n :Returns:\n The values of any matching subelements.\n\n :Return type:\n list\n\n **iteraslist(key)**\n\n Iterates through the values of a dictionary key. Useful for\n elements whose values may or may not be lists.\n\n :Parameters:\n **key** (*str*) \u00e2\u20ac\u201c Dictionary key\n\n :Yields:\n *any* \u00e2\u20ac\u201c The dictionary\u00e2\u20ac\u2122s value or each element in value if\n value is a list.\n\n **iterfinds(key, yes={}, no={})**\n\n Iterates over the values of all subelements at any level\n identified by the specified conditions.\n\n :Parameters:\n * **key** (*str*) \u00e2\u20ac\u201c Dictionary key to search for.\n\n * **yes** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must have to be considered a match.\n\n * **no** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must not have to be considered a match.\n\n :Yields:\n *any* \u00e2\u20ac\u201c The values of any matching subelements.\n\n **iterpaths(key, yes={}, no={})**\n\n Iterates over the path lists to all elements at any level\n identified by the specified conditions.\n\n :Parameters:\n * **key** (*str*) \u00e2\u20ac\u201c Dictionary key to search for.\n\n * **yes** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must have to be considered a match.\n\n * **no** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must not have to be considered a match.\n\n :Yields:\n *list of str* \u00e2\u20ac\u201c The path lists to any matching subelements.\n\n **itervaluepaths()**\n\n Iterates over path lists to all value elements at any level.\n\n :Yields:\n *list* \u00e2\u20ac\u201c The path lists to all value subelements.\n\n **json(fp=None, *args, kwargs)**\n\n Converts the DataModelDict to JSON content.\n\n :Parameters:\n * **fp** (*file-like object or None, optional*) \u00e2\u20ac\u201c An\n open file to write the content to. If None (default),\n then the content is returned as a str.\n\n * ***args** (*any*) \u00e2\u20ac\u201c Any other positional arguments\n accepted by json.dump(s)\n\n * ****kwargs** (*any*) \u00e2\u20ac\u201c Any other keyword arguments\n accepted by json.dump(s)\n\n :Returns:\n The JSON content (only returned if fp is None).\n\n :Return type:\n str, optional\n\n **load(model, format=None)**\n\n Read in values from a json/xml string or file-like object.\n\n :Parameters:\n * **model** (*str or file-like object*) \u00e2\u20ac\u201c The XML or\n JSON content to read. This is allowed to be either a file\n path, a string representation, or an open file-like object\n in byte mode.\n\n * **format** (*str or None, optional*) \u00e2\u20ac\u201c Allows for\n the format of the content to be explicitly stated (\u00e2\u20ac\u02dcxml\u00e2\u20ac\u2122\n or \u00e2\u20ac\u02dcjson\u00e2\u20ac\u2122). If None (default), will try to determine\n which format based on if the first character of model is\n \u00e2\u20ac\u02dc<\u00e2\u20ac\u2122 or \u00e2\u20ac\u02dc{\u00e2\u20ac\u02dc.\n\n :Raises:\n **ValueError** \u00e2\u20ac\u201c If format is None and unable to identify\n XML/JON content, or if format is not equal to \u00e2\u20ac\u02dcxml\u00e2\u20ac\u2122 or\n \u00e2\u20ac\u02dcjson\u00e2\u20ac\u2122.\n\n **path(key, yes={}, no={})**\n\n Return the path list of a subelement at any level uniquely\n identified by the specified conditions. Issues an error if\n either no match, or multiple matches are found.\n\n :Parameters:\n * **key** (*str*) \u00e2\u20ac\u201c Dictionary key to search for.\n\n * **yes** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must have to be considered a match.\n\n * **no** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must not have to be considered a match.\n\n :Returns:\n The subelement path list to the uniquely identified\n subelement.\n\n :Return type:\n list of str\n\n :Raises:\n **ValueError** \u00e2\u20ac\u201c If exactly one matching subelement is not\n identified.\n\n **paths(key, yes={}, no={})**\n\n Return a list of all path lists of all elements at any level\n identified by the specified conditions.\n\n :Parameters:\n * **key** (*str*) \u00e2\u20ac\u201c Dictionary key to search for.\n\n * **yes** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must have to be considered a match.\n\n * **no** (*dict*) \u00e2\u20ac\u201c Key-value terms which the subelement\n must not have to be considered a match.\n\n :Returns:\n The path lists for any matching subelements.\n\n :Return type:\n list\n\n **xml(fp=None, indent=None, kwargs)**\n\n Return the DataModelDict as XML content.\n\n :Parameters:\n * **fp** (*file-like object or None, optional*) \u00e2\u20ac\u201c An\n open file to write the content to. If None (default),\n then the content is returned as a str.\n\n * **indent** (*int, str or None, optional*) \u00e2\u20ac\u201c If\n int, number of spaces to indent lines. If str, will use\n that as the indentation. If None (default), the content\n will be inline.\n\n * ****kwargs** (*any*) \u00e2\u20ac\u201c Other keywords supported by\n xmltodict.unparse, except for output which is replaced by\n fp, and preprocessor, which is controlled.\n\n :Returns:\n The XML content (only returned if fp is None).\n\n :Return type:\n str, optional\n\n**DataModelDict.joinpath(path: list, delimiter: str = '.',\nopenbracket: str = '[', closebracket: str = ']') -> str**\n\n Takes a path as a list and transforms it into a string.\n\n :Parameters:\n * **path** (*list*) \u00e2\u20ac\u201c The path list to join.\n\n * **delimiter** (*str*) \u00e2\u20ac\u201c The delimiter between subsequent\n element names.\n\n * **openbracket** (*str*) \u00e2\u20ac\u201c The opening indicator of list\n indices.\n\n * **closebracket** (*str*) \u00e2\u20ac\u201c The closing indicator of list\n indices.\n\n :Return type:\n The path as a delimited string.\n\n**DataModelDict.parsepath(pathstr: str, delimiter: str = '.',\nopenbracket: str = '[', closebracket: str = ']') -> list**\n\n Takes a path as a string and parses it into a list of terms.\n\n :Parameters:\n * **pathstr** (*str*) \u00e2\u20ac\u201c The path string to parse.\n\n * **delimiter** (*str*) \u00e2\u20ac\u201c The delimiter between subsequent\n element names.\n\n * **openbracket** (*str*) \u00e2\u20ac\u201c The opening indicator of list\n indices.\n\n * **closebracket** (*str*) \u00e2\u20ac\u201c The closing indicator of list\n indices.\n\n :Returns:\n The path as a list.\n\n :Return type:\n list\n\n**DataModelDict.uber_open_rmode(data: Union[str, bytes, pathlib.Path,\nio.IOBase]) -> io.IOBase**\n\n Provides a uniform means of reading data from files, file-like\n objects, and string/bytes content.\n\n :Parameters:\n **data** (*file-like object, file path, or str/bytes\n file content*) \u00e2\u20ac\u201c The data that will be opened for reading.\n\n :Returns:\n An open file-like object that is in a bytes read mode. If a\n file-like object is given, it is passed through after checking\n that it is for bytes content. If a file path is given, the file\n is opened in \u00e2\u20ac\u02dcrb\u00e2\u20ac\u2122 mode. If bytes or string content is given,\n the content is returned in a BytesIO object.\n\n :Return type:\n file-like object\n\n :Raises:\n * **ValueError** \u00e2\u20ac\u201c If a file-like object in text mode is given.\n\n * **TypeError** \u00e2\u20ac\u201c If data is not a file-like object, bytes, str\n or Path.\n\n * **FileNotFoundError** \u00e2\u20ac\u201c If data is a pathlib.Path object and\n is not an existing file.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Class allowing for data models equivalently represented as Python dictionaries, JSON, and XML",
"version": "0.9.9",
"split_keywords": [
"json",
"xml",
"dictionary"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "426bfe3b022663e3589ee811fc5a499830370170b45244629670cdc99fd3be9e",
"md5": "a2ebe660047e28665a0a9c3392925249",
"sha256": "0549f80bf8e1d4725397fb737d495da8089828b1af4e5202e31c5d7b03fea852"
},
"downloads": -1,
"filename": "DataModelDict-0.9.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a2ebe660047e28665a0a9c3392925249",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 15040,
"upload_time": "2022-02-17T15:57:41",
"upload_time_iso_8601": "2022-02-17T15:57:41.227821Z",
"url": "https://files.pythonhosted.org/packages/42/6b/fe3b022663e3589ee811fc5a499830370170b45244629670cdc99fd3be9e/DataModelDict-0.9.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "51dac5709322a1ddab201d37e2614edb1a90c6b64d5c0f02f9eae70f26847075",
"md5": "41463d06075ffe7b2554a0d5a5279038",
"sha256": "0da74146c73ca84bbd3d680c3659464b611228bee48012c3860e320ebf3b5919"
},
"downloads": -1,
"filename": "DataModelDict-0.9.9.tar.gz",
"has_sig": false,
"md5_digest": "41463d06075ffe7b2554a0d5a5279038",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16379,
"upload_time": "2022-02-17T15:57:43",
"upload_time_iso_8601": "2022-02-17T15:57:43.409532Z",
"url": "https://files.pythonhosted.org/packages/51/da/c5709322a1ddab201d37e2614edb1a90c6b64d5c0f02f9eae70f26847075/DataModelDict-0.9.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-02-17 15:57:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "usnistgov",
"github_project": "DataModelDict",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "datamodeldict"
}
JSON
