orthodox-spinner 0.1.1__tar.gz

orthodox_spinner-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,54 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]   # only fires when you publish a GitHub Release
+
+permissions:
+  contents: read
+
+jobs:
+  # ── 1. Build & verify ────────────────────────────────────────────────────
+  build:
+    name: Build & verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Check PyPI metadata
+        run: twine check --strict dist/*
+
+      - name: Smoke-test the wheel
+        run: |
+          pip install dist/*.whl
+          spin --version
+          spin echo "orthodox cross spinner works"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # ── 2. Upload to PyPI (only if build passes) ─────────────────────────────
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

orthodox_spinner-0.1.1/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/

orthodox_spinner-0.1.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: orthodox-spinner
+Version: 0.1.1
+Summary: A terminal spinner shaped like an orthodox cross ☦
+Project-URL: Homepage, https://github.com/samsonofzorah/orthodox-spinner
+Project-URL: Source, https://github.com/samsonofzorah/orthodox-spinner
+Author-email: Vasily Piccone <vasily.piccone@gmail.com>
+License: MIT
+Keywords: cli,loading,spinner,terminal
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Terminals
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# orthodox-spinner ☦
+
+A terminal spinner shaped like an orthodox cross that breathes in and out.
+
+```
+☦  npm install
+```
+
+The `☦` pulses from bright to dim while any command runs, then clears — replacing whatever spinner the tool would have shown.
+
+---
+
+## Installation
+
+**Recommended (isolated CLI tool):**
+```sh
+pipx install git+https://github.com/samsonofzorah/orthodox-spinner.git
+```
+
+> **macOS + Homebrew Python 3.14 note:** if pipx errors with `ImportError: dlopen … pyexpat`, pipx's shared env is on Python 3.14 which has a broken libexpat on macOS. Fix it with:
+> ```sh
+> PIPX_DEFAULT_PYTHON=/opt/homebrew/bin/python3.12 pipx install git+https://github.com/samsonofzorah/orthodox-spinner.git
+> ```
+
+**Or with pip (Python 3.11–3.13 all work):**
+```sh
+pip install git+https://github.com/samsonofzorah/orthodox-spinner.git
+```
+
+---
+
+## CLI usage
+
+Wrap any command — its output is buffered and shown after the spinner clears:
+
+```sh
+spin npm install
+spin make build
+spin -m "Deploying…" ./deploy.sh
+```
+
+| Flag | Description |
+|------|-------------|
+| `-m TEXT` / `--message TEXT` | Label beside the spinner (default: the command itself) |
+| `--version` | Print version and exit |
+
+---
+
+## Python library
+
+```python
+from orthodox_spinner import Spinner
+
+# context manager
+with Spinner("installing"):
+    subprocess.run(["npm", "install"])
+
+# manual control
+s = Spinner("building").start()
+do_work()
+s.stop()
+```
+
+---
+
+## Shell integrations
+
+To replace the built-in spinners of common tools system-wide, source the
+provided shell file in your `~/.zshrc`:
+
+```sh
+echo 'source /path/to/orthodox-spinner/shell/orthodox_spinner.zsh' >> ~/.zshrc
+```
+
+Or copy the relevant functions directly into your `~/.zshrc`.
+
+**Covered tools:** `npm`, `pip`, `pip3`, `brew`, `yarn`, `cargo`
+
+Each wrapper only activates for slow subcommands (install, build, update, etc.)
+and falls through to the real binary for everything else.
+
+---
+
+## How it works
+
+`spin <cmd>` runs the command with its stdout/stderr captured, shows the
+breathing `☦` spinner on stderr, then flushes the buffered output once the
+command exits. The spinner is written to stderr so it does not pollute piped
+output.
+
+The animation uses ANSI 256-color grayscale codes (no dependencies beyond the
+Python standard library).
+
+---
+
+## Requirements
+
+- Python ≥ 3.8
+- A 256-color terminal (iTerm2, Terminal.app on macOS, most modern terminals)

orthodox_spinner-0.1.1/README.md

@@ -0,0 +1,99 @@
+# orthodox-spinner ☦
+
+A terminal spinner shaped like an orthodox cross that breathes in and out.
+
+```
+☦  npm install
+```
+
+The `☦` pulses from bright to dim while any command runs, then clears — replacing whatever spinner the tool would have shown.
+
+---
+
+## Installation
+
+**Recommended (isolated CLI tool):**
+```sh
+pipx install git+https://github.com/samsonofzorah/orthodox-spinner.git
+```
+
+> **macOS + Homebrew Python 3.14 note:** if pipx errors with `ImportError: dlopen … pyexpat`, pipx's shared env is on Python 3.14 which has a broken libexpat on macOS. Fix it with:
+> ```sh
+> PIPX_DEFAULT_PYTHON=/opt/homebrew/bin/python3.12 pipx install git+https://github.com/samsonofzorah/orthodox-spinner.git
+> ```
+
+**Or with pip (Python 3.11–3.13 all work):**
+```sh
+pip install git+https://github.com/samsonofzorah/orthodox-spinner.git
+```
+
+---
+
+## CLI usage
+
+Wrap any command — its output is buffered and shown after the spinner clears:
+
+```sh
+spin npm install
+spin make build
+spin -m "Deploying…" ./deploy.sh
+```
+
+| Flag | Description |
+|------|-------------|
+| `-m TEXT` / `--message TEXT` | Label beside the spinner (default: the command itself) |
+| `--version` | Print version and exit |
+
+---
+
+## Python library
+
+```python
+from orthodox_spinner import Spinner
+
+# context manager
+with Spinner("installing"):
+    subprocess.run(["npm", "install"])
+
+# manual control
+s = Spinner("building").start()
+do_work()
+s.stop()
+```
+
+---
+
+## Shell integrations
+
+To replace the built-in spinners of common tools system-wide, source the
+provided shell file in your `~/.zshrc`:
+
+```sh
+echo 'source /path/to/orthodox-spinner/shell/orthodox_spinner.zsh' >> ~/.zshrc
+```
+
+Or copy the relevant functions directly into your `~/.zshrc`.
+
+**Covered tools:** `npm`, `pip`, `pip3`, `brew`, `yarn`, `cargo`
+
+Each wrapper only activates for slow subcommands (install, build, update, etc.)
+and falls through to the real binary for everything else.
+
+---
+
+## How it works
+
+`spin <cmd>` runs the command with its stdout/stderr captured, shows the
+breathing `☦` spinner on stderr, then flushes the buffered output once the
+command exits. The spinner is written to stderr so it does not pollute piped
+output.
+
+The animation uses ANSI 256-color grayscale codes (no dependencies beyond the
+Python standard library).
+
+---
+
+## Requirements
+
+- Python ≥ 3.8
+- A 256-color terminal (iTerm2, Terminal.app on macOS, most modern terminals)

orthodox_spinner-0.1.1/demo.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""
+Orthodox Cross Spinner — demo of 3 animation styles.
+Run with:  python3 demo.py
+"""
+
+import sys
+import time
+
+def w(s): sys.stdout.write(s); sys.stdout.flush()
+
+HIDE  = '\033[?25l'
+SHOW  = '\033[?25h'
+GOLD  = '\033[38;5;220m'
+DIM_G = '\033[38;5;136m'
+DIM_W = '\033[38;5;242m'
+WHITE = '\033[97m'
+RST   = '\033[0m'
+
+# ── 1. Breathing — single ☦ pulsing in brightness ────────────────────────────
+
+def breathing_frames():
+    cross = '☦'
+    lo, hi = 238, 255
+    ramp = list(range(hi, lo - 1, -1)) + list(range(lo + 1, hi + 1, 1))
+    return [f'\033[38;5;{n}m{cross}{RST}' for n in ramp]
+
+def run_breathing(seconds=7, fps=18):
+    frames = breathing_frames()
+    n = len(frames)
+    end = time.time() + seconds
+    i = 0
+    while time.time() < end:
+        w(f'\r\033[K  {frames[i % n]}  loading...')
+        time.sleep(1 / fps)
+        i += 1
+    w('\r\033[K')
+
+# ── 2. Dots drawing the cross segment-by-segment, then erasing ───────────────
+
+W, H = 7, 5
+
+# Each list is one segment of the orthodox cross, drawn in order:
+#   top small bar → upper shaft → main crossbar → lower shaft → diagonal
+SEGS = [
+    [(0, 3)],
+    [(1, 3)],
+    [(2, 0),(2,1),(2,2),(2,3),(2,4),(2,5),(2,6)],
+    [(3, 3)],
+    [(4, 2),(4, 1)],
+]
+
+def dot_grid(lit, char='●', color=GOLD):
+    g = [[' '] * W for _ in range(H)]
+    for r, c in lit:
+        g[r][c] = f'{color}{char}{RST}'
+    return [''.join(row) for row in g]
+
+def dot_frames():
+    fs = []
+    lit = []
+    for seg in SEGS:
+        lit = lit + seg
+        fs += [dot_grid(lit)] * 4          # draw each segment
+    all_pts = [p for s in SEGS for p in s]
+    for k in range(8):                     # glow: alternate filled / hollow
+        char  = '●' if k % 2 == 0 else '○'
+        color = GOLD if k % 2 == 0 else DIM_G
+        fs   += [dot_grid(all_pts, char, color)] * 3
+    lit = list(all_pts)
+    for seg in reversed(SEGS):            # erase in reverse order
+        for p in seg:
+            lit.remove(p)
+        fs += [dot_grid(lit)] * 4
+    fs += [dot_grid([])] * 4              # pause on empty
+    return fs
+
+# ── 3. Bright dot travels along the arms of the cross ────────────────────────
+
+def base_grid():
+    g = [[' '] * W for _ in range(H)]
+    g[0][3] = f'{DIM_W}─{RST}'
+    g[1][3] = f'{DIM_W}│{RST}'
+    for c in range(W):
+        g[2][c] = f'{DIM_W}─{RST}'
+    g[2][3] = f'{DIM_W}┼{RST}'
+    g[3][3] = f'{DIM_W}│{RST}'
+    g[4][1] = f'{DIM_W}╲{RST}'
+    g[4][2] = f'{DIM_W}╲{RST}'
+    return g
+
+def travel_frames():
+    path = (
+        [(2,3)]
+        + [(1,3),(0,3)]               # up to top bar
+        + [(1,3),(2,3)]               # back to center
+        + [(2,4),(2,5),(2,6)]         # right arm
+        + [(2,5),(2,4),(2,3)]         # back
+        + [(2,2),(2,1),(2,0)]         # left arm
+        + [(2,1),(2,2),(2,3)]         # back
+        + [(3,3),(4,2),(4,1)]         # down + diagonal
+        + [(4,2),(3,3),(2,3)]         # back to center
+    )
+    fs = []
+    for r, c in path:
+        g = base_grid()
+        g[r][c] = f'{WHITE}●{RST}'
+        rows = [''.join(row) for row in g]
+        fs += [rows, rows]            # hold each position 2 frames
+    return fs
+
+# ── Shared multi-line runner ──────────────────────────────────────────────────
+
+def run_ml(frames, fps=10, loops=1):
+    total = len(frames) * loops
+    first = True
+    for i in range(total):
+        f = frames[i % len(frames)]
+        if not first:
+            w(f'\033[{H}A')
+        for row in f:
+            w(f'\r\033[2K  {row}\n')
+        first = False
+        time.sleep(1 / fps)
+
+# ── Entry point ───────────────────────────────────────────────────────────────
+
+def hdr(n, title):
+    bar = '─' * (len(title) + 6)
+    print(f'\n  [{n}/3]  {title}')
+    print(f'  {bar}\n')
+
+def main():
+    try:
+        w(HIDE)
+        print('\n  ☦  Orthodox Cross Spinner — Animation Demo')
+        print('      Ctrl-C to exit early.\n')
+
+        hdr(1, 'Breathing  — single ☦ oscillating in brightness')
+        run_breathing(seconds=7, fps=18)
+        print()
+        time.sleep(0.6)
+
+        hdr(2, 'Dot cross  — draws then erases the cross with dots')
+        run_ml(dot_frames(), fps=10, loops=2)
+        time.sleep(0.6)
+
+        hdr(3, 'Traveler   — dot traces each arm of the cross')
+        run_ml(travel_frames(), fps=10, loops=3)
+
+        print('\n\n  Done — let me know which style (or combo) you want!\n')
+
+    except KeyboardInterrupt:
+        print('\n\n  (exited early)\n')
+    finally:
+        w(SHOW)
+
+if __name__ == '__main__':
+    main()

orthodox_spinner-0.1.1/pyproject.toml

@@ -0,0 +1,30 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "orthodox-spinner"
+version = "0.1.1"
+description = "A terminal spinner shaped like an orthodox cross ☦"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "Vasily Piccone", email = "vasily.piccone@gmail.com" }]
+keywords = ["spinner", "terminal", "cli", "loading"]
+classifiers = [
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Terminals",
+]
+
+[project.urls]
+Homepage = "https://github.com/samsonofzorah/orthodox-spinner"
+Source   = "https://github.com/samsonofzorah/orthodox-spinner"
+
+[project.scripts]
+spin = "orthodox_spinner.core:cli"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/orthodox_spinner"]

orthodox_spinner-0.1.1/shell/orthodox_spinner.zsh

@@ -0,0 +1,73 @@
+# orthodox_spinner.zsh
+# Source this file in ~/.zshrc to replace default spinners in common tools
+# with the breathing orthodox cross ☦.
+#
+# Usage: add to ~/.zshrc:
+#   source /path/to/orthodox-spinner/shell/orthodox_spinner.zsh
+
+# Internal helper — finds the real binary in PATH (bypasses these wrappers)
+# and hands off to `spin`.
+_spin_wrap() {
+  local cmd="$1" msg="$2"
+  shift 2
+  spin -m "$msg" /usr/bin/env "$cmd" "$@"
+}
+
+# npm — disable its own progress bar and replace with ☦
+npm() {
+  case "$1" in
+    install|i|ci|update|up|add|remove|uninstall|run)
+      _spin_wrap npm "npm $*" --no-progress "$@" ;;
+    *)
+      /usr/bin/env npm "$@" ;;
+  esac
+}
+
+# pip / pip3 — suppress pip's own progress output
+pip() {
+  case "$1" in
+    install|download|uninstall|wheel)
+      _spin_wrap pip "pip $*" "$@" ;;
+    *)
+      /usr/bin/env pip "$@" ;;
+  esac
+}
+
+pip3() {
+  case "$1" in
+    install|download|uninstall|wheel)
+      _spin_wrap pip3 "pip3 $*" "$@" ;;
+    *)
+      /usr/bin/env pip3 "$@" ;;
+  esac
+}
+
+# brew — wrap slow subcommands only
+brew() {
+  case "$1" in
+    install|reinstall|upgrade|uninstall|remove|fetch)
+      _spin_wrap brew "brew $*" "$@" ;;
+    *)
+      /usr/bin/env brew "$@" ;;
+  esac
+}
+
+# yarn
+yarn() {
+  case "$1" in
+    add|remove|install|upgrade|up)
+      _spin_wrap yarn "yarn $*" "$@" ;;
+    *)
+      /usr/bin/env yarn "$@" ;;
+  esac
+}
+
+# cargo
+cargo() {
+  case "$1" in
+    build|check|test|run|install|fetch)
+      _spin_wrap cargo "cargo $*" "$@" ;;
+    *)
+      /usr/bin/env cargo "$@" ;;
+  esac
+}

orthodox_spinner-0.1.1/src/orthodox_spinner/__init__.py

@@ -0,0 +1,3 @@
+from .core import Spinner
+
+__all__ = ["Spinner"]

orthodox_spinner-0.1.1/src/orthodox_spinner/core.py

@@ -0,0 +1,107 @@
+import sys
+import time
+import threading
+import subprocess
+import argparse
+from importlib.metadata import version as _pkg_version
+
+HIDE = '\033[?25l'
+SHOW = '\033[?25h'
+RST  = '\033[0m'
+
+def _frames():
+    lo, hi = 238, 255
+    ramp = list(range(hi, lo - 1, -1)) + list(range(lo + 1, hi + 1, 1))
+    return [f'\033[38;5;{n}m☦{RST}' for n in ramp]
+
+
+class Spinner:
+    """
+    Breathing orthodox cross spinner ☦.
+
+    Usage as context manager:
+        with Spinner("installing"):
+            ...
+
+    Usage manual:
+        s = Spinner("building").start()
+        ...
+        s.stop()
+    """
+
+    def __init__(self, text='', fps=18):
+        self.text = text
+        self.fps  = fps
+        self._stop   = threading.Event()
+        self._thread = None
+
+    def start(self):
+        sys.stderr.write(HIDE)
+        sys.stderr.flush()
+        self._stop.clear()
+        self._thread = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+        return self
+
+    def stop(self, success=True):
+        self._stop.set()
+        if self._thread:
+            self._thread.join()
+        sys.stderr.write(f'\r\033[K{SHOW}')
+        sys.stderr.flush()
+
+    def _spin(self):
+        frames = _frames()
+        n = len(frames)
+        i = 0
+        while not self._stop.is_set():
+            suffix = f'  {self.text}' if self.text else ''
+            sys.stderr.write(f'\r\033[K{frames[i % n]}{suffix}')
+            sys.stderr.flush()
+            time.sleep(1 / self.fps)
+            i += 1
+
+    def __enter__(self):
+        return self.start()
+
+    def __exit__(self, exc_type, *_):
+        self.stop(success=exc_type is None)
+
+
+def cli():
+    parser = argparse.ArgumentParser(
+        prog='spin',
+        description='Run a command with an orthodox cross spinner ☦',
+    )
+    parser.add_argument(
+        '--version',
+        action='version',
+        version=f'%(prog)s {_pkg_version("orthodox-spinner")}',
+    )
+    parser.add_argument(
+        '-m', '--message',
+        default='',
+        metavar='TEXT',
+        help='label shown beside the spinner (defaults to the command)',
+    )
+    parser.add_argument('command', nargs=argparse.REMAINDER)
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    label = args.message or ' '.join(args.command)
+
+    with Spinner(text=label):
+        result = subprocess.run(args.command, capture_output=True)
+
+    # flush buffered output after spinner clears
+    if result.stdout:
+        sys.stdout.buffer.write(result.stdout)
+        sys.stdout.buffer.flush()
+    if result.stderr:
+        sys.stderr.buffer.write(result.stderr)
+        sys.stderr.buffer.flush()
+
+    sys.exit(result.returncode)