mahautils.utils.Dictionary#

class mahautils.utils.Dictionary(contents: dict | None = None, required_key_type: ~typing.Type[~mahautils.utils.dictionary.K] | ~typing.List[~typing.Type[~mahautils.utils.dictionary.K]] | ~typing.Tuple[~typing.Type[~mahautils.utils.dictionary.K], ...] | None = None, required_value_type: ~typing.Type[~mahautils.utils.dictionary.V] | ~typing.List[~typing.Type[~mahautils.utils.dictionary.V]] | ~typing.Tuple[~typing.Type[~mahautils.utils.dictionary.V], ...] | None = None, multiline_print: bool = False, str_indent: int = 0, str_pad_left: int = 1, str_pad_right: int = 2, custom_except_class: ~typing.Type[Exception] = <class 'KeyError'>, custom_except_msg: str = '%s')#

Bases: OrderedDict[K, V]

Customized Python dictionary

This class is a modified version of Python’s built-in OrderedDict dictionary. Most typical dictionary methods function as they do in a dict. However, additional functionality has been added, such as being able to insert items at any position in the dictionary and customizations for printing content in the dictionary.

Attributes

custom_except_class

The exception to raise if a key does not exist in the dictionary

custom_except_msg

A custom error message if a key was not found in the dictionary

multiline_print

Whether to print each entry of the dictionary on its own line when converting to a printable string representation

str_indent

The number of spaces of indentation at the beginning of each line when converting a Dictionary object to a printable string representation.

str_pad_left

The number of spaces between the printed key and the separator when converting a Dictionary object to a printable string representation.

str_pad_right

The number of spaces between the separator and printed value when converting a Dictionary object to a printable string representation.

Methods

__init__([contents, required_key_type, ...])

Defines a Dictionary instance

delete_index(index)

Removes an item from the dictionary based on its index

index(key)

Returns the index of a key in the dictionary

insert(index, key, value)

Adds a new item to the dictionary at a specified position

insert_after(existing_key, key, value)

Adds a new item to the dictionary at after another existing item in the dictionary

insert_before(existing_key, key, value)

Adds a new item to the dictionary at before another existing item in the dictionary

Inherited Methods

clear()

copy()

fromkeys([value])

Create a new ordered dictionary with keys from iterable and values set to value.

get(key[, default])

Return the value for key if key is in the dictionary, else default.

items()

keys()

move_to_end(key[, last])

Move an existing element to the end (or beginning if last is false).

pop(key[,default])

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem([last])

Remove and return a (key, value) pair from the dictionary.

setdefault(key[, default])

Insert key with a value of default if key is not in the dictionary.

update([E, ]**F)

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values()

__init__(contents: dict | None = None, required_key_type: ~typing.Type[~mahautils.utils.dictionary.K] | ~typing.List[~typing.Type[~mahautils.utils.dictionary.K]] | ~typing.Tuple[~typing.Type[~mahautils.utils.dictionary.K], ...] | None = None, required_value_type: ~typing.Type[~mahautils.utils.dictionary.V] | ~typing.List[~typing.Type[~mahautils.utils.dictionary.V]] | ~typing.Tuple[~typing.Type[~mahautils.utils.dictionary.V], ...] | None = None, multiline_print: bool = False, str_indent: int = 0, str_pad_left: int = 1, str_pad_right: int = 2, custom_except_class: ~typing.Type[Exception] = <class 'KeyError'>, custom_except_msg: str = '%s') → None#

Defines a Dictionary instance

Defines a new Dictionary object, providing options to populate the dictionary’s contents and define parameters controlling how the dictionary is formatted when converting to a string.

Parameters:

  • contents (dict, optional) – Python dict which, if provided, will immediately populate the data in the dictionary upon creation (default is None)

  • required_key_type (type or list or tuple, optional) – One or more required type(s) of which all keys in the dictionary must be a subclass. Set to None to allow any type (default is None)

  • required_value_type (type or list or tuple, optional) – One or more required type(s) of which all values in the dictionary must be a subclass. Set to None to allow any type (default is None)

  • multiline_print (bool, optional) – Whether to print each entry of the dictionary on its own line when converting to a printable string representation (default is False)

  • str_indent (int, optional) – Sets the dictionary’s str_indent attribute (default is 0). Only applicable if multiline_print is True

  • str_pad_left (int, optional) – Sets the dictionary’s str_pad_left attribute (default is 0). Only applicable if multiline_print is True

  • str_pad_right (int, optional) – Sets the dictionary’s str_pad_right attribute (default is 0). Only applicable if multiline_print is True

  • custom_except_class (class, optional) – An Exception subclass to raise if a given key is not found in the dictionary (default is KeyError)

  • custom_except_msg (str, optional) – Only applicable if custom_except_class is not None. Specifies an error message to throw if a key is not found in the dictionary. Must contain a single %s occurrence, which will be replaced by the name of the key which was not found (default is '%s')

property custom_except_class: Type[Exception]#

The exception to raise if a key does not exist in the dictionary

property custom_except_msg: str#

A custom error message if a key was not found in the dictionary

The message must contain a single %s occurrence, which will be replaced by the name of the key which was not found.

clear() → None.  Remove all items from od.#
copy() → a shallow copy of od#
fromkeys(value=None)#

Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /)#

Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items#
keys() → a set-like object providing a view on D's keys#
move_to_end(key, last=True)#

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

property multiline_print: bool#

Whether to print each entry of the dictionary on its own line when converting to a printable string representation

pop(key[, default]) → v, remove specified key and return the corresponding value.#

If the key is not found, return the default if given; otherwise, raise a KeyError.

popitem(last=True)#

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

setdefault(key, default=None)#

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

update([E, ]**F) → None.  Update D from dict/iterable E and F.#

If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

values() → an object providing a view on D's values#
property str_indent: int#

The number of spaces of indentation at the beginning of each line when converting a Dictionary object to a printable string representation. Only applicable if multiline_print is True

property str_pad_left: int#

The number of spaces between the printed key and the separator when converting a Dictionary object to a printable string representation. Only applicable if multiline_print is True

property str_pad_right: int#

The number of spaces between the separator and printed value when converting a Dictionary object to a printable string representation. Only applicable if multiline_print is True

delete_index(index: int) → None#

Removes an item from the dictionary based on its index

Items can easily be removed from the dictionary by key (example: to remove an item with key 'myKey' from a dictionary, simply call del dictionary['myKey']). This method extends this functionality and allows items to be removed based on their position in the dictionary.

Parameters:

index (int) – The index of the item to remove from the dictionary

index(key: K) → int#

Returns the index of a key in the dictionary

Parameters:

key (Any) – A key in the dictionary

Returns:

The location (beginning from 0) of key in the dictionary

Return type:

int

insert(index: int, key: K, value: V) → None#

Adds a new item to the dictionary at a specified position

Parameters:

  • index (int) – The position in the dictionary at which to insert the new key

  • key (Any) – The key for the new item to insert int the dictionary

  • value (Any) – The value for the new item to insert in the dictionary

insert_after(existing_key: K, key: K, value: V) → None#

Adds a new item to the dictionary at after another existing item in the dictionary

Parameters:

  • existing_key (Any) – The existing key in the dictionary after which key should be inserted

  • key (Any) – The key for the new item to insert int the dictionary

  • value (Any) – The value for the new item to insert in the dictionary

insert_before(existing_key: K, key: K, value: V) → None#

Adds a new item to the dictionary at before another existing item in the dictionary

Parameters:

  • existing_key (Any) – The existing key in the dictionary before which key should be inserted

  • key (Any) – The key for the new item to insert int the dictionary

  • value (Any) – The value for the new item to insert in the dictionary