RetrievalOutcome#

class scikitplot.mcp.RetrievalOutcome(hits=(), *, legs=None, status=None)[source]#

Ranked hits plus the story of how they were obtained.

Parameters:
hitsiterable, optional

The fused, ranked hits. Copied into this list.

legslist of LegRecord, optional

One entry per evidence path considered.

statusstr or None, optional

Normally left None so it is derived from legs and hits. Pass a value only for terminal outcomes the legs cannot express, such as CANCELLED.

Parameters:

Notes

User-focused. This is a real list of hits. len(outcome), for hit in outcome, outcome[0] and if outcome: all behave exactly as they did before. Read status when you need to know why the list is the length it is.

Developer-focused. Deriving status rather than accepting it is what makes the “EMPTY requires every leg to have run” rule enforceable. The derivation order mirrors scikitplot.corpus.RetrievalResponse._derive_status:

  1. every recorded leg FAILED -> FAILED

  2. any leg FAILED or DEGRADED -> DEGRADED

  3. all legs ran, zero hits -> EMPTY

  4. otherwise -> SUCCESS

With no legs recorded the outcome degrades to the historical behaviour (EMPTY when there are no hits, SUCCESS otherwise), so a retriever that has not yet been updated keeps its previous meaning.

Examples

>>> RetrievalOutcome([]).status
'empty'
>>> failed = LegRecord("dense", FAILED, error="index unavailable")
>>> RetrievalOutcome([], legs=[failed]).status
'failed'
>>> ok = LegRecord("lexical", EMPTY)
>>> RetrievalOutcome([], legs=[ok, failed]).status
'degraded'
append(object, /)#

Append object to the end of the list.

as_dict()[source]#

Return a JSON-safe mapping describing the outcome, without the hits.

Returns:
dict

Keys status and legs.

Return type:

dict[str, Any]

clear(/)#

Remove all items from list.

copy(/)#

Return a shallow copy of the list.

count(value, /)#

Return number of occurrences of value.

property degraded: bool#

True when at least one evidence path did not run cleanly.

Type:

bool

errors()[source]#

Return the explanations from every leg that did not run cleanly.

Returns:
list of str
Return type:

list[str]

extend(iterable, /)#

Extend list by appending elements from the iterable.

property failed: bool#

True when no evidence path produced a usable answer.

Type:

bool

index(value, start=0, stop=sys.maxsize, /)#

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)#

Insert object before index.

legs: list[LegRecord]#

!! processed by numpydoc !!

pop(index=-1, /)#

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)#

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse(/)#

Reverse IN PLACE.

sort(*, key=None, reverse=False)#

Sort the list in ascending order and return None.

The sort is in-place (i.e. the list itself is modified) and stable (i.e. the order of two equal elements is maintained).

If a key function is given, apply it once to each list item and sort them, ascending or descending, according to their function values.

The reverse flag can be set to sort in descending order.

status: str#

!! processed by numpydoc !!