collections - Various collection types¶

Overview¶

This module provides data structures that behave much like builtin list and dict types, but with direct support of operations that can use structured data stored in container, and which would normally require utilization of operator, functools or other means.

All containers provide next operations:

filter and filterfalse that return generator that yields items for which expr is evaluated as True (or False).
find that returns first item for which expr is evaluated as True, or default.
contains that returns True if there is any item for which expr is evaluated as True.
occurrence that returns number of items for which expr is evaluated as True.
all and any that return True if expr is evaluated as True for all or any list element(s).
report that returns generator that yields data produced by expression(s) evaluated on list items.

Individual collection types provide additional operations like splitting and extracting based on expression etc.

Expressions used by these methods could be strings that contain Python expression referencing the collection item(s), or lambda functions.

Types for type hints & annotations¶

firebird.base.collections.Item = typing.Type[typing.Any]¶: Collection Item

firebird.base.collections.TypeSpec = typing.Union[typing.Type, typing.Tuple[typing.Type]]¶: Collection Item type specification

firebird.base.collections.ItemExpr = typing.Union[str, typing.Callable[[typing.Type[typing.Any]], typing.Type[typing.Any]]]¶: Collection Item sort expression

firebird.base.collections.FilterExpr = typing.Union[str, typing.Callable[[typing.Type[typing.Any]], bool]]¶: Filter expression

firebird.base.collections.CheckExpr = typing.Union[str, typing.Callable[[typing.Type[typing.Any], typing.Any], bool]]¶: Check expression

Collections¶

BaseObjectCollection¶

class firebird.base.collections.BaseObjectCollection¶

Bases: object

Base class for collection of objects.

all(expr)¶

Return True if expr is evaluated as True for all list elements.

Parameters: expr (Union[str, Callable[[Type[Any]], bool]]) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Example

L.all(lambda x: x.name.startswith("ABC"))
L.all('item.name.startswith("ABC")')

Return type: bool

any(expr)¶

Return True if expr is evaluated as True for any list element.

Parameters: expr (Union[str, Callable[[Type[Any]], bool]]) – Bool expression, a callable accepting one parameter and returnin bool or bool expression as string referencing list item as item.

Example

L.any(lambda x: x.name.startswith("ABC"))
L.any('item.name.startswith("ABC")')

Return type: bool

contains(expr=None)¶

Returns True if there is any item for which expr is evaluated as True.

Parameters: expr (Union[str, Callable[[Type[Any]], bool], None]) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Example

if L.contains(lambda x: x.name.startswith("ABC")):
    ...
if L.contains('item.name.startswith("ABC")'):
    ...

Return type: bool

filter(expr)¶

Returns generator that yields items for which expr is evaluated as True.

Parameters: expr (Union[str, Callable[[Type[Any]], bool]]) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Example

L.filter(lambda x: x.name.startswith("ABC"))
L.filter('item.name.startswith("ABC")')

Return type: Generator[Type[Any], None, None]

filterfalse(expr)¶

Returns generator that yields items for which expr is evaluated as False.

Parameters: expr (Union[str, Callable[[Type[Any]], bool]]) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Example

L.filterfalse(lambda x: x.name.startswith("ABC"))
L.filterfalse('item.name.startswith("ABC")')

Return type: Generator[Type[Any], None, None]

find(expr, default=None)¶

Returns first item for which expr is evaluated as True, or default.

Parameters

expr (Union[str, Callable[[Type[Any]], bool]]) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.
default (Optional[Any]) – Default value returned when Items is not found.

Example

L.find(lambda x: x.name.startswith("ABC"))
L.find('item.name.startswith("ABC")')

Return type: Type[Any]

occurrence(expr)¶

Return number of items for which expr is evaluated as True.

Parameters: expr (Union[str, Callable[[Type[Any]], bool]]) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Example

L.occurrence(lambda x: x.name.startswith("ABC"))
L.occurrence('item.name.startswith("ABC")')

Return type: int

report(*args)¶

Returns generator that yields data produced by expression(s) evaluated on list items.

Parameters

args –

Parameter(s) could be one from:

A callable accepting one parameter and returning data for output
One or more expressions as string referencing item as item.

Example

# generator of tuples with item.name and item.size

L.report(lambda x: (x.name, x.size))
L.report('item.name','item.size')

# generator of item names

L.report(lambda x: x.name)
L.report('item.name')

Return type: Generator[Any, None, None]

DataList¶

class firebird.base.collections.DataList(items=None, type_spec=Sentinel('UNDEFINED'), key_expr=None, frozen=False)¶

Bases: list, typing.Generic, firebird.base.collections.BaseObjectCollection

List of data (objects) with additional functionality.

__init__(items=None, type_spec=Sentinel('UNDEFINED'), key_expr=None, frozen=False)¶

Parameters

items (Optional[Iterable]) – Sequence to initialize the collection.
type_spec (Union[Type, Tuple[Type]]) – Reject instances that are not instances of specified types.
key_expr (Optional[str]) – Key expression. Must contain item referrence as item, for example item.attribute_name. If all classes specified in type_spec are descendants of Distinct, the default value is item.get_key(), otherwise the default is None.
frozen (bool) – Create frozen list.

Raises

ValueError – When initialization sequence contains invalid instance.

append(item)¶

Add an item to the end of the list.

Raises: TypeError – When item is not an instance of allowed class, or list is frozen
Return type: None

clear()¶

Remove all items from the list.

Raises: TypeError – When list is frozen.
Return type: None

extend(iterable)¶

Extend the list by appending all the items in the given iterable.

Raises: TypeError – When item is not an instance of allowed class, or list is frozen
Return type: None

extract(expr, copy=False)¶

Move/copy items for which expr is evaluated as True into new DataList.

Parameters

expr (Union[str, Callable[[Type[Any]], bool]]) – A callable accepting one parameter or expression as string referencing list item as item.
copy (bool) – When True, items are not removed from source DataList.

Raises

TypeError – When list is frozen and copy is False.

Example

L.extract(lambda x: x.name.startswith("ABC"))
L.extract('item.name.startswith("ABC")')

Return type: DataList

freeze()¶

Set list to immutable (frozen) state.

Freezing list makes internal map from key_expr to item index that significantly speeds up retrieval by key using the get() method.

It’s not possible to add, delete or change items in frozen list, but sort is allowed.

Return type: None

get(key, default=None)¶

Returns item with given key using default key expression. Returns default value if item is not found.

Uses very fast method to look up value of default key expression in frozen list, otherwise it uses slower list traversal.

Parameters

key (Any) – Searched value.
default (Optional[Any]) – Default value.

Raises

Error – If key expression is not defined.

Example

# Search using default key expression (fast for frozen list)
L.get('ITEM_NAME')

Return type: Type[Any]

insert(index, item)¶

Insert item before index.

Raises: TypeError – When item is not an instance of allowed class, or list is frozen
Return type: None

remove(item)¶

Remove first occurrence of item.

Raises: ValueError – If the value is not present, or list is frozen
Return type: None

sort(attrs=None, expr=None, reverse=False)¶

Sort items in-place, optionaly using attribute values as key or key expression.

Parameters

attrs (Optional[List]) – List of attribute names.
expr (Union[str, Callable[[Type[Any]], Type[Any]], None]) – Key expression, a callable accepting one parameter or expression as string referencing list item as item.
Important – Only one parameter (attrs or expr) could be specified. If none is present then uses default list sorting rule.

Example

L.sort(attrs=['name','degree'])       # Sort by item.name, item.degree
L.sort(expr=lambda x: x.name.upper()) # Sort by upper item.name
L.sort(expr='item.name.upper()')      # Sort by upper item.name

Return type: None

split(expr, frozen=False)¶

Return two new DataList instances, first with items for which expr is evaluated as True and second for expr evaluated as False.

Parameters

expr (Union[str, Callable[[Type[Any]], bool]]) – A callable accepting one parameter or expression as string referencing list item as item.
frozen (bool) – Create frozen lists.

Example

below, above = L.split(lambda x: x.size > 100)
below, above = L.split('item.size > 100')

Return type: Tuple[DataList, DataList]

property frozen¶

True if list items couldn’t be changed.

Return type: bool

property key_expr¶

Key expression.

Return type: Type[Any]

property type_spec¶

Specification of valid type(s) for list values, or UNDEFINED if there is no such constraint.

Return type: Union[Type, Tuple[Type], Sentinel]

Registry¶

class firebird.base.collections.Registry(data=None)¶

Bases: firebird.base.collections.BaseObjectCollection, collections.abc.Mapping, typing.Generic

Mapping container for Distinct objects.

Any method that expects a key also acepts Distinct instance.

To store items into registry with existence check, use:

R.store(item)
R.extend(items) or R.extend(item)

To update items in registry (added if not present), use:

R[key] = item
R.update(items) or R.update(item)

To check presence of item or key in registry, use:

key in R

To retrieve items from registry, use:

R.get(key, default=None)
R[key]
R.pop(key, default=None)
R.popitem(last=True)

To delete items from registry, use:

R.remove(item)
del R[key]

Whenever a key is required, you can use either a Distinct instance, or any value that represens a key value for instances of stored type.

__init__(data=None)¶

Parameters: data (Union[Mapping, Sequence, Registry, None]) – Either a Distinct instance, or sequence or mapping of Distinct instances.

clear()¶

Remove all items from registry.

Return type: None

copy()¶

Shalow copy of the registry.

Return type: Registry

extend(_from)¶

Store one or more items to the registry.

Parameters: _from (Union[Distinct, Mapping, Sequence]) – Either a Distinct instance, or sequence or mapping of Distinct instances.
Return type: None

get(key, default=None)¶

Return type: Distinct

pop(key, default=None)¶

Remove specified key and return the corresponding Distinct object. If key is not found, the default is returned if given, otherwise KeyError is raised.

Return type: Distinct

popitem(last=True)¶

Returns and removes a Distinct object. The objects are returned in LIFO order if last is true or FIFO order if false.

Return type: Distinct

remove(item)¶: Removes item from registry (same as: del R[item]).

store(item)¶

Raises: ValueError – When item is already registered.
Return type: Distinct

update(_from)¶

Update items in the registry.

Parameters: _from (Union[Distinct, Mapping, Sequence]) – Either a Distinct instance, or sequence or mapping of Distinct instances.
Return type: None

Functions¶

make_lambda¶

firebird.base.collections.make_lambda(expr, params='item', context=None)¶

Makes lambda function from expression.

Parameters

expr (str) – Python expression as string.
params (str) – Comma-separated list of names that should be used as lambda parameters
context (Optional[Dict[str, Any]]) – Dictionary passed as context to eval.