fletchtime 0.1.0__py3-none-any.whl

fletchtime/__main__.py

@@ -0,0 +1,149 @@
+"""Point d'entrée `python -m fletchtime` (ou la commande `fletchtime` si le
+paquet est installé -- voir `[project.scripts]` dans pyproject.toml) : lance
+le serveur de contrôle et d'affichage.
+
+Deux notions de dossier bien distinctes ici, à ne pas confondre :
+
+- Les **pages de l'application** (control.html, display.html, i18n.js,
+  logo.svg...) : toujours en lecture seule du point de vue du club, peu
+  importe comment FletchTime a été installé -- elles vivent dans le paquet
+  installé (``fletchtime.web``), ou à côté de l'exécutable pour un build
+  PyInstaller.
+- Les **données propres à un club** (logo, bannières, images de cible,
+  packs de sons, réglages TOML) : doivent rester modifiables, donc jamais
+  dans le paquet installé lui-même. Vivent dans le répertoire courant
+  (comme la plupart des outils en ligne de commande -- jekyll, hugo...),
+  ou à côté de l'exécutable pour un build PyInstaller (pour rester
+  cohérent avec le comportement historique de cette distribution-là).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import shutil
+import socket
+import sys
+import threading
+from importlib import resources
+from pathlib import Path
+
+from fletchtime.server.http_static import start_http_server
+from fletchtime.server.ws_server import run_ws_server
+
+HTTP_PORT = 8000
+WS_PORT = 8765
+
+# Dossiers pré-remplis avec un contenu par défaut fourni avec FletchTime
+# (copié une seule fois, au tout premier lancement -- jamais écrasé
+# ensuite, donc une personnalisation du club est toujours préservée même
+# après une mise à jour du paquet).
+BOOTSTRAP_DEFAULT_DIRS = {
+    "targets": "_defaults/targets",
+    "sounds/packs/classic": "_defaults/sounds/packs/classic",
+}
+
+# Fichiers isolés copiés une seule fois (même logique que ci-dessus, mais
+# pour un seul fichier plutôt qu'un dossier entier) -- des README qui
+# expliquent la convention à suivre pour chaque type de donnée du club.
+BOOTSTRAP_DEFAULT_FILES = {
+    "club/README.md": "_defaults/club/README.md",
+    "banners/README.md": "_defaults/banners/README.md",
+    "sounds/packs/README.md": "_defaults/sounds/packs/README.md",
+}
+
+
+def _app_web_dir() -> Path:
+    """Où vivent les pages de l'application elles-même."""
+    if getattr(sys, "frozen", False):
+        return Path(sys.executable).resolve().parent / "web"
+    return Path(str(resources.files("fletchtime.web")))
+
+
+def _data_root() -> Path:
+    """Où vivent les données propres au club (voir docstring du module)."""
+    if getattr(sys, "frozen", False):
+        return Path(sys.executable).resolve().parent
+    return Path.cwd()
+
+
+def ensure_directories(data_root: Path, app_web_dir: Path) -> None:
+    """Crée les dossiers attendus s'ils manquent, et copie le contenu par
+    défaut fourni avec FletchTime (README explicatifs, images de blasons,
+    pack de sons "classic") au tout premier lancement -- idempotent, sans
+    danger à chaque redémarrage, et ne touche jamais à un fichier/dossier
+    déjà existant (donc ne casse ni n'écrase jamais une personnalisation
+    faite par le club, y compris après une mise à jour)."""
+    for rel, default_rel in BOOTSTRAP_DEFAULT_DIRS.items():
+        directory = data_root / "web" / "assets" / rel
+        if directory.exists():
+            continue
+        source = app_web_dir / default_rel
+        if source.is_dir():
+            shutil.copytree(source, directory)
+        else:
+            # ancien build sans _defaults (ou chemin inattendu) -- pas de
+            # contenu par défaut à copier, mais ne doit jamais planter
+            # le démarrage pour autant.
+            directory.mkdir(parents=True, exist_ok=True)
+
+    for rel, default_rel in BOOTSTRAP_DEFAULT_FILES.items():
+        dest = data_root / "web" / "assets" / rel
+        if dest.exists():
+            continue
+        source = app_web_dir / default_rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        if source.is_file():
+            shutil.copy2(source, dest)
+
+    (data_root / "config").mkdir(parents=True, exist_ok=True)
+
+
+def local_ip() -> str:
+    """Best-effort local network IP (works even offline, since a UDP
+    'connect' only consults the routing table, no packet is actually
+    sent). Falls back to 127.0.0.1 if there is no network route at all."""
+    s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+    try:
+        s.connect(("8.8.8.8", 80))
+        return s.getsockname()[0]
+    except OSError:
+        return "127.0.0.1"
+    finally:
+        s.close()
+
+
+def main() -> None:
+    data_root = _data_root()
+    app_web_dir = _app_web_dir()
+    ensure_directories(data_root, app_web_dir)
+    assets_dir = data_root / "web" / "assets"
+
+    ip = local_ip()
+    print("=" * 60)
+    print("  FletchTime -- serveur de contrôle et d'affichage")
+    print("=" * 60)
+    print(f"  Accueil   : http://{ip}:{HTTP_PORT}/")
+    print(f"  Contrôle  : http://{ip}:{HTTP_PORT}/control.html")
+    print(f"  Affichage : http://{ip}:{HTTP_PORT}/display.html?lane=1")
+    print()
+    print("  Depuis CE téléphone, remplace l'IP par 127.0.0.1 si besoin.")
+    print("  Depuis une tablette/PC sur le même WiFi, utilise l'IP ci-dessus.")
+    print("  (si l'IP semble fausse : vérifie-la dans les réglages WiFi du téléphone)")
+    print(f"  Données du club (logo, sons, config...) : {data_root}")
+    print("=" * 60)
+
+    http_thread = threading.Thread(
+        target=start_http_server,
+        args=(str(app_web_dir), HTTP_PORT, str(assets_dir)),
+        daemon=True,
+    )
+    http_thread.start()
+
+    try:
+        asyncio.run(run_ws_server(WS_PORT))
+    except KeyboardInterrupt:
+        print("Arrêt du serveur.")
+
+
+if __name__ == "__main__":
+    main()

fletchtime/engine/__init__.py

@@ -0,0 +1,16 @@
+from .engine import MatchEngine
+from .models import MatchState, Phase
+from .modes.flint import FlintConfig, FlintMode
+from .modes.indoor import IndoorConfig, IndoorMode
+from .sequence import Step
+
+__all__ = [
+    "MatchEngine",
+    "MatchState",
+    "Phase",
+    "Step",
+    "IndoorMode",
+    "IndoorConfig",
+    "FlintMode",
+    "FlintConfig",
+]

fletchtime/engine/engine.py

@@ -0,0 +1,270 @@
+"""Plays back the ordered list of :class:`Step` produced by a
+:class:`ShootingMode`, exposing the controls a DOS (Director Of Shooting)
+needs: regular ticking, manual advance, stop, restart, jump to a specific
+end, emergency stop/resume, temporary pause.
+
+This is intentionally the only stateful class in the engine package -- modes
+themselves stay pure/stateless so they are trivial to unit test in
+isolation (see tests/test_indoor_mode.py, tests/test_flint_mode.py).
+"""
+
+from __future__ import annotations
+
+from .models import MatchState, Phase
+from .modes.base import ShootingMode
+from .sequence import Step
+
+
+class MatchEngine:
+    def __init__(self, mode: ShootingMode, countdown_tick_seconds: int = 5) -> None:
+        if countdown_tick_seconds < 0:
+            raise ValueError(f"countdown_tick_seconds must be >= 0, got {countdown_tick_seconds}")
+        self._countdown_tick_seconds = countdown_tick_seconds
+
+        self._steps: list[Step] = mode.build_sequence()
+        if not self._steps:
+            raise ValueError("A shooting mode must produce at least one step")
+
+        self._index = 0
+        self._time_left: float | None = self._steps[0].duration
+        self._finished = False
+        self._paused = False
+
+        self._emergency = False
+        self._emergency_saved_time: float | None = None
+
+        self._orange_event_fired = False
+        self._countdown_ticks_fired: set = set()
+
+        self._pending_events: list[str] = []
+        self._emit_current_step_event()
+
+    # -- controls --------------------------------------------------------
+
+    def tick(self, dt: float) -> MatchState:
+        """Advance the clock by ``dt`` seconds. Call regularly (e.g. 10Hz).
+
+        Safe to call with a ``dt`` larger than the remaining time on the
+        current step: the engine will cascade through as many steps as
+        needed (e.g. after a lag spike), matching the "catch up to real
+        time" behaviour described in the ArcheryClock manual. The cascade
+        stops as soon as it lands on an indefinite (PAUSE) step: those
+        never count down on their own, only :meth:`next` moves past them.
+        """
+        if self._emergency or self._paused or self._finished or self._time_left is None:
+            return self.current_state
+
+        self._time_left -= dt
+        while self._time_left is not None and self._time_left <= 0 and not self._finished:
+            overflow = -self._time_left
+            self._advance_step()
+            if self._finished or self._time_left is None:
+                break
+            self._time_left -= overflow
+        self._maybe_emit_orange_threshold_event()
+        self._maybe_emit_countdown_ticks()
+        return self.current_state
+
+    def next(self) -> MatchState:
+        """Manual advance, as if the DOS pressed the "next" button. This is
+        how a PAUSE step (end of a volée, arrows being retrieved) is left:
+        pressing next starts the following volée's preparation time."""
+        if not self._emergency:
+            self._advance_step()
+        return self.current_state
+
+    def stop(self) -> MatchState:
+        """Hard stop: end the current match right now, regardless of where
+        it is in the sequence. Distinct from :meth:`emergency` (which can
+        be resumed) -- this is a deliberate abandon/cancel by the DOS."""
+        self._finished = True
+        self._time_left = 0.0
+        self._pending_events.append("end_of_match")
+        return self.current_state
+
+    def restart(self) -> MatchState:
+        """Restart the whole match from its very first step, keeping the
+        same mode/config."""
+        self._index = 0
+        self._time_left = self._steps[0].duration
+        self._finished = False
+        self._paused = False
+        self._emergency = False
+        self._emergency_saved_time = None
+        self._orange_event_fired = False
+        self._countdown_ticks_fired = set()
+        self._pending_events = []
+        self._emit_current_step_event()
+        return self.current_state
+
+    def goto(
+        self, unit_number: int, end_number: int, arrow_in_end: int = 0, turn: str = ""
+    ) -> MatchState:
+        """Jump to a specific volée (and, for a walk-up end, optionally a
+        specific arrow). ``turn`` disambiguates when the same
+        (unit, end_number) occurs more than once -- e.g. Flint, where each
+        relay repeats the whole unit, so volée 3 exists once per relay.
+        Leave ``turn`` empty to match the first occurrence regardless of
+        relay. Lands on the PAUSE step immediately preceding it when one
+        exists -- more practical for the DOS: the screen already previews
+        the target end/distance, and the countdown only actually starts
+        once ``next()`` is pressed. Falls back to the shooting step itself
+        when there is no preceding pause (e.g. the very first step of the
+        match, or an individual walk-up arrow after the first). Raises
+        ``ValueError`` if no step matches."""
+        for index, step in enumerate(self._steps):
+            if step.phase == Phase.PAUSE:
+                continue
+            if step.unit_number != unit_number or step.end_number != end_number:
+                continue
+            if arrow_in_end and step.arrow_in_end != arrow_in_end:
+                continue
+            if turn and step.current_turn != turn:
+                continue
+
+            target_index = index
+            if index > 0 and self._steps[index - 1].phase == Phase.PAUSE:
+                target_index = index - 1
+
+            self._index = target_index
+            self._time_left = self._steps[target_index].duration
+            self._finished = False
+            self._paused = False
+            self._emergency = False
+            self._emergency_saved_time = None
+            self._pending_events = []
+            self._orange_event_fired = False
+            self._countdown_ticks_fired = set()
+            self._emit_current_step_event()
+            return self.current_state
+        raise ValueError(
+            f"No step found for unit={unit_number} end={end_number} "
+            f"arrow={arrow_in_end or '-'} turn={turn or '-'}"
+        )
+
+    def emergency(self) -> MatchState:
+        """Freeze the clock immediately. Position/time-left are remembered
+        so :meth:`resume` can pick up where it left off."""
+        if not self._emergency:
+            self._emergency = True
+            self._emergency_saved_time = self._time_left
+            self._pending_events.append("emergency_start")
+        return self.current_state
+
+    def resume(self, adjusted_time_left: float | None = None) -> MatchState:
+        """Recover from emergency. ``adjusted_time_left`` lets the DOS
+        compensate the archers for time lost, per FFTL rules on equipment
+        failure."""
+        if self._emergency:
+            self._emergency = False
+            self._time_left = (
+                adjusted_time_left if adjusted_time_left is not None else self._emergency_saved_time
+            )
+            self._emergency_saved_time = None
+            self._pending_events.append("emergency_end")
+        return self.current_state
+
+    def pause(self) -> MatchState:
+        if not self._paused:
+            self._paused = True
+            self._pending_events.append("pause_start")
+        return self.current_state
+
+    def play(self) -> MatchState:
+        if self._paused:
+            self._paused = False
+            self._pending_events.append("pause_end")
+        return self.current_state
+
+    def pop_pending_events(self) -> list[str]:
+        """Return and clear sound events accumulated since the last call.
+
+        Kept separate from ``current_state`` on purpose: an event (e.g.
+        "shoot_start") should be broadcast exactly once, at the transition,
+        not re-read on every tick.
+        """
+        events, self._pending_events = self._pending_events, []
+        return events
+
+    # -- internals ---------------------------------------------------------
+
+    def _advance_step(self) -> None:
+        if self._index + 1 >= len(self._steps):
+            self._finished = True
+            self._time_left = 0.0
+            self._pending_events.append("end_of_match")
+        else:
+            self._index += 1
+            self._time_left = self._steps[self._index].duration
+            self._orange_event_fired = False
+            self._countdown_ticks_fired = set()
+            if self._steps[self._index].phase == Phase.PAUSE:
+                self._pending_events.append("end_of_volee")
+            self._emit_current_step_event()
+
+    def _emit_current_step_event(self) -> None:
+        event = self._steps[self._index].sound_event
+        if event:
+            self._pending_events.append(event)
+
+    def _maybe_emit_orange_threshold_event(self) -> None:
+        """Check whether the current step just crossed its orange
+        threshold (e.g. 30s remaining out of a continuous 240s countdown)
+        and fire its sound event exactly once. Does not change ``_index``
+        or reset the countdown -- the displayed phase switch is computed
+        in :attr:`current_state`."""
+        if self._finished or self._orange_event_fired or self._time_left is None:
+            return
+        step = self._steps[self._index]
+        if step.orange_threshold is not None and self._time_left <= step.orange_threshold:
+            self._orange_event_fired = True
+            if step.orange_sound_event:
+                self._pending_events.append(step.orange_sound_event)
+
+    def _maybe_emit_countdown_ticks(self) -> None:
+        """Fire one "countdown_tick" event for each of the last
+        ``self._countdown_tick_seconds`` seconds of the current step's
+        countdown, once each -- e.g. a beep every second on the final
+        stretch of a volée or a walk-up arrow. Works for any timed step
+        (RED prep or GREEN shoot); frozen during emergency/pause since
+        :meth:`tick` doesn't run at all then."""
+        if self._finished or self._time_left is None or self._countdown_tick_seconds == 0:
+            return
+        for seconds in range(self._countdown_tick_seconds, 0, -1):
+            if seconds not in self._countdown_ticks_fired and self._time_left <= seconds:
+                self._countdown_ticks_fired.add(seconds)
+                self._pending_events.append("countdown_tick")
+
+    @property
+    def current_state(self) -> MatchState:
+        if self._finished:
+            return MatchState(phase=Phase.FINISHED, finished=True)
+
+        step = self._steps[self._index]
+        time_left = self._emergency_saved_time if self._emergency else self._time_left
+
+        if self._emergency:
+            phase = Phase.EMERGENCY
+        elif (
+            step.orange_threshold is not None
+            and time_left is not None
+            and time_left <= step.orange_threshold
+        ):
+            phase = Phase.ORANGE
+        else:
+            phase = step.phase
+
+        return MatchState(
+            phase=phase,
+            time_left=round(max(time_left, 0.0), 1) if time_left is not None else 0.0,
+            current_turn=step.current_turn,
+            end_number=step.end_number,
+            total_ends=step.total_ends,
+            unit_number=step.unit_number,
+            arrow_in_end=step.arrow_in_end,
+            total_arrows_in_end=step.total_arrows_in_end,
+            distance_label=step.distance_label,
+            target_image=step.target_image,
+            target_image_2=step.target_image_2,
+            finished=False,
+        )

fletchtime/engine/models.py

@@ -0,0 +1,60 @@
+"""Core data model shared by every shooting mode and by the match engine.
+
+Deliberately dependency-free (stdlib only) so this package can be tested and
+reused without pulling in FastAPI/websockets: the engine only produces
+``MatchState`` snapshots, it says nothing about how they are transported.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+
+class Phase(StrEnum):
+    """Visual/safety phase of the current step.
+
+    WAIT      -- before the match starts, or between matches. No countdown.
+    RED       -- preparation time (archers approach / take position).
+    GREEN     -- main shooting time.
+    ORANGE    -- warning period near the end of shooting time.
+    PAUSE     -- end of a volée: archers retrieve arrows, no countdown.
+                 The engine waits here indefinitely until the DOS manually
+                 starts the next volée (``MatchEngine.next()``).
+    EMERGENCY -- danger signal, clock frozen, must be explicitly resumed.
+    FINISHED  -- sequence exhausted, nothing left to shoot.
+    """
+
+    WAIT = "wait"
+    RED = "red"
+    GREEN = "green"
+    ORANGE = "orange"
+    PAUSE = "pause"
+    EMERGENCY = "emergency"
+    FINISHED = "finished"
+
+
+@dataclass(frozen=True)
+class MatchState:
+    """Immutable snapshot of where the match currently stands.
+
+    This is the object a transport layer (FastAPI/WebSocket) would serialize
+    and push to display screens -- see docs/architecture.md.
+    """
+
+    phase: Phase = Phase.WAIT
+    time_left: float = 0.0
+
+    # sequencing / display context
+    current_turn: str = ""  # e.g. "A-B", "C-D", "" if not applicable
+    end_number: int = 0  # 1-indexed end/volée within the unit
+    total_ends: int = 0  # total ends in the unit (incl. walk-up end)
+    unit_number: int = 1  # for Flint: which "unité standard" (1..n)
+    arrow_in_end: int = 0  # for walk-up ends: which arrow (1-indexed)
+    total_arrows_in_end: int = 0  # for walk-up ends: arrows in this end
+
+    distance_label: str = ""
+    target_image: str = ""
+    target_image_2: str = ""
+
+    finished: bool = False

fletchtime/engine/modes/__init__.py

@@ -0,0 +1,11 @@
+from .base import ShootingMode
+from .flint import FlintConfig, FlintMode
+from .indoor import IndoorConfig, IndoorMode
+
+__all__ = [
+    "ShootingMode",
+    "IndoorMode",
+    "IndoorConfig",
+    "FlintMode",
+    "FlintConfig",
+]

fletchtime/engine/modes/base.py

@@ -0,0 +1,27 @@
+"""Common interface for shooting modes.
+
+Unlike the legacy ArcheryClock approach (a single 12k-line file dispatching
+on a string like ``archerysystem = 'fita'`` in dozens of scattered ``if``
+branches), each mode here is a self-contained class that only knows how to
+build its own sequence of steps. Adding a new mode never touches existing
+ones -- see docs/dev-guide for the walkthrough.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ..sequence import Step
+
+
+class ShootingMode(ABC):
+    """Builds the full ordered list of :class:`Step` for one competition
+    round. Modes are stateless sequence generators; all runtime state
+    (current position, elapsed time, pause/emergency) lives in
+    :class:`fletchtime.engine.engine.MatchEngine`.
+    """
+
+    @abstractmethod
+    def build_sequence(self) -> list[Step]:
+        """Return the ordered, non-empty list of steps for this round."""
+        raise NotImplementedError