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)
