xconv2 0.0.0__py3-none-any.whl

xconv2/__init__.py

@@ -0,0 +1,19 @@
+"""xconv2 package."""
+
+from __future__ import annotations
+
+from importlib.metadata import version, PackageNotFoundError
+
+
+try:
+    __version__ = version("xconv2")
+except PackageNotFoundError as exc:
+    msg = (
+        "xconv2 package not found, please run `pip install -e .` before "
+        "importing the package."
+    )
+    raise PackageNotFoundError(
+        msg,
+    ) from exc
+
+

xconv2/aaa/aaa_config.py

@@ -0,0 +1,64 @@
+from pathlib import Path
+import json
+import warnings
+from urllib.parse import urlparse
+
+def get_locations(config_file=None):
+    """ 
+    Read config file (config.json) and find usable locations.
+    We are expecting a file in the "minio configuration format",
+    and we expect it in either ~/.mc/ or in ~/.config/cfview.
+    """
+
+    if config_file is None:
+        candidates = [
+            Path.home() / '.mc/config.json',
+            Path.home() / '.config/cfview/config.json',
+        ]
+        config_file = next((path for path in candidates if path.is_file()), None)
+        if config_file is None:
+            return None
+    else:
+        config_file = Path(config_file).expanduser()
+        if not config_file.is_file():
+            raise FileNotFoundError(f'Configuration file not found: {config_file}')
+
+    try:
+        with open(config_file, 'r', encoding='utf-8') as jfile:
+            jdata = json.load(jfile)
+        jd = jdata['aliases']
+    except (json.JSONDecodeError, KeyError, TypeError) as exc:
+        raise ValueError(f'Malformed configuration file: {config_file}') from exc
+
+    locations = {}
+    servers = {}
+    for k, v in jd.items():
+        api = v.get('api')
+        if (api or '').lower() != 's3v4':
+            warnings.warn(f'WARNING: Found unexpected S3 API {api} for {k} in configuration file {config_file}')
+        else:
+            locations[k] = v
+
+            parsed = urlparse(v.get('url', ''))
+            host = parsed.netloc or parsed.path
+            if host:
+                servers[host] = k
+
+    return locations, servers
+
+
+def get_user_config(target, config_file=None):
+    """
+    Obtain credentials from user configuration file
+    """
+    if config_file is None:
+        config_file = Path.home()/'.mc/config.json'
+    options = get_locations(config_file)
+    if options is None:
+        raise ValueError(f'No configuration file found for target [{target}]')
+
+    locations, _ = options
+    try:
+        return locations[target]
+    except KeyError:
+        raise ValueError(f'Target [{target}] not found in ~/{config_file}')

xconv2/animation_protocol.py

@@ -0,0 +1,189 @@
+"""Animation protocol types and message helpers for xconv2 streaming animation."""
+
+from __future__ import annotations
+
+import base64
+import json
+import pickle
+import time
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class AnimationMetadata:
+    """Metadata for an animation session."""
+
+    session_id: str | None
+    total_frames: int | None
+    fps_hint: float | None
+    title_template: str | None
+    plot_kind: str
+    levels_locked: bool
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to payload dict."""
+        return {
+            "session_id": self.session_id,
+            "total_frames": self.total_frames,
+            "fps_hint": self.fps_hint,
+            "title_template": self.title_template,
+            "plot_kind": self.plot_kind,
+            "levels_locked": self.levels_locked,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AnimationMetadata:
+        """Construct from payload dict."""
+        return cls(
+            session_id=data.get("session_id"),
+            total_frames=data.get("total_frames"),
+            fps_hint=data.get("fps_hint"),
+            title_template=data.get("title_template"),
+            plot_kind=str(data.get("plot_kind", "contour")),
+            levels_locked=bool(data.get("levels_locked", False)),
+        )
+
+
+@dataclass
+class AnimationFrame:
+    """A single frame in an animation stream."""
+
+    request_id: str
+    session_id: str | None
+    frame_index: int
+    total_frames: int | None
+    png_bytes: bytes
+    frame_value_label: str | None
+    emitted_at: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to payload dict (bytes included as-is)."""
+        return {
+            "request_id": self.request_id,
+            "session_id": self.session_id,
+            "frame_index": self.frame_index,
+            "total_frames": self.total_frames,
+            "png_bytes": self.png_bytes,
+            "frame_value_label": self.frame_value_label,
+            "emitted_at": self.emitted_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AnimationFrame:
+        """Construct from payload dict."""
+        return cls(
+            request_id=str(data.get("request_id", "")),
+            session_id=data.get("session_id"),
+            frame_index=int(data.get("frame_index", 0)),
+            total_frames=data.get("total_frames"),
+            png_bytes=bytes(data.get("png_bytes", b"")),
+            frame_value_label=data.get("frame_value_label"),
+            emitted_at=float(data.get("emitted_at", time.time())),
+        )
+
+
+@dataclass
+class AnimationStart:
+    """Animation session start notification."""
+
+    request_id: str
+    session_id: str | None
+    total_frames: int | None
+    fps_hint: float | None
+    title_template: str | None
+    started_at: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to payload dict."""
+        return {
+            "request_id": self.request_id,
+            "session_id": self.session_id,
+            "total_frames": self.total_frames,
+            "fps_hint": self.fps_hint,
+            "title_template": self.title_template,
+            "started_at": self.started_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AnimationStart:
+        """Construct from payload dict."""
+        return cls(
+            request_id=str(data.get("request_id", "")),
+            session_id=data.get("session_id"),
+            total_frames=data.get("total_frames"),
+            fps_hint=data.get("fps_hint"),
+            title_template=data.get("title_template"),
+            started_at=float(data.get("started_at", time.time())),
+        )
+
+
+@dataclass
+class AnimationEnd:
+    """Animation session completion notification."""
+
+    request_id: str
+    session_id: str | None
+    frames_emitted: int
+    completed_at: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to payload dict."""
+        return {
+            "request_id": self.request_id,
+            "session_id": self.session_id,
+            "frames_emitted": self.frames_emitted,
+            "completed_at": self.completed_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AnimationEnd:
+        """Construct from payload dict."""
+        return cls(
+            request_id=str(data.get("request_id", "")),
+            session_id=data.get("session_id"),
+            frames_emitted=int(data.get("frames_emitted", 0)),
+            completed_at=float(data.get("completed_at", time.time())),
+        )
+
+
+@dataclass
+class AnimationError:
+    """Animation session error notification."""
+
+    request_id: str
+    session_id: str | None
+    frame_index: int | None
+    error: str
+    failed_at: float
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to payload dict."""
+        return {
+            "request_id": self.request_id,
+            "session_id": self.session_id,
+            "frame_index": self.frame_index,
+            "error": self.error,
+            "failed_at": self.failed_at,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AnimationError:
+        """Construct from payload dict."""
+        return cls(
+            request_id=str(data.get("request_id", "")),
+            session_id=data.get("session_id"),
+            frame_index=data.get("frame_index"),
+            error=str(data.get("error", "")),
+            failed_at=float(data.get("failed_at", time.time())),
+        )
+
+
+def encode_payload(payload: dict[str, Any]) -> str:
+    """Encode a payload dict as base64(pickle) for stdout transmission."""
+    return base64.b64encode(pickle.dumps(payload)).decode("ascii")
+
+
+def decode_payload(encoded: str) -> dict[str, Any]:
+    """Decode a base64(pickle) payload from stdout."""
+    return pickle.loads(base64.b64decode(encoded.encode("ascii")))

xconv2/animation_session.py

@@ -0,0 +1,165 @@
+"""Backend animation session controller for xconv2."""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from enum import Enum
+
+logger = logging.getLogger(__name__)
+
+
+class AnimationPlaybackState(Enum):
+    """Playback state for an animation session."""
+
+    IDLE = "idle"
+    STREAMING = "streaming"
+    BUFFERED = "buffered"
+    PLAYING = "playing"
+    PAUSED = "paused"
+    STOPPED = "stopped"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+
+@dataclass
+class AnimationSession:
+    """Backend state for a single animation session."""
+
+    request_id: str
+    session_id: str | None = None
+    total_frames: int | None = None
+    fps_hint: float | None = None
+    title_template: str | None = None
+    frames: list[bytes] = field(default_factory=list)
+    playback_state: AnimationPlaybackState = field(default=AnimationPlaybackState.IDLE)
+    current_frame_index: int = 0
+    error_message: str | None = None
+    started_at: float | None = None
+    completed_at: float | None = None
+
+    def add_frame(self, png_bytes: bytes) -> None:
+        """Append a frame to the buffer."""
+        if self.playback_state == AnimationPlaybackState.FAILED:
+            logger.warning("Ignoring frame for failed session %s", self.request_id)
+            return
+        self.frames.append(png_bytes)
+        if self.playback_state == AnimationPlaybackState.IDLE:
+            self.playback_state = AnimationPlaybackState.STREAMING
+
+    def frame_count(self) -> int:
+        """Return number of buffered frames."""
+        return len(self.frames)
+
+    def get_frame(self, index: int) -> bytes | None:
+        """Get frame at index, or None if out of bounds."""
+        if 0 <= index < len(self.frames):
+            return self.frames[index]
+        return None
+
+    def mark_started(self, total_frames: int | None, fps_hint: float | None, title_template: str | None) -> None:
+        """Mark session as started with metadata."""
+        self.started_at = time.time()
+        self.total_frames = total_frames
+        self.fps_hint = fps_hint or 4.0
+        self.title_template = title_template
+        self.playback_state = AnimationPlaybackState.STREAMING
+
+    def mark_completed(self) -> None:
+        """Mark session as completed."""
+        if self.playback_state != AnimationPlaybackState.FAILED:
+            self.playback_state = AnimationPlaybackState.BUFFERED
+        self.completed_at = time.time()
+        logger.info(
+            "Animation session complete request_id=%s session_id=%s frames=%d",
+            self.request_id,
+            self.session_id,
+            len(self.frames),
+        )
+
+    def mark_failed(self, error: str) -> None:
+        """Mark session as failed."""
+        self.playback_state = AnimationPlaybackState.FAILED
+        self.error_message = error
+        logger.error("Animation session failed request_id=%s: %s", self.request_id, error)
+
+    def start_playback(self) -> None:
+        """Transition from buffered to playing."""
+        if self.playback_state == AnimationPlaybackState.BUFFERED:
+            self.playback_state = AnimationPlaybackState.PLAYING
+            self.current_frame_index = 0
+            logger.info("Playback started for request_id=%s", self.request_id)
+
+    def pause_playback(self) -> None:
+        """Pause playback."""
+        if self.playback_state == AnimationPlaybackState.PLAYING:
+            self.playback_state = AnimationPlaybackState.PAUSED
+            logger.info("Playback paused for request_id=%s at frame %d", self.request_id, self.current_frame_index)
+
+    def resume_playback(self) -> None:
+        """Resume from pause."""
+        if self.playback_state == AnimationPlaybackState.PAUSED:
+            self.playback_state = AnimationPlaybackState.PLAYING
+            logger.info("Playback resumed for request_id=%s", self.request_id)
+
+    def stop_playback(self) -> None:
+        """Stop playback and reset to frame 0."""
+        if self.playback_state in (AnimationPlaybackState.PLAYING, AnimationPlaybackState.PAUSED):
+            self.current_frame_index = 0
+            self.playback_state = AnimationPlaybackState.STOPPED
+            logger.info("Playback stopped for request_id=%s", self.request_id)
+
+    def next_frame(self) -> bytes | None:
+        """Advance to next frame and return its bytes, or None if at end."""
+        if self.current_frame_index < len(self.frames):
+            frame = self.frames[self.current_frame_index]
+            self.current_frame_index += 1
+            return frame
+        return None
+
+    def seek_to_frame(self, index: int) -> bytes | None:
+        """Seek to a specific frame and return its bytes."""
+        if 0 <= index < len(self.frames):
+            self.current_frame_index = index
+            return self.frames[index]
+        return None
+
+    def reset_playback(self) -> None:
+        """Reset playback to frame 0 without changing state."""
+        self.current_frame_index = 0
+
+
+class AnimationSessionController:
+    """Manager for multiple concurrent animation sessions."""
+
+    def __init__(self) -> None:
+        self._sessions: dict[str, AnimationSession] = {}
+
+    def create_session(self, request_id: str, session_id: str | None = None) -> AnimationSession:
+        """Create a new animation session."""
+        session = AnimationSession(request_id=request_id, session_id=session_id)
+        self._sessions[request_id] = session
+        logger.info("Created animation session request_id=%s session_id=%s", request_id, session_id)
+        return session
+
+    def get_session(self, request_id: str) -> AnimationSession | None:
+        """Retrieve an existing session by request_id."""
+        return self._sessions.get(request_id)
+
+    def end_session(self, request_id: str) -> None:
+        """Remove a session from tracking."""
+        if request_id in self._sessions:
+            del self._sessions[request_id]
+            logger.info("Ended animation session request_id=%s", request_id)
+
+    def list_sessions(self) -> list[AnimationSession]:
+        """Return all active sessions."""
+        return list(self._sessions.values())
+
+    def cancel_session(self, request_id: str) -> None:
+        """Cancel/abandon a session."""
+        session = self._sessions.get(request_id)
+        if session:
+            session.mark_failed("User cancelled")
+            logger.info("Cancelled animation session request_id=%s", request_id)