dictIO.formatter module

class dictIO.formatter.Formatter

Bases: object

Abstract Base Class for formatters.

Formatters serialize a dict into a string applying a specific format.

classmethod get_formatter(target_file: Path | None = None)

Return a Formatter instance matching the type of the target file to be formatted (factory method).

Parameters:

target_file (Path, optional) – name of the target file to be formatted, by default None

Returns:

specific Formatter instance matching the target file type to be formatted

Return type:

Formatter

to_string(dict: MutableMapping[Any, Any] | CppDict) → str

Create a string representation of the passed in dict.

Note: Override this method when implementing a specific Formatter.

Parameters:

dict (Union[MutableMapping[Any, Any], CppDict]) – dict to be formatted

Returns:

string representation of the dict

Return type:

str

format_dict(arg: MutableMapping[Any, Any] | MutableSequence[Any] | Any) → str

Format a dict or list object.

Note: Override this method when implementing a specific Formatter.

Parameters:

arg (Union[MutableMapping[Any, Any], MutableSequence[Any], Any]) – the dict or list to be formatted

Returns:

the formatted string representation of the passed in dict or list

Return type:

str

format_type(arg: Any) → str

Format a single value type (str, int, float, boolean or None).

Parameters:

arg (Any) – the value to be formatted

Returns:

the formatted string representation of the passed in value

Return type:

str

format_bool(arg: bool) → str

Format a boolean.

Note: Override this method for specific formatting of booleans when implementing a Formatter.

Parameters:

arg (bool) – the boolean value to be formatted

Returns:

the formatted string representation of the passed in boolean value

Return type:

str

format_int(arg: int) → str

Format an integer.

Note: Override this method for specific formatting of integers when implementing a Formatter.

Parameters:

arg (int) – the int to be formatted

Returns:

the formatted string representation of the passed in int

Return type:

str

format_float(arg: float) → str

Format a floating point number.

Note: Override this method for specific formatting of floating point numbers when implementing a Formatter.

Parameters:

arg (float) – the float to be formatted

Returns:

the formatted string representation of the passed in float

Return type:

str

format_none() → str

Format None value.

Note: Override this method for specific formatting of None when implementing a Formatter.

Returns:

the formatted string representation of None

Return type:

str

format_string(arg: str) → str

Format a string.

Parameters:

arg (str) – the string to be formatted

Returns:

the formatted string

Return type:

str

format_empty_string(arg: str) → str

Format an empty string.

Note: Override this method for specific formatting of empty strings when implementing a Formatter.

Parameters:

arg (str) – the empty string to be formatted

Returns:

the formatted empty string

Return type:

str

format_single_word_string(arg: str) → str

Format a single word string.

Note: Override this method for specific formatting of single word strings when implementing a Formatter.

Parameters:

arg (str) – the single word string to be formatted

Returns:

the formatted single word string

Return type:

str

format_string_with_nested_string(arg: str) → str

Format a string that contains a nested string.

Note: Override this method for specific formatting of strings with nested strings when implementing a Formatter.

Parameters:

arg (str) – the string with a nested string to be formatted

Returns:

the formatted string with a nested string

Return type:

str

format_multi_word_string(arg: str) → str

Format a multi word string.

Note: Override this method for specific formatting of multi word strings when implementing a Formatter.

Parameters:

arg (str) – the multi word string to be formatted

Returns:

the formatted multi word string

Return type:

str

format_reference_string(arg: str) → str

Format a reference.

Note: Override this method for specific formatting of references when implementing a Formatter.

Parameters:

arg (str) – the reference to be formatted

Returns:

the formatted reference

Return type:

str

format_expression_string(arg: str) → str

Format an expression.

Note: Override this method for specific formatting of expressions when implementing a Formatter.

Parameters:

arg (str) – the expression to be formatted

Returns:

the formatted expression

Return type:

str

add_single_quotes(arg: str) → str

Add single quotes to a string.

Leading and trailing single quotes will added to the passed in string (i.e. it will be wrapped in single quotes). Note: Call this base class method from any specific Formatter implementation to easily add single quotes to a string when formatting.

Parameters:

arg (str) – the string to be wrapped in single quotes

Returns:

the string wrapped in single quotes

Return type:

str

add_double_quotes(arg: str) → str

Add double quotes to a string.

Leading and trailing double quotes will added to the passed in string (i.e. it will be wrapped in double quotes). Note: Call this base class method from any specific Formatter implementation to easily add double quotes to a string when formatting.

Parameters:

arg (str) – the string to be wrapped in double quotes

Returns:

the string wrapped in double quotes

Return type:

str

class dictIO.formatter.CppFormatter

Bases: Formatter

Formatter to serialize a dict into a string in dictIO dict file format.

to_string(dict: MutableMapping[Any, Any] | CppDict) → str

Create a string representation of the passed in dict in dictIO dict file format.

Parameters:

dict (Union[MutableMapping[Any, Any], CppDict]) – dict to be formatted

Returns:

string representation of the dict in dictIO dict file format

Return type:

str

format_dict(arg: MutableMapping[Any, Any] | MutableSequence[Any] | Any, tab_len: int = 4, level: int = 0, sep: str = ' ', items_per_line: int = 10, end: str = '\n', ancestry: Type[MutableMapping[Any, Any]] | Type[MutableSequence[Any]] = MutableMapping) → str

Format a dict or list object.

format_bool(arg: bool) → str

Format a boolean.

Parameters:

arg (bool) – the boolean value to be formatted

Returns:

the formatted string representation of the passed in boolean value

Return type:

str

format_none() → str

Format None.

Returns:

the formatted string representation of None

Return type:

str

format_empty_string(arg: str) → str

Format an empty string.

Parameters:

arg (str) – the empty string to be formatted

Returns:

the formatted empty string

Return type:

str

format_string_with_nested_string(arg: str) → str

Format a string that contains a nested string.

Parameters:

arg (str) – the string with a nested string to be formatted

Returns:

the formatted string with a nested string

Return type:

str

format_multi_word_string(arg: str) → str

Format a multi word string.

Parameters:

arg (str) – the multi word string to be formatted

Returns:

the formatted multi word string

Return type:

str

format_expression_string(arg: str) → str

Format an expression.

Parameters:

arg (str) – the expression to be formatted

Returns:

the formatted expression

Return type:

str

insert_block_comments(dict: CppDict, s: str) → str

Insert back all block comments.

Replaces all BLOCKCOMMENT placeholders in s with the actual block_comments saved in dict str s is expected to contain the CppDict’s block_content containing block comment placeholders to substitute (BLOCKCOMMENT… BLOCKCOMMENT…)

make_default_block_comment(block_comment: str = '') → str

Create the default block comment (header) for files in dictIO dict file format.

insert_includes(cpp_dict: CppDict, s: str) → str

Insert back all include directives.

insert_line_comments(cpp_dict: CppDict, s: str) → str

Insert back all line directives.

remove_trailing_spaces(s: str) → str

Remove trailing spaces from all lines.

Reads all lines from the passed in string, removes trailing spaces from each line and returns a new string with trailing spaces removed.

class dictIO.formatter.FoamFormatter

Bases: CppFormatter

Formatter to serialize a dict into a string in OpenFOAM dictionary format.

to_string(dict: MutableMapping[Any, Any] | CppDict) → str

Create a string representation of the passed in dict in OpenFOAM dictionary format.

Parameters:

dict (Union[MutableMapping[Any, Any], CppDict]) – dict to be formatted

Returns:

string representation of the dict in OpenFOAM dictionary format

Return type:

str

format_empty_string(arg: str) → str

Format an empty string.

Parameters:

arg (str) – the empty string to be formatted

Returns:

the formatted empty string

Return type:

str

format_string_with_nested_string(arg: str) → str

Format a string that contains a nested string.

Parameters:

arg (str) – the string with a nested string to be formatted

Returns:

the formatted string with a nested string

Return type:

str

format_multi_word_string(arg: str) → str

Format a multi word string.

Parameters:

arg (str) – the multi word string to be formatted

Returns:

the formatted multi word string

Return type:

str

format_expression_string(arg: str) → str

Format an expression.

Parameters:

arg (str) – the expression to be formatted

Returns:

the formatted expression

Return type:

str

make_default_block_comment(block_comment: str = '') → str

Create the default block comment (header) for files in OpenFOAM dictionary format.

class dictIO.formatter.JsonFormatter

Bases: Formatter

Formatter to serialize a dict into a string in JSON dictionary format.

to_string(dict: MutableMapping[Any, Any] | CppDict) → str

Create a string representation of the passed in dict in JSON dictionary format.

Parameters:

dict (Union[MutableMapping[Any, Any], CppDict]) – dict to be formatted

Returns:

string representation of the dict in JSON dictionary format

Return type:

str

insert_includes(cpp_dict: CppDict, s: str) → str

Insert back all include directives.

class dictIO.formatter.XmlFormatter(omit_prefix: bool = True, integrate_attributes: bool = True, remove_node_numbering: bool = True)

Bases: Formatter

Formatter to serialize a dict into a string in xml format.

Defaults:

namespaces: ‘https://www.w3.org/2009/XMLSchema/XMLSchema.xsd’ n root tag: ‘NOTSPECIFIED’ n root attributes: None n indent: 4

Defaults can be overwritten by adding a subdict ‘_xmlOpts’ to dict, containing ‘_nameSpaces’, ‘_rootTag’, ‘_rootAttributes’.

Adding a subdict ‘_attributes’ to a subdict inside dict causes the XmlFormatter to write xml attributes. In contrast to xml, there are some specialties in dict format what need to be customized:

property | in xml | sibling in dict |

:———– | :—————– | :————– |

general name | root tag | the file name is the ‘root tag’ and hence the name of the dict |

name | element name (tag) | sub-dict name (has to be unique) |

| (multiple occurrences allowed due to attributes) | |

attributes | as required | attributes need to be provided in a separate subdict “_attributes” to take action |

style | namespace(s) | style guide, no namespaces (ns can be provided in a subdict “_xmlOpts”) |

to_string(dict: MutableMapping[Any, Any] | CppDict) → str

Create a string representation of the passed in dict in XML format.

Parameters:

dict (Union[MutableMapping[Any, Any], CppDict]) – dict to be formatted

Returns:

string representation of the dict in XML format

Return type:

str

populate_into_element(element: Element, arg: MutableMapping[Any, Any] | MutableSequence[Any] | Any, xsd_uri: str | None = None)

Populate arg into the XML element node.

If arg is a dict or list, method will call itself recursively until all nested content within the dict or list is populated into nested elements, eventually creating an XML dom.

Parameters:

• element (Element) – element which will be populated

• arg (Union[MutableMapping[Any, Any], MutableSequence[Any], Any]) – value to be populated into the element

• xsd_uri (str, optional) – xsd uri, by default None