data

Data

This class includes methods, used to work with lists, tuples, sets, frozensets and dictionaries.

serialize_bytes()

This method will convert a bytearray() or bytes() object to a JSON-compatible format (dictionary) with explicit keys.
Param: data: bytes | bytearray the data to serialize
Returns: the serialized data as a dictionary:

# bytes("Hello world!", "utf-8")
{"bytes": "Hello world!", "encoding": "utf-8"}

# bytearray("Bye world!", "utf-8")
{"bytearray": "Bye world!", "encoding": "utf-8"}

deserialize_bytes()

This method will convert a JSON-compatible format (dictionary) with explicit keys back to a bytearray() or bytes() object.
Param: obj: dict[str, str] the data to deserialize
Returns: the deserialized data
Raises: ValueError if the data couldn't be deserialized

chars_count()

This method will return the sum of the amount of all the characters (including the keys if it's a dictionary) in data.
Param: data: DataStructure the data to count the characters in
Returns: the sum of the amount of all the characters

strip()

This method will remove all leading and trailing whitespaces from data items.
Param: data: DataStructure the data to strip
Returns: the stripped data

remove_empty_items()

This method will remove empty items from data.
Params:

• data: DataStructure the data to remove empty items from
• spaces_are_empty: bool = False whether to count items with only spaces as empty

Returns: the data with the empty items removed

remove_duplicates()

This method will remove duplicate items from data.
Param: data: DataStructure the data to remove duplicates from
Returns: the data with the duplicates removed

remove_comments()

This method will remove custom defined comments from the data's keys, items and values.
Params:

• data: DataStructure the data to remove comments from
• comment_start: str = ">>" the string that marks the start of a comment
• comment_end: str = "<<" the string that marks the end of a comment
• comment_sep: str = "" a string with which a comment will be replaced, if it is in the middle of a string

Returns: the data with the comments removed

Data Comments:

Comments can be placed in the values, but also keys of the data. With comments, you can leave a quick note, but you can also easily comment big parts of the data:

data = {
    "key1": [
        ">> COMMENT IN THE BEGINNING OF THE STRING <<  value1",
        "value2  >> COMMENT IN THE END OF THE STRING",
        "val>> COMMENT IN THE MIDDLE OF THE STRING <<ue3",
        ">> FULL VALUE IS A COMMENT  value4"
    ],
    ">> FULL KEY + ALL ITS VALUES ARE A COMMENT  key2": [
        "value",
        "value",
        "value"
    ],
    "key3": ">> ALL THE KEYS VALUES ARE COMMENTS  value"
}

processed_data = Data.remove_comments(
    data,
    comment_start=">>",
    comment_end="<<",
    comment_sep="__"
)

For this example, processed_data would be:

{
    "key1": [
        "value1",
        "value2",
        "val__ue3"
    ],
    "key3": None
}

This is because:
For key1, all the comments will just be removed, except at value3 and value4:
 value3 The comment is removed, and the parts left and right are joined through comment_sep.
 value4 The whole value is removed, since the whole value was a comment.
For key2, the key, including its whole values will be removed.
For key3, since all its values are just comments, the key will still exist, but with a value of None.

is_equal()

This method will check if two data structures are equal (comments not ignored).
Params:

• data1: DataStructure the first data structure to compare
• data2: DataStructure the second data structure to compare
• ignore_paths: str | list[str] = "" parts of the structure to ignore while comparing (see Data.get_path_id())
• path_sep: str = "->" the separator to separate the parts of the path (see Data.get_path_id())
• comment_start: str = ">>" the string that marks the start of a comment (see Data.remove_comments())
• comment_end: str = "<<" the string that marks the end of a comment (see Data.remove_comments())

Returns: True if the data structures are equal, False otherwise

get_path_id()

This method generates a unique ID based on the path to a specific value within a nested data structure.
Params:

• data: DataStructure the data structure to get the path ID from
• value_paths: str | list[str] the path/s to the value/s to be updated
• path_sep: str = "->" the separator to separate the parts of the path
• comment_start: str = ">>" the string that marks the start of a comment (see Data.remove_comments())
• comment_end: str = "<<" the string that marks the end of a comment (see Data.remove_comments())
• ignore_not_found: bool = False if True, will not raise an exception if a path from value_paths is not found and instead return None

Returns: the generated path ID/s

Value Paths:

To more easily explain value_paths, we'll take this data structure for an example:

{
    "healthy": {
        "fruit": ["apples", "bananas", "oranges"],
        "vegetables": ["carrots", "broccoli", "celery"]
    }
}

... if we would want to target the list item "apples", our value-path would be healthy->fruit->apples. This is because the item "apples" is under the key "fruit" with the parent dictionary "healthy".
If we don't know that the list item is "apples" we can also use the list index of that item, so healthy->fruit->0, since the index of "apples" in the list under healthy->fruit is 0.

Path Separator:

The path_sep parameter is the separator between the keys/indexes in the value-path. In the example above, -> is used as the separator (which is also the default separator).

get_value_by_path_id()

This method tries to retrieve a value, using the provided path ID (generated with Data.get_path_id()), within a nested data structure.
Params:

• data: DataStructure the data structure to get the value from
• path_id: str the path ID to get the value from
• get_key: bool = False whether to return the value's key instead of the value itself

Returns: the value (or key) from the path ID location, as long as the structure of data hasn't changed since creating the path ID to that value.

set_value_by_path_id()

This method updates a value (or a list of values), using the provided path ID (generated with Data.get_path_id()), within a nested data structure.
Params:

• data: DataStructure the data structure to update values in
• update_values: dict[str, Any] the path ID/s along with the new value/s to be inserted

Returns: the updated data structure

Update Values:

The update_values parameter is a dictionary with the path IDs as keys and the new value/s to be inserted at the location specified by that ID:

{
    "1>012": "new value 1",  # REPLACE OLD VALUE WITH A NEW STRING VALUE
    "1>203": [123, "abc"],   # REPLACE OLD VALUE WITH A LIST
    ...
}

to_str()

This method converts a nested data structure into a nicely formatted string.
Params:

• data: DataStructure the data structure to convert
• indent: int = 4 the number of spaces used to indent the data structure
• compactness: int = 1 the level of compactness of the data structure
• max_width: int = 127 the maximum amount of characters a line in the formatted data structure can have
• sep: str = ", " the separator to use inside the formatted data structure
• as_json: bool = False whether to format the data structure in JSON format

Returns: the formatted data structure as a string

Compactness:

The compactness parameter can be set to three different levels:
 0 expands everything possible
 1 only expands if there are other data structures inside the current item/value or if a line's characters amount is more than max_width
 2 keeps everything collapsed (all on one line)

print()

This method prints a nested data structure in a nicely formatted way, including optional syntax highlighting.
Params:

• data: DataStructure the data structure to print
• indent: int = 4 the number of spaces used to indent the data structure
• compactness: int = 1 the level of compactness of the data structure (see Data.to_str())
• max_width: int = 127 the maximum amount of characters a line in the formatted data structure can have
• sep: str = ", " the separator to use inside the formatted data structure
• end: str = "\n" the string to use at the end of the formatted data structure
• as_json: bool = False whether to print the data structure in JSON format
• syntax_highlighting: dict[str, str] | bool = {} the syntax highlighting colors to apply to the data structure

Returns: no return value

Syntax Highlighting:

The syntax_highlighting parameter can be set to a dictionary with a key for each part of the data structure. The key's values are the colors and styles (see the format_codes documentation) to apply to that part of the data structure:
 str the color of strings in the data structure (default is COLOR.BLUE)
 number the color of numbers in the data structure (default is COLOR.MAGENTA)
 literal the color of literals in the data structure (default is COLOR.CYAN)
 type the color of displayed types (e.g. bytes(...)) in the data structure (default is "i|" + COLOR.LIGHT_BLUE)
 punctuation the color of punctuation in the data structure (default is COLOR.DARK_GRAY)

The keys put in the dictionary from the syntax_highlighting parameter will overwrite the default styles.

Example:
To only change the color of strings from the default COLOR.BLUE to for example u|#00FF00 (underlined & green), we just add that one dictionary key with the style we want to the param syntax_highlighting:

Data.print(
    data,
    syntax_highlighting={
        "str": "u|#00FF00"
    },
)

The syntax highlighting can be completely disabled by setting the syntax_highlighting parameter to False.