Error API

btpc.errors

Catch structured errors from parsing, creation, editing, and verification.

BencodeError

class BencodeError

Report malformed bencode syntax or an invalid canonical encoding.

BtpcError

class BtpcError(message: str, *, offset: int | None = None, field: str | None = None, path: Path | None = None, limit: str | None = None, actual: int | None = None, maximum: int | None = None)

Base class for stable BTPC error categories.

Inspect the optional attributes instead of parsing the human-readable message. Only attributes relevant to a particular failure are populated.

Attributes:

• offset: Encoded byte offset for syntax or canonicalization failures.
• field: Protocol field associated with a validation failure.
• path: Filesystem path associated with an I/O or safety failure.
• limit: Resource-limit name.
• actual: Observed resource value.
• maximum: Configured maximum resource value.

offset

field

path

limit

actual

maximum

CancelledError

class CancelledError

Report cooperative cancellation requested through a cancellation token.

MetainfoError

class MetainfoError

Report torrent fields that violate v1, v2, or hybrid protocol rules.

PathError

class PathError

Report filesystem I/O, unsafe path, traversal, or destination failures.

ResourceLimitError

class ResourceLimitError

Configured parser or ownership resource limit was exceeded.

raise_exceeded

raise_exceeded(limit: str, actual: int, maximum: int) -> Never

Raise a structured limit error matching the native diagnostic.

UnsupportedError

class UnsupportedError

Report a requested feature or policy that BTPC does not support.

VerificationError

class VerificationError

Report an operational failure that prevents payload verification.