error

compression_safeguards.utils.error

Exception and warning types and helpers to raise exceptions with context.

Exceptions raised in this package carry ErrorContext, which can be accessed through the ErrorContextMixin.

Classes:

Functions:

  • lookup_enum_or_raise –

    Look up and return the enum member with the given name or raise an error, with context.

Ei module-attribute 

Ei = TypeVar('Ei', bound=Enum)

Any enum type (invariant).

Returned by: Used by:

ContextLayer

Bases: ABC

flowchart LR compression_safeguards.utils.error.ContextLayer[ContextLayer] click compression_safeguards.utils.error.ContextLayer href "" "compression_safeguards.utils.error.ContextLayer"

Context layer abstract base class.

separator property 

separator: str

Separator to print before this layer, '.' by default.

ErrorContext 

ErrorContext(*context: ContextLayer)

Context in which an error was raised.

The context can be added to an exception using the err | ErrorContext(...) syntax.

Parameters:
  • *context (ContextLayer, default: () ) –

    The layers of the context.

layers property 

layers: tuple[ContextLayer, ...]

The layers of the context, from outermost to innermost.

ctx

Singleton error context type with which additional context scopes can be entered.

An exception can be prepared for receiving context using the err | ctx syntax.

Methods:

  • layer –

    Context manager that adds one layer of context to any exception that

  • safeguard –

    Context manager that adds one layer of context, the type of a

  • safeguardty –

    Context manager that adds one layer of context, the safeguard type,

  • parameter –

    Context manager that adds one layer of context, the name of a

  • late_bound_parameter –

    Context manager that adds one layer of context, the name of a

  • index –

    Context manager that adds one layer of context, an index, to any

layer staticmethod 

layer(layer: ContextLayer)

Context manager that adds one layer of context to any exception that is raised within.

Parameters:

safeguard staticmethod 

safeguard(
    safeguard: Safeguard,
) -> AbstractContextManager[None]

Context manager that adds one layer of context, the type of a safeguard, to any exception that is raised within.

The added context layer will be a SafeguardTypeContextLayer.

Parameters:
  • safeguard (Safeguard) –

    A safeguard whose type to add as a layer of context.

safeguardty staticmethod 

safeguardty(
    safeguard: type[Safeguard],
) -> AbstractContextManager[None]

Context manager that adds one layer of context, the safeguard type, to any exception that is raised within.

The added context layer will be a SafeguardTypeContextLayer.

Parameters:
  • safeguard (type[Safeguard]) –

    The type of a safeguard to add as a layer of context.

parameter staticmethod 

parameter(name: str) -> AbstractContextManager[None]

Context manager that adds one layer of context, the name of a parameter, to any exception that is raised within.

The added context layer will be a ParameterContextLayer.

Parameters:
  • name (str) –

    The name of a parameter to add as a layer of context.

late_bound_parameter staticmethod 

late_bound_parameter(
    name: Parameter,
) -> AbstractContextManager[None]

Context manager that adds one layer of context, the name of a late-bound parameter, to any exception that is raised within.

The added context layer will be a LateBoundParameterContextLayer.

Parameters:
  • name (Parameter) –

    The name of a late-bound parameter to add as a layer of context.

index staticmethod 

index(index: int) -> AbstractContextManager[None]

Context manager that adds one layer of context, an index, to any exception that is raised within.

The added context layer will be an IndexContextLayer.

Parameters:
  • index (int) –

    An index to add as a layer of context.

ErrorContextMixin

Mixin for exceptions that have ErrorContext.

The context can be accessed after checking isinstance(err, ErrorContextMixin).

context property 

context: ErrorContext

The context in which this exception was raised.

SafeguardTypeContextLayer 

SafeguardTypeContextLayer(safeguard: type[Safeguard])

Bases: ContextLayer

flowchart LR compression_safeguards.utils.error.SafeguardTypeContextLayer[SafeguardTypeContextLayer] compression_safeguards.utils.error.ContextLayer[ContextLayer] compression_safeguards.utils.error.ContextLayer --> compression_safeguards.utils.error.SafeguardTypeContextLayer click compression_safeguards.utils.error.SafeguardTypeContextLayer href "" "compression_safeguards.utils.error.SafeguardTypeContextLayer" click compression_safeguards.utils.error.ContextLayer href "" "compression_safeguards.utils.error.ContextLayer"

Safeguard type context layer.

Parameters:

safeguard property 

safeguard: type[Safeguard]

The safeguard type.

ParameterContextLayer 

ParameterContextLayer(parameter: str)

Bases: ContextLayer

flowchart LR compression_safeguards.utils.error.ParameterContextLayer[ParameterContextLayer] compression_safeguards.utils.error.ContextLayer[ContextLayer] compression_safeguards.utils.error.ContextLayer --> compression_safeguards.utils.error.ParameterContextLayer click compression_safeguards.utils.error.ParameterContextLayer href "" "compression_safeguards.utils.error.ParameterContextLayer" click compression_safeguards.utils.error.ContextLayer href "" "compression_safeguards.utils.error.ContextLayer"

Parameter context layer.

Parameters:
  • parameter (str) –

    The name of the parameter.

parameter property 

parameter: str

The name of the parameter.

LateBoundParameterContextLayer 

LateBoundParameterContextLayer(parameter: Parameter)

Bases: ContextLayer

flowchart LR compression_safeguards.utils.error.LateBoundParameterContextLayer[LateBoundParameterContextLayer] compression_safeguards.utils.error.ContextLayer[ContextLayer] compression_safeguards.utils.error.ContextLayer --> compression_safeguards.utils.error.LateBoundParameterContextLayer click compression_safeguards.utils.error.LateBoundParameterContextLayer href "" "compression_safeguards.utils.error.LateBoundParameterContextLayer" click compression_safeguards.utils.error.ContextLayer href "" "compression_safeguards.utils.error.ContextLayer"

Late-bound parameter context layer.

Parameters:
  • parameter (Parameter) –

    The late-bound parameter.

parameter property 

parameter: Parameter

The late-bound parameter.

separator property 

separator: str

'=' separator to print before this layer.

IndexContextLayer 

IndexContextLayer(index: int)

Bases: ContextLayer

flowchart LR compression_safeguards.utils.error.IndexContextLayer[IndexContextLayer] compression_safeguards.utils.error.ContextLayer[ContextLayer] compression_safeguards.utils.error.ContextLayer --> compression_safeguards.utils.error.IndexContextLayer click compression_safeguards.utils.error.IndexContextLayer href "" "compression_safeguards.utils.error.IndexContextLayer" click compression_safeguards.utils.error.ContextLayer href "" "compression_safeguards.utils.error.ContextLayer"

Index context layer.

Parameters:
  • index (int) –

    The index.

index property 

index: int

The index.

separator property 

separator: str

Empty "" separator to print before this layer.

TypeCheckError 

TypeCheckError(expected: type | UnionType, found: object)

Bases: TypeError

flowchart LR compression_safeguards.utils.error.TypeCheckError[TypeCheckError] click compression_safeguards.utils.error.TypeCheckError href "" "compression_safeguards.utils.error.TypeCheckError"

TypeError that is raised when a value fails a type check.

Parameters:
  • expected (type | UnionType) –

    The expected type or type union.

  • found (object) –

    The value that failed the type check.

Methods:

check_instance_or_raise classmethod 

check_instance_or_raise(
    obj: object, expected: type | UnionType
) -> None | Never

Check isinstance(obj, expected) or raise a type check error, with context.

Parameters:
  • obj (object) –

    The value to type check.

  • expected (type | UnionType) –

    The expected type or type union.
Raises:

expected property 

expected: type | UnionType

The expected type or type union.

found property 

found: object

The value that failed the type check.

TypeSetError 

TypeSetError(expected: type | UnionType, found: type)

Bases: TypeError

flowchart LR compression_safeguards.utils.error.TypeSetError[TypeSetError] click compression_safeguards.utils.error.TypeSetError href "" "compression_safeguards.utils.error.TypeSetError"

TypeError that is raised when a type is not in a type set.

Parameters:
  • expected (type | UnionType) –

    The expected type or type union.

  • found (type) –

    The type that failed the type set check.

Methods:

  • check_or_raise –

    Check issubclass(ty, expected) or raise a type set error, with

  • check_dtype_or_raise –

    Check if dtype is in the set of supported data types or raise a

check_or_raise classmethod 

check_or_raise(
    ty: type, expected: type | UnionType
) -> None | Never

Check issubclass(ty, expected) or raise a type set error, with context.

Parameters:
  • ty (type) –

    The type to check.

  • expected (type | UnionType) –

    The expected type or type union.
Raises:

check_dtype_or_raise classmethod 

check_dtype_or_raise(
    dtype: dtype, supported: Set[dtype]
) -> None | Never

Check if dtype is in the set of supported data types or raise a type set error, with context.

Parameters:
  • dtype (dtype) –

    The data type to check.

  • supported (Set[dtype]) –

    The set of supported data types.
Raises:

expected property 

expected: type | UnionType

The expected type or type union.

found property 

found: type

The type that failed the type set check.

LateBoundParameterResolutionError 

LateBoundParameterResolutionError(
    expected: Set[Parameter], provided: Set[Parameter]
)

Bases: KeyError

flowchart LR compression_safeguards.utils.error.LateBoundParameterResolutionError[LateBoundParameterResolutionError] click compression_safeguards.utils.error.LateBoundParameterResolutionError href "" "compression_safeguards.utils.error.LateBoundParameterResolutionError"

KeyError that is raised when late-bound parameter resolution fails because one or more parameters are missing or extraneous.

Parameters:
  • expected (Set[Parameter]) –

    The set of expected late-bound parameters.

  • provided (Set[Parameter]) –

    The type that failed the type set check.

Methods:

  • check_or_raise –

    Check if the expected set of late-bound parameters matches the

check_or_raise staticmethod 

check_or_raise(
    expected: Set[Parameter], provided: Set[Parameter]
) -> None | Never

Check if the expected set of late-bound parameters matches the provided set or raise a late-bound parameter resolution error, with context.

Parameters:
  • expected (Set[Parameter]) –

    The expected set of late-bound parameters.

  • provided (Set[Parameter]) –

    The provided set of late-bound parameters.
Raises:

expected property 

expected: Set[Parameter]

The expected set of late-bound parameters.

provided property 

provided: Set[Parameter]

The provided set of late-bound parameters.

missing property 

missing: Set[Parameter]

The missing (expected but not provided) set of late-bound parameters.

extraneous property 

extraneous: Set[Parameter]

The extraneous (provided but not expected) set of late-bound parameters.

SafeguardsSafetyBug 

SafeguardsSafetyBug(message: str)

Bases: RuntimeError

flowchart LR compression_safeguards.utils.error.SafeguardsSafetyBug[SafeguardsSafetyBug] click compression_safeguards.utils.error.SafeguardsSafetyBug href "" "compression_safeguards.utils.error.SafeguardsSafetyBug"

RuntimeError that is raised when a fatal safety bug occurs.

A fatal safety bug occurs when the safeguards are unable to provide the requested safety requirement.

By raising this error, the compression-safeguards avoid violating the safety requirements.

When this error is raised, it is a fatal bug in the implementation of the compression-safeguards, which should be reported at https://github.com/juntyr/compression-safeguards/issues.

Parameters:
  • message (str) –

    The error message.

QuantityOfInterestRuntimeWarning 

QuantityOfInterestRuntimeWarning(message: str)

Bases: RuntimeWarning

flowchart LR compression_safeguards.utils.error.QuantityOfInterestRuntimeWarning[QuantityOfInterestRuntimeWarning] click compression_safeguards.utils.error.QuantityOfInterestRuntimeWarning href "" "compression_safeguards.utils.error.QuantityOfInterestRuntimeWarning"

RuntimeWarning that is raised when a recoverable quantity of interest sanity check fails.

A quantity of interest safeguard raises this warning if it fails at providing the requested safety requirement using regular means but is still able to recover and uphold the requirement in the end.

When this warning is raised, it is a non-fatal bug in the implementation of the compression-safeguards, which should be reported at https://github.com/juntyr/compression-safeguards/issues.

Parameters:
  • message (str) –

    The warning message.

lookup_enum_or_raise 

lookup_enum_or_raise(
    enum: type[Ei],
    name: str,
    error: type[Exception] = ValueError,
) -> Ei | Never

Look up and return the enum member with the given name or raise an error, with context.

Parameters:
  • enum (type[Ei]) –

    The enum in which the name is looked up.

  • name (str) –

    The enum member name to look up.

  • error (type[Exception], default: ValueError ) –

    The type of error that is raised if the name is not a member of the enum.
Returns:
  • member( Ei ) –

    The enum member with the given name.
Raises:
  • error –

    if the name is not a member of the enum.