everbar 0.1.0__py3-none-any.whl

everbar/__init__.py

@@ -0,0 +1,7 @@
+"""everbar — a progress bar that works everywhere."""
+
+from everbar._detect import detect_environment
+from everbar._progress import Progress, set_default_backend
+
+__all__ = ["Progress", "detect_environment", "set_default_backend"]
+__version__ = "0.1.0"

everbar/_backends.py

@@ -0,0 +1,174 @@
+"""Progress backends.
+
+Each backend implements the same minimal surface:
+
+    __enter__ / __exit__   — context-manager use
+    __iter__               — iterator-wrapper use
+    update(n=1)            — manual advance
+
+Backends are constructed lazily by ``Progress``. Optional third-party
+dependencies (``tqdm``, ``marimo``) are imported only inside the backend
+that needs them, so ``everbar`` itself has zero required deps.
+"""
+
+import sys
+import time
+from collections.abc import Iterable, Iterator
+from contextlib import nullcontext
+from typing import Any, Self
+
+
+def _len_or_none(obj: Any) -> int | None:
+    try:
+        return len(obj)
+    except (TypeError, AttributeError):
+        return None
+
+
+class NullBackend(nullcontext):
+    """No-op backend used when ``disable=True``."""
+
+    def __init__(self, iterable: Iterable[Any] | None = None, **_: Any) -> None:
+        super().__init__()
+        self._iterable = iterable
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._iterable or ())
+
+    def update(self, n: int = 1) -> None:  # noqa: ARG002 — protocol shape
+        return None
+
+
+class FallbackBackend:
+    r"""Log-line backend for non-TTY environments.
+
+    Emits one line every ``min_interval`` seconds. Suitable for CI logs,
+    Kubernetes, CloudWatch — anywhere ``\r`` would just produce spam.
+    """
+
+    def __init__(
+        self,
+        iterable: Iterable[Any] | None = None,
+        total: int | None = None,
+        desc: str = "",
+        min_interval: float = 2.0,
+        stream: Any = None,
+        **_: Any,
+    ) -> None:
+        self._iterable = iterable
+        self._total = total if total is not None else _len_or_none(iterable)
+        self._desc = desc
+        self._min_interval = min_interval
+        self._stream = stream if stream is not None else sys.stderr
+        self._n = 0
+        self._t0 = 0.0
+        self._last_log = 0.0
+        self._entered = False
+
+    def __enter__(self) -> Self:
+        self._t0 = time.monotonic()
+        self._last_log = self._t0
+        self._entered = True
+        self._log(final=False)
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self._log(final=True)
+        self._entered = False
+
+    def __iter__(self) -> Iterator[Any]:
+        with self:
+            for item in self._iterable or ():
+                yield item
+                self.update(1)
+
+    def update(self, n: int = 1) -> None:
+        self._n += n
+        now = time.monotonic()
+        if now - self._last_log >= self._min_interval:
+            self._last_log = now
+            self._log(final=False)
+
+    def _log(self, *, final: bool) -> None:
+        elapsed = time.monotonic() - self._t0 if self._t0 else 0.0
+        if self._total:
+            pct = f"{100 * self._n / self._total:.0f}%"
+            total_str = str(self._total)
+        else:
+            pct = "?"
+            total_str = "?"
+        marker = "done" if final else "progress"
+        desc = f" {self._desc}" if self._desc else ""
+        line = (
+            f"[{marker}]{desc} {self._n}/{total_str}"
+            f" ({pct}) elapsed={elapsed:.1f}s"
+        )
+        print(line, file=self._stream, flush=True)
+
+
+class TqdmBackend:
+    """Wraps ``tqdm``.
+
+    Aggregates rather than subclasses so Marimo's function-style monkey-patch
+    of ``tqdm_notebook`` (#4016) can't break us.
+    """
+
+    def __init__(
+        self,
+        iterable: Iterable[Any] | None = None,
+        total: int | None = None,
+        desc: str = "",
+        *,
+        notebook: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        if notebook:
+            from tqdm.notebook import tqdm as _tqdm
+        else:
+            from tqdm import tqdm as _tqdm
+        self._inner = _tqdm(iterable, total=total, desc=desc, **kwargs)
+
+    def __enter__(self) -> Self:
+        self._inner.__enter__()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Any:
+        return self._inner.__exit__(exc_type, exc_val, exc_tb)
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._inner)
+
+    def update(self, n: int = 1) -> None:
+        self._inner.update(n)
+
+
+class MarimoBackend:
+    """Marimo-native bar via ``marimo.status.progress_bar``."""
+
+    def __init__(
+        self,
+        iterable: Iterable[Any] | None = None,
+        total: int | None = None,
+        desc: str = "",
+        **_: Any,
+    ) -> None:
+        import marimo as mo
+
+        self._inner = mo.status.progress_bar(
+            iterable,
+            total=total if total is not None else _len_or_none(iterable),
+            title=desc or None,
+        )
+
+    def __enter__(self) -> Self:
+        self._inner.__enter__()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Any:
+        return self._inner.__exit__(exc_type, exc_val, exc_tb)
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._inner)
+
+    def update(self, n: int = 1) -> None:
+        self._inner.update(n)

everbar/_detect.py

@@ -0,0 +1,80 @@
+"""Runtime environment detection.
+
+Heuristic — the caller can override via the ``backend`` argument on ``Progress``
+or the ``EVERBAR_BACKEND`` environment variable.
+"""
+
+import os
+import sys
+from typing import Literal
+
+Environment = Literal[
+    "marimo",
+    "colab",
+    "kaggle",
+    "vscode_notebook",
+    "jupyter",
+    "jupyter_qt",
+    "spyder",
+    "databricks",
+    "pyodide",
+    "ipython_terminal",
+    "terminal",
+    "non_tty",
+]
+
+
+def detect_environment() -> Environment:
+    """Return a string identifying the runtime environment."""
+    # 1. Marimo — official API
+    try:
+        import marimo  # type: ignore
+
+        if marimo.running_in_notebook():
+            return "marimo"
+    except Exception:
+        pass
+
+    # 2. Pyodide / JupyterLite
+    if "pyodide" in sys.modules or sys.platform == "emscripten":
+        return "pyodide"
+
+    # 3. Databricks
+    if "DATABRICKS_RUNTIME_VERSION" in os.environ:
+        return "databricks"
+
+    # 4. IPython-based environments
+    try:
+        from IPython import get_ipython  # type: ignore
+
+        ip = get_ipython()
+    except Exception:
+        ip = None
+
+    if ip is not None:
+        shell = ip.__class__.__name__
+        mods = sys.modules
+
+        if "google.colab" in mods:
+            return "colab"
+        if "kaggle_secrets" in mods or "KAGGLE_KERNEL_RUN_TYPE" in os.environ:
+            return "kaggle"
+        if "VSCODE_PID" in os.environ or (
+            hasattr(ip, "user_ns") and "__vsc_ipynb_file__" in ip.user_ns
+        ):
+            return "vscode_notebook"
+        if "spyder_kernels" in mods or "SPY_TESTING" in os.environ:
+            return "spyder"
+        if shell == "ZMQInteractiveShell":
+            return "jupyter"
+        if shell == "TerminalInteractiveShell":
+            return "ipython_terminal"
+
+    # 5. Plain Python
+    if sys.stdout is not None and hasattr(sys.stdout, "isatty"):
+        try:
+            if sys.stdout.isatty():
+                return "terminal"
+        except Exception:
+            pass
+    return "non_tty"

everbar/_progress.py

@@ -0,0 +1,98 @@
+"""Public ``Progress`` facade. Picks a backend and delegates."""
+
+import os
+from collections.abc import Iterable, Iterator
+from typing import Any, Self
+
+from everbar._detect import detect_environment
+
+_DEFAULT_BACKEND: str | None = None
+
+_NOTEBOOK_ENVS = {"jupyter", "colab", "kaggle", "vscode_notebook", "databricks"}
+_TQDM_STD_ENVS = {"terminal", "ipython_terminal", "spyder", "jupyter_qt"}
+
+
+def set_default_backend(name: str | None) -> None:
+    """Pin the backend globally. Pass ``None`` to restore auto-detection.
+
+    Valid names: ``"marimo"``, ``"jupyter"``, ``"colab"``, ``"kaggle"``,
+    ``"vscode_notebook"``, ``"jupyter_qt"``, ``"spyder"``, ``"databricks"``,
+    ``"ipython_terminal"``, ``"terminal"``, ``"pyodide"``, ``"non_tty"``.
+    """
+    global _DEFAULT_BACKEND  # noqa: PLW0603 — module-level pin is the API
+    _DEFAULT_BACKEND = name
+
+
+class Progress:
+    """A progress bar that adapts to its environment.
+
+    Iterator form:
+
+        for x in Progress(items, desc="Loading"):
+            work(x)
+
+    Context-manager form:
+
+        with Progress(total=100, desc="Steps") as bar:
+            for _ in range(100):
+                do_step()
+                bar.update(1)
+    """
+
+    def __init__(
+        self,
+        iterable: Iterable[Any] | None = None,
+        total: int | None = None,
+        desc: str = "",
+        backend: str | None = None,
+        *,
+        disable: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        self._iterable = iterable
+        self._total = total
+        self._desc = desc
+        self._kwargs = kwargs
+
+        chosen = (
+            backend or os.environ.get("EVERBAR_BACKEND") or _DEFAULT_BACKEND
+        )
+        self._env: str = chosen or detect_environment()
+        self._impl = self._make_impl(disable=disable)
+
+    def _make_impl(self, *, disable: bool) -> Any:
+        from everbar import _backends
+
+        if disable:
+            return _backends.NullBackend(iterable=self._iterable)
+
+        common = {"total": self._total, "desc": self._desc, **self._kwargs}
+
+        try:
+            if self._env == "marimo":
+                return _backends.MarimoBackend(self._iterable, **common)
+            if self._env in _NOTEBOOK_ENVS:
+                return _backends.TqdmBackend(
+                    self._iterable, notebook=True, **common
+                )
+            if self._env in _TQDM_STD_ENVS:
+                return _backends.TqdmBackend(
+                    self._iterable, notebook=False, **common
+                )
+        except ImportError:
+            pass
+
+        return _backends.FallbackBackend(self._iterable, **common)
+
+    def __iter__(self) -> Iterator[Any]:
+        return iter(self._impl)
+
+    def __enter__(self) -> Self:
+        self._impl.__enter__()
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> Any:
+        return self._impl.__exit__(exc_type, exc_val, exc_tb)
+
+    def update(self, n: int = 1) -> None:
+        self._impl.update(n)

everbar-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: everbar
+Version: 0.1.0
+Summary: A progress bar that works everywhere — terminal, Jupyter, VS Code, Colab, Marimo.
+Project-URL: Homepage, https://github.com/mluttikh/everbar
+Project-URL: Issues, https://github.com/mluttikh/everbar/issues
+License-Expression: MIT
+Keywords: jupyter,marimo,notebook,progress,progressbar,tqdm
+Classifier: Development Status :: 3 - Alpha
+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 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: ipywidgets>=8.0; extra == 'all'
+Requires-Dist: marimo>=0.10; extra == 'all'
+Requires-Dist: rich>=13.0; extra == 'all'
+Requires-Dist: tqdm>=4.65; extra == 'all'
+Provides-Extra: marimo
+Requires-Dist: marimo>=0.10; extra == 'marimo'
+Provides-Extra: notebook
+Requires-Dist: ipywidgets>=8.0; extra == 'notebook'
+Requires-Dist: tqdm>=4.65; extra == 'notebook'
+Provides-Extra: rich
+Requires-Dist: rich>=13.0; extra == 'rich'
+Provides-Extra: tqdm
+Requires-Dist: tqdm>=4.65; extra == 'tqdm'
+Description-Content-Type: text/markdown
+
+# everbar
+
+A progress bar that works **everywhere** — terminal, Jupyter, JupyterLab, VS Code notebooks, Google Colab, Marimo, Pyodide, and CI logs. One API, the right backend per environment.
+
+> Status: 0.1.0 — alpha. API may shift.
+
+## Install
+
+```bash
+pip install everbar             # core only; uses text fallback if nothing else is installed
+pip install "everbar[tqdm]"     # terminal + Jupyter via tqdm
+pip install "everbar[all]"      # everything (tqdm, rich, ipywidgets, marimo)
+```
+
+## Use
+
+```python
+from everbar import Progress
+
+for x in Progress(items, desc="Loading"):
+    work(x)
+
+with Progress(total=100, desc="Steps") as bar:
+    for _ in range(100):
+        do_step()
+        bar.update(1)
+```
+
+## Overrides
+
+```python
+Progress(items, backend="terminal")        # per-call
+```
+
+```bash
+EVERBAR_BACKEND=terminal python script.py  # env var
+```
+
+```python
+import everbar
+everbar.set_default_backend("terminal")    # module-wide
+```
+
+## How it picks a backend
+
+`everbar.detect_environment()` returns one of: `marimo`, `colab`, `kaggle`, `vscode_notebook`, `jupyter`, `jupyter_qt`, `spyder`, `databricks`, `pyodide`, `ipython_terminal`, `terminal`, `non_tty`. Each maps to a backend, with graceful fallback to a log-line text mode when nothing better is available.

everbar-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+everbar/__init__.py,sha256=ohr1mGbK02QG2Jnfwv2vJVEuGuTf9RGQw8fenN4Q_Iw,255
+everbar/_backends.py,sha256=8fOuAfVtd2qSfMEy3G4dktr1AwgDwT-fIi8SNacw_qc,5025
+everbar/_detect.py,sha256=qHqnDmmD6Y7gxwGmFx9zyWSiPi-K2Pmb9cs4WO_kWwM,2041
+everbar/_progress.py,sha256=H5wsugx7lbZhXGQljAETu01rCApZbWkjFr6nMlQRlBQ,2986
+everbar-0.1.0.dist-info/METADATA,sha256=AUQBbVkDSTUgdIF0hX5tyRM9N-yzvAZ5jk8uQHV4QYs,2795
+everbar-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+everbar-0.1.0.dist-info/RECORD,,

everbar-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any