vikron-nt 0.1.0__py3-none-any.whl

vikron_nt/__init__.py

@@ -0,0 +1,40 @@
+"""Vikron NT: consumer-side Catalog registration and reading.
+
+Vikron independently develops and maintains this integration. Nautech Systems Pty Ltd and the NautilusTrader project have no affiliation with it and do not endorse or support it.
+"""
+from .data import (
+    Liquidation, OpenInterestUpdate, LastPriceUpdate,
+    PredictedFundingRateUpdate, register_custom_types,
+)
+from .official_v1 import prepare_catalog_v1
+from ._paths import catalog_root
+
+
+def prepare_catalog(path, *, fallback=None):
+    """Initialize an existing local catalog and return its absolute path.
+
+    Selects compatibility setup from the installed NautilusTrader version.
+    Call once per process, before using official Catalog or BacktestNode APIs.
+    The returned path keeps the caller's form: mapped network drives are not
+    expanded to UNC paths, which NautilusTrader's Rust catalog cannot open.
+
+    ``fallback="downcast"`` applies to catalog v1 on a 64-bit runtime (always the
+    case on Windows): a 16-byte fixed-point catalog is converted to an 8-byte
+    copy once and that copy is returned. The default raises instead, and
+    ``VIKRON_WIDE_PRECISION_FALLBACK=downcast`` sets the choice globally.
+    """
+    from .data import V2
+
+    if not V2:
+        return prepare_catalog_v1(path, fallback=fallback)
+    root = catalog_root(path)
+    if not (root / "data").is_dir():
+        raise ValueError(f"Not a Catalog directory: {root} (missing data directory)")
+    register_custom_types()
+    return str(root)
+
+__all__ = [
+    "register_custom_types", "prepare_catalog", "prepare_catalog_v1", "Liquidation",
+    "OpenInterestUpdate", "LastPriceUpdate",
+    "PredictedFundingRateUpdate",
+]

vikron_nt/_compat.py

@@ -0,0 +1,17 @@
+"""Supported Nautilus Python version families."""
+from packaging.specifiers import SpecifierSet
+from packaging.version import Version
+
+SUPPORTED_VERSIONS = {
+    1: SpecifierSet(">=1.226.0,<2.0.0"),
+    2: SpecifierSet(">=2.0.0rc6"),
+}
+
+
+def catalog_version(nautilus_version):
+    version = Version(nautilus_version)
+    for catalog, supported in SUPPORTED_VERSIONS.items():
+        if supported.contains(version, prereleases=True):
+            return catalog
+    ranges = "; ".join(f"v{catalog}: {spec}" for catalog, spec in SUPPORTED_VERSIONS.items())
+    raise ImportError(f"Unsupported Nautilus version {version}; supported ranges: {ranges}")

vikron_nt/_paths.py

@@ -0,0 +1,160 @@
+"""Filesystem helpers shared by the v1 and v2 catalog initialisers.
+
+Two Windows behaviours are handled here:
+
+* ``Path.resolve()`` expands a mapped network drive (``Z:\\``) into a UNC path
+  (``\\\\server\\share``). NautilusTrader's Rust catalog cannot open UNC paths,
+  so the caller's own form is preserved instead.
+* Creating a directory symlink needs ``SeCreateSymbolicLinkPrivilege`` (Developer
+  Mode or an elevated terminal). When that fails, an NTFS *junction*
+  (``mklink /J``) is created instead: it needs no privilege and behaves the same
+  for NautilusTrader, which only needs to resolve the alias to a directory.
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+
+__all__ = [
+    "catalog_root", "create_directory_link", "is_directory_link",
+    "remove_directory_link", "normalize",
+]
+
+# Symlink creation errors that justify the junction fallback on Windows:
+# 1314 = privilege not held, 5 = access denied, 1 = unspecified.
+_WINDOWS_LINK_ERRORS = frozenset({1, 5, 1314})
+
+
+def normalize(path: str | os.PathLike[str]) -> str:
+    """Return a comparison key for *path* that survives junctions and drive maps."""
+    return os.path.normcase(os.path.abspath(os.fspath(path)))
+
+
+_mapped_shares: dict[str, Path] = {}
+
+
+def _net_use_mappings() -> dict[str, str]:
+    """Return ``{r'\\\\server\\share': 'Z:'}`` for the current user's mappings."""
+    try:
+        result = subprocess.run(["net", "use"], capture_output=True, text=True,
+                                encoding="utf-8", errors="replace",
+                                stdin=subprocess.DEVNULL, timeout=30)
+    except (OSError, subprocess.SubprocessError):  # pragma: no cover - `net.exe` unavailable
+        return {}
+    mappings: dict[str, str] = {}
+    for line in (result.stdout or "").splitlines():
+        tokens = line.split()
+        for index, token in enumerate(tokens):
+            if len(token) == 2 and token[1] == ":" and token[0].isalpha():
+                for following in tokens[index + 1:]:
+                    if following.startswith("\\\\"):
+                        mappings[following.rstrip("\\").lower()] = token.upper()
+                        break
+    return mappings
+
+
+def map_unc_to_drive(path: Path) -> Path:
+    """Return a drive-letter path for a UNC path, mapping the share if needed.
+
+    NautilusTrader's Rust catalog cannot open ``\\\\server\\share`` paths, so the
+    share is mapped to a free drive letter (no privilege required, and the same
+    thing Explorer does). A share that is already mapped is reused.
+    """
+    text = str(path)
+    if os.name != "nt" or not text.startswith("\\\\"):
+        return path
+    server, _, remainder = text[2:].partition("\\")
+    share, _, rest = remainder.partition("\\")
+    if not server or not share:
+        return path
+    key = f"\\\\{server}\\{share}".lower()
+    cached = _mapped_shares.get(key)
+    if cached is not None:
+        return cached / rest
+
+    mappings = _net_use_mappings()
+    if key in mappings:
+        drive = Path(f"{mappings[key]}\\")
+        _mapped_shares[key] = drive
+        return drive / rest
+
+    for letter in "ZYXWVUTSRQPONMLKJIHGFED":
+        if Path(f"{letter}:\\").exists():
+            continue
+        try:
+            result = subprocess.run(["net", "use", f"{letter}:", f"\\\\{server}\\{share}",
+                                     "/persistent:no"], capture_output=True, text=True,
+                                    encoding="utf-8", errors="replace",
+                                    stdin=subprocess.DEVNULL, timeout=60)
+        except (OSError, subprocess.SubprocessError):
+            # `net use` failed or hung (e.g. it wanted credentials): try the
+            # next letter, and never block the caller on an interactive prompt.
+            continue
+        if result.returncode != 0:
+            continue
+        drive = Path(f"{letter}:\\")
+        _mapped_shares[key] = drive
+        return drive / rest
+    raise OSError(f"could not map {server}\\{share} to a drive letter; "
+                  "map it manually with `net use Z: \\\\server\\share`")
+
+
+def catalog_root(path: str | os.PathLike[str]) -> Path:
+    """Return an absolute catalog root without resolving links or drive maps.
+
+    UNC paths are mapped to a drive letter on Windows because the Rust catalog
+    cannot open them. Raises ``FileNotFoundError`` when the path does not exist,
+    matching the previous ``Path.resolve(strict=True)`` behaviour.
+    """
+    root = Path(os.path.abspath(os.path.expanduser(os.fspath(path))))
+    root = map_unc_to_drive(root)
+    if not root.exists():
+        raise FileNotFoundError(f"Catalog directory does not exist: {root}")
+    return root
+
+
+def is_directory_link(path: Path) -> bool:
+    """Return True for a symlink or an NTFS junction."""
+    if path.is_symlink():
+        return True
+    is_junction = getattr(path, "is_junction", None)
+    try:
+        return bool(is_junction is not None and is_junction())
+    except OSError:  # pragma: no cover - unreadable reparse point
+        return False
+
+
+def _create_junction(alias: Path, target: Path) -> None:
+    result = subprocess.run(
+        ["cmd", "/c", "mklink", "/J", str(alias), str(target.resolve())],
+        capture_output=True, text=True, encoding="utf-8", errors="replace",
+    )
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout or "").strip()
+        raise OSError(f"failed to create junction {alias} -> {target}: {detail}")
+
+
+def create_directory_link(alias: Path, target: Path) -> None:
+    """Point *alias* at the *target* directory.
+
+    Tries a relative symlink first. On Windows, when symlink creation is denied,
+    falls back to an NTFS junction so that unprivileged accounts work too.
+    """
+    try:
+        alias.symlink_to(os.path.relpath(target, alias.parent), target_is_directory=True)
+        return
+    except OSError as exc:
+        if os.name != "nt" or getattr(exc, "winerror", None) not in _WINDOWS_LINK_ERRORS:
+            raise
+    _create_junction(alias, target)
+
+
+def remove_directory_link(path: Path) -> None:
+    """Remove a symlink or junction without touching the directory it points at."""
+    if path.is_symlink():
+        path.unlink()
+    elif is_directory_link(path):
+        os.rmdir(path)  # junction: removes the reparse point only
+    else:
+        raise ValueError(f"{path} is not a directory link")

vikron_nt/data.py

@@ -0,0 +1,142 @@
+import json
+from decimal import Decimal
+from importlib.metadata import version
+
+import pyarrow as pa
+
+from ._compat import catalog_version
+
+NAUTILUS_VERSION = version("nautilus_trader")
+V2 = catalog_version(NAUTILUS_VERSION) == 2
+if V2:
+    from nautilus_trader.model import InstrumentId
+    BaseData = object
+else:
+    from nautilus_trader.core.data import Data as BaseData
+    from nautilus_trader.model.identifiers import InstrumentId
+
+
+class _Observation(BaseData):
+    fields = ()
+    decimals = ()
+
+    def __init__(self, instrument_id, ts_event, ts_init, **values):
+        if set(values) != set(self.fields):
+            raise ValueError(f"{type(self).__name__} requires fields {self.fields}")
+        self.instrument_id = InstrumentId.from_str(str(instrument_id))
+        self._ts_event = int(ts_event)
+        self._ts_init = int(ts_init)
+        if not (0 <= self._ts_event < 2**64 and 0 <= self._ts_init < 2**64):
+            raise ValueError("invalid event/init timestamps")
+        for name, value in values.items():
+            setattr(self, name, Decimal(str(value)) if name in self.decimals else value)
+
+    @property
+    def ts_event(self):
+        return self._ts_event
+
+    @property
+    def ts_init(self):
+        return self._ts_init
+
+    @classmethod
+    def type_name_static(cls):
+        return f"Vikron{cls.__name__}"
+
+    def to_dict(self):
+        return dict(
+            type=self.type_name_static(), instrument_id=str(self.instrument_id),
+            ts_event=self.ts_event, ts_init=self.ts_init,
+            **{name: str(getattr(self, name)) if name in self.decimals else getattr(self, name)
+               for name in self.fields},
+        )
+
+    @classmethod
+    def from_dict(cls, values):
+        values = dict(values)
+        if values.pop("type", cls.type_name_static()) != cls.type_name_static():
+            raise ValueError("unexpected custom data type")
+        return cls(**values)
+
+    def to_json(self):
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, value):
+        return cls.from_dict(value if isinstance(value, dict) else json.loads(value))
+
+    @classmethod
+    def arrow_schema_py(cls):
+        timestamp = pa.timestamp("ns", tz="UTC") if V2 else pa.uint64()
+        return pa.schema([
+            pa.field("payload", pa.string(), nullable=False),
+            pa.field("ts_event", timestamp, nullable=False),
+            pa.field("ts_init", timestamp, nullable=False),
+        ])
+
+    def encode_record_batch_py(self, items):
+        return pa.RecordBatch.from_arrays([
+            pa.array([item.to_json() for item in items]),
+            pa.array([item.ts_event for item in items], type=pa.int64() if V2 else pa.uint64()).cast(self.arrow_schema_py().field("ts_event").type),
+            pa.array([item.ts_init for item in items], type=pa.int64() if V2 else pa.uint64()).cast(self.arrow_schema_py().field("ts_init").type),
+        ], schema=self.arrow_schema_py())
+
+    @classmethod
+    def decode_record_batch_py(cls, metadata, batch):
+        times = batch.column("ts_init").cast(pa.int64() if V2 else pa.uint64()).to_pylist()
+        events = batch.column("ts_event").cast(pa.int64() if V2 else pa.uint64()).to_pylist()
+        rows = []
+        for payload, event, init in zip(batch.column("payload").to_pylist(), events, times):
+            values = json.loads(payload)
+            values.update(ts_event=event, ts_init=init)
+            rows.append(cls.from_dict(values))
+        return rows
+
+
+class Liquidation(_Observation):
+    fields = ("source_id", "side", "price", "size")
+    decimals = ("price", "size")
+
+
+class OpenInterestUpdate(_Observation):
+    fields = ("open_interest",)
+    decimals = fields
+
+
+class LastPriceUpdate(_Observation):
+    fields = ("price",)
+    decimals = fields
+
+
+class PredictedFundingRateUpdate(_Observation):
+    fields = ("rate", "funding_timestamp")
+    decimals = ("rate",)
+
+
+CUSTOM_TYPES = (
+    Liquidation, OpenInterestUpdate,
+    LastPriceUpdate, PredictedFundingRateUpdate,
+)
+_registered = False
+
+
+def register_custom_types():
+    """Register once per interpreter, before querying/subscribing to custom data."""
+    global _registered
+    if _registered:
+        return
+    if V2:
+        from nautilus_trader.model import register_custom_data_class
+        for cls in CUSTOM_TYPES:
+            register_custom_data_class(cls)
+    else:
+        from nautilus_trader.serialization import register_serializable_type
+        from nautilus_trader.serialization.arrow.serializer import register_arrow
+        for cls in CUSTOM_TYPES:
+            register_serializable_type(cls, cls.to_dict, cls.from_dict)
+            register_arrow(
+                cls, cls.arrow_schema_py(),
+                encoder=lambda obj: obj.encode_record_batch_py([obj]),
+                decoder=lambda batch, cls=cls: cls.decode_record_batch_py({}, batch),
+            )
+    _registered = True

vikron_nt/downcast.py

@@ -0,0 +1,278 @@
+"""Downcast a Downloader catalog-v1 from 16-byte to 8-byte fixed point.
+
+Official Downloader v1 catalogs store ``price``/``size``/``value`` as 16-byte
+(128-bit) fixed-point integers scaled by 1e-16. NautilusTrader's Python 1.x
+wheels for Windows are always built with 64-bit precision
+(``PRECISION_BYTES == 8``, scale 1e-9), so those files abort the Rust catalog
+instead of raising. This module rewrites the same catalog with 8-byte columns,
+keeping the decimal value (raw / 1e7) and every other column untouched, which
+lets Windows read official v1 catalogs.
+
+    python -m vikron_nt.downcast SRC DST
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+WIDE = 16                      # bytes of the stored fixed point
+NARROW = 8                     # bytes the 64-bit runtime expects
+WIDE_DECIMALS = 16             # 16-byte values are scaled by 1e-16
+NARROW_DECIMALS = 9            # 8-byte values are scaled by 1e-9
+SCALE = 10 ** (WIDE_DECIMALS - NARROW_DECIMALS)   # 1e7
+
+
+def _i128_to_i64(raw: bytes) -> int:
+    """Rescale a 128-bit fixed-point integer to 64-bit, rounding half away from zero."""
+    value = int.from_bytes(raw, "little", signed=True)
+    quotient, remainder = divmod(abs(value), SCALE)
+    if 2 * remainder >= SCALE:
+        quotient += 1
+    return -quotient if value < 0 else quotient
+
+
+def _column_to_narrow(column):
+    """Convert one fixed_size_binary[16] column to fixed_size_binary[8].
+
+    Fast path: reinterpret the buffer as 128-bit little-endian words and do the
+    rescale with uint64 arithmetic after checking the rounded int64 range.
+    Wrapped intermediate sums are recomputed with Python integers; columns with
+    nulls and negative values use the per-value path.
+    """
+    import numpy as np
+    import pyarrow as pa
+
+    if isinstance(column, pa.ChunkedArray):
+        column = column.chunk(0) if column.num_chunks == 1 else column.combine_chunks()
+
+    if column.null_count == 0:
+        buffers = column.buffers()
+        raw = buffers[1] if len(buffers) > 1 else None
+        if raw is not None and len(raw) == len(column) * WIDE:
+            words = np.frombuffer(raw, dtype="<u8")
+            low = words[0::2].astype(np.uint64)
+            high = words[1::2].astype(np.uint64)
+            if not (high & np.uint64(1 << 63)).any():
+                # Check before uint64 arithmetic: the scaled result can wrap to
+                # a small positive number, so checking only the output is unsafe.
+                max_raw = (2 ** 63 - 1) * SCALE + SCALE // 2 - 1
+                max_high, max_low = divmod(max_raw, 1 << 64)
+                if ((high > max_high) | ((high == max_high) & (low > max_low))).any():
+                    raise OverflowError("downcast value out of int64 range")
+                half = np.uint64(SCALE // 2)
+                quotient = np.uint64((1 << 64) // SCALE)
+                remainder = np.uint64((1 << 64) % SCALE)
+                carry = high * remainder + low + half
+                wrapped = carry < low
+                out = high * quotient + carry // np.uint64(SCALE)
+                if wrapped.any():
+                    for index in np.nonzero(wrapped)[0]:
+                        value = (int(high[index]) << 64) + int(low[index]) + SCALE // 2
+                        out[index] = np.uint64(value // SCALE)
+                narrowed = out.astype("<i8")
+                return pa.Array.from_buffers(
+                    pa.binary(NARROW), len(column),
+                    [None, pa.py_buffer(narrowed.tobytes())])
+
+    out = []
+    for raw_value in column.to_pylist():
+        if raw_value is None:
+            out.append(None)
+            continue
+        converted = _i128_to_i64(raw_value)
+        if not -(2 ** 63) <= converted < 2 ** 63:
+            raise OverflowError(f"downcast value out of int64 range: {converted}")
+        out.append(converted.to_bytes(NARROW, "little", signed=True))
+    return pa.array(out, type=pa.binary(NARROW))
+
+
+def _narrow_schema(schema):
+    import pyarrow as pa
+
+    fields = []
+    for field in schema:
+        if pa.types.is_fixed_size_binary(field.type) and field.type.byte_width == WIDE:
+            fields.append(pa.field(field.name, pa.binary(NARROW), field.nullable,
+                                   field.metadata))
+        else:
+            fields.append(field)
+    return pa.schema(fields, metadata=_narrow_metadata(schema.metadata))
+
+
+def _narrow_metadata(metadata):
+    """Rewrite the ``*_precision`` schema metadata from 16 decimals to 9.
+
+    NautilusTrader rebuilds ``Price``/``Quantity`` from these values when it
+    decodes a file, so leaving ``price_precision=16`` makes it parse an 8-byte
+    value with a 16-decimal scale and abort with "precision exceeded maximum".
+    """
+    if not metadata:
+        return metadata
+    narrowed = {}
+    for key, value in metadata.items():
+        name = key.decode() if isinstance(key, bytes) else key
+        text = value.decode() if isinstance(value, bytes) else value
+        if name.endswith("precision") and text == str(WIDE_DECIMALS):
+            text = str(NARROW_DECIMALS)
+        narrowed[key] = text
+    return narrowed
+
+
+def _wide_columns(table):
+    return [name for name, field in zip(table.column_names, table.schema)
+            if str(field.type) == f"fixed_size_binary[{WIDE}]"]
+
+
+def narrow_table(table):
+    """Return *table* with its 16-byte fixed-point columns narrowed to 8 bytes.
+
+    This is the in-memory counterpart of :func:`downcast_file`: useful for a
+    direct read on a 64-bit runtime without writing a converted catalog. Tables
+    that carry no 16-byte columns are returned unchanged.
+    """
+    import pyarrow as pa
+
+    wide = _wide_columns(table)
+    if not wide:
+        return table
+    arrays = list(table.columns)
+    for name in wide:
+        arrays[table.column_names.index(name)] = _column_to_narrow(table.column(name))
+    return pa.Table.from_arrays(arrays, schema=_narrow_schema(table.schema))
+
+
+def _is_complete(path: Path) -> bool:
+    """True when *path* is a readable parquet file (guards against half-written copies)."""
+    try:
+        import pyarrow.parquet as pq
+
+        return pq.ParquetFile(path).metadata.num_rows >= 0
+    except Exception:  # noqa: BLE001 - unreadable file means "convert again"
+        return False
+
+
+def _replace(src: Path, dst: Path) -> None:
+    """Move *src* onto *dst* atomically (same filesystem)."""
+    os.replace(src, dst)
+
+
+def downcast_file(src: Path, dst: Path) -> bool:
+    """Rewrite one parquet file. Returns False when the file had nothing to change."""
+    import pyarrow.parquet as pq
+
+    table = pq.read_table(src)
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    staging = dst.with_name(dst.name + ".part")
+    if not _wide_columns(table):
+        shutil.copy2(src, staging)
+        _replace(staging, dst)
+        return False
+
+    narrowed = narrow_table(table)
+    # Keep zstd: the Downloader writes zstd, and snappy would inflate the copy.
+    pq.write_table(narrowed, staging, compression="zstd")
+    _replace(staging, dst)
+    return True
+
+
+_narrow_cache: dict[str, Path] = {}
+
+
+def ensure_narrow_catalog(src, *, cache_root=None) -> tuple[Path, bool]:
+    """Return an 8-byte copy of *src*, converting (or refreshing) it as needed.
+
+    This is the runtime fallback for a 16-byte catalog on a 64-bit NautilusTrader
+    build (always the case on Windows). The copy lives beside the catalog when
+    that directory is writable, otherwise under ``%LOCALAPPDATA%/vikron``; the
+    conversion is incremental, so a daily append only rewrites the new files.
+
+    Returns ``(path, converted)``: ``converted`` is False when this process had
+    already prepared the same source.
+    """
+    source = Path(src)
+    if not (source / "data").is_dir():
+        raise ValueError(f"Not a Catalog directory: {source} (missing data directory)")
+
+    key = str(source).lower()
+    cached = _narrow_cache.get(key)
+    if cached is not None:
+        return cached, False
+
+    sibling = source.with_name(source.name + "-int64")
+    try:
+        sibling.mkdir(parents=True, exist_ok=True)
+        probe = sibling / ".write-probe"
+        probe.write_text("", encoding="utf-8")
+        probe.unlink()
+        target = sibling
+    except OSError:
+        import hashlib
+        import os
+        import tempfile
+        base = Path(cache_root or os.environ.get("LOCALAPPDATA")
+                    or tempfile.gettempdir()) / "vikron" / "catalog-int64"
+        digest = hashlib.sha1(str(source).lower().encode("utf-8")).hexdigest()[:12]
+        target = base / f"{source.name}-{digest}"
+        target.mkdir(parents=True, exist_ok=True)
+    downcast_catalog(source, target, incremental=True, quiet=True)
+    _narrow_cache[key] = target
+    return target, True
+
+
+def downcast_catalog(src, dst=None, *, overwrite: bool = False,
+                     incremental: bool = False, quiet: bool = False) -> Path:
+    """Downcast every parquet file under *src* into *dst* (default ``<src>-int64``).
+
+    ``incremental`` leaves files already present in *dst* alone, which is what a
+    daily-append catalog needs: only the new day is converted. ``quiet`` silences
+    the summary line for library callers.
+    """
+    source = Path(src)
+    target = Path(dst) if dst is not None else source.with_name(source.name + "-int64")
+    if not (source / "data").is_dir():
+        raise ValueError(f"Not a Catalog directory: {source} (missing data directory)")
+    if target.exists() and any(target.rglob("*.parquet")) and not (overwrite or incremental):
+        raise FileExistsError(
+            f"{target} already holds parquet files; pass overwrite=True or incremental=True")
+
+    converted = copied = skipped = 0
+    for path in sorted((source / "data").rglob("*.parquet")):
+        destination = target / path.relative_to(source)
+        if incremental and destination.exists() and _is_complete(destination):
+            skipped += 1
+            continue
+        changed = downcast_file(path, destination)
+        converted += int(changed)
+        copied += int(not changed)
+    for extra in source.glob("*.json"):
+        shutil.copy2(extra, target / extra.name)
+    suffix = f", skipped {skipped} existing file(s)" if skipped else ""
+    if not quiet:
+        print(f"downcast {converted} file(s), copied {copied} unchanged file(s){suffix} -> {target}")
+    return target
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("src", help="catalog-v1 root containing data/")
+    ap.add_argument("dst", nargs="?", help="destination root (default: <src>-int64)")
+    ap.add_argument("--overwrite", action="store_true",
+                    help="rewrite every file, including ones already converted")
+    ap.add_argument("--incremental", action="store_true",
+                    help="only convert files missing from the destination (daily appends)")
+    args = ap.parse_args(argv)
+    try:
+        downcast_catalog(args.src, args.dst, overwrite=args.overwrite,
+                         incremental=args.incremental)
+    except (ValueError, FileExistsError, OverflowError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())