collections

item

from toolbox.collections import item

class Item

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.

Parameters:

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

Example

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

print(repr(item))
# >>> Item(bytes=b'hello', str='hello', int=None, bool=True, original_type=str)

property raw

Bytes representation of the passed item.

Return type:

bytes

property string

String representation of the passed item.

Return type:

str

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:

Optional[int]

property boolean

Boolean representation of the passed item.

Return type:

bool

property original

Original representation of the passed item.

Return type:

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

The following special operators are included:

__pos__()

Returns the string representation of the object.

Example

from toolbox.collections.item import Item

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

__neg__()

Returns the integer representation of the object.

Example

from toolbox.collections.item import Item

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

The following operations are also included:

__contains__()

b"hello" in Item("hello world") # >>> True

__eq__()

Item(100) == Item(b'100') == Item('100') # >>> True

__add__()

Item("hello") + Item("world") == Item("helloworld") # >>> True

__iadd__()

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

__sub__()

Uses bytes.replace to remove item.

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

__isub__()

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

__iter__()

Returns string version of the item for iteration.

for i in Item("hello world"):
    print(i)

# >>> h
# >>> e
# >>> ...

__hash__()

hash(Item(100)) == hash(b"100") # >>> True

__len__()

len(Item("hello world")) == 11 # >>> True

__bool__()

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

__str__()

Equivalent to the string property.

__repr__()

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)

bytes.replace() functionality on item.

See Python docs for more info.

Return type:

bytes

---

mapping

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

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.

Example

from toolbox.collections.mapping import BaseDict

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

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

class BidirectionalDict

Dictionary with two-way capabilities.

Example

from toolbox.collections.mapping import BidirectionalDict

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

class ObjectDict(BaseDict)

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

Example

from toolbox.collections.mapping import ObjectDict

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

print(d.hello) # >>> 'world'

d.hello = "mundo"
print(d.hello) # >>> 'mundo'

class OverloadedDict(BaseDict)

Dictionary that can be added or subtracted.

Example

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)

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

Example

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)

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 MultiEntryDict(BaseDict)

Dictionary that can have multiple entries for the same key.

from toolbox.collections.mapping import MultiEntryDict

d = MultiEntryDict({"hello": "world", "hello": "mundo"})
print(d) # >>> <MultiEntryDict {'hello': ['world', 'mundo']}>

d['hello'] = 'globo'
print(d) # >>> <MultiEntryDict {'hello': ['world', 'mundo', 'globo']}>

class ItemDict

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

Example

from toolbox.collections.mapping import ItemDict

d = ItemDict({"100": "one hundred"})
print(d)
# >>> <ItemDict {100: one hundred}>

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

---

namedtuple

from toolbox.collections import namedtuple

nestednamedtuple(dictionary)

Converts dictionary to a nested namedtuple recursively.

Parameters:

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

Example

from toolbox.collections.namedtuple import nestednamedtuple

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

Return type:

namedtuple

class fdict

Forced dictionary. Prevents dictionary from becoming a nested namedtuple.

Example

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'}