Module adcp.reporting.ledger.row_encoding

Canonical JSONL row encoding for reporting revisions.

This is the Python half of the shared SDK persistence contract reporting-row-storage v1 (adcontextprotocol/adcp#7996, section 3.1). The JavaScript SDK implements the same contract; both must produce byte-identical chunks, manifests and digests for the same rows, which the shared golden fixture tests/fixtures/reporting-row-storage-v1.json pins.

Rows are stored as JCS(row) + "\n" in ordinal order, where JCS is RFC 8785. JCS escapes newline characters inside strings, so the 0x0A byte only ever separates rows. Rows are grouped into segments (the unit of verification and of paged reads) and chunks (the unit of storage). The boundaries are fixed by the contract:

  • a new chunk starts when the current chunk holds :data:REPORTING_ROW_CHUNK_MAX_ROWS rows, or when appending the next row would exceed :data:REPORTING_ROW_CHUNK_MAX_BYTES canonical bytes;
  • segments restart at each chunk boundary and close every :data:REPORTING_ROW_SEGMENT_MAX_ROWS rows.

A row larger than the chunk byte limit forms its own segment and chunk. Digests always cover the uncompressed canonical bytes.

Readers verify bytes. Nothing here re-serializes a stored row to check it, so verification never depends on number parsing or timestamp formatting.

Global variables

var REPORTING_ROW_FORMAT_V1

Stored row format and canonicalization algorithm, as AdCP names them (reporting-file-manifest.json format, reporting-canonicalization-contract.json algorithm). Neither is an input to any digest: segment, chunk and manifest digests cover chunk bytes and manifest fields, and revision_content_sha256 covers the envelope and rows. adcp_jcs_rows_v1 names the per-row RFC 8785 canonicalization; a revision's content_sha256 is still the envelope digest, not AdCP's array-shaped content digest.

Functions

def assert_reporting_revision_envelope_v1(*,
reporting_revision_id: str,
row_count: int,
control_totals: Sequence[Any],
chunks: Iterable[bytes],
sha256: str,
byte_count: int | None = None) ‑> None
Expand source code
def assert_reporting_revision_envelope_v1(
    *,
    reporting_revision_id: str,
    row_count: int,
    control_totals: Sequence[Any],
    chunks: Iterable[bytes],
    sha256: str,
    byte_count: int | None = None,
) -> None:
    """Raise unless the canonical chunks reproduce the committed revision binding."""
    actual = reporting_revision_envelope_digest_v1(
        reporting_revision_id=reporting_revision_id,
        row_count=row_count,
        control_totals=control_totals,
        chunks=chunks,
    )
    if actual.sha256 != sha256.lower() or (
        byte_count is not None and actual.byte_count != byte_count
    ):
        raise ReportingRowEncodingError(
            "ENVELOPE_INTEGRITY_FAILED", "revision content binding mismatch"
        )

Raise unless the canonical chunks reproduce the committed revision binding.

def canonical_reporting_row_v1(row: object, ordinal: int = 0) ‑> bytes
Expand source code
def canonical_reporting_row_v1(row: object, ordinal: int = 0) -> bytes:
    """Canonicalize one row for storage, without the trailing newline.

    Refuses values whose canonical bytes are not portable across conforming JCS
    implementations: non-objects, non-finite numbers, integers outside
    +-(2^53 - 1) (they must be strings in the row schema), and lone surrogates.
    ``-0`` serializes as ``0`` per RFC 8785; that is not a refusal.
    """
    if not isinstance(row, dict):
        raise ReportingRowEncodingError("INVALID_ROW", f"row {ordinal} is not a JSON object")
    try:
        _assert_portable_numbers(row, ordinal)
        return rfc8785.dumps(row)
    except ReportingRowEncodingError:
        raise
    except (rfc8785.CanonicalizationError, ValueError, TypeError, RecursionError) as error:
        raise ReportingRowEncodingError(
            "INVALID_ROW", f"row {ordinal} is not canonical JSON: {type(error).__name__}"
        ) from None

Canonicalize one row for storage, without the trailing newline.

Refuses values whose canonical bytes are not portable across conforming JCS implementations: non-objects, non-finite numbers, integers outside +-(2^53 - 1) (they must be strings in the row schema), and lone surrogates. -0 serializes as 0 per RFC 8785; that is not a refusal.

def create_reporting_revision_envelope_hasher_v1(*, reporting_revision_id: str, row_count: int, control_totals: Sequence[Any]) ‑> ReportingRevisionEnvelopeHasherV1
Expand source code
def create_reporting_revision_envelope_hasher_v1(
    *, reporting_revision_id: str, row_count: int, control_totals: Sequence[Any]
) -> ReportingRevisionEnvelopeHasherV1:
    """Streaming hasher for the protocol revision binding.

    ``sha256(JCS({reporting_revision_id, row_count, control_totals, reporting_rows}))``.
    JCS orders those keys as ``control_totals``, ``reporting_revision_id``,
    ``reporting_rows``, ``row_count``, so the preimage is the fixed prefix, the
    rows joined by commas, and the fixed suffix. Feed verified chunk bytes in
    order.
    """
    prefix = (
        b'{"control_totals":'
        + rfc8785.dumps(list(control_totals))
        + b',"reporting_revision_id":'
        + rfc8785.dumps(reporting_revision_id)
        + b',"reporting_rows":['
    )
    suffix = b'],"row_count":' + rfc8785.dumps(row_count) + b"}"
    return _JoinedRowsHasher(prefix, suffix, row_count)

Streaming hasher for the protocol revision binding.

sha256(JCS({reporting_revision_id, row_count, control_totals, reporting_rows})). JCS orders those keys as control_totals, reporting_revision_id, reporting_rows, row_count, so the preimage is the fixed prefix, the rows joined by commas, and the fixed suffix. Feed verified chunk bytes in order.

def create_reporting_rows_only_hasher_v1(row_count: int) ‑> ReportingRevisionEnvelopeHasherV1
Expand source code
def create_reporting_rows_only_hasher_v1(row_count: int) -> ReportingRevisionEnvelopeHasherV1:
    """Streaming hasher for digest profile ``rows_v1``: ``sha256(JCS(rows))``."""
    return _JoinedRowsHasher(b"[", b"]", row_count)

Streaming hasher for digest profile rows_v1: sha256(JCS(rows)).

def decode_verified_reporting_row_segments_v1(manifest: ReportingRowChunkManifestV1,
segment_range: tuple[int, int],
data: bytes) ‑> list[dict[str, typing.Any]]
Expand source code
def decode_verified_reporting_row_segments_v1(
    manifest: ReportingRowChunkManifestV1,
    segment_range: tuple[int, int],
    data: bytes,
) -> list[dict[str, Any]]:
    """Verify and decode the inclusive segment range ``[from, to]``.

    ``data`` must hold exactly those segments' canonical bytes, starting at the
    first segment's ``byte_offset``; that is the shape a ranged object read
    returns. Rows are released only after every segment verifies.
    """
    first, last = segment_range
    if first < 0 or last < first or last >= len(manifest.segments):
        raise ReportingRowEncodingError("MANIFEST_MISMATCH", "segment range is outside the chunk")
    buffer = memoryview(data)
    base = manifest.segments[first].byte_offset
    end = manifest.segments[last].byte_offset + manifest.segments[last].byte_count
    if len(buffer) != end - base:
        raise ReportingRowEncodingError(
            "CHUNK_INTEGRITY_FAILED", "segment range byte length mismatch"
        )
    for index in range(first, last + 1):
        segment = manifest.segments[index]
        start = segment.byte_offset - base
        _verify_segment(manifest, index, buffer[start : start + segment.byte_count])
    rows: list[dict[str, Any]] = []
    for line in _split_lines(bytes(buffer)):
        try:
            parsed = json.loads(line)
        except ValueError:
            raise ReportingRowEncodingError(
                "CHUNK_INTEGRITY_FAILED", "a verified row is not valid JSON"
            ) from None
        if not isinstance(parsed, dict):
            raise ReportingRowEncodingError(
                "CHUNK_INTEGRITY_FAILED", "a verified row is not a JSON object"
            )
        rows.append(parsed)
    return rows

Verify and decode the inclusive segment range [from, to].

data must hold exactly those segments' canonical bytes, starting at the first segment's byte_offset; that is the shape a ranged object read returns. Rows are released only after every segment verifies.

def encode_reporting_rows_v1(rows: Iterable[object]) ‑> ReportingEncodedRowsV1
Expand source code
def encode_reporting_rows_v1(rows: Iterable[object]) -> ReportingEncodedRowsV1:
    """Encode rows into contract-fixed canonical JSONL chunks and manifests."""
    chunks: list[ReportingRowChunkV1] = []
    chunk_lines: list[bytes] = []
    chunk_bytes = 0
    chunk_first_ordinal = 0
    total_rows = 0

    def close_chunk() -> None:
        nonlocal chunk_lines, chunk_bytes
        if not chunk_lines:
            return
        chunks.append(_build_chunk(len(chunks), chunk_first_ordinal, chunk_lines))
        chunk_lines = []
        chunk_bytes = 0

    for ordinal, row in enumerate(rows):
        line = canonical_reporting_row_v1(row, ordinal) + _NEWLINE
        if len(chunk_lines) == REPORTING_ROW_CHUNK_MAX_ROWS or (
            chunk_lines and chunk_bytes + len(line) > REPORTING_ROW_CHUNK_MAX_BYTES
        ):
            close_chunk()
        if not chunk_lines:
            chunk_first_ordinal = ordinal
        chunk_lines.append(line)
        chunk_bytes += len(line)
        total_rows = ordinal + 1
    close_chunk()

    manifests = tuple(chunk.manifest for chunk in chunks)
    return ReportingEncodedRowsV1(
        format=REPORTING_ROW_FORMAT_V1,
        algorithm=REPORTING_ROW_ALGORITHM_V1,
        row_count=total_rows,
        byte_count=sum(manifest.byte_count for manifest in manifests),
        chunks=tuple(chunks),
        manifests=manifests,
        row_manifest_sha256=reporting_row_manifest_sha256_v1(manifests),
    )

Encode rows into contract-fixed canonical JSONL chunks and manifests.

def reporting_revision_envelope_digest_v1(*,
reporting_revision_id: str,
row_count: int,
control_totals: Sequence[Any],
chunks: Iterable[bytes]) ‑> ReportingRevisionEnvelopeDigestV1
Expand source code
def reporting_revision_envelope_digest_v1(
    *,
    reporting_revision_id: str,
    row_count: int,
    control_totals: Sequence[Any],
    chunks: Iterable[bytes],
) -> ReportingRevisionEnvelopeDigestV1:
    """Envelope digest over already-encoded chunk bytes."""
    hasher = create_reporting_revision_envelope_hasher_v1(
        reporting_revision_id=reporting_revision_id,
        row_count=row_count,
        control_totals=control_totals,
    )
    for chunk in chunks:
        hasher.update(chunk)
    return hasher.digest()

Envelope digest over already-encoded chunk bytes.

def reporting_row_manifest_sha256_v1(manifests: Sequence[ReportingRowChunkManifestV1]) ‑> str
Expand source code
def reporting_row_manifest_sha256_v1(manifests: Sequence[ReportingRowChunkManifestV1]) -> str:
    """``sha256(JCS(manifests))`` over the ordered chunk manifests, locators excluded."""
    return _sha256_hex(rfc8785.dumps([manifest.to_wire() for manifest in manifests]))

sha256(JCS(manifests)) over the ordered chunk manifests, locators excluded.

def verify_reporting_row_chunk_v1(manifest: ReportingRowChunkManifestV1,
data: bytes) ‑> None
Expand source code
def verify_reporting_row_chunk_v1(manifest: ReportingRowChunkManifestV1, data: bytes) -> None:
    """Verify a whole chunk's canonical bytes: digest, byte count, every segment."""
    buffer = memoryview(data)
    if len(buffer) != manifest.byte_count or _sha256_hex(buffer) != manifest.sha256:
        raise ReportingRowEncodingError(
            "CHUNK_INTEGRITY_FAILED", f"chunk {manifest.chunk_index} digest mismatch"
        )
    for index, segment in enumerate(manifest.segments):
        _verify_segment(
            manifest, index, buffer[segment.byte_offset : segment.byte_offset + segment.byte_count]
        )

Verify a whole chunk's canonical bytes: digest, byte count, every segment.

def verify_reporting_row_manifests_v1(manifests: Sequence[ReportingRowChunkManifestV1],
*,
row_count: int,
row_manifest_sha256: str) ‑> None
Expand source code
def verify_reporting_row_manifests_v1(
    manifests: Sequence[ReportingRowChunkManifestV1], *, row_count: int, row_manifest_sha256: str
) -> None:
    """Verify a manifest set against the digest and row count committed in PostgreSQL.

    Ordinals must be contiguous from zero, chunk and segment boundaries must
    follow the contract limits, and segment byte ranges must tile their chunk
    exactly.
    """
    if reporting_row_manifest_sha256_v1(manifests) != row_manifest_sha256.lower():
        raise ReportingRowEncodingError(
            "MANIFEST_MISMATCH", "chunk manifest digest does not match the header"
        )
    next_ordinal = 0
    for index, manifest in enumerate(manifests):
        if manifest.chunk_index != index or manifest.first_ordinal != next_ordinal:
            raise ReportingRowEncodingError("MANIFEST_MISMATCH", f"chunk {index} is out of order")
        if (
            manifest.row_count < 1
            or manifest.row_count > REPORTING_ROW_CHUNK_MAX_ROWS
            or len(manifest.segments) < 1
            or len(manifest.segments) > REPORTING_ROW_CHUNK_MAX_SEGMENTS
        ):
            raise ReportingRowEncodingError(
                "MANIFEST_MISMATCH", f"chunk {index} exceeds contract limits"
            )
        segment_ordinal = manifest.first_ordinal
        segment_offset = 0
        for segment_index, segment in enumerate(manifest.segments):
            last = segment_index == len(manifest.segments) - 1
            if (
                segment.first_ordinal != segment_ordinal
                or segment.byte_offset != segment_offset
                or segment.row_count < 1
                or segment.byte_count < 1
                or segment.row_count > REPORTING_ROW_SEGMENT_MAX_ROWS
                or (not last and segment.row_count != REPORTING_ROW_SEGMENT_MAX_ROWS)
            ):
                raise ReportingRowEncodingError(
                    "MANIFEST_MISMATCH", f"chunk {index} segment {segment_index} is invalid"
                )
            segment_ordinal += segment.row_count
            segment_offset += segment.byte_count
        if (
            segment_ordinal != manifest.first_ordinal + manifest.row_count
            or segment_offset != manifest.byte_count
        ):
            raise ReportingRowEncodingError(
                "MANIFEST_MISMATCH", f"chunk {index} segments do not tile the chunk"
            )
        if manifest.row_count > 1 and manifest.byte_count > REPORTING_ROW_CHUNK_MAX_BYTES:
            raise ReportingRowEncodingError(
                "MANIFEST_MISMATCH", f"chunk {index} exceeds the byte limit"
            )
        next_ordinal += manifest.row_count
    if next_ordinal != row_count:
        raise ReportingRowEncodingError(
            "MANIFEST_MISMATCH", "chunk manifests do not cover row_count"
        )

Verify a manifest set against the digest and row count committed in PostgreSQL.

Ordinals must be contiguous from zero, chunk and segment boundaries must follow the contract limits, and segment byte ranges must tile their chunk exactly.

Classes

class ReportingEncodedRowsV1 (format: str,
algorithm: str,
row_count: int,
byte_count: int,
chunks: tuple[ReportingRowChunkV1, ...],
manifests: tuple[ReportingRowChunkManifestV1, ...],
row_manifest_sha256: str)
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingEncodedRowsV1:
    format: str
    algorithm: str
    row_count: int
    #: Total canonical JSONL bytes across all chunks.
    byte_count: int
    chunks: tuple[ReportingRowChunkV1, ...]
    manifests: tuple[ReportingRowChunkManifestV1, ...]
    #: ``sha256(JCS(manifests))``; bound immutably on the revision's row set.
    row_manifest_sha256: str

ReportingEncodedRowsV1(format: 'str', algorithm: 'str', row_count: 'int', byte_count: 'int', chunks: 'tuple[ReportingRowChunkV1, …]', manifests: 'tuple[ReportingRowChunkManifestV1, …]', row_manifest_sha256: 'str')

Instance variables

var algorithm : str
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingEncodedRowsV1:
    format: str
    algorithm: str
    row_count: int
    #: Total canonical JSONL bytes across all chunks.
    byte_count: int
    chunks: tuple[ReportingRowChunkV1, ...]
    manifests: tuple[ReportingRowChunkManifestV1, ...]
    #: ``sha256(JCS(manifests))``; bound immutably on the revision's row set.
    row_manifest_sha256: str
var byte_count : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingEncodedRowsV1:
    format: str
    algorithm: str
    row_count: int
    #: Total canonical JSONL bytes across all chunks.
    byte_count: int
    chunks: tuple[ReportingRowChunkV1, ...]
    manifests: tuple[ReportingRowChunkManifestV1, ...]
    #: ``sha256(JCS(manifests))``; bound immutably on the revision's row set.
    row_manifest_sha256: str

Total canonical JSONL bytes across all chunks.

var chunks : tuple[ReportingRowChunkV1, ...]
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingEncodedRowsV1:
    format: str
    algorithm: str
    row_count: int
    #: Total canonical JSONL bytes across all chunks.
    byte_count: int
    chunks: tuple[ReportingRowChunkV1, ...]
    manifests: tuple[ReportingRowChunkManifestV1, ...]
    #: ``sha256(JCS(manifests))``; bound immutably on the revision's row set.
    row_manifest_sha256: str
var format : str
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingEncodedRowsV1:
    format: str
    algorithm: str
    row_count: int
    #: Total canonical JSONL bytes across all chunks.
    byte_count: int
    chunks: tuple[ReportingRowChunkV1, ...]
    manifests: tuple[ReportingRowChunkManifestV1, ...]
    #: ``sha256(JCS(manifests))``; bound immutably on the revision's row set.
    row_manifest_sha256: str
var manifests : tuple[ReportingRowChunkManifestV1, ...]
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingEncodedRowsV1:
    format: str
    algorithm: str
    row_count: int
    #: Total canonical JSONL bytes across all chunks.
    byte_count: int
    chunks: tuple[ReportingRowChunkV1, ...]
    manifests: tuple[ReportingRowChunkManifestV1, ...]
    #: ``sha256(JCS(manifests))``; bound immutably on the revision's row set.
    row_manifest_sha256: str
var row_count : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingEncodedRowsV1:
    format: str
    algorithm: str
    row_count: int
    #: Total canonical JSONL bytes across all chunks.
    byte_count: int
    chunks: tuple[ReportingRowChunkV1, ...]
    manifests: tuple[ReportingRowChunkManifestV1, ...]
    #: ``sha256(JCS(manifests))``; bound immutably on the revision's row set.
    row_manifest_sha256: str
var row_manifest_sha256 : str
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingEncodedRowsV1:
    format: str
    algorithm: str
    row_count: int
    #: Total canonical JSONL bytes across all chunks.
    byte_count: int
    chunks: tuple[ReportingRowChunkV1, ...]
    manifests: tuple[ReportingRowChunkManifestV1, ...]
    #: ``sha256(JCS(manifests))``; bound immutably on the revision's row set.
    row_manifest_sha256: str

sha256(JCS(manifests)); bound immutably on the revision's row set.

class ReportingRevisionEnvelopeDigestV1 (sha256: str, byte_count: int)
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRevisionEnvelopeDigestV1:
    sha256: str
    #: Byte length of the canonical preimage; equals the binding's byte count.
    byte_count: int

ReportingRevisionEnvelopeDigestV1(sha256: 'str', byte_count: 'int')

Instance variables

var byte_count : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRevisionEnvelopeDigestV1:
    sha256: str
    #: Byte length of the canonical preimage; equals the binding's byte count.
    byte_count: int

Byte length of the canonical preimage; equals the binding's byte count.

var sha256 : str
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRevisionEnvelopeDigestV1:
    sha256: str
    #: Byte length of the canonical preimage; equals the binding's byte count.
    byte_count: int
class ReportingRevisionEnvelopeHasherV1 (*args, **kwargs)
Expand source code
class ReportingRevisionEnvelopeHasherV1(Protocol):
    """Streaming hasher over verified chunk bytes; rows are never parsed."""

    def update(self, chunk_bytes: bytes) -> None: ...

    def digest(self) -> ReportingRevisionEnvelopeDigestV1: ...

Streaming hasher over verified chunk bytes; rows are never parsed.

Ancestors

  • typing.Protocol
  • typing.Generic

Methods

def digest(self) ‑> ReportingRevisionEnvelopeDigestV1
Expand source code
def digest(self) -> ReportingRevisionEnvelopeDigestV1: ...
def update(self, chunk_bytes: bytes) ‑> None
Expand source code
def update(self, chunk_bytes: bytes) -> None: ...
class ReportingRowChunkManifestV1 (chunk_index: int,
first_ordinal: int,
row_count: int,
byte_count: int,
sha256: str,
segments: tuple[ReportingRowSegmentManifestV1, ...])
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkManifestV1:
    """One chunk: up to 20 segments, the unit of storage."""

    chunk_index: int
    first_ordinal: int
    row_count: int
    byte_count: int
    sha256: str
    segments: tuple[ReportingRowSegmentManifestV1, ...]

    def to_wire(self) -> dict[str, Any]:
        return {
            "chunk_index": self.chunk_index,
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
            "segments": [segment.to_wire() for segment in self.segments],
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowChunkManifestV1:
        return cls(
            chunk_index=int(value["chunk_index"]),
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
            segments=tuple(
                ReportingRowSegmentManifestV1.from_wire(segment) for segment in value["segments"]
            ),
        )

One chunk: up to 20 segments, the unit of storage.

Static methods

def from_wire(value: Mapping[str, Any]) ‑> ReportingRowChunkManifestV1

Instance variables

var byte_count : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkManifestV1:
    """One chunk: up to 20 segments, the unit of storage."""

    chunk_index: int
    first_ordinal: int
    row_count: int
    byte_count: int
    sha256: str
    segments: tuple[ReportingRowSegmentManifestV1, ...]

    def to_wire(self) -> dict[str, Any]:
        return {
            "chunk_index": self.chunk_index,
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
            "segments": [segment.to_wire() for segment in self.segments],
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowChunkManifestV1:
        return cls(
            chunk_index=int(value["chunk_index"]),
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
            segments=tuple(
                ReportingRowSegmentManifestV1.from_wire(segment) for segment in value["segments"]
            ),
        )
var chunk_index : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkManifestV1:
    """One chunk: up to 20 segments, the unit of storage."""

    chunk_index: int
    first_ordinal: int
    row_count: int
    byte_count: int
    sha256: str
    segments: tuple[ReportingRowSegmentManifestV1, ...]

    def to_wire(self) -> dict[str, Any]:
        return {
            "chunk_index": self.chunk_index,
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
            "segments": [segment.to_wire() for segment in self.segments],
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowChunkManifestV1:
        return cls(
            chunk_index=int(value["chunk_index"]),
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
            segments=tuple(
                ReportingRowSegmentManifestV1.from_wire(segment) for segment in value["segments"]
            ),
        )
var first_ordinal : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkManifestV1:
    """One chunk: up to 20 segments, the unit of storage."""

    chunk_index: int
    first_ordinal: int
    row_count: int
    byte_count: int
    sha256: str
    segments: tuple[ReportingRowSegmentManifestV1, ...]

    def to_wire(self) -> dict[str, Any]:
        return {
            "chunk_index": self.chunk_index,
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
            "segments": [segment.to_wire() for segment in self.segments],
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowChunkManifestV1:
        return cls(
            chunk_index=int(value["chunk_index"]),
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
            segments=tuple(
                ReportingRowSegmentManifestV1.from_wire(segment) for segment in value["segments"]
            ),
        )
var row_count : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkManifestV1:
    """One chunk: up to 20 segments, the unit of storage."""

    chunk_index: int
    first_ordinal: int
    row_count: int
    byte_count: int
    sha256: str
    segments: tuple[ReportingRowSegmentManifestV1, ...]

    def to_wire(self) -> dict[str, Any]:
        return {
            "chunk_index": self.chunk_index,
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
            "segments": [segment.to_wire() for segment in self.segments],
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowChunkManifestV1:
        return cls(
            chunk_index=int(value["chunk_index"]),
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
            segments=tuple(
                ReportingRowSegmentManifestV1.from_wire(segment) for segment in value["segments"]
            ),
        )
var segments : tuple[ReportingRowSegmentManifestV1, ...]
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkManifestV1:
    """One chunk: up to 20 segments, the unit of storage."""

    chunk_index: int
    first_ordinal: int
    row_count: int
    byte_count: int
    sha256: str
    segments: tuple[ReportingRowSegmentManifestV1, ...]

    def to_wire(self) -> dict[str, Any]:
        return {
            "chunk_index": self.chunk_index,
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
            "segments": [segment.to_wire() for segment in self.segments],
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowChunkManifestV1:
        return cls(
            chunk_index=int(value["chunk_index"]),
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
            segments=tuple(
                ReportingRowSegmentManifestV1.from_wire(segment) for segment in value["segments"]
            ),
        )
var sha256 : str
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkManifestV1:
    """One chunk: up to 20 segments, the unit of storage."""

    chunk_index: int
    first_ordinal: int
    row_count: int
    byte_count: int
    sha256: str
    segments: tuple[ReportingRowSegmentManifestV1, ...]

    def to_wire(self) -> dict[str, Any]:
        return {
            "chunk_index": self.chunk_index,
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
            "segments": [segment.to_wire() for segment in self.segments],
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowChunkManifestV1:
        return cls(
            chunk_index=int(value["chunk_index"]),
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
            segments=tuple(
                ReportingRowSegmentManifestV1.from_wire(segment) for segment in value["segments"]
            ),
        )

Methods

def to_wire(self) ‑> dict[str, typing.Any]
Expand source code
def to_wire(self) -> dict[str, Any]:
    return {
        "chunk_index": self.chunk_index,
        "first_ordinal": self.first_ordinal,
        "row_count": self.row_count,
        "byte_count": self.byte_count,
        "sha256": self.sha256,
        "segments": [segment.to_wire() for segment in self.segments],
    }
class ReportingRowChunkV1 (manifest: ReportingRowChunkManifestV1,
data: bytes)
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkV1:
    manifest: ReportingRowChunkManifestV1
    #: Uncompressed canonical JSONL bytes.
    data: bytes

ReportingRowChunkV1(manifest: 'ReportingRowChunkManifestV1', data: 'bytes')

Instance variables

var data : bytes
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkV1:
    manifest: ReportingRowChunkManifestV1
    #: Uncompressed canonical JSONL bytes.
    data: bytes

Uncompressed canonical JSONL bytes.

var manifest : ReportingRowChunkManifestV1
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowChunkV1:
    manifest: ReportingRowChunkManifestV1
    #: Uncompressed canonical JSONL bytes.
    data: bytes
class ReportingRowEncodingError (code: ReportingRowEncodingErrorCode, detail: str)
Expand source code
class ReportingRowEncodingError(ValueError):
    """A row set cannot be encoded, or stored bytes do not match their digests.

    Switch on :attr:`code`. ``detail`` never carries row content.
    """

    def __init__(self, code: ReportingRowEncodingErrorCode, detail: str) -> None:
        super().__init__(f"Reporting row encoding: {code}: {detail}")
        self.code: ReportingRowEncodingErrorCode = code
        self.detail = detail

A row set cannot be encoded, or stored bytes do not match their digests.

Switch on :attr:code. detail never carries row content.

Ancestors

  • builtins.ValueError
  • builtins.Exception
  • builtins.BaseException
class ReportingRowSegmentManifestV1 (first_ordinal: int, row_count: int, byte_offset: int, byte_count: int, sha256: str)
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowSegmentManifestV1:
    """One segment: up to 500 consecutive rows, the unit of verified reads."""

    first_ordinal: int
    row_count: int
    #: Offset of the segment within its chunk's uncompressed canonical bytes.
    byte_offset: int
    byte_count: int
    sha256: str

    def to_wire(self) -> dict[str, Any]:
        return {
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_offset": self.byte_offset,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowSegmentManifestV1:
        return cls(
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_offset=int(value["byte_offset"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
        )

One segment: up to 500 consecutive rows, the unit of verified reads.

Static methods

def from_wire(value: Mapping[str, Any]) ‑> ReportingRowSegmentManifestV1

Instance variables

var byte_count : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowSegmentManifestV1:
    """One segment: up to 500 consecutive rows, the unit of verified reads."""

    first_ordinal: int
    row_count: int
    #: Offset of the segment within its chunk's uncompressed canonical bytes.
    byte_offset: int
    byte_count: int
    sha256: str

    def to_wire(self) -> dict[str, Any]:
        return {
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_offset": self.byte_offset,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowSegmentManifestV1:
        return cls(
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_offset=int(value["byte_offset"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
        )
var byte_offset : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowSegmentManifestV1:
    """One segment: up to 500 consecutive rows, the unit of verified reads."""

    first_ordinal: int
    row_count: int
    #: Offset of the segment within its chunk's uncompressed canonical bytes.
    byte_offset: int
    byte_count: int
    sha256: str

    def to_wire(self) -> dict[str, Any]:
        return {
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_offset": self.byte_offset,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowSegmentManifestV1:
        return cls(
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_offset=int(value["byte_offset"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
        )

Offset of the segment within its chunk's uncompressed canonical bytes.

var first_ordinal : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowSegmentManifestV1:
    """One segment: up to 500 consecutive rows, the unit of verified reads."""

    first_ordinal: int
    row_count: int
    #: Offset of the segment within its chunk's uncompressed canonical bytes.
    byte_offset: int
    byte_count: int
    sha256: str

    def to_wire(self) -> dict[str, Any]:
        return {
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_offset": self.byte_offset,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowSegmentManifestV1:
        return cls(
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_offset=int(value["byte_offset"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
        )
var row_count : int
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowSegmentManifestV1:
    """One segment: up to 500 consecutive rows, the unit of verified reads."""

    first_ordinal: int
    row_count: int
    #: Offset of the segment within its chunk's uncompressed canonical bytes.
    byte_offset: int
    byte_count: int
    sha256: str

    def to_wire(self) -> dict[str, Any]:
        return {
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_offset": self.byte_offset,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowSegmentManifestV1:
        return cls(
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_offset=int(value["byte_offset"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
        )
var sha256 : str
Expand source code
@dataclass(frozen=True, slots=True)
class ReportingRowSegmentManifestV1:
    """One segment: up to 500 consecutive rows, the unit of verified reads."""

    first_ordinal: int
    row_count: int
    #: Offset of the segment within its chunk's uncompressed canonical bytes.
    byte_offset: int
    byte_count: int
    sha256: str

    def to_wire(self) -> dict[str, Any]:
        return {
            "first_ordinal": self.first_ordinal,
            "row_count": self.row_count,
            "byte_offset": self.byte_offset,
            "byte_count": self.byte_count,
            "sha256": self.sha256,
        }

    @classmethod
    def from_wire(cls, value: Mapping[str, Any]) -> ReportingRowSegmentManifestV1:
        return cls(
            first_ordinal=int(value["first_ordinal"]),
            row_count=int(value["row_count"]),
            byte_offset=int(value["byte_offset"]),
            byte_count=int(value["byte_count"]),
            sha256=str(value["sha256"]),
        )

Methods

def to_wire(self) ‑> dict[str, typing.Any]
Expand source code
def to_wire(self) -> dict[str, Any]:
    return {
        "first_ordinal": self.first_ordinal,
        "row_count": self.row_count,
        "byte_offset": self.byte_offset,
        "byte_count": self.byte_count,
        "sha256": self.sha256,
    }