ping-dataexport 0.1.0__py3-none-any.whl

ping_dataexport/planner/base.py

@@ -0,0 +1,71 @@
+"""PartitionPlanner interface + Partition/Plan + for_options() registry.
+
+A planner turns ExportOptions into partitions: (query with '?' placeholders,
+bind params, target filename). ALL partition values are bound parameters — a
+group value like O'Brien can never break the generated SQL. Placeholders are
+qmark; the connector rewrites for its paramstyle and adapts param types.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Callable, List, Optional, Tuple
+
+from ..applogger import AppLogger
+from ..export.options import ExportOptions
+
+
+@dataclass(frozen=True)
+class Partition:
+    """One unit of work: query + bind params + target file (None = single output)."""
+
+    query: str
+    params: Tuple[Any, ...] = ()
+    filename: Optional[str] = None
+    label: str = ""
+    where_display: Optional[str] = None  # human-readable WHERE for the logs
+
+
+@dataclass
+class Plan:
+    partitions: List[Partition] = field(default_factory=list)
+    #: called by the engine after ALL partitions succeed (never in --test);
+    #: watermark uses it to advance state — at-least-once delivery.
+    on_success: Optional[Callable[[], None]] = None
+
+
+class PartitionPlanner(ABC):
+    @abstractmethod
+    def plan(self, options: ExportOptions, conn: Any, connector: Any, logger: AppLogger) -> Plan:
+        """May query the DB (groupby DISTINCT pass, watermark MAX/type checks)."""
+
+
+def wrap_query(query: str) -> str:
+    """User query as a dialect-neutral subquery."""
+    return f"SELECT * FROM ({query}) QRY"
+
+
+def for_options(options: ExportOptions) -> PartitionPlanner:
+    mode = options.mode
+    if mode is None or mode == "splitrow":
+        from .single import SinglePlanner
+
+        return SinglePlanner()
+    if mode == "groupby":
+        from .groupby import GroupByPlanner
+
+        return GroupByPlanner()
+    if mode in ("date", "relativedate"):
+        from .datelist import DateListPlanner
+
+        return DateListPlanner()
+    if mode == "monthbydate":
+        from .monthbydate import MonthByDatePlanner
+
+        return MonthByDatePlanner()
+    if mode == "watermark":
+        from .watermark import WatermarkPlanner
+
+        return WatermarkPlanner()
+    raise ValueError(f"no planner for mode {mode!r}")  # unreachable after validation

ping_dataexport/planner/datelist.py

@@ -0,0 +1,35 @@
+"""DateListPlanner — date and relativedate modes: one file per day.
+
+The inclusive date list is pre-built by JobSpecBuilder (Python, never SQL).
+Per date: SELECT * FROM (<q>) QRY WHERE <col> = ?   bound as datetime.date.
+Files:    base_YYYY-MM-DD.ext
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..applogger import AppLogger
+from ..export.options import ExportOptions
+from ..export.util import output_filename
+from .base import Partition, PartitionPlanner, Plan, wrap_query
+
+
+class DateListPlanner(PartitionPlanner):
+    def plan(self, options: ExportOptions, conn: Any, connector: Any, logger: AppLogger) -> Plan:
+        col = options.column
+        base = wrap_query(options.query)
+        partitions = [
+            Partition(
+                query=f"{base} WHERE {col} = ?",
+                params=(day,),
+                filename=output_filename(
+                    options.base_name, day.isoformat(), options.format, options.gzip
+                ),
+                label=day.isoformat(),
+                where_display=f"{col} = '{day.isoformat()}'",
+            )
+            for day in options.dates
+        ]
+        logger.info("EXPORT", "DATELIST", f"{len(partitions)} date partition(s)")
+        return Plan(partitions=partitions)

ping_dataexport/planner/groupby.py

@@ -0,0 +1,71 @@
+"""GroupByPlanner — one file per distinct value of the group column.
+
+DISTINCT pass: SELECT DISTINCT <col> FROM (<q>) A ORDER BY <col>
+Per value:     SELECT * FROM (<q>) QRY WHERE <col> = ?   (NULL group -> IS NULL)
+Files:         base_<value>.ext, base_NULL.ext
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any
+
+from ..applogger import AppLogger
+from ..errors import ExportError
+from ..export.options import ExportOptions
+from ..export.util import output_filename
+from .base import Partition, PartitionPlanner, Plan, wrap_query
+
+
+def _suffix_for(value: Any) -> str:
+    if value is None:
+        return "NULL"
+    if isinstance(value, datetime.datetime):
+        return value.strftime("%Y-%m-%d %H%M%S")
+    if isinstance(value, datetime.date):
+        return value.isoformat()
+    return str(value)
+
+
+class GroupByPlanner(PartitionPlanner):
+    def plan(self, options: ExportOptions, conn: Any, connector: Any, logger: AppLogger) -> Plan:
+        col = options.column
+        distinct_sql = connector.rewrite_params(
+            f"SELECT DISTINCT {col} FROM ({options.query}) A ORDER BY {col}"
+        )
+        cursor = connector.prepare_cursor(conn, options.fetch_size)
+        try:
+            cursor.execute(distinct_sql)
+            values = [row[0] for row in cursor.fetchall()]
+        except Exception as exc:
+            raise ExportError(f"groupby DISTINCT query failed: {exc}") from exc
+        finally:
+            cursor.close()
+
+        logger.info("EXPORT", "GROUPBY", f"{len(values)} distinct value(s) of {col}")
+        base = wrap_query(options.query)
+        partitions = []
+        for value in values:
+            suffix = _suffix_for(value)
+            filename = output_filename(options.base_name, suffix, options.format, options.gzip)
+            if value is None:
+                partitions.append(
+                    Partition(
+                        query=f"{base} WHERE {col} IS NULL",
+                        params=(),
+                        filename=filename,
+                        label=suffix,
+                        where_display=f"{col} IS NULL",
+                    )
+                )
+            else:
+                partitions.append(
+                    Partition(
+                        query=f"{base} WHERE {col} = ?",
+                        params=(value,),
+                        filename=filename,
+                        label=suffix,
+                        where_display=f"{col} = '{value}'",
+                    )
+                )
+        return Plan(partitions=partitions)

ping_dataexport/planner/monthbydate.py

@@ -0,0 +1,104 @@
+"""MonthByDatePlanner — one file per calendar month.
+
+Months: N months before the anchor month .. the anchor month (anchor = --datefrom,
+default today). Boundaries are generated in Python, never SQL:
+  full month:   WHERE <col> >= ? AND <col> < ?    [month start, next month start)
+  anchor month: WHERE <col> >= ? AND <col> <= ?   (<= anchor date)
+Files: base_YYYYMM.ext
+
+Pre-check: a WHERE 1=0 metadata query must show a DATE/TIMESTAMP column —
+a non-date column logs ERROR and skips the export; an inconclusive detection
+(e.g. sqlite, which has no type codes) is only a warning.
+"""
+
+from __future__ import annotations
+
+import datetime
+from typing import Any, List, Tuple
+
+from ..applogger import AppLogger
+from ..export.options import ExportOptions
+from ..export.util import output_filename
+from .base import Partition, PartitionPlanner, Plan, wrap_query
+
+
+def month_starts(anchor: datetime.date, months_back: int) -> List[datetime.date]:
+    """First-of-month dates, oldest first, for anchor-month - months_back .. anchor-month."""
+    year, month = anchor.year, anchor.month
+    total = year * 12 + (month - 1)
+    starts = []
+    for m in range(total - months_back, total + 1):
+        starts.append(datetime.date(m // 12, m % 12 + 1, 1))
+    return starts
+
+
+def next_month(day: datetime.date) -> datetime.date:
+    if day.month == 12:
+        return datetime.date(day.year + 1, 1, 1)
+    return datetime.date(day.year, day.month + 1, 1)
+
+
+class MonthByDatePlanner(PartitionPlanner):
+    def plan(self, options: ExportOptions, conn: Any, connector: Any, logger: AppLogger) -> Plan:
+        col = options.column
+        kind = self._column_kind(options, conn, connector)
+        if kind is None:
+            logger.warning(
+                "EXPORT", "MONTHBYDATE", f"cannot verify column type of {col} — proceeding"
+            )
+        elif kind not in ("DATE", "TIMESTAMP"):
+            logger.error(
+                "EXPORT",
+                "MONTHBYDATE",
+                f"column {col} is {kind}, not DATE/DATETIME — export skipped",
+            )
+            return Plan(partitions=[])
+
+        anchor = options.datefrom
+        base = wrap_query(options.query)
+        partitions = []
+        starts = month_starts(anchor, options.monthsrelative)
+        for start in starts:
+            is_anchor_month = (start.year, start.month) == (anchor.year, anchor.month)
+            if is_anchor_month:
+                query = f"{base} WHERE {col} >= ? AND {col} <= ?"
+                params: Tuple[Any, ...] = (start, anchor)
+                display = f"{col} >= '{start}' AND {col} <= '{anchor}'"
+            else:
+                end = next_month(start)
+                query = f"{base} WHERE {col} >= ? AND {col} < ?"
+                params = (start, end)
+                display = f"{col} >= '{start}' AND {col} < '{end}'"
+            suffix = start.strftime("%Y%m")
+            partitions.append(
+                Partition(
+                    query=query,
+                    params=params,
+                    filename=output_filename(options.base_name, suffix, options.format, options.gzip),
+                    label=suffix,
+                    where_display=display,
+                )
+            )
+        logger.info("EXPORT", "MONTHBYDATE", f"{len(partitions)} month partition(s)")
+        return Plan(partitions=partitions)
+
+    @staticmethod
+    def _column_kind(options: ExportOptions, conn: Any, connector: Any):
+        """Canonical kind of the mode column via a WHERE 1=0 query; None = inconclusive."""
+        sql = connector.rewrite_params(f"{wrap_query(options.query)} WHERE 1=0")
+        cursor = connector.prepare_cursor(conn, options.fetch_size)
+        try:
+            cursor.execute(sql)
+            columns = connector.describe(cursor, [])
+        except Exception:
+            return None  # detection failure is a warning, not fatal
+        finally:
+            cursor.close()
+        for c in columns:
+            if c.name.lower() == options.column.lower():
+                # sample-inferred describes (sqlite) see STRING for everything on a
+                # zero-row query -> inconclusive; typed drivers are authoritative
+                if not connector.authoritative_types and c.kind == "STRING":
+                    return None
+                return c.kind
+        return None

ping_dataexport/planner/single.py

@@ -0,0 +1,18 @@
+"""SinglePlanner — default mode and splitrow: the query as-is, one partition.
+
+For splitrow the ENGINE rotates the output file every N rows; the plan is still a
+single query so the DB is read once.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..applogger import AppLogger
+from ..export.options import ExportOptions
+from .base import Partition, PartitionPlanner, Plan
+
+
+class SinglePlanner(PartitionPlanner):
+    def plan(self, options: ExportOptions, conn: Any, connector: Any, logger: AppLogger) -> Plan:
+        return Plan(partitions=[Partition(query=options.query, label=options.job_name)])

ping_dataexport/planner/watermark.py

@@ -0,0 +1,202 @@
+"""WatermarkPlanner — incremental export driven by __watermark__.ini in --outputdir.
+
+First run (missing file / blank value / FirstRun=True):
+    validate column type, MAX(col), export WHERE <col> IS NULL OR <col> <= ?
+Incremental:
+    export WHERE <col> > ? AND <col> <= ?   (prev, MAX); skip when no new data.
+State advances ONLY after a successful export (Plan.on_success) — at-least-once
+delivery. INT binds as int; DATE/DATETIME bind as date/datetime objects — the
+quoted form appears only in the logged human-readable WHERE.
+Files: base_YYYYMMDD_HHmmss.ext
+"""
+
+from __future__ import annotations
+
+import configparser
+import datetime
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional, Tuple
+
+from ..applogger import AppLogger
+from ..errors import ExportError
+from ..export.options import ExportOptions
+from ..export.util import output_filename
+from .base import Partition, PartitionPlanner, Plan, wrap_query
+
+STATE_FILENAME = "__watermark__.ini"
+_SECTION = "Watermark"
+
+# state ColumnType values — the state file format records DATETIME, not TIMESTAMP
+INT_TYPE = "INT"
+DATE_TYPE = "DATE"
+DATETIME_TYPE = "DATETIME"
+
+
+@dataclass(frozen=True)
+class WatermarkState:
+    column: str
+    column_type: Optional[str]
+    previous_value: str
+    first_run: bool
+
+
+def read_state(path: Path) -> Optional[WatermarkState]:
+    if not path.is_file():
+        return None
+    parser = configparser.RawConfigParser()
+    parser.optionxform = str
+    parser.read(path, encoding="utf-8-sig")
+    if not parser.has_section(_SECTION):
+        return None
+    get = lambda key: parser.get(_SECTION, key, fallback="").strip()  # noqa: E731
+    return WatermarkState(
+        column=get("Column"),
+        column_type=get("ColumnType") or None,
+        previous_value=get("PreviousValue"),
+        first_run=get("FirstRun").lower() in ("true", "yes", "1", ""),
+    )
+
+
+def write_state(path: Path, column: str, column_type: str, value: str) -> None:
+    parser = configparser.RawConfigParser()
+    parser.optionxform = str
+    parser.add_section(_SECTION)
+    parser.set(_SECTION, "Column", column)
+    parser.set(_SECTION, "ColumnType", column_type)
+    parser.set(_SECTION, "PreviousValue", value)
+    parser.set(_SECTION, "FirstRun", "False")
+    with open(path, "w", encoding="utf-8", newline="\n") as fh:
+        parser.write(fh)
+
+
+def value_to_state_string(value: Any) -> str:
+    if isinstance(value, datetime.datetime):
+        return value.isoformat(sep=" ")
+    if isinstance(value, datetime.date):
+        return value.isoformat()
+    return str(value)
+
+
+def parse_state_value(text: str, column_type: str) -> Any:
+    try:
+        if column_type == INT_TYPE:
+            return int(text)
+        if column_type == DATE_TYPE:
+            return datetime.date.fromisoformat(text[:10])
+        return datetime.datetime.fromisoformat(text.replace("T", " "))
+    except ValueError:
+        raise ExportError(f"invalid watermark PreviousValue {text!r} for {column_type}") from None
+
+
+class WatermarkPlanner(PartitionPlanner):
+    def plan(self, options: ExportOptions, conn: Any, connector: Any, logger: AppLogger) -> Plan:
+        col = options.column
+        state_path = Path(options.output_dir) / STATE_FILENAME
+        state = read_state(state_path)
+        first_run = state is None or state.previous_value == "" or state.first_run
+        logger.info(
+            "WATERMARK", "STATE",
+            "first run" if first_run else f"previous value {state.previous_value}",
+        )
+
+        max_value, column_type = self._max_and_type(options, conn, connector)
+        if max_value is None:
+            logger.info("WATERMARK", "SKIP", "no data (MAX is NULL) — nothing to export")
+            return Plan(partitions=[])
+
+        base = wrap_query(options.query)
+        suffix = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
+        filename = output_filename(options.base_name, suffix, options.format, options.gzip)
+
+        if first_run:
+            query = f"{base} WHERE {col} IS NULL OR {col} <= ?"
+            params: Tuple[Any, ...] = (max_value,)
+            display = f"{col} IS NULL OR {col} <= '{value_to_state_string(max_value)}'"
+        else:
+            if state.column_type:
+                column_type = state.column_type  # the state file is authoritative
+            prev = parse_state_value(state.previous_value, column_type)
+            if not self._is_newer(max_value, prev):
+                logger.info(
+                    "WATERMARK", "SKIP",
+                    f"no new data (MAX {value_to_state_string(max_value)} "
+                    f"<= previous {state.previous_value})",
+                )
+                return Plan(partitions=[])
+            query = f"{base} WHERE {col} > ? AND {col} <= ?"
+            params = (prev, max_value)
+            display = (
+                f"{col} > '{value_to_state_string(prev)}' "
+                f"AND {col} <= '{value_to_state_string(max_value)}'"
+            )
+
+        logger.info("WATERMARK", "RANGE", display)
+
+        def advance_state() -> None:
+            write_state(state_path, col, column_type, value_to_state_string(max_value))
+            logger.info(
+                "WATERMARK", "ADVANCED", f"PreviousValue={value_to_state_string(max_value)}"
+            )
+
+        return Plan(
+            partitions=[
+                Partition(
+                    query=query, params=params, filename=filename,
+                    label=suffix, where_display=display,
+                )
+            ],
+            on_success=advance_state,
+        )
+
+    def _max_and_type(
+        self, options: ExportOptions, conn: Any, connector: Any
+    ) -> Tuple[Any, str]:
+        """MAX(col) + canonical watermark type (INT | DATE | DATETIME)."""
+        col = options.column
+        sql = connector.rewrite_params(f"SELECT MAX({col}) FROM ({options.query}) QRY")
+        cursor = connector.prepare_cursor(conn, options.fetch_size)
+        try:
+            cursor.execute(sql)
+            row = cursor.fetchone()
+            max_raw = row[0] if row else None
+            columns = connector.describe(cursor, [row] if row else [])
+        except Exception as exc:
+            raise ExportError(f"watermark MAX query failed: {exc}") from exc
+        finally:
+            cursor.close()
+        if max_raw is None:
+            return None, ""
+
+        kind = columns[0].kind if columns else "STRING"
+        if kind in ("INT", "BIGINT"):
+            return int(max_raw), INT_TYPE
+        if kind == "DATE":
+            value = (
+                max_raw if isinstance(max_raw, datetime.date)
+                and not isinstance(max_raw, datetime.datetime)
+                else datetime.date.fromisoformat(str(max_raw)[:10])
+            )
+            return value, DATE_TYPE
+        if kind == "TIMESTAMP":
+            value = (
+                max_raw if isinstance(max_raw, datetime.datetime)
+                else datetime.datetime.fromisoformat(str(max_raw).replace("T", " "))
+            )
+            return value, DATETIME_TYPE
+        raise ExportError(
+            f"watermark column {col} must be INT, DATE or DATETIME (detected {kind})"
+        )
+
+    @staticmethod
+    def _is_newer(max_value: Any, prev: Any) -> bool:
+        # DATE state with a DATETIME max (or vice versa) — align before comparing
+        if isinstance(prev, datetime.datetime) and not isinstance(max_value, datetime.datetime):
+            max_value = datetime.datetime(max_value.year, max_value.month, max_value.day)
+        elif (
+            isinstance(prev, datetime.date)
+            and not isinstance(prev, datetime.datetime)
+            and isinstance(max_value, datetime.datetime)
+        ):
+            max_value = max_value.date()
+        return max_value > prev

ping_dataexport/writer/arrow_map.py

@@ -0,0 +1,174 @@
+"""ArrowRowMapper — driver rows -> PyArrow, the ONLY place driver quirks meet Arrow.
+
+- Schema: canonical ColumnInfo -> Arrow type (all fields nullable). DECIMAL keeps
+  decimal128(p,s) when p <= 38 — full precision survives, never downcast to DOUBLE.
+- One value normalizer per column, chosen ONCE from metadata (no per-value
+  isinstance chains on the hot path beyond what a normalizer needs).
+- RecordBatches are built with explicit types: pa.array(col, type=...) — Arrow type
+  inference is never used, exactly as pandas never is.
+
+pyarrow is imported lazily so delimited-only deployments don't need it installed.
+"""
+
+from __future__ import annotations
+
+import datetime
+import decimal
+from typing import Any, Callable, List, Optional, Sequence
+
+from ..db.connector import (
+    BIGINT,
+    BINARY,
+    BOOL,
+    DATE,
+    DECIMAL,
+    DOUBLE,
+    FLOAT,
+    INT,
+    STRING,
+    TIME,
+    TIMESTAMP,
+    ColumnInfo,
+)
+from ..errors import ExportError
+
+_MS_PER_DAY = 86_400_000
+_MAX_DECIMAL128_PRECISION = 38
+
+Normalizer = Callable[[Any], Any]
+
+
+class ArrowRowMapper:
+    def __init__(self, columns: List[ColumnInfo], clean_text: Callable[[str], str]):
+        try:
+            import pyarrow as pa
+        except ImportError:
+            raise ExportError("parquet output requires the pyarrow package") from None
+        self._pa = pa
+        self.columns = columns
+        self._types = [self._arrow_type(c) for c in columns]
+        self._normalizers = [self._normalizer(c, clean_text) for c in columns]
+        self._schema = pa.schema(
+            [pa.field(c.name, t, nullable=True) for c, t in zip(columns, self._types)]
+        )
+
+    @property
+    def schema(self):  # pyarrow.Schema
+        return self._schema
+
+    def new_buffers(self) -> List[List[Any]]:
+        return [[] for _ in self.columns]
+
+    def append_row(self, buffers: List[List[Any]], row: Sequence[Any]) -> None:
+        for buf, normalize, value in zip(buffers, self._normalizers, row):
+            buf.append(normalize(value))
+
+    def to_record_batch(self, buffers: List[List[Any]]):
+        pa = self._pa
+        arrays = [pa.array(buf, type=t) for buf, t in zip(buffers, self._types)]
+        return pa.record_batch(arrays, schema=self._schema)
+
+    # -- type mapping (concept §5.2 table) ----------------------------------
+
+    def _arrow_type(self, col: ColumnInfo):
+        pa = self._pa
+        if col.kind == INT:
+            return pa.int32()
+        if col.kind == BIGINT:
+            return pa.int64()
+        if col.kind == FLOAT:
+            return pa.float32()
+        if col.kind == DOUBLE:
+            return pa.float64()
+        if col.kind == DECIMAL:
+            if col.precision and col.precision <= _MAX_DECIMAL128_PRECISION:
+                return pa.decimal128(col.precision, col.scale or 0)
+            return pa.float64()  # p > 38: downcast, documented
+        if col.kind == BOOL:
+            return pa.bool_()
+        if col.kind == DATE:
+            return pa.date32()
+        if col.kind == TIME:
+            return pa.time32("ms")
+        if col.kind == TIMESTAMP:
+            return pa.timestamp("us")
+        if col.kind == BINARY:
+            return pa.binary()
+        return pa.string()
+
+    # -- per-column value normalizers ---------------------------------------
+
+    def _normalizer(self, col: ColumnInfo, clean_text: Callable[[str], str]) -> Normalizer:
+        if col.kind == DECIMAL and col.precision and col.precision <= _MAX_DECIMAL128_PRECISION:
+            quantum = decimal.Decimal(1).scaleb(-(col.scale or 0))
+
+            def norm_decimal(v: Any) -> Optional[decimal.Decimal]:
+                if v is None:
+                    return None
+                d = v if isinstance(v, decimal.Decimal) else decimal.Decimal(str(v))
+                return d.quantize(quantum)
+
+            return norm_decimal
+
+        if col.kind in (DOUBLE, FLOAT) or col.kind == DECIMAL:  # DECIMAL p>38 -> float64
+            return lambda v: None if v is None else float(v)
+
+        if col.kind in (INT, BIGINT):
+            return lambda v: None if v is None else int(v)
+
+        if col.kind == BOOL:
+            return lambda v: None if v is None else bool(v)
+
+        if col.kind == DATE:
+
+            def norm_date(v: Any) -> Optional[datetime.date]:
+                if v is None:
+                    return None
+                if isinstance(v, datetime.datetime):
+                    return v.date()
+                if isinstance(v, datetime.date):
+                    return v
+                # loose drivers (sqlite, old FreeTDS) deliver ISO strings
+                return datetime.date.fromisoformat(str(v)[:10])
+
+            return norm_date
+
+        if col.kind == TIMESTAMP:
+
+            def norm_ts(v: Any) -> Optional[datetime.datetime]:
+                if v is None:
+                    return None
+                if isinstance(v, datetime.datetime):
+                    return v
+                if isinstance(v, datetime.date):
+                    return datetime.datetime(v.year, v.month, v.day)
+                return datetime.datetime.fromisoformat(str(v).replace("T", " "))
+
+            return norm_ts
+
+        if col.kind == TIME:
+
+            def norm_time(v: Any) -> Optional[int]:
+                if v is None:
+                    return None
+                if isinstance(v, datetime.time):
+                    ms = ((v.hour * 60 + v.minute) * 60 + v.second) * 1000 + v.microsecond // 1000
+                elif isinstance(v, (int, float)):
+                    ms = int(v)
+                else:
+                    t = datetime.time.fromisoformat(str(v))
+                    ms = ((t.hour * 60 + t.minute) * 60 + t.second) * 1000 + t.microsecond // 1000
+                return ms % _MS_PER_DAY
+
+            return norm_time
+
+        if col.kind == BINARY:
+            return lambda v: None if v is None else bytes(v)
+
+        # STRING / fallback — strip rules apply here (parquet parity with delimited)
+        def norm_string(v: Any) -> Optional[str]:
+            if v is None:
+                return None
+            return clean_text(v) if isinstance(v, str) else str(v)
+
+        return norm_string