fleche.query

Classes

QueryIterator

Re-iterable view over a lazy query result.

Functions

_resolve_key(→ Callable[[call.LazyCall], Any])

Normalise a key argument to a callable.

Module Contents

fleche.query._resolve_key(key: str | Callable[[call.LazyCall], Any]) → Callable[[call.LazyCall], Any]

Normalise a key argument to a callable.

When given a string, produce a lookup on LazyCall.arguments[key].

class fleche.query.QueryIterator

Bases: Iterable[fleche.call.LazyCall]

Re-iterable view over a lazy query result.

calls is a zero-argument callable that returns a fresh iterable each time it is invoked. Every for loop, list(), or consuming method therefore starts a new traversal of the underlying source, so the same QueryIterator can be used multiple times and will reflect the current state of the cache on each pass.

Parameters:

calls – factory returning an iterable of LazyCall

calls: Callable[[], Iterable[fleche.call.LazyCall]]

__iter__() → Iterator[fleche.call.LazyCall]

only() → fleche.call.LazyCall

Return the single matching call.

Raises:

• IndexError – if there are no matching calls

• ValueError – if there is more than one matching call

count() → int

Return the total number of matching calls.

any() → fleche.call.LazyCall | None

Return the first matching call, or None if there are no matching calls.

Use .sorted(reverse=…) to control which call is returned when ordering matters.

empty() → bool

Return True if there are no matching calls.

take(n: int) → QueryIterator

Return first n results as a new QueryIterator (lazy).

skip(n: int) → QueryIterator

Skip first n results and return the rest as a new QueryIterator (lazy).

filter(predicate: Callable[[fleche.call.LazyCall], bool]) → QueryIterator

Return a new QueryIterator keeping only calls where predicate(call) is truthy (lazy).

sorted(key: str | Callable[[call.LazyCall], Any] | None = None, reverse: bool = False) → QueryIterator

Return a new QueryIterator with calls sorted by key.

Parameters:

• key – a callable taking a LazyCall, or a string argument name to sort by

• reverse – if True, sort in descending order

unique(key: str | Callable[[call.LazyCall], Any]) → QueryIterator

Return a new QueryIterator with duplicates removed, keeping the first per group (lazy).

Parameters:

key – a callable taking a LazyCall, or a string argument name to deduplicate by

groupby(key: str | Callable[[call.LazyCall], Any]) → dict[Any, QueryIterator]

Partition calls into a dict of QueryIterators keyed by group value.

Parameters:

key – a callable taking a LazyCall, or a string argument name to group by

_timestop_extremum(*, reverse: bool) → fleche.call.LazyCall

latest() → fleche.call.LazyCall

Return the call with the most recent timestop (requires Runtime metadata).

Raises:

IndexError – if there are no matching calls

oldest() → fleche.call.LazyCall

Return the call with the oldest timestop (requires Runtime metadata).

Raises:

IndexError – if there are no matching calls

evict() → None

Remove all matched calls from the cache.

table(arguments: Iterable[str] | str | Literal[True] = (), results=False) → pandas.DataFrame

Return a pandas DataFrame summarizing queried calls.

Arguments and results are elided.

The DataFrame index will be the lookup key (digest) of each call. Columns are:

• name: the function name

• module: the module name

• ‘result`: if results argument is True

• metadata fields are flattened and added as columns directly

If given argument names collide with any of the above columns, the are prefixed by ‘a_’. Only requested arguments are loaded from cache.

timestart and timestop columns (produced by the Runtime metadata) are automatically converted from UTC Unix timestamps (float seconds) to timezone-aware pandas.Timestamp objects in the local timezone.

Parameters:

• arguments – add the given arguments (of the queried calls) as columns to the table. Pass True to add all arguments, or a single string as a shortcut for a one-element tuple.

• results (bool) – if True, add results of queried calls to table

Returns:

table of all calls on cache

Return type:

pandas.DataFrame

results() → Iterator[Any]

Returns an iterator over the results of queried calls.