`sartoriuslib.errors`¶

Typed exception hierarchy and structured ErrorContext. See Troubleshooting for a field-guide cheat sheet and Design §12 for the full tree.

sartoriuslib.errors ¶

Typed exception hierarchy for :mod:sartoriuslib.

Every library exception inherits from :class:SartoriusError and carries a structured :class:ErrorContext. See design doc §12.

In addition to exceptions, the library emits :class:SartoriusCapabilityWarning (a :class:UserWarning subclass) when a command is attempted against a device whose priors do not match in non-strict mode (design doc §6.1).

ErrorContext `dataclass` ¶

ErrorContext(
    command_name=None,
    command_bytes=None,
    opcode=None,
    sbi_token=None,
    raw_response=None,
    protocol=None,
    port=None,
    model=None,
    family=None,
    sbn_address=None,
    elapsed_s=None,
    extra=_empty_extra(),
)

Structured context attached to every :class:SartoriusError.

Fields are best-effort — missing data is None rather than raising.

InvalidParameterIndexError ¶

InvalidParameterIndexError(message='', *, context=None)

Bases: SartoriusConfigurationError

Parameter-table index is out of range for this device.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

InvalidSbnError ¶

InvalidSbnError(message='', *, context=None)

Bases: SartoriusConfigurationError

SBN bus address is invalid.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusAutoprintActiveError ¶

SartoriusAutoprintActiveError(message='', *, context=None)

Bases: SartoriusProtocolError

SBI autoprint is active, so command/reply traffic is not reliable.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusCapabilityError ¶

SartoriusCapabilityError(message='', *, context=None)

Bases: SartoriusError

Command is not available on this device / firmware / family.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusCapabilityWarning ¶

Bases: UserWarning

Emitted when a command's family/capability priors do not match the device.

In non-strict mode (the default) the library attempts the command anyway and updates availability from the device's response. See design doc §6.1.

SartoriusCommandRejectedError ¶

SartoriusCommandRejectedError(message='', *, context=None)

Bases: SartoriusProtocolError

The device returned an xBPI subtype 0x01 / SBI refusal response.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusConfigurationError ¶

SartoriusConfigurationError(message='', *, context=None)

Bases: SartoriusError

Configuration-level error (bad args, wrong confirm flag, etc.).

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusConfirmationRequiredError ¶

SartoriusConfirmationRequiredError(
    message="", *, context=None
)

Bases: SartoriusConfigurationError

A PERSISTENT / DANGEROUS command was attempted without confirm=True.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusConnectionError ¶

SartoriusConnectionError(message='', *, context=None)

Bases: SartoriusTransportError

Could not open / lost the connection to the balance.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusError ¶

SartoriusError(message='', *, context=None)

Bases: Exception

Base class for every :mod:sartoriuslib exception.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusFirmwareError ¶

SartoriusFirmwareError(message='', *, context=None)

Bases: SartoriusCapabilityError

Command is outside the supported firmware window.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusFrameError ¶

SartoriusFrameError(message='', *, context=None)

Bases: SartoriusProtocolError

Bad checksum, bad length, malformed TLV, etc.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusIndexOutOfRangeError ¶

SartoriusIndexOutOfRangeError(message='', *, context=None)

Bases: SartoriusCapabilityError, SartoriusCommandRejectedError

Device returned xBPI err 0x10 (index out of range).

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusMissingArgsError ¶

SartoriusMissingArgsError(message='', *, context=None)

Bases: SartoriusCapabilityError, SartoriusCommandRejectedError

Device returned xBPI err 0x07 (invalid or missing args).

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusOperationNotApplicableError ¶

SartoriusOperationNotApplicableError(
    message="", *, context=None
)

Bases: SartoriusCapabilityError, SartoriusCommandRejectedError

Device returned xBPI err 0x06 (operation not applicable).

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusParseError ¶

SartoriusParseError(message='', *, context=None)

Bases: SartoriusProtocolError

Unknown xBPI subtype or unparseable SBI line.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusProtocolError ¶

SartoriusProtocolError(message='', *, context=None)

Bases: SartoriusError

Protocol-level error (framing, parsing, device refusal).

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusProtocolUnsupportedError ¶

SartoriusProtocolUnsupportedError(
    message="", *, context=None
)

Bases: SartoriusProtocolError

Command has no variant defined for the active protocol.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusSinkDependencyError ¶

SartoriusSinkDependencyError(message='', *, context=None)

Bases: SartoriusSinkError, SartoriusConfigurationError

A sink's optional backing library is not installed.

Raised when the user instantiates (or calls open() on) a sink whose extras have not been installed — e.g. ParquetSink without sartoriuslib[parquet] or PostgresSink without sartoriuslib[postgres]. The message names the exact extra to install so the remediation is copy-pasteable.

Multi-inherits :class:SartoriusConfigurationError because callers that already branch on configuration errors (missing extras being a configuration problem from their perspective) keep working without changes.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusSinkError ¶

SartoriusSinkError(message='', *, context=None)

Bases: SartoriusError

Base class for errors raised by sinks (CSV, JSONL, SQLite, Parquet, Postgres).

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusSinkSchemaError ¶

SartoriusSinkSchemaError(message='', *, context=None)

Bases: SartoriusSinkError

A batch's shape is incompatible with the sink's locked schema.

Raised when a sink has locked its schema on the first batch (or validated against an existing table) and a subsequent batch carries rows whose shape can't be reconciled — for example, a Postgres target table that's missing a required column.

Dropping unknown optional columns is handled by a per-sink WARN log and does not raise.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusSinkWriteError ¶

SartoriusSinkWriteError(message='', *, context=None)

Bases: SartoriusSinkError

The backing store rejected a write.

Wraps the underlying driver exception (sqlite3, asyncpg, pyarrow) so downstream error handlers don't need to import optional dependencies. The original exception is preserved via raise ... from original so tracebacks remain intact.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusTimeoutError ¶

SartoriusTimeoutError(message='', *, context=None)

Bases: SartoriusTransportError

A transport read or write timed out.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusTransportError ¶

SartoriusTransportError(message='', *, context=None)

Bases: SartoriusError

I/O-layer error from the serial transport.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusUnsupportedCommandError ¶

SartoriusUnsupportedCommandError(
    message="", *, context=None
)

Bases: SartoriusCapabilityError, SartoriusCommandRejectedError

Device returned xBPI err 0x04 (unsupported/unknown opcode).

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusValidationError ¶

SartoriusValidationError(message='', *, context=None)

Bases: SartoriusConfigurationError

Request validation failed before I/O.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

SartoriusValueOutOfRangeError ¶

SartoriusValueOutOfRangeError(message='', *, context=None)

Bases: SartoriusCapabilityError, SartoriusCommandRejectedError

Device returned xBPI err 0x03 (value out of range).

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

UnknownUnitError ¶

UnknownUnitError(message='', *, context=None)

Bases: SartoriusConfigurationError

The unit code is not recognised.

Source code in src/sartoriuslib/errors.py

def __init__(self, message: str = "", *, context: ErrorContext | None = None) -> None:
    super().__init__(message)
    self.context = context or ErrorContext()

sartoriuslib.errors¶