slab-cli 0.8.0__tar.gz → 0.9.0__tar.gz

{slab_cli-0.8.0 → slab_cli-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: slab-cli
-Version: 0.8.0
+Version: 0.9.0
 Summary: CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal.
 Author: dev_jeb
 Requires-Dist: slab-schemas>=0.1.0

{slab_cli-0.8.0 → slab_cli-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "slab-cli"
-version = "0.8.0"
+version = "0.9.0"
 description = "CLI for the slab trading-card API — catalog, collect, and track your cards from the terminal."
 readme = "README.md"
 authors = [{name = "dev_jeb"}]

{slab_cli-0.8.0 → slab_cli-0.9.0}/src/slab_cli/browse.py

@@ -6,8 +6,13 @@ across every column, and q leaves — printing the plain table on the way out so
 survives in scrollback. Enter drills down: with a `detail` callback the highlighted row's
 detail view REPLACES the list as a scrollable page (Esc/q climbs back up to the list, same row
 highlighted); without one, Enter simply returns the row's item to the caller. Anywhere output
-isn't an interactive terminal (a pipe, CI, redirection, a platform without termios) it
-degrades to the static table, so `slab ... | grep` keeps working unchanged.
+isn't an interactive terminal (a pipe, CI, redirection) it degrades to the static table, so
+`slab ... | grep` keeps working unchanged.
+
+Reading keys is the one OS-specific part, and this module doesn't do it: `platforms.current()`
+hands back a backend whose `key_source()` yields a `read()` returning platform-neutral key NAMES
+('up', 'enter', …). Everything below is written against those names, so it behaves identically on
+macOS and Windows and stays that way — see `platforms/base.py` for the rule.
 
 This is THE tabular display for result lists: a command builds `(item, cells)` rows once and
 the same spec drives the interactive view, the static fallback, and the exit receipt.
@@ -15,7 +20,6 @@ the same spec drives the interactive view, the static fallback, and the exit rec
 
 from __future__ import annotations
 
-import os
 import sys
 from typing import Any, Callable, Sequence
 
@@ -23,6 +27,7 @@ from rich.console import Group
 from rich.live import Live
 from rich.text import Text
 
+from .platforms import KeyReader, current as current_platform
 from .theme import console, heading, slab_table
 
 # One row: the domain object Enter should act on, plus its cell markup strings (one per column).
@@ -85,76 +90,16 @@ def pager_top(top: int, viewport: int, n: int) -> int:
     return max(0, min(top, n - viewport))
 
 
-_SEQUENCES = {
-    b"\x1b[A": "up", b"\x1b[B": "down",
-    b"\x1bOA": "up", b"\x1bOB": "down",          # application cursor mode
-    b"\x1b[5~": "pgup", b"\x1b[6~": "pgdn",
-    b"\x1b[H": "home", b"\x1b[F": "end",
-    b"\x1b[1~": "home", b"\x1b[4~": "end",
-    b"\x1b[D": "left", b"\x1bOD": "left",        # ← also climbs back up a level
-}
-
-
-def split_keys(data: bytes) -> list[str]:
-    """A raw input burst -> ordered key names ('up', 'enter', 'esc', …) and printable chars.
-
-    Terminals deliver fast typing, pastes, and escape sequences as multi-byte chunks; parsing
-    the whole burst (instead of assuming one read = one key) is what keeps a pasted filter
-    query intact and an arrow key from being mistaken for its component bytes."""
-    keys: list[str] = []
-    i = 0
-    while i < len(data):
-        if data[i:i + 1] == b"\x1b":
-            for seq, name in _SEQUENCES.items():
-                if data.startswith(seq, i):
-                    keys.append(name)
-                    i += len(seq)
-                    break
-            else:
-                if data[i + 1:i + 2] in (b"[", b"O"):
-                    # An escape sequence we don't drive anything with: swallow through its
-                    # final byte (0x40–0x7e) so its payload doesn't leak in as typed text.
-                    j = i + 2
-                    while j < len(data) and not 0x40 <= data[j] <= 0x7E:
-                        j += 1
-                    i = j + 1
-                else:
-                    i += 1  # bare Escape
-                keys.append("esc")
-            continue
-        j = data.find(b"\x1b", i)
-        run = data[i:] if j == -1 else data[i:j]
-        i = len(data) if j == -1 else j
-        for ch in run.decode(errors="ignore"):
-            if ch in ("\r", "\n"):
-                keys.append("enter")
-            elif ch in ("\x7f", "\x08"):
-                keys.append("backspace")
-            elif ch == "\x03":
-                keys.append("quit")  # Ctrl-C when ISIG doesn't get there first
-            elif ch.isprintable():
-                keys.append(ch)
-    return keys
-
-
 # ---------------------------------------------------------------------------
 # The interactive machinery
 # ---------------------------------------------------------------------------
 
 def _interactive_ok() -> bool:
-    """True when we can actually run a keyboard loop: a real terminal on a termios platform."""
+    """True when we can actually run a keyboard loop: a real terminal (not a pipe, not CI), on a
+    platform that can read single keypresses. Either half failing is a fallback, not an error."""
     if not (console.is_terminal and sys.stdin.isatty()):
         return False
-    try:
-        import termios  # noqa: F401  (Unix-only; absent on Windows)
-        import tty  # noqa: F401
-    except ImportError:
-        return False
-    return True
-
-
-def _read_keys(fd: int) -> list[str]:
-    return split_keys(os.read(fd, 64))
+    return current_platform().can_read_keys()
 
 
 def _frame(
@@ -196,7 +141,7 @@ def _frame(
 
 
 def _run_list(
-    fd: int,
+    read: KeyReader,
     columns: list[tuple[str, dict]],
     rows: list[Row],
     *,
@@ -232,7 +177,7 @@ def _run_list(
             )
 
             if not pending:
-                pending = _read_keys(fd)
+                pending = read()
             if not pending:
                 continue
             key = pending.pop(0)
@@ -274,7 +219,7 @@ def _run_list(
                 typing = True
 
 
-def _run_pager(fd: int, lines: list[Text], *, back_hint: str) -> None:
+def _run_pager(read: KeyReader, lines: list[Text], *, back_hint: str) -> None:
     """The detail screen: a captured view as a scrollable page. Esc/q/←/backspace climbs back
     up to the list; ↑↓, PgUp/PgDn, and space scroll when the content is taller than the
     terminal. Returns when the user leaves."""
@@ -294,7 +239,7 @@ def _run_pager(fd: int, lines: list[Text], *, back_hint: str) -> None:
             live.update(Group(*window), refresh=True)
 
             if not pending:
-                pending = _read_keys(fd)
+                pending = read()
             if not pending:
                 continue
             key = pending.pop(0)
@@ -356,28 +301,21 @@ def browse(
         print_table(columns, rows, title=title, note=note, footer=footer)
         return None
 
-    import termios
-    import tty
-
-    fd = sys.stdin.fileno()
-    saved = termios.tcgetattr(fd)
     picked: Any | None = None
     sel = start
     try:
-        tty.setcbreak(fd)
-        while True:
-            item, sel = _run_list(fd, columns, rows, title=title, note=note,
-                                  hint=hint, start=sel)
-            if item is None:
-                break
-            if detail is None:
-                picked = item
-                break
-            _run_pager(fd, _capture_lines(lambda: detail(item)), back_hint="back to list")
+        with current_platform().key_source() as read:
+            while True:
+                item, sel = _run_list(read, columns, rows, title=title, note=note,
+                                      hint=hint, start=sel)
+                if item is None:
+                    break
+                if detail is None:
+                    picked = item
+                    break
+                _run_pager(read, _capture_lines(lambda: detail(item)), back_hint="back to list")
     except KeyboardInterrupt:
         pass
-    finally:
-        termios.tcsetattr(fd, termios.TCSADRAIN, saved)
 
     if picked is not None:
         return picked

{slab_cli-0.8.0 → slab_cli-0.9.0}/src/slab_cli/display.py

@@ -19,7 +19,7 @@ from slab_schemas.community import (
 )
 from slab_schemas.custom_sets import CustomSetDetail, CustomSetOut, CustomSetSearchResult
 from slab_schemas.dashboard import CatalogStats, DashboardStats, HighlightCard, LabeledCount
-from slab_schemas.enums import Grade
+from slab_schemas.enums import Grade, SealedFormat
 from slab_schemas.pricing import CardComps, CardMarket, PortfolioSummary, SetTopCards
 from slab_schemas.sealed import SealedPriceHistory, SealedProductOut
 from slab_schemas.timeseries import CardPriceHistory
@@ -908,16 +908,27 @@ def _format_label(fmt: str) -> str:
     return fmt.replace("_", " ").title()
 
 
+_CASE_FORMATS = {SealedFormat.hobby_case, SealedFormat.retail_case}
+
+
 def _sealed_config(p: SealedProductOut) -> str:
-    """A compact config string for a sealed SKU: '12 packs × 8 cards' / '8 boxes'."""
+    """A compact config string for a sealed SKU — what you actually get when you open THIS SKU:
+    '12 boxes × 8 packs × 12 cards' for a case, '4 packs × 12 cards' for a box, '24 cards' for a
+    single-pack SKU. `boxes_per_case` describes the CASE, not the box, so on a non-case SKU it
+    rides along as a '· 20/case' suffix — never as a factor (a blaster box holds 4 packs, not the
+    20 blasters that share its case)."""
     parts = []
-    if p.boxes_per_case:
+    if p.format in _CASE_FORMATS and p.boxes_per_case:
         parts.append(f"{p.boxes_per_case} boxes")
-    if p.packs_per_box:
+    # A 1-pack SKU (hanger, starter) is just its pack — "1 packs × 24 cards" reads as noise.
+    if p.packs_per_box and p.packs_per_box > 1:
         parts.append(f"{p.packs_per_box} packs")
     if p.cards_per_pack:
         parts.append(f"{p.cards_per_pack} cards")
-    return " × ".join(parts) if parts else "—"
+    config = " × ".join(parts) if parts else "—"
+    if p.format not in _CASE_FORMATS and p.boxes_per_case:
+        config = f"{config} · {p.boxes_per_case}/case"
+    return config
 
 
 def render_set_market(s: SetOut, sealed: list[SealedProductOut], top: SetTopCards) -> None:

slab_cli-0.9.0/src/slab_cli/platforms/__init__.py

@@ -0,0 +1,70 @@
+"""The platform registry — `current()` is how the rest of the CLI gets its `Platform`.
+
+    from .platforms import current
+
+    plat = current()
+    if plat.can_read_keys():
+        with plat.key_source() as read: ...
+
+Selection happens once and is cached: the OS doesn't change mid-run. `SLAB_PLATFORM` overrides it
+by name, which is how you drive the Windows code path from a Mac (its decoding is pure; only
+`key_source` actually needs the OS) — an unknown name falls back to the real platform rather than
+erroring, so a typo can't brick the CLI.
+
+See `base.py` for the protocol and the rule about where OS forks may live.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Callable
+
+from .base import KEY_NAMES, KeyReader, Platform, unsupported_key_source
+from .posix import PosixPlatform
+from .windows import WindowsPlatform
+
+__all__ = [
+    "KEY_NAMES", "KeyReader", "Platform", "unsupported_key_source",
+    "PLATFORMS", "current", "detect_name", "get_platform",
+]
+
+# name -> factory. Add a platform here and nothing else in the CLI changes.
+PLATFORMS: dict[str, Callable[[], Platform]] = {
+    "posix": PosixPlatform,
+    "windows": WindowsPlatform,
+}
+
+ENV_OVERRIDE = "SLAB_PLATFORM"
+
+
+def detect_name(platform_str: str | None = None) -> str:
+    """Which registry entry this interpreter is running on. Pure — pass `sys.platform` to test.
+
+    Everything that isn't Windows is POSIX as far as the CLI is concerned: macOS, Linux, and the
+    BSDs all read keys the same way, so they share one implementation rather than one each."""
+    return "windows" if (platform_str or sys.platform).startswith("win32") else "posix"
+
+
+def get_platform(name: str) -> Platform:
+    """The named platform. Raises KeyError for an unknown name — callers that take user input
+    should go through `current()`, which falls back instead."""
+    return PLATFORMS[name]()
+
+
+_current: Platform | None = None
+
+
+def current() -> Platform:
+    """The `Platform` for this run, detected once and cached."""
+    global _current
+    if _current is None:
+        requested = os.environ.get(ENV_OVERRIDE, "").strip().lower()
+        _current = PLATFORMS.get(requested, PLATFORMS[detect_name()])()
+    return _current
+
+
+def set_platform(platform: Platform | None) -> None:
+    """Force the active platform, or None to re-detect. For tests — nothing in the CLI calls it."""
+    global _current
+    _current = platform

slab_cli-0.9.0/src/slab_cli/platforms/base.py

@@ -0,0 +1,86 @@
+"""The `Platform` protocol — the ONE contract every OS-specific behaviour in the CLI goes through.
+
+Mirrors the seeder's `sources/` seam: a protocol here, one module per implementation beside it,
+a registry in `__init__.py`. The point is the same — the rest of the code is written against the
+protocol and never learns which OS it's on.
+
+## The rule
+
+**No `sys.platform` check, and no import of an OS-only stdlib module (`termios`, `tty`, `msvcrt`,
+`fcntl`, `winreg`, …), may live outside this package.** `tests/test_platforms.py` enforces it by
+scanning the source, so a stray fork fails CI rather than quietly shipping a Mac-only feature —
+which is exactly how the browse table came to be invisible on Windows for a release.
+
+## Adding a capability
+
+When something new turns out to differ by OS:
+
+1. Add the method to `Platform` below, documenting **what varies and why** — not just its
+   signature. If you can't name the divergence, the caller probably doesn't need a fork.
+2. Implement it in EVERY module in this package. A platform that can't do the thing returns a
+   falsey/None value the caller degrades on; it never raises for being the wrong OS.
+3. Keep the pure part pure. Decoding, parsing, and formatting go in module-level functions that
+   take plain data (see `posix.split_keys` / `windows.split_win_keys`), so the other platform's
+   logic stays unit-testable from whatever machine you happen to be on.
+
+## Adding a platform
+
+Add a module, implement `Platform`, register it in `__init__.py`. Nothing else changes.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Callable, ContextManager, Iterator, Protocol, runtime_checkable
+
+# A key burst, decoded: the platform-neutral NAMES the interactive loops switch on. Both backends
+# translate their own wire format (POSIX escape sequences, Windows `\x00`/`\xe0` scan codes) into
+# these, plus bare printable characters for anything typed. Adding a name means teaching EVERY
+# platform to produce it — an unmapped key must be dropped, never leaked through as text.
+KEY_NAMES = frozenset({
+    "up", "down", "left",
+    "pgup", "pgdn", "home", "end",
+    "enter", "esc", "backspace",
+    "quit",          # Ctrl-C where the platform hands it over as data rather than a signal
+})
+
+# `read() -> [key names]`: blocks for at least one key, then returns everything already buffered
+# alongside it. Returning the whole burst (rather than one key per call) is what keeps a pasted
+# filter query intact and stops a held arrow key from lagging behind the render.
+KeyReader = Callable[[], list[str]]
+
+
+@runtime_checkable
+class Platform(Protocol):
+    """What the CLI needs from the operating system. One implementation per OS."""
+
+    #: Registry key and what the diagnostics print — "posix", "windows".
+    name: str
+
+    def can_read_keys(self) -> bool:
+        """Whether single-keypress reads are possible here at all — i.e. this platform's
+        keyboard module imported. False makes every interactive view degrade to its static
+        rendering, so a missing backend costs a feature, never a traceback.
+
+        This is the PLATFORM half of the question only. Whether stdout/stdin are actually a
+        terminal is universal, so callers check that themselves (see `browse._interactive_ok`)."""
+        ...
+
+    def key_source(self) -> ContextManager[KeyReader]:
+        """Enter unbuffered key reading, yielding a `read()`; restore the terminal on the way out.
+
+        What varies: POSIX must put the tty into cbreak mode and put it back (a crash mid-browse
+        would otherwise leave the user's shell without echo), and parses raw escape-sequence
+        bytes. Windows reads the console API through `msvcrt`, which needs no mode change, gives
+        back already-decoded wide chars, and signals special keys with a scan-code prefix.
+
+        Only call this when `can_read_keys()` is True."""
+        ...
+
+
+@contextmanager
+def unsupported_key_source() -> Iterator[KeyReader]:
+    """The `key_source` a platform without a keyboard backend returns — a valid context manager
+    whose reader answers "quit", so a caller that skipped `can_read_keys()` leaves its loop
+    immediately instead of spinning or blowing up."""
+    yield lambda: ["quit"]

slab_cli-0.9.0/src/slab_cli/platforms/posix.py

@@ -0,0 +1,99 @@
+"""macOS / Linux / BSD — keys via `termios` + `tty`.
+
+A POSIX terminal delivers keys as raw bytes on stdin, with anything that isn't a plain character
+encoded as an escape sequence (`\\x1b[A` = up). Reading them one at a time requires taking the tty
+out of line-buffered mode, which also means putting it BACK — a browse that exits without
+restoring leaves the user's shell with no echo.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from contextlib import contextmanager
+from typing import Iterator
+
+from .base import KeyReader
+
+_SEQUENCES = {
+    b"\x1b[A": "up", b"\x1b[B": "down",
+    b"\x1bOA": "up", b"\x1bOB": "down",          # application cursor mode
+    b"\x1b[5~": "pgup", b"\x1b[6~": "pgdn",
+    b"\x1b[H": "home", b"\x1b[F": "end",
+    b"\x1b[1~": "home", b"\x1b[4~": "end",
+    b"\x1b[D": "left", b"\x1bOD": "left",        # ← also climbs back up a level
+}
+
+# One read is sized to swallow a whole burst (a paste, a held key) rather than a single sequence.
+_BURST_BYTES = 64
+
+
+def split_keys(data: bytes) -> list[str]:
+    """A raw input burst -> ordered key names ('up', 'enter', 'esc', …) and printable chars.
+
+    Terminals deliver fast typing, pastes, and escape sequences as multi-byte chunks; parsing
+    the whole burst (instead of assuming one read = one key) is what keeps a pasted filter
+    query intact and an arrow key from being mistaken for its component bytes."""
+    keys: list[str] = []
+    i = 0
+    while i < len(data):
+        if data[i:i + 1] == b"\x1b":
+            for seq, name in _SEQUENCES.items():
+                if data.startswith(seq, i):
+                    keys.append(name)
+                    i += len(seq)
+                    break
+            else:
+                if data[i + 1:i + 2] in (b"[", b"O"):
+                    # An escape sequence we don't drive anything with: swallow through its
+                    # final byte (0x40–0x7e) so its payload doesn't leak in as typed text.
+                    j = i + 2
+                    while j < len(data) and not 0x40 <= data[j] <= 0x7E:
+                        j += 1
+                    i = j + 1
+                else:
+                    i += 1  # bare Escape
+                keys.append("esc")
+            continue
+        j = data.find(b"\x1b", i)
+        run = data[i:] if j == -1 else data[i:j]
+        i = len(data) if j == -1 else j
+        for ch in run.decode(errors="ignore"):
+            if ch in ("\r", "\n"):
+                keys.append("enter")
+            elif ch in ("\x7f", "\x08"):
+                keys.append("backspace")
+            elif ch == "\x03":
+                keys.append("quit")  # Ctrl-C when ISIG doesn't get there first
+            elif ch.isprintable():
+                keys.append(ch)
+    return keys
+
+
+class PosixPlatform:
+    """`Platform` for anything with a termios tty."""
+
+    name = "posix"
+
+    def can_read_keys(self) -> bool:
+        try:
+            import termios  # noqa: F401
+            import tty  # noqa: F401
+        except ImportError:
+            return False
+        return True
+
+    @contextmanager
+    def key_source(self) -> Iterator[KeyReader]:
+        import termios
+        import tty
+
+        fd = sys.stdin.fileno()
+        saved = termios.tcgetattr(fd)
+        try:
+            tty.setcbreak(fd)
+            yield lambda: split_keys(os.read(fd, _BURST_BYTES))
+        finally:
+            # TCSADRAIN, not TCSANOW: let queued output flush before the mode flips back, so a
+            # half-drawn frame doesn't survive into the restored shell.
+            termios.tcsetattr(fd, termios.TCSADRAIN, saved)

slab_cli-0.9.0/src/slab_cli/platforms/windows.py

@@ -0,0 +1,91 @@
+"""Windows — keys via `msvcrt`.
+
+The Windows console has no termios and sends no escape sequences. `msvcrt.getwch()` reads the
+console directly, one already-decoded wide character at a time, so there is no terminal mode to
+set or restore and no bytes to decode. Special keys arrive as two reads instead: a `\\x00` or
+`\\xe0` prefix, then a scan code identifying the key.
+
+Two consequences worth knowing, both handled here:
+- Ctrl-C comes back as ordinary data (`\\x03`), not a `KeyboardInterrupt`, so it is mapped to
+  "quit" the way POSIX cbreak mode does.
+- Backspace is `\\x08` (BS), where a POSIX terminal usually sends `\\x7f` (DEL).
+
+Note this covers the real Windows console and Windows Terminal. Under mintty (Git Bash), Python's
+stdin is a pipe rather than a console handle, so `sys.stdin.isatty()` is False and interactive
+views fall back to their static rendering — correct, if not ideal.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Iterator, Sequence
+
+from .base import KeyReader
+
+# The scan codes the console reports after a `\x00`/`\xe0` prefix — its stand-in for the escape
+# sequences a POSIX terminal sends. Same key names as `posix._SEQUENCES`.
+_SPECIAL = {
+    "H": "up", "P": "down",
+    "I": "pgup", "Q": "pgdn",
+    "G": "home", "O": "end",
+    "K": "left",
+}
+
+_PREFIXES = ("\x00", "\xe0")
+
+
+def split_win_keys(chars: Sequence[str]) -> list[str]:
+    """A burst of Windows console wide chars -> the same key names `posix.split_keys` produces.
+
+    A prefix at the very end of a burst (its scan code not read yet) and an unrecognized scan code
+    are both dropped rather than leaking in as typed text — an unmapped F-key must not end up in
+    a filter query."""
+    keys: list[str] = []
+    i = 0
+    while i < len(chars):
+        ch = chars[i]
+        if ch in _PREFIXES:
+            name = _SPECIAL.get(chars[i + 1]) if i + 1 < len(chars) else None
+            if name:
+                keys.append(name)
+            i += 2
+            continue
+        if ch in ("\r", "\n"):
+            keys.append("enter")
+        elif ch in ("\x7f", "\x08"):
+            keys.append("backspace")
+        elif ch == "\x1b":
+            keys.append("esc")
+        elif ch == "\x03":
+            keys.append("quit")
+        elif ch.isprintable():
+            keys.append(ch)
+        i += 1
+    return keys
+
+
+class WindowsPlatform:
+    """`Platform` for the Windows console."""
+
+    name = "windows"
+
+    def can_read_keys(self) -> bool:
+        try:
+            import msvcrt  # noqa: F401
+        except ImportError:
+            return False
+        return True
+
+    @contextmanager
+    def key_source(self) -> Iterator[KeyReader]:
+        import msvcrt
+
+        def read() -> list[str]:
+            # Block for one key, then drain what's already buffered — the same burst semantics as
+            # a single `os.read` on POSIX, so pastes and held keys arrive together.
+            chars = [msvcrt.getwch()]
+            while msvcrt.kbhit():
+                chars.append(msvcrt.getwch())
+            return split_win_keys(chars)
+
+        yield read  # nothing to restore: msvcrt never changed the console's mode