jacinle.io.pretty#

Functions to dump Python objects into human-readable formats.

Functions

`dump_env`(value)	Dump a structured object into a file, similar to `os.environ()`.
`dump_json`(value[, compressed])	Dump a JSON object into a file.
`dump_jsonc`(value)	Dump a list of dictionary into a JSON string, separated by new lines, with compressed format.
`dump_kv`(value)	Dump a structured object into a file, using `jacinle.utils.printing.kvformat()`.
`dump_struct`(value)	Dump a structured object into a file, using `jacinle.utils.printing.stformat()`.
`dump_txt`(value)	Dump a list of strings into a file, separated by newlines.
`dump_xml`(value, **kwargs)	Dump an XML object into a file.
`dump_yaml`(value)	Dump a YAML object into a file.
`dumps_env`(value)	Dump a structured object into a string, similar to `os.environ()`.
`dumps_json`(value[, compressed])	Dump a JSON object into a string.
`dumps_jsonc`(value)	Dump a list of dictionary into a JSON string, separated by new lines, with compressed format.
`dumps_kv`(value)	Dump a structured object into a string, using `jacinle.utils.printing.kvformat()`.
`dumps_struct`(value)	Dump a structured object into a string, using `jacinle.utils.printing.stformat()`.
`dumps_txt`(value)	Dump a list of strings into a string, separated by newlines.
`dumps_xml`(value, **kwargs)	Dump an XML object into a string.
`dumps_yaml`(value)	Dump a YAML object into a string.
`iter_txt`(fd[, strip])	Iterate over lines in a text file.
`load_json`(value)	Load a JSON object from a string.
`load_jsonc`(value)	Load a list of JSON dictionaries from a string.
`load_xml`(value[, name_key, attribute_key])	Load an XML object from a string.
`load_yaml`(value)	Load a YAML object from a string.
`loads_json`(value)	Load a JSON object from a string.
`loads_jsonc`(value)	Load a list of JSON dictionaries from a string.
`loads_xml`(value[, name_key, attribute_key])	Load an XML object from a string.
`loads_yaml`(value)	Load a YAML object from a string.
`pretty_dump`(file, obj, **kwargs)	Dump a file with pretty-printing.
`pretty_dump_json`(value[, compressed])	Dump a JSON object into a file, with pretty-printing.
`pretty_dumps_json`(value[, compressed])	Dump a JSON object into a string, with pretty-printing.
`pretty_load`(file, **kwargs)	Load a file with pretty-printing.

Functions

dump_env(value)#: Dump a structured object into a file, similar to os.environ().

dump_json(value, compressed=True)#

Dump a JSON object into a file. In addition to the standard JSON format, this function also supports

__jsonify__: an instance method for objects that returns a JSON-serializable object.
For classes, it will store __dict__ as the JSON object.

Note that both features can not be preserved when loading the JSON object back.

Parameters:

value (Any) – the object to dump.
compressed (bool) – whether to use compressed format. If set to False, the dumped string will be pretty-printed.

Returns:

a file.

Return type:

str

dump_jsonc(value)#

Dump a list of dictionary into a JSON string, separated by new lines, with compressed format.

Parameters:: value (Iterable[Dict])
Return type:: str

dump_kv(value)#: Dump a structured object into a file, using jacinle.utils.printing.kvformat().

dump_struct(value)#: Dump a structured object into a file, using jacinle.utils.printing.stformat().

dump_txt(value)#

Dump a list of strings into a file, separated by newlines.

Parameters:: value (Iterable[str]) – a list of strings.
Returns:: a file.
Return type:: str

dump_xml(value, **kwargs)#

Dump an XML object into a file.

Parameters:: value (Dict)
Return type:: str

dump_yaml(value)#

Dump a YAML object into a file.

Parameters:: value (Any)
Return type:: str

dumps_env(value)[source]#: Dump a structured object into a string, similar to os.environ().

dumps_json(value, compressed=True)[source]#

Dump a JSON object into a string. In addition to the standard JSON format, this function also supports

__jsonify__: an instance method for objects that returns a JSON-serializable object.
For classes, it will store __dict__ as the JSON object.

Note that both features can not be preserved when loading the JSON object back.

Parameters:

value (Any) – the object to dump.
compressed (bool) – whether to use compressed format. If set to False, the dumped string will be pretty-printed.

Returns:

a string.

Return type:

str

dumps_jsonc(value)[source]#

Dump a list of dictionary into a JSON string, separated by new lines, with compressed format.

Parameters:: value (Iterable[Dict])
Return type:: str

dumps_kv(value)[source]#: Dump a structured object into a string, using jacinle.utils.printing.kvformat().

dumps_struct(value)[source]#: Dump a structured object into a string, using jacinle.utils.printing.stformat().

dumps_txt(value)[source]#

Dump a list of strings into a string, separated by newlines.

Parameters:: value (Iterable[str]) – a list of strings.
Returns:: a string.
Return type:: str

dumps_xml(value, **kwargs)[source]#

Dump an XML object into a string.

Parameters:: value (Dict)
Return type:: str

dumps_yaml(value)[source]#

Dump a YAML object into a string.

Parameters:: value (Any)
Return type:: str

iter_txt(fd, strip=True)[source]#

Iterate over lines in a text file. This function will ignore empty lines.

Parameters:

fd (IOBase) – a file descriptor.
strip (bool) – whether to strip the line.

Return type:

Iterable[str]

load_json(value)#

Load a JSON object from a string.

Parameters:: value (str)
Return type:: Any

load_jsonc(value)#

Load a list of JSON dictionaries from a string. This function supports multiple JSON objects in a single string, separated by newlines. Note that this function only support a list of plain dictionaries. Do not use this function to load JSON objects with nested lists or dictionaries.

Parameters:: value (str) – a string.
Returns:: a list of dictionaries.
Return type:: List[Dict]

load_xml(value, name_key='__name__', attribute_key='__attribute__')#

Load an XML object from a string. It will return a dictionary as the root node. For each node, it will have a key named “__name__” as the tag name, and a key “__attributes__” as a dictionary of attributes. Each child node will be a nested dictionary under the root node. If there are multiple child nodes with the same tag name, they will be stored in a list.

Parameters:

value (str) – a string.
name_key (str) – the key name for the tag name.
attribute_key (str | None) – the key name for the attributes. If set to None, the attributes will be stored in the root node.

Returns:

a dictionary.

Return type:

Dict

load_yaml(value)#

Load a YAML object from a string.

Parameters:: value (str)
Return type:: Any

loads_json(value)[source]#

Load a JSON object from a string.

Parameters:: value (str)
Return type:: Any

loads_jsonc(value)[source]#

Parameters:: value (str) – a string.
Returns:: a list of dictionaries.
Return type:: List[Dict]

loads_xml(value, name_key='__name__', attribute_key='__attribute__')[source]#

Parameters:

value (str) – a string.
name_key (str) – the key name for the tag name.
attribute_key (str | None) – the key name for the attributes. If set to None, the attributes will be stored in the root node.

Returns:

a dictionary.

Return type:

Dict

loads_yaml(value)[source]#

Load a YAML object from a string.

Parameters:: value (str)
Return type:: Any

pretty_dump(file, obj, **kwargs)[source]#: Dump a file with pretty-printing.

pretty_dump_json(value, compressed=False)#

Dump a JSON object into a file, with pretty-printing.

Parameters:

value (Any)
compressed (bool)

Return type:

str

pretty_dumps_json(value, compressed=False)[source]#

Dump a JSON object into a string, with pretty-printing.

Parameters:

value (Any)
compressed (bool)

Return type:

str

pretty_load(file, **kwargs)[source]#: Load a file with pretty-printing.