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

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.

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.

Parameters

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

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.

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)

Register an 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.