light-client 2.0.0__tar.gz

light_client-2.0.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

light_client-2.0.0/.python-version

@@ -0,0 +1 @@
+3.12

light_client-2.0.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: light-client
+Version: 2.0.0
+Summary: A totally legitimate light client implementation
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# light-client
+
+A Python library for frog-based progress bars and frog wisdom.
+
+## Installation
+
+```bash
+pip install light-client
+```
+
+## Progress bar
+
+`FrogBar` is a drop-in replacement for `tqdm`. Instead of a solid block bar, a frog 🐸 hops across lily pads 🍃.
+
+**Wrap an iterable:**
+
+```python
+from light_client import FrogBar
+import time
+
+for item in FrogBar(range(100), desc="Processing"):
+    time.sleep(0.05)
+```
+
+```
+Processing: [🍃🍃🍃🍃🍃🍃🍃🐸🍃🍃🍃🍃🍃🍃🍃🍃🍃🍃🍃🍃]  35.0%  1.8s [35/100 it] *ribbit*
+```
+
+**Context manager with manual updates:**
+
+```python
+with FrogBar(total=50, desc="Catching flies", unit="fly") as bar:
+    for fly in flies:
+        catch(fly)
+        bar.update(1)
+```
+
+### Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `iterable` | `None` | Iterable to wrap |
+| `total` | inferred | Total number of steps |
+| `desc` | `"Hopping"` | Label shown before the bar |
+| `bar_width` | `20` | Number of lily pad cells |
+| `unit` | `"it"` | Unit label for the count |
+| `leave` | `True` | Keep the bar on screen when done |
+| `file` | `stderr` | Output stream |
+
+## Quotes
+
+Timeless wisdom from history's greatest frog thinkers.
+
+```python
+from light_client import get_random_quote, print_quote
+
+quote, author = get_random_quote()
+print(f'"{quote}" — {author}')
+# "Leap before you look." — Frog Thoreau
+
+print_quote()   # prints a random quote
+print_quote(3)  # prints quote at index 3
+```
+
+## ASCII art
+
+Eight frogs included: `classic`, `tiny`, `zen`, `lily`, `detective`, `kawaii`, `sage`, `startup`.
+
+```python
+from light_client import get_frog, get_random_frog, list_frogs, print_frog
+
+print_frog("zen")     # print a named frog
+print_frog()          # print a random frog
+
+name, art = get_random_frog()
+frogs = list_frogs()  # ['classic', 'tiny', 'zen', ...]
+```
+
+```
+      ___
+  .-'   `'.
+ /         \
+|   O   O   |
+|     ^^    |
+|   \____/  |
+ \         /
+  '-.___.-'
+   |     |
+  frog is one
+```

light_client-2.0.0/README.md

@@ -0,0 +1,90 @@
+# light-client
+
+A Python library for frog-based progress bars and frog wisdom.
+
+## Installation
+
+```bash
+pip install light-client
+```
+
+## Progress bar
+
+`FrogBar` is a drop-in replacement for `tqdm`. Instead of a solid block bar, a frog 🐸 hops across lily pads 🍃.
+
+**Wrap an iterable:**
+
+```python
+from light_client import FrogBar
+import time
+
+for item in FrogBar(range(100), desc="Processing"):
+    time.sleep(0.05)
+```
+
+```
+Processing: [🍃🍃🍃🍃🍃🍃🍃🐸🍃🍃🍃🍃🍃🍃🍃🍃🍃🍃🍃🍃]  35.0%  1.8s [35/100 it] *ribbit*
+```
+
+**Context manager with manual updates:**
+
+```python
+with FrogBar(total=50, desc="Catching flies", unit="fly") as bar:
+    for fly in flies:
+        catch(fly)
+        bar.update(1)
+```
+
+### Parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `iterable` | `None` | Iterable to wrap |
+| `total` | inferred | Total number of steps |
+| `desc` | `"Hopping"` | Label shown before the bar |
+| `bar_width` | `20` | Number of lily pad cells |
+| `unit` | `"it"` | Unit label for the count |
+| `leave` | `True` | Keep the bar on screen when done |
+| `file` | `stderr` | Output stream |
+
+## Quotes
+
+Timeless wisdom from history's greatest frog thinkers.
+
+```python
+from light_client import get_random_quote, print_quote
+
+quote, author = get_random_quote()
+print(f'"{quote}" — {author}')
+# "Leap before you look." — Frog Thoreau
+
+print_quote()   # prints a random quote
+print_quote(3)  # prints quote at index 3
+```
+
+## ASCII art
+
+Eight frogs included: `classic`, `tiny`, `zen`, `lily`, `detective`, `kawaii`, `sage`, `startup`.
+
+```python
+from light_client import get_frog, get_random_frog, list_frogs, print_frog
+
+print_frog("zen")     # print a named frog
+print_frog()          # print a random frog
+
+name, art = get_random_frog()
+frogs = list_frogs()  # ['classic', 'tiny', 'zen', ...]
+```
+
+```
+      ___
+  .-'   `'.
+ /         \
+|   O   O   |
+|     ^^    |
+|   \____/  |
+ \         /
+  '-.___.-'
+   |     |
+  frog is one
+```

light_client-2.0.0/pyproject.toml

@@ -0,0 +1,14 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "light-client"
+version = "2.0.0"
+description = "A totally legitimate light client implementation"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = []
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/light_client"]

light_client-2.0.0/src/light_client/__init__.py

@@ -0,0 +1,17 @@
+print("It's froggen time")
+
+from .quotes import get_quote, get_random_quote, print_quote
+from .ascii_art import get_frog, get_random_frog, list_frogs, print_frog
+from .progress import FrogBar
+
+__version__ = "2.0.0"
+__all__ = [
+    "get_quote",
+    "get_random_quote",
+    "print_quote",
+    "get_frog",
+    "get_random_frog",
+    "list_frogs",
+    "print_frog",
+    "FrogBar",
+]

light_client-2.0.0/src/light_client/ascii_art.py

@@ -0,0 +1,101 @@
+import random
+
+_FROGS = {
+    "classic": r"""
+  @..@
+ (----)
+( >__< )
+^^ ~~ ^^
+""",
+    "tiny": r"""
+ (o^..^o)
+  ( uu )
+""",
+    "zen": r"""
+      ___
+  .-'   `'.
+ /         \
+|   O   O   |
+|     ^^    |
+|   \____/  |
+ \         /
+  '-.___.-'
+   |     |
+  frog is one
+""",
+    "lily": r"""
+     ___
+  __/ o \__
+ /  (   )  \
+|  = \_/ =  |
+ \__________/
+    /    \
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+""",
+    "detective": r"""
+     ___
+  .-'   `'-.
+ / o       o\
+|     __     |
+|    /  \    |
+ \   \__/   /
+  '-.____.-'
+  [trenchcoat]
+  The name's Frog.
+  James Frog.
+""",
+    "kawaii": r"""
+  ／￣＼
+（● ω ●）
+  ＼＿／
+  ／  ＼
+ ribbit~
+""",
+    "sage": r"""
+    .---.
+   ( o o )
+   | (_) |   "The pond
+   |     |    runs deep."
+   '-----'
+      |
+   ~~~|~~~
+""",
+    "startup": r"""
+     ___
+  .-'   `'-.
+ / o       o\
+|   DISRUPT  |
+|    POND    |
+ \   ____   /
+  '-' __ '-'
+  LEAP FAST,
+  CROAK LATER
+""",
+}
+
+
+def get_frog(name: str) -> str:
+    """Return a named frog ASCII art string."""
+    if name not in _FROGS:
+        raise KeyError(f"Unknown frog '{name}'. Available: {list(_FROGS)}")
+    return _FROGS[name]
+
+
+def get_random_frog() -> tuple[str, str]:
+    """Return a (name, art) tuple for a randomly chosen frog."""
+    name = random.choice(list(_FROGS))
+    return name, _FROGS[name]
+
+
+def list_frogs() -> list[str]:
+    """Return the names of all available frogs."""
+    return list(_FROGS.keys())
+
+
+def print_frog(name: str | None = None) -> None:
+    """Print a frog, random if no name given."""
+    if name is None:
+        chosen_name, art = get_random_frog()
+        print(f"[{chosen_name}]{art}")
+    else:
+        print(f"[{name}]{get_frog(name)}")

light_client-2.0.0/src/light_client/progress.py

@@ -0,0 +1,168 @@
+import sys
+import time
+
+_FROG = "🐸"
+_LILY = "🍃"
+_WATER = "~"
+
+_RIBBITS = [
+    "*ribbit*", "*croak*", "*brrp*", "*gribbit*", "*kerchunk*",
+]
+
+_DONE_MSGS = [
+    "All pads hopped!",
+    "Pond crossed!",
+    "Mission ribbited!",
+    "The frog has landed.",
+    "Leap complete!",
+]
+
+
+class FrogBar:
+    """A frog-themed progress bar. A frog hops across lily pads instead of filling a block bar.
+
+    Usage — as an iterator wrapper::
+
+        for item in FrogBar(my_list, desc="Processing"):
+            process(item)
+
+    Usage — as a context manager with manual updates::
+
+        with FrogBar(total=100, desc="Loading") as bar:
+            for i in range(100):
+                do_work()
+                bar.update(1)
+    """
+
+    def __init__(
+        self,
+        iterable=None,
+        total=None,
+        desc: str = "Hopping",
+        file=None,
+        leave: bool = True,
+        unit: str = "it",
+        bar_width: int = 20,
+    ):
+        self.iterable = iterable
+        if total is not None:
+            self.total = total
+        elif iterable is not None and hasattr(iterable, "__len__"):
+            self.total = len(iterable)
+        else:
+            self.total = None
+
+        self.desc = desc
+        self.bar_width = bar_width
+        self.file = file or sys.stderr
+        self.leave = leave
+        self.unit = unit
+        self.n = 0
+        self.start_time: float | None = None
+        self._rendered_len = 0
+        self._done = False
+        self._ribbit_index = 0
+
+    # ------------------------------------------------------------------
+    # Context manager / iterator protocol
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "FrogBar":
+        self.start_time = time.time()
+        self._render()
+        return self
+
+    def __exit__(self, *_) -> None:
+        self._finish()
+
+    def __iter__(self):
+        self.start_time = time.time()
+        self._render()
+        try:
+            for item in self.iterable:
+                yield item
+                self.update(1)
+        finally:
+            self._finish()
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def update(self, n: int = 1) -> None:
+        """Advance the bar by *n* steps."""
+        self.n += n
+        self._render()
+
+    # ------------------------------------------------------------------
+    # Internal rendering
+    # ------------------------------------------------------------------
+
+    def _finish(self) -> None:
+        if self._done:
+            return
+        self._done = True
+        self.n = self.total if self.total is not None else self.n
+        self._render(final=True)
+        if self.leave:
+            self.file.write("\n")
+            self.file.flush()
+        else:
+            self._clear()
+
+    def _clear(self) -> None:
+        self.file.write(f"\r{' ' * self._rendered_len}\r")
+        self.file.flush()
+
+    def _render(self, final: bool = False) -> None:
+        elapsed = time.time() - (self.start_time or time.time())
+        bar_str = self._build_bar()
+        pct_str = self._pct_str()
+        time_str = _fmt_time(elapsed)
+        count_str = f"{self.n}" + (f"/{self.total}" if self.total is not None else "")
+
+        if final and self.total and self.n >= self.total:
+            import random
+            suffix = f" {random.choice(_DONE_MSGS)}"
+        else:
+            suffix = f" {_RIBBITS[self._ribbit_index % len(_RIBBITS)]}"
+            self._ribbit_index += 1
+
+        line = f"\r{self.desc}: [{bar_str}] {pct_str} {time_str} [{count_str} {self.unit}]{suffix}"
+        self.file.write(line)
+        self.file.flush()
+        # track printable length (strip \r for width calc)
+        self._rendered_len = len(line) - 1
+
+    def _build_bar(self) -> str:
+        w = self.bar_width
+        if self.total and self.total > 0:
+            frac = min(self.n / self.total, 1.0)
+            pos = int(round(frac * (w - 1)))
+        else:
+            # bounce when total is unknown
+            cycle = (self.n % (w * 2)) if self.n else 0
+            pos = cycle if cycle < w else (w * 2 - 1 - cycle)
+
+        # Each cell is one character: lily pad or frog.
+        # Note: emoji are 2 columns wide in most terminals, so the visual
+        # width of the bar is ~2× the logical character count — but it
+        # still hops left to right correctly.
+        cells = [_LILY] * w
+        cells[pos] = _FROG
+        return "".join(cells)
+
+    def _pct_str(self) -> str:
+        if self.total:
+            return f"{min(self.n / self.total, 1.0) * 100:5.1f}%"
+        return "  ?  %"
+
+
+def _fmt_time(seconds: float) -> str:
+    if seconds < 60:
+        return f"{seconds:4.1f}s"
+    m, s = divmod(int(seconds), 60)
+    if m < 60:
+        return f"{m:02d}:{s:02d}"
+    h, m = divmod(m, 60)
+    return f"{h:02d}:{m:02d}:{s:02d}"

light_client-2.0.0/src/light_client/quotes.py

@@ -0,0 +1,35 @@
+import random
+
+_QUOTES = [
+    ("Leap before you look.", "Frog Thoreau"),
+    ("The pond is half full.", "Kermit the Optimist"),
+    ("I think, therefore I ribbit.", "René Desfrogs"),
+    ("To croak or not to croak, that is the question.", "William Shakespduck"),
+    ("The greatest glory in living lies not in never falling, but in hopping back up every time we fall.", "Nelson Froggela"),
+    ("In the middle of every difficulty lies a lily pad.", "Albert Einswamp"),
+    ("It does not matter how slowly you hop, so long as you do not stop.", "Confrocius"),
+    ("Be the frog you wish to see in the pond.", "Mahatma Ribbiti"),
+    ("Tongue out and leap—that is the whole of the frog.", "Swamp Hemingway"),
+    ("The pond you seek is already beneath your webbed feet.", "Zen Bullfrog"),
+    ("Not all those who wander are lost. Some are just looking for flies.", "J.R.R. Toadkien"),
+    ("Ask not what your swamp can do for you; ask what you can do for your swamp.", "John Fitz-Frog Kennedy"),
+    ("Float like a lily, sting like a tongue.", "Muhammud Pond-Ali"),
+    ("Give a frog a fly and you feed him for a day. Teach a frog to catch flies and you feed him for a lifetime.", "Froze Tzu"),
+    ("With great webbed feet comes great leaping ability.", "Uncle Tadpole"),
+]
+
+
+def get_quote(index: int) -> tuple[str, str]:
+    """Return the quote at the given index as (quote, author)."""
+    return _QUOTES[index % len(_QUOTES)]
+
+
+def get_random_quote() -> tuple[str, str]:
+    """Return a random frog quote as (quote, author)."""
+    return random.choice(_QUOTES)
+
+
+def print_quote(index: int | None = None) -> None:
+    """Print a frog quote, random if no index given."""
+    quote, author = get_random_quote() if index is None else get_quote(index)
+    print(f'"{quote}"\n  — {author}')