Skip to content

Materializer Methods🔗

aggregate 🔗

aggregate(by: Callable[[T, T], U], initial: Optional[U] = None) -> T

Applies an accumulator function over the query.

For an optimized summation of numeric values, use sum.

Examples:

>>> from fliq.tests.fliq_test_utils import Point
>>> from fliq import q
>>> q([Point(0, 0), Point(1, 1), Point(2, 2)]).aggregate(by=lambda a, b: a + b)
Point(x=3, y=3)
>>> q([Point(1, 1), Point(2, 2)]).aggregate(by=lambda a, b: a + b, initial=Point(0, 0))
Point(x=3, y=3)

Parameters:

  • by (Callable[[T, T], U]) –

    The accumulator function to apply to each two elements.

  • initial (Optional[U], default: None ) –

    Optional. The initial value of the accumulator. Defaults to None. If provided, it will also serve as the default value for an empty query. If not provided, the first element of the query will be used as the initial value.

all 🔗

all(predicate: Optional[Predicate[T]] = None) -> bool

Returns whether all elements in the query evaluate to true. If a predicate is provided, only elements that satisfy the predicate are considered.

For custom types, consider providing a predicate or implementing __bool__ or __len__ to support this method. see https://docs.python.org/3/reference/datamodel.html#object.bool .

Examples:

>>> from fliq import q
>>> q([True, True, True]).all()
True
>>> q([True, False, True]).all()
False

Parameters:

  • predicate (Optional[Predicate[T]], default: None ) –

    Optional. The predicate to filter the query by.

any 🔗

any(predicate: Optional[Predicate[T]] = None) -> bool

Returns whether any element in the query evaluates to true. If a predicate is provided, only elements that satisfy the predicate are considered.

For custom types, consider providing a predicate or implementing __bool__ or __len__ to support this method. see https://docs.python.org/3/reference/datamodel.html#object.bool .

Examples:

>>> from fliq import q
>>> q([True, False, False]).any()
True
>>> q([False, False, False]).any()
False

Parameters:

  • predicate (Optional[Predicate[T]], default: None ) –

    Optional. The predicate to filter the iterable by.

contains 🔗

contains(item: Any) -> bool

Returns whether the query contains the given item (by equality, not identity). Query also supports the in and not in syntax, which are identical in functionality.

Examples:

>>> from fliq import q
>>> q([1, 2, 3]).contains(2)
True
>>> q([1, 2, 3]).contains(4)
False
>>> 2 in q([1, 2, 3])
True

Parameters:

  • item (Any) –

    The item to test for.

count 🔗

count() -> int

Returns the number of elements in the query.

Examples:

>>> from fliq import q
>>> q([1, 2, 3]).count()
3

equals 🔗

equals(other: Iterable[T], bag_compare: bool = False) -> bool

Returns whether the query is equal to the given iterable. Query also supports the == and != operators.

Examples:

>>> from fliq import q
>>> q([1, 2, 3]).equals([1, 2, 3])
True
>>> q([1, 2, 3]).equals(q([1, 2]))
False
>>> q([1, 2, 3]).equals([3, 2, 1], bag_compare=True)
True

Parameters:

  • other (Iterable[T]) –

    The iterable to test for equality.

  • bag_compare (bool, default: False ) –

    Optional. If True, compares the query and the other iterable as bags, ignoring order and duplicate items. Defaults to False.

first 🔗

first(predicate: Optional[Predicate[T]] = None, default: MissingOrOptional[T] = MISSING) -> Optional[T]

Returns the first element in the query that satisfies the predicate (if provided), or a default value if the query is empty. If default is not provided, raises NoItemsFoundException in case the query is empty.

Parameters:

  • predicate (Optional[Predicate[T]], default: None ) –

    Optional. The predicate to filter the query by.

  • default (MissingOrOptional[T], default: MISSING ) –

    Optional. The default value to return in case the query is empty. Defaults to raise an exception if the query is empty.

Raises:

  • NoItemsFoundException –

    In case the query is empty.

Examples:

>>> from fliq import q
>>> q([1, 2, 3]).first()
1
>>> q([]).first()
Traceback (most recent call last):
...
fliq.exceptions.NoItemsFoundException
>>> q([]).first(default=-1)
-1
>>> q([]).first(default=None) # returns None

max 🔗

max(by: Optional[Selector[T, U]] = None) -> T

Returns the maximal element in the query. If a selector is provided, maximality is determined by the selected value.

Custom types must provide a selector function or implement value comparisons (see https://docs.python.org/3/reference/expressions.html#value-comparisons).

Examples:

>>> from fliq import q
>>> q(range(5)).max()
4
>>> q(range(5)).max(by=lambda x: x*-1)
0

Parameters:

  • by (Optional[Selector[T, U]], default: None ) –

    Optional. The selector function to test for the maximal element. If None, the default ordering is used. If exists, assumes the key is comparable.

Raises:

  • ValueError –

    In case the query is empty.

min 🔗

min(by: Optional[Selector[T, U]] = None) -> T

Returns the minimal element in the query. If a selector is provided, minimality is determined by the selected value.

Custom types must provide a selector function or implement value comparisons (see https://docs.python.org/3/reference/expressions.html#value-comparisons).

Examples:

>>> from fliq import q
>>> q(range(5)).min()
0
>>> q(range(5)).min(by=lambda x: x*-1)
4

Parameters:

  • by (Optional[Selector[T, U]], default: None ) –

    Optional. The selector function to test for the minimal element. If None, the default ordering is used. If exists, assumes the key is comparable.

Raises:

  • ValueError –

    In case the query is empty.

sample 🔗

sample(n: int = 1, seed: Optional[Hashable] = None, budget_factor: Optional[int] = 10, stop_factor: Optional[int] = 10) -> Union[T, List[T]]

Returns a random sample of n elements from the query. If n is 1, returns a single item, otherwise returns a tuple (that can be unpacked).

Examples:

>>> from fliq import q
>>> q(range(10)).sample(n=2, seed=42)
[0, 4]
>>> q(range(10)).sample(n=1, seed=42)
1

Parameters:

  • n (int, default: 1 ) –

    Optional. The number of elements to sample. Defaults to 1.

  • seed (Optional[Hashable], default: None ) –

    Optional. The seed to use for the random sample. Defaults to None.

  • budget_factor (Optional[int], default: 10 ) –

    Optional. Limits the number of attempts to sample n items, as a factor of n. Defaults to 10x n. None will disable budgeting, and may exhaust the iterable (depending on stop_factor).

  • stop_factor (Optional[int], default: 10 ) –

    Optional. The probability to stop re-sampling once the sample is full, as a factor of n: 1 / ( stop_factor * n). Defaults to 1 / (10 * n). None will disable early stopping, and may exhaust the iterable (depending on budget_factor).

Note
  • To safely support infinite iterables, make sure you use budget_factor and/or stop_factor (they are set by default).

Raises:

  • NotEnoughItemsFoundException –

    In case the query is exhausted before n items are sampled.

  • ValueError –

    In case n is not positive.

single 🔗

single(predicate: Optional[Predicate[T]] = None, default: MissingOrOptional[T] = MISSING) -> Optional[T]

Returns the single element in the query, or a default value if the query is empty. Single expects the query to have at most one element (if default is provided), or exactly one element (if default is not provided).

Parameters:

  • predicate (Optional[Predicate[T]], default: None ) –

    Optional. The predicate to filter the query by.

  • default (MissingOrOptional[T], default: MISSING ) –

    Optional. The default value to return in case the query is empty. Defaults to raise an exception if the query is empty.

Examples:

>>> from fliq import q
>>> q([1]).single()
1
>>> q([]).single()
Traceback (most recent call last):
...
fliq.exceptions.NoItemsFoundException
>>> q([1]).single(default=None)
1
>>> q([]).single(default=None) # returns None

>>> q([1, 2, 3]).single(default=None)
Traceback (most recent call last):
...
fliq.exceptions.MultipleItemsFoundException

Raises:

  • NoItemsFoundException –

    In case the query is empty.

  • MultipleItemsFoundException –

    In case the query has more than one element.

sum 🔗

sum(by: Optional[NumericSelector[T]] = None, accumulator: Union[int, float] = 0) -> Union[int, float]

Returns the sum of the elements in the query. If a selector is provided, the sum of the selected elements is returned. If an accumulator is provided, it is used as the initial value for the summation.

Custom types must provide a selector function or implement __add__ and optionally __radd__ (see https://docs.python.org/3/reference/datamodel.html#emulating-numeric-types).

Use this method for optimized summation of numeric values, for other types of aggregation, use aggregate.

Examples:

>>> from fliq import q
>>> q(range(5)).sum()
10
>>> q(range(5)).sum(by=lambda x: x*2)
20

Parameters:

  • by (Optional[NumericSelector[T]], default: None ) –

    Optional. The selector function to apply to each element.

  • accumulator (Union[int, float], default: 0 ) –

    Optional. The initial value of the sum. Defaults to 0.

Returns:

  • Union[int, float] –

    The sum of the elements in the iterable.

to_dict 🔗

to_dict(key: Union[str, Selector[T, U]]) -> Dict[U, List[T]]

Returns the elements of the query as a dictionary, grouped by the given key. If you don't require the group key, consider using group_by() instead.

Examples:

>>> from fliq import q
>>> q([1, 2, 3]).to_dict(key=lambda x: x % 2 == 0)
{False: [1, 3], True: [2]}

Parameters:

  • key (Union[str, Selector[T, U]]) –

    The selector function to apply to each element, or a string representing the name of an attribute to group by.

to_list 🔗

to_list() -> List[T]

Returns the elements of the query as a list.