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.Any

Collection Item

firebird.base.collections.TypeSpec

Collection Item type specification

alias of Union[Type, Tuple[Type]]

firebird.base.collections.ItemExpr

Collection Item sort expression

alias of Union[str, Callable[[Any], Any]]

firebird.base.collections.FilterExpr

Filter expression

alias of Union[str, Callable[[Any], bool]]

firebird.base.collections.CheckExpr

Check expression

alias of Union[str, Callable[[Any, Any], bool]]

Collections

class firebird.base.collections.BaseObjectCollection[source]

Bases: object

Base class for collection of objects.

all(expr: FilterExpr) → bool[source]

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

Parameters:

expr (FilterExpr) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Return type:

bool

Example

L.all(lambda x: x.name.startswith("ABC"))
L.all('item.name.startswith("ABC")')
any(expr: FilterExpr) → bool[source]

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

Parameters:

expr (FilterExpr) – Bool expression, a callable accepting one parameter and returnin bool or bool expression as string referencing list item as item.

Return type:

bool

Example

L.any(lambda x: x.name.startswith("ABC"))
L.any('item.name.startswith("ABC")')
contains(expr: FilterExpr | None = None) → bool[source]

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

Parameters:

expr (FilterExpr | None) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Return type:

bool

Example

if L.contains(lambda x: x.name.startswith("ABC")):
    ...
if L.contains('item.name.startswith("ABC")'):
    ...
filter(expr: FilterExpr) → Generator[Item, None, None][source]

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

Parameters:

expr (FilterExpr) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Return type:

Generator[Item, None, None]

Example

L.filter(lambda x: x.name.startswith("ABC"))
L.filter('item.name.startswith("ABC")')
filterfalse(expr: FilterExpr) → Generator[Item, None, None][source]

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

Parameters:

expr (FilterExpr) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Return type:

Generator[Item, None, None]

Example

L.filterfalse(lambda x: x.name.startswith("ABC"))
L.filterfalse('item.name.startswith("ABC")')
find(expr: FilterExpr, default: Any | None = None) → Item[source]

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

Parameters:

  • expr (FilterExpr) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

  • default (Any | None) – Default value returned when Items is not found.

Return type:

Item

Example

L.find(lambda x: x.name.startswith("ABC"))
L.find('item.name.startswith("ABC")')
occurrence(expr: FilterExpr) → int[source]

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

Parameters:

expr (FilterExpr) – Bool expression, a callable accepting one parameter and returning bool or bool expression as string referencing list item as item.

Return type:

int

Example

L.occurrence(lambda x: x.name.startswith("ABC"))
L.occurrence('item.name.startswith("ABC")')
report(*args) → Generator[Any, None, None][source]

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.

Return type:

Generator[Any, None, None]

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')
class firebird.base.collections.DataList(items: Iterable | None = None, type_spec: TypeSpec = Sentinel('UNDEFINED'), key_expr: str | None = None, frozen: bool = False)[source]

Bases: List[Any], BaseObjectCollection

List of data (objects) with additional functionality.

Parameters:

  • items (Iterable) –

  • type_spec (TypeSpec) –

  • key_expr (str) –

  • frozen (bool) –

__init__(items: Iterable | None = None, type_spec: TypeSpec = Sentinel('UNDEFINED'), key_expr: str | None = None, frozen: bool = False)[source]
Parameters:

  • items (Iterable | None) – Sequence to initialize the collection.

  • type_spec (TypeSpec) – Reject instances that are not instances of specified types.

  • key_expr (str | None) – 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: Item) → None[source]

Add an item to the end of the list.

Raises:

TypeError – When item is not an instance of allowed class, or list is frozen

Parameters:

item (Item) –

Return type:

None

clear() → None[source]

Remove all items from the list.

Raises:

TypeError – When list is frozen.

Return type:

None

extend(iterable: Iterable) → None[source]

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

Parameters:

iterable (Iterable) –

Return type:

None

extract(expr: FilterExpr, copy: bool = False) → DataList[source]

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

Parameters:

  • expr (FilterExpr) – 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.

Return type:

DataList

Example

L.extract(lambda x: x.name.startswith("ABC"))
L.extract('item.name.startswith("ABC")')
freeze() → None[source]

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: Any, default: Any | None = None) → Item[source]

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 (Any | None) – Default value.

Raises:

Error – If key expression is not defined.

Return type:

Item

Example

# Search using default key expression (fast for frozen list)
L.get('ITEM_NAME')
insert(index: int, item: Item) → None[source]

Insert item before index.

Raises:

TypeError – When item is not an instance of allowed class, or list is frozen

Parameters:

  • index (int) –

  • item (Item) –

Return type:

None

remove(item: Item) → None[source]

Remove first occurrence of item.

Raises:

ValueError – If the value is not present, or list is frozen

Parameters:

item (Item) –

Return type:

None

sort(attrs: List | None = None, expr: ItemExpr | None = None, reverse: bool = False) → None[source]

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

Parameters:

  • attrs (List | None) – List of attribute names.

  • expr (ItemExpr | 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.

  • reverse (bool) –

Return type:

None

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
split(expr: FilterExpr, frozen: bool = False) → Tuple[DataList, DataList][source]

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

Parameters:

  • expr (FilterExpr) – A callable accepting one parameter or expression as string referencing list item as item.

  • frozen (bool) – Create frozen lists.

Return type:

Tuple[DataList, DataList]

Example

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

True if list items couldn’t be changed.

property key_expr: Item

Key expression.

property type_spec: TypeSpec | Sentinel

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

class firebird.base.collections.Registry(data: Mapping | Sequence | Registry | None = None)[source]

Bases: BaseObjectCollection, Mapping[Any, Distinct]

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: Mapping | Sequence | Registry | None = None)[source]
Parameters:

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

clear() → None[source]

Remove all items from registry.

Return type:

None

copy() → Registry[source]

Shalow copy of the registry.

Return type:

Registry

extend(_from: Distinct | Mapping | Sequence) → None[source]

Store one or more items to the registry.

Parameters:

_from (Distinct | Mapping | Sequence) – Either a Distinct instance, or sequence or mapping of Distinct instances.

Return type:

None

get(key[, d]) → D[key] if key in D else d. d defaults to None.[source]
Parameters:

  • key (Any) –

  • default (Any | None) –

Return type:

Distinct

pop(key: Any, default: Any | None = None) → Distinct[source]

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

Parameters:

  • key (Any) –

  • default (Any | None) –

Return type:

Distinct

popitem(last: bool = True) → Distinct[source]

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

Parameters:

last (bool) –

Return type:

Distinct

remove(item: Distinct)[source]

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

Parameters:

item (Distinct) –

store(item: Distinct) → Distinct[source]

Register an item.

Raises:

ValueError – When item is already registered.

Parameters:

item (Distinct) –

Return type:

Distinct

update(_from: Distinct | Mapping | Sequence) → None[source]

Update items in the registry.

Parameters:

_from (Distinct | Mapping | Sequence) – Either a Distinct instance, or sequence or mapping of Distinct instances.

Return type:

None

Functions

firebird.base.collections.make_lambda(expr: str, params: str = 'item', context: Dict[str, Any] | None = None)[source]

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 (Dict[str, Any] | None) – Dictionary passed as context to eval.