FunctionContext

The FunctionContext captures the arguments of a function. It can be created using the capsula.FunctionContext.builder method or the capsula.FunctionContext.__init__ method.

capsula.FunctionContext.builder classmethod

builder(
    *, ignore: Container[str] = ()
) -> Callable[[CapsuleParams], FunctionContext]

PARAMETER	DESCRIPTION
ignore	Parameters to ignore when capturing the arguments. This is useful when you pass values that you don't want to be in the output, such as a large data structure or a function that is not serializable, or a secret. TYPE: Container[str] DEFAULT: ()

Source code in capsula/_context/_function.py

@classmethod
def builder(
    cls,
    *,
    ignore: Annotated[
        Container[str],
        Doc(
            "Parameters to ignore when capturing the arguments. "
            "This is useful when you pass values that you don't want to be in the output, "
            "such as a large data structure or a function that is not serializable, or a secret.",
        ),
    ] = (),
) -> Callable[[CapsuleParams], FunctionContext]:
    def build(params: CapsuleParams) -> FunctionContext:
        if not isinstance(params.exec_info, FuncInfo):
            msg = "FunctionContext can only be built from a FuncInfo."
            raise TypeError(msg)

        return cls(
            params.exec_info.func,
            args=params.exec_info.args,
            kwargs=params.exec_info.kwargs,
            ignore=ignore,
            _remove_pre_run_capsule_before_binding=params.exec_info.pass_pre_run_capsule,
        )

    return build

capsula.FunctionContext.__init__

__init__(
    function: Callable[..., Any],
    *,
    args: Sequence[Any],
    kwargs: Mapping[str, Any],
    ignore: Container[str] = (),
    _remove_pre_run_capsule_before_binding: bool = False
)

PARAMETER	DESCRIPTION
function	TYPE: Callable[..., Any]
args	TYPE: Sequence[Any]
kwargs	TYPE: Mapping[str, Any]
ignore	TYPE: Container[str] DEFAULT: ()
_remove_pre_run_capsule_before_binding	TYPE: bool DEFAULT: False

Source code in capsula/_context/_function.py

def __init__(
    self,
    function: Callable[..., Any],
    *,
    args: Sequence[Any],
    kwargs: Mapping[str, Any],
    ignore: Container[str] = (),
    _remove_pre_run_capsule_before_binding: bool = False,
) -> None:
    self._function = function
    self._args = args
    self._kwargs = kwargs
    self._ignore = ignore
    self._remove_pre_run_capsule_before_binding = _remove_pre_run_capsule_before_binding

Configuration example

Via capsula.toml

Warning

Configuring the FunctionContext via capsula.toml is not recommended because capsula enc will fail as there is no target function to capture.

[pre-run]
contexts = [
  { type = "FunctionContext" },
]

Via @capsula.context decorator

import capsula

@capsula.run()
@capsula.context(capsula.FunctionContext.builder(), mode="pre")
def func(arg1, arg2): ...

Output example

The following is an example of the output of the FunctionContext, reported by the JsonDumpReporter:

"function": {
  "calculate_pi": {
    "file_path": "examples/simple_decorator.py",
    "first_line_no": 6,
    "bound_args": {
      "n_samples": 1000,
      "seed": 42
    }
  }
}