orjson 3.12.0: Serialize zoneinfo timezone offsets, omit microsecond precision, convert non-finite floats to JSON null, and parse zero-copy memoryview slices while rejecting UTF-8 BOM headers

# Notes: orjson Timestamp Precision, Float Standardization, and Buffer Parser Invariants

## Prior Knowledge Search
`search_known_solution` returned hits:
- `sha256:020e06fb410676e34ab53ed4e3734a8f3ae84c4a47d5e61fbfa1744e5a92934d` ("Serialize and deserialize data with orjson handling bytes return type, bitmask option flags instead of stdlib kwargs, non-string dict keys, and native dataclass/UUID/datetime support")
- `sha256:05f2672095e6b40251604acdb3f1cf2defa139aa701bc9f92f5d48baa62b229e` ("Configure orjson option bitmasks to intercept subclasses, dataclasses, naive timestamps, and JS-safe integers that default serialization silently bypasses or corrupts")
- `sha256:46db4dc7997a998dde22ff96adcbebfac3ef3c3f1468eae57798840b9de8cc18` ("Serialize vertical tabulation (\v / 0x0B) to RFC 8259 \u000b hex escapes without 3.10.17 escape corruption, and handle 3.11.7 positive float exponent formatting")

This sample proves a distinct set of behaviors: native `zoneinfo.ZoneInfo` daylight saving offset formatting, `OPT_OMIT_MICROSECONDS` precision truncation, RFC 8259 non-finite float conversion to `null`, zero-copy `memoryview` slice parsing, and strict parser rejection of UTF-8 BOM headers and stream inputs.

## Pinned Release and Scope
- Package: `orjson==3.12.0`
- Ecosystem: PyPI (Python)

## What a Model Would Have Written Instead
A model would have assumed `orjson.loads()` transparently strips or ignores UTF-8 byte order mark (BOM) prefixes (`\xef\xbb\xbf`), accepts `io.BytesIO` or file-like streams, and assumed `orjson.dumps()` serializes `float('nan')` and `float('inf')` to literal tokens `NaN` and `Infinity` matching Python's standard library `json.dumps()`.

## How the Wrong Version Fails
The wrong version fails loudly:
1. Passing UTF-8 BOM bytes to `orjson.loads()` raises `orjson.JSONDecodeError: UTF-8 byte order mark (BOM) is not supported: line 1 column 1 (char 0)`.
2. Passing a stream or `io.BytesIO` to `orjson.loads()` raises `orjson.JSONDecodeError: Input must be bytes, bytearray, memoryview, or str: line 1 column 1 (char 0)`.
3. Expecting `orjson.dumps()` to emit non-standard `NaN` or `Infinity` tokens fails assertions because `orjson` strictly serializes non-finite floats to JSON `null`.
4. Passing non-standard `b'{"val": NaN}'` or `b'{"val": Infinity}'` payloads to `orjson.loads()` raises `orjson.JSONDecodeError` because RFC 8259 forbids non-finite float literals.

{"case":{"believed":"orjson.loads transparently accepts UTF-8 byte order mark (BOM) prefixes, accepts stream and file-like objects, and orjson.dumps formats float NaN and Infinity as numeric literals matching standard library json.","caseId":"case:sha256:1a3cc5bad745b04b15bdf0bb81582b7ce1a9d382ba3b07b704a3a28b36b8e2f0","contract":["orjson.loads explicitly rejects UTF-8 byte order marks (BOM) with JSONDecodeError rather than stripping them, and requires bytes-like buffers rejecting file streams with JSONDecodeError.","assert orjson.dumps strictly serializes float NaN, Infinity, and -Infinity to JSON null rather than stdlib json non-standard literal tokens","assert orjson.loads rejects raw NaN and Infinity tokens with JSONDecodeError adhering to RFC 8259","assert zoneinfo.ZoneInfo timezone-aware datetimes serialize with exact UTC offsets including daylight saving adjustments","assert OPT_OMIT_MICROSECONDS strips microsecond precision from both datetime.datetime and datetime.time objects","assert orjson.loads parses zero-copy memoryview buffer slices without intermediate allocations or copies","assert orjson.JSONDecodeError subclasses ValueError and json.JSONDecodeError, and JSONEncodeError subclasses TypeError"],"goal":"Serialize zoneinfo timezone offsets, omit microsecond precision, convert non-finite floats to JSON null, and parse zero-copy memoryview slices while rejecting UTF-8 BOM headers","kind":"HOW","packages":["pkg:pypi/orjson@3.12.0"],"schemaVersion":1,"symbols":["orjson.dumps","orjson.loads","orjson.OPT_OMIT_MICROSECONDS","orjson.OPT_UTC_Z","orjson.OPT_NAIVE_UTC","orjson.JSONDecodeError","orjson.JSONEncodeError"]},"contractCommand":["python","test/contract.py"],"environment":{"arch":"x64","ecosystem":"pypi","executionContext":"python","language":"python","os":"linux","packageManager":"pip","runtime":"python","schemaVersion":1},"license":"MIT-0","packages":["pkg:pypi/orjson@3.12.0"],"schemaVersion":1,"symbols":["orjson.dumps","orjson.loads","orjson.OPT_OMIT_MICROSECONDS","orjson.OPT_UTC_Z","orjson.OPT_NAIVE_UTC","orjson.JSONDecodeError","orjson.JSONEncodeError"],"verifierAdapter":"python@1"}

orjson==3.12.0

"""orjson timestamp, float, and parser invariant demonstration package."""

from .parser import (
    format_time,
    format_timestamp,
    parse_buffer_slice,
    serialize_metrics,
)

__all__ = [
    "format_time",
    "format_timestamp",
    "parse_buffer_slice",
    "serialize_metrics",
]

"""Production serialization and parsing helpers demonstrating orjson behaviors."""

from typing import Any, Union
import datetime
import zoneinfo
import orjson


def format_timestamp(
    dt: datetime.datetime,
    *,
    omit_microseconds: bool = False,
    utc_z: bool = False,
    naive_as_utc: bool = False,
) -> bytes:
    """Serialize a datetime object to RFC 3339 / ISO 8601 JSON bytes.

    Supports native zoneinfo.ZoneInfo instances and microsecond truncation.
    """
    option = 0
    if omit_microseconds:
        option |= orjson.OPT_OMIT_MICROSECONDS
    if utc_z:
        option |= orjson.OPT_UTC_Z
    if naive_as_utc:
        option |= orjson.OPT_NAIVE_UTC

    if option != 0:
        return orjson.dumps(dt, option=option)
    return orjson.dumps(dt)


def format_time(
    t: datetime.time,
    *,
    omit_microseconds: bool = False,
) -> bytes:
    """Serialize a time object to ISO 8601 JSON bytes."""
    if omit_microseconds:
        return orjson.dumps(t, option=orjson.OPT_OMIT_MICROSECONDS)
    return orjson.dumps(t)


def serialize_metrics(metrics: dict[str, float]) -> bytes:
    """Serialize float metrics into JSON bytes.

    Under RFC 8259, non-finite floats (NaN, +Inf, -Inf) are converted to JSON null
    rather than Python stdlib non-standard NaN/Infinity tokens.
    """
    return orjson.dumps(metrics)


def parse_buffer_slice(
    buf: Union[bytes, bytearray, memoryview],
    start: int = 0,
    end: int | None = None,
) -> Any:
    """Parse JSON payload directly from a memoryview slice of a larger buffer.

    Avoids intermediate byte allocations and copies.
    """
    mv = memoryview(buf)
    if end is not None:
        slice_view = mv[start:end]
    else:
        slice_view = mv[start:]
    return orjson.loads(slice_view)

"""Contract test proving orjson 3.12.0 behaviors and invariants."""

import datetime
import io
import json
from pathlib import Path
import sys
import zoneinfo

sys.path.insert(0, str(Path(__file__).resolve().parents[1]))

import orjson
from src.parser import (
    format_time,
    format_timestamp,
    parse_buffer_slice,
    serialize_metrics,
)


def test_contract() -> None:
    # 1. orjson.loads BOM rejection & input type requirements
    # A common expectation is that loads() transparently strips UTF-8 BOM headers.
    # orjson strictly rejects UTF-8 BOM with JSONDecodeError.
    bom_data = b'\xef\xbb\xbf{"key": "value"}'
    try:
        orjson.loads(bom_data)
        raise AssertionError("Expected orjson.loads to reject UTF-8 BOM")
    except orjson.JSONDecodeError as exc:
        assert "BOM" in str(exc) or "byte order mark" in str(exc)

    # Rejection of stream-like file/BytesIO objects
    stream = io.BytesIO(b'{"key": "value"}')
    try:
        orjson.loads(stream)  # type: ignore
        raise AssertionError("Expected orjson.loads to reject BytesIO stream")
    except orjson.JSONDecodeError as exc:
        assert "Input must be bytes, bytearray, memoryview, or str" in str(exc)

    # 2. Non-finite float serialization to null (RFC 8259 compliance)
    # stdlib json.dumps emits non-standard NaN / Infinity literals by default.
    # orjson.dumps strictly converts NaN, Inf, and -Inf to JSON null.
    nan_val = float("nan")
    inf_val = float("inf")
    ninf_val = float("-inf")

    metrics_payload = {"ratio": nan_val, "limit": inf_val, "floor": ninf_val}
    encoded_metrics = serialize_metrics(metrics_payload)
    assert encoded_metrics == b'{"ratio":null,"limit":null,"floor":null}'
    assert orjson.dumps({"nan": nan_val, "inf": inf_val, "ninf": ninf_val}) == b'{"nan":null,"inf":null,"ninf":null}'

    # 3. orjson.loads rejects non-standard NaN and Infinity tokens
    for non_finite_json in [b'{"ratio": NaN}', b'{"limit": Infinity}', b'{"floor": -Infinity}', b'{"limit": +Infinity}']:
        try:
            orjson.loads(non_finite_json)
            raise AssertionError(f"Expected orjson.loads to reject non-finite token in {non_finite_json!r}")
        except orjson.JSONDecodeError:
            pass

    # 4. Native ZoneInfo serialization & daylight saving adjustments
    utc_zone = zoneinfo.ZoneInfo("UTC")
    ny_zone = zoneinfo.ZoneInfo("America/New_York")

    summer_dt = datetime.datetime(2024, 7, 15, 14, 30, 0, tzinfo=ny_zone)
    winter_dt = datetime.datetime(2024, 1, 15, 14, 30, 0, tzinfo=ny_zone)
    utc_dt = datetime.datetime(2024, 7, 15, 14, 30, 0, tzinfo=utc_zone)

    # EDT is UTC-04:00, EST is UTC-05:00
    assert format_timestamp(summer_dt) == b'"2024-07-15T14:30:00-04:00"'
    assert format_timestamp(winter_dt) == b'"2024-01-15T14:30:00-05:00"'
    assert format_timestamp(utc_dt) == b'"2024-07-15T14:30:00+00:00"'
    assert format_timestamp(utc_dt, utc_z=True) == b'"2024-07-15T14:30:00Z"'

    # Naive datetimes require OPT_NAIVE_UTC to emit 'Z' with OPT_UTC_Z
    naive_dt = datetime.datetime(2024, 7, 15, 14, 30, 0)
    assert format_timestamp(naive_dt, utc_z=True) == b'"2024-07-15T14:30:00"'
    assert format_timestamp(naive_dt, utc_z=True, naive_as_utc=True) == b'"2024-07-15T14:30:00Z"'

    # 5. OPT_OMIT_MICROSECONDS option
    dt_micros = datetime.datetime(2024, 7, 15, 14, 30, 0, 987654, tzinfo=utc_zone)
    time_micros = datetime.time(9, 15, 30, 123456)

    assert format_timestamp(dt_micros) == b'"2024-07-15T14:30:00.987654+00:00"'
    assert format_timestamp(dt_micros, omit_microseconds=True) == b'"2024-07-15T14:30:00+00:00"'
    assert format_timestamp(dt_micros, omit_microseconds=True, utc_z=True) == b'"2024-07-15T14:30:00Z"'
    assert format_time(time_micros) == b'"09:15:30.123456"'
    assert format_time(time_micros, omit_microseconds=True) == b'"09:15:30"'

    # 6. Zero-copy memoryview parsing
    buffer_packet = bytearray(b'PREFIX_HEADER_1234_{"event": "login", "user_id": 1001}_SUFFIX_CHECKSUM_5678')
    parsed_payload = parse_buffer_slice(buffer_packet, start=19, end=54)
    assert parsed_payload == {"event": "login", "user_id": 1001}

    # 7. Strict RFC 8259 structural validation
    # Rejection of trailing commas and single quotes
    for invalid_payload in [b'{"item": 1,}', b'[10, 20, 30,]', b"{'item': 1}", b'{item: 1}']:
        try:
            orjson.loads(invalid_payload)
            raise AssertionError(f"Expected orjson.loads to reject invalid syntax in {invalid_payload!r}")
        except orjson.JSONDecodeError:
            pass

    # 8. Exception class hierarchy
    assert issubclass(orjson.JSONDecodeError, ValueError)
    assert issubclass(orjson.JSONDecodeError, json.JSONDecodeError)
    assert issubclass(orjson.JSONEncodeError, TypeError)


if __name__ == "__main__":
    test_contract()