maci.dump

dumps maci, dict, or object data to a file

dumping a file

Dumps maci, dict, or custom object data to a file. Output in file is structured following the maci language syntax (See language). Nothing is returned. Creates a new or overwrites an existing file by default (See append parameter to change mode)

Basic Example of dumping data to a file using default positional parameters

maci.dump('my.data', data)

In this example, we simply dump data to a file using the dump function and pass a string of the filepath to the file as the first argument to the function, then pass the data as the second argument to the function.

Example of dumping MaciDataObj

maci_obj.mydata1 = 'data1'
maci_obj.mydata2 = 2

maci.dump('my.data', maci_obj)

Example of dumping dict

dict_data = {'mydata1': 'data1', 'mydata2': 2}

maci.dump('my.data', dict_data)

Example of dumping custom object

my_object.mydata1 = 'data1'
my_object.mydata2 = 2

maci.dump('my.data', my_object)

Resulted output contents in example file from all object dumps

mydata1 = 'data1'
mydata2 = 2

parameters & arguments

Describes all parameter functionality and accepted data types

filename: str | Path

First required positional argument. Accepts strings and Path objects

Use this parameter to point to your filepath

data: MaciDataObj | dict | ClassObject

Second required positional argument. Accepts maci data objects, dictionaries, or custom objects.

Use this parameter to pass in the data you want to dump to a file.

append: bool

Optional parameter. Accepts booleans. Default = False. File must already exist.

Use this parameter to enable appending mode to write by appending data to the file. Default is disabled which writes new or overwrites a file.

indent_level: int

Optional parameter. Accepts integers. Default = 1

Use this parameter to change the indentation level for structured data (lists, dicts, tuples, sets) written to the file. Indentation will be applied to nested data as well.

Default uses the standard 4x spaces indentation practice. A single integer represents adding 4x more spaces at each level. For example 1 = 4x spaces, 2 = 8x spaces, 3 = 12x spaces, etc.

Note: Setting it to 0 will slightly improve write performance by approx 5%.

indentation_on: bool

Optional parameter. Accepts booleans. Default = True

Use this parameter to enable/disable setting and indenting structured data (lists, dicts, tuples, sets) over multiple lines.

Note: Disabling indentation will slightly improve write performance by approx 5%, but output of structured data may be less human-readable.

multi_line_str: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to enable writing data that contain strings to be written as a multiline string representation. This will represent your string like a python triple-quoted string in the output over multiple lines. This mechanic works by delimiting each new line of the string data when it detects a newline character.

Default is disabled as it would be more desirable for a developer to have string data in its original representation as this feature does add 1 leading and 1 trailing newline character to the string (See multiline data), but does not tamper with the data in-between. However, you can enable this feature if you desire a more human-readable multiline string for your string data in the output. Loading the string with the load function for example will not strip the leading and trailing newline characters for the reason of preserving the original string data in case it was intentionally written that way.

encoding: str | None

Optional parameter. Accepts strings or None. Default = None

Use this parameter to dump the data with the desired codec of the data if needed. The default uses the default of python, so you don't have to use this, but you can if the data needs to be written with a specific codec.

private_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private attribute names that begin with a single or double underscore. Default is disabled to protect private or name-mangled attributes.

This is a global switch that affects initialized and class (if enabled) attributes.

private_under_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private attribute names that begin with a single underscore. Default is disabled to protect private attributes.

This is a global switch that affects initialized and class (if enabled) attributes.

private_dunder_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private attribute names that begin with a double underscore. Default is disabled to protect private/name-mangled attributes.

This is a global switch that affects initialized and class (if enabled) attributes.

class_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to dump all attributes of the class. This can be useful if you also need the attributes of a class or class of an object to be stored along with the initialized attributes. Pass the class only if just wanting class attributes dumped.

Default is disabled as this may be undesirable to also store class attributes.

private_init_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private initialized attribute names that begin with a single or double underscore. Default is disabled to protect private or name-mangled attributes. Note: Using this is only necessary if you have class_attrs parameter enabled and want to only dump private or name-mangled initialized attributes and not private class attributes.

private_init_under_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private initialized attribute names that begin with a single underscore. Default is disabled to protect private attributes. Note: Using this is only necessary if you have class_attrs parameter enabled and want to only dump private initialized attributes and not private class attributes.

private_init_dunder_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private initialized attribute names that begin with a double underscore. Default is disabled to protect private/name-mangled attributes. Note: Using this is only necessary if you have class_attrs parameter enabled and want to only dump private/name-mangled initialized attributes and not private class attributes.

private_class_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private class attribute names that begin with a single or double underscore. Default is disabled to protect private or name-mangled attributes. Note: Using this is only necessary if you have class_attrs parameter enabled and want to only dump private or name-mangled class attributes and not private initialized attributes.

private_class_under_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private class attribute names that begin with a single underscore. Default is disabled to protect private attributes. Note: Using this is only necessary if you have class_attrs parameter enabled and want to only dump private class attributes and not private initialized attributes.

private_class_dunder_attrs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to also dump all private class attribute names that begin with a double underscore. Default is disabled to protect private/name-mangled attributes. Note: Using this is only necessary if you have class_attrs parameter enabled and want to only dump private/name-mangled class attributes and not private initialized attributes.

use_symbol_glyphs: bool

Optional parameter. Accepts booleans. Default = False

Use this parameter to enable writing the Assignment Glyphs as symbols instead of their default syntax. Default is disabled as this feature may not be supported in the future and is discouraged from using in general. It was only implemented as a courtesy to provide ported support (See ported mention), but it is instead encouraged to use the main maci supported glyphs from the glyph legend.