avialsync 0.1.0b5__py3-none-any.whl

avialsync/__init__.py

@@ -0,0 +1,3 @@
+"""AvialSync root module."""
+
+__version__ = "0.1.0b5"

avialsync/__main__.py

@@ -0,0 +1,117 @@
+"""CLI entry point."""
+
+import argparse
+import locale
+import os
+import sys
+import time
+from importlib.resources import files
+from pathlib import Path
+
+from avialsync.runtime import configure_media_runtime
+
+
+def _parse_args(argv: list[str]) -> argparse.Namespace:
+    """Parse the supported AvialSync command-line arguments."""
+    parser = argparse.ArgumentParser(prog="avialsync")
+    parser.add_argument(
+        "command",
+        nargs="?",
+        choices=("demo", "open"),
+        help="demo: generate and load the inspection demo. open: load PATH.",
+    )
+    parser.add_argument(
+        "path",
+        nargs="?",
+        type=Path,
+        help="Session file (.avv) or a folder of recordings, for 'open'.",
+    )
+    parser.add_argument("--smoke-test", action="store_true", help=argparse.SUPPRESS)
+    args = parser.parse_args(argv)
+    if args.command == "open":
+        if args.path is None:
+            parser.error("open needs a path: avialsync open <session.avv|folder>")
+        if not args.path.exists():
+            # Refuse before Qt starts: a missing path is a typo, and reporting
+            # it in a dialog behind a window that has already opened is worse
+            # than reporting it on the terminal that issued the command.
+            parser.error(f"no such file or folder: {args.path}")
+    elif args.path is not None:
+        parser.error(f"'{args.command}' takes no path argument")
+    return args
+
+
+def main() -> None:
+    args = _parse_args(sys.argv[1:])
+    from PySide6.QtCore import QTimer
+    from PySide6.QtGui import QIcon
+    from PySide6.QtWidgets import QApplication
+
+    from avialsync.demo import DEMO_CHANNEL_COUNT, DEMO_VIDEO_COUNT, DemoLaunch
+    from avialsync.ui.main_window import MainWindow
+    from avialsync.ui.theme import load_saved_font_size, load_saved_theme
+
+    configure_media_runtime()
+    app = QApplication(sys.argv)
+    app_icon = QIcon(str(files("avialsync.resources").joinpath("avialsync.png")))
+    app.setWindowIcon(app_icon)
+
+    # Prevent Qt from stomping LC_NUMERIC (breaks libmpv float parsing)
+    locale.setlocale(locale.LC_NUMERIC, "C")
+
+    load_saved_theme(app)
+    load_saved_font_size(app)
+
+    win = MainWindow()
+    win.setWindowIcon(app_icon)
+    win.show()
+    demo_launch = DemoLaunch(win) if args.command == "demo" else None
+    if demo_launch is not None:
+        QTimer.singleShot(0, demo_launch.start)
+    elif args.command == "open":
+        # Deferred so the window is mapped before scanning reports progress.
+        QTimer.singleShot(0, lambda: win.open_path(args.path))
+
+    if args.smoke_test and demo_launch is None:
+        QTimer.singleShot(250, win.close)
+    elif args.smoke_test:
+        smoke_started = time.monotonic()
+        # The harness sets this below its own timeout so this deadline fires
+        # first and reports what the demo was still waiting for. A slow runner
+        # needs a longer budget than a workstation, so it is not a constant.
+        smoke_deadline = float(os.environ.get("AVIALSYNC_SMOKE_DEADLINE_S", "110"))
+
+        def poll_demo_ready() -> None:
+            panes = win.video_grid.panes
+            videos_ready = (
+                len(panes) == DEMO_VIDEO_COUNT
+                and all(pane._media_loaded for pane in panes)
+                and not win._pending_video_loads
+                and not win._video_load_jobs
+                and win._video_pane_initializing is None
+            )
+            data_ready = (
+                len(win.plot_pane.channels) == DEMO_CHANNEL_COUNT
+                and not win._pending_imports
+                and win._import_thread is None
+            )
+            if videos_ready and data_ready:
+                win.close()
+                return
+            if time.monotonic() - smoke_started >= smoke_deadline:
+                print(
+                    "Demo smoke timed out: "
+                    f"videos={len(panes)}/{DEMO_VIDEO_COUNT}, "
+                    f"channels={len(win.plot_pane.channels)}/{DEMO_CHANNEL_COUNT}",
+                    file=sys.stderr,
+                )
+                app.exit(2)
+                return
+            QTimer.singleShot(50, poll_demo_ready)
+
+        QTimer.singleShot(50, poll_demo_ready)
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    main()

avialsync/core/__init__.py

@@ -0,0 +1 @@
+"""Core module."""

avialsync/core/cache.py

@@ -0,0 +1,183 @@
+"""Cache management for sidecar files."""
+
+import json
+import os
+import shutil
+import tempfile
+import uuid
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+import xxhash
+
+from avialsync.core.errors import CacheError
+
+
+class CacheManager:
+    """Manages .avialcache sidecar directories with atomic writes and hardened keys."""
+
+    def __init__(
+        self,
+        loader_version: int = 1,
+        cache_config: Mapping[str, Any] | None = None,
+    ):
+        self.loader_version = loader_version
+        self._cache_config = dict(cache_config or {})
+
+    def _hash_file_edges(self, path: Path) -> str:
+        """Hash the first and last 64KB of the file."""
+        if path.is_dir():
+            # For directories, edge hashing is not applicable. The cache key
+            # will rely on the directory's mtime and size in generate_key.
+            return xxhash.xxh64(str(path.absolute()).encode("utf-8")).hexdigest()
+
+        size = path.stat().st_size
+        chunk_size = 64 * 1024
+
+        h = xxhash.xxh64()
+        with open(path, "rb") as f:
+            # First 64KB
+            chunk = f.read(chunk_size)
+            h.update(chunk)
+
+            # Last 64KB
+            if size > chunk_size:
+                seek_pos = max(chunk_size, size - chunk_size)
+                f.seek(seek_pos)
+                chunk = f.read(chunk_size)
+                h.update(chunk)
+
+        return h.hexdigest()
+
+    def generate_key(self, path: Path) -> str:
+        """Generate cache invalidation key per D-008."""
+        if not path.exists():
+            raise FileNotFoundError(f"Source file not found: {path}")
+
+        stat = path.stat()
+        edge_hash = self._hash_file_edges(path)
+
+        key_data = {
+            "path": str(path.absolute()),
+            "size": stat.st_size,
+            "mtime": stat.st_mtime,
+            "loader_version": self.loader_version,
+            "cache_config": self._cache_config,
+            "hash": edge_hash,
+        }
+
+        return json.dumps(key_data, sort_keys=True)
+
+    def get_cache_dir(self, source_path: Path) -> Path:
+        """Return the path to the sidecar cache directory."""
+        return source_path.with_name(source_path.name + ".avialcache")
+
+    def is_cache_valid(self, source_path: Path) -> bool:
+        """Check if the cache directory exists and the key matches."""
+        cache_dir = self.get_cache_dir(source_path)
+        self._recover_interrupted_swap(cache_dir)
+        meta_path = cache_dir / "meta.json"
+
+        if not cache_dir.exists() or not meta_path.exists():
+            return False
+
+        try:
+            with open(meta_path) as f:
+                cached_key = f.read()
+
+            current_key = self.generate_key(source_path)
+            return cached_key == current_key
+        except Exception:
+            return False
+
+    def get_temp_cache_dir(self, source_path: Path) -> Path:
+        """Get a temporary directory for writing cache. Ensure atomic swap later."""
+        parent = source_path.parent
+        temp_dir = tempfile.mkdtemp(prefix=".tmp_avialcache_", dir=parent)
+        return Path(temp_dir)
+
+    def commit_cache(self, source_path: Path, temp_dir: Path) -> None:
+        """Commit a replacement without discarding the last valid sidecar first."""
+        cache_dir = self.get_cache_dir(source_path)
+
+        # Write metadata key
+        meta_path = temp_dir / "meta.json"
+        with open(meta_path, "w") as f:
+            f.write(self.generate_key(source_path))
+
+        backup_dir: Path | None = None
+        try:
+            if cache_dir.exists():
+                backup_dir = cache_dir.with_name(f".{cache_dir.name}.backup-{uuid.uuid4().hex}")
+                os.rename(cache_dir, backup_dir)
+            os.rename(temp_dir, cache_dir)
+        except OSError as rename_error:
+            if backup_dir is not None and backup_dir.exists() and not cache_dir.exists():
+                try:
+                    os.rename(backup_dir, cache_dir)
+                except OSError:
+                    pass
+            # Renaming a *directory* can fail even when its files are writable:
+            # on Windows a sync client (OneDrive), search indexer or antivirus
+            # commonly holds a handle on the directory itself, which is normal
+            # under a synced Documents folder. Fall back to a file-level swap
+            # that never renames a directory.
+            try:
+                self._commit_in_place(source_path, cache_dir, temp_dir)
+            except OSError as swap_error:
+                shutil.rmtree(temp_dir, ignore_errors=True)
+                raise CacheError(
+                    f"Failed to commit cache: {rename_error}; "
+                    f"in-place fallback also failed: {swap_error}"
+                ) from swap_error
+            return
+        if backup_dir is not None:
+            try:
+                shutil.rmtree(backup_dir)
+            except OSError as error:
+                raise CacheError(f"Committed cache but could not remove backup: {error}") from error
+
+    def _commit_in_place(self, source_path: Path, cache_dir: Path, temp_dir: Path) -> None:
+        """Replace a sidecar's contents without renaming the directory.
+
+        Individual files can be replaced even while the enclosing directory is
+        held open. ``meta.json`` is removed first and written last, so an
+        interruption leaves the sidecar *invalid* (and therefore rebuilt) rather
+        than a mix of old and new arrays.
+        """
+        cache_dir.mkdir(parents=True, exist_ok=True)
+
+        meta_path = cache_dir / "meta.json"
+        if meta_path.exists():
+            meta_path.unlink()
+
+        staged = {item.name for item in temp_dir.iterdir() if item.is_file()}
+        for item in temp_dir.iterdir():
+            if item.is_file() and item.name != "meta.json":
+                os.replace(item, cache_dir / item.name)
+
+        # Drop arrays that the new build no longer produces.
+        for existing in cache_dir.iterdir():
+            if existing.is_file() and existing.name not in staged:
+                existing.unlink()
+
+        (cache_dir / "meta.json").write_text(self.generate_key(source_path), encoding="utf-8")
+        shutil.rmtree(temp_dir, ignore_errors=True)
+
+    @staticmethod
+    def _recover_interrupted_swap(cache_dir: Path) -> None:
+        """Restore the most recent valid-sidecar backup after a process interruption."""
+        if cache_dir.exists():
+            return
+        backups = sorted(
+            cache_dir.parent.glob(f".{cache_dir.name}.backup-*"),
+            key=lambda path: path.stat().st_mtime,
+            reverse=True,
+        )
+        if not backups:
+            return
+        try:
+            os.replace(backups[0], cache_dir)
+        except OSError:
+            return

avialsync/core/channel_reader.py

@@ -0,0 +1,165 @@
+"""Master-clock presentation of a cached pyramid channel.
+
+A :class:`~avialsync.core.pyramid.PyramidReader` speaks its source's own time
+base — whatever the acquisition system wrote.  Video sources have always been
+projected onto the master clock through a :class:`~avialsync.core.timeline.TimeMap`;
+P3.5 gives time-series sources the same treatment so a sensor recorded on an
+independent clock can be aligned without ever rewriting a cached sample.
+
+:class:`MappedChannelReader` is drop-in compatible with ``PyramidReader``: every
+method takes and returns **master** time.  Consumers (plot rows, readout, delta
+measurement, export, statistics) therefore need no mapping logic of their own.
+
+Only bounded results are converted.  ``mapped_columns`` deliberately stays in
+source time — converting a whole recording would allocate a second copy of it —
+so tick-rate consumers convert their scalar query instead via :attr:`time_map`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from dataclasses import dataclass
+from pathlib import Path
+
+import numpy as np
+
+from avialsync.core.pyramid import RAW_CHUNK_SAMPLES, PyramidReader
+from avialsync.core.timeline import TimeMap
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class ChannelKey:
+    """Stable identity of one channel: its source plus its name.
+
+    A channel name alone is not unique.  Two recordings of the same rig both
+    contain ``force_z``; keying plots, readouts, units, visibility, or exports by
+    the bare name lets one file silently overwrite or control the other's row.
+    Every such map is keyed by this pair instead (P3.5 P1 identity).
+    """
+
+    source_id: str
+    channel_id: str
+
+    def label(self, ambiguous: bool = False) -> str:
+        """Return the display name, qualified by source only when it must be."""
+        if not ambiguous or not self.source_id:
+            return self.channel_id
+        return f"{self.channel_id} · {Path(self.source_id).name}"
+
+
+def disambiguate(keys: list[ChannelKey]) -> dict[ChannelKey, str]:
+    """Return display labels, qualifying only names owned by more than one source."""
+    owners: dict[str, set[str]] = {}
+    for key in keys:
+        owners.setdefault(key.channel_id, set()).add(key.source_id)
+    return {key: key.label(len(owners[key.channel_id]) > 1) for key in keys}
+
+
+class MappedChannelReader:
+    """A pyramid channel presented on the master clock through its ``TimeMap``."""
+
+    def __init__(
+        self,
+        reader: PyramidReader,
+        time_map: TimeMap | None = None,
+        source_id: str = "",
+    ) -> None:
+        self._reader = reader
+        self._time_map = time_map if time_map is not None else TimeMap()
+        self._source_id = source_id
+
+    # ── Identity (delegated so existing grouping/lookup keeps working) ─
+
+    @property
+    def cache_dir(self) -> Path:
+        return self._reader.cache_dir
+
+    @property
+    def channel_id(self) -> str:
+        return self._reader.channel_id
+
+    @property
+    def source_id(self) -> str:
+        """The owning source's stable identifier (its path)."""
+        return self._source_id
+
+    @property
+    def key(self) -> ChannelKey:
+        """The ``(source_id, channel_id)`` identity of this channel."""
+        return ChannelKey(self._source_id, self._reader.channel_id)
+
+    @property
+    def source_reader(self) -> PyramidReader:
+        """The underlying source-time reader."""
+        return self._reader
+
+    @property
+    def time_map(self) -> TimeMap:
+        """The source-to-master mapping applied by every method here."""
+        return self._time_map
+
+    def set_mapping(self, offset: float, drift_ppm: float) -> None:
+        """Replace the offset/drift mapping in place.
+
+        Existing plot rows and readout rows keep their reader object, so a live
+        offset edit is a mapping change rather than a channel reload.
+        """
+        self._time_map.offset = float(offset)
+        self._time_map.drift_ppm = float(drift_ppm)
+
+    # ── Bounded read API, all in master time ──────────────────────────
+
+    def coverage(self) -> tuple[float, float] | None:
+        """Return this channel's master-time extent, or None when empty."""
+        bounds = self._reader.coverage()
+        if bounds is None:
+            return None
+        return self._time_map.to_master(bounds[0]), self._time_map.to_master(bounds[1])
+
+    def sample_count(self) -> int:
+        return self._reader.sample_count()
+
+    def sample_at(self, t_master: float) -> tuple[int, float] | None:
+        return self._reader.sample_at(self._time_map.to_source(t_master))
+
+    def value_at(self, t_master: float) -> float:
+        return self._reader.value_at(self._time_map.to_source(t_master))
+
+    def raw_slice(
+        self, t0_master: float, t1_master: float
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Return ``(t_master, v, gap)`` for a bounded master-time range."""
+        t, v, gap = self._reader.raw_slice(
+            self._time_map.to_source(t0_master), self._time_map.to_source(t1_master)
+        )
+        return self._time_map.to_master_array(t), v, gap
+
+    def iter_raw_chunks(
+        self,
+        chunk_size: int = RAW_CHUNK_SAMPLES,
+        t0: float | None = None,
+        t1: float | None = None,
+    ) -> Iterator[tuple[np.ndarray, np.ndarray]]:
+        """Yield bounded ``(t_master, v)`` chunks."""
+        source_t0 = None if t0 is None else self._time_map.to_source(t0)
+        source_t1 = None if t1 is None else self._time_map.to_source(t1)
+        for times, values in self._reader.iter_raw_chunks(chunk_size, source_t0, source_t1):
+            yield self._time_map.to_master_array(times), values
+
+    def query(
+        self, t0: float, t1: float, max_points: int
+    ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+        """Decimated master-time query; the result is bounded by *max_points*."""
+        t, vmin, vmax, gap = self._reader.query(
+            self._time_map.to_source(t0), self._time_map.to_source(t1), max_points
+        )
+        return self._time_map.to_master_array(t), vmin, vmax, gap
+
+    def mapped_columns(self) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+        """Return level-1 mmap views in **source** time.
+
+        Kept unmapped on purpose: converting the whole time column would
+        materialise the recording.  Convert the scalar query with
+        ``reader.time_map.to_source(t_master)`` instead.
+        """
+        return self._reader.mapped_columns()

avialsync/core/errors.py

@@ -0,0 +1,73 @@
+"""AvialSync exception hierarchy."""
+
+from typing import Any
+
+
+class AvialSyncError(Exception):
+    """Base exception for all AvialSync errors."""
+
+    pass
+
+
+class NonMonotonicTimeError(AvialSyncError):
+    """Raised when time series timestamps go backwards."""
+
+    def __init__(self, message: str, row: int, context: Any = None):
+        super().__init__(message)
+        self.row = row
+        self.context = context
+
+
+class SourceOpenError(AvialSyncError):
+    """Raised when a media or data source fails to open."""
+
+    pass
+
+
+class CacheError(AvialSyncError):
+    """Raised when the sidecar binary cache encounters an error."""
+
+    pass
+
+
+class CodecUnsupportedError(AvialSyncError):
+    """Raised when a video codec is not supported."""
+
+    pass
+
+
+class MissingColumnError(AvialSyncError):
+    """Raised when a required CSV column is missing."""
+
+    def __init__(self, column: str, available: list[str]):
+        self.column = column
+        self.available = available
+        super().__init__(f"Column '{column}' not found. Available: {', '.join(available)}")
+
+
+class FileUnreadableError(AvialSyncError):
+    """Raised when a file cannot be read or parsed."""
+
+    pass
+
+
+class LoaderContractError(AvialSyncError):
+    """Raised when a source plugin violates the frozen v1 ingest contract.
+
+    Distinct from :class:`SourceOpenError`: the file is readable, but the loader
+    returned something the importer cannot align — mismatched chunk lengths,
+    a missing declared channel, or chunks that disagree about their timestamps.
+    The actionable fix is in the plugin, not in the user's data.
+    """
+
+
+class SyncEvidenceError(AvialSyncError):
+    """Raised when synchronization evidence is malformed or insufficient."""
+
+    pass
+
+
+class SyncAmbiguityError(SyncEvidenceError):
+    """Raised when event evidence supports multiple equally valid alignments."""
+
+    pass

avialsync/core/inspection.py

@@ -0,0 +1,146 @@
+"""Headless dataclasses for import statistics and source integrity (D-020).
+
+No PySide6 imports — enforced by test_headless_core.py.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from typing import Any
+
+
+@dataclasses.dataclass(frozen=True)
+class ImportReport:
+    """Statistics collected by ImportWorker during one source import."""
+
+    rows_parsed: int = 0
+    rows_dropped_duplicate: int = 0
+    rows_dropped_nonmonotonic: int = 0
+    gap_count: int = 0
+    nan_count: int = 0
+    sentinel_count: int = 0
+    gap_locations: tuple[float, ...] = ()
+    import_timestamp: float = 0.0
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "rows_parsed": self.rows_parsed,
+            "rows_dropped_duplicate": self.rows_dropped_duplicate,
+            "rows_dropped_nonmonotonic": self.rows_dropped_nonmonotonic,
+            "gap_count": self.gap_count,
+            "nan_count": self.nan_count,
+            "sentinel_count": self.sentinel_count,
+            "gap_locations": list(self.gap_locations),
+            "import_timestamp": self.import_timestamp,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> ImportReport:
+        return cls(
+            rows_parsed=d.get("rows_parsed", 0),
+            rows_dropped_duplicate=d.get("rows_dropped_duplicate", 0),
+            rows_dropped_nonmonotonic=d.get("rows_dropped_nonmonotonic", 0),
+            gap_count=d.get("gap_count", 0),
+            nan_count=d.get("nan_count", 0),
+            sentinel_count=d.get("sentinel_count", 0),
+            gap_locations=tuple(d.get("gap_locations", [])),
+            import_timestamp=d.get("import_timestamp", 0.0),
+        )
+
+
+@dataclasses.dataclass(frozen=True)
+class IntegrityFlags:
+    """Anomaly flags for one loaded source.
+
+    Video flags (is_vfr, fps_mismatch) are set by MainWindow._load_video.
+    Data flags (has_gaps, fps_provisional) are set by ImportWorker.
+    drift_nonzero is set when the user assigns a non-zero drift to any source.
+    """
+
+    is_vfr: bool = False
+    fps_mismatch: bool = False
+    has_gaps: bool = False
+    drift_nonzero: bool = False
+    fps_provisional: bool = False
+
+    @property
+    def any_flag(self) -> bool:
+        return any(
+            [
+                self.is_vfr,
+                self.fps_mismatch,
+                self.has_gaps,
+                self.drift_nonzero,
+                self.fps_provisional,
+            ]
+        )
+
+    def flag_labels(self) -> list[str]:
+        labels = []
+        if self.is_vfr:
+            labels.append("Variable frame rate")
+        if self.fps_mismatch:
+            labels.append("Nominal ≠ measured fps")
+        if self.has_gaps:
+            labels.append("Data gaps detected")
+        if self.drift_nonzero:
+            labels.append("Non-zero drift set")
+        if self.fps_provisional:
+            labels.append("FPS is provisional (no video loaded)")
+        return labels
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "is_vfr": self.is_vfr,
+            "fps_mismatch": self.fps_mismatch,
+            "has_gaps": self.has_gaps,
+            "drift_nonzero": self.drift_nonzero,
+            "fps_provisional": self.fps_provisional,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> IntegrityFlags:
+        return cls(
+            is_vfr=d.get("is_vfr", False),
+            fps_mismatch=d.get("fps_mismatch", False),
+            has_gaps=d.get("has_gaps", False),
+            drift_nonzero=d.get("drift_nonzero", False),
+            fps_provisional=d.get("fps_provisional", False),
+        )
+
+
+@dataclasses.dataclass
+class SourceInspection:
+    """All collected inspection data for one loaded source.
+
+    Not frozen because import_config is a mutable dict.
+    """
+
+    path: str
+    loader_id: str = ""
+    import_config: dict[str, Any] = dataclasses.field(default_factory=dict)
+    import_report: ImportReport | None = None
+    integrity_flags: IntegrityFlags = dataclasses.field(default_factory=IntegrityFlags)
+    fps_binding: str = ""  # "provisional", "bound:<video_path>", or ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "loader_id": self.loader_id,
+            "import_config": dict(self.import_config),
+            "import_report": self.import_report.as_dict() if self.import_report else None,
+            "integrity_flags": self.integrity_flags.as_dict(),
+            "fps_binding": self.fps_binding,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> SourceInspection:
+        report_d = d.get("import_report")
+        return cls(
+            path=d.get("path", ""),
+            loader_id=d.get("loader_id", ""),
+            import_config=dict(d.get("import_config", {})),
+            import_report=ImportReport.from_dict(report_d) if report_d else None,
+            integrity_flags=IntegrityFlags.from_dict(d.get("integrity_flags", {})),
+            fps_binding=d.get("fps_binding", ""),
+        )