everbar 0.1.0__tar.gz

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

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # setup-uv doesn't publish a floating major tag — must pin to a
+      # specific version. Bump as new patches/minors land.
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.13"
+          enable-cache: true
+
+      - name: Sync dev environment
+        run: uv sync --all-extras --group dev
+
+      - name: ruff check
+        run: uv run ruff check .
+
+      - name: ruff format --check
+        run: uv run ruff format --check .
+
+  test:
+    name: Test (Python ${{ matrix.python-version }} on ${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Sync environment
+        run: uv sync --all-extras --group dev
+
+      - name: Run tests
+        run: uv run pytest -v

everbar-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,35 @@
+name: release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write   # required to create the GitHub Release
+  id-token: write   # required for PyPI trusted publishing (OIDC)
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment: pypi  # gates the job behind manual approval
+    steps:
+      - uses: actions/checkout@v5
+
+      # setup-uv doesn't publish a floating major tag — must pin to a
+      # specific version. Bump as new patches/minors land.
+      - uses: astral-sh/setup-uv@v8.1.0
+        with:
+          python-version: "3.13"
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing automatic
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

everbar-0.1.0/.gitignore

@@ -0,0 +1,124 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django / Flask stuff (kept for completeness)
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+instance/
+.webassets-cache
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv / poetry / pdm / uv lockfile preferences left to project
+Pipfile.lock
+poetry.lock
+pdm.lock
+.pdm.toml
+.pdm-python
+.pdm-build/
+uv.lock
+
+# PEP 582
+__pypackages__/
+
+# Environments
+.env
+.env.*
+!.env.example
+.venv
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy / pyright / ruff caches
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ruff_cache/
+
+# Cython debug symbols
+cython_debug/
+
+# IDEs / editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Marimo
+__marimo__/

everbar-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,46 @@
+# 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/pyproject.toml

@@ -0,0 +1,125 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "everbar"
+version = "0.1.0"
+description = "A progress bar that works everywhere — terminal, Jupyter, VS Code, Colab, Marimo."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["progress", "progressbar", "tqdm", "jupyter", "marimo", "notebook"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: Terminals",
+]
+dependencies = []
+
+[project.optional-dependencies]
+tqdm = ["tqdm>=4.65"]
+rich = ["rich>=13.0"]
+notebook = ["ipywidgets>=8.0", "tqdm>=4.65"]
+marimo = ["marimo>=0.10"]
+all = ["tqdm>=4.65", "rich>=13.0", "ipywidgets>=8.0", "marimo>=0.10"]
+
+[dependency-groups]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.6",
+    "tqdm>=4.65",
+    "rich>=13.0",
+    "ipywidgets>=8.0",
+    "marimo>=0.10",
+]
+
+[project.urls]
+Homepage = "https://github.com/mluttikh/everbar"
+Issues = "https://github.com/mluttikh/everbar/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/everbar"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 80
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+[tool.ruff.lint]
+select = [
+    "E",     # pycodestyle errors
+    "W",     # pycodestyle warnings
+    "F",     # pyflakes
+    "I",     # isort
+    "N",     # pep8-naming
+    "D",     # pydocstyle (google style — see [lint.pydocstyle] below)
+    "UP",    # pyupgrade
+    "B",     # flake8-bugbear
+    "A",     # flake8-builtins (don't shadow builtins)
+    "ANN",   # flake8-annotations (require type hints)
+    "ARG",   # flake8-unused-arguments
+    "C4",    # flake8-comprehensions
+    "EM",    # flake8-errmsg (extract msgs before raise)
+    "FBT",   # flake8-boolean-trap (bool params should be kw-only)
+    "INP",   # flake8-no-pep420 (require __init__.py)
+    "ISC",   # flake8-implicit-str-concat
+    "LOG",   # flake8-logging
+    "PIE",   # flake8-pie
+    "PT",    # flake8-pytest-style
+    "RET",   # flake8-return
+    "SIM",   # flake8-simplify
+    "SLF",   # flake8-self (don't access private from outside)
+    "T20",   # flake8-print (no stray print())
+    "TC",    # flake8-type-checking
+    "TRY",   # tryceratops (exception handling)
+    "PERF",  # perflint
+    "FURB",  # refurb (modernization)
+    "PL",    # pylint subset (E/W/R/C)
+    "ERA",   # eradicate (commented-out code)
+    "RUF",   # ruff-specific (includes RUF100: flag unused noqa directives)
+]
+ignore = [
+    "TRY003",  # raise long-message — fine for small exceptions here
+    "EM101",   # raw-string in exception is OK for tiny one-offs
+    "EM102",   # f-string in exception is OK
+    "ISC001",  # conflicts with the formatter
+    "D203",    # one-blank-line-before-class (conflicts with D211)
+    "D213",    # multi-line-summary-second-line (conflicts with D212)
+    "ANN401",  # `Any` is permitted (used for **kwargs, __exit__, opaque inner)
+    "PLC0415", # imports inside functions — intentional for lazy soft-deps
+    "PLR0911", # too-many-return-statements — fine for dispatch funcs
+    "PLR0912", # too-many-branches — same
+    "PLR0913", # too-many-arguments — Progress legitimately has several
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "E501",    # long lines OK
+    "D",       # tests don't need docstrings
+    "S101",    # asserts are the point
+    "SLF001",  # accessing _private members in tests is fine
+    "PT011",   # broad pytest.raises is fine
+    "PLR2004", # magic numbers in assertions are fine
+    "ARG",     # pytest fixtures may pass unused args
+    "ANN",     # tests don't need full type annotations
+]

everbar-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_detect.py

@@ -0,0 +1,27 @@
+"""Smoke tests for detect_environment()."""
+
+from everbar import detect_environment
+
+VALID = {
+    "marimo",
+    "colab",
+    "kaggle",
+    "vscode_notebook",
+    "jupyter",
+    "jupyter_qt",
+    "spyder",
+    "databricks",
+    "pyodide",
+    "ipython_terminal",
+    "terminal",
+    "non_tty",
+}
+
+
+def test_returns_known_environment():
+    env = detect_environment()
+    assert env in VALID
+
+
+def test_idempotent():
+    assert detect_environment() == detect_environment()

everbar-0.1.0/tests/test_progress.py

@@ -0,0 +1,61 @@
+"""End-to-end tests for the Progress facade.
+
+We force ``backend="non_tty"`` so tests don't depend on tqdm/marimo and don't
+spam the terminal during CI.
+"""
+
+import io
+
+from everbar import Progress, set_default_backend
+from everbar._backends import FallbackBackend, NullBackend
+
+
+def test_iterator_form_yields_all_items():
+    items = [1, 2, 3, 4, 5]
+    out = list(Progress(items, backend="non_tty"))
+    assert out == items
+
+
+def test_context_manager_updates():
+    with Progress(total=10, backend="non_tty") as bar:
+        for _ in range(10):
+            bar.update(1)
+    assert bar._impl._n == 10  # type: ignore[attr-defined]
+
+
+def test_disable_uses_null_backend():
+    p = Progress([1, 2, 3], disable=True)
+    assert isinstance(p._impl, NullBackend)
+    assert list(p) == [1, 2, 3]
+
+
+def test_explicit_backend_overrides_detection():
+    p = Progress([1, 2, 3], backend="non_tty")
+    assert isinstance(p._impl, FallbackBackend)
+
+
+def test_env_var_overrides(monkeypatch):
+    monkeypatch.setenv("EVERBAR_BACKEND", "non_tty")
+    p = Progress([1, 2, 3])
+    assert isinstance(p._impl, FallbackBackend)
+
+
+def test_set_default_backend(monkeypatch):
+    monkeypatch.delenv("EVERBAR_BACKEND", raising=False)
+    set_default_backend("non_tty")
+    try:
+        p = Progress([1, 2, 3])
+        assert isinstance(p._impl, FallbackBackend)
+    finally:
+        set_default_backend(None)
+
+
+def test_fallback_writes_lines(monkeypatch):
+    buf = io.StringIO()
+    bar = FallbackBackend(total=3, desc="x", min_interval=0.0, stream=buf)
+    with bar:
+        for _ in range(3):
+            bar.update(1)
+    output = buf.getvalue()
+    assert "[progress]" in output or "[done]" in output
+    assert "x" in output