dict_plus package

Submodules

dict_plus.dictplus module

dict_plus.elements module

class dict_plus.elements.ElementFactory

Bases: object

Factory to create Elements within Dictionaries

static element(subclass_type, superclass_type)

Create a new element of type subclass_type in containing dictionary of type superclass_type

Parameters:

• subclass_type – Type of Element to create, ie KeyValuePair
• superclass_type – Type of Dictionary to hold this element, ie. SortedDictPlus

Returns:

A new element type class for the specific use of the subclass type and superclass type

dict_plus.etypes module

Python version compatible type import helper Exported types: - DictType - ListType - StringTypes

dict_plus.exceptions module

exception dict_plus.exceptions.InvalidElementTypeException

Bases: TypeError

Raised when the Element type doesn’t match the expected element type

exception dict_plus.exceptions.InvalidElementValueException

Bases: ValueError

Raised when the Element value doesn’t match the expected element value constraints

exception dict_plus.exceptions.InvalidIteratorException

Bases: Exception

Raised when an invalid Iterator is passed in

exception dict_plus.exceptions.InvalidSubDictType

Bases: ValueError

Raised when the subdict type of a listdict isn’t the correct type

dict_plus.funcs module

class dict_plus.funcs.Functions

Bases: object

static AND(*els)

Basic AND function operation for elements

Parameters:*els – Element-like instances to AND values with Returns:(True, True) if all values evaluate to true (False, False) otherwise

static GE(v1, v2)

Is v1 >= v2 ? :param v1: Value 1 :param v2: Value 2

Returns:True if v1 >= v2 else False

static GT(v1, v2)

Is v1 > v2 ? :param v1: Value 1 :param v2: Value 2

Returns:True if v1 .>v2 else false

static LE(v1, v2)

Is v1 <= v2 ? :param v1: Value 1 :param v2: Value 2

Returns:True if v1 <= v2 else false

static LT(v1, v2)

Is v1 < v2 ? :param v1: Value 1 :param v2: Value 2

Returns:True if v1 < v2 else false

static OR(*els)

Basic OR function operation for elements :param *els: Element-like instances to OR values with

Returns:True if any value evaluates to True

dict_plus.hooked module

dict_plus.indexes module

dict_plus.insensitive module

dict_plus.iterable module

class dict_plus.iterable.Iterable(data=None, **kwargs)

Bases: dict

__add__(other)

Default behavior the same as self.update(other) Returns new instance, doesn’t modify self

Parameters:other – Iterable-like to add Returns:Added Iterables

__contains__(item)

Check whether item exists in self, where item is a key in the Iterable

Parameters:item – Key to check if it exists Returns:True if item in self else False

__delitem__(k)

Delete an item from the Iterable

__eq__(other)

Check if this Iterable is equal to another Iterable-like ‘other’ Must have the same length, and each key must have the same value, order doesn’t matter

Parameters:other – Iterable-like to compare equality Returns:True if self is equal to other else False

__ge__(other)

Compare each element in self to other with >= operator, then aggregate the values of each resulting key with AND

Parameters:other – Iterable-like to compare against Returns:True if self >= other else False

__getitem__(k)

Get an item from I x.__getitem__(y) <==> x[y]

Parameters:k – Key to retrieve Returns:Value at key ‘k’

__gt__(other)

Compare each element in self to other with > operator, then aggregate the values of each resulting key with AND

Parameters:other – Iterable-like to compare against Returns:True if self > other else False

__init__(data=None, **kwargs)

Initialize a new Iterable

Examples

Iterable() -> new empty Iterable Iterable(mapping) -> new Iterable initialized from a mapping object’s (key, value) pairs Iterable(iterable) -> new Iterable initialized as if via:

d = {}
for k, v in iterable:
    d[k] = v

Iterable(**kwargs) -> new Iterable initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

Parameters:

• data – Optional data to be inserted into the Iterable, can be a dict, list of tuples,
• another Iterable instance (or) –
• element_type – Element container for the data, must inherit from Element, contains an id and a value
• kwargs – Additional data to initialize with

__iter__()

Get an iterable instance from I, similar to iter(dict) iterates on the keys

Returns:iter of the keys

__le__(other)

Compare each element in self to other with <= operator, then aggregate the values of each resulting key with AND

Parameters:other – Iterable-like to compare against Returns:True if self <= other else False

__len__()

Get the number of elements in self

Returns:Integer length of elements in self

__lt__(other)

Compare each element in self to other with < operator, then aggregate the values of each resulting key with AND

Parameters:other – Iterable-like to compare against Returns:True if self < other else False

__mul__(other)

Multiply self by other Returns new instance, doesn’t modify self

Parameters:other – Iterable-like Returns:Multiplied Iterable

__ne__(other)

Opposite of __eq__

__repr__()

Get the string-like representation of this object, fit for eval()

Returns:Constructor to create this instance with the same data

__setitem__(key, value)

Set self[key] to value. If key doesn’t exist, create it

Parameters:

• key – key to set
• value – value to set under key

__str__()

Get the string representation of this object, should be the same as str(dict) Except for Python2, where dictionary order is not preserved

Returns:String representing this Iterable

__sub__(other)

Default behavior the same as self.unupdate(other) Returns new instance, doesn’t modify self

Parameters:other – Iterable-like to sub Returns:Difference of Iterables

__truediv__(other)

Divide self by other, inverse of multiplication Returns new instance, doesn’t modify self

Parameters:other – Iterable-like Returns:Divided Iterable

atindex(int_val)

Get the element at index ‘int_val’

Parameters:int_val – Integer value to fetch the element from Returns:Element instance

chop(func)

Chop the Iterable into other Iterables using a binning function ‘func’ Each keypair is assigned a value -infinity to +infinity, and put into other iterables with the same number. These ‘bins’ are then ordered relatively to each other and returned in a list

Parameters:func – func(k, v) -> int Returns:List of Iterables

clear() → None. Remove all items from the dict

compare(other, comp, agg, mapp=None, inplace=False)

Compare self with other using comparison func ‘comp’ aggregate function ‘agg’ and mapping function ‘mapp’ If no mapping function is given, the default mapping function maps each element at index i in self to an element at index i in other. This can cause problems if other and self don’t have the same length

Parameters:

• other – Iterable-like to compare against
• comp – comp(element1, element2) -> new_value
• agg – agg([element1, element2, ..]) -> new_value
• mapp – mapp(self_key) -> other_key
• inplace – Boolean to modify self or use a copy

Returns:

Result from the aggregate function

copy() → a shallow copy of I

Returns:Copied instance

disaggregate(placeholder=None)

Opposite of the ListDict .aggregate()

divide(other, func_inv=None)

Divide self with Iterable-like ‘other’ using function ‘func’ If func_inv is None, will default to func_inv(element1, element2) -> (key1, value1) or (key2, value2) Every element of self is applied to every element of ‘other’

Parameters:

• other – Iterable-like to multiply by
• func_inv – func_inv(element1, element2) -> new_element

Returns:

self

elements()

Returns a copy of the elements in the Iterable instance

Returns:List of Elements

expand(key, new_keys, func_inv)

Expand a key into a larger amount of keys Works in place

Parameters:

• to expand on (Key) –
• new_keys – List of keys that will be set
• func_inv – func(value) -> [value1, value2, ..]

filter(func)

Filter each element in the Iterable to keep if ‘func’ returns True, otherwise it is removed.

Parameters:func – func(k,v) -> True or False

fold_left(func)

Reduce the Iterable using function ‘func’ and the ‘left’ grouping pattern Like (((1 + 2) + 3) + 4) so:

func(func(func(element1, element2), element3), element4)

Parameters:func – func(element1, element2) -> new_element Returns:Element

fold_right(func)

Reduce the Iterable using function ‘func’ and the ‘right’ grouping pattern Like (1 + (2 + (3 + 4))) so:

func(element1, func(element2, func(element3, element4)))

Parameters:func – func(element1, element2) -> new_element Returns:Element

static fromkeys(sequence, value=None)

Create an Iterable instance using a list, each element will be used as a key, with each with value ‘value’

Parameters:

• sequence – List of keys to use
• value – Value to set for each key

Returns:

Instance with keys from ‘sequence’ with value ‘value’

funcmap(other, comb, mapp, inplace=True)

Combine self and Iterable-like ‘other’ with function ‘comb’ Using mapping ‘mapp’ Can be in-place or not.

Parameters:

• other – Iterable-like to combine with
• comb – combine function with signature comb(value1, value2) -> new_value
• mapp – mapping function with signature mapp(self_key) -> other_key
• inplace – Boolean to change self, or return a modified copy

Returns:

Iterable

get(k[, v_alt]) → I[k] if k in I, else v_alt.

v_alt defaults to None.

Parameters:

• k – key to get the value of
• v_alt – alternate value to return if key doesn’t exist

Returns:

The value stored with the key

get_element_type()

static getfunc(name, *args, **kwargs)

Get a wrapped static version of an Iterable function, with signature func(inst) Providing arguments and keyword arguments for the function.

Parameters:

• name – Name of the function to get
• args – Arguments to use for the function
• kwargs – Keyword arguments to use for the function

Returns:

A function with signature f(instance)

getitem(k, v_alt=<dict_plus.etypes._NoneVal object>)

Get the full element from key ‘k’ if no key or value is present, Element(k, v_alt) will be returned

Parameters:

• k – key to get
• v_alt – alternate value to return if the key doesn’t exist

Returns:

Element with key ‘k’

indexof(key)

Get the integer index value of a given key

Raises:KeyError – if the key doesn’t exist Parameters:key – Key to get the index of Returns:Integer index

insert(index, obj)

Insert an object into the Iterable, raises a KeyError if the key already exists Index value is ignored in the Iterable superclass, as order is not preserved anyways

Parameters:

• index – Value to insert element to, unless ordered, the index always will be the last
• obj – Object to insert into the Iterable. Must conform with the element type of the iterable

Returns:

Element that was inserted

items()

Gives a list of the items in the Iterable instance, in form (key, value)

Returns:a list providing a view on I’s items

iteritems()

Python2 iteritems()

Returns:An iterable list of (key, value) consistent with python 2 syntax

keys()

A list providing a view on I’s keys

Returns:List of keys in I

map(func)

Map each element in the Iterable to another using function ‘func’

Parameters:func – func(key, value) -> (new_key, new_value)

multiply(other, func=None)

Multiply self with Iterable-like ‘other’ using function ‘func’ If func is None, will default to func(element1, element2) -> ((key1, key2), (value1, value2)) Every element of self is applied to every element of ‘other’

Parameters:

• other – Iterable-like to multiply by
• func – func(element1, element2) -> new_element

Returns:

self

pop(k, v_alt=<dict_plus.etypes._NoneVal object>)

Don’t care about order, so we move the last element to the position of the removed element, remove the index to the popped element, to keep the time complexity constant

I.pop(k[,v_alt]) -> v, remove specified key and return the corresponding value. If key is not found, v_alt is returned if given, otherwise KeyError is raised :param k: key to pop :param v_alt: alternate value if k doesn’t exist :return: The retrieved value from key k

pop_regex(k_regex)

Pop keys in the dict that match the given regex

popitem() → (k, v), remove and return some (key, value) pair as a

2-tuple; but raise KeyError if I is empty. Pops from the last index

Returns:(key, value)

rekey(func)

Re-key the Iterable with function ‘func’ Changes keys in place, values untouched

Parameters:func – func(key1) -> key2

rekey_regex(regex, replace_str='', overwrite_collisions=False)

Re-key keys that match the given regex, and replacing the part of the key that matches with replace_str. Useful for removing prefixes in dictionaries.

overwrite_collisions will overwrite upon collision, else KeyError will be thrown

setdefault(k, v_alt=None)

Same as I.get(k,d), also set I[k]=d if k not in I

Parameters:

• k – key to use
• v_alt – Alternate value to set and return if k isn’t in I

Returns:

Element value

squish(keys, new_key, func)

Squish elements into another new element, using function ‘func’ Works in place.

Parameters:

• keys – List of keys to squish
• new_key – Name of the new key
• func – func([value1, value2, …]) -> new_value

swap(k1, k2)

Swap two keys in the Iterable, works in place

Parameters:

• k1 – first key
• k2 – second key

todict()

Convert the Iterable to a pure python dictionary

Returns:dict

tolist()

Convert the Iterable to a pure python list

Returns:list of (key, value)

unupdate(e=None, **kwargs)

Undo a .update operation, essentially the same as popping a list of keys, except will raise an InvalidElementValueException if the key-value pair doesn’t match what is to be popped

Parameters:

• e – dict or iterable to unupdate with
• kwargs – keyword args to unupdate from

update([E, ]**F) → None. Update I 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]

Parameters:

• e – iterable/dict to update from
• kwargs – other keyword args to update from

values() → an object providing a view on I's values

Returns:List of values in I

class dict_plus.iterable.OrderedIterable(data=None, **kwargs)

Bases: dict_plus.iterable.Iterable

Mixin of Iterable, specializing in keeping the order of the elements intact through any internal operations.

add(other, func=None)

Add this Iterable with another Iterable-like combine with function ‘func’ If no function is given, the default function will concatenate the two Iterables Works in place, allows for concurrent modification

Parameters:

• other – Iterable-like to add to
• func – func(element1, element2) -> new_element

Returns:

self

static fromkeys(sequence, value=None)

Create an OrderedIterable instance using a list, each element will be used as a key, with each with value ‘value’

Parameters:

• sequence – List of keys to use
• value – Value to set for each key

Returns:

Instance with keys from ‘sequence’ with value ‘value’

insert(index, obj)

Insert an object into the OrderedIterable, raises a KeyError if the key already exists Index value is used to place the object, and then we must update our indexes dict

Parameters:

• index – Value to insert element to
• obj – Object to insert into the Iterable. Must conform with the element type of the iterable

Returns:

Element that was inserted

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

If key is not found, v_alt is returned if given, otherwise KeyError is raised. After the pop an indexes update must be performed

Parameters:

• k – key to pop
• v_alt – alternate value if k doesn’t exist

Returns:

The retrieved value from key k

sub(other, func_inv=None)

Inverse of I.add(), combines with another Iterable-like with function ‘func’ If no function is given will default to removing the ‘other’s elements from self

Parameters:

• other – Iterable-like to subtrace from
• func_inv – func(element1, element2) -> new_element

Returns:

self

Module contents