Map: Ordered dictionary with magic powers

class carriage.Map

A mutable dictionary enhanced with a bulk of useful methods.

filter(pred)

Create a new Map with key/value pairs satisfying the predicate

>>> m = Map({1: 2, 2: 4, 3: 6})
>>> m2 = m.filter(lambda k, v: (v-k) % 3 == 0)
>>> m2
Map({3: 6})
Parameters:pred ((k, v) -> bool) – predicate
Returns:
Return type:Map[key, value]
filter_by_key(pred)

Create a new Map with keys satisfying the predicate

>>> m = Map({1: 2, 2: 4, 3: 6})
>>> m2 = m.filter_by_key(lambda k: k % 3 == 0)
>>> m2
Map({3: 6})
Parameters:pred ((k, v) -> bool) – predicate
Returns:
Return type:Map[key, value]
filter_by_value(pred)

Create a new Map with values satisfying the predicate

>>> m = Map({1: 2, 2: 4, 3: 6})
>>> m2 = m.filter_by_value(lambda v: v % 3 == 0)
>>> m2
Map({3: 6})
Parameters:pred ((k, v) -> bool) – predicate
Returns:
Return type:Map[key, value]
filter_false(pred)

Create a new Map with key/value pairs not satisfying the predicate

>>> m = Map({1: 2, 2: 4, 3: 6})
>>> m2 = m.filter_false(lambda k, v: (v-k) % 3 == 0)
>>> m2
Map({1: 2, 2: 4})
Parameters:pred ((k, v) -> bool) – predicate
Returns:
Return type:Map[key, value]
first()

Get the first item in Row(key, value) type

>>> m = Map(a=4, b=5, c=6, d=7)
>>> m.first()
Row(key='a', value=4)
>>> m.first().key
'a'
>>> m.first().value
4
>>> m = Map()
>>> m.first()
Traceback (most recent call last):
...
IndexError: index out of range.
Returns:
Return type:Row[key, value]
first_opt()

Optionally get the first item. Return Some(Row(key, value)) if first item exists, otherwise return Nothing

>>> m = Map(a=4, b=5, c=6, d=7)
>>> m.first_opt().map(lambda kv: kv.transform(value=lambda v: v * 2))
Some(Row(key='a', value=8))
>>> m.first_opt().map(lambda kv: kv.value)
Some(4)
>>> m = Map()
>>> m.first_opt()
Nothing
Returns:
Return type:Optional[Row[key, value]]
flip()

Create a new Map which key/value pairs are fliped

>>> m = Map(a=4, b=5, c=6)
>>> m.flip()
Map({4: 'a', 5: 'b', 6: 'c'})
for_each(func)

Call func for each key/value pair

>>> m = Map(a=[], b=[], c=[])
>>> m.for_each(lambda k, v: v.append(k))
>>> m
Map({'a': ['a'], 'b': ['b'], 'c': ['c']})
for_each_key(func)

Call func for each key

>>> m = Map(a=[], b=[], c=[])
>>> keys = []
>>> m.for_each_key(lambda k: keys.append(k))
>>> keys
['a', 'b', 'c']
for_each_value(func)

Call func for each value

>>> m = Map(a=[], b=[], c=[])
>>> m.for_each_value(lambda v: v.append(3))
>>> m
Map({'a': [3], 'b': [3], 'c': [3]})
get_opt(key)

Get the value of specified key as Optional type. Return Some(value) if key exists, otherwise return Nothing.

>>> m = Map(a=3, b=4)
>>> m.get_opt('a')
Some(3)
>>> m.get_opt('c')
Nothing
>>> m.get_opt('a').map(lambda v: v * 2)
Some(6)
>>> m.get_opt('c').map(lambda v: v * 2)
Nothing
Returns:
Return type:Optional[value]
group_by(key_func)

Group key/value pairs into nested Maps.

>>> Map(a=3, b=4, c=5).group_by(lambda k, v: v % 2)
Map({1: Map({'a': 3, 'c': 5}), 0: Map({'b': 4})})
Parameters:key_func ((key, value) -> group_key) – predicate
Returns:
Return type:Map[key_func(key), Map[key, value]]
items() → a set-like object providing a view on D's items
iter_joined(*others, fillvalue=None, agg=None)

Create a Row(key, Row(v0, v1, ...)) iterator with keys from all Maps and value joined.

>>> m = Map(a=1, b=2)
>>> l = list(m.iter_joined(
...          Map(a=3, b=4, c=5),
...          Map(a=6, c=7),
...          fillvalue=0))
>>> l[0]
Row(key='a', values=Row(f0=1, f1=3, f2=6))
>>> l[1]
Row(key='b', values=Row(f0=2, f1=4, f2=0))
>>> l[2]
Row(key='c', values=Row(f0=0, f1=5, f2=7))
join(*others, fillvalue=None, agg=None)

Create a new Map instance with keys merged and values joined.

>>> m1 = Map(a=1, b=2)
>>> m2 = m1.join(dict(a=3, b=4, c=5))
>>> m2 is m1
False
>>> m2
Map({'a': Row(f0=1, f1=3), 'b': Row(f0=2, f1=4), 'c': Row(f0=None, f1=5)})
>>> m1 = Map(a=1, b=2)
>>> m2 = m1.join(dict(a=3, b=4, c=5), agg=sum, fillvalue=0)
>>> m2
Map({'a': 4, 'b': 6, 'c': 5})
keep(*keys)

Delete keys not specified and return self

>>> m = Map(a=3, b=4, c=5)
>>> m.keep('a', 'c')
Map({'a': 3, 'c': 5})
>>> m
Map({'a': 3, 'c': 5})
Returns:
Return type:self
keys() → a set-like object providing a view on D's keys
len()

Get the length of this Map

>>> m = Map(a=4, b=5, c=6, d=7)
>>> m.len()
4
Returns:
Return type:int
make_string(key_value_format='{key!r}: {value!r}', start='{', item_sep=', ', end='}')

Construct a string from key/values.

>>> m = Map(a=3, b=4, c=5)
>>> m.make_string()
"{'a': 3, 'b': 4, 'c': 5}"
>>> m.make_string(start='(', key_value_format='{key}={value!r}',
...               item_sep=', ', end=')')
'(a=3, b=4, c=5)'
Parameters:
  • key_value_format (str) – string template using builtin str.format() for formatting key/value pairs. Default to '{key!r}: {value!r}'. Available named placeholders: {key}, {value}
  • start (str) – Default to '{'.
  • item_sep (str) – Default to ', '
  • end (str) – Default to }
Returns:

Return type:

str

map(func)

Create a new Map instance that each key, value pair is derived by applying function to original key, value.

>>> Map(a=3, b=4).map(lambda k, v: (v, k))
Map({3: 'a', 4: 'b'})
Parameters:func (pred(key, value) -> (key, value)) – function for computing new key/value pair
map_keys(func)

Create a new Map instance that all values remains the same, while each corresponding key is updated by applying function to original key, value.

>>> Map(a=3, b=4).map_keys(lambda k, v: k + '_1')
Map({'a_1': 3, 'b_1': 4})
Parameters:func (pred(key, value) -> key) – function for computing new keys
map_values(func)

Create a new Map instance that all keys remains the same, while each corresponding value is updated by applying function to original key, value.

>>> Map(a=3, b=4).map_values(lambda k, v: v * 2)
Map({'a': 6, 'b': 8})
Parameters:func (pred(key, value) -> value) – function for computing new values
nlargest_value_items(n=None)

Get top n largest values

>>> m = Map(a=6, b=2, c=10, d=9)
>>> m.nlargest_value_items(n=2)
Array([Row(key='c', value=10), Row(key='d', value=9)])
Returns:
Return type:Array[Row[key, value]]
nsmallest_value_items(n=None)

Get top n smallest values

>>> m = Map(a=6, b=2, c=10, d=9)
>>> m.nsmallest_value_items(n=2)
Array([Row(key='b', value=2), Row(key='a', value=6)])
Returns:
Return type:Array[Row[key, value]]
nth(index)

Get the nth item in Row(key, value) type.

>>> m = Map(a=4, b=5, c=6, d=7)
>>> m.nth(2)
Row(key='c', value=6)
>>> m = Map(a=4, b=5)
>>> m.nth(2)
Traceback (most recent call last):
...
IndexError: index out of range.
Returns:
Return type:Row[key, value]
nth_opt(index)

Optionally get the nth item. Return Some(Row(key, value)) if first item exists, otherwise return Nothing.

>>> m = Map(a=4, b=5, c=6, d=7)
>>> m.first_opt().map(lambda kv: kv.transform(value=lambda v: v * 2))
Some(Row(key='a', value=8))
>>> m = Map()
>>> m.first_opt()
Nothing
Returns:
Return type:Optional[Row[key, value]]
project(*keys)

Create a new Map instance contains only specified keys.

>>> m = Map(a=3, b=4, c=5)
>>> m.project('a', 'c')
Map({'a': 3, 'c': 5})
>>> m
Map({'a': 3, 'b': 4, 'c': 5})
Returns:
Return type:Map[key, value]
remove(*keys)

Delete keys and return self

>>> m = Map(a=3, b=4, c=5)
>>> m.remove('a', 'c')
Map({'b': 4})
>>> m
Map({'b': 4})
Returns:
Return type:self
retain(pred)

Delete key/value pairs not satisfying the predicate and return self

>>> m = Map(a=3, b=4, c=5)
>>> m.retain(lambda k, v: k == 'b' or v == 5)
Map({'b': 4, 'c': 5})
>>> m
Map({'b': 4, 'c': 5})
Parameters:pred ((k, v) -> bool) –
Returns:
Return type:self
retain_by_key(pred)

Delete key/value pairs not satisfying the predicate and return self

>>> m = Map(a=3, b=4, c=5)
>>> m.retain_by_key(lambda k: k == 'b')
Map({'b': 4})
>>> m
Map({'b': 4})
Parameters:pred ((k) -> bool) –
Returns:
Return type:self
retain_by_value(pred)

Delete key/value pairs not satisfying the predicate and return self

>>> m = Map(a=3, b=4, c=5)
>>> m.retain_by_value(lambda v: v == 4)
Map({'b': 4})
>>> m
Map({'b': 4})
Parameters:pred ((k) -> bool) –
Returns:
Return type:self
retain_false(pred)

Delete key/value pairs satisfying the predicate and return self

>>> m = Map(a=3, b=4, c=5)
>>> m.retain_false(lambda k, v: k == 'b' or v == 5)
Map({'a': 3})
>>> m
Map({'a': 3})
Parameters:pred ((k, v) -> bool) –
Returns:
Return type:self
revamp_values(func)

Update values of current Map and return self. Each value is derived by computing the function using both key and value.

>>> m = Map(a=3, b=4)
>>> m.revamp_values(lambda k, v: v * 2)
Map({'a': 6, 'b': 8})
>>> m
Map({'a': 6, 'b': 8})
Parameters:func (pred(key, value) -> value) – function for computing new values
Returns:
Return type:self
take(n)

create a Stream instance of first n Row(key, value) elements.

>>> m = Map(a=4, b=5, c=6, d=7)
>>> m.take(2).to_list()
[Row(key='a', value=4), Row(key='b', value=5)]
Returns:
Return type:Stream[Row[key, value]]
to_array()

Convert to an Array instance of Row(key, value) iterable.

>>> m = Map(a=4, b=5, c=6, d=7)
>>> m.to_array().take(2)
Array([Row(key='a', value=4), Row(key='b', value=5)])
Returns:
Return type:Array[Row[key, value]]
to_dict()

Convert to dict

to_list()

Convert to an list instance of Row(key, value) iterable.

>>> m = Map(a=4, b=5)
>>> m.to_list()
[Row(key='a', value=4), Row(key='b', value=5)]
Returns:
Return type:Array[Row[key, value]]
to_stream(key_field='key', value_field='value')

Convert to a Stream instance of Row(key, value) iterable.

>>> m = Map(a=4, b=5, c=6, d=7)
>>> m.to_stream().take(2).to_list()
[Row(key='a', value=4), Row(key='b', value=5)]
Returns:
Return type:Stream[Row[key, value]]
update(*args, **kwds)

Update Map from dict/iterable and return self

>>> m = Map(a=3, b=4)
>>> m2 = m.update(a=5, c=3).update({'d': 2})
>>> m is m2
True
>>> m
Map({'a': 5, 'b': 4, 'c': 3, 'd': 2})
updated(*args, **kwds)

Create a new Map instance that is updated from dict/iterable. This method is the same as m.copy().update(...)

>>> m = Map(a=3, b=4)
>>> m2 = m.updated(a=5, c=3).update({'d': 2})
>>> m2
Map({'a': 5, 'b': 4, 'c': 3, 'd': 2})
>>> m
Map({'a': 3, 'b': 4})
values() → an object providing a view on D's values
without(*keys)

Create a new Map instance with those keys

>>> m = Map(a=3, b=4, c=6)
>>> m.without('a', 'c')
Map({'b': 4})
>>> m
Map({'a': 3, 'b': 4, 'c': 6})
Returns:
Return type:Map[key, value]