fleche.query
============

.. py:module:: fleche.query


Classes
-------

.. autoapisummary::

   fleche.query.QueryIterator


Module Contents
---------------

.. py:class:: QueryIterator

   Bases: :py:obj:`Iterable`\ [\ :py:obj:`fleche.call.LazyCall`\ ]


   Iterator that adds some convenience to plain iterators over calls of query result.

   :param calls: (iterable of call.LazyCall): underlying results of the query


   .. py:attribute:: calls
      :type:  Iterable[fleche.call.LazyCall]


   .. py:method:: __iter__() -> Iterator[fleche.call.LazyCall]


   .. py:method:: only() -> fleche.call.LazyCall

      Return the single matching call.

      :raises IndexError: if there are no matching calls
      :raises ValueError: if there is more than one matching call



   .. py:method:: count() -> int

      Return the total number of matching calls.



   .. py:method:: 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.



   .. py:method:: empty() -> bool

      Return True if there are no matching calls.



   .. py:method:: take(n: int) -> QueryIterator

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



   .. py:method:: skip(n: int) -> QueryIterator

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



   .. py:method:: filter(predicate: Callable[[fleche.call.LazyCall], bool]) -> QueryIterator

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



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

      Return a new QueryIterator with calls sorted by key.

      :param key: a callable taking a LazyCall, or a string argument name to sort by
      :param reverse: if True, sort in descending order



   .. py:method:: unique(key: str | Callable[[call.LazyCall], Any]) -> QueryIterator

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

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



   .. py:method:: groupby(key: str | Callable[[call.LazyCall], Any]) -> dict[Any, QueryIterator]

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

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



   .. py:method:: latest() -> fleche.call.LazyCall

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

      :raises IndexError: if there are no matching calls



   .. py:method:: oldest() -> fleche.call.LazyCall

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

      :raises IndexError: if there are no matching calls



   .. py:method:: evict() -> None

      Remove all matched calls from the cache.



   .. py:method:: 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 :class:`~fleche.metadata.Runtime`
      metadata) are automatically converted from UTC Unix timestamps (float seconds) to
      timezone-aware :class:`pandas.Timestamp` objects in the local timezone.

      :param 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.
      :param results: if True, add results of queried calls to table
      :type results: bool

      :returns: table of all calls on cache
      :rtype: :class:`pandas.DataFrame`



   .. py:method:: results() -> Iterator[Any]

      Returns an iterator over the results of queried calls.