psyexp-core 0.5.1__py3-none-any.whl

psyexp_core/__init__.py

@@ -0,0 +1,19 @@
+"""
+psyexp-core: task-agnostic harness for PsychoPy experiments.
+
+Submodules are import-tiered: ``diagnostics``, ``rundir``, ``recording``, and
+``manifest`` are PsychoPy-free and safe to import anywhere; ``screen``,
+``keyboard``, ``instructions``, and ``wizard`` pull in PsychoPy / GL / terminal
+machinery and should be imported by the task entry point. Import from the
+submodules directly to keep startup lean.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("psyexp-core")
+except PackageNotFoundError:  # running from a raw checkout without install
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

psyexp_core/diagnostics.py

@@ -0,0 +1,21 @@
+"""
+The ScreenDiagnostics dataclass, kept in its own import-light module (no PsychoPy
+/ pyglet) so manifest writing and tests can use it without pulling in the GL
+stack. ``screen.setup_screen`` populates it; ``manifest.write_manifest`` reads it.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class ScreenDiagnostics:
+    gl_vendor: str
+    gl_renderer: str
+    win_type: str
+    pyglet_version: str
+    platform_str: str
+    calib_median_ms: float
+    calib_p99_ms: float
+    calib_max_ms: float
+    calib_n: int

psyexp_core/instructions.py

@@ -0,0 +1,70 @@
+"""
+A self-paced, keypress-driven instruction pager. The task supplies the pages and
+a *draw_page* callback that renders one page (the task owns its stimuli and
+layout); this module owns the navigation loop — forward / optional back / quit —
+and the flip + key polling, reusing the shared keyboard abstraction.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import TYPE_CHECKING, TypeVar
+
+from psyexp_core.keyboard import clear_events, get_keys
+
+if TYPE_CHECKING:
+    from psychopy import visual
+    from psychopy.hardware.keyboard import Keyboard
+
+_Page = TypeVar("_Page")
+
+
+def _default_quit() -> None:
+    from psychopy import core
+
+    core.quit()
+
+
+def page_through(
+    win: visual.Window,
+    pages: Sequence[_Page],
+    draw_page: Callable[[_Page, bool], None],
+    *,
+    forward_keys: Sequence[str],
+    back_keys: Sequence[str] = (),
+    quit_keys: Sequence[str] = (),
+    kb: Keyboard | None = None,
+    on_quit: Callable[[], None] | None = None,
+) -> None:
+    """Page through *pages* one at a time until the operator advances past the last.
+
+    *draw_page(page, is_last)* draws (but does not flip) a single page. Forward
+    keys advance — and return once past the last page; back keys step back (no-op
+    on the first page); quit keys call *on_quit* (defaults to ``psychopy.core.quit``).
+    """
+    if not pages:
+        return
+
+    quit_fn = on_quit or _default_quit
+    keys = [*forward_keys, *back_keys, *quit_keys]
+
+    clear_events(kb)
+    page_idx = 0
+    while True:
+        # Poll (rather than block on waitKeys) so the window keeps flipping each
+        # frame; on macOS a window that flips once and then blocks may never come
+        # to the foreground to receive keypresses.
+        draw_page(pages[page_idx], page_idx == len(pages) - 1)
+        win.flip()
+
+        pressed = get_keys(kb, keys)
+        if not pressed:
+            continue
+        key_name = pressed[0]
+        if key_name in quit_keys:
+            quit_fn()
+        elif key_name in back_keys and page_idx > 0:
+            page_idx -= 1
+        elif key_name in forward_keys:
+            if page_idx == len(pages) - 1:
+                return
+            page_idx += 1

psyexp_core/keyboard.py

@@ -0,0 +1,150 @@
+"""Keyboard helpers that work with either PTB or PsychoPy's event backend."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+try:
+    import psychtoolbox  # noqa: F401
+except ImportError:
+    KEYBOARD_BACKEND = "event"
+else:
+    KEYBOARD_BACKEND = "ptb"
+
+# PsychoPy is imported lazily inside the functions that need it so this module —
+# and the PsychoPy-free timed-press / clock helpers below — stay importable (and
+# unit-testable) in headless/CI environments without the PsychoPy stack.
+
+if TYPE_CHECKING:
+    from psychopy.hardware.keyboard import Keyboard
+
+
+def configure_psychopy_backend() -> None:
+    from psychopy import prefs
+
+    prefs.hardware["keyboardBackend"] = KEYBOARD_BACKEND
+    if KEYBOARD_BACKEND != "ptb":
+        warn_degraded_backend()
+
+
+def warn_degraded_backend() -> None:
+    """Loudly flag, at startup, that psychtoolbox is missing and the keyboard has
+    fallen back to PsychoPy's ``event`` backend — which only captures keys while the
+    PsychoPy window holds OS focus. Without this, the experimenter doesn't discover
+    that keypresses (e.g. the start key) silently aren't registering until mid-run."""
+    from rich.console import Console
+    from rich.panel import Panel
+
+    Console(stderr=True).print(
+        Panel(
+            "[bold]psychtoolbox is not installed[/bold] — the keyboard is using "
+            "PsychoPy's\n[bold]event[/bold] backend, which only captures keypresses "
+            "while the PsychoPy\nwindow has OS focus. If keys don't register "
+            "mid-run, click the window\nfirst — or install psychtoolbox for the "
+            "robust PTB backend.",
+            title="[bold red]Keyboard: degraded backend[/bold red]",
+            border_style="red",
+            expand=False,
+            padding=(1, 2),
+        )
+    )
+
+
+def build_keyboard() -> Keyboard | None:
+    if KEYBOARD_BACKEND == "ptb":
+        from psychopy.hardware import keyboard
+
+        kb = keyboard.Keyboard()
+        # PsychoPy ≥2024.1 defaults muteOutsidePsychopy=True on macOS, silently
+        # dropping keypresses when the PsychoPy window isn't the focused/registered
+        # app (common when launched from a terminal or IDE). Disable it so keys are
+        # accepted without first clicking the window to give it focus.
+        try:
+            kb.device.muteOutsidePsychopy = False
+        except AttributeError:
+            pass
+        return kb
+    return None
+
+
+def clear_events(kb: Keyboard | None) -> None:
+    if KEYBOARD_BACKEND == "ptb":
+        if kb is not None:
+            kb.clearEvents()
+        return
+    from psychopy import event
+
+    event.clearEvents(eventType="keyboard")
+
+
+def wait_for_keys(kb: Keyboard | None, key_list: list[str]) -> list[str]:
+    if KEYBOARD_BACKEND == "ptb":
+        if kb is None:
+            return []
+        return [key_press.name for key_press in kb.waitKeys(keyList=key_list, waitRelease=False)]
+    from psychopy import event
+
+    pressed = event.waitKeys(keyList=key_list)
+    return [str(key_name) for key_name in (pressed or [])]
+
+
+def get_keys(kb: Keyboard | None, key_list: list[str]) -> list[str]:
+    if KEYBOARD_BACKEND == "ptb":
+        if kb is None:
+            return []
+        return [key_press.name for key_press in kb.getKeys(keyList=key_list, waitRelease=False)]
+    from psychopy import event
+
+    return [str(key_name) for key_name in event.getKeys(keyList=key_list)]
+
+
+# ── Timed presses + keyboard-clock helpers (PTB timing) ───────────────────────
+#
+# The functions above return key *names*, which is all most prompts need. A
+# timing-critical response window also needs the per-press reaction time and the
+# ability to anchor that clock to a stimulus onset flip. These helpers read the
+# Keyboard object directly (so they require the robust PTB backend / a real
+# device) and expose its hardware-timestamped clock.
+
+
+@dataclass
+class KeyPress:
+    """One key press with its reaction time off the keyboard's own clock."""
+
+    name: str
+    rt: float  # seconds since the keyboard clock was last reset
+
+
+def get_presses(kb: Keyboard | None, key_list: list[str]) -> list[KeyPress]:
+    """Return timed presses (name + rt) read from the keyboard's own clock.
+
+    Unlike :func:`get_keys`, this preserves each press's hardware reaction time,
+    measured against the keyboard clock (reset via :func:`reset_clock_on_flip`).
+    Requires a real Keyboard object; returns ``[]`` if *kb* is ``None``.
+    """
+    if kb is None:
+        return []
+    return [
+        KeyPress(name=key_press.name, rt=key_press.rt)
+        for key_press in kb.getKeys(keyList=key_list, waitRelease=False)
+    ]
+
+
+def reset_clock_on_flip(kb: Keyboard, win) -> None:
+    """Queue the keyboard clock to reset on the next ``win.flip()``.
+
+    Anchors reaction times to a stimulus onset: presses read after the flip carry
+    an ``rt`` measured from the moment the stimulus landed on the glass.
+    """
+    win.callOnFlip(kb.clock.reset)
+
+
+def reset_clock(kb: Keyboard) -> None:
+    """Reset the keyboard clock to zero immediately."""
+    kb.clock.reset()
+
+
+def clock_time(kb: Keyboard) -> float:
+    """Seconds elapsed on the keyboard clock since its last reset."""
+    return kb.clock.getTime()

psyexp_core/manifest.py

@@ -0,0 +1,151 @@
+"""
+Run manifest (manifest.json) writing plus the best-effort system/hardware
+diagnostics it embeds. ``write_manifest`` is task-agnostic: the task supplies its
+own top-level fields via *header* and its parameters via *study_params*; the
+system / display / process blocks and the resolved psyexp-core version are
+filled in here so every task records the same reproducibility metadata.
+"""
+from __future__ import annotations
+
+import json
+import platform
+import socket
+import subprocess
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from psyexp_core.diagnostics import ScreenDiagnostics
+
+__all__ = ["system_info", "write_manifest"]
+
+
+def _git_commit() -> str:
+    """Short HEAD of the *caller's* working directory (i.e. the task repo)."""
+    try:
+        out = subprocess.check_output(
+            ["git", "rev-parse", "--short", "HEAD"],
+            stderr=subprocess.DEVNULL,
+            text=True,
+        )
+        return out.strip()
+    except Exception:  # noqa: BLE001 — diagnostic only
+        return "unknown"
+
+
+def _cpu_name() -> str:
+    """Best-effort friendly CPU name.
+
+    ``platform.processor()`` returns the raw CPUID descriptor on Windows
+    (e.g. "Intel64 Family 6 Model 158 Stepping 11") and the bare arch on
+    macOS, neither of which is a marketing name. Read the registry on
+    Windows; otherwise fall back to ``platform.processor()``.
+    """
+    if platform.system() == "Windows":
+        try:
+            import winreg
+
+            key = winreg.OpenKey(
+                winreg.HKEY_LOCAL_MACHINE,
+                r"HARDWARE\DESCRIPTION\System\CentralProcessor\0",
+            )
+            try:
+                name, _ = winreg.QueryValueEx(key, "ProcessorNameString")
+            finally:
+                winreg.CloseKey(key)
+            if name:
+                return str(name).strip()
+        except Exception:  # noqa: BLE001 — diagnostic only
+            pass
+    return platform.processor() or "unknown"
+
+
+def _psychopy_version() -> str:
+    try:
+        import psychopy  # type: ignore
+
+        return getattr(psychopy, "__version__", "unknown")
+    except Exception:  # noqa: BLE001
+        return "unknown"
+
+
+def system_info() -> dict[str, Any]:
+    return {
+        "hostname": socket.gethostname(),
+        "platform": platform.platform(),
+        "machine": platform.machine(),
+        "processor": _cpu_name(),
+        "os_name": platform.system(),
+        "os_release": platform.release(),
+        "python_version": platform.python_version(),
+        "psychopy_version": _psychopy_version(),
+        "git_commit": _git_commit(),
+    }
+
+
+def write_manifest(
+    run_dir: Path,
+    *,
+    header: dict[str, Any],
+    session_time: datetime,
+    screen_diag: ScreenDiagnostics | None = None,
+    win_res: list[int] | None = None,
+    study_params: dict[str, Any] | None = None,
+    frame_rate: float | None = None,
+    n_trials: int | None = None,
+    frame_dur_s: float | None = None,
+    frame_dur_source: str | None = None,
+    extra_process: dict[str, Any] | None = None,
+) -> Path:
+    """Write ``run_dir/manifest.json`` and return its path.
+
+    *header* carries the task's own top-level fields (subject_id, run, plus the
+    task's own version key, e.g. ``{"medoc_version": ...}``) and is merged in
+    verbatim. *study_params* is the task's parameter block. The ``system`` /
+    ``display`` / ``process`` blocks and ``psyexp_core_version`` are added here.
+    """
+    from psyexp_core import __version__
+
+    manifest: dict[str, Any] = {"psyexp_core_version": __version__}
+    manifest.update(header)
+    manifest["session_time"] = session_time.isoformat(timespec="seconds")
+    if frame_rate is not None:
+        manifest["frame_rate_hz"] = round(frame_rate, 3)
+    if n_trials is not None:
+        manifest["n_trials"] = n_trials
+    if study_params is not None:
+        manifest["study_params"] = study_params
+
+    manifest["system"] = system_info()
+
+    if screen_diag is not None:
+        display: dict[str, Any] = {
+            "gl_vendor": screen_diag.gl_vendor,
+            "gl_renderer": screen_diag.gl_renderer,
+            "win_type": screen_diag.win_type,
+            "pyglet_version": screen_diag.pyglet_version,
+            "resolution": [int(x) for x in win_res] if win_res is not None else None,
+            "vsync_calibration": {
+                "median_ms": screen_diag.calib_median_ms,
+                "p99_ms": screen_diag.calib_p99_ms,
+                "max_ms": screen_diag.calib_max_ms,
+                "n_samples": screen_diag.calib_n,
+            },
+        }
+        if frame_dur_s is not None:
+            display["frame_dur_ms"] = round(frame_dur_s * 1000, 4)
+        if frame_dur_source is not None:
+            display["frame_dur_source"] = frame_dur_source
+        manifest["display"] = display
+
+    process: dict[str, Any] = {"argv": sys.argv}
+    if extra_process:
+        process.update(extra_process)
+    manifest["process"] = process
+
+    path = run_dir / "manifest.json"
+    with open(path, "w") as f:
+        json.dump(manifest, f, indent=2)
+    return path

psyexp_core/recording.py

@@ -0,0 +1,26 @@
+"""
+The generic CSV writer. A task defines its own record dataclasses and column
+lists, then either uses ``CsvWriter`` directly or subclasses it to bind a fixed
+schema. Each ``append`` pulls the named attributes off the record and flushes,
+so a crash mid-run still leaves a complete file up to the last trial.
+"""
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+
+
+class CsvWriter:
+    def __init__(self, path: Path, columns: list[str]) -> None:
+        self._file = open(path, "w", newline="")
+        self._writer = csv.DictWriter(self._file, fieldnames=columns)
+        self._writer.writeheader()
+        self._columns = columns
+
+    def append(self, record: object) -> None:
+        row = {name: getattr(record, name) for name in self._columns}
+        self._writer.writerow(row)
+        self._file.flush()
+
+    def close(self) -> None:
+        self._file.close()

psyexp_core/rundir.py

@@ -0,0 +1,17 @@
+"""Timestamped output-directory creation, shared by every task."""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+
+def make_run_dir(data_dir: Path, label: str, session_time: datetime) -> Path:
+    """Create and return ``data_dir/{label}_{YYYYMMDDTHHMMSS}``.
+
+    *label* is the task-specific stem (e.g. ``"XXX000_run1"`` or
+    ``"XXX000_example"``); the timestamp keeps repeated runs from colliding.
+    """
+    ts = session_time.strftime("%Y%m%dT%H%M%S")
+    run_dir = data_dir / f"{label}_{ts}"
+    run_dir.mkdir(parents=True, exist_ok=True)
+    return run_dir

psyexp_core/screen.py

@@ -0,0 +1,101 @@
+"""
+Screen + frame-timing setup: open a fullscreen PsychoPy window on the last
+display, enable VSYNC, run a short flip-interval calibration, and return the
+window alongside a ScreenDiagnostics snapshot for the manifest.
+"""
+from __future__ import annotations
+
+import platform
+import statistics
+
+import pyglet
+from psychopy import core, monitors, visual
+
+from psyexp_core.diagnostics import ScreenDiagnostics
+
+__all__ = ["ScreenDiagnostics", "setup_screen"]
+
+
+def setup_screen(
+    *,
+    color: tuple[float, float, float] = (-1, -1, -1),
+    units: str = "height",
+    warmup_flips: int = 30,
+    calib_flips: int = 120,
+) -> tuple[list[int], visual.Window, ScreenDiagnostics]:
+    """Open a fullscreen window on the last screen and calibrate frame timing.
+
+    Returns ``(win_res, win, diagnostics)``. The diagnostics carry GL/driver
+    identifiers and a flip-interval calibration (median / p99 / max in ms) so
+    timing spikes can be correlated with the compositor in post-hoc analysis.
+    """
+    display = pyglet.canvas.get_display()
+    screens = display.get_screens()
+    win_res = [screens[-1].width, screens[-1].height]
+    exp_mon = monitors.Monitor("exp_mon")
+    exp_mon.setSizePix(win_res)
+    win = visual.Window(
+        size=win_res,
+        screen=len(screens) - 1,
+        allowGUI=True,
+        fullscr=True,
+        monitor=exp_mon,
+        units=units,
+        color=color,
+        waitBlanking=True,
+    )
+
+    # Explicitly enable VSYNC on the pyglet window.
+    handle = getattr(win, "winHandle", None)
+    if handle is not None and hasattr(handle, "set_vsync"):
+        handle.set_vsync(True)
+
+    # Collect backend identifiers so timing spikes can be correlated with
+    # driver/compositor in post-hoc analysis.
+    try:
+        gl_info = pyglet.gl.current_context.get_info()
+        gl_vendor = gl_info.get_vendor()
+        gl_renderer = gl_info.get_renderer()
+    except Exception:  # noqa: BLE001 — diagnostic only
+        gl_vendor = "?"
+        gl_renderer = "?"
+
+    # VSYNC calibration: flip ~120 times and measure intervals. If the 99th
+    # percentile is well above one frame period, vsync is not actually blocking
+    # — typical on Windows under DWM composition or borderless fullscreen.
+    intervals_ms: list[float] = []
+    # Warm-up flips before measurement: PsychoPy's detectingFrameDrops doc notes
+    # drops are common during startup as the GPU/driver/compositor settle. Run
+    # these before the calibration loop so the median feeding frame_dur_s is
+    # measured on a settled context, not a cold one.
+    for _ in range(warmup_flips):
+        win.flip()
+    last_t = core.getTime()
+    for _ in range(calib_flips):
+        win.flip()
+        now = core.getTime()
+        intervals_ms.append((now - last_t) * 1000)
+        last_t = now
+    intervals_ms.sort()
+    median = statistics.median(intervals_ms)
+    p99 = intervals_ms[int(0.99 * len(intervals_ms)) - 1]
+    mx = intervals_ms[-1]
+
+    # Enable PsychoPy's frame interval recording so callers can read
+    # win.nDroppedFrames and isolate on-screen drops from measurement artifacts.
+    win.refreshThreshold = (median / 1000.0) * 1.5
+    win.recordFrameIntervals = True
+
+    diagnostics = ScreenDiagnostics(
+        gl_vendor=gl_vendor,
+        gl_renderer=gl_renderer,
+        win_type=str(getattr(win, "winType", "?")),
+        pyglet_version=str(getattr(pyglet, "version", "?")),
+        platform_str=platform.platform(),
+        calib_median_ms=round(median, 3),
+        calib_p99_ms=round(p99, 3),
+        calib_max_ms=round(mx, 3),
+        calib_n=len(intervals_ms),
+    )
+
+    return win_res, win, diagnostics

psyexp_core/wizard.py

@@ -0,0 +1,177 @@
+"""
+Reusable building blocks for terminal setup wizards: a shared questionary /
+prompt_toolkit colour palette, thin ``ask_*`` helpers that apply the palette and
+treat Ctrl-C / Esc as "quit the task", a positive-float validator, and a
+filename prompt that guards against clobbering an existing file. Tasks compose
+their own wizard from these; task-specific fields (e.g. a frame-stepping RT
+prompt) stay in the task repo.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import NoReturn
+
+import questionary
+from prompt_toolkit import prompt as _pt_prompt
+from prompt_toolkit.application.current import get_app
+from prompt_toolkit.formatted_text import HTML, FormattedText
+from prompt_toolkit.styles import Style as PtStyle
+from prompt_toolkit.validation import ValidationError, Validator
+from rich.console import Console
+
+_rcon = Console(stderr=True)
+
+# ── Styles ──────────────────────────────────────────────────────────────────
+
+# Match questionary's default palette so everything looks cohesive.
+QSTYLE = questionary.Style(
+    [
+        ("qmark", "fg:#5f819d bold"),
+        ("question", "bold"),
+        ("answer", "fg:#ff9d00 bold"),
+        ("pointer", "fg:#ff9d00 bold"),
+        ("highlighted", "fg:#ff9d00 bold"),
+        ("selected", "fg:#cc5454"),
+        ("separator", "fg:#6c6c6c"),
+        ("instruction", "fg:#858585 italic"),
+        ("placeholder", "fg:#6c6c6c"),
+    ]
+)
+
+# prompt_toolkit style for the custom prompts.
+PT_STYLE = PtStyle.from_dict(
+    {
+        "prompt": "#ff9d00 bold",           # ❯ arrow: matches questionary answer
+        "placeholder": "#6c6c6c italic",    # greyed-out example, not submitted
+        "bottom-toolbar": "bg:#1e1e1e #888888",
+        "bottom-toolbar.text": "bg:#1e1e1e",
+    }
+)
+
+
+# ── Quit / cancel ─────────────────────────────────────────────────────────────
+
+
+def quit_app() -> NoReturn:
+    """Quit PsychoPy + the process. Called when an operator cancels a prompt."""
+    from psychopy import core  # late import — avoids slow startup / circulars
+
+    core.quit()
+    raise SystemExit(0)  # unreachable; tells the type checker this never returns
+
+
+# ── Thin questionary helpers (apply QSTYLE; cancel ⇒ quit_app) ─────────────────
+
+
+def ask_text(
+    message: str,
+    *,
+    placeholder: str | None = None,
+    default: str = "",
+    validate: Callable[[str], bool | str] | None = None,
+) -> str:
+    ph = HTML(f"<placeholder>{placeholder}</placeholder>") if placeholder else None
+    answer = questionary.text(
+        message,
+        default=default,
+        placeholder=ph,
+        validate=validate,
+        style=QSTYLE,
+    ).ask()
+    if answer is None:
+        quit_app()
+    return answer
+
+
+def ask_select(message: str, choices: Sequence[questionary.Choice | str]):
+    answer = questionary.select(message, choices=list(choices), style=QSTYLE).ask()
+    if answer is None:
+        quit_app()
+    return answer
+
+
+def ask_confirm(message: str, *, default: bool = True) -> bool:
+    answer = questionary.confirm(message, default=default, style=QSTYLE).ask()
+    if answer is None:
+        quit_app()
+    return answer
+
+
+# ── Validators ────────────────────────────────────────────────────────────────
+
+
+class PosFloatValidator(Validator):
+    """prompt_toolkit validator: text must parse to a float > 0."""
+
+    def __init__(self, unit: str = "") -> None:
+        self._suffix = f" ({unit})" if unit else ""
+
+    def validate(self, document) -> None:
+        text = document.text.strip()
+        try:
+            value = float(text)
+        except ValueError:
+            raise ValidationError(
+                message=f"Enter a number{self._suffix}", cursor_position=len(text)
+            ) from None
+        if value <= 0:
+            raise ValidationError(
+                message=f"Value must be > 0{self._suffix}", cursor_position=len(text)
+            )
+
+
+# ── Filename prompt with overwrite guard ──────────────────────────────────────
+
+
+def prompt_unique_name(
+    label: str,
+    target_dir: Path,
+    filename_for: Callable[[str], str],
+    *,
+    example: str = "1",
+) -> str:
+    """Prompt for a NAME and guard against clobbering an existing file.
+
+    *filename_for* maps the entered NAME to the target filename inside
+    *target_dir*. Re-prompts until the resulting path is free or the operator
+    confirms an overwrite, then returns the chosen NAME.
+    """
+    _rcon.print(
+        f"[bold #5f819d]?[/bold #5f819d] [bold]{label}[/bold]  "
+        "[dim]NAME is only part of the saved file[/dim]",
+        highlight=False,
+    )
+
+    def _toolbar() -> FormattedText:
+        typed = get_app().current_buffer.text.strip()
+        if not typed:
+            return FormattedText([("fg:ansired bold", " ✗  Name cannot be empty")])
+        preview = target_dir / filename_for(typed)
+        return FormattedText([("fg:ansigreen bold", f" → saves as {preview}")])
+
+    while True:
+        try:
+            raw = _pt_prompt(
+                FormattedText([("class:prompt", "❯ ")]),
+                placeholder=HTML(f"<placeholder>e.g. {example}</placeholder>"),
+                bottom_toolbar=_toolbar,
+                style=PT_STYLE,
+            )
+        except (KeyboardInterrupt, EOFError):
+            quit_app()
+        name = raw.strip()
+        if not name:
+            _rcon.print("[red]Name cannot be empty.[/red]")
+            continue
+
+        target = target_dir / filename_for(name)
+        if not target.exists():
+            return name
+
+        if ask_confirm(
+            f"{target.name} already exists in {target_dir}/ — overwrite?",
+            default=False,
+        ):
+            return name
+        # else: loop and re-prompt for a different NAME

psyexp_core-0.5.1.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: psyexp-core
+Version: 0.5.1
+Summary: Task-agnostic harness for PsychoPy experiments: screen/frame-timing setup, run manifests, CSV writers, setup-wizard primitives, instruction pager, and keyboard abstraction.
+Project-URL: Homepage, https://github.com/HAPNlab/psyexp-core
+Project-URL: Repository, https://github.com/HAPNlab/psyexp-core
+Author: Eric Wang
+Requires-Python: >=3.11
+Requires-Dist: prompt-toolkit>=3.0
+Requires-Dist: psychopy>=2025.1
+Requires-Dist: pyobjc-framework-quartz>=10; sys_platform == 'darwin'
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=14.3.3
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# psyexp-core
+
+Task-agnostic harness for PsychoPy experiments, shared across the lab's task
+repos (`heat-task`, `mid-task`, `mid-task-deterministic`). It owns the *plumbing*
+that every task duplicates; each task repo keeps only its own stimuli, trial
+logic, and record schemas.
+
+## What's in here
+
+| Module | Responsibility |
+| --- | --- |
+| `screen` | `setup_screen()` — open a fullscreen PsychoPy window, enable VSYNC, run a frame-timing calibration, and return a `ScreenDiagnostics`. |
+| `diagnostics` | The `ScreenDiagnostics` dataclass (import-light; no PsychoPy). |
+| `rundir` | `make_run_dir(data_dir, label, session_time)` — timestamped output directory. |
+| `manifest` | `write_manifest(...)` + `system_info()` — JSON run manifest with system/display/process diagnostics and the resolved `psyexp_core_version`. App-specific fields are injected via `header` / `study_params`. |
+| `recording` | `CsvWriter` base class (maps a dataclass record onto a fixed column schema). |
+| `wizard` | questionary / prompt_toolkit setup-wizard primitives: shared styles, `ask_text` / `ask_select` / `ask_confirm`, `PosFloatValidator`, `prompt_unique_name`, `quit_app`. |
+| `instructions` | `page_through(...)` — a self-paced, keypress-driven instruction pager. |
+| `keyboard` | PTB / PsychoPy-event keyboard abstraction: `build_keyboard` / `get_keys` / `wait_for_keys` / `clear_events`, plus the timed-press API for response windows — `get_presses` (name + rt), `reset_clock_on_flip` / `reset_clock` / `clock_time`. |
+
+## Use from a task repo
+
+Add it as a dependency. For day-to-day development, point at a local checkout so
+edits are live without reinstalling:
+
+```toml
+# your-task/pyproject.toml
+dependencies = ["psyexp-core"]
+
+[tool.uv.sources]
+psyexp-core = { path = "../psyexp-core", editable = true }
+```
+
+For a reproducible release build, pin a tagged ref instead:
+
+```toml
+[tool.uv.sources]
+psyexp-core = { git = "ssh://git@github.com/<you>/psyexp-core.git", tag = "v0.1.0" }
+```
+
+`write_manifest` records the resolved `psyexp_core_version` so each run is
+traceable back to a core version.
+
+### Co-developing core while a task repo keeps the git pin
+
+Lab task repos (e.g. `heat-task`) commit the **git-tag** source above so clones
+reproduce exactly, then overlay a local editable install for development:
+
+```bash
+uv pip install -e ../psyexp-core
+```
+
+**Gotcha:** `uv run` re-syncs the task venv from its `uv.lock` on every launch,
+which reverts that editable install straight back to the pinned tag (symptoms:
+your local core edits silently don't take effect). Set `UV_NO_SYNC=1` in the task
+repo (export it in your shell, or use `uv run --no-sync`) so the editable overlay
+sticks; run a manual `uv sync` only when you change other deps, then re-run the
+editable install. See heat-task's README ("Co-developing `psyexp-core` locally")
+for the full workflow.
+
+## Releasing
+
+Tagging and publishing are deliberately separate, so tags stay cheap to iterate on:
+
+1. **Bump + lock + changelog**, then tag `vX.Y.Z`. The tag runs the checks and
+   creates a **draft** GitHub Release — it does **not** publish anything.
+2. **Review the draft** Release and publish it. That triggers
+   [`publish.yml`](.github/workflows/publish.yml), which uploads to
+   [PyPI](https://pypi.org/project/psyexp-core/) via **Trusted Publishing** (OIDC;
+   no API token stored).
+
+PyPI versions are immutable, so retagging never republishes; bump the version to
+ship new code. See **[docs/releasing.md](docs/releasing.md)** for the full process,
+SemVer policy, pre-releases, retag semantics, and the one-time PyPI setup.

psyexp_core-0.5.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+psyexp_core/__init__.py,sha256=vHzPYmGJAI7WxyJeAEwcf8bRyJtBsU0VUqZ8GFSj6P8,697
+psyexp_core/diagnostics.py,sha256=44PYqSctMHAi1KcVyStcrX0x2UQGUA9p3DJh3oM9zlY,554
+psyexp_core/instructions.py,sha256=zKvUf18gCbnE_qEw3L3JpLHMqAEQucl38erZlTPmXcU,2225
+psyexp_core/keyboard.py,sha256=2bFTHa04IwOuhzpzMmJmnQxj0zmAPffElnhV9lMF0RQ,5308
+psyexp_core/manifest.py,sha256=UdPkPKrMhUJU1XXgKrlVeC-bO29kCro2-Sr7jGX4hYQ,5127
+psyexp_core/recording.py,sha256=0s0pMyZ1gc36y87Nz2-TbAI6nahBUGRSR746u1QcW_g,891
+psyexp_core/rundir.py,sha256=sF7PPmUr6LoaJCbiMcLn_mspCAGWxfRmq2-rcT-lKE4,609
+psyexp_core/screen.py,sha256=SBL6USxizh6fJr8J6L5RWBZZrlUC15RtAO3U1J8XLgk,3629
+psyexp_core/wizard.py,sha256=suTC9DhMQ1Y2eM5C97CDPitNkfT9RdzZQHzqyhhdGYk,6251
+psyexp_core-0.5.1.dist-info/METADATA,sha256=IMvvecAZZ1lFdRnJiiUe3xHt5lpUyUl-75EpCM4Lgdk,4347
+psyexp_core-0.5.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+psyexp_core-0.5.1.dist-info/RECORD,,

psyexp_core-0.5.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any