Exceptions and warnings

For you to use

satella.warnings.mark_temporarily_disabled(reason: str = '')

A decorator to mark a function unusable due to some forthcoming changes.

A call to the function will raise NotImplementedError

and a mention of this function in code will mark a function disabled for whatever reason.

Usage:

>>> @mark_temporarily_disabled('Due to analysis schema changes')
>>> def serialize_report(analysis):
>>>     ...

Warnings

class satella.warnings.ExperimentalWarning

This feature is experimental!

CustomException

This is the class you can base your exceptions off. It provides a reasonable __repr__ and __str__, eg.:

class MyException(CustomException):
    ...

assert str(MyException) == 'MyException()'

__repr__ will additionally prefix the exception class name with entire module path to it.

CodedCustomException

A CustomException with an additional field in constructor, namely the exception’s code, and a special property that it’s subclasses who define a class property code are considered instances of that class, if it’s code matches.

Example:

class BaseCodedError(CodedCustomException):
    def __init__(self, msg, code):
        super().__init__(msg, code)

class Code2Error(BaseCodedError):
    code = 2

assert isinstance(BaseCodedError('message', 2', Code2Error)

The exceptions have to be in a common hierarchy to check them via codes.

For example, the following is true:

::

class DifferentHierarchy(CodedCustomException):

pass

assert not isinstance(DifferentHierarchy(‘message’, 2), Code2Error)

In general, please do not construct direct exceptions from CodedCustomException, please do it via a hierarchy such as:

class GenericError(CodedCustomException):
    pass

class SpecificError(GenericError):
    code = 3

raise SpecificError('message')

Note that this won’t allow you to handle exceptions like that

try:
    raise BaseCodedError('message', 2')
except Code2Error:
    self.succeed()
else:
    self.fail()

As this is a Python limitation.

The CodedCustomException uses the following metaclass to accomplish it’s magic

class satella.exceptions.CodedCustomExceptionMetaclass

Metaclass implementing the isinstance check for coded custom exceptions

ImpossibleError

class satella.exceptions.ImpossibleError

For these cases where your execution flow goes some place, that should be impossible for it to reach.

This is a BaseException, since it should be propagated upwards as soon as possible!

Note that ImpossibleError inherits from BaseException instead of the standard Satella hierarchy. The thought is, since this is an anomalous exception, it should get to the top of the stack ASAP.

Satella-specific exceptions

BaseSatellaError

class satella.exceptions.BaseSatellaError(*args, **kwargs)

“Base class for all Satella exceptions

ResourceLockingError

class satella.exceptions.ResourceLockingError(*args, **kwargs)

Base class for resource locking issues

ResourceLocked

class satella.exceptions.ResourceLocked(*args, **kwargs)

Given resource has been already locked

ResourceNotLocked

class satella.exceptions.ResourceNotLocked(*args, **kwargs)

Locking given resource is needed in order to access it

WouldWaitMore

class satella.exceptions.WouldWaitMore(*args, **kwargs)

wait()’s timeout has expired

PreconditionError

class satella.exceptions.PreconditionError(*args, **kwargs)

A precondition was not met for the argument

ConfigurationError

class satella.exceptions.ConfigurationError(*args, **kwargs)

A generic error during configuration

ConfigurationSchemaError

class satella.exceptions.ConfigurationSchemaError(*args, **kwargs)

Schema mismatch to what was seen

ConfigurationMisconfiguredError

class satella.exceptions.ConfigurationMisconfiguredError(*args, **kwargs)

Configuration was improperly passed to Satella

ConfigurationValidationError

class satella.exceptions.ConfigurationValidationError(msg, value=None, **kwargs)

A validator failed

Empty

class satella.exceptions.Empty(*args, **kwargs)

The queue was empty

MetricAlreadyExists

class satella.exceptions.MetricAlreadyExists(msg, name, requested_type, existing_type)

Metric with given name already exists, but with a different type

AlreadyAllocated

class satella.exceptions.AlreadyAllocated(*args, **kwargs)

Given ID has been already marked as allocated

ProcessFailed

class satella.exceptions.ProcessFailed(rc: int, stdout_so_far: bytes | str)

A process finished with other result code than it was requested

Parameters:

• rc – return code of the process

• stdout_so_far – process’ stdout gathered so far

NotEnoughBytes

class satella.exceptions.NotEnoughBytes(*args, **kwargs)

Not enough bytes in the parser remain to satisfy this request