Skip to content

Mapper Methods🔗

append 🔗

append(*single_items: T) -> Query[T]

Yields the elements of the original query, followed by the input element(s). This supports multiple arguments, where each is considered as a single element.

Infinite iterables are supported, behaving as expected.

Examples:

>>> from fliq import q
>>> q(range(5)).append(5).to_list()
[0, 1, 2, 3, 4, 5]
>>> q(range(5)).append(5, 6, 7).to_list()
[0, 1, 2, 3, 4, 5, 6, 7]

Parameters:

  • *single_items (T, default: () ) –

    One or more elements to add to the end of the query.

append_many 🔗

append_many(items: Iterable[T]) -> Query[T]

Yields the elements of the original query, followed by the elements given.

Infinite iterables are supported, behaving as expected.

Examples:

>>> from fliq import q
>>> q(range(5)).append_many([5, 6, 7]).to_list()
[0, 1, 2, 3, 4, 5, 6, 7]

Parameters:

  • items (Iterable[T]) –

    An iterable to concatenate to the end of the query.

Raises:

  • TypeError –

    In case the elements are not iterable. Error will be raised when query is collected.

bottom 🔗

bottom(n: int = 1, by: Optional[NumericSelector[T]] = None) -> Query[T]

Yields the bottom n elements of the query, according to the selector (if provided).

This is done in O(N log n) time, and O(n) space. Where n is the number of elements to take, and N is the number of elements in the query.

Examples:

>>> from fliq import q
>>> q(range(10)).bottom(n=3).to_list()
[0, 1, 2]

Parameters:

  • n (int, default: 1 ) –

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

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

    Optional. The selector function to apply to each element. Defaults to the identity. If by is None, the default ordering is used, which requires elements to be able to be multiplied by integers.

distinct 🔗

distinct() -> Query[T]

Yields distinct elements while preserving order. Distinct supports infinite iterables. Note that elements must be hashable.

Examples:

>>> from fliq import q
>>> q([0, 1, 0, 2, 2]).distinct().to_list()
[0, 1, 2]

Raises:

  • TypeError –

    In case one or more items in the query are not hashable.

exclude 🔗

exclude(predicate: Predicate[T]) -> Query[T]

Yields elements that do not satisfy the predicate.

Examples:

>>> from fliq import q
>>> q(range(5)).exclude(lambda x: x > 3).to_list()
[0, 1, 2, 3]

Parameters:

  • predicate (Predicate[T]) –

    The predicate to filter the query by.

flatten 🔗

flatten(max_depth: Optional[int] = None, ignore_types: Optional[Tuple[Type[Any], ...]] = (str, bytes)) -> Query[T]

Yields a flattened iterable to a specified depth.

Examples:

>>> from fliq import q
>>> q([[[1], 2], [3, 4]]).flatten().to_list()
[1, 2, 3, 4]
>>> q([[[1], 2], [3, 4]]).flatten(max_depth=1).to_list()
[[1], 2, 3, 4]
>>> q([['hello', 'world'], ['I', 'am', 'Fliq']]).flatten().to_list()
['hello', 'world', 'I', 'am', 'Fliq']
>>> q([['hello', 'world'], ['I', 'am', 'Fliq']]).flatten(ignore_types=None).to_list()
['h', 'e', 'l', 'l', 'o', 'w', 'o', 'r', 'l', 'd', 'I', 'a', 'm', 'F', 'l', 'i', 'q']

Parameters:

  • max_depth (Optional[int], default: None ) –

    Optional. Non-negative. The maximum depth to flatten to. Defaults to none (no limit, completely flat). If max_depth is 0, the query is left unchanged.

  • ignore_types (Optional[Tuple[Type[Any], ...]], default: (str, bytes) ) –

    Optional. A tuple of types to ignore flattening for. Defaults to (str, bytes).

Raises:

  • ValueError –

    In case max_depth is non-positive.

group_by 🔗

group_by(key: Union[str, Selector[T, U]]) -> Query[List[T]]

Yields an iterable of groups (as lists), where each group has identical key. If you require the group key, consider using to_dict() instead.

Examples:

>>> from fliq import q
>>> q([1, 2, 3]).group_by(lambda x: x % 2 == 0).to_list()
[[1, 3], [2]]

Parameters:

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

    A function that takes an element and returns its grouping key, or a string representing the name of an attribute to group by.

interleave 🔗

interleave(*iterables: Iterable[U]) -> Query[Union[T, U]]

Combines the elements of the query with the elements of the provided iterables into a single Query. The elements are interleaved in the order they appear in their respective sources (similar to zip). The process continues until all sources are exhausted. No padding is done in case the iterables are of different lengths.

Examples:

>>> from fliq import q
>>> q([1, 2, 3]).interleave([4], [5, 6]).to_list()
[1, 4, 5, 2, 6, 3]

Parameters:

  • *iterables (Iterable[U], default: () ) –

    One or more iterables to unify with the query.

most_common 🔗

most_common(n: int = 1) -> Query[T]

Yields the most common n elements, in descending order of frequency. By definition, does not support inifinte iterables.

Examples:

>>> from fliq import q
>>> q([1, 2, 3, 1, 2, 1]).most_common(n=1).single()
1
>>> q([1, 2, 3, 1, 2, 1]).most_common(n=2).to_list()
[1, 2]

Parameters:

  • n (int, default: 1 ) –

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

Raises:

  • NotEnoughElementsException –

    In case the query does not have n items.

order 🔗

order(by: Optional[Selector[T, U]] = None, ascending: bool = True) -> Query[T]

Yields elements in sorted order.

Examples:

>>> from fliq import q
>>> q([4, 3, 2, 1, 0]).order().to_list()
[0, 1, 2, 3, 4]

Parameters:

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

    a selector function to extract the key from an item, defaults to None. If None, the default ordering is used. If exists, assumes the key is comparable.

  • ascending (bool, default: True ) –

    whether to sort in ascending or descending order, defaults to True.

pairwise 🔗

pairwise(pad: Optional[T] = None) -> Query[Tuple[T, T]]

Yields tuples of consecutive elements in the query. Practically this is a sliding window of size 2, with overlap 0.

Parameters:

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

    The value to use for padding the last window in case the iterable size is odd.

Examples:

>>> from fliq import q
>>> q([1, 2, 3, 4]).pairwise().to_list()
[(1, 2), (3, 4)]
>>> q([1, 2, 3, 4, 5]).pairwise().to_list()
[(1, 2), (3, 4), (5, None)]

prepend 🔗

prepend(*single_items: T) -> Query[T]

Yields the element(s) given, followed by the elements of the original query. This supports multiple arguments, where each is considered as a single element.

Infinite iterables are supported, behaving as expected.

Examples:

>>> from fliq import q
>>> q(range(5)).prepend(5).to_list()
[5, 0, 1, 2, 3, 4]
>>> q(range(5)).prepend(5, 6, 7).to_list()
[5, 6, 7, 0, 1, 2, 3, 4]

Parameters:

  • *single_items (T, default: () ) –

    One or more elements to add to the start of the query.

prepend_many 🔗

prepend_many(items: Iterable[T]) -> Query[T]

Yields the elements given, followed by the elements of the original query.

Infinite iterables are supported, behaving as expected.

Examples:

>>> from fliq import q
>>> q(range(5)).prepend_many([5, 6, 7]).to_list()
[5, 6, 7, 0, 1, 2, 3, 4]

Parameters:

  • items (Iterable[T]) –

    The elements to add to the start of the query.

Raises:

  • TypeError –

    In case the items are not iterable. Error will be raised when the query is collected.

reverse 🔗

reverse() -> Query[T]

Yields elements in reverse order. Notes: - in case of an irreversible query, TypeError is raised (e.g., set). - in case of an iterator, it is first converted to a list, then reversed, this has a performance and memory impact, and assumes a finite iterator.

Examples: >>> from fliq import q >>> q([0, 1, 2, 3, 4]).reverse().to_list() [4, 3, 2, 1, 0]

Raises:

  • TypeError –

    In case the iterable is irreversible.

select 🔗

select(selector: Selector[T, U]) -> Query[U]

Yields the result of applying the selector function to each element (aka map).

Examples:

>>> from fliq import q
>>> q(range(5)).select(lambda x: x * 2).to_list()
[0, 2, 4, 6, 8]

Parameters:

  • selector (Selector[T, U]) –

    The selector function to apply to each element.

shuffle 🔗

shuffle(buffer_size: int = 10, seed: Optional[Hashable] = None, fair: bool = False) -> Query[T]

Yields elements in a random order. Supports infinite iterables.

Parameters:

  • buffer_size (int, default: 10 ) –

    The size of the shuffle buffer for an unfair shuffle. Defaults to 10. Increasing the size of the buffer will require more memory. However, it will also result in a shuffle that is more evenly distributed (fair).

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

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

  • fair (bool, default: False ) –

    Whether to use a fair shuffle. Defaults to False. If True, each permutation of the elements will be equally likely. This option does not support infinite iterables (specifically, requires a sizeable iterable). This requires materialization of the iterable, which is more memory intensive. Use this for scenarios where fairness is important, like rolling a die or shuffling a deck of cards. If False, each permutation of elements will NOT be equally likely. However, this is more memory efficient, and supports infinite iterables. Use this for scenarios where fairness is not top priority, like shuffling a list of songs in a playlist.

Examples:

>>> from fliq import q
>>> q(range(10)).shuffle(seed=42, buffer_size=5).to_list()
[1, 5, 6, 3, 0, 8, 7, 2, 4, 9]
>>> q(range(10)).shuffle(seed=42, fair=True).to_list()
[7, 3, 2, 8, 5, 6, 9, 4, 0, 1]

Raises:

  • TypeError –

    In case a fair shuffle is requested for a non-sizeable iterable.

skip 🔗

skip(n: int = 1) -> Query[T]

Yields the elements after skipping the first n (as returned from the iterator).

Examples:

>>> from fliq import q
>>> q(range(10)).skip(n=5).to_list()
[5, 6, 7, 8, 9]

Parameters:

  • n (int, default: 1 ) –

    Optional. The number of items to take. Defaults to 1.

slice 🔗

slice(start: int = 0, stop: Optional[int] = None, step: int = 1) -> Query[T]

Yields a slice of the query

Examples:

>>> from fliq import q
>>> q(range(10)).slice(start=1, stop=6, step=2).to_list()
[1, 3, 5]

Parameters:

  • start (int, default: 0 ) –

    Optional. The start index of the slice. Defaults to 0.

  • stop (Optional[int], default: None ) –

    Optional. The stop index of the slice. Defaults to None.

  • step (int, default: 1 ) –

    Optional. The step of the slice. Defaults to 1.

slide 🔗

slide(window: int, overlap: int, pad: Optional[T] = None) -> Query[Tuple[T, ...]]

Yields a sliding window over the iterable. In practice, these are tuples of size 'window' containing the current element and the next 'size-1' elements in the iterable. The tuples overlap by 'overlap' elements.

Parameters:

  • window (int) –

    The size of the tuples to be returned.

  • overlap (int) –

    The number of elements that should overlap between consecutive tuples.

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

    The value to use for padding the last window when the iterable is exhausted.

Examples:

>>> from fliq import q
>>> q([1, 2, 3, 4]).slide(window=3, overlap=2).to_list()
[(1, 2, 3), (2, 3, 4)]
>>> q([1, 2, 3, 4]).slide(window=3, overlap=1).to_list()
[(1, 2, 3), (3, 4, None)]
>>> q([1, 2, 3, 4]).slide(window=3, overlap=1, pad=-1).to_list()
[(1, 2, 3), (3, 4, -1)]

take 🔗

take(n: int = 1, predicate: Optional[Predicate[T]] = None) -> Query[T]

Yields up to n items that satisfy the predicate (if provided). In case the query is ordered, the first n elements are returned.

Parameters:

  • n (int, default: 1 ) –

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

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

    Optional. The predicate to filter the query by.

top 🔗

top(n: int = 1, by: Optional[NumericSelector[T]] = None) -> Query[T]

Yields the top n elements of the query, according to the selector (if provided).

This is done in O(N log n) time, and O(n) space. Where n is the number of elements to take, and N is the number of elements in the query.

Examples:

>>> from fliq import q
>>> q(range(10)).top(n=3).to_list()
[9, 8, 7]
>>> q(range(10)).top(n=3, by=lambda x: x*-1).to_list()
[0, 1, 2]

Parameters:

  • n (int, default: 1 ) –

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

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

    Optional. The selector function to apply to each element. Defaults to the identity.

where 🔗

where(predicate: Optional[Predicate[T]] = None) -> Query[T]

Yields elements that satisfy the predicate (aka filter).

Examples:

>>> from fliq import q
>>> q(range(10)).where(lambda x: x % 2 == 0).to_list()
[0, 2, 4, 6, 8]

Parameters:

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

    Optional. The predicate to filter the query by. If None is given, no filtering takes place.

zip 🔗

zip(*iterables: Iterable[U], longest: bool = False, fill: Optional[Tuple[T, U]] = None) -> Query[Tuple[T, U]]

Yields tuples of the elements of the query with the input iterables. The zipping stops as soon as the smallest of the iterables and the query is exhausted, unless longest is set to True, in which case the zipping stops when the longest iterable is exhausted. If strict mode is enabled, all iterables must have the same length.

Examples:

>>> from fliq import q
>>> q(range(5)).zip([5, 6, 7]).to_list()
[(0, 5), (1, 6), (2, 7)]
>>> q(range(5)).zip([5, 6, 7], longest=True).to_list()
[(0, 5), (1, 6), (2, 7), (3, None), (4, None)]
>>> q(range(5)).zip([5, 6, 7], [8, 9, 10]).to_list()
[(0, 5, 8), (1, 6, 9), (2, 7, 10)]
>>> q(range(5)).zip([5, 6, 7], [8, 9, 10], longest=True, fill=-1).to_list()
[(0, 5, 8), (1, 6, 9), (2, 7, 10), (3, -1, -1), (4, -1, -1)]

Parameters:

  • *iterables (Iterable[U], default: () ) –

    One or more iterables to zip with the query.

  • longest (bool, default: False ) –

    If True, stop zipping when the longest iterable is exhausted. If False (default), stop when the shortest iterable is exhausted.

  • fill (Optional[Tuple[T, U]], default: None ) –

    The value to use for padding when the longest iterable is exhausted. relevant only when longest is True.