modifiable-items-dict

A simple, fast, typed, and tested implementation for a python3.6+ Modifiable Items dictionary. ModifiableItemsDict extends dict with the ability to modify keys and values on creation, insertion, and retrieval. This class extends and maintains the original functionality of the builtin dict.

In addition to ModifiableItemsDict, this implementation also includes ModifiableItemsAttrDict, a class that inherits from ModifiableItemsDict and adds attribute-style access to dictionary items. This means you can access dictionary items as if they were attributes of the object, providing an alternative, often more readable way to access dictionary items. Like ModifiableItemsDict, ModifiableItemsAttrDict also allows modification of keys and values on creation, insertion, and retrieval, ensuring consistency and flexibility in handling dictionary items.

Key Features:

• Easy: Flexible and easy to add Key and/or Value modifiers to the ModifiableItemsDict and ModifiableItemsAttrDict.
• Attribute Access: ModifiableItemsAttrDict allows attribute-style access to dictionary items, providing an alternative, often more readable way to access dictionary items.
• Great Developer Experience: Being fully typed makes it great for editor support.
• Fully Tested: Our test suite fully tests the functionality to ensure that ModifiableItemsDict and ModifiableItemsAttrDict run as expected.
• There is More!!!:
  • CaselessDict: CaselessDict extends ModifiableItemsDict and ModifiableItemsAttrDict which is a CaselessDict and CaselessAttrDict that ignores the case of the keys.

Installation

pip install modifiable-items-dictionary

ModifiableItemsDict and ModifiableItemsAttrDict

The ModifiableItemsDict and ModifiableItemsAttrDict classes are part of the modifiable_items_dictionary module. They provide advanced dictionary functionalities with additional features for modifying keys and values.

ModifiableItemsDict

The ModifiableItemsDict class is a dictionary class that allows modification of keys and values during creation, insertion, and retrieval. It provides the following features:

• Key Modifiers: This class allows you to specify functions that modify keys on creation, insertion, and retrieval. This can be useful for ensuring that all keys adhere to a certain format or standard.
• Value Modifiers: Similar to key modifiers, you can also specify functions that modify values. This can be useful for transforming or sanitizing data as it's added to the dictionary.
• Thread Safety: This class is designed to be thread-safe, making it suitable for use in multi-threaded applications.
• Fully Tested: The functionality of this class is fully tested to ensure reliable operation.

Example

from modifiable_items_dictionary import ModifiableItemsDict


def _add_1(_value):
    if isinstance(_value, int):
        _value += 1
    return _value


def _case_fold_string(_value):
    if isinstance(_value, str):
        _value = _value.casefold()
    return _value


ModifiableItemsDict._key_modifiers = [str.casefold]
ModifiableItemsDict._value_modifiers = (
    _add_1, _case_fold_string)
# Or
# ModifiableItemsDict._key_modifiers = staticmethod(str.casefold)
# ModifiableItemsDict._value_modifiers = [_case_fold_string, _add_1]

modifiable_items_dictionary = ModifiableItemsDict(
    {"lower": 1, "UPPER": 2},
    CamelCase=3,
    snake_case="FoUR"
)

print(
    modifiable_items_dictionary
)  # {'lower': 2, 'upper': 3, 'camelcase': 4, 'snake_case': 'four'}

del modifiable_items_dictionary["LOWER"]
del modifiable_items_dictionary["UPPER"]
modifiable_items_dictionary.pop("SNAKE_CAse")

modifiable_items_dictionary["HeLLO"] = 5

print(modifiable_items_dictionary)  # {'camelcase': 4, 'hello': 6}

ModifiableItemsAttrDict

The ModifiableItemsAttrDict class is an extension of the ModifiableItemsDict class, inheriting all its features while adding attribute-style access to dictionary items. This class maintains the same key and value modifiers, ensuring consistency and flexibility in handling dictionary items.

Like ModifiableItemsDict, ModifiableItemsAttrDict is designed with thread safety in mind, making it suitable for use in multi-threaded applications. It is also fully tested to ensure reliable operation.

In addition to these features, ModifiableItemsAttrDict offers:

• Attribute-style Access: This feature allows you to access dictionary items as if they were attributes of the object. For example, you can use dict.key instead of dict['key']. This provides an alternative, often more readable way to access dictionary items, while still retaining the traditional dictionary access methods.

This combination of features makes ModifiableItemsAttrDict a powerful tool for managing dictionaries in a way that is both flexible and intuitive, while maintaining the robustness and reliability of the ModifiableItemsDict class.

Example

import modifiable_items_dictionary


def _add_1(_value):
    if isinstance(_value, int):
        _value += 1
    return _value


def _case_fold_string(_value):
    if isinstance(_value, str):
        _value = _value.casefold()
    return _value


modifiable_items_dictionary.ModifiableItemsAttrDict._key_modifiers = [
    str.casefold
]
modifiable_items_dictionary.ModifiableItemsAttrDict._value_modifiers = (
    _add_1,
    _case_fold_string,
)

modifiable_items_attr_dict = (
    modifiable_items_dictionary.ModifiableItemsAttrDict(
        {'lower': 1, 'UPPER': 2}, CamelCase=3, snake_case='FoUR'
    )
)

print(
    modifiable_items_attr_dict
)  # {'lower': 2, 'upper': 3, 'camelcase': 4, 'snake_case': 'four'}

# Key-based access
del modifiable_items_attr_dict['LOWER']
modifiable_items_attr_dict['HeLLO'] = 5

# Attribute-based access
del modifiable_items_attr_dict.UPPER
modifiable_items_attr_dict.HeLLO = 6
print(modifiable_items_attr_dict.hELlo)  # 6
print(modifiable_items_attr_dict)  # {'camelcase': 4, 'hello': 6}

Use Case Example

Let's say that there is a .json file that has Url hosts and their IP address. Our Goal is to load the json data into a dictionary like structure that will have it's items modified during creation, insertion, and retrieval. This example highlights how to inherit from ModifiableItemsDict and had key and value modifiers.

import ipaddress

from modifiable_items_dictionary import ModifiableItemsDict


class HostDict(ModifiableItemsDict):
    _key_modifiers = [str.casefold, str.strip]
    _value_modifiers = [ipaddress.ip_address]
    # Or
    # _value_modifiers = @staticmethod(ipaddress.ip_address)


browsers = HostDict(
    {
        "  GooGle.com    ": "142.250.69.206",
        " duckDUCKGo.cOM   ": "52.250.42.157",
    }
)

print(browsers)
# {'google.com': IPv4Address('142.250.69.206'), 'duckduckgo.com': IPv4Address('52.250.42.157')}

_old_browser = browsers.pop("  gOOgle.com  ")
# or 
# del host_dict["   GooGle.com  "]

browsers["   BrAvE.com   "] = "2600:9000:234c:5a00:6:d0d2:780:93a1"

print(browsers)
# {'duckduckgo.com': IPv4Address('52.250.42.157'), 'brave.com': IPv6Address('2600:9000:234c:5a00:6:d0d2:780:93a1')}

Threading Example

It is easy to add Threading to a ModifiableItemsDict.

NOTE: Since ModifiableItemsDict is not pickable it does not work with Multiprocessing. It only works with Multithreading.

import multiprocessing.pool
import string
import time

from modifiable_items_dictionary import ModifiableItemsDict

pool = multiprocessing.pool.ThreadPool(10)


def _slow_function(x):
    time.sleep(.05)
    return x


class TimeDictWithThreading(ModifiableItemsDict):
    _key_modifiers = (_slow_function,)
    _value_modifiers = (_slow_function,)
    _map_function = pool.imap_unordered
    # or if order matters
    # _map_function = pool.imap


class TimeDict(ModifiableItemsDict):
    _key_modifiers = (_slow_function,)
    _value_modifiers = (_slow_function,)


iterable = {_letter: _index for _index, _letter in
            enumerate(string.ascii_letters)}

# Without Threading
start = time.perf_counter()
TimeDict(iterable)
end = time.perf_counter()
print(f"{end - start:.2f} seconds")  # 5.54 seconds

# With Threading
start = time.perf_counter()
TimeDictWithThreading(iterable)
end = time.perf_counter()
print(f"{end - start:.2f} seconds")  # 0.64 seconds

Reference

This project was inspired by Raymond Hettinger (rhettinger).

• Hettinger, R. (2023). (Advanced) Python For Engineers: Part 3.