# maci The easy to use library for data serialization [maci](/docs/maci) is a python-styled serialization [language](/docs/maci/language) & thin wrapper library that makes handling serialized data simple. It parses native python data types from any plain file, which can be safer than using an executable .py file for your stored save data or configuration data. Focuses on reducing boilerplate by removing repetitive implementation, like code written for common file handling, or common libraries used like JSON, YAML, TOML, etc., and move towards concision. It also introduces features like [loading stored data back into your class object](/docs/maci/functions/maci.loadattrs), or creating realistic constants for your name/value pairs by locking them, mapping a name to another to follow its value similar to a pointer, and much more. maci on its own is a pure Python-based library. I've used variations of this library for many external projects, and I wanted to make a robust and stable public version. It has made common needs less painful and has solved simplicity in many ways. Hope it helps you! ### insights Use python data types for your data (literally use python data types as stored values loading them securely using any text file created. Supports [**json**](/docs/json)**,** [**yaml**](/docs/yaml)**,** [**toml**](/docs/toml)**,** [**xml**](/docs/xml)**,** [**ini/conf**](/docs/ini) using common & native libraries with the idea of simpler api abstraction. Use built-in features for locking your data, referencing data by mapping names, loading stored data back into your class object, and other quick and [easy tools ](/docs/tools)like getting or comparing the hash of a file or easily formatting large data sets. ### goals To provide a simple and easy experience in loading/dumping serialized data, with convenient extras! Support the freedom to load your own custom save file, config file, or data file using plain text with any file extension using python's native data types for your projects. Make access convenient for other serialization libraries as well! ### **can't I just load *****.py***** files or use *****pickle***** you might ask?** The maci library [language](/docs/maci/language) maintains a different more secure approach with techniques to ensure loading python data is not susceptible to code execution like what you would expect when you load a **py** or **pickle** file (as by design, and not to detract from their native power) to just access variables or attributes and their values. Python's documentation also states that pickle is insecure for that reason as well, but there are methods to make pickle secure for that purpose. It is more widely accepted to use common data serialization formats designed for storing values if you want to just load your values or data back whether you use maci or not, but maci does just that as well using python's native types to make your life easier with secure mechanics.\ \ Some of the techniques include only allowing the loading of primitive data types, name duplication protection so all name references in a file need to be unique, and name reference locking to protect against re-assignment (essentially creating a constant on any primitive type), and more. You can pickle maci objects if you really wanted to as well. ### install flavors full -> maci, standard library, and 3rd-party packages included ```bash pip install maci ``` standard lib -> maci and standard library based packages only ```bash pip install maci-std ``` **just maci -> maci package only** ```bash pip install maci-only ``` ### code
For contributing: * Fork the repo and submit a feature branch PR to the latest dev-x.x.x branch * All tests must pass before approval consideration and code review * Official release is when dev branch gets merged into mainline branch and if pre-release test env deployments pass: ### pypi \ \ # code project: for contributing: * Fork the repo and submit a feature branch PR to the latest dev-x.x.x branch * All tests must pass before approval consideration and code review * Official release is when dev branch gets merged into mainline branch and if pre-release test env deployments pass: # Quick Start learn maci with a quick start tutorial {% embed url="" %} # Full Training Series learn maci with full training tutorials {% embed url="" %}

Youtube playlist

# maci maci language, api functions, and information [language](/docs/maci/language) [functions](/docs/maci/functions) [object](/docs/maci/object) [errors](/docs/maci/errors) [hints](/docs/maci/hints) # language learn the language syntax and version features ### latest: [1.0.0](/docs/maci/language/v1.0.0) *** maci uses a hybrid parsing concept where it reads the file or string and parses the valid syntax with its own custom tokenization logic and then relies on the [ast library ](https://docs.python.org/3/library/ast.html)to set the literal python object from the parsed data. *** ### language versions and support *To learn about the language, click a version to view the documentation*
lang versionsupported maci versionscurrenteolcurrently supported
1.0.0<=1.1.0yesnoyes
# v1.0.0 language syntax & features for v1.0.0 Describes and specifies the syntax structure, data type literals, language format, and features used within a file or literal string. *** ## assignment glyph legend
glyphassignment typedescription
=regularassigns name to value
+l=lockassigns name to value and locks name from re-assignment
+h=hard lockassigns name to value and locks name from re-assignment, deletion, and unlocking
+m=mapassigns name to another name's value and follows its value changes
+ml=map lockmaps name and locks name
+mh=map hard lockmaps name and hard locks name
Uppercase and Mixed case glyphs are also accepted, but not very clean looking. You may also set letters in the desired order in a file or string to load from and the result is the same (e.g. +hm= instead of +mh=). However, the default is what is described in the legend, and any dump mechanics will follow that default when output to a file or string.
There are also symbols that represent the letter-based glyphs, but those will be retired in the future and are not currently encouraged. The symbols were added as ported support from the older library for migration reasons.
symbol glyphs (older, but still supported) $= lock\ $$= hard lock\ \== map\ $== map lock\ $$== map hard lock
## usage Examples are demonstrating usage in a file to illustrate the language features. Language features may be used in **files** and **strings** to be parsed with maci's load functions (See [functions](/docs/maci/functions)).
#### Regular Assignment Assigning names to values. Shows all supported data types accepted, and any maci specific extras *Example file "my.data"* ```python name_str = 'data' name_int = 1 name_float = 1.0 name_bool = True name_list = [1,2,3] name_dict = {'k1': 1} name_tuple = (1,2,3) name_set = {1,2,3} name_none = None name_bytes = b'data\n' name_datetime = 2023-12-02 21:48:00 name_iso8601 = 2023-12-02T21:48:00-06:00 name_date = 2023-12-02 name_time = 21:48:00 ``` The extras in this example are the date and time formats being parsed natively with maci returning datetime objects in python. It also accepts milliseconds in the time portions. (hint: date and times in example is an easter egg) #### Lock Assignment Glyph Locking a name to a value. This feature protects against an attribute name from being reassigned. Use the lock assignment glyph to set the lock. ```python name_str +l= 'data' ``` During the code's runtime, if this attribute name is ever attempted to be reassigned, it will throw an exception and prevent reassignment. If the exception is caught, the value will remain unchanged. *Exception thrown (See* [*errors*](/docs/maci/errors)*)* ``` maci.error.GeneralError: Attribute Name Locked! Cannot be reassigned ``` If you need to reassign the name to a new value while it is locked, you may utilize the partner method **"unlock\_attr"** to achieve this (See [unlock\_attr](/docs/maci/object/methods/unlock_attr)) You may view all locked names using the "get\_locked\_list" method (See [get\_locked\_list](/docs/maci/object/methods/get_locked_list)). #### Hard Lock Assignment Glyph Hard locking a name to a value. This feature protects against an attribute name from being reassigned, deleted, and unlocked. Use the hard lock assignment glyph to set the hard lock. This feature effectively gives you a constant-like ability. ```python name_str +h= 'data' ``` During the code's runtime, if this attribute name is ever attempted to be reassigned, deleted, or unlocked it will throw an exception to prevent those changes to the name. If an exception is caught, the name and value will remain unchanged. Once this is set, it is permanent during the code's runtime. The only way to change or remove the attribute name would be to delete the whole [maci object](/docs/maci/object). *Exceptions thrown (See* [*errors*](/docs/maci/errors)*)* *This exception is thrown when attempting to reassign or delete name* ``` maci.error.GeneralError: Attribute Name Hard Locked! Cannot be reassigned, deleted, or unlocked ``` *This exception is thrown when attempting to unlock name. Unlock only searches for locked names, not hard-locked names.* ``` maci.error.GeneralError: Unlock attribute name does not exist in lock! Could not find name to unlock ``` You may view all hard-locked names using the "get\_hard\_locked\_list" method (See [get\_hard\_locked\_list](/docs/maci/object/methods/get_hard_locked_list)). A Gotcha, but not really. Something to keep in mind is that any objects that are mutable (e.g. a list, dict, set) can still be updated in-place even if you lock/hard-lock an attribute name. Locking is a feature to protect the attribute name, not the value. Any immutable object must always be re-assigned to a name, hence why locking will protect against that. #### Map Assignment Glyph Mapping a name to another name. This feature allows an attribute name to follow another attribute name's value. Use the map assignment glyph and set the value to be the name of the attribute name you want to follow. This feature effectively gives you a pointer-like ability, especially with python's native optimization features to reference the same object in memory for its immutable data types. ```python name1 = 'data' name2 +m= name1 ``` During the code's runtime, if the parent attribute name is ever reassigned or if the object it is assigned to changes, the child attribute name will always update its reference to match the parent. Take note, that the name must already exist to assign a name to follow it. If you wish to follow any other names that are not in a file, you may utilize the "map\_attr" method in code to map to names (See [map\_attr](/docs/maci/object/methods/map_attr)). \ \ It is possible to create a chain-like structure of your references as well like so: ```python name1 = 'data' name2 +m= name1 name3 +m= name2 name4 +m= name3 name5 +m= name4 ``` In this use case, if the parent name changes its value, all child names will update as well following one after another linked together like a chain. It is also possible to create a key-ring-like structure of your references as well like so: ```python name1 = 'data' name2 +m= name1 name3 +m= name1 name4 +m= name1 name5 +m= name1 ``` In this use case, if the parent name changes its value, all child names will update as well referencing the same parent. This is different from the chain concept where they are not following one after another, and just referencing the same parent, kind of like all keys on a single ring. \ \ You can have multiple mapped children to as many parents as you want. Once a name is assigned to another name, that other name will now become a parent. It is possible to have a name be a parent and a child simultaneously, and that is demonstrated in the chain concept. If you need to release a reference to a name, you may utilize the partner method **"unmap\_attr"** to achieve this (See [unmap\_attr](/docs/maci/object/methods/unmap_attr)). This will safely release the reference even if the name is locked. You can also reassign the child to another name or value and that will cause it to detach as well, but if it is locked, then a lock exception with be thrown. You may view all map references and references in a chain-like view using the following methods: [get\_all\_maps](/docs/maci/object/methods/get_all_maps) = Shows all parent and child map references\ [get\_parent\_maps](/docs/maci/object/methods/get_parent_maps) = Shows all parent map references\ [get\_child\_maps](/docs/maci/object/methods/get_child_maps) = Shows all child map references\ [get\_parent\_map\_chains](/docs/maci/object/methods/get_parent_map_chains) = Shows all parent map references as a chain #### Map and Lock Assignment Glyphs Mapping and locking a name. You may combine certain glyphs to assign multiple features to a name. In this example you can map a child name to a parent name, then also lock that name from being changed. No matter the letter order you choose, maci will always first create the reference map, then lock the name to establish an assigned value before locking. *Example using map and lock* ```python name1 = 'data' name2 +ml= name1 ``` *Example using map and hard lock* ```python name1 = 'data' name2 +mh= name1 ``` This combo may be desired if you want a name to initially reference another name's value, then to lock it so it is unchanged. Keep in mind though, if the parent name changes, the parent will change, but the child will not and throw an exception. You may [unlock](/docs/maci/object/methods/unlock_attr) or [unmap](/docs/maci/object/methods/unmap_attr) the child name temporarily in code to make any changes to the parent without receiving an exception from the child. If you wish to have the child mapped again, then it first must be unlocked if using a normal lock, then simply re-map with [map\_attr](/docs/maci/object/methods/map_attr) and then re-lock with [lock\_attr ](/docs/maci/object/methods/lock_attr)the child to the parent again.\ \ Another reason this combo may be desired is if you have a strict set of rules on names that cannot or should not be changed. This can promote architecting your code more carefully to maintain integrity of the names if certain aspects of your program heavily rely on those attribute names. For example, creating a dependency model using the chain concept where if a top or upper-level name changes via re-assignment, then the children that depend on that data will throw exceptions, which can be indicative to not change that data cause certain points of the program depend on it. Again, this can promote rethinking how the data should be updated more carefully depending on how you design it. ### multiline data Certain data types may be represented over multiple lines in a file or string as well and will be read the same as if in a single line. Data types that support going over multiple lines will be represented in that format from maci's dump functions by default. The behavior can be changed by toggling some of the varying parameters (See [functions](/docs/maci/functions)). *Example list, dict, tuple, set* ```python name_list = [ 1, 2, 3 ] name_dict = { 'k1': 1, 'k2': 2, 'k3': 3 } name_tuple = ( 1, 2, 3 ) name_set = { 1, 2, 3 } ``` This format structure is typically desired for easier readability and that is why it is the default output behavior. This behavior will also automatically handle nested data structures as well, maintaining a clean human-readable format. **All multiline data must have their data enclosed properly** by their respective delimiting partner character placing it as the first character on a newline trailing the data like in the example above. maci's dump functions auto-handles the formatting on this for any supported objects it accepts. You may also represent multi-line string data to be loaded as well using triple-quoted strings. However, this is not the default format representation when using the dump functions for reasons of maintaining the integrity of the original string data. This is due to a multi-line string requiring 2 extra characters added to the string, being a leading and trailing newline character, to maintain maci's parsing format structure. If desired, that behavior can be turned on for the dump functions (See [functions](/docs/maci/functions)). *Example multiline string* ```python name_double_quote_str1 = """ data1 data2 data3 """ name_single_quote_str = ''' data1 data2 data3 ''' ``` If this dump behavior is turned on, it will generate your string data into a multi-line format only if it detects newline characters in your string. Upon each newline it detects, it will set the next line of data based on that newline detected. *Note: maci will natively load multi-line strings in files.* If your string data contains a matching delimiting triple-quoted string at the start of a newline, it will terminate the read at that point just like python would. However, if it contains an opposite triple-quoted string like single triple-quotes inside of double triple-quotes, maci is smart enough to ignore that. You may also escape it if you need both, see example below. *maci ignores the single triple-quotes and vice versa if encapsulated by opposite quote type* ```python name_str = """ data1 '''data2 data3 """ ``` *Escaping the double triple-quotes* ```python name_str = """ data1 \"""data2 data3 """ ``` ### comments Commenting using the native python "#" syntax is fully supported. Multiline comments using single or double quotes are **not** currently supported but are targeted to feature and support in the future. *Example comment syntax variations in file* ```python # My comment data1 = 1 # my comment data2 = [ 1, 2, # my comment 3#my comment ] # my comment # My comment # My comment data3 = (#my comment 1, 2, 3 )#my comment ``` ## language syntax Describes the varying syntax structure and data type literals
### assignment structure maci follows and accepts a very similar and familiar name assignment structure as python, with the exception of adding special glyphs to perform special operations. You may assign names to values using any of the following methods: Examples are represented using a file *Space before and after "=". Common* [*pep8*](https://peps.python.org/pep-0008/) *style. Default structure from dump function format* ```python name = 'John' ``` *Space before "="* ```python name ='John' ``` *Space after "="* ```python name= 'John' ``` *No Spaces between "="* ```python name='John' ``` *Many Random Spaces* ```python name = 'John' ``` Syntax also works for all assignment glyphs *Hard lock with no spaces* ```python name+h='John' ``` ### string concatenation maci supports in-line implicit string concatenation on assignments. This is currently the only supported use of string concatenation in this language version Example is represented using a file ```python data1 = "hello" " world" data2 = "hello"" world" data3 = 'hello' ' ' 'world' ``` ### data types maci parses and supports a very similar experience and representation of primitive data types likened to python using a hybrid parsing concept where maci reads and parses the data to prepare for validation, to then be validated and transformed into a python object leveraging the [ast library](https://docs.python.org/3/library/ast.html). The mechanics of how it is parsed are not the same of course, but the native data type representation found in python's basic data types can be written similarly. maci attempts to keep it as familiar to python as possible to make the usage of data feel natural and not hard to learn if you're already comfortable with python's data types and structure. However, maci may add unique features that python does not have, or lack features that python has. #### Accepted data type literals and format *Literal values are expressed as if written in a file or string to be parsed*
literaltypedescription
"data"strString data in double-quotes
'data'strString data in single-quotes
'''data'''strString data in single triple-quotes
"""data"""strString data in double triple-quotes
1intInteger data
10_000intInteger data using underscores
1.0floatFloating point data
TrueboolBoolean data
[1,2,3]listList data
{'k1': 1}dictDictionary data
(1,2,3)tupleTuple data
1, 2, 3tupleTuple data without parenthesis
{1,2,3}setSet data
NoneNoneTypeNone data
b'data\n'bytesBytes data in single quotes
b"data\n"bytesBytes data in double quotes
b'''data\n'''bytesBytes data in single triple-quotes
b"""data\n"""bytesBytes data in double triple-quotes
2023-12-02 21:48:00datetimeDatetime data as date and time
2023-12-02 21:48:00.050datetimeDatetime data as date and time.microseconds
21:48:00 2023-12-02datetimeDatetime data as time and date
21:48:00.050 2023-12-02datetimeDatetime data as time.microseconds and date
2023-12-02T21:48:00-06:00datetimeDatetime data as ISO 8601
2023-12-02datetime.dateDatetime data as date
21:48:00datetime.timeDatetime data as time
21:48:00.050datetime.timeDatetime data as time.microseconds
#### Accepted string literal prefixes These are [python-specific string literal prefixes](https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals) that adhere to python's natural handling to produce the same results. maci does not do anything to handle these and is solely handled by the [ast library](https://docs.python.org/3/library/ast.html).
literaltypedescription
r"data"strRaw prefixed string
b"data"bytesBytes prefixed string
u"\u263A"strUnicode prefixed string
rb"data\n"bytesPrefixed string with raw and bytes combo
br"data\n"bytesPrefixed string with bytes and raw combo
Strings that contain any of the above prefixes can be parsed by maci leveraging the ast library. f-strings are **not** currently supported but are targeted to feature and support in the future. # functions api functions for maci [maci.build](/docs/maci/functions/maci.build) [maci.load](/docs/maci/functions/maci.load) [maci.loadstr](/docs/maci/functions/maci.loadstr) [maci.loadattrs](/docs/maci/functions/maci.loadattrs) [maci.loadraw](/docs/maci/functions/maci.loadraw) [maci.loaddict](/docs/maci/functions/maci.loaddict) [maci.loadstrdict](/docs/maci/functions/maci.loadstrdict) [maci.dump](/docs/maci/functions/maci.dump) [maci.dumpstr](/docs/maci/functions/maci.dumpstr) [maci.dumpraw](/docs/maci/functions/maci.dumpraw) # maci.build builds a maci data object Calling this function will simply return an empty [MaciDataObj](/docs/maci/object) to build out data in your maci object manually. This function currently has no parameters. {% hint style="info" %} maci.build -> [MaciDataObj](/docs/maci/object) {% endhint %} *Example building maci data object and building out data* ```python data = maci.build() data.mydata1 = 'data' data.mydata2 = [1,2,3] data.mydata3 = True ``` In this example, we created a new empty maci object and assigned it to a variable, then created new attribute names with data assigned. You may use any of the maci object features with this new object (See [methods](/docs/maci/object/methods)). # maci.load loads maci data from a file ### loading a file Loads any plain text file that contains maci data that follows the maci language syntax (See [language](/docs/maci/language)), and returns a [MaciDataObj](/docs/maci/object). {% hint style="info" %} maci.load -> [MaciDataObj](/docs/maci/object) {% endhint %} *Basic Example of loading a file using default positional parameter* ```python data = maci.load('my.data') ``` In this example, we simply load maci data from a file using the load function and pass a string of the filepath to the file as an argument to the function to load the maci data, and assign the returned data object to a variable. Access the data by their individual and respective attribute names like you normally would on an object in python. *Example accessing and viewing the data* ```python data.mydata1 print(data.mydata1) ``` You may also view all maci data simply by printing or viewing the repr of the object (See [object](/docs/maci/object)) ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
attr_name_dedup: bool Optional parameter. Accepts booleans. Default = True Use this parameter to enable/disable Attribute Name Deduplication. The default setting is enabled. This feature protects against having duplicate attribute names loaded from a file. This is helpful if a name has already been defined in the file previously and you do not want it to be overwritten accidentally. This ensures attribute names are unique in your file especially when loading large data sets having thousands of names where it may be hard to keep track. \ \ It will also protect against re-assigning an already existing method name in the maci data object.\ \ You may disable this feature by setting this parameter to False if you need names to be overwritten, but it is recommended to leave it on and write names uniquely.
encoding: str | None Optional parameter. Accepts strings or None. Default = None Use this parameter to load the data with the desired codec of the encoded data if needed. The default uses the default of python, so you don't have to use this, but you can if the data is using a specific codec.
_ignore_maci_attr_check: bool Private optional parameter. Accepts booleans. Default = False It is not recommended to use this as it may break the internal functionality of the maci object or may not allow you to change the name at all still. \ \ With that said, use this parameter to enable using names that match names the maci object is already using. For example "\_MaciDataObjConstructor\_\_assignment\_hard\_locked\_attribs". It is a very low chance to have such a name collision, but if you do, just name it with a number or extra underscore or something instead of disabling this. This must be used in combination with the [attr\_name\_dedup](https://docs.macilib.org/docs/maci/functions/maci.load#attr_name_dedup-bool) parameter set to False in order to potentially work. NOTE: Some internal attr names that are re-assigned may not show up in the object's repr, but name's value still may get set
# maci.loadstr loads maci data from a string ### loading a string Loads a string that contains maci data that follows the maci language syntax (See [language](/docs/maci/language)), and returns a [MaciDataObj](/docs/maci/object). {% hint style="info" %} maci.loadstr -> [MaciDataObj](/docs/maci/object) {% endhint %} *Basic Example of loading a string using default positional parameter* ```python data = maci.loadstr('mydata1 = "data1" \nmydata2 = "data2"') ``` In this example, we simply load maci data from a string using the loadstr function passing a maci formatted string as the first argument to the function to load the maci data, and assign the returned data object to a variable. Access the data by their individual and respective attribute names like you normally would on an object in python. *Example accessing and viewing the data* ```python data.mydata1 data.mydata2 print(data.mydata1) print(data.mydata2) ``` You may also view all maci data simply by printing or viewing the repr of the object (See [object](/docs/maci/object)) ### parameters & arguments Describes all parameter functionality and accepted data types
maci_str_data: str First and only required positional argument. Accepts strings. Use this parameter to pass in your maci formatted string data
attr_name_dedup: bool Optional parameter. Accepts booleans. Default = True Use this parameter to enable/disable Attribute Name Deduplication. The default setting is enabled. This feature protects against having duplicate attribute names loaded from a string. This is helpful if a name has already been defined in the string previously and you do not want it to be overwritten accidentally. This ensures attribute names are unique in your string especially when loading large data sets having thousands of names where it may be hard to keep track. \ \ It will also protect against re-assigning an already existing method name in the maci data object.\ \ You may disable this feature by setting this parameter to False if you need names to be overwritten, but it is recommended to leave it on and write names uniquely.
# maci.loadattrs loads maci data from a file into any class/object ### loading data from a file Loads any plain text file that contains formatted maci data that follows the maci language syntax (See [language](/docs/maci/language)), and loads the attribute names and data into a custom class/object. This is done in-place, so nothing is returned. This can be very useful to load data back into an object whether already stored or after being stored to a file from the partner function [maci.dump](broken://pages/iDpQZ6gfz5ySQsP0QjXW). *Basic Example of loading data from file into object using default positional parameters* ```python maci.loadattrs('my.data', my_object) ``` In this example, we simply load maci formatted data from a file using the loadattrs function and pass a string of the filepath to the file as the first argument to the function, then pass the custom object as the second argument to the function, and the data gets loaded into the object in-place. *Example data inside the file* ``` mydata1 = 'data1' mydata2 = 2 ``` Access the data by their individual and respective attribute names like you normally would on an object in python. *Example accessing and viewing the data* ```python my_object.mydata1 my_object.mydata2 print(my_object.mydata1) print(my_object.mydata2) ``` ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
class_object: ClassObject Second required positional argument. Accepts any general custom object Use this parameter to pass in your object to load data into it in-place
attr_name_dedup: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable/disable Attribute Name Deduplication. The default setting is disabled to loosen the constraints for your custom object data. This feature protects against having duplicate attribute names loaded from a file. This is helpful if a name has already been defined in the file previously and you do not want it to be overwritten accidentally. This ensures attribute names are unique in your file especially when loading large data sets having thousands of names where it may be hard to keep track. \ \ You may enable this feature by setting this parameter to True if you need names to be protected, especially when they have already been defined in code. This really depends on your data to determine if this feature is beneficial to you.
encoding: str | None Optional parameter. Accepts strings or None. Default = None Use this parameter to load the data with the desired codec of the encoded data if needed. The default uses the default of python, so you don't have to use this, but you can if the data is using a specific codec.
_ignore_maci_attr_check: bool Private optional parameter. Accepts booleans. Default = True Use this parameter by setting it to False to disallow using matching names that maci object is already using. For example "\_MaciDataObjConstructor\_\_assignment\_hard\_locked\_attribs". It is not necessary to disable this unless you want to protect internal maci object names for some reason, because you are loading any potential names into your custom object, this is not something to be concerned about.
# maci.loadraw loads raw data from a file ### loading a file raw Loads any raw data from a file and returns a string by default, or optionally bytes. This is helpful to easily load file data without writing extra boilerplate code just to load raw data from a file. {% hint style="info" %} maci.loadraw -> str | bytes {% endhint %} *Basic Example of loading a file using default positional parameter* ```python data = maci.loadraw('my.data') ``` In this example, we simply load raw data from a file using the loadraw function and pass a string of the filepath to the file as an argument to the function to load the raw data, and assign the returned data to a variable. *Example viewing the data and its original representation* ```python print(data) print(repr(data)) ``` ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
byte_data: bool Optional parameter. Accepts booleans. Default = False Use this parameter to set loading your data from the file as bytes. Default is disabled as returning file data as a string is more common, but enable it if you need the data returned as bytes.
encoding: str | None Optional parameter. Accepts strings or None. Default = None Use this parameter to load the data with the desired codec of the encoded data if needed. The default uses the default of python, so you don't have to use this, but you can if the data is using a specific codec.
# maci.loaddict loads maci data from a file as dict ### loading data from a file Loads any plain text file that contains formatted maci data that follows the maci language syntax (See [language](/docs/maci/language)), and returns the attribute names and data as a dictionary representing them as key/value pairs. {% hint style="info" %} maci.loaddict -> dict {% endhint %} *Basic Example of loading a file using default positional parameter* ```python data = maci.loaddict('my.data') ``` In this example, we simply load maci formatted data from a file using the loaddict function and pass a string of the filepath to the file as the first argument to the function, and assign the returned dictionary object data to a variable. *Example data inside the file* 
mydata1 = 'data1'
mydata2 = 2
Access the data by their individual and respective key names like you normally would on a dictionary in python. *Example accessing and viewing the data* ```python data['mydata1'] data['mydata2'] print(data['mydata1']) print(data['mydata2']) ``` ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
attr_name_dedup: bool Optional parameter. Accepts booleans. Default = False *(Changed in v1.1.1)* Use this parameter to enable/disable Attribute Name Deduplication. The default setting is disabled. This feature protects against having duplicate attribute names loaded from a file. This is helpful if a name has already been defined in the file previously and you do not want it to be overwritten accidentally. This ensures attribute names are unique in your file, especially when loading large data sets having thousands of names where it may be hard to keep track. \ \ You may enable this feature by setting this parameter to True if you need names to not get overwritten. Note: maci internal names may cause name collisions
encoding: str | None Optional parameter. Accepts strings or None. Default = None Use this parameter to load the data with the desired codec of the encoded data if needed. The default uses the default of python, so you don't have to use this, but you can if the data is using a specific codec.
# maci.loadstrdict loads maci data from a string as dict ### loading data from a string Loads a string that contains formatted maci data that follows the maci language syntax (See [language](/docs/maci/language)), and returns the attribute names and data as a dictionary representing them as key/value pairs. {% hint style="info" %} maci.loadstrdict -> dict {% endhint %} *Basic Example of loading a string using default positional parameter* ```python data = maci.loadstrdict('mydata1 = "data1" \nmydata2 = "data2"') ``` In this example, we simply load maci formatted data from a string using the loadstrdict function by passing a maci formatted string as an argument to the function, and assign the returned dictionary object data to a variable. Access the data by their individual and respective key names like you normally would on a dictionary in python. *Example accessing and viewing the data* ```python data['mydata1'] data['mydata2'] print(data['mydata1']) print(data['mydata2']) ``` ### parameters & arguments Describes all parameter functionality and accepted data types
maci_str_data: str First and only required positional argument. Accepts strings. Use this parameter to pass in your maci formatted string data
attr_name_dedup: bool Optional parameter. Accepts booleans. Default = False *(Changed in v1.1.1)* Use this parameter to enable/disable Attribute Name Deduplication. The default setting is disabled. This feature protects against having duplicate attribute names loaded from a string. This is helpful if a name has already been defined in the string previously and you do not want it to be overwritten accidentally. This ensures attribute names are unique in your string, especially when loading large data sets having thousands of names where it may be hard to keep track. \ \ You may enable this feature by setting this parameter to True if you need names to not get overwritten. Note: maci internal names may cause name collisions
# 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](/docs/maci/language)). Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/maci/functions/maci.dump#append-bool) to change mode) *Basic Example of dumping data to a file using default positional parameters* ```python 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*](/docs/maci/object) ```python maci_obj.mydata1 = 'data1' maci_obj.mydata2 = 2 maci.dump('my.data', maci_obj) ``` *Example of dumping dict* ```python dict_data = {'mydata1': 'data1', 'mydata2': 2} maci.dump('my.data', dict_data) ``` *Example of dumping custom object* ```python my_object.mydata1 = 'data1' my_object.mydata2 = 2 maci.dump('my.data', my_object) ``` *Resulted output contents in example file from all object dumps* ```python 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](https://docs.python.org/3/library/pathlib.html) 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](https://docs.macilib.org/docs/maci/language/v1.0.0#multiline-data) 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](https://docs.macilib.org/docs/maci/language/v1.0.0#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](/docs/maci/functions/maci.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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool)) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool)) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool)) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/language/v1.0.0#assignment-glyph-legend) 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](https://github.com/aaronater10/maci?tab=readme-ov-file#-previous-project-support)), but it is instead encouraged to use the main maci supported glyphs from the glyph legend.
# maci.dumpstr dumps maci, dict, or object data to a string ### dumping a string Dumps maci, dict, or custom object data to a string. The returned string is a structured format following the maci language syntax (See [language](/docs/maci/language)). {% hint style="info" %} maci.dumpstr -> str {% endhint %} *Basic Example of dumping data to a string using default positional parameter* ```python data = maci.dumpstr(mydata) ``` In this example, we simply dump data to a string using the dump function and pass the data as an argument to the function, and assign the returned data to a variable. *Example of dumping* [*MaciDataObj*](/docs/maci/object) ```python maci_obj.mydata1 = 'data1' maci_obj.mydata2 = 2 data = maci.dumpstr(maci_obj) ``` *Example of dumping dict* ```python dict_data = {'mydata1': 'data1', 'mydata2': 2} data = maci.dumpstr(dict_data) ``` *Example of dumping custom object* ```python my_object.mydata1 = 'data1' my_object.mydata2 = 2 data = maci.dumpstr(my_object) ``` *Resulted output contents in example string from all object dumps* ```python "mydata1 = 'data1'\nmydata2 = 2" ``` ### parameters & arguments Describes all parameter functionality and accepted data types
data: MaciDataObj | dict | ClassObject First and only 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 string.
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 string. 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](https://docs.macilib.org/docs/maci/language/v1.0.0#multiline-data) 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](https://docs.macilib.org/docs/maci/language/v1.0.0#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](/docs/maci/functions/maci.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.
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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool)) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool)) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool)) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/functions/maci.dump#class_attrs-bool) 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](https://docs.macilib.org/docs/maci/language/v1.0.0#assignment-glyph-legend) 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](https://github.com/aaronater10/maci?tab=readme-ov-file#-previous-project-support)), but it is instead encouraged to use the main maci supported glyphs from the glyph legend.
# maci.dumpraw dumps raw data to a file dumping raw data to file Dumps any data raw to a file. This is helpful to easily dump data without writing extra boilerplate code just to dump data raw to a file. Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/maci/functions/maci.dumpraw#append-bool) to change mode). *Basic Example of dumping to a file using default positional parameters* ```python maci.dumpraw('my.data', data) ``` In this example, we simply dump any raw data to a file using the dumpraw function and pass a string of the filepath to the file as the first argument to the function, then pass any data as the second argument to the function to be written to the file. ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
*data: Any Second required positional argument. Accepts any data type. This parameter accepts any number of positional arguments but must supply at least 1 at a minimum.
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.
byte_data: bool Optional parameter. Accepts booleans. Default = False Use this parameter to set dumping your data to the file as bytes. Default is disabled as dumping the string representation is more common, but enable it if you need the data written as bytes.
newline_sep: bool Optional parameter. Accepts booleans. Default = True Use this parameter to enable/disable the newline separator character set between each piece of data when passing more than 1 positional argument to [data](https://docs.macilib.org/docs/maci/functions/maci.dumpraw#data-any) parameter. Default is enabled to receive a more expected or desirable result in the file.
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.
# object maci data object The maci data object is a custom data type that provides unique functionality to perform useful operations on attribute names in the object and is responsible for holding all stored data during the runtime of the code. *Type name representation:* MaciDataObj ### building a maci data object To build a maci data object in code, you may run the simple build function (See [maci.build](/docs/maci/functions/maci.build)). This will return an empty maci object.
*Example creating an empty maci data object using the* [*maci build function*](/docs/maci/functions/maci.build) ```python data = maci.build() ``` ### creating and setting attribute names with data Whether loaded from a file (See [maci.load](/docs/maci/functions/maci.load)) or in code, you can create and set attribute names and assign data to them on the object in code like you normally would expect in python.
*Example creating and setting attributes names in code with basic data* ```python data.attr1 = 1 data.attr2 = 2 data.attr3 = 3 ``` See [maci.load](/docs/maci/functions/maci.load) and [language section](/docs/maci/language) for loading data from a file ### object view You may view the representation of the object by printing the object directly, or calling the [str()](https://docs.python.org/3.12/library/stdtypes.html#str) or [repr()](https://docs.python.org/3.12/library/functions.html#repr) functions on the object. The resulting output will display all attribute names and their currently assigned values.\ \ *Example output showing current attribute names and their respective data* ```python MaciDataObj(attr1=1, attr2=2, attr3=3) ``` If the object is empty, it will show like so: ```python MaciDataObj() ``` ### object operators and built-in behavior *maci version 1.0.0* #### equality Compare maci objects to each other to check for equality. This will check if the data attribute names and values inside the object are exactly the same. Does not check value identity. *Example comparing maci objects* ```python maci_obj1 == maci_obj2 ``` #### bool Call the bool built-in function on the object to check if the object is empty or not. Empty means no defined attribute names and values. *Example calling built-in bool function on maci object* ```python bool(maci_obj) ``` *Added in maci version 1.1.1* #### hashability maci objects are hashable and may be used as keys in data structures as an example. The hash is uniquely generated once per object instance lifetime, and you may modify the object without the hash changing. This allows more flexibility to interconnect maci objects and still update them. *Example using maci object as key in dict* ```python dict_data[maci_obj] ``` #### length Call the len built-in function on the maci object to get the current length of it. Length is the count of how many attribute names have been defined. *Example calling built-in len function on maci object* ```python len(maci_obj) ``` ### object methods Perform varying operations on the attribute names or data for the object using the built-in methods. \ \ You can set attribute names to be locked like a constant, or map attribute names to another like a pointer, get views of the object data and their states, and more. See the object's api [methods section](/docs/maci/object/methods) for all useful functionality ### object hinting *maci version 1.0.0* Typing for the MaciDataObj is currently supported if needed for type checkers. This is being currently tested using [mypy](https://www.mypy-lang.org/) for type safety. Updates may be made in the future for uncaught scenarios that is not passing mypy or other type checkers. Conveniently, you can access the MaciDataObj type to hint it in your code from the maci module. *Example accessing the MaciDataObj type for hinting* ```python maci.hint.MaciDataObj ``` See [hints section](/docs/maci/hints) for more on this and other types # methods api methods for MaciDataObj [lock\_attr](/docs/maci/object/methods/lock_attr) [unlock\_attr](/docs/maci/object/methods/unlock_attr) [hard\_lock\_attr](/docs/maci/object/methods/hard_lock_attr) [map\_attr](/docs/maci/object/methods/map_attr) [unmap\_attr](/docs/maci/object/methods/unmap_attr) [load\_attrs](/docs/maci/object/methods/load_attrs) [get\_attrs](/docs/maci/object/methods/get_attrs) [get\_locked\_list](/docs/maci/object/methods/get_locked_list) [get\_hard\_locked\_list](/docs/maci/object/methods/get_hard_locked_list) [get\_all\_maps](/docs/maci/object/methods/get_all_maps) [get\_parent\_maps](/docs/maci/object/methods/get_parent_maps) [get\_child\_maps](/docs/maci/object/methods/get_child_maps) [get\_parent\_map\_chains](/docs/maci/object/methods/get_parent_map_chains) [is\_parent\_map](/docs/maci/object/methods/is_parent_map) [is\_child\_map](/docs/maci/object/methods/is_child_map) # lock\_attr lock an attribute name Locks an attribute name from reassignment. Nothing is returned.\ \ Attribute names that are locked cannot be reassigned to a new value, but a locked attribute name can be deleted or unlocked (See [unlock\_attr](/docs/maci/object/methods/unlock_attr)). If there is an attempt to reassign an attribute name that is currently locked, an exception will be thrown. Attribute names must already exist to lock them. You cannot have an attribute name locked and [hard-locked](/docs/maci/object/methods/hard_lock_attr) simultaneously. Only one lock type can be used on an attribute name at a time.
*Basic Example of locking a name using default positional parameter* ```python data.lock_attr('attr_name') ``` In this example, we simply lock an attribute name that already exists in the [MaciDataObj](/docs/maci/object) using the lock\_attr method and pass a string of the attribute name as an argument to the method to lock the name. ### partner methods Methods that provide related utility to this method [unlock\_attr](/docs/maci/object/methods/unlock_attr) -> Unlock an attribute name\ [get\_locked\_list](/docs/maci/object/methods/get_locked_list) -> View all the currently locked attribute names ### parameters & arguments Describes all parameter functionality and accepted data types
attr_name: str First and only required positional argument. Accepts strings Use this parameter to pick attribute name to lock
# unlock\_attr unlock an attribute name Unlocks an attribute name that is currently locked. Nothing is returned. Any attribute name that is currently locked from reassignment (See [lock\_attr](/docs/maci/object/methods/lock_attr)) only can be unlocked using this method, which reinstates the ability to reassign that attribute name to new values again. Unlocking an attribute name will only affect the general lock (See [lock\_attr](/docs/maci/object/methods/lock_attr)). \ *Basic Example of unlocking a name using default positional parameter* ```python data.unlock_attr('attr_name') ``` In this example, we simply unlock an attribute name that already exists in the [MaciDataObj](/docs/maci/object) and is also currently present in the [lock list](/docs/maci/object/methods/get_locked_list) by passing a string of the attribute name as an argument to the unlock\_attr method to unlock the name. ### partner methods Methods that provide related utility to this method [lock\_attr](/docs/maci/object/methods/lock_attr) -> Lock an attribute name\ [get\_locked\_list](/docs/maci/object/methods/get_locked_list) -> View all the currently locked attribute names ### parameters & arguments Describes all parameter functionality and accepted data types
attr_name: str First and only required positional argument. Accepts strings Use this parameter to pick attribute name to unlock
# hard\_lock\_attr hard lock an attribute name Hard Locks an attribute name from reassignment, unlocking, and deletion. Nothing is returned.\ \ Attribute names that are hard-locked cannot be reassigned to a new value, unlocked, or deleted. If there is an attempt to reassign, unlock, or delete an attribute name that is currently hard-locked, an exception will be thrown. Attribute names must already exist to hard lock them. The [unlock\_attr](/docs/maci/object/methods/unlock_attr) method does not evaluate the hard-locked attribute names at all and will throw an exception stating the name does not exist in [lock](/docs/maci/object/methods/lock_attr). You cannot have an attribute name hard-locked and [locked](/docs/maci/object/methods/lock_attr) simultaneously. Only one lock type can be used on an attribute name at a time.
*Basic Example of hard-locking a name using default positional parameter* ```python data.hard_lock_attr('attr_name') ``` In this example, we simply hard-lock an attribute name that already exists in the [MaciDataObj](/docs/maci/object) using the hard\_lock\_attr method and pass a string of the attribute name as an argument to the method to hard-lock the name. ### partner methods Methods that provide related utility to this method [get\_hard\_locked\_list](/docs/maci/object/methods/get_hard_locked_list) -> View all the current hard-locked attribute names ### parameters & arguments Describes all parameter functionality and accepted data types
attr_name: str First and only required positional argument. Accepts strings Use this parameter to pick attribute name to hard-lock
# map\_attr map attribute name to another Maps an attribute name to another attribute name. Nothing is returned. Attribute names that are mapped to another attribute name will allow it to follow that name's value. The name that requests the map, will become the child, and the name that the child maps to becomes the parent. Attribute names for the child and parent must already exist to map them. This feature works similarly to the concept of a pointer. It also maintains reference to the same object in memory naturally from python's inherent optimization design. See more information on the mapping concept in the [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph) language section.
*Basic Example of mapping a name using default positional parameters* ```python data.map_attr('attr_name_child', 'attr_name_parent') ``` In this example, we simply map an attribute name that already exists in the [MaciDataObj](/docs/maci/object) using the map\_attr method and pass a string of the child attribute name as the first argument to the method, then pass the parent attribute name as the second argument to the method. ### partner methods Methods that provide related utility to this method [unmap\_attr](/docs/maci/object/methods/unmap_attr) -> Unmap an attribute name\ [get\_all\_maps](/docs/maci/object/methods/get_all_maps) -> Get all parent and child maps\ [get\_parent\_maps](/docs/maci/object/methods/get_parent_maps) -> Get all parent maps\ [get\_child\_maps](/docs/maci/object/methods/get_child_maps) -> Get all child maps\ [get\_parent\_map\_chains](/docs/maci/object/methods/get_parent_map_chains) -> Get parent maps represented as a chain\ [is\_parent\_map](/docs/maci/object/methods/is_parent_map) -> Check if attribute name is a parent mapped with children\ [is\_child\_map](/docs/maci/object/methods/is_child_map) -> Check if attribute name is a child mapped to a parent ### parameters & arguments Describes all parameter functionality and accepted data types
child_attr: str First required positional argument. Accepts strings Use this parameter to set the child attribute name that will follow the parent attribute name.
parent_attr: str Second required positional argument. Accepts strings Use this parameter to set the parent attribute name for the child attribute name to follow.
# unmap\_attr unmap an attribute name Unmaps an attribute name from the other attribute name. Nothing is returned. Any attribute name that is currently mapped to another attribute name (See [map\_attr](/docs/maci/object/methods/map_attr)) can be unmapped using this method. Attribute names must already exist to unmap them. This will release the mapping between a child attribute name and the corresponding parent attribute name. In addition, If a parent attribute name is specified, that contains children with references to it, all child mappings will be detached from that parent
*Basic Example of unmapping a name using default positional parameter* ```python data.unmap_attr('attr_name') ``` In this example, we simply unmap an attribute name that already exists in the [MaciDataObj](/docs/maci/object) and is also currently present in the reference maps by passing a string of the attribute name as an argument to the unmap\_attr method to unmap the name. ### partner methods Methods that provide related utility to this method [map\_attr](/docs/maci/object/methods/map_attr) -> Map an attribute name\ [get\_all\_maps](/docs/maci/object/methods/get_all_maps) -> Get all parent and child maps\ [get\_parent\_maps](/docs/maci/object/methods/get_parent_maps) -> Get all parent maps\ [get\_child\_maps](/docs/maci/object/methods/get_child_maps) -> Get all child maps\ [get\_parent\_map\_chains](/docs/maci/object/methods/get_parent_map_chains) -> Get parent maps represented as a chain\ [is\_parent\_map](/docs/maci/object/methods/is_parent_map) -> Check if attribute name is a parent mapped with children\ [is\_child\_map](/docs/maci/object/methods/is_child_map) -> Check if attribute name is a child mapped to a parent ### parameters & arguments Describes all parameter functionality and accepted data types
attr_name: str First and only required positional argument. Accepts strings Use this parameter to pick the attribute name to release its map reference(s).
# load\_attrs load attribute names and data Loads data from a dict into the [MaciDataObj](/docs/maci/object) in-place. Nothing is returned. All key and value pairs in the top level of the dictionary will be loaded creating new attribute names, with their respective values retained, in the maci object based on the key names of the dict. If the key name is not a valid [pythonic name convention](https://peps.python.org/pep-0008/), it will be skipped. \ *Basic Example of loading attribute names from dict using default positional parameter* ```python data.load_attrs({'attr1': 1, 'attr2': 2, 'attr3': 3}) ``` In this example, we simply load attribute names and their values into the [MaciDataObj](/docs/maci/object) using the load\_attrs method and pass a dictionary representing the names/values we want to load in the object as an argument to the method. This is done in-place on the object. Access the data by their individual and respective attribute names like you normally would on an object in python. *Example accessing and viewing the data* ```python data.attr1 data.attr2 data.attr3 print(data.attr3) ``` ### parameters & arguments Describes all parameter functionality and accepted data types
data: dict[str, Any] First and only required positional argument. Accepts dictionaries Use this parameter to pass in a dictionary to load your attribute names and values into the maci object
# get\_attrs get dict of attribute names and values Generates a dictionary of the [MaciDataObj's](/docs/maci/object) current attribute names and values, and returns a dict. This method currently has no parameters. Useful if it is desired to view or pull all current attribute names and values on the object. {% hint style="info" %} data.get\_attrs() -> dict\[str, Any] {% endhint %} \ *Basic Example of getting a dictionary of the current attribute names/values of the* [*MaciDataObj*](/docs/maci/object) ```python dict_data = data.get_attrs() ``` In this example, we simply use the get\_attrs method on the [MaciDataObj](/docs/maci/object) to get a generated copy of the current attribute names and values, currently held inside the maci object, to receive a dictionary representing the attribute names as key names and their respective associated values, and assign the returned dict data to a variable. # get\_locked\_list get list of locked attribute names Generates a list of the [MaciDataObj's](/docs/maci/object) currently locked attribute names, and returns a list. This method currently has no parameters. Useful if it is desired to view or reference all currently locked attribute names. {% hint style="info" %} data.get\_locked\_list() -> list\[str] {% endhint %} \ *Basic Example of getting a list of the currently locked attribute names of the* [*MaciDataObj*](/docs/maci/object) ```python list_data = data.get_locked_list() ``` In this example, we simply use the get\_locked\_list method on the [MaciDataObj](/docs/maci/object) to get a generated copy of the currently locked attribute names, currently held inside the maci object, as a list of strings, and assign the returned list data to a variable. ### partner methods Methods that provide related utility to this method [lock\_attr](/docs/maci/object/methods/lock_attr) -> Lock an attribute name\ [unlock\_attr](/docs/maci/object/methods/unlock_attr) -> Unlock an attribute name
# get\_hard\_locked\_list get list of hard locked attribute names Generates a list of the [MaciDataObj's](/docs/maci/object) currently hard-locked attribute names, and returns a list. This method currently has no parameters. Useful if it is desired to view or reference all currently hard-locked attribute names. {% hint style="info" %} data.get\_hard\_locked\_list() -> list\[str] {% endhint %} \ *Basic Example of getting a list of the currently hard-locked attribute names of the* [*MaciDataObj*](/docs/maci/object) ```python list_data = data.get_hard_locked_list() ``` In this example, we simply use the get\_hard\_locked\_list method on the [MaciDataObj](/docs/maci/object) to get a generated copy of the currently hard-locked attribute names, currently held inside the maci object, as a list of strings, and assign the returned list data to a variable. ### partner methods Methods that provide related utility to this method [hard\_lock\_attr](/docs/maci/object/methods/hard_lock_attr) -> Hard Lock an attribute name # get\_all\_maps get dict of all parent and child maps Generates a dictionary of all the [MaciDataObj's](/docs/maci/object) currently mapped parent and child attribute name references, and returns a dict representation of the maps. This method currently has no parameters. Useful if it is desired to view or reference all currently mapped attribute names. {% hint style="info" %} data.get\_all\_maps() -> dict\[str, dict\[str, Any] {% endhint %} \ *Basic Example of getting a dict of all the currently mapped attribute names of the* [*MaciDataObj*](/docs/maci/object) ```python dict_data = data.get_all_maps() ``` In this example, we simply use the get\_all\_maps method on the [MaciDataObj](/docs/maci/object) to get a generated copy of the currently mapped parent and child attribute name references, currently held inside the maci object, as a dictionary, and assign the returned dict data to a variable. Each map has its own dedicated key name. Examples below show empty maps and maps with a basic reference. *Example output of empty maps showing dedicated key names* ```python {'parent_maps': {}, 'child_maps': {}} ``` *Example output of maps with basic references* ```python {'parent_maps': {'attr1': {'attr2': 'attr1'}}, 'child_maps': {'attr2': 'attr1'}} ``` Parent maps will have their own parent key name matching its attribute name with a value to all child maps referencing the parent attribute name. Child maps will have their own child key name matching its attribute name with a value to the parent attribute name they are referencing.
For more information on the mapping concept, see [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph) in the language section and [map\_attr](/docs/maci/object/methods/map_attr). ### partner methods Methods that provide related utility to this method [map\_attr](/docs/maci/object/methods/map_attr) -> Map an attribute name\ [unmap\_attr](/docs/maci/object/methods/unmap_attr) -> Unmap an attribute name # get\_parent\_maps get dict of all parent maps Generates a dictionary copy of all the [MaciDataObj's](/docs/maci/object) currently mapped parent attribute name references to its children, and returns a dict of the maps. This method currently has no parameters. Useful if it is desired to view or reference all parent attribute names with their child mappings. {% hint style="info" %} data.get\_parent\_maps() -> dict\[str, dict\[str, str] {% endhint %} \ *Basic Example of getting a dict of current parent mappings of the* [*MaciDataObj*](/docs/maci/object) ```python dict_data = data.get_parent_maps() ``` In this example, we simply use the get\_parent\_maps method on the [MaciDataObj](/docs/maci/object) to get a generated copy of the current parent attribute names with their child mappings, currently held inside the maci object, as a dictionary, and assign the returned dict data to a variable. Parent maps have their own dedicated key name. Example below shows maps with a basic reference. *Example output of parent maps with basic references* ```python {'attr1': {'attr2': 'attr1'}, 'attr2': {'attr3': 'attr2'}} ``` Parent maps will have their own parent key name matching its attribute name with a value to all child maps referencing the parent attribute name. The values of the child maps will have their own child key name matching its attribute name with a value to the parent attribute name they are referencing.
For more information on the mapping concept, see [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph) in the language section and [map\_attr](/docs/maci/object/methods/map_attr). ### partner methods Methods that provide related utility to this method [map\_attr](/docs/maci/object/methods/map_attr) -> Map an attribute name\ [unmap\_attr](/docs/maci/object/methods/unmap_attr) -> Unmap an attribute name # get\_child\_maps get dict of all child maps Generates a dictionary copy of all the [MaciDataObj's](/docs/maci/object) currently mapped child attribute names with the references to their parent, and returns a dict of the maps. This method currently has no parameters. Useful if it is desired to view or reference all child attribute names with their parent mappings. {% hint style="info" %} data.get\_child\_maps() -> dict\[str, str] {% endhint %} \ *Basic Example of getting a dict of current child mappings of the* [*MaciDataObj*](/docs/maci/object) ```python dict_data = data.get_child_maps() ``` In this example, we simply use the get\_child\_maps method on the [MaciDataObj](/docs/maci/object) to get a generated copy of the current child attribute names with their mapping to their respective parent, currently held inside the maci object, as a dictionary, and assign the returned dict data to a variable.
*Example output of child maps with basic references* ```python {'attr2': 'attr1', 'attr3': 'attr2'} ``` Child maps will have their own child key name matching its attribute name with a value to the parent attribute name they are referencing.
For more information on the mapping concept, see [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph) in the language section and [map\_attr](/docs/maci/object/methods/map_attr). ### partner methods Methods that provide related utility to this method [map\_attr](/docs/maci/object/methods/map_attr) -> Map an attribute name\ [unmap\_attr](/docs/maci/object/methods/unmap_attr) -> Unmap an attribute name # get\_parent\_map\_chains get dict of parent maps with chain of their children as list Generates a dictionary of all the [MaciDataObj's](/docs/maci/object) currently mapped parent attribute name references to its children, and returns a dict of the maps with the values represented in a chain-like structure using lists. Useful if it is desired to view all parent attribute names with their interconnected child mappings following each other in order. {% hint style="info" %} data.get\_parent\_map\_chains() -> dict\[str, list\[str]] | list\[str] {% endhint %} \ *Basic Example getting all current parent mappings of the* [*MaciDataObj*](/docs/maci/object) *as chains with no parameters* ```python dict_data = data.get_parent_map_chains() ``` In this example, we simply use the get\_parent\_map\_chains method on the [MaciDataObj](/docs/maci/object) to get a generated dict of all the current parent attribute names with their child mappings, currently held inside the maci object, represented as a dictionary, and assign the returned data to a variable.
*Example output of a basic parent map with the children following it as a chain* ```python {'attr1': ['attr1', 'attr2', 'attr3', 'attr4', 'attr5']} ``` Parent maps have their own parent key name matching its attribute name and value being a list of attribute names starting with the parent as the first name, then children following one after another. You may also pass in the known parent key name of the chain you wish to retrieve using the "parent\_attr" optional positional parameter.
*Example passing the name "attr1" in the method to receive its chain output* ```python data.get_parent_map_chains('attr1') ``` ```python ['attr1', 'attr2', 'attr3', 'attr4', 'attr5'] ``` As mentioned in the language section [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph), It is possible to have a name be a parent and a child simultaneously. This is evaluated whether a child that is following a parent also has children following it and they are all interlinked together one after another. However, if it is just a parent and not a child, it will gain its own key name with its own chain. If a child breaks off from the chain being reassigned to a new value and has children following it, it will gain its own chain separate from the one it was linked to. In addition, if a child happens to break off from the chain by being unmapped (See [unmap\_attr](/docs/maci/object/methods/unmap_attr)) or deleted, the child will just be released from the chain mapping. However, if the child that broke off was unmapped or deleted and was also a parent, the next child will inherit the role of a parent if it also has children and gain its own chain.
*Example output of "attr3" breaking off chain by reassignment gaining its own chain* ```python {'attr1': ['attr1', 'attr2'], 'attr3': ['attr3', 'attr4', 'attr5']} ``` *Example output of "attr3" breaking off chain by unmap or deletion and next child gains its own chain* ```python {'attr1': ['attr1', 'attr2'], 'attr4': ['attr4', 'attr5']} ``` #### key-ring exception If a chain attempts to generate with multiple children mapped to the same parent, an exception will be thrown by default stating it cannot build a chain with multiple children linked to the same parent. That behavior would describe more of a key-ring like structure over a chain. See [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph) for more on that. If you wish to ignore that check, use [dup\_link\_check](https://docs.macilib.org/docs/maci/object/methods/get_parent_map_chains#dup_link_check-bool) parameter to disable it, but your chains may break off into separate chains if encountered as explained above. For more information on the mapping concept, see [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph) in the language section and [map\_attr](/docs/maci/object/methods/map_attr). ### partner methods Methods that provide related utility to this method [map\_attr](/docs/maci/object/methods/map_attr) -> Map an attribute name\ [unmap\_attr](/docs/maci/object/methods/unmap_attr) -> Unmap an attribute name ### parameters & arguments Describes all parameter functionality and accepted data types
parent_attr: str | None Optional first positional parameter. Accepts strings or None. Default = None. Use this parameter to retrieve a chain from a specific parent attribute name
dup_link_check: bool Optional parameter. Accepts booleans. Default = True. Protects against duplicate child links being built to the parent. If disabled and a duplicate is found, it will still return chain(s), but will cut the chain's previous child links to the parent and only continue the chain from the last child to the parent and retain any chain links following the last child. It is worth stating, this method does not break/affect the actual behavior of the attributes being linked together, as the get\_parent\_map\_chains method only fresh builds a representation of the attributes linked together in the form of a chain for your reference to help understand what attribute names are connected to each other. The true linking is controlled by other mechanics, and any real duplicate links are not affected as that is acceptable behavior.
# is\_parent\_map check if attribute name is a parent Checks if an attribute name in the [MaciDataObj](/docs/maci/object) is a parent mapped with children, and returns a bool. {% hint style="info" %} data.is\_parent\_map() -> bool {% endhint %} \ *Basic Example checking if an attribute name is a parent in the* [*MaciDataObj*](/docs/maci/object) ```python result = data.is_parent_map('attr1') ``` In this example, we simply use the is\_parent\_map method on the [MaciDataObj](/docs/maci/object) to get a boolean check if the attribute name passed into the parameter is a parent mapped with children, and assign the returned bool to a variable. For more information on the mapping concept, see [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph) in the language section and [map\_attr](/docs/maci/object/methods/map_attr). ### partner methods Methods that provide related utility to this method [map\_attr](/docs/maci/object/methods/map_attr) -> Map an attribute name\ [unmap\_attr](/docs/maci/object/methods/unmap_attr) -> Unmap an attribute name ### parameters & arguments Describes all parameter functionality and accepted data types
attr_name: str First and only required positional argument. Accepts strings Use this parameter to pick the attribute name to check.
# is\_child\_map check if attribute name is a child Checks if an attribute name in the [MaciDataObj](/docs/maci/object) is a child mapped to a parent, and returns a bool. {% hint style="info" %} data.is\_child\_map() -> bool {% endhint %} \ *Basic Example checking if an attribute name is a child in the* [*MaciDataObj*](/docs/maci/object) ```python result = data.is_child_map('attr2') ``` In this example, we simply use the is\_child\_map method on the [MaciDataObj](/docs/maci/object) to get a boolean check if the attribute name passed into the parameter is a child mapped to a parent, and assign the returned bool to a variable. For more information on the mapping concept, see [Map Assignment Glyph](https://docs.macilib.org/docs/maci/language/v1.0.0#map-assignment-glyph) in the language section and [map\_attr](/docs/maci/object/methods/map_attr). ### partner methods Methods that provide related utility to this method [map\_attr](/docs/maci/object/methods/map_attr) -> Map an attribute name\ [unmap\_attr](/docs/maci/object/methods/unmap_attr) -> Unmap an attribute name ### parameters & arguments Describes all parameter functionality and accepted data types
attr_name: str First and only required positional argument. Accepts strings Use this parameter to pick the attribute name to check.
# errors all errors and exceptions All exceptions/errors thrown from the maci library, including 3rd-party libraries, are redirected and handled with a maci-specific naming convention and helpful output. The helpful output aims to try and provide useful and easy-to-understand information to quickly gather the reason for the exception thrown. This helpful output effort will consistently be improved or reiterated, and therefore an example will not be given. ### path name convention The exception path name convention contains 3-parts and ensures simplicity in locating the exception.\ \ Here is the convention and how to break it down: *Example exception name:* maci.error.ExceptionName * `maci` is the top-level module name. * `error` is a submodule of `maci`, which contains definitions of various error or exception classes related to the `maci` module. * `ExceptionName` is the class name of the specific exception being raised. ### handling exception thrown Any time an exception is thrown, maci will provide the true module path followed by the class name of the exception to keep it simple, so there is no need to import anything additional to handle it.\ \ *Example of maci exception thrown by* [*load*](/docs/maci/functions/maci.load) *showing the full module and class path for bad filepath* ```bash maci.error.Load: [Errno 2] No such file or directory: 'test.data' ``` If needing to handle this, you would simply write or copy the exception path, and that will handle that specific exception. *Example handling above exception* ```python try: ... except maci.error.Load: ... ``` ### maci base exception All maci exceptions derive from its base exception **MaciError**. To handle all exceptions thrown from the maci library, you can handle the following exception path: ```python maci.error.MaciError ``` # hints all type hints All type hints from the maci library and third-party libraries are accessible through the "hint" module to annotate unique or custom data types. Placing them in one location aims to provide a simple way of finding the desired unique types you need to annotate. ### path name convention The hint path name convention contains 3-parts and ensures simplicity in locating the data type.\ \ Here is the convention and how to break it down: *Example data type name:* maci.hint.DataType * `maci` is the top-level module name. * `hint` is a submodule of `maci`, which contains definitions of various data type classes. * `DataType` is the class name of the specific data type. ### type hint usage *Example of using the* [*MaciDataObj*](/docs/maci/object) *type to annotate a variable and function* ```python # variable maci_obj: maci.hint.MaciDataObj = maci.build() # function def fn(data: maci.hint.MaciDataObj) -> maci.hint.MaciDataObj: ... ``` Note: There are other types available in the "hint" module for thin wrapper api functions used like xml, ini, etc,. # json thin wrapper functions and information for json This section describes the thin wrapper api functions for processing JSON data. [functions](/docs/json/functions) The thin api functions used for the maci library that enable JSON functionality, use and wrap the native json library shipped with the python standard library for its underlying functionality. For more information on the json library, visit: # functions api functions for maci.json\* [maci.jsonload](/docs/json/functions/maci.jsonload) [maci.jsonloadstr](/docs/json/functions/maci.jsonloadstr) [maci.jsondump](/docs/json/functions/maci.jsondump) [maci.jsondumpstr](/docs/json/functions/maci.jsondumpstr) # maci.jsonload loads json data from a file ### loading a file Loads json file data, and returns the corresponding python data type. {% hint style="info" %} maci.jsonload -> list | dict | str | int | float | bool | None {% endhint %} *Basic Example of loading a json file using default positional parameter* ```python data = maci.jsonload('mydata.json') ``` In this example, we simply load json data from a file using the jsonload function and pass a string of the filepath to the file as an argument to the function to load the json data, and assign the returned data to a variable. ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
encoding: str | None Optional parameter. Accepts strings or None. Default = None Use this parameter to load the data with the desired codec of the encoded data if needed. The default uses the default of python, so you don't have to use this, but you can if the data is using a specific codec.
*This function uses the native json library shipped with the python standard library for its underlying functionality. For more information on the json library, visit:* [*https://docs.python.org/3/library/json.html*](https://docs.python.org/3/library/json.html) # maci.jsonloadstr loads json data from a string ### loading a string Loads json string data, and returns the corresponding python data type. {% hint style="info" %} maci.jsonloadstr -> list | dict | str | int | float | bool | None {% endhint %} *Basic Example of loading a json string using default positional parameter* ```python data = maci.jsonloadstr('{"key1": "value1", "key2": "value2"}') ``` In this example, we simply load json data from a string using the jsonloadstr function and pass a string as an argument to the function to load the json data, and assign the returned data to a variable. ### parameters & arguments Describes all parameter functionality and accepted data types
json_str_data: str First and only required positional argument. Accepts strings Use this parameter to pass in your json formatted string data
*This function uses the native json library shipped with the python standard library for its underlying functionality. For more information on the json library, visit:* [*https://docs.python.org/3/library/json.html*](https://docs.python.org/3/library/json.html) # maci.jsondump dumps data to a file as json ### dumping a file Dumps the corresponding python data types to a file formatted as JSON. Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/json/functions/maci.jsondump#append-bool) to change mode). *Basic Example of dumping data to a file using default positional parameters* ```python maci.jsondump('mydata.json', data) ``` In this example, we simply dump data to a file using the jsondump 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. ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
data: dict | list | tuple | str | int | float | bool | None Second required positional argument. Accepts dictionaries, lists, tuples, strings, integers, floats, booleans, and None Use this parameter to pass in the data you want to dump to a file.
append: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable appending mode to write by appending data to the file. A new file will be created if the filename does not exist. Default is disabled which writes new or overwrites a file.
indent_level: int Optional parameter. Accepts integers. Default = 4 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. This parameter sets the true underlying indent level for the json library. 1 level = 1 space
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.
*This function uses the native json library shipped with the python standard library for its underlying functionality. For more information on the json library, visit:* [*https://docs.python.org/3/library/json.html*](https://docs.python.org/3/library/json.html) # maci.jsondumpstr dumps data to a string as json ### dumping a string Dumps the corresponding python data types to a string formatted as JSON. {% hint style="info" %} maci.jsondumpstr -> str {% endhint %} *Basic Example of dumping data to a string using default positional parameters* ```python json_string = maci.jsondumpstr(data) ``` In this example, we simply dump data to a string formatted as json using the jsondumpstr function and pass the data as an argument to the function, and assign the returned data to a variable. ### parameters & arguments Describes all parameter functionality and accepted data types
data: dict | list | tuple | str | int | float | bool | None First and only required positional argument. Accepts dictionaries, lists, tuples, strings, integers, floats, booleans, and None Use this parameter to pass in the data you want to dump to a string.
indent_level: int Optional parameter. Accepts integers. Default = 4 Use this parameter to change the indentation level for structured data (lists, dicts, tuples, sets) written to the string. Indentation will be applied to nested data as well. This parameter sets the true underlying indent level for the json library. 1 level = 1 space
*This function uses the native json library shipped with the python standard library for its underlying functionality. For more information on the json library, visit:* [*https://docs.python.org/3/library/json.html*](https://docs.python.org/3/library/json.html) # yaml thin wrapper functions and information for yaml This section describes the thin wrapper api functions for processing YAML data. [functions](/docs/yaml/functions) The thin api functions used for the maci library that enable YAML functionality, use and wrap the PyYAML framework installed as a dependency from pypi for its underlying functionality. **Loading note**: Uses the "safe\_load" and "safe\_load\_all" methods only to protect from untrusted input. **Dumping note**: Uses the "safe\_dump" and "safe\_dump\_all" methods, which only support standard YAML tags and cannot represent an arbitrary Python object For more information on PyYAML, visit: # functions api functions for maci.yaml\* [maci.yamlload](/docs/yaml/functions/maci.yamlload) [maci.yamlloadstr](/docs/yaml/functions/maci.yamlloadstr) [maci.yamlloadall](/docs/yaml/functions/maci.yamlloadall) [maci.yamldump](/docs/yaml/functions/maci.yamldump) [maci.yamldumpstr](/docs/yaml/functions/maci.yamldumpstr) [maci.yamldumpall](/docs/yaml/functions/maci.yamldumpall) # maci.yamlload loads yaml data from a file ### loading a file Loads yaml file data, and returns the corresponding python data type. {% hint style="info" %} maci.yamlload -> Any {% endhint %} *Basic Example of loading a yaml file using default positional parameter* ```python data = maci.yamlload('mydata.yml') ``` In this example, we simply load yaml data from a file using the yamlload function and pass a string of the filepath to the file as an argument to the function to load the yaml data, and assign the returned data to a variable.\ \ **Note:** This function loads a single yaml document in the file. If looking to load multiple yaml documents from a file, use the [yamlloadall](/docs/yaml/functions/maci.yamlloadall) function. ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
encoding: str | None Optional parameter. Accepts strings or None. Default = None Use this parameter to load the data with the desired codec of the encoded data if needed. The default uses the default of python, so you don't have to use this, but you can if the data is using a specific codec.
*This function uses the PyYAML framework installed as a dependency from pypi for its underlying functionality. It is only using the "safe\_load" method to protect from untrusted input. For more information on PyYAML, visit:* [*https://pypi.org/project/PyYAML/*](https://pypi.org/project/PyYAML/) # maci.yamlloadstr loads yaml data from a string ### loading a string Loads yaml string data, and returns the corresponding python data type. {% hint style="info" %} maci.yamlloadstr -> Any {% endhint %} *Basic Example of loading a yaml string using default positional parameter* ```python data = maci.yamlloadstr('key1: value1 \nkey2: value2') ``` In this example, we simply load yaml data from a string using the yamlloadstr function and pass a string as an argument to the function to load the yaml data, and assign the returned data to a variable. ### parameters & arguments Describes all parameter functionality and accepted data types
yaml_str_data: str First and only required positional argument. Accepts strings Use this parameter to pass in your yaml formatted string data
*This function uses the PyYAML framework installed as a dependency from pypi for its underlying functionality. It is only using the "safe\_load" method to protect from untrusted input. For more information on PyYAML, visit:* [*https://pypi.org/project/PyYAML/*](https://pypi.org/project/PyYAML/) # maci.yamlloadall loads multiple yaml docs from a file ### loading a file Loads multiple yaml documents from a file, and returns the corresponding python data types. {% hint style="info" %} maci.yamlloadall -> Iterator\[Any] {% endhint %} *Basic Example of loading a yaml file with multiple docs using default positional parameter* ```python data = maci.yamlloadall('mydata.yml') ``` In this example, we simply load a file that contains multiple yaml documents using the yamlloadall function and pass a string of the filepath to the file as an argument to the function to load the yaml data, and assign the returned data to a variable. The returned data will be an iterator with each item containing the individual yaml document data.\ \ Information on writing multiple YAML docs in a file:\ \ ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
encoding: str | None Optional parameter. Accepts strings or None. Default = None Use this parameter to load the data with the desired codec of the encoded data if needed. The default uses the default of python, so you don't have to use this, but you can if the data is using a specific codec.
*This function uses the PyYAML framework installed as a dependency from pypi for its underlying functionality. It is only using the "safe\_load\_all" method to protect from untrusted input. For more information on PyYAML, visit:* [*https://pypi.org/project/PyYAML/*](https://pypi.org/project/PyYAML/) # maci.yamldump dumps data to a file as yaml ### dumping a file Dumps the corresponding python data types to a file formatted as YAML. Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/yaml/functions/maci.yamldump#append-bool) to change mode). *Basic Example of dumping data to a file using default positional parameters* ```python maci.yamldump('mydata.yml', data) ``` In this example, we simply dump data to a file using the yamldump 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.\ \ **Note:** This function dumps a single yaml document to the file. If looking to dump multiple yaml documents to a file, use the [yaml](/docs/yaml/functions/maci.yamlloadall)[dumpall](/docs/yaml/functions/maci.yamldumpall) function. ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
data: Any Second required positional argument. Accepts Any Use this parameter to pass in the data you want to dump to a file.
append: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable appending mode to write by appending data to the file. A new file will be created if the filename does not exist. Default is disabled which writes new or overwrites a file.
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.
*This function uses the PyYAML framework installed as a dependency from pypi for its underlying functionality. It is only using the "safe\_dump" method, which only supports standard YAML tags and cannot represent an arbitrary Python object. For more information on PyYAML, visit:* [*https://pypi.org/project/PyYAML/*](https://pypi.org/project/PyYAML/) # maci.yamldumpstr dumps data to a string as yaml ### dumping a string Dumps the corresponding python data types to a string formatted as YAML. {% hint style="info" %} maci.yamldumpstr -> str {% endhint %} *Basic Example of dumping data to a string using default positional parameters* ```python yaml_string = maci.yamldumpstr(data) ``` In this example, we simply dump data to a string formatted as yaml using the yamldumpstr function and pass the data as an argument to the function, and assign the returned data to a variable. ### parameters & arguments Describes all parameter functionality and accepted data types
data: Any First and only required positional argument. Accepts Any Use this parameter to pass in the data you want to dump to a string.
*This function uses the PyYAML framework installed as a dependency from pypi for its underlying functionality. It is only using the "safe\_dump" method, which only supports standard YAML tags and cannot represent an arbitrary Python object. For more information on PyYAML, visit:* [*https://pypi.org/project/PyYAML/*](https://pypi.org/project/PyYAML/) # maci.yamldumpall dumps multiple yaml docs to a file ### dumping a file Dumps any iterable with the corresponding python data types to a file with each item formatted as individual YAML documents. Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/yaml/functions/maci.yamldumpall#append-bool) to change mode). *Basic Example of dumping data to a file as multiple docs using default positional parameters* ```python maci.yamldumpall('mydata.yml', data) ``` In this example, we simply dump data that is an iterable object to a file using the yamldumpall 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. The data passed in will be iterated over with each item being an individual yaml document in the file.\ \ Information on multiple YAML docs in a file:\ \ ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
data: Iterable[Any] Second required positional argument. Accepts Iterable\[Any] Use this parameter to pass in the data you want to dump to a file.
append: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable appending mode to write by appending data to the file. A new file will be created if the filename does not exist. Default is disabled which writes new or overwrites a file.
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.
*This function uses the PyYAML framework installed as a dependency from pypi for its underlying functionality. It is only using the "safe\_dump\_all" method, which only supports standard YAML tags and cannot represent an arbitrary Python object. For more information on PyYAML, visit:* [*https://pypi.org/project/PyYAML/*](https://pypi.org/project/PyYAML/) # toml thin wrapper functions and information for toml This section describes the thin wrapper api functions for processing TOML data. [functions](/docs/toml/functions) The thin api functions used for the maci library that enable TOML functionality, use and wrap the tomli & tomli-w libraries installed as dependencies from pypi for its underlying functionality. For more information on tomli, visit: \ For more information on tomli-w, visit: # functions api functions for maci.toml\* [maci.tomlload](/docs/toml/functions/maci.tomlload) [maci.tomlloadstr](/docs/toml/functions/maci.tomlloadstr) [maci.tomldump](/docs/toml/functions/maci.tomldump) [maci.tomldumpstr](/docs/toml/functions/maci.tomldumpstr) # maci.tomlload loads toml data from a file ### loading a file Loads toml file data, and returns a dictionary. {% hint style="info" %} maci.tomlload -> dict\[str, Any] {% endhint %} *Basic Example of loading a toml file using default positional parameter* ```python data = maci.tomlload('mydata.toml') ``` In this example, we simply load toml data from a file using the tomlload function and pass a string of the filepath to the file as an argument to the function to load the toml data, and assign the returned data to a variable. ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
*This function uses the tomli library installed as a dependency from pypi for its underlying functionality. For more information on tomli, visit:* [*https://pypi.org/project/tomli/*](https://pypi.org/project/tomli/) # maci.tomlloadstr loads toml data from a string ### loading a string Loads toml string data, and returns a dictionary. {% hint style="info" %} maci.tomlloadstr -> dict\[str, Any] {% endhint %} *Basic Example of loading a toml string using default positional parameter* ```python data = maci.tomlloadstr('key1 = "value1" \nkey2 = "value2"') ``` In this example, we simply load toml data from a string using the tomlloadstr function and pass a string as an argument to the function to load the toml data, and assign the returned data to a variable. ### parameters & arguments Describes all parameter functionality and accepted data types
toml_str_data: str First and only required positional argument. Accepts strings Use this parameter to pass in your toml formatted string data
*This function uses the tomli library installed as a dependency from pypi for its underlying functionality. For more information on tomli, visit:* [*https://pypi.org/project/tomli/*](https://pypi.org/project/tomli/) # maci.tomldump dumps data to a file as toml ### dumping a file Dumps a dictionary to a file formatted as TOML. Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/toml/functions/maci.tomldump#append-bool) to change mode). *Basic Example of dumping data to a file using default positional parameters* ```python maci.tomldump('mydata.toml', data) ``` In this example, we simply dump data to a file using the tomldump function and pass a string of the filepath to the file as the first argument to the function, then pass the dictionary data as the second argument to the function. ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
data: dict[str, Any] Second required positional argument. Accepts dictionaries Use this parameter to pass in the data you want to dump to a file.
append: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable appending mode to write by appending data to the file. A new file will be created if the filename does not exist. Default is disabled which writes new or overwrites a file.
multi_line_str: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable writing string values as a multiline string. Default behavior is disabled matching the default for the tomli-w library.
*This function uses the tomli-w library installed as a dependency from pypi as its underlying functionality. For more information on tomli-w, visit:* [*https://pypi.org/project/tomli-w/*](https://pypi.org/project/tomli-w/) # maci.tomldumpstr dumps data to a string as toml ### dumping a string Dumps a dictionary to a string formatted as TOML. {% hint style="info" %} maci.tomldumpstr -> str {% endhint %} *Basic Example of dumping data to a string using default positional parameters* ```python toml_string = maci.tomldumpstr(data) ``` In this example, we simply dump data to a string formatted as toml using the tomldumpstr function and pass dictionary data as an argument to the function, and assign the returned data to a variable. ### parameters & arguments Describes all parameter functionality and accepted data types
data: dict[str, Any] First and only required positional argument. Accepts dictionaries Use this parameter to pass in the data you want to dump to a string.
multi_line_str: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable writing string values as a multiline string. Default behavior is disabled matching the default for the tomli-w library.
*This function uses the tomli-w library installed as a dependency from pypi as its underlying functionality. For more information on tomli-w, visit:* [*https://pypi.org/project/tomli-w/*](https://pypi.org/project/tomli-w/) # ini thin wrapper functions and information for ini This section describes the thin wrapper api functions for processing INI data. The underlying functionality can also load ".conf, .cfg" files since they are nearly similar syntactically. [functions](/docs/ini/functions) The thin api functions used for the maci library that enable INI functionality, use and wrap the native configparser library shipped with the python standard library for its underlying functionality. For more information on the configparser library, visit: # functions api functions for maci.ini\* [maci.iniload](/docs/ini/functions/maci.iniload) [maci.inidump](/docs/ini/functions/maci.inidump) [maci.inibuildauto](/docs/ini/functions/maci.inibuildauto) [maci.inibuildmanual](/docs/ini/functions/maci.inibuildmanual) # maci.iniload loads ini data from a file ### loading a file Loads ini file data, and returns a [ConfigParser](https://docs.python.org/3/library/configparser.html) object. This function can also load ".conf, .cfg" files. {% hint style="info" %} maci.iniload -> [ConfigParser](https://docs.python.org/3/library/configparser.html) {% endhint %} *Basic Example of loading an ini file using default positional parameter* ```python data = maci.iniload('mydata.ini') ``` In this example, we simply load ini data from a file using the iniload function and pass a string of the filepath to the file as an argument to the function to load the ini data, and assign the returned data to a variable.
*Basic Example of accessing sections and their keys to get values* ```python data['section']['key'] ``` Note: All values in a ini file are [returned as strings](https://docs.python.org/3/library/configparser.html#supported-datatypes), but can be converted with some of the [convenience methods](https://docs.python.org/3/library/configparser.html#configparser.ConfigParser.getint) on the object.
More information on using ConfigParser data:\ Youtube Video Search: \ Documentation: ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
encoding: str | None Optional parameter. Accepts strings or None. Default = None Use this parameter to load the data with the desired codec of the encoded data if needed. The default uses the default of python, so you don't have to use this, but you can if the data is using a specific codec.
*This function uses the native configparser library shipped with the python standard library for its underlying functionality. ExtendedInterpolation is enabled by default. For more information on the configparser library, visit:*[ *https://docs.python.org/3/library/configparser.html*](https://docs.python.org/3/library/configparser.html) # maci.inidump dumps data to a file as ini ### dumping a file Dumps [ConfigParser](https://docs.python.org/3/library/configparser.html) data to a file formatted as INI. Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/ini/functions/maci.inidump#append-bool) to change mode). *Basic Example of dumping data to a file using default positional parameters* ```python maci.inidump('mydata.ini', data) ``` In this example, we simply dump data to a file using the inidump 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. To learn more about building out your ini data in code, see:\ [inibuildauto](/docs/ini/functions/maci.inibuildauto)\ [inibuildmanual](/docs/ini/functions/maci.inibuildmanual)\ \ More information on using ConfigParser data:\ Youtube Video Search: \ Documentation: ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
data: ConfigParser Second required positional argument. Accepts [ConfigParser](https://docs.python.org/3/library/configparser.html) object Use this parameter to pass in the data you want to dump to a file.
append: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable appending mode to write by appending data to the file. A new file will be created if the filename does not exist. Default is disabled which writes new or overwrites a file.
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.
*This function uses the native configparser library shipped with the python standard library for its underlying functionality. For more information on the configparser library, visit:*[ *https://docs.python.org/3/library/configparser.html*](https://docs.python.org/3/library/configparser.html) # maci.inibuildauto auto builds a configparser object from dict Auto builds a [ConfigParser](https://docs.python.org/3/library/configparser.html) object from a dictionary with a correct section and key/value structure. {% hint style="info" %} maci.inibuildauto -> [ConfigParser](https://docs.python.org/3/library/configparser.html) {% endhint %} *Example auto building ConfigParser data with sections and key/values* ```python data_to_build = {'section1': {'key1': 1}, 'section2': {'key2': 2}} data = maci.inibuildauto(data_to_build) ``` In this example, we created a simple dictionary representing sections with key names and their values and assigned the data to a variable, then passed the dict data as an argument to the inibuildauto function to build the ini data and assign the returned data to a variable. #### dictionary structure As shown in the example above, in order to auto-build the ini data for your [ConfigParser](https://docs.python.org/3/library/configparser.html) object, your dictionary must follow a specific structure. The structure is as follows: * All top level key names in dict are sections * All values of each section must contain a dict with key/value pairs *Example structure unpacked* ```python { 'section1': { 'key1': 'value1' }, 'section2': { 'key2': 'value2' } } ``` Values can be anything, but when they are [dumped](/docs/ini/functions/maci.inidump) to a file and loaded back in, they will be loaded as a string type in their string representation (See [iniload](/docs/ini/functions/maci.iniload)) Note: If your sub-value contains a NoneType, this function will auto-convert that to a string representation for you as the underlying library does not support None.\ \ \ More information on using ConfigParser data:\ Youtube Video Search: \ Documentation: ### parameters & arguments Describes all parameter functionality and accepted data types
data: dict[str, dict[str, Any]] First and only required positional argument. Accepts dictionaries Use this parameter to pass in the data you want to build out the [ConfigParser](https://docs.python.org/3/library/configparser.html) object.
*This function uses the native configparser library shipped with the python standard library for its underlying functionality. For more information on the configparser library, visit:*[ *https://docs.python.org/3/library/configparser.html*](https://docs.python.org/3/library/configparser.html) # maci.inibuildmanual gets a configparser object to build from Calling this function will simply return an empty [ConfigParser](https://docs.python.org/3/library/configparser.html) object to build out ini data manually. This function currently has no parameters. {% hint style="info" %} maci.inibuildmanual -> [ConfigParser](https://docs.python.org/3/library/configparser.html) {% endhint %} *Example getting configparser object and building out ini data* ```python data = maci.inibuildmanual() data['section1'] = {'key1': 1} data['section2'] = {'key2': 2} ``` In this example, we created a new empty [ConfigParser](https://docs.python.org/3/library/configparser.html) object and assigned it to a variable, then created new sections names with key/value pair data. Values can be anything, but when they are [dumped](/docs/ini/functions/maci.inidump) to a file and loaded back in, they will be loaded as a string type in their string representation (See [iniload](/docs/ini/functions/maci.iniload)) Note: If your sub-value contains a NoneType, the underlying library does not support None. See [inibuildauto](/docs/ini/functions/maci.inibuildauto) if you want any NoneTypes to be auto-converted to strings, or simply remove or replace the None values with default values. *This function uses the native configparser library shipped with the python standard library for its underlying functionality. For more information on the configparser library, visit:*[ *https://docs.python.org/3/library/configparser.html*](https://docs.python.org/3/library/configparser.html) # xml thin wrapper functions and information for xml This section describes the thin wrapper api functions for processing XML data. The underlying functionality primarily deals with dictionaries and [Element](https://docs.python.org/3/library/xml.etree.elementtree.html) or [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) objects [functions](/docs/xml/functions) The thin api functions used for the maci library that enable XML functionality, use and wrap the native xml.etree library shipped with the python standard library and the xmltodict external library for its underlying functionality. For more information on the xml.etree api, visit: For more information on xmltodict, visit: **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the official python documentation above. Additionally, see the provided tooling to potentially assist with vulnerabilities [\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) # functions api functions for maci.xml\* [maci.xmlload](/docs/xml/functions/maci.xmlload) [maci.xmlloadstr](/docs/xml/functions/maci.xmlloadstr) [maci.xmlloaddict](/docs/xml/functions/maci.xmlloaddict) [maci.xmlloadstrdict](/docs/xml/functions/maci.xmlloadstrdict) [maci.xmldump](/docs/xml/functions/maci.xmldump) [maci.xmldumpstr](/docs/xml/functions/maci.xmldumpstr) [maci.xmldumpdict](/docs/xml/functions/maci.xmldumpdict) [maci.xmldumpstrdict](/docs/xml/functions/maci.xmldumpstrdict) [maci.xmlbuildmanual](/docs/xml/functions/maci.xmlbuildmanual) [maci.\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) # maci.xmlload loads xml data to element or elementtree from a file ### loading a file Loads xml file data, and returns an [Element](https://docs.python.org/3/library/xml.etree.elementtree.html) or [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) object. {% hint style="info" %} maci.xmlload -> [Element](https://docs.python.org/3/library/xml.etree.elementtree.html) | [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) {% endhint %} *Basic Example of loading a xml file using default positional parameter* ```python data = maci.xmlload('mydata.xml') ``` In this example, we simply load xml data from a file using the xmlload function and pass a string of the filepath to the file as an argument to the function to load the xml data, and assign the returned data to a variable. \ *Basic Example of xml data in file and accessing element data* *file example* ```xml one ``` *accessing in code* ```python data.find('data1').text ``` Note: All values in a xml file are returned as strings. \ More information on using Element and ElementTree data:\ Youtube Video Search: \ Documentation: ### partner functions Functions that are related for ElementTree [maci.xmlloadstr](/docs/xml/functions/maci.xmlloadstr) -> Loads xml data from a string as Element object\ [maci.xmldump](/docs/xml/functions/maci.xmldump) -> Dumps xml data to a file from xml etree ElementTree or Element object\ [maci.xmldumpstr](/docs/xml/functions/maci.xmldumpstr) -> Dumps xml data to a string from xml etree Element object\ [maci.xmlbuildmanual](/docs/xml/functions/maci.xmlbuildmanual) -> Returns empty xml ElementTree object to manually build xml data\ [maci.\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) -> Monkey patch and defuse all stdlib packages \[security use] ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
auto_get_root: bool Optional parameter. Accepts booleans. Default = True Returns the root Element object of the ElementTree parsed from a xml file. Default is enabled to simplify data navigation steps. Disable it to get the main ElementTree object.
*This function uses the native xml library etree shipped with the python standard library for its underlying functionality. For more information on the xml.etree api, visit:* [*https://docs.python.org/3/library/xml.etree.elementtree.html*](https://docs.python.org/3/library/xml.etree.elementtree.html) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the official python documentation above. Additionally, see the provided tooling to potentially assist with vulnerabilities [\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) # maci.xmlloadstr loads xml data to element from a string ### loading a string Loads xml string data, and returns an [Element](https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) object. {% hint style="info" %} maci.xmlloadstr -> [Element](https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) {% endhint %} *Basic Example of loading a xml string using default positional parameter* ```python data = maci.xmlloadstr('one') ``` In this example, we simply load xml data from a string using the xmlloadstr function and pass a string as an argument to the function to load the xml data, and assign the returned data to a variable. \ *Basic Example of accessing element data* ```python data.find('data1').text ``` Note: All values in xml data are returned as strings. \ More information on using Element and ElementTree data:\ Youtube Video Search: \ Documentation: ### partner functions Functions that are related for ElementTree [maci.xmlload](/docs/xml/functions/maci.xmlload) -> Loads xml data from a file as Element or ElementTree object\ [maci.xmldump](/docs/xml/functions/maci.xmldump) -> Dumps xml data to a file from xml etree ElementTree or Element object\ [maci.xmldumpstr](/docs/xml/functions/maci.xmldumpstr) -> Dumps xml data to a string from xml etree Element object\ [maci.xmlbuildmanual](/docs/xml/functions/maci.xmlbuildmanual) -> Returns empty xml ElementTree object to manually build xml data\ [maci.\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) -> Monkey patch and defuse all stdlib packages \[security use] ### parameters & arguments Describes all parameter functionality and accepted data types
xml_str_data: str First and only required positional argument. Accepts strings Use this parameter to pass in your xml formatted string data
*This function uses the native xml library etree shipped with the python standard library for its underlying functionality. For more information on the xml.etree api, visit:* [*https://docs.python.org/3/library/xml.etree.elementtree.html*](https://docs.python.org/3/library/xml.etree.elementtree.html) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the official python documentation above. Additionally, see the provided tooling to potentially assist with vulnerabilities [\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) # maci.xmlloaddict loads xml data to dict from a file ### loading a file Loads xml file data, and returns data as a dictionary. {% hint style="info" %} maci.xmlloaddict -> dict\[str, Any] {% endhint %} *Basic Example of loading a xml file using default positional parameter* ```python data = maci.xmlloaddict('mydata.xml') ``` In this example, we simply load xml data from a file using the xmlloaddict function and pass a string of the filepath to the file as an argument to the function to load the xml data, and assign the returned data to a variable. Access data as you normally would with a dictionary in python. Note: All values in a xml file are returned as strings. ### partner functions Functions that are related for xml as dict [maci.xmlloadstrdict](/docs/xml/functions/maci.xmlloadstrdict) -> Loads xml data from a string as dict\ [maci.xmldumpdict](/docs/xml/functions/maci.xmldumpdict) -> Dumps xml data to a file from dict\ [maci.xmldumpstrdict](/docs/xml/functions/maci.xmldumpstrdict) -> Dumps xml data to a string from dict ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First and only required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
*This function uses the xmltodict library installed as a dependency from pypi for its underlying functionality. For more information on xmltodict, visit:* [*https://pypi.org/project/xmltodict/*](https://pypi.org/project/xmltodict/) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the [official python documentation](https://docs.python.org/3/library/xml.etree.elementtree.html). # maci.xmlloadstrdict loads xml data to dict from a string ### loading a string Loads xml string data, and returns data as a dictionary. {% hint style="info" %} maci.xmlloadstrdict -> dict\[str, Any] {% endhint %} *Basic Example of loading a xml string using default positional parameter* ```python data = maci.xmlloadstrdict('one') ``` In this example, we simply load xml data from a string using the xmlloadstrdict function and pass a string as an argument to the function to load the xml data, and assign the returned data to a variable. Access data as you normally would with a dictionary in python. Note: All values in xml data are returned as strings. ### partner functions Functions that are related for xml as dict [maci.xmlloaddict](/docs/xml/functions/maci.xmlloaddict) -> Loads xml data from a file as dict\ [maci.xmldumpdict](/docs/xml/functions/maci.xmldumpdict) -> Dumps xml data to a file from dict\ [maci.xmldumpstrdict](/docs/xml/functions/maci.xmldumpstrdict) -> Dumps xml data to a string from dict ### parameters & arguments Describes all parameter functionality and accepted data types
xml_str_data: str First and only required positional argument. Accepts strings Use this parameter to pass in your xml formatted string data
*This function uses the xmltodict library installed as a dependency from pypi for its underlying functionality. For more information on xmltodict, visit:* [*https://pypi.org/project/xmltodict/*](https://pypi.org/project/xmltodict/) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the [official python documentation](https://docs.python.org/3/library/xml.etree.elementtree.html). # maci.xmldump dumps element or elementtree data to a file as xml ### dumping a file Dumps [Element](https://docs.python.org/3/library/xml.etree.elementtree.html) or [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) object data to a file formatted as XML. Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/xml/functions/maci.xmldump#append-bool) to change mode). *Basic Example of dumping data to a file using default positional parameters* ```python maci.xmldump('mydata.xml', data) ``` In this example, we simply dump data to a file using the xmldump 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. To learn more about building out your xml ElementTree data in code, see [xmlbuildmanual](/docs/xml/functions/maci.xmlbuildmanual)\ \ \ More information on using Element and ElementTree data:\ Youtube Video Search: \ Documentation: ### partner functions Functions that are related for ElementTree [maci.xmlload](/docs/xml/functions/maci.xmlload) -> Loads xml data from a file as Element or ElementTree object\ [maci.xmlloadstr](/docs/xml/functions/maci.xmlloadstr) -> Loads xml data from a string as Element object\ [maci.xmldumpstr](/docs/xml/functions/maci.xmldumpstr) -> Dumps xml data to a string from xml etree Element object\ [maci.xmlbuildmanual](/docs/xml/functions/maci.xmlbuildmanual) -> Returns empty xml ElementTree object to manually build xml data\ [maci.\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) -> Monkey patch and defuse all stdlib packages \[security use] ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
data: ElementTree | Element Second required positional argument. Accepts [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) or [Element](https://docs.python.org/3/library/xml.etree.elementtree.html) 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.
pretty: bool (Added in v1.1.1) Optional parameter. Accepts booleans. Default = True *Only available in py39+* Use this parameter to enable automatic indentation writes on sub-elements. Disable if you want all xml data to be in one line.
full_doc: bool (Added in v1.1.1) Optional parameter. Accepts booleans. Default = True Use this parameter to enable output to be a complete xml document, which includes the xml declaration at the top. Default is enabled for formal xml document info. Disabling is useful when you only need a portion of an XML document or when you are generating xml.
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.
*This function uses the native xml library etree shipped with the python standard library for its underlying functionality. For more information on the xml.etree api, visit:* [*https://docs.python.org/3/library/xml.etree.elementtree.html*](https://docs.python.org/3/library/xml.etree.elementtree.html) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the official python documentation above. Additionally, see the provided tooling to potentially assist with vulnerabilities [\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) # maci.xmldumpstr dumps element data to a string as xml ### dumping a string Dumps [Element](https://docs.python.org/3/library/xml.etree.elementtree.html) object data to a string formatted as XML. *Basic Example of dumping data to a string using default positional parameters* ```python xml_string = maci.xmldumpstr(data) ``` In this example, we simply dump data to a string using the xmldumpstr function and pass data as an argument to the function, and assign the returned data to a variable. To learn more about building out your xml ElementTree data in code, see [xmlbuildmanual](/docs/xml/functions/maci.xmlbuildmanual)\ \ \ More information on using Element data:\ Youtube Video Search: \ Documentation: ### partner functions Functions that are related for ElementTree [maci.xmlload](/docs/xml/functions/maci.xmlload) -> Loads xml data from a file as Element or ElementTree object\ [maci.xmlloadstr](/docs/xml/functions/maci.xmlloadstr) -> Loads xml data from a string as Element object\ [maci.xmldump](/docs/xml/functions/maci.xmldump) -> Dumps xml data to a file from xml etree ElementTree or Element object\ [maci.xmlbuildmanual](/docs/xml/functions/maci.xmlbuildmanual) -> Returns empty xml ElementTree object to manually build xml data\ [maci.\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) -> Monkey patch and defuse all stdlib packages \[security use] ### parameters & arguments Describes all parameter functionality and accepted data types
data: Element First and only required positional argument. Accepts [Element](https://docs.python.org/3/library/xml.etree.elementtree.html) objects Use this parameter to pass in the data you want to dump to a string.
pretty: bool (Added in v1.1.1) Optional parameter. Accepts booleans. Default = True *Only available in py39+* Use this parameter to enable automatic indentation writes on sub-elements. Disable if you want all xml data to be in one line.
full_doc: bool (Added in v1.1.1) Optional parameter. Accepts booleans. Default = True Use this parameter to enable output to be a complete xml document, which includes the xml declaration at the top. Default is enabled for formal xml document info. Disabling is useful when you only need a portion of an XML document or when you are generating xml.
encoding: str Optional parameter. Accepts strings. Default = 'utf-8' Use this parameter to dump the data with the desired codec of the data if needed. The default uses a common industry standard, so you don't have to use this, but you can if the data needs to be written with a specific codec.
*This function uses the native xml library etree shipped with the python standard library for its underlying functionality. For more information on the xml.etree api, visit:* [*https://docs.python.org/3/library/xml.etree.elementtree.html*](https://docs.python.org/3/library/xml.etree.elementtree.html) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the official python documentation above. Additionally, see the provided tooling to potentially assist with vulnerabilities [\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) # maci.xmldumpdict dumps dict data to a file as xml ### dumping a file Dumps a dictionary to a file formatted as XML. Nothing is returned. Creates a new or overwrites an existing file by default (See [append parameter](https://docs.macilib.org/docs/xml/functions/maci.xmldumpdict#append-bool) to change mode). *Basic Example of dumping data to a file using default positional parameters* ```python maci.xmldumpdict('mydata.xml', data) ``` In this example, we simply dump data to a file using the xmldumpdict function and pass a string of the filepath to the file as the first argument to the function, then pass the dictionary data as the second argument to the function. ### partner functions Functions that are related for xml as dict [maci.xmlloaddict](/docs/xml/functions/maci.xmlloaddict) -> Loads xml data from a file as dict\ [maci.xmlloadstrdict](/docs/xml/functions/maci.xmlloadstrdict) -> Loads xml data from a string as dict\ [maci.xmldumpstrdict](/docs/xml/functions/maci.xmldumpstrdict) -> Dumps xml data to a string from dict ### parameters & arguments Describes all parameter functionality and accepted data types
filename: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your filepath
data: dict[str, Any] Second required positional argument. Accepts dictionaries Use this parameter to pass in the data you want to dump to a file.
append: bool Optional parameter. Accepts booleans. Default = False Use this parameter to enable appending mode to write by appending data to the file. A new file will be created if the filename does not exist. Default is disabled which writes new or overwrites a file.
pretty: bool Optional parameter. Accepts booleans. Default = True Use this parameter to enable automatic indentation writes on sub-elements. Disable if you want all xml data to be in one line.
full_doc: bool Optional parameter. Accepts booleans. Default = True Use this parameter to enable output to be a complete xml document, which includes the xml declaration at the top. Default is enabled for formal xml document info. Disabling is useful when you only need a portion of an XML document or when you are generating xml.
*This function uses the xmltodict library installed as a dependency from pypi for its underlying functionality. For more information on xmltodict, visit:* [*https://pypi.org/project/xmltodict/*](https://pypi.org/project/xmltodict/) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the [official python documentation](https://docs.python.org/3/library/xml.etree.elementtree.html). # maci.xmldumpstrdict dumps dict data to a string as xml ### dumping a string Dumps a dictionary to a string formatted as XML. *Basic Example of dumping data to a string using default positional parameters* ```python xml_string = maci.xmldumpstrdict(data) ``` In this example, we simply dump data to a string using the xmldumpstrdict function and pass dictionary data as an argument to the function, and assign the returned data to a variable. ### partner functions Functions that are related for xml as dict [maci.xmlloaddict](/docs/xml/functions/maci.xmlloaddict) -> Loads xml data from a file as dict\ [maci.xmlloadstrdict](/docs/xml/functions/maci.xmlloadstrdict) -> Loads xml data from a string as dict\ [maci.xmldumpdict](/docs/xml/functions/maci.xmldumpdict) -> Dumps xml data to a file from dict ### parameters & arguments Describes all parameter functionality and accepted data types
data: dict[str, Any] First and only required positional argument. Accepts dictionaries Use this parameter to pass in the data you want to dump to a string.
pretty: bool Optional parameter. Accepts booleans. Default = True Use this parameter to enable automatic indentation writes on sub-elements. Disable if you want all xml data to be in one line.
full_doc: bool Optional parameter. Accepts booleans. Default = True Use this parameter to enable output to be a complete xml document, which includes the xml declaration at the top. Default is enabled for formal xml document info. Disabling is useful when you only need a portion of an XML document or when you are generating xml.
*This function uses the xmltodict library installed as a dependency from pypi for its underlying functionality. For more information on xmltodict, visit:* [*https://pypi.org/project/xmltodict/*](https://pypi.org/project/xmltodict/) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the [official python documentation](https://docs.python.org/3/library/xml.etree.elementtree.html). # maci.xmlbuildmanual gets the elementtree module object to build elements Calling this function will simply return the [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html) module object to build out xml [Element](https://docs.python.org/3/library/xml.etree.elementtree.html) or [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html#module-xml.etree.ElementTree) data manually. This function currently has no parameters. {% hint style="info" %} maci.xmlbuildmanual -> [ElementTree Module](https://docs.python.org/3/library/xml.etree.elementtree.html) {% endhint %} *Example getting* [*ElementTree Module*](https://docs.python.org/3/library/xml.etree.elementtree.html) *object and building out xml data using a person concept and dumping the data using* [*xmldump*](/docs/xml/functions/maci.xmldump) ```python ET = maci.xmlbuildmanual() root = ET.Element("person") name = ET.SubElement(root, "name") name.text = "John Doe" age = ET.SubElement(root, "age") age.text = "30" tree = ET.ElementTree(root) maci.xmldump('mydata.xml', tree) ``` In this example, we got the [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html) module with the xmlbuildmanual function, and created a new [ElementTree](https://docs.python.org/3/library/xml.etree.elementtree.html) object structure to build out our data, assigned the final tree build to a variable, then dumped that data to a file. Values for the sub-elements must be strings or None.
More information on using Element and ElementTree data:\ Youtube Video Search: \ Documentation: ### partner functions Functions that are related for ElementTree [maci.xmlload](/docs/xml/functions/maci.xmlload) -> Loads xml data from a file as Element or ElementTree object\ [maci.xmlloadstr](/docs/xml/functions/maci.xmlloadstr) -> Loads xml data from a string as Element object\ [maci.xmldump](/docs/xml/functions/maci.xmldump) -> Dumps xml data to a file from xml etree ElementTree or Element object\ [maci.xmldumpstr](/docs/xml/functions/maci.xmldumpstr) -> Dumps xml data to a string from xml etree Element object\ [maci.\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) -> Monkey patch and defuse all stdlib packages \[security use] *This function uses the native xml library etree shipped with the python standard library for its underlying functionality. For more information on the xml.etree api, visit:* [*https://docs.python.org/3/library/xml.etree.elementtree.html*](https://docs.python.org/3/library/xml.etree.elementtree.html) **Security awareness**: It is important to evaluate handling XML data carefully as there are known vulnerabilities in dealing with XML data. Please refer to the official python documentation above. Additionally, see the provided tooling to potentially assist with vulnerabilities [\_defuse\_xml\_stdlib](/docs/xml/functions/maci._defuse_xml_stdlib) # maci.\_defuse\_xml\_stdlib enable defusedxml feature Calling this function may provide aid in reducing risk factors when working with XML data. Under the hood, this is simply pointing to the [defusedxml library](https://pypi.org/project/defusedxml/) monkey patch standard libraries function. This feature is EXPERIMENTAL according to the developers. Please read below for more information and documentation from the external package and official python docs supporting defusedxml. Reason maci library provides this is to help facilitate more security for XML data and provide a simple easy api solution to enable support.\ \ *Example activating it by calling the function* ```python maci._defuse_xml_stdlib() ``` In this example we simply called the \_defuse\_xml\_stdlib function to activate the defusedxml feature. You only need to call this once during the runtime of the program. It is best to call it at the beginning or before you handle any xml data. The purpose of using `defusedxml.defused_stdlib` is to patch or replace parts of the standard XML parsing libraries (`xml.etree.ElementTree`, `xml.dom.minidom`, `xml.sax`, and others) with safer implementations that prevent these vulnerabilities. This is particularly important for applications that need to process XML data from untrusted sources. *For more information on the provided defusedxml external pkg, visit:* [*https://pypi.org/project/defusedxml*](https://pypi.org/project/defusedxml/) *Official Python doc stating std lib xml vulns and recommending defusedxml:* [*https://docs.python.org/3/library/xml.html#xml-vulnerabilities*](https://docs.python.org/3/library/xml.html#xml-vulnerabilities) # pickle thin wrapper functions and information for pickle data This section describes the thin wrapper api functions for processing pickle data. The underlying functionality primarily deals with pickled byte objects. [functions](/docs/pickle/functions) The thin api functions used for the maci library that enable some pickle functionality, use and wrap the native pickle library shipped with the python standard library for its underlying functionality. For more information on the pickle library and official security concerns with pickling, visit: ### Security awareness It is important to evaluate handling pickled data carefully as it can be very insecure in dealing with pickle data. Please refer to the official python documentation above. To store pickled data to a file using a technique that provides the opportunity to evaluate the pickled data as a byte value before processing it, see [pickledumpbytes](/docs/pickle/functions/maci.pickledumpbytes). This offers an alternative to storing pickled data to a file instead of using a straight pickle file, which is executable by nature, and enables more control over checking the integrity (using your own means) of the data being processed. **Extra information:** As closely mentioned on the main doc homepage, the maci [language](/docs/maci/language) itself (not pickle functions) maintains a different more secure approach with techniques to ensure loading python data is not susceptible to code execution like what you would expect when you load a **py** or **pickle** file (as by design, and not to detract from their native power) to just access variables or attributes and their values. **Python's documentation also states that pickle is insecure** for that reason as well, but there are methods to make pickle secure for that purpose. It is more widely accepted to use common data serialization formats designed for storing values if you want to just load your values or data back whether you use maci or not, but maci does just that as well using python's native types to make your life easier with secure mechanics. # functions api functions for maci.pickle\* [maci.pickleloadbytes](/docs/pickle/functions/maci.pickleloadbytes) [maci.pickledumpbytes](/docs/pickle/functions/maci.pickledumpbytes) # maci.pickleloadbytes load pickled bytes ### loading a byte string Load object data from pickled byte string. **Security awareness**, only unpickle data you trust and review considerations for unpickling data. See more information at [pickle section](/docs/pickle) {% hint style="info" %} maci.pickleloadbytes -> Any {% endhint %} *Basic Example of loading a pickle object from byte string using default positional parameter* ```python data = maci.pickleloadbytes(b'pickledbytedata') ``` In this example, we simply load pickled data using the pickleloadbytes function and pass a byte string as an argument to the function to load the pickled data, and assign the returned data to a variable. #### combining pickle with maci to store data to file To store pickled data to a file, it is more encouraged to store it as a byte string value rather than a whole executable pickle file. The byte string itself is not executable yet as it is stored as a value that can be safely tested (using your own means) before loading it. This approach enables the ability to still store your pickle data to a file as an alternative, and control what byte data is coming in instead of just loading/executing a whole pickle file. See [pickledumpbytes](/docs/pickle/functions/maci.pickledumpbytes) for example on dumping pickled to a file paired with maci ### partner functions Functions that are related for pickleloadbytes [maci.pickledumpbytes](/docs/pickle/functions/maci.pickledumpbytes) -> Dump data to pickled bytes ### parameters & arguments Describes all parameter functionality and accepted data types
pickled_byte_data: bytes First and only required positional argument. Accepts bytes Use this parameter to pass in and load your pickled bytes data
This uses the native pickle library shipped with the python standard library for its underlying functionality. For more information on the pickle library and official security concerns with pickling, visit: # maci.pickledumpbytes dump data to pickled bytes ### dumping a byte string Dump data to pickled object byte string. **Security awareness**, only unpickle data you trust and review considerations for unpickling data. See more information at [pickle section](/docs/pickle) {% hint style="info" %} maci.pickledumpbytes -> bytes {% endhint %} *Basic Example of dumping data to pickled byte string using default positional parameter* ```python pickled_data = maci.pickledumpbytes(data) ``` In this example, we simply dump data using the pickledumpbytes function and pass any data as an argument to the function to dump it to pickled object data, and assign the returned data to a variable. #### combining pickle with maci to store data to file To store pickled data to a file, it is more encouraged to store it as a byte string value rather than a whole executable pickle file. The byte string itself is not executable yet as it is stored as a value that can be safely tested (using your own means) before loading it. This approach enables the ability to still store your pickle data to a file as an alternative, and control what byte data is coming in instead of just loading/executing a whole pickle file. *Example storing pickled data to a file as a value using maci, and loading it back* ```python # dumping data maci_data = maci.build() maci_data.pickled_data = maci.pickledumpbytes(my_data) maci.dump('my.data', maci_data) # loading data loaded_data = maci.load('my.data') my_data = maci.pickleloadbytes(maci_data.pickled_data) ``` In the example part for dumping, we simply create an empty [maci object](/docs/maci/object) using [maci.build](/docs/maci/functions/maci.build) and use the pickledumpbytes function on our data to assign it to a new attribute name created on our maci object, then dump the maci data using [maci.dump](/docs/maci/functions/maci.dump) to a file called 'my.data'. In the example part for loading the data back, we simply load in the file called 'my.data' using [maci.load](/docs/maci/functions/maci.load) and assign the newly imported maci object to a variable, then using the partner function [maci.pickleloadbytes](/docs/pickle/functions/maci.pickleloadbytes), we unpickle the attribute name on the maci object with the assigned pickled byte string data back to a variable. Right before unpickling the data, that could be a point to check the integrity of the byte string value before processing it. ### partner functions Functions that are related for pickledumpbytes [maci.pickleloadbytes](/docs/pickle/functions/maci.pickleloadbytes) -> Load data from pickled bytes ### parameters & arguments Describes all parameter functionality and accepted data types
data: Any First and only required positional argument. Accepts Any Use this parameter to pass any data to dump to pickled byte string
This uses the native pickle library shipped with the python standard library for its underlying functionality. For more information on the pickle library and official security concerns with pickling, visit: # tools extra tooling for convenience Tools help provide extra convenience for varying requirements, whether it's formatting data or easily getting a hash of files or data, the tooling provided, and more to be added, simplify common needs. [hash functions](/docs/tools/hash-functions) [format functions](/docs/tools/format-functions) # hash functions api functions for hash tools [maci.createfilehash](/docs/tools/hash-functions/maci.createfilehash) [maci.comparefilehash](/docs/tools/hash-functions/maci.comparefilehash) [maci.createhash](/docs/tools/hash-functions/maci.createhash) # maci.createhash create hash of data Creates a hash of the provided data, and returns a string of the hash. {% hint style="info" %} maci.createhash -> str {% endhint %} *Basic Example of hashing data using the default positional parameter* ```python hashed_data = maci.createhash(data) ``` In this example, we simply input the data desired to hash using the createhash function and pass the data as an argument to the function, and assign the returned hashed data to a variable. This function accepts simple or specific data type structures. Strings or bytes for example are some of the simple ones, but see [data\_to\_hash](https://docs.macilib.org/docs/tools/hash-functions/maci.createhash#data_to_hash-str-or-bytes-or-int-or-list-int-or-tuple-int-or-set-int-or-range-or-bool) parameter below to see other options. ### parameters & arguments Describes all parameter functionality and accepted data types
data_to_hash: str | bytes | int | list[int] | tuple[int] | set[int] | range | bool First and only required positional argument. Accepts strings, bytes, integers, list of integers, tuple of integers, set of integers, range objects, and booleans Use this parameter to input the data to get hashed. Note: the current selection of data allowed to get hashed is related to the built-in [bytes function](https://docs.python.org/3/library/stdtypes.html#bytes).
hash_algorithm: str Optional parameter. Accepts strings. Default = 'sha256' Use this parameter to set the hash algorithm used for the hash. Default is sha256, which is a current common industry standard. All options available: 'sha256', 'sha512', 'sha384', 'sha1', 'md5'
encoding: str Optional parameter. Accepts strings. Default = 'utf-8' Use this parameter to set the desired codec of the data if needed. The default uses a common industry standard, so you don't have to use this, but you can if the data needs to be written with a specific codec.
# maci.createfilehash hash a file and store hash to file Creates a hash of any file, and stores the hash data to a newly created file. Always returns a string of the file hash. Useful to use alongside its partner function as mentioned below. {% hint style="info" %} maci.createfilehash -> str {% endhint %} *Basic Example of hashing a file and storing its hash using default positional parameters* ```python maci.createfilehash(src_file, dst_file) ``` In this example, we simply input the source file to hash and the destination file to store the hash data using the createfilehash function and pass the file locations as arguments to the function, and the hashed data is then stored to the destination file. This tool is **encouraged to be used alongside its partner function** [comparefilehash](/docs/tools/hash-functions/maci.comparefilehash), which will automatically handle comparing the hash data stored against the source file hashed and return a Trur/False if they match. #### disable creating destination file createfilehash always returns the hash of the source file to a string if needing to store it in code whether you create a destination file or not. However, you may also disable the need for a destination file to store the hash by setting the file\_to\_store\_hash parameter to None. *Example disabling creating a destination file and just collecting the hash* ```python data = maci.createfilehash(src_file, None) ``` ### partner functions Functions that are related for createfilehash [maci.comparefilehash](/docs/tools/hash-functions/maci.comparefilehash) -> Compares previously created file with stored hash with the source file hash ### parameters & arguments Describes all parameter functionality and accepted data types
file_to_hash: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your source filepath to get the hash.
file_to_store_hash: str | Path | None Second required positional argument. Accepts strings, [Path objects](https://docs.python.org/3/library/pathlib.html), and None Use this parameter to point to your destination filepath to store hash of the source file. Set to None if you do not want a file created to store hash.
hash_algorithm: str Optional parameter. Accepts strings. Default = 'sha256' Use this parameter to set the hash algorithm used for the hash. Default is sha256, which is a current common industry standard. All options available: 'sha256', 'sha512', 'sha384', 'sha1', 'md5'
encoding: str | None (Removed in v.1.1.1) Optional parameter. Accepts strings or None. Default = None Use this parameter to set the source file hashed data and destination file with the desired codec 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.
# maci.comparefilehash compare hash of file to stored hash Compares a hash of the source file against the previously created file with the stored hash data, from using the [createfilehash](/docs/tools/hash-functions/maci.createfilehash) partner function, and returns a boolean if the hashes match. {% hint style="info" %} maci.comparefilehash -> bool {% endhint %} *Basic Example of comparing hash of a file against the stored hash using default positional parameters* ```python result = maci.comparefilehash(src_file, dst_file) ``` In this example, we simply input the source file to hash and the destination file with the stored hash data using the comparefilehash function and pass the file locations as arguments to the function, the hashed data is then compared against the source file, and assign the returned result to a variable. To create the initial stored hashed data, see the partner function [createfilehash](/docs/tools/hash-functions/maci.createfilehash). This tool is designed to dependently work with its partner function. ### partner functions Functions that are related for comparefilehash [maci.createfilehash](/docs/tools/hash-functions/maci.createfilehash) -> Creates hash of a file, and stores the hash data to a newly created file ### parameters & arguments Describes all parameter functionality and accepted data types
file_to_hash: str | Path First required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your source filepath to get the hash.
stored_hash_file: str | Path Second required positional argument. Accepts strings and [Path objects](https://docs.python.org/3/library/pathlib.html) Use this parameter to point to your destination filepath of the file with the stored hash data.
hash_algorithm: str Optional parameter. Accepts strings. Default = 'sha256' Use this parameter to set the hash algorithm used for the hash. Default is sha256, which is a current common industry standard. All options available: 'sha256', 'sha512', 'sha384', 'sha1', 'md5'
encoding: str | None (Removed in v.1.1.1) Optional parameter. Accepts strings or None. Default = None Use this parameter to set the source file hashed data and the destination file containing the hashed data with the desired codec 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.
# format functions api functions for format tools [maci.cleanformat](/docs/tools/format-functions/maci.cleanformat) # maci.cleanformat formats data to a cleaner structured output Formats and dumps dictionaries, lists, tuples, and sets to a string formatted in a clean human-readable structure. Useful for nested data to be represented over multiple lines with indentation. {% hint style="info" %} maci.cleanformat -> str {% endhint %} *Basic Example of formatting data to a string using default positional parameter* ```python data = maci.cleanformat(nested_data) ``` In this example, we simply format nested data to a string using the cleanformat function and pass the data as an argument to the function, and assign the returned string data to a variable.
*Example output using cleanformat with nested dictionary data* ```python { 'k1': 'value1', 'k2': { 'sub1': 'sub_value1', 'sub2': { 'sub_sub1': 'sub_sub_value1', }, 'sub3': 'sub_value3', }, 'k3': 'value3', } ``` *Example output using cleanformat with nested list data* ```python [ 1, [ 1, 2, [ 1, 2, 3, ], 3, ], 2, 3, ] ``` ### parameters & arguments Describes all parameter functionality and accepted data types
data: dict | list | tuple | set First and only required positional argument. Accepts dictionaries, lists, tuples, and sets Use this parameter to pass in the data you want to format
indent_level: int Optional parameter. Accepts integers. Default = 1 Use this parameter to change the indentation level for structured data (lists, dicts, tuples, sets) in the output. Indentation will be applied to nested data. 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%.
# Changelog logged changes [v1.1.1](/updates/changelog/v1.1.1) - Official Release - 2026-03-11 [v1.1.0](/updates/changelog/v1.1.0) - Official Release - 2025-04-20 [v1.0.0](/updates/changelog/v1.0.0) - Official Production Release - 2023-12-02 # v1.1.1 official release v1.1.1 - Official Release - 2026-03-11 #### Added * Added support for configuring XML dump indentation and XML declaration options in `xmldump` * Added object hashability support * Added object len support #### Fixed * Fixed `ValueError` not being correctly redirected in `xmldump` functions * Fixed incorrect exception handling when attribute names are invalid during dump operations * Fixed parsing issue when indent level was set to `0` for nested structures * Fixed missing method names from the rename protection list * Fixed internal name reassignment ignore switch behavior * Fixed Unicode decode error when hashing binary files * Fixed attribute name collisions in `loaddict` caused by internal maci names * Fixed extra internal data being returned by `loaddict` and `loadstrdict` * Fixed incorrect file hashing implementation causing mismatches on Windows OS systems * Fixed equality operator issue if attribute comparison was out of order #### Performance * Performance improvements on several object operations: * `bool` operator evaluation improved by a reduction of \~99% * `==` operator comparison improved by a reduction of \~92% * `repr` improved by a reduction of \~35% * `dir` improved by a reduction of \~71% * `get_attrs` method improved by a reduction of \~83% * Added internal caching improving overall average method performance by a reduction of \~86%: * `get_all_maps` * `get_parent_maps` * `get_child_maps` #### Removed * Removed "encoding" param from tooling functions due to above fixed issue on hashing: * `createfilehash` * `comparefilehash` #### Updated * Updated dependency version constraints and deployment requirements to address vulnerabilities and dependency resolution across supported Python versions * Updated GitHub Actions CI configuration and workflow debugging improvements * Added new pipline testing environment to verify publishing pre-release: # v1.1.0 official release - production v1.1.0 - Official Production Release - 2025-04-20 * Removed support for python 3.7 due to eol deprecation and security vulns on setuptools dependency * Adopted support for python 3.13 by updating test environment validation # v1.0.0 official release - production v1.0.0 - Official Production Release - 2023-12-02 I am thrilled to announce the official release of maci v1.0.0. This milestone represents a stable, feature-complete version suitable for production use. Extending my heartfelt thanks to all who have provided feedback and contributions. Your support has been invaluable! Looking ahead, this project is open source, and the plan is to focus on improving performance and fixing or adding features as they arise. I welcome feedback and contributions. For more information on contributing see [maci code](https://docs.macilib.org/#code) Thank you for supporting maci. I'm excited to see what you build with it!