API documentation

High level routines

hsd.load_string(hsdstr: str, lower_tag_names: bool = False, include_hsd_attribs: bool = False, flatten_data: bool = False) → dict

Loads a string with HSD-formatted data into a Python dictionary.

Parameters:

hsdstr – String with HSD-formatted data.
lower_tag_names – When set, all tag names will be converted to lower-case (practical, when input should be treated case insensitive.) If include_hsd_attribs is set, the original tag name will be stored among the HSD attributes.
include_hsd_attribs – Whether the HSD-attributes (processing related attributes, like original tag name, line information, etc.) should be stored. Use it, if you wish to keep the formatting of the data close to the original one on writing (e.g. lowered tag names converted back to their original form, equals signs between parent and only child kept, instead of converted to curly braces).
flatten_data – Whether multiline data in the HSD input should be flattened into a single list. Othewise a list of lists is created, with one list for every line (default).

Returns:

Dictionary representing the HSD data.

Examples

>>> hsdstr = """
... Dftb {
...   Scc = Yes
...   Filling {
...     Fermi {
...       Temperature [Kelvin] = 100
...     }
...   }
... }
... """
>>> hsd.load_string(hsdstr)
{'Dftb': {'Scc': True, 'Filling': {'Fermi': {'Temperature': 100,
'Temperature.attrib': 'Kelvin'}}}}

In order to ease the case-insensitive handling of the input, the tag names can be converted to lower case during reading using the lower_tag_names option.

>>> hsd.load_string(hsdstr, lower_tag_names=True)
{'dftb': {'scc': True, 'filling': {'fermi': {'temperature': 100,
'temperature.attrib': 'Kelvin'}}}}

The original tag names (together with additional information like the line number of a tag) can be recorded, if the include_hsd_attribs option is set:

>>> data = hsd.load_string(hsdstr, lower_tag_names=True,
... include_hsd_attribs=True)

Each tag in the dictionary will have a corresponding “.hsdattrib” entry with the recorded data:

>>> data["dftb.hsdattrib"]
{'equal': False, 'line': 1, 'name': 'Dftb'}

This additional data can be then also used to format the tags in the original style, when writing the data in HSD-format again. Compare:

>>> hsd.dump_string(data)
'dftb {\n  scc = Yes\n  filling {\n    fermi {\n
temperature [Kelvin] = 100\n    }\n  }\n}\n'

versus

>>> hsd.dump_string(data, use_hsd_attribs=True)
'Dftb {\n  Scc = Yes\n  Filling {\n    Fermi {\n
Temperature [Kelvin] = 100\n    }\n  }\n}\n'

hsd.load(hsdfile: Union[TextIO, str], lower_tag_names: bool = False, include_hsd_attribs: bool = False, flatten_data: bool = False) → dict

Loads a file with HSD-formatted data into a Python dictionary

Parameters:

hsdfile – Name of file or file like object to read the HSD data from
lower_tag_names – When set, all tag names will be converted to lower-case (practical, when input should be treated case insensitive.) If include_hsd_attribs is set, the original tag name will be stored among the HSD attributes.
include_hsd_attribs – Whether the HSD-attributes (processing related attributes, like original tag name, line information, etc.) should be stored. Use it, if you wish to keep the formatting of the data close to the original on writing (e.g. lowered tag names converted back to their original form, equals signs between parent and only child kept, instead of converted to curly braces).
flatten_data – Whether multiline data in the HSD input should be flattened into a single list. Othewise a list of lists is created, with one list for every line (default).

Returns:

Dictionary representing the HSD data.

Examples

See hsd.load_string() for examples of usage.

hsd.dump_string(data: dict, use_hsd_attribs: bool = False) → str

Serializes an object to string in HSD format.

Parameters:

data – Dictionary like object to be written in HSD format.
use_hsd_attribs – Whether HSD attributes of the data structure should be used to format the output (e.g. to restore original mixed case tag names)

Returns:

HSD formatted string.

Examples

>>> hsdtree = {
...     'Dftb': {
...         'Scc': True,
...         'Filling': {
...             'Fermi': {
...                 'Temperature': 100,
...                 'Temperature.attrib': 'Kelvin'
...             }
...         }
...     }
... }
>>> hsd.dump_string(hsdtree)
'Dftb {\n  Scc = Yes\n  Filling {\n    Fermi {\n
Temperature [Kelvin] = 100\n    }\n  }\n}\n'

See also hsd.load_string() for an example.

hsd.dump(data: dict, hsdfile: Union[TextIO, str], use_hsd_attribs: bool = False)

Dumps data to a file in HSD format.

Parameters:

data – Dictionary like object to be written in HSD format
hsdfile – Name of file or file like object to write the result to.
use_hsd_attribs –
Whether HSD attributes in the data structure should be used to format the output.

This option can be used to for example to restore original tag names, if the file was loaded with the lower_tag_names and include_hsd_attribs options set or keep the equal signs between parent and contained only child.

Raises:

TypeError – if object is not a dictionary instance.

Examples

See hsd.load_string() for an example.

Lower level building blocks

class hsd.HsdParser(eventhandler: Optional[HsdEventHandler] = None)

Event based parser for the HSD format.

Parameters:: eventhandler – Object which should handle the HSD-events triggered during parsing. When not specified, HsdEventPrinter() is used.

Examples

>>> from io import StringIO
>>> dictbuilder = hsd.HsdDictBuilder()
>>> parser = hsd.HsdParser(eventhandler=dictbuilder)
>>> hsdfile = StringIO("""
... Hamiltonian {
...     Dftb {
...         Scc = Yes
...         Filling = Fermi {
...             Temperature [Kelvin] = 100
...         }
...     }
... }
... """)
>>> parser.parse(hsdfile)
>>> dictbuilder.hsddict
{'Hamiltonian': {'Dftb': {'Scc': True, 'Filling': {'Fermi':
{'Temperature': 100, 'Temperature.attrib': 'Kelvin'}}}}}

parse(fobj: Union[TextIO, str])

Parses the provided file-like object.

The parser will process the data and trigger the corresponding events in the eventhandler which was passed at initialization.

Parameters:: fobj – File like object or name of a file containing the data.

class hsd.HsdEventHandler

Abstract base class for handling HSD events.

abstract open_tag(tagname: str, attrib: Optional[str], hsdattrib: Optional[dict])

Opens a tag.

Parameters:

tagname – Name of the tag which had been opened.
attrib – String containing the attribute of the tag or None.
hsdattrib – Dictionary of the options created during the processing in the hsd-parser.

abstract close_tag(tagname: str)

Closes a tag.

Parameters:: tagname – Name of the tag which had been closed.

abstract add_text(text: str)

Adds text (data) to the current tag.

Parameters:: text – Text in the current tag.

class hsd.HsdDictBuilder(flatten_data: bool = False, lower_tag_names: bool = False, include_hsd_attribs: bool = False)

Specific HSD event handler, which builds a nested Python dictionary.

Parameters:

flatten_data – Whether multiline data in the HSD input should be flattened into a single list. Othewise a list of lists is created, with one list for every line (default).
lower_tag_names – Whether tag names should be all converted to lower case (to ease case insensitive processing). Default: False. If set and include_hsd_attribs is also set, the original tag names can be retrieved from the “name” hsd attributes.
include_hsd_attribs – Whether the HSD-attributes (processing related attributes, like original tag name, line information, etc.) should be stored (default: False).

property hsddict: The dictionary which has been built

open_tag(tagname, attrib, hsdattrib)

Opens a tag.

Parameters:

tagname – Name of the tag which had been opened.
attrib – String containing the attribute of the tag or None.
hsdattrib – Dictionary of the options created during the processing in the hsd-parser.

close_tag(tagname)

Closes a tag.

Parameters:: tagname – Name of the tag which had been closed.

add_text(text)

Adds text (data) to the current tag.

Parameters:: text – Text in the current tag.

class hsd.HsdDictWalker(eventhandler: Optional[HsdEventHandler] = None)

Walks through a Python dictionary and triggers HSD events.

Parameters:: eventhandler – Event handler dealing with the HSD events generated while walking through the dictionary. When not specified, the events are printed.

walk(dictobj)

Walks through the directory and generates HSD events.

Parameters:: dictobj – Directory to walk through.

class hsd.HsdFormatter(fobj, use_hsd_attribs=True)

Implements an even driven HSD formatter.

Parameters:

fobj – File like object to write the formatted output to.
use_hsd_attribs – Whether HSD attributes passed to the formatter should be considered, when formatting the the output (default: True)

open_tag(tagname: str, attrib: str, hsdattrib: dict)

Opens a tag.

Parameters:

tagname – Name of the tag which had been opened.
attrib – String containing the attribute of the tag or None.
hsdattrib – Dictionary of the options created during the processing in the hsd-parser.

close_tag(tagname: str)

Closes a tag.

Parameters:: tagname – Name of the tag which had been closed.

add_text(text: str)

Adds text (data) to the current tag.

Parameters:: text – Text in the current tag.