tqrex 0.1.0__tar.gz

tqrex-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Lint & type-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dev deps
+        run: pip install -e ".[dev]"
+      - name: Ruff check
+        run: ruff check src/ tests/
+      - name: Ruff format
+        run: ruff format --check src/ tests/
+      - name: Mypy
+        run: mypy src/playgress
+
+  test:
+    name: Test — Python ${{ matrix.python-version }} / ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dev deps
+        run: pip install -e ".[dev]"
+      - name: Run tests (skip terminal-requiring tests in CI)
+        run: pytest -m "not terminal" --cov=playgress --cov-report=xml
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.11'
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false

tqrex-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+.venv/
+venv/
+env/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/

tqrex-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Samoilov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tqrex-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: tqrex
+Version: 0.1.0
+Summary: A progress bar that lets you play the Chrome T-Rex game in your terminal
+Project-URL: Homepage, https://github.com/Samoilov2004/tqrex
+Project-URL: Repository, https://github.com/Samoilov2004/tqrex
+Project-URL: Issues, https://github.com/Samoilov2004/tqrex/issues
+Project-URL: Changelog, https://github.com/Samoilov2004/tqrex/releases
+Author: Mikhail Samoilov
+License: MIT License
+        
+        Copyright (c) 2026 Mikhail Samoilov
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: cli,dinosaur,fun,game,progress,progress-bar,terminal,tqdm,trex
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment :: Arcade
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Terminals
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# playgress
+
+> A progress bar that lets you play the Chrome T-Rex game in your terminal.
+
+![demo](demo.gif)
+
+Your long-running script doesn't have to be boring. **playgress** wraps any
+iterable in a full T-Rex side-scroller — jump cacti, dodge birds, rack up a
+high score — while your real work happens in the background. When the task
+finishes the game keeps running until you decide to quit.
+
+---
+
+## Features
+
+- **Zero runtime dependencies** — pure Python standard library
+- **Drop-in `tqdm` replacement** — `track()` has the same call signature
+- **`Progress` context manager** — for manual update control
+- **60 FPS physics** — faithful gravity, jump arc, and speed curve from the
+  original Chrome dino
+- **Autoplay AI** — built-in geometric look-ahead controller (`autoplay=True`)
+- **Double-buffered renderer** — flicker-free diff-based redraw, single write
+  per frame
+- **Cross-platform** — macOS, Linux, Windows (ANSI terminal required)
+- **Python 3.11+**
+
+---
+
+## Installation
+
+```bash
+pip install playgress
+```
+
+Or for local development:
+
+```bash
+git clone https://github.com/mikhail-samoilov/playgress
+cd playgress
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart
+
+### Drop-in replacement for `tqdm`
+
+```python
+import time
+from playgress import track
+
+for item in track(range(100), description="Processing"):
+    time.sleep(0.05)
+```
+
+### Any iterable works
+
+```python
+files = ["data_001.csv", "data_002.csv", ...]
+
+for f in track(files, description="Crunching files"):
+    crunch(f)
+```
+
+### Manual control with the `Progress` context manager
+
+```python
+from playgress import Progress
+
+steps = ["Download", "Extract", "Build", "Install"]
+with Progress(total=len(steps), description="Installing") as p:
+    for step in steps:
+        p.set_description(f"Step: {step}")
+        run(step)
+        p.update(1)
+```
+
+### Let the AI play for you
+
+```python
+for epoch in track(range(200), description="Training", autoplay=True):
+    train_one_epoch(epoch)
+```
+
+---
+
+## Keyboard controls
+
+| Key | Action |
+|-----|--------|
+| `Space` / `↑` | Jump |
+| `↓` | Duck on ground / fast-drop mid-air |
+| `R` | Restart after game-over; replay after task completes |
+| `Q` / `Ctrl-C` | Quit — unblocks the script |
+
+> **Note:** The game keeps running after all items are processed so you can
+> finish your current run. Press **Q** when you're done.
+
+---
+
+## Themes
+
+The default theme uses prototype-verified ASCII art that renders crisply in
+every monospace font:
+
+```
+       ++++          /|\/|\       <o=-
+++    ++Q+++          |  |          |
+ + +++++_ww
+  ++++++
+   |   |
+```
+
+An `EMOJI` theme (`theme=Theme.EMOJI`) for full Unicode width terminals is on
+the roadmap.
+
+---
+
+## API reference
+
+### `track(iterable, *, description, total, theme, autoplay, disable)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `iterable` | `Iterable[T]` | — | Items to iterate over |
+| `description` | `str` | `"Processing..."` | Status line label |
+| `total` | `int \| None` | `None` | Item count; auto-inferred from `len()` |
+| `theme` | `Theme` | `Theme.AUTO` | Sprite theme |
+| `autoplay` | `bool` | `False` | Enable AI controller |
+| `disable` | `bool` | `False` | Skip game; yield items silently |
+
+Returns a generator that yields items from `iterable` unchanged.
+
+### `Progress(total, description, theme, autoplay)`
+
+| Method | Description |
+|--------|-------------|
+| `update(n=1)` | Advance by *n* steps (thread-safe) |
+| `set_description(text)` | Update the status line label |
+| `fraction` | Current progress as a float in `[0, 1]` |
+
+---
+
+## CI / non-interactive environments
+
+When `stdout` is not a TTY (piped output, GitHub Actions, `pytest`) the game
+is automatically bypassed and items are yielded with zero overhead. No
+`disable=True` guard needed.
+
+---
+
+## How it works
+
+```
+Main thread          Game thread (60 FPS)     Input thread
+──────────           ────────────────────     ────────────
+for item in track():
+  yield item    ←→   read ProgressState  ←←   push InputEvent
+  completed += 1     run physics               (termios raw mode /
+                     render diff frame          msvcrt poll)
+shutdown.wait()
+```
+
+Three threads, two shared objects: a `ProgressState` (protected by a
+`threading.Lock`) and a `queue.Queue[InputEvent]` (lock-free). The game thread
+owns all `GameState` mutations — no other thread touches it.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tqrex-0.1.0/README.md

@@ -0,0 +1,173 @@
+# playgress
+
+> A progress bar that lets you play the Chrome T-Rex game in your terminal.
+
+![demo](demo.gif)
+
+Your long-running script doesn't have to be boring. **playgress** wraps any
+iterable in a full T-Rex side-scroller — jump cacti, dodge birds, rack up a
+high score — while your real work happens in the background. When the task
+finishes the game keeps running until you decide to quit.
+
+---
+
+## Features
+
+- **Zero runtime dependencies** — pure Python standard library
+- **Drop-in `tqdm` replacement** — `track()` has the same call signature
+- **`Progress` context manager** — for manual update control
+- **60 FPS physics** — faithful gravity, jump arc, and speed curve from the
+  original Chrome dino
+- **Autoplay AI** — built-in geometric look-ahead controller (`autoplay=True`)
+- **Double-buffered renderer** — flicker-free diff-based redraw, single write
+  per frame
+- **Cross-platform** — macOS, Linux, Windows (ANSI terminal required)
+- **Python 3.11+**
+
+---
+
+## Installation
+
+```bash
+pip install playgress
+```
+
+Or for local development:
+
+```bash
+git clone https://github.com/mikhail-samoilov/playgress
+cd playgress
+pip install -e ".[dev]"
+```
+
+---
+
+## Quickstart
+
+### Drop-in replacement for `tqdm`
+
+```python
+import time
+from playgress import track
+
+for item in track(range(100), description="Processing"):
+    time.sleep(0.05)
+```
+
+### Any iterable works
+
+```python
+files = ["data_001.csv", "data_002.csv", ...]
+
+for f in track(files, description="Crunching files"):
+    crunch(f)
+```
+
+### Manual control with the `Progress` context manager
+
+```python
+from playgress import Progress
+
+steps = ["Download", "Extract", "Build", "Install"]
+with Progress(total=len(steps), description="Installing") as p:
+    for step in steps:
+        p.set_description(f"Step: {step}")
+        run(step)
+        p.update(1)
+```
+
+### Let the AI play for you
+
+```python
+for epoch in track(range(200), description="Training", autoplay=True):
+    train_one_epoch(epoch)
+```
+
+---
+
+## Keyboard controls
+
+| Key | Action |
+|-----|--------|
+| `Space` / `↑` | Jump |
+| `↓` | Duck on ground / fast-drop mid-air |
+| `R` | Restart after game-over; replay after task completes |
+| `Q` / `Ctrl-C` | Quit — unblocks the script |
+
+> **Note:** The game keeps running after all items are processed so you can
+> finish your current run. Press **Q** when you're done.
+
+---
+
+## Themes
+
+The default theme uses prototype-verified ASCII art that renders crisply in
+every monospace font:
+
+```
+       ++++          /|\/|\       <o=-
+++    ++Q+++          |  |          |
+ + +++++_ww
+  ++++++
+   |   |
+```
+
+An `EMOJI` theme (`theme=Theme.EMOJI`) for full Unicode width terminals is on
+the roadmap.
+
+---
+
+## API reference
+
+### `track(iterable, *, description, total, theme, autoplay, disable)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `iterable` | `Iterable[T]` | — | Items to iterate over |
+| `description` | `str` | `"Processing..."` | Status line label |
+| `total` | `int \| None` | `None` | Item count; auto-inferred from `len()` |
+| `theme` | `Theme` | `Theme.AUTO` | Sprite theme |
+| `autoplay` | `bool` | `False` | Enable AI controller |
+| `disable` | `bool` | `False` | Skip game; yield items silently |
+
+Returns a generator that yields items from `iterable` unchanged.
+
+### `Progress(total, description, theme, autoplay)`
+
+| Method | Description |
+|--------|-------------|
+| `update(n=1)` | Advance by *n* steps (thread-safe) |
+| `set_description(text)` | Update the status line label |
+| `fraction` | Current progress as a float in `[0, 1]` |
+
+---
+
+## CI / non-interactive environments
+
+When `stdout` is not a TTY (piped output, GitHub Actions, `pytest`) the game
+is automatically bypassed and items are yielded with zero overhead. No
+`disable=True` guard needed.
+
+---
+
+## How it works
+
+```
+Main thread          Game thread (60 FPS)     Input thread
+──────────           ────────────────────     ────────────
+for item in track():
+  yield item    ←→   read ProgressState  ←←   push InputEvent
+  completed += 1     run physics               (termios raw mode /
+                     render diff frame          msvcrt poll)
+shutdown.wait()
+```
+
+Three threads, two shared objects: a `ProgressState` (protected by a
+`threading.Lock`) and a `queue.Queue[InputEvent]` (lock-free). The game thread
+owns all `GameState` mutations — no other thread touches it.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

tqrex-0.1.0/examples/basic_usage.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+import sys
+import time
+
+from playgress import Progress, track
+from playgress.config import Theme
+
+
+def example_track() -> None:
+    """Process 60 items while playing the T-Rex game.
+
+    Keys during the game:
+      SPACE / ↑   jump
+      ↓           duck / fast-drop mid-air
+      R           restart after game-over or after task completes
+      Q           quit (unblocks the script)
+    """
+    files = [f"report_{i:04d}.csv" for i in range(60)]
+    for _f in track(files, description="Crunching reports"):
+        time.sleep(0.12)  # simulate I/O work
+
+def example_range() -> None:
+    """Iterate over range(100) — total is inferred automatically."""
+    for _i in track(range(100), description="Training epochs"):
+        time.sleep(0.05)
+
+def example_context() -> None:
+    """Use Progress when you control the update timing explicitly."""
+    steps = ["Download", "Unpack", "Compile", "Link", "Install"]
+    with Progress(total=len(steps), description="Building package") as p:
+        for step in steps:
+            p.set_description(f"Step: {step}")
+            time.sleep(0.8)
+            p.update(1)
+
+def example_autoplay() -> None:
+    """Let the AI controller play while your batch job runs."""
+    dataset = list(range(80))
+    for _d in track(dataset, description="Embedding vectors", autoplay=True):
+        time.sleep(0.08)
+
+_EXAMPLES: dict[str, tuple[str, object]] = {
+    "track":    ("Process 60 files (default)", example_track),
+    "range":    ("Iterate range(100)",         example_range),
+    "context":  ("Manual Progress manager",    example_context),
+    "autoplay": ("Autoplay AI controller",     example_autoplay),
+}
+
+if __name__ == "__main__":
+    mode = sys.argv[1] if len(sys.argv) > 1 else "track"
+    if mode not in _EXAMPLES:
+        print(f"Unknown example '{mode}'. Choose from: {', '.join(_EXAMPLES)}")
+        sys.exit(1)
+    label, fn = _EXAMPLES[mode]
+    print(f"Running: {label}")
+    fn()  # type: ignore[operator]
+    print("\nAll done. Goodbye!")