binobj.errors module

Errors for the binobj package.

exception ArraySizeError(*, field: Field[Any], n_expected: int, n_given: int | None = None)

Bases: SerializationError

The array can’t be serialized because there are too many or too few items.

Parameters:

  • field (Field) – The field that failed to be serialized.

  • n_expected (int) – The expected number of items in the field.

  • n_given (int) – Optional. The actual number of items given to the field for serialization.

exception ConfigurationError(message: str | None = None, *, field: str | Field[Any] | None = None, struct: str | Struct | Type[Struct] | None = None, obj: Any = None)

Bases: Error

A field, struct, or other object was misconfigured.

At least one of the field, struct, or obj keyword arguments must be passed to the constructor.

Parameters:

  • message (str) – Optional. A description of what’s wrong. If not given, a generic error message will be chosen depending on which of the field, struct, or obj keyword arguments is passed.

  • field – The misconfigured Field or its name.

  • struct – The misconfigured Struct or its name.

  • obj – If the misconfigured object is neither a field nor a struct, pass it or its name here.

Raises:

ValueError – None of the field, struct, or obj keyword arguments were passed.

New in version 0.3.0: The struct and obj arguments.

exception DeserializationError(message: str | None = None, *, field: Field[Any] | None = None, data: bytes | None = None, offset: int | None = None)

Bases: Error

An error occurred while deserializing data.

Parameters:

  • message (str) – An error message explaining the problem.

  • field (Field) – The field that failed to load.

  • data (bytes) – The raw data that was read that led to the crash.

  • offset (int) – The offset into the data stream where the crash occurred.

exception Error(message: str | None = None, *args: Any)

Bases: Exception

Base class for all binobj errors.

Do not throw this exception directly.

exception ExtraneousDataError(message: str | None = None, *, field: Field[Any] | None = None, data: bytes | None = None, offset: int | None = None)

Bases: DeserializationError

Extra bytes were found at the end of the input after deserialization.

exception FieldRedefinedError(*, struct: str, field: str | Field[Any])

Bases: ConfigurationError

A struct has a field already defined in a parent class.

Parameters:

  • struct (str) – The name of the struct that has the redefined field.

  • field – The Field that’s been redefined, or its name.

New in version 0.3.0.

exception FieldReferenceError(message: str | None = None, *, field: str)

Bases: Error

An error occurred while computing a field reference.

Parameters:

  • message (str) – Optional. A more detailed error message, if desired.

  • field (str) – The name of the field that failed to be referenced.

exception IllegalOperationError(message: str | None = None, *args: Any)

Bases: Error

The attempted operation is disallowed.

New in version 0.4.1.

exception ImmutableFieldError(*, field: Field[Any] | None = None)

Bases: IllegalOperationError

Cannot assign to an immutable or computed field.

Parameters:

field (Field) – The field an attempt was made to be assigned to.

New in version 0.4.1.

New in version 0.6.1: The field argument.

exception MissingRequiredValueError(*, field: str | Field[Any])

Bases: SerializationError

No value was passed for a required field.

Parameters:

field – The missing field, or its name.

exception MultipleInheritanceError(message: str | None = None, *, field: str | Field[Any] | None = None, struct: str | Struct | Type[Struct] | None = None, obj: Any = None)

Bases: ConfigurationError

A Struct can’t inherit from more than one Struct.

This restriction is in place because the field ordering could be non-intuitive given Python’s MRO.

New in version 0.3.0.

exception SerializationError(message: str | None = None, *, struct: Struct | None = None, field: str | Field[Any] | None = None, value: T | None = None)

Bases: Error

An error occurred while serializing data.

Parameters:

  • message (str) – An error message explaining the problem.

  • struct (Struct) – The struct that contains the field that failed to be serialized.

  • field (Field) – The field that failed to be serialized.

  • value – The value that caused the crash.

exception UndefinedSizeError(*, field: str | Field[Any])

Bases: ConfigurationError

The size of the field couldn’t be determined, possibly due to misconfiguration.

Parameters:

field – The Field that’s missing its size, or the name of that field.

New in version 0.3.1.

exception UnexpectedEOFError(*, field: Field[Any] | None, size: int, offset: int)

Bases: DeserializationError

Hit EOF while reading, but expected more data.

Parameters:

  • field (Field) – The field that failed to be deserialized.

  • size (int) – The number of bytes that were attempted to be read.

  • offset (int) – The offset into the input stream/string where the error was encountered, in bytes.

exception UnexpectedValueError(*, struct: Struct, name: str | Iterable[str])

Bases: SerializationError

The data to dump has unexpected fields.

Parameters:

  • struct (Struct) – The struct performing the serialization.

  • name – Either a string or an iterable of strings, each being the name of a field that was unexpected. Don’t pass Field instances.

exception UnserializableValueError(*, field: Field[T], value: T | None, reason: str | None = None)

Bases: SerializationError

The value couldn’t be serialized.

Parameters:

  • field (Field) – The field that failed to serialize the given value.

  • value – The value that can’t be serialized.

  • reason (str) – Optional. The reason for the failure.

exception ValidationError(message: str | None = None, *, field: Field[T], value: T | None)

Bases: Error

Validation failed for one or more fields.

Parameters:

  • message (str) – An error message explaining the problem.

  • field (Field) – The field that failed validation.

  • value – The invalid value.

exception ValueSizeError(*, field: Field[Any], value: Any)

Bases: UnserializableValueError

The value can’t be serialized because it doesn’t fit into the field.

Parameters:

  • field (Field) – The field that failed to serialize the given value.

  • value – The value that’s the wrong size.