from toolbox.collections import item
class Item[source]#
An interface for type-agnostic operations between bytes, str, int,

bool, and None.

Internally, the passed item object is stored as its bytes representation. Any operation or modification to the new Item instance is done to the internal bytes object. The true usefulness of this container is for type-agnostic operations such as equality checks.


item (Union[bytes, str, int, bool, None, Item]) – Input to be stored.


from toolbox.collections.item import Item

item = Item("hello world")
if b" world" in item:
    item -= " world"

print(item.raw, item.string)
# >>> b'hello' hello

# >>> Item(bytes=b'hello', str='hello', int=None, bool=True, original_type=str)
property raw#

Bytes representation of the passed item.

Return type


property string#

String representation of the passed item.

Return type


property integer#

Integer representation of the passed item.

If passed item is not a sub class of type int or str.isdigit() this property returns None.

Return type


property boolean#

Boolean representation of the passed item.

Return type


property original#

Original representation of the passed item.

Return type

Union[bytes, str, int, bool, None, Item]

The following special operators are included:


Returns the string representation of the object.


from toolbox.collections.item import Item

item = Item(100)
print(+item, type(+item)) # >>> 100 <class 'str'>

Returns the integer representation of the object.


from toolbox.collections.item import Item

item = Item(100)
print(-item, type(-item)) # >>> 100 <class 'int'>

The following operations are also included:

b"hello" in Item("hello world") # >>> True
Item(100) == Item(b'100') == Item('100') # >>> True
Item("hello") + Item("world") == Item("helloworld") # >>> True
i = Item("hello")
i += Item("world")
i == Item("helloworld") # >>> True

Uses bytes.replace to remove item.

Item("helloworld") - Item("world") == Item("hello") # >>> True
i = Item("helloworld")
i -= Item("world")
i == Item("hello") # >>> True

Returns string version of the item for iteration.

for i in Item("hello world"):

# >>> h
# >>> e
# >>> ...
hash(Item(100)) == hash(b"100") # >>> True
len(Item("hello world")) == 11 # >>> True
False == bool(Item(0)) == bool(Item("")) == bool(Item(b"")) == bool(Item(False)) == bool(Item(None)) # >>> True
True == bool(Item(1)) == bool(Item("hello")) == bool(Item(b"hello")) == bool(Item(True)) # >>> True

Equivalent to the string property.

repr(Item(100)) # >>> Item(bytes=b'100', str='100', int=100, bool=True, original_type=int)
repr(Item(True)) # >>> Item(bytes=b'1', str='1', int=1, bool=True, original_type=bool)
repr(Item("hello")) # >>> Item(bytes=b'hello', str='hello', int=None, bool=True, original_type=str)

The following functions are included:

replace(old, new, count)[source]#

bytes.replace() functionality on item.

See Python docs for more info.

Return type



from toolbox.collections import mapping

Since the mappings below are children class to dict, they may all be initialized in three different ways:

from toolbox.collections.mapping import ObjectDict

ObjectDict(hello="world", ola="mundo")
ObjectDict({"hello":"world", "ola": "mundo"})
ObjectDict({"hello":"world"}, ola="mundo")

Note that *Dict types below can be combined together (as mixins) to create unique dictionary types.

from toolbox.collections.mapping import ObjectDict, UnderscoreAccessDict, FrozenDict

class Dict(ObjectDict, UnderscoreAccessDict, FrozenDict):
    """ Frozen dictionary that allows object access with underscore access. """

d = Dict({"hello world": "ola mundo", "100": "one hundred"})
print(d)                # >>> <Dict {'hello world': 'ola mundo', '100': 'one hundred'}>
print(d.hello_world)    # >>> ola mundo
print(d._100)           # >>> one hundred
class BaseDict[source]#

Dictionary with pretty __repr__() output.

Base class that all other dictionaries in this file inherit from. __repr__() is replaced with <{class_name} {dictionary data}> output style for implicit inferences.


from toolbox.collections.mapping import BaseDict

class NewDict(BaseDict):
    '''New dictionary example.'''

d = NewDict({"hello": "world"})
print(d) # >>> <NewDict {'hello': 'world'}>
class BidirectionalDict[source]#

Dictionary with two-way capabilities.


from toolbox.collections.mapping import BidirectionalDict

d = BidirectionalDict({"hello": "world"})
print(d) # >>> <BidirectionalDict {'hello': 'world', 'world': 'hello'}>
class ObjectDict(BaseDict)[source]#

Dictionary that can be accessed as though it was an object.


from toolbox.collections.mapping import ObjectDict

d = ObjectDict({"hello": "world"})
print(d) # >>> <ObjectDict {'hello': 'world'}>

print(d.hello) # >>> 'world'
class OverloadedDict(BaseDict)[source]#

Dictionary that can be added or subtracted.


from toolbox.collections.mapping import OverloadedDict

d1 = OverloadedDict({"hello": "world"})
d2 = {"ola": "mundo"}

d1 += d2
print(d1) # >>> <OverloadedDict {'hello': 'world', 'ola': 'mundo'}>

d1 -= d2
print(d1) # >>> <OverloadedDict {'hello': 'world'}>
class UnderscoreAccessDict(BaseDict)[source]#

Dictionary that doesn’t distinct keys with empty spaces and underscores.


from toolbox.collections.mapping import UnderscoreAccessDict

d = UnderscoreAccessDict({"hello world": "ola mundo"})
print(d) # >>> <UnderscoreAccessDict {'hello world': 'ola mundo'}>

print(d['hello_world']) # >>> 'ola mundo'
class FrozenDict(BaseDict)[source]#

Dictionary that is frozen.

from toolbox.collections.mapping import FrozenDict

d = FrozenDict({"hello": "world"})
print(d) # >>> <FrozenDict {'hello': 'world'}>

d['ola'] = 'mundo'
# >>> KeyError: 'Cannot set key and value because this is a frozen dictionary.'
class ItemDict[source]#

Dictionary composed of toolbox.collections.item.Item key and values.


from toolbox.collections.mapping import ItemDict

d = ItemDict({"100": "one hundred"})
# >>> <ItemDict {Item(bytes=b'100', str='100', int=100, bool=True, original_type=str): Item(bytes=b'one hundred', str='one hundred', int=None, bool=True, original_type=str)}>

print(d["100"] == d[100] == d[b"100"]) # >>> True


from toolbox.collections import namedtuple

Converts dictionary to a nested namedtuple recursively.


dictionary (dict) – Dictionary to convert into a nested namedtuple.


from toolbox.collections.namedtuple import nestednamedtuple

nt = nestednamedtuple({"hello": {"ola": "mundo"}})
print(nt) # >>> namedtupled(hello=namedtupled(ola='mundo'))
Return type


class fdict[source]#

Forced dictionary. Prevents dictionary from becoming a nested namedtuple.


from toolbox.collections.namedtuple import nestednamedtuple, fdict

d = {"hello": "world"}
nt = nestednamedtuple({"forced": fdict(d), "notforced": d})
print(nt.notforced)    # >>> namedtupled(hello='world')
print(nt.forced)       # >>> {'hello': 'world'}