staticfx 2.0.0__py3-none-any.whl

staticfx/app/session.py

@@ -0,0 +1,97 @@
+"""Running the app in a real terminal, and rendering it without one."""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+from staticfx.app.app import App
+from staticfx.core.clock import FrameClock
+from staticfx.core.frame import Frame
+from staticfx.core.keys import KeyReader
+from staticfx.core.renderer import Renderer
+from staticfx.core.terminal import CLEAR, Terminal
+
+SAVE_INTERVAL = 1.0  # seconds; settings change on every effect switch, so batch the writes
+
+
+def supports_truecolor() -> bool:
+    """Best guess from the environment; ``staticfx`` can be told otherwise in Settings."""
+    if os.environ.get("COLORTERM", "").lower() in ("truecolor", "24bit"):
+        return True
+    term = os.environ.get("TERM", "")
+    return not ("256color" in term or term in ("linux", "screen", "xterm"))
+
+
+def supports_utf8() -> bool:
+    encoding = getattr(sys.stdout, "encoding", None) or ""
+    return encoding.lower().replace("-", "") == "utf8"
+
+
+def wants_truecolor(app: App) -> bool:
+    colour = app.settings.colour
+    return supports_truecolor() if colour == "auto" else colour == "truecolor"
+
+
+def run(app: App, duration: float | None = None) -> None:
+    """The interactive loop. Returns when the user quits or ``duration`` seconds pass."""
+    renderer = Renderer()
+    started = last_save = time.monotonic()
+    try:
+        with Terminal() as terminal:
+            reader = KeyReader(terminal.fd)
+            clock = FrameClock(app.settings.fps)
+            frame = Frame(*terminal.size())
+            app.resize(frame.width, frame.height)
+            if app.notes:
+                extra = len(app.notes) - 1
+                more = f" (+{extra} more, listed when you quit)" if extra else ""
+                app.toast(app.notes[0] + more, 6.0)
+
+            while app.running:
+                dt = clock.tick()
+                for key in reader.read():
+                    app.handle_key(key)
+                if not app.running:
+                    break
+                if app.suspend_requested:
+                    app.suspend_requested = False
+                    terminal.suspend()
+
+                size = terminal.size()
+                if terminal.resized or size != (frame.width, frame.height):
+                    terminal.resized = False
+                    frame.resize(*size)
+                    app.resize(*size)
+                    renderer.invalidate()
+                    terminal.write(CLEAR)
+
+                clock.interval = 1.0 / app.settings.fps
+                renderer.truecolor = wants_truecolor(app)
+                app.update(dt)
+                app.draw(frame)
+                terminal.write(renderer.diff(frame))
+
+                now = time.monotonic()
+                if app.dirty and now - last_save >= SAVE_INTERVAL:
+                    app.save_settings()
+                    last_save = now
+                if duration is not None and now - started >= duration:
+                    break
+                clock.wait()
+    finally:
+        app.save_settings()
+
+
+def render_frames(app: App, frames: int, fps: float = 30.0) -> Frame:
+    """Simulate ``frames`` frames headlessly and return the last one.
+
+    Uses a fixed timestep and no adaptive resolution, so the same seed always
+    gives the same picture.
+    """
+    frame = Frame(app.width, app.height)
+    for _ in range(max(1, frames)):
+        app.player.update(1.0 / fps)
+    app.player.draw(frame)
+    return frame

staticfx/cli/__init__.py

@@ -0,0 +1,20 @@
+"""The ``staticfx`` command."""
+
+from __future__ import annotations
+
+import sys
+
+from staticfx.cli.commands import HANDLERS
+from staticfx.cli.parser import COMMANDS, build, translate
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = translate(list(sys.argv[1:] if argv is None else argv))
+    if not args or (args[0] not in COMMANDS and args[0] not in ("-h", "--help", "--version")):
+        args = ["play", *args]  # plain `staticfx [options]` plays
+    options = build().parse_args(args)
+    # Output may be piped or the locale may be C; a glyph must never crash a listing.
+    reconfigure = getattr(sys.stdout, "reconfigure", None)
+    if reconfigure is not None:
+        reconfigure(errors="replace")
+    return HANDLERS[options.command](options)

staticfx/cli/commands.py

@@ -0,0 +1,293 @@
+"""One function per subcommand. Each returns the process exit code."""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import platform
+import random
+import sys
+import time
+from pathlib import Path
+
+from staticfx import __version__, themes
+from staticfx.app import session
+from staticfx.app.app import App
+from staticfx.core.frame import Frame
+from staticfx.core.renderer import Renderer
+from staticfx.core.terminal import is_interactive, supported, terminal_size
+from staticfx.effects.engine import generate
+from staticfx.effects.spec import BUILTIN, GENERATED, USER
+from staticfx.integrations import overlay, system_info
+from staticfx.library import config
+from staticfx.library.effects import EffectLibrary, UserEffect, export
+from staticfx.library.files import clean_name, default_data_dir, slugify
+from staticfx.library.looks import BUILTIN_LOOKS, find_look
+
+EXIT_OK, EXIT_ERROR, EXIT_USAGE = 0, 1, 2
+
+
+def fail(message: str, code: int = EXIT_USAGE) -> int:
+    print(f"staticfx: {message}", file=sys.stderr)
+    return code
+
+
+def data_dir(args: argparse.Namespace) -> Path:
+    return Path(args.data_dir).expanduser() if args.data_dir else default_data_dir()
+
+
+def load_app(args: argparse.Namespace, persist: bool = False) -> App:
+    """The app with the user's settings and library loaded, and the command-line
+    options from the "what to show" group applied on top."""
+    folder = data_dir(args)
+    settings, warnings = config.load(folder / "config.json")
+    seed = getattr(args, "seed", None)
+    app = App(
+        settings,
+        folder,
+        utf8=session.supports_utf8(),
+        persist_settings=persist,
+        rng=random.Random(seed),
+    )
+    app.notes += warnings
+    if getattr(args, "ascii", False):
+        app.override("characters", "ascii")
+    elif getattr(args, "katakana", False):
+        app.override("characters", "katakana")
+    app.apply_characters()
+    app.start()
+    return app
+
+
+def apply_look_options(app: App, args: argparse.Namespace) -> str | None:
+    """Apply --look, --effect, --theme, --speed and the filters. Returns an error, if any."""
+    if args.look:
+        look = find_look(args.look, app.looks)
+        if look is None:
+            names = ", ".join(look.name for look in (*app.looks.looks, *BUILTIN_LOOKS))
+            return f"no look called '{args.look}' (try one of: {names})"
+        app.settings.allow_flashing |= look.theme == "strobe" and args.theme == "strobe"
+        app.apply_look(look)
+    effect = getattr(args, "effect_name", None) or args.effect
+    if effect:
+        if effect.lower() == "random":
+            app.play_random()
+        else:
+            try:
+                app.play(app.registry.resolve(effect), announce=False)
+            except KeyError:
+                return f"unknown effect '{effect}' (search with: staticfx list {effect})"
+    if args.theme:
+        app.set_theme(args.theme)
+    if args.speed:
+        app.player.speed = min(5.0, max(0.1, args.speed))
+    post = app.player.post
+    for name in ("crt", "glitch", "recolour"):
+        value = getattr(args, name)
+        if value is not None:
+            setattr(post, name, value)
+    return None
+
+
+def play(args: argparse.Namespace) -> int:
+    if not supported():
+        return fail("the interactive app needs Linux, macOS or WSL (try `staticfx render`)")
+    if not is_interactive():
+        return fail("the interactive app needs a terminal; for piped output use `staticfx render`")
+    app = load_app(args, persist=not args.no_save)
+    app.player.adaptive = True
+    app.player.reload()
+    if args.fps:
+        app.override("fps", args.fps)
+    if args.color256:
+        app.override("colour", "256")
+    error = apply_look_options(app, args)
+    if error:
+        return fail(error)
+    if args.auto:
+        low, high = config.AUTO_RANGE
+        app.override("auto_seconds", min(high, max(low, args.auto)))
+        app.auto = True
+        app.auto_timer = app.settings.auto_seconds
+    with contextlib.suppress(KeyboardInterrupt):  # SIGINT from outside; Ctrl-C is a key
+        session.run(app, args.duration)
+    for note in app.notes:
+        print(f"staticfx: {note}", file=sys.stderr)
+    return EXIT_OK
+
+
+def render(args: argparse.Namespace) -> int:
+    app = load_app(args)
+    error = apply_look_options(app, args)
+    if error:
+        return fail(error)
+    app.resize(*args.size)
+    frame = session.render_frames(app, args.frames)
+    text = (
+        Renderer(truecolor=not args.color256).full(frame) if args.ansi else "\n".join(frame.lines())
+    )
+    if args.out:
+        try:
+            Path(args.out).write_text(text + "\n", encoding="utf-8")
+        except OSError as exc:
+            return fail(f"can't write {args.out}: {exc.strerror}", EXIT_ERROR)
+    else:
+        print(text)
+    return EXIT_OK
+
+
+def fetch(args: argparse.Namespace) -> int:
+    try:
+        info = system_info(args.tool)
+    except RuntimeError as exc:
+        return fail(str(exc), EXIT_ERROR)
+    app = load_app(args)
+    error = apply_look_options(app, args)
+    if error:
+        return fail(error)
+    width, height = terminal_size() if is_interactive() else (80, 24)
+    app.resize(width, height - 1)
+    frame = session.render_frames(app, 90)
+    overlay(frame, app.player.theme(), info)
+    print(Renderer(truecolor=session.wants_truecolor(app)).full(frame))
+    return EXIT_OK
+
+
+def list_effects(args: argparse.Namespace) -> int:
+    app = load_app(args)
+    specs = app.registry.specs()
+    if args.kind == "gallery":
+        specs = [app.registry[k] for k in app.registry.gallery]
+    elif args.kind:
+        kind = {"mine": USER, "generated": GENERATED}.get(args.kind, args.kind)
+        specs = [s for s in specs if s.kind == kind]
+    if args.favorites:
+        specs = [s for s in specs if app.is_favorite(s.key)]
+    words = [w.lower() for w in args.query]
+    specs = [s for s in specs if all(w in s.search_text() for w in words)]
+    for spec in specs:
+        star = "*" if app.is_favorite(spec.key) else " "
+        print(f"{star} {spec.key:<20} {spec.label:<30} {spec.category}")
+    if not specs:
+        print("No effects match.", file=sys.stderr)
+    return EXIT_OK
+
+
+def list_themes(args: argparse.Namespace) -> int:
+    for key, label in themes.LABELS.items():
+        note = "  (flashing: allow it in Settings first)" if key == "strobe" else ""
+        print(f"{key:<10} {label}{note}")
+    return EXIT_OK
+
+
+def list_looks(args: argparse.Namespace) -> int:
+    app = load_app(args)
+    for heading, looks in (("Yours", app.looks.looks), ("Built in", BUILTIN_LOOKS)):
+        print(f"{heading}:")
+        if not looks:
+            save = app.keymap.label("save_look", ascii_only=True)
+            print(f"  (none yet: press {save} while an effect plays to save one)")
+        for look in looks:
+            print(f"  {look.name:<20} {look.effect:<18} {look.theme:<10} {look.note}")
+    return EXIT_OK
+
+
+def new_effect(args: argparse.Namespace) -> int:
+    name = clean_name(args.name)
+    if not name:
+        return fail("the effect needs a name")
+    library = EffectLibrary(data_dir(args) / "effects")
+    seed = args.seed if args.seed is not None else random.randrange(10**6, 10**7)
+    effect = UserEffect(library.unique_id(name), name, generate(seed)[0])
+    try:
+        path = library.save(effect)
+    except OSError as exc:
+        return fail(f"can't save: {exc.strerror}", EXIT_ERROR)
+    print(f"Created '{name}' in {path}\nPlay it with:  staticfx -e {effect.key}")
+    return EXIT_OK
+
+
+def import_effect(args: argparse.Namespace) -> int:
+    library = EffectLibrary(data_dir(args) / "effects")
+    try:
+        effect = library.import_file(Path(args.file))
+    except (ValueError, OSError) as exc:
+        return fail(f"import failed: {exc}", EXIT_ERROR)
+    print(f"Imported '{effect.name}'. Play it with:  staticfx -e {effect.key}")
+    return EXIT_OK
+
+
+def export_effect(args: argparse.Namespace) -> int:
+    app = load_app(args)
+    try:
+        spec = app.registry[app.registry.resolve(args.effect)]
+    except KeyError:
+        return fail(f"unknown effect '{args.effect}'")
+    if spec.recipe is None:
+        return fail(f"'{spec.label}' is hand-written; only Studio and generated effects export")
+    effect = UserEffect(slugify(spec.label), spec.label, spec.recipe, spec.description)
+    try:
+        path = export(effect, Path(args.file))
+    except OSError as exc:
+        return fail(f"can't write {args.file}: {exc.strerror}", EXIT_ERROR)
+    print(f"Exported '{spec.label}' to {path}")
+    return EXIT_OK
+
+
+def doctor(args: argparse.Namespace) -> int:
+    """Report on the environment and saved files, then render every effect once."""
+    folder = data_dir(args)
+    print(f"StaticFX {__version__} on Python {platform.python_version()} ({platform.system()})")
+    width, height = terminal_size()
+    traits = [
+        "interactive" if is_interactive() else "not a terminal",
+        f"{width}x{height}",
+        "UTF-8" if session.supports_utf8() else "ASCII only",
+        "truecolor" if session.supports_truecolor() else "256 colours",
+    ]
+    print(f"terminal    {', '.join(traits)} (colour support is a best guess)")
+    if not supported():
+        print("            interactive mode is not supported here (needs Linux, macOS or WSL)")
+    print(f"data folder {folder}")
+
+    app = load_app(args)
+    registry = app.registry
+    counts = f"{registry.count(BUILTIN)} built in, {registry.count(GENERATED)} generated"
+    print(f"effects     {len(registry)}: {counts}, {registry.count(USER)} yours")
+    print(f"looks       {len(app.looks.looks)} saved, {len(BUILTIN_LOOKS)} built in")
+    for note in app.notes:
+        print(f"  warning   {note}")
+
+    keys = [s.key for s in registry.specs() if s.kind != GENERATED]
+    keys += [s.key for s in registry.specs() if s.kind == GENERATED][::20]
+    print(f"self-test   rendering {len(keys)} effects...", end="", flush=True)
+    failures, started = [], time.perf_counter()
+    theme = themes.STATIC_THEMES[themes.DEFAULT]
+    for key in keys:
+        try:
+            effect = registry.make(key, random.Random(1))
+            effect.resize(80, 24)
+            frame = Frame(80, 24)
+            for _ in range(5):
+                effect.update(1 / 30)
+                effect.draw(frame, theme)
+        except Exception as exc:  # report every broken effect rather than stopping at one
+            failures.append(f"{key}: {exc.__class__.__name__}: {exc}")
+    print(f" {len(keys) - len(failures)} ok in {time.perf_counter() - started:.1f}s")
+    for failure in failures:
+        print(f"  FAILED    {failure}")
+    return EXIT_ERROR if failures else EXIT_OK
+
+
+HANDLERS = {
+    "play": play,
+    "render": render,
+    "fetch": fetch,
+    "list": list_effects,
+    "themes": list_themes,
+    "looks": list_looks,
+    "new": new_effect,
+    "import": import_effect,
+    "export": export_effect,
+    "doctor": doctor,
+}

staticfx/cli/parser.py

@@ -0,0 +1,185 @@
+"""Command-line arguments."""
+
+from __future__ import annotations
+
+import argparse
+
+from staticfx import __version__, themes
+
+COMMANDS = (
+    "play",
+    "list",
+    "themes",
+    "looks",
+    "new",
+    "import",
+    "export",
+    "render",
+    "fetch",
+    "doctor",
+)
+
+EPILOG = """\
+In the app: arrows browse, m opens the effect browser, t themes, l looks,
+n the Studio, o settings, ? every key.
+
+examples:
+  staticfx                         play (picks up where you left off)
+  staticfx -e plasma -t ocean      start on an effect and theme
+  staticfx --auto 20               screensaver: a new effect every 20 seconds
+  staticfx list fire               search effects
+  staticfx render galaxy --size 80x24 --ansi > galaxy.txt
+"""
+
+
+def size(text: str) -> tuple[int, int]:
+    try:
+        width, height = (int(part) for part in text.lower().split("x"))
+    except ValueError:
+        raise argparse.ArgumentTypeError("size must look like 80x24") from None
+    if not (1 <= width <= 1000 and 1 <= height <= 500):
+        raise argparse.ArgumentTypeError("size must be between 1x1 and 1000x500")
+    return width, height
+
+
+def positive(text: str) -> float:
+    try:
+        value = float(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"not a number: {text}") from None
+    if value <= 0:
+        raise argparse.ArgumentTypeError("must be greater than zero")
+    return value
+
+
+def theme(text: str) -> str:
+    try:
+        return themes.normalize(text)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError(str(exc)) from None
+
+
+def build() -> argparse.ArgumentParser:
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--data-dir", metavar="DIR", help="where effects, looks and settings live")
+
+    look = argparse.ArgumentParser(add_help=False)
+    group = look.add_argument_group("what to show")
+    group.add_argument("-e", "--effect", help="effect key, name, proc42-style number, or 'random'")
+    group.add_argument("-t", "--theme", type=theme, help=f"one of: {', '.join(themes.LABELS)}")
+    group.add_argument("--look", help="start from a saved or built-in look")
+    group.add_argument("--speed", type=positive, help="animation speed (1.0 is normal)")
+    group.add_argument("--crt", action=argparse.BooleanOptionalAction, help="CRT scanlines")
+    group.add_argument("--glitch", action=argparse.BooleanOptionalAction, help="glitch filter")
+    group.add_argument("--recolour", action=argparse.BooleanOptionalAction, help="rainbow recolour")
+    group.add_argument("--seed", type=int, help="random seed, for reproducible output")
+    group.add_argument("--ascii", action="store_true", help="plain ASCII only")
+    group.add_argument("--katakana", action="store_true", help="katakana in the rain effects")
+
+    parser = argparse.ArgumentParser(
+        prog="staticfx",
+        description="Animated ASCII effects for your terminal.",
+        epilog=EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"StaticFX {__version__}")
+    sub = parser.add_subparsers(dest="command", metavar="COMMAND")
+
+    play = sub.add_parser("play", parents=[common, look], help="run the app (the default)")
+    play.add_argument(
+        "--auto",
+        type=positive,
+        nargs="?",
+        const=12.0,
+        metavar="SECS",
+        help="change effect every SECS seconds (default 12)",
+    )
+    play.add_argument("--duration", type=positive, metavar="SECS", help="quit after SECS seconds")
+    play.add_argument("--fps", type=int, choices=range(5, 61), metavar="5-60", help="frame rate")
+    play.add_argument("--256", dest="color256", action="store_true", help="force 256 colours")
+    play.add_argument("--no-save", action="store_true", help="don't save settings on exit")
+
+    lister = sub.add_parser("list", parents=[common], help="list or search effects")
+    lister.add_argument("query", nargs="*", help="words to search for")
+    lister.add_argument("--kind", choices=("builtin", "generated", "mine", "gallery"))
+    lister.add_argument("--favorites", action="store_true", help="only your favourites")
+
+    sub.add_parser("themes", parents=[common], help="list themes")
+    sub.add_parser("looks", parents=[common], help="list saved and built-in looks")
+
+    new = sub.add_parser("new", parents=[common], help="create a random effect in My Effects")
+    new.add_argument("name")
+    new.add_argument("--seed", type=int, help="pick the starting recipe")
+
+    importer = sub.add_parser("import", parents=[common], help="add a .sfx file to My Effects")
+    importer.add_argument("file")
+
+    exporter = sub.add_parser("export", parents=[common], help="save an effect as a .sfx file")
+    exporter.add_argument("effect", help="one of your effects, or a generated one (proc_NNN)")
+    exporter.add_argument("file")
+
+    render = sub.add_parser("render", parents=[common, look], help="print one frame and exit")
+    render.add_argument("effect_name", nargs="?", metavar="EFFECT")
+    render.add_argument("--size", type=size, default=(80, 24), metavar="WxH")
+    render.add_argument(
+        "--frames", type=int, default=60, metavar="N", help="frames to simulate first (default 60)"
+    )
+    render.add_argument("--ansi", action="store_true", help="keep colours (escape codes)")
+    render.add_argument("--256", dest="color256", action="store_true", help="256-colour codes")
+    render.add_argument("--out", metavar="FILE", help="write to FILE instead of the screen")
+
+    fetch = sub.add_parser("fetch", parents=[common, look], help="system info over an effect")
+    fetch.add_argument(
+        "--tool", choices=("fastfetch", "neofetch"), help="default: whichever is installed"
+    )
+
+    sub.add_parser("doctor", parents=[common], help="check your setup and run a self-test")
+    return parser
+
+
+# StaticFX 1.x flags, mapped to the commands that replaced them.
+LEGACY_COMMANDS = {
+    "--list": "list",
+    "--favorites": "list",
+    "--themes": "themes",
+    "--looks": "looks",
+    "--presets": "looks",
+    "--scenes": "looks",
+    "--new-effect": "new",
+    "--import": "import",
+    "--export": "export",
+    "--frames": "render",
+    "--fetch": "fetch",
+    "--smoke-test": "doctor",
+    "--info": "doctor",
+}
+LEGACY_RENAMES = {
+    "--mode": "--effect",
+    "--rainbow": "--recolour",
+    "--no-rainbow": "--no-recolour",
+    "--unicode": "--katakana",
+    "--color256": "--256",
+    "--preset": "--look",
+    "--scene": "--look",
+    "--no-config": "--no-save",
+}
+LEGACY_KEPT = {"--favorites": "--favorites", "--fetch": "--tool", "--frames": "--frames"}
+LEGACY_DROPPED = {"--no-unicode", "--no-katakana", "--no-256", "--no-color256", "--plugin-dir"}
+
+
+def translate(argv: list[str]) -> list[str]:
+    """Rewrite a 1.x command line (``--list fire``) into the new form (``list fire``)."""
+    command = None
+    out: list[str] = []
+    args = iter(argv)
+    for arg in args:
+        if arg in LEGACY_DROPPED:
+            if arg == "--plugin-dir":
+                next(args, None)
+        elif arg in LEGACY_COMMANDS:
+            command = command or LEGACY_COMMANDS[arg]
+            if arg in LEGACY_KEPT:  # these become the command *and* keep an option
+                out.append(LEGACY_KEPT[arg])
+        else:
+            out.append(LEGACY_RENAMES.get(arg, arg))
+    return [command, *out] if command else out

staticfx/core/__init__.py

@@ -0,0 +1 @@
+"""Terminal plumbing with no knowledge of effects: colour, frames, rendering, input."""

staticfx/core/clock.py

@@ -0,0 +1,30 @@
+"""Frame pacing."""
+
+from __future__ import annotations
+
+import time
+
+# A frame that took longer than this (a suspend, a debugger pause, a slow
+# terminal) is treated as if it took this long, so simulations never take
+# one enormous step.
+MAX_STEP = 0.25
+
+
+class FrameClock:
+    def __init__(self, fps: float) -> None:
+        self.interval = 1.0 / max(1.0, fps)
+        self._last = time.perf_counter()
+        self._frame_start = self._last
+
+    def tick(self) -> float:
+        """Start a frame; returns the seconds since the previous one."""
+        now = time.perf_counter()
+        dt = min(MAX_STEP, max(0.0, now - self._last))
+        self._last = self._frame_start = now
+        return dt
+
+    def wait(self) -> None:
+        """Sleep off whatever is left of this frame's time budget."""
+        remaining = self.interval - (time.perf_counter() - self._frame_start)
+        if remaining > 0:
+            time.sleep(remaining)