Verification API

btpc.verification

Verify payload files against v1 pieces and v2 Merkle roots.

MismatchKind

class MismatchKind

Stable payload verification mismatch category.

MISSING

WRONG_SIZE

EXTRA

UNSAFE_PATH

V1_HASH

V2_HASH

PayloadMismatch

class PayloadMismatch(kind: MismatchKind, path: Path, piece: int | None)

Describe one deterministic payload mismatch.

Attributes:

• kind: Stable mismatch category.
• path: Payload-relative filesystem path.
• piece: Zero-based v1 piece index when the mismatch is piece-specific.

kind

kind: MismatchKind

path

path: Path

piece

piece: int | None

PayloadVerificationReport

class PayloadVerificationReport(mismatches: tuple[PayloadMismatch, ...])

Collect deterministic mismatches from a completed verification.

Attributes:

• mismatches: Mismatches in deterministic path and piece order.

mismatches

mismatches: tuple[PayloadMismatch, ...]

is_valid

is_valid: bool

Return whether every enabled check passed.

verify

verify(metainfo: Metainfo, payload: str | PathLike[str], *, fail_fast: bool = False, extra_files: bool = False, progress: Callable[[int, int, int], None] | None = None, cancellation: CancellationToken | None = None) -> PayloadVerificationReport

Verify payload content against all hashes represented by metainfo.

payload points directly to a single-file payload or to the root directory of a multi-file torrent. v1 verification hashes the logical concatenated file stream; v2 verification checks each file’s Merkle root; hybrid torrents check both. Missing files, unsafe paths, and content mismatches are returned in the report. Operational I/O failures raise exceptions.

Relative roots use the current directory. Torrent paths must match actual directory entries exactly, including on case-insensitive filesystems, and must not cross symlinks. Verification keeps a bounded number of files open and checks saved file identity and state before and after hashing and before it reports successful verification. These checks do not provide an atomic filesystem snapshot. Imported v2 torrents can use BEP 52 piece lengths above the creation policy’s 16 MiB limit.

Args:

• metainfo: Parsed torrent describing the expected payload.
• payload: Payload file or root directory.
• fail_fast: Stop after the first mismatch when true.
• extra_files: Include files absent from the torrent as mismatches.
• progress: Optional callback receiving ``(completed_bytes, total_bytes, completed_pieces)`. Callback exceptions propagate unchanged.
• cancellation: Cooperative cancellation token.

Returns:

A report containing zero or more deterministic mismatches.

Raises:

• PathError: If an operational filesystem read fails.
• VerificationError: If verification cannot be completed under the selected policy.
• CancelledError: If cancellation is requested.
• Exception: Any exception raised by progress.

Examples:

>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> from btpc import CreateOptions, Metainfo, create_bytes, verify
>>> with TemporaryDirectory() as directory:
...     payload = Path(directory) / "hello.txt"
...     _ = payload.write_bytes(b"hello torrent\n")
...     created = create_bytes(
...         payload,
...         options=CreateOptions(creation_date=0, threads=1),
...     )
...     torrent = Metainfo.from_bytes(created.bytes)
...     assert verify(torrent, payload).is_valid