Errors

BigfootError

Bases: Exception

Base class for all bigfoot errors.

UnmockedInteractionError

UnmockedInteractionError(source_id, args, kwargs, hint)

Bases: BigfootError

Raised at call time: an interaction fired with no matching registered mock.

Message includes: source description, args/kwargs, copy-pasteable mock hint.

Source code in src/bigfoot/_errors.py

def __init__(
    self,
    source_id: str,
    args: tuple[Any, ...],
    kwargs: dict[str, Any],
    hint: str,
) -> None:
    self.source_id = source_id
    self.args_tuple = args
    self.kwargs = kwargs
    self.hint = hint
    super().__init__(
        f"Unexpected call: source_id={source_id!r}, "
        f"args={args!r}, kwargs={kwargs!r}\n\n{hint}"
    )

UnassertedInteractionsError

UnassertedInteractionsError(interactions, hint)

Bases: BigfootError

Raised at teardown: timeline contains interactions not matched by assert_interaction().

Message lists each unasserted interaction with copy-pasteable assert hint.

Source code in src/bigfoot/_errors.py

def __init__(self, interactions: list[Any], hint: str) -> None:
    self.interactions = interactions
    self.hint = hint
    super().__init__(f"{hint}")

UnusedMocksError

UnusedMocksError(mocks, hint)

Bases: BigfootError

Raised at teardown: registered mocks with required=True were never triggered.

Message lists each unused mock with hint to either remove or set required=False.

Source code in src/bigfoot/_errors.py

def __init__(self, mocks: list[Any], hint: str) -> None:
    self.mocks = mocks
    self.hint = hint
    super().__init__(f"{hint}")

VerificationError

VerificationError(unasserted, unused)

Bases: BigfootError

Raised at teardown when BOTH UnassertedInteractionsError and UnusedMocksError apply.

Contains both reports in separate sections.

Source code in src/bigfoot/_errors.py

def __init__(
    self,
    unasserted: UnassertedInteractionsError | None,
    unused: UnusedMocksError | None,
) -> None:
    self.unasserted = unasserted
    self.unused = unused

    parts: list[str] = []
    if unasserted is not None:
        parts.append(f"  [UnassertedInteractions] {unasserted}")
    if unused is not None:
        parts.append(f"  [UnusedMocks] {unused}")

    if parts:
        body = "\n".join(parts)
        message = f"VerificationError:\n{body}"
    else:
        message = "VerificationError: (no details)"

    super().__init__(message)

InteractionMismatchError

InteractionMismatchError(expected, actual, hint)

Bases: BigfootError

Raised by assert_interaction() when expected source/fields don't match the next interaction in the timeline.

Message includes: expected description, actual next interaction, remaining timeline.

Source code in src/bigfoot/_errors.py

def __init__(
    self,
    expected: object,
    actual: object,
    hint: str,
) -> None:
    self.expected = expected
    self.actual = actual
    self.hint = hint
    super().__init__(
        f"Expected={expected!r}, actual={actual!r}\n\n{hint}"
    )

MissingAssertionFieldsError

MissingAssertionFieldsError(missing_fields)

Bases: BigfootError

Raised by assert_interaction() when the caller omits one or more assertable fields from **expected.

Attributes: missing_fields: frozenset of field names that were required but absent.

Source code in src/bigfoot/_errors.py

def __init__(self, missing_fields: frozenset[str]) -> None:
    self.missing_fields = missing_fields
    fields_str = ", ".join(sorted(missing_fields))
    super().__init__(
        f"MissingAssertionFieldsError: the following assertable fields were not "
        f"included in the assertion: {fields_str}. "
        f"Include them in **expected or use a dirty-equals matcher (e.g., IsAnything()) "
        f"if the value is not the focus of this assertion."
    )

SandboxNotActiveError

SandboxNotActiveError(source_id)

Bases: BigfootError

Raised when an intercepted call fires but no sandbox is active.

Attributes: source_id: Identifier of the interceptor that fired without a sandbox.

Message includes hint: 'Did you forget bigfoot_verifier fixture or sandbox() CM?'

Source code in src/bigfoot/_errors.py

def __init__(self, source_id: str) -> None:
    self.source_id = source_id
    super().__init__(
        f"SandboxNotActiveError: source_id={source_id!r}, "
        "hint='Did you forget bigfoot_verifier fixture or sandbox() CM?'"
    )

ConflictError

ConflictError(target, patcher)

Bases: BigfootError

Raised at activate() time if target method is already patched by another library.

Message names the conflicting library and the patched target.

Source code in src/bigfoot/_errors.py

def __init__(self, target: str, patcher: str) -> None:
    self.target = target
    self.patcher = patcher
    super().__init__(f"ConflictError: target={target!r}, patcher={patcher!r}")