Errors and warnings (tsbootstrap.errors)

Structured error and warning taxonomy.

Every failure mode carries a stable, machine-readable code (a TSB_* string) so callers and tooling can branch on what went wrong without parsing human messages. The message and an optional remediation hint are kept separate from the code. Codes are the public contract; messages are not.

Design rules:

• Raise a typed subclass so callers can except InputDataError.

• Pass a specific code=Codes.X at the raise site when the subclass covers several codes (e.g. shape vs non-finite both raise InputDataError).

• Warnings (recoverable, advisory) subclass TSBootstrapWarning.

class tsbootstrap.errors.Codes

Bases: object

Stable string codes for every error and warning tsbootstrap can emit.

Reference these constants in code rather than hard-coding the strings, and treat the string values themselves as the stable public API.

exception tsbootstrap.errors.TSBootstrapError(message: str, *, code: str | None = None, context: dict[str, Any] | None = None, hint: str | None = None)

Bases: Exception

Base class for all tsbootstrap errors.

Parameters:

• message (str) – Human-readable description.

• code (str, optional) – Machine-readable TSB_* code. Defaults to the raising subclass’s code class attribute.

• context (dict, optional) – Structured detail (e.g. {"block_length": 50, "n": 30}) for tooling.

• hint (str, optional) – Actionable remediation shown after the message.

exception tsbootstrap.errors.InputDataError(message: str, *, code: str | None = None, context: dict[str, Any] | None = None, hint: str | None = None)

Bases: TSBootstrapError

Invalid input array: bad shape, dtype, non-finite values, or too few observations.

exception tsbootstrap.errors.MethodConfigError(message: str, *, code: str | None = None, context: dict[str, Any] | None = None, hint: str | None = None)

Bases: TSBootstrapError

Invalid method specification or parameter (block length, order, unknown method).

exception tsbootstrap.errors.ModelStabilityError(message: str, *, code: str | None = None, context: dict[str, Any] | None = None, hint: str | None = None)

Bases: TSBootstrapError

Fitted model is unstable (unit-root or larger) or a simulated path diverged.

exception tsbootstrap.errors.BackendError(message: str, *, code: str | None = None, context: dict[str, Any] | None = None, hint: str | None = None)

Bases: TSBootstrapError

Model-fitting backend is unavailable or does not support the requested model.

exception tsbootstrap.errors.OOBUnavailableError(message: str, *, code: str | None = None, context: dict[str, Any] | None = None, hint: str | None = None)

Bases: TSBootstrapError

Out-of-bag / in-bag information is undefined for this method.

OOB masks are only meaningful for observation-resampling methods (IID, block). Recursive residual/model-based bootstraps generate fresh paths and have no observation-index provenance.

exception tsbootstrap.errors.RNGContractError(message: str, *, code: str | None = None, context: dict[str, Any] | None = None, hint: str | None = None)

Bases: TSBootstrapError

The deterministic RNG contract was violated.

exception tsbootstrap.errors.TSBootstrapWarning(message: str, *, code: str | None = None, context: dict[str, Any] | None = None)

Bases: UserWarning

Base class for advisory, recoverable warnings.

Carries the same code/context contract as TSBootstrapError.

exception tsbootstrap.errors.NearUnitRootWarning(message: str, *, code: str | None = None, context: dict[str, Any] | None = None)

Bases: TSBootstrapWarning

Fitted model has a root near the unit circle; recursive paths may be unreliable.

exception tsbootstrap.errors.DegenerateBlockBootstrapWarning(message: str, *, code: str | None = None, context: dict[str, Any] | None = None)

Bases: TSBootstrapWarning

Block length equals the series length, so every block is the whole series.