fleche.query

Attributes

logger

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

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

• cache – the cache that produced these calls; set by query() and propagated through chainable methods. Used by table() to call shrink without reaching into LazyCall._cache.

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

cache: BaseCache | None = None

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

transfer(target, pop: bool = False, overwrite: bool = False) → None

Replay matching calls into the target cache.

Parameters:

• target – destination BaseCache.

• pop – if True, evict transferred calls from the source cache.

• overwrite – if True, overwrite entries already present in the target. If False (default), conflicts are skipped.

table(arguments: Iterable[str] | str | Literal[True] = (), results=False, shrink_keys: bool = True) → 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

• shrink_keys (bool) – if True (default), shrink each lookup key in the index to its shortest unambiguous prefix via the owning cache’s shrink. Falls back to the full digest if shrinking raises AmbiguousDigestError. Set to False to keep full-length digests (cheaper on large caches).

Returns:

table of all calls on cache

Return type:

pandas.DataFrame

results() → Iterator[Any]

Returns an iterator over the results of queried calls.