Skip to content

returns

returns #

return_spec — the return annotation is the schema a result is stored and loaded with.

RESULT_STEM = 'result' module-attribute #

The result subtree per return position: result, or result0… for a tuple.

result_stems(returns) #

The workspace subtree per return position.

Source code in capturegraph-lib/capturegraph/recipes/calls/returns.py
def result_stems(returns: ReturnSpec) -> list[str]:
    """The workspace subtree per return position."""
    if isinstance(returns, tuple):
        return [f"{RESULT_STEM}{index}" for index in range(len(returns))]
    return [RESULT_STEM]

return_spec(func) #

The CGType return type(s) declared by func's annotation.

Raises:

Type Description
TypeError

If the return annotation is missing, unresolvable, or not CGType-typed.

Source code in capturegraph-lib/capturegraph/recipes/calls/returns.py
def return_spec(func: Callable[..., object]) -> ReturnSpec:
    """The ``CGType`` return type(s) declared by ``func``'s annotation.

    Raises:
        TypeError: If the return annotation is missing, unresolvable, or not
            ``CGType``-typed.
    """
    try:
        hints = get_type_hints(func)
    except NameError as error:
        raise TypeError(
            f"pure_function {func.__qualname__}: return annotation is unresolvable "
            f"({error}); it is required — it stores and loads the cached result."
        ) from error
    if "return" not in hints:
        raise TypeError(
            f"pure_function {func.__qualname__} needs a return annotation — it is "
            f"load-bearing (it stores and loads the cached result)."
        )
    hint = hints["return"]
    if get_origin(hint) is tuple:
        elements = get_args(hint)
        if not elements or not all(_is_cgtype(element) for element in elements):
            raise TypeError(
                f"pure_function {func.__qualname__}: a tuple return must spell out "
                f"CGType elements, e.g. tuple[cg.Image, cg.Number]; got {hint!r}."
            )
        return tuple(elements)
    if not _is_cgtype(hint):
        raise TypeError(
            f"pure_function {func.__qualname__}: return annotation must be a CGType "
            f"(or tuple of CGTypes), got {hint!r}."
        )
    return hint

return_types(returns) #

The declared return types, one per position.

Source code in capturegraph-lib/capturegraph/recipes/calls/returns.py
def return_types(returns: ReturnSpec) -> tuple[type[CGType], ...]:
    """The declared return types, one per position."""
    return returns if isinstance(returns, tuple) else (returns,)

returned_values(returns, result) #

The body's return as one value per declared position.

Raises:

Type Description
TypeError

If a tuple-returning body returned something else.

Source code in capturegraph-lib/capturegraph/recipes/calls/returns.py
def returned_values(returns: ReturnSpec, result: object) -> tuple[object, ...]:
    """The body's return as one value per declared position.

    Raises:
        TypeError: If a tuple-returning body returned something else.
    """
    if not isinstance(returns, tuple):
        return (result,)
    if not isinstance(result, tuple) or len(result) != len(returns):
        raise TypeError(f"expected a {len(returns)}-tuple matching the annotation, got {result!r}")
    return result