real-browser-cli 0.14.2__py3-none-any.whl

browser_cli/sdk/dom.py

@@ -0,0 +1,169 @@
+"""DOM, content-extraction, and page-info namespaces: ``b.dom.*``, ``b.extract.*``, ``b.page.*``."""
+from __future__ import annotations
+
+from browser_cli.sdk.base import Namespace, sdk_command
+
+def _selector_args(self, selector):
+  return {"selector": selector}
+
+def _selector_value_args(self, selector, value):
+  return {"selector": selector, "value": value}
+
+def _extract_markdown(self, result, *args, **kwargs) -> str:
+  from browser_cli.markdown import render_markdown
+
+  return render_markdown(result)
+
+class DomNS(Namespace):
+  """Query and drive page elements in the active (or specified) tab."""
+
+  @sdk_command("dom.query", _selector_args, default=[])
+  def query(self, selector: str) -> list[dict]:
+    """Return elements matching a CSS selector."""
+
+  @sdk_command("dom.click", _selector_args, return_result=False)
+  def click(self, selector: str) -> None:
+    """Click the first element matching a CSS selector."""
+
+  @sdk_command("dom.type", lambda self, selector, text: {"selector": selector, "text": text}, return_result=False)
+  def type(self, selector: str, text: str) -> None:
+    """Type text into the first matching element."""
+
+  @sdk_command("dom.attr", lambda self, selector, attr: {"selector": selector, "attr": attr}, default=[])
+  def attr(self, selector: str, attr: str) -> list[str]:
+    """Return an attribute from all matching elements."""
+
+  @sdk_command("dom.text", _selector_args, default=[])
+  def text(self, selector: str) -> list[str]:
+    """Return text from all matching elements."""
+
+  @sdk_command("dom.exists", _selector_args, default=False)
+  def exists(self, selector: str) -> bool:
+    """Return whether a selector exists."""
+
+  @sdk_command("dom.scroll", lambda self, selector=None, *, x=None, y=None: {"selector": selector, "x": x, "y": y}, return_result=False)
+  def scroll(self, selector: str | None = None, *, x: int | None = None, y: int | None = None) -> None:
+    """Scroll to a CSS selector or to pixel coordinates."""
+
+  @sdk_command("dom.select", _selector_value_args, return_result=False)
+  def select(self, selector: str, value: str) -> None:
+    """Set the value of a <select> element."""
+
+  @sdk_command("dom.eval", lambda self, code, tab_id=None: {"code": code, "tabId": tab_id})
+  def eval(self, code: str, tab_id: int | None = None):
+    """Evaluate JavaScript in the page's main world and return the result."""
+
+  @sdk_command("dom.key", lambda self, key, selector=None: {"key": key, "selector": selector}, return_result=False)
+  def key(self, key: str, selector: str | None = None) -> None:
+    """Dispatch a keyboard event. key examples: 'Enter', 'Tab', 'Escape', 'ArrowDown'."""
+
+  @sdk_command("dom.hover", _selector_args, return_result=False)
+  def hover(self, selector: str) -> None:
+    """Dispatch mouseover/mouseenter on an element."""
+
+  @sdk_command("dom.check", _selector_args, return_result=False)
+  def check(self, selector: str) -> None:
+    """Check a checkbox."""
+
+  @sdk_command("dom.uncheck", _selector_args, return_result=False)
+  def uncheck(self, selector: str) -> None:
+    """Uncheck a checkbox."""
+
+  @sdk_command("dom.clear", _selector_args, return_result=False)
+  def clear(self, selector: str) -> None:
+    """Clear the value of an input element."""
+
+  @sdk_command("dom.focus", _selector_args, return_result=False)
+  def focus(self, selector: str) -> None:
+    """Focus an element."""
+
+  @sdk_command("dom.submit", _selector_args, return_result=False)
+  def submit(self, selector: str) -> None:
+    """Submit the form containing the matched element."""
+
+  def poll(
+    self,
+    selector: str,
+    pattern: str,
+    *,
+    attr: str | None = None,
+    timeout: float = 30.0,
+    interval: float = 0.5,
+    tab_id: int | None = None,
+  ) -> dict:
+    """Poll selector's text/value until it matches regex pattern.
+
+    Returns ``{"selector": ..., "value": ..., "pattern": ...}`` when matched.
+    """
+    return self.command("dom.poll", {
+      "selector": selector,
+      "pattern": pattern,
+      "attr": attr,
+      "timeout": int(timeout * 1000),
+      "interval": int(interval * 1000),
+      "tabId": tab_id,
+    })
+
+  def wait_for(
+    self,
+    selector: str,
+    *,
+    timeout: float = 10.0,
+    visible: bool = False,
+    hidden: bool = False,
+    tab_id: int | None = None,
+  ) -> dict:
+    """Wait until a CSS selector appears (or disappears) in the DOM.
+
+    Args:
+      selector: CSS selector to watch.
+      timeout: Max seconds to wait before raising ``RuntimeError``.
+      visible: Wait until the element has non-zero dimensions.
+      hidden: Wait until the element is absent or has ``offsetParent == null``.
+      tab_id: Tab to watch. Defaults to the active tab.
+    """
+    return self.command("dom.wait_for", {
+      "selector": selector,
+      "timeout": int(timeout * 1000),
+      "visible": visible,
+      "hidden": hidden,
+      "tabId": tab_id,
+    })
+
+class ExtractNS(Namespace):
+  """Extract structured content from the active tab."""
+
+  @sdk_command("extract.links", default=[])
+  def links(self) -> list[dict]:
+    """Return links from the active tab."""
+
+  @sdk_command("extract.images", default=[])
+  def images(self) -> list[dict]:
+    """Return images from the active tab."""
+
+  @sdk_command("extract.text", default="")
+  def text(self) -> str:
+    """Return plain text from the active tab."""
+
+  @sdk_command("extract.json", lambda self, selector: {"selector": selector})
+  def json(self, selector: str):
+    """Extract JSON-like structured data from a selector."""
+
+  @sdk_command("extract.html", default="")
+  def html(self) -> str:
+    """Return the full HTML source of the active tab."""
+
+  @sdk_command("extract.markdown", lambda self, selector=None: {"selector": selector}, mapper=_extract_markdown)
+  def markdown(self, selector: str | None = None) -> str:
+    """Extract the page's main content as clean Markdown.
+
+    The extractor may return either Markdown or raw HTML; both are
+    normalized to Markdown here so SDK and CLI callers get identical output.
+    """
+
+class PageNS(Namespace):
+  """Inspect the active page."""
+
+  @sdk_command("page.info", default={})
+  def info(self) -> dict:
+    """Return title, URL, readyState, lang, and meta tags of the active tab."""

browser_cli/sdk/extension.py

@@ -0,0 +1,24 @@
+"""Extension-control namespace: ``b.extension.*``."""
+from __future__ import annotations
+
+from browser_cli.sdk.base import Namespace, sdk_command
+
+class ExtensionNS(Namespace):
+  """Control the browser-cli extension itself."""
+
+  @sdk_command("extension.info", default={})
+  def info(self) -> dict:
+    """Return extension version, runtime metadata, and capabilities."""
+
+  @sdk_command("extension.capabilities", default=[])
+  def capabilities(self) -> list[str]:
+    """Return feature capability strings advertised by the extension."""
+
+  @sdk_command("extension.reload")
+  def reload(self) -> None:
+    """Reload the browser-cli extension service worker.
+
+    Schedules a ``chrome.runtime.reload()`` inside the extension and returns
+    immediately. The extension restarts ~200 ms later and reconnects via the
+    keepalive alarm within ~25 seconds.
+    """

browser_cli/sdk/factories.py

@@ -0,0 +1,103 @@
+"""Object-factory mixin for :class:`~browser_cli.BrowserCLI`.
+
+Builds the typed :class:`~browser_cli.models.Tab` / :class:`~browser_cli.models.Group`
+dataclasses from raw command responses and binds each one to the client that
+should run its actions. In multi-browser mode an object is bound to a sibling
+client targeting the browser it came from, so ``tab.close()`` routes correctly.
+"""
+from __future__ import annotations
+
+from typing import Any, Protocol, cast
+
+from browser_cli.models import Group, Tab
+
+class _FactoryClient(Protocol):
+    _key: str | None
+
+class FactoryMixin:
+    """Turn raw response dicts into bound ``Tab``/``Group`` objects.
+
+    Mixed into :class:`~browser_cli.BrowserCLI`; relies on the client providing
+    ``_browser``/``_remote``/``_key`` and being constructible via ``type(self)``.
+    """
+
+    def tab_from(
+        self,
+        data: dict,
+        *,
+        browser_profile: str | None = None,
+        browser_name: str | None = None,
+        browser_remote: str | None = None,
+    ) -> Tab:
+        tab = Tab(
+            id=data["id"],
+            window_id=data.get("windowId", 0),
+            active=data.get("active", False),
+            muted=data.get("muted", False),
+            title=data.get("title") or "",
+            url=data.get("url") or "",
+            group_id=data.get("groupId") or None,
+            browser=browser_name,
+        )
+        client = cast(_FactoryClient, self)
+        tab._browser = self if browser_profile is None else cast(Any, type(self))(
+            browser=browser_profile,
+            remote=browser_remote,
+            key=client._key,
+            _command_sender=getattr(self, "_command_sender", None),
+        )
+        return tab
+
+    def require_tab_response(self, data, error: str) -> Tab:
+        """Build a bound Tab from a tab-shaped response, or raise ``RuntimeError(error)``."""
+        if not isinstance(data, dict) or "id" not in data:
+            raise RuntimeError(error)
+        return self.tab_from(data)
+
+    def group_from(
+        self,
+        data: dict,
+        *,
+        browser_profile: str | None = None,
+        browser_name: str | None = None,
+        browser_remote: str | None = None,
+    ) -> Group:
+        group = Group(
+            id=data["id"],
+            title=data.get("title") or "",
+            color=data.get("color") or "",
+            collapsed=data.get("collapsed", False),
+            tab_count=data.get("tabCount", 0),
+            browser=browser_name,
+        )
+        client = cast(_FactoryClient, self)
+        group._browser = self if browser_profile is None else cast(Any, type(self))(
+            browser=browser_profile,
+            remote=browser_remote,
+            key=client._key,
+            _command_sender=getattr(self, "_command_sender", None),
+        )
+        return group
+
+    def tab_from_target(self, data: dict, target) -> Tab:
+        """Build a Tab, tagging it with *target* in multi-browser mode (``None`` = local)."""
+        return self.tab_from(
+            data,
+            browser_profile=target.profile if target else None,
+            browser_name=target.display_name if target else None,
+            browser_remote=target.remote if target else None,
+        )
+
+    def group_from_target(self, data: dict, target) -> Group:
+        """Build a Group, tagging it with *target* in multi-browser mode (``None`` = local)."""
+        return self.group_from(
+            data,
+            browser_profile=target.profile if target else None,
+            browser_name=target.display_name if target else None,
+            browser_remote=target.remote if target else None,
+        )
+
+    @staticmethod
+    def tag_browser(item: dict, target) -> dict:
+        """Return *item* as-is locally, or with a ``browser`` key in multi-browser mode."""
+        return item if target is None else {**item, "browser": target.display_name}

browser_cli/sdk/groups.py

@@ -0,0 +1,51 @@
+"""Tab groups namespace: ``b.groups.*``."""
+from __future__ import annotations
+
+from browser_cli.models import BrowserCounts, Group, Tab
+from browser_cli.sdk.base import Namespace
+
+class GroupsNS(Namespace):
+  """List, create, query, and modify tab groups."""
+
+  def list(self) -> list[Group]:
+    """Return all tab groups.
+
+    When multiple browsers are active and no browser was specified, each Group
+    includes ``group.browser`` naming its source browser.
+    """
+    return self.multi_list("group.list", {}, self.group_from_target)
+
+  def count(self) -> "int | BrowserCounts":
+    """Return the number of tab groups.
+
+    Returns ``BrowserCounts`` in implicit multi-browser mode.
+    """
+    return self.multi_count("group.count", {})
+
+  def query(self, search: str) -> list[Group]:
+    """Search groups by name."""
+    return [self.group_from(g) for g in (self.command("group.query", {"search": search}) or [])]
+
+  def create(self, name: str) -> Group:
+    """Create a new tab group with *name*. Returns the created Group."""
+    data = self.command("group.open", {"name": name})
+    if isinstance(data, dict):
+      return self.group_from(data)
+    return Group(id=data, title=name, color="", collapsed=False, tab_count=0)
+
+  def tabs(self, group_id: int) -> list[Tab]:
+    """Return all tabs inside a group."""
+    return [self.tab_from(t) for t in (self.command("group.tabs", {"groupId": group_id}) or [])]
+
+  def add_tab(self, group: str | int, url: str | None = None) -> int | None:
+    """Open a new tab (optionally at URL) inside a group. Returns the new tab ID."""
+    result = self.command("group.add_tab", {"group": str(group), "url": url})
+    return self.field(result, "tabId", fallback=result)
+
+  def move(self, group: str | int, *, forward: bool = False, backward: bool = False) -> dict | None:
+    """Move a tab group forward or backward. Returns the raw move result."""
+    return self.command("group.move", {"group": str(group), "forward": forward, "backward": backward})
+
+  def close(self, group_id: int, *, gentle_mode: str = "auto") -> None:
+    """Ungroup (and close) a tab group by ID."""
+    self.command("group.close", {"groupId": group_id, "gentleMode": gentle_mode})

browser_cli/sdk/navigation.py

@@ -0,0 +1,122 @@
+"""Navigation namespace: ``b.nav.*``."""
+from __future__ import annotations
+
+from browser_cli.models import Tab
+from browser_cli.sdk.base import Namespace, sdk_command
+
+def _open_args(self, url, *, background=False, focus=False, window=None, group=None, **_ignored):
+  return {"url": url, "background": background or not focus, "focus": focus, "window": window, "group": group}
+
+def _tab_args(self, tab_id=None):
+  return {"tabId": tab_id}
+
+class NavigationNS(Namespace):
+  """Open URLs, navigate history, and focus tabs."""
+
+  def open(
+    self,
+    url: str,
+    *,
+    background: bool = False,
+    focus: bool = False,
+    window: str | None = None,
+    group: str | None = None,
+    reuse: bool = False,
+    reuse_domain: bool = False,
+    reuse_title: str | None = None,
+  ) -> None:
+    """Open *url* in a new tab without stealing OS focus by default.
+
+    ``reuse``/``reuse_domain``/``reuse_title`` navigate an existing matching tab
+    instead of creating a new one.
+    """
+    tab = self._reuse_target(url, reuse=reuse, reuse_domain=reuse_domain, reuse_title=reuse_title)
+    if tab is not None:
+      self.to(tab.id, url)
+      if focus:
+        self._c.tabs.activate(tab.id)
+      return None
+    self.command("navigate.open", _open_args(self, url, background=background, focus=focus, window=window, group=group))
+    return None
+
+  def open_wait(
+    self,
+    url: str,
+    *,
+    timeout: float = 30.0,
+    background: bool = False,
+    focus: bool = False,
+    window: str | None = None,
+    group: str | None = None,
+    reuse: bool = False,
+    reuse_domain: bool = False,
+    reuse_title: str | None = None,
+  ) -> Tab:
+    """Open *url* in a new tab and block until fully loaded. Returns the Tab."""
+    tab = self._reuse_target(url, reuse=reuse, reuse_domain=reuse_domain, reuse_title=reuse_title)
+    if tab is not None:
+      self.to(tab.id, url)
+      if focus:
+        self._c.tabs.activate(tab.id)
+      return self._c.tabs.wait_for_load(tab.id, timeout=timeout)
+    return self.require_tab(
+      self.command("navigate.open_wait", {
+        "url": url, "timeout": int(timeout * 1000),
+        "background": background or not focus, "focus": focus, "window": window, "group": group,
+      }),
+      "navigate.open_wait returned unexpected data",
+    )
+
+  @sdk_command("navigate.reload", _tab_args)
+  def reload(self, tab_id: int | None = None) -> None:
+    """Reload the active tab or a specific tab."""
+
+  @sdk_command("navigate.hard_reload", _tab_args)
+  def hard_reload(self, tab_id: int | None = None) -> None:
+    """Hard-reload the active tab or a specific tab."""
+
+  @sdk_command("navigate.back", _tab_args)
+  def back(self, tab_id: int | None = None) -> None:
+    """Navigate back in the active tab or a specific tab."""
+
+  @sdk_command("navigate.forward", _tab_args)
+  def forward(self, tab_id: int | None = None) -> None:
+    """Navigate forward in the active tab or a specific tab."""
+
+  @sdk_command("navigate.focus", lambda self, pattern: {"pattern": pattern})
+  def focus(self, pattern: str) -> dict | None:
+    """Focus the first tab whose URL matches *pattern*. Returns the matched tab info, if any."""
+
+  @sdk_command("navigate.to", lambda self, tab_id, url: {"tabId": tab_id, "url": url})
+  def to(self, tab_id: int, url: str) -> None:
+    """Navigate a specific tab to *url* in place."""
+
+  def _reuse_target(self, url: str, *, reuse: bool, reuse_domain: bool, reuse_title: str | None):
+    if not (reuse or reuse_domain or reuse_title):
+      return None
+    from urllib.parse import urlparse
+    wanted = urlparse(url)
+    wanted_host = wanted.netloc.lower()
+    for tab in self._c.tabs.list():
+      tab_url = tab.url or ""
+      parsed = urlparse(tab_url)
+      if reuse and tab_url == url:
+        return tab
+      if reuse_domain and wanted_host and parsed.netloc.lower() == wanted_host:
+        return tab
+      if reuse_title and reuse_title.lower() in (tab.title or "").lower():
+        return tab
+    return None
+
+  def search(
+    self, engine: str, query: str, *,
+    background: bool = False, focus: bool = False, window: str | None = None, group: str | None = None,
+  ) -> None:
+    """Open a search query in the given engine (e.g. 'google', 'youtube', 'ddg')."""
+    from urllib.parse import quote_plus
+    from browser_cli.commands.search import ENGINES
+    template = ENGINES.get(engine)
+    if template is None:
+      raise ValueError(f"Unknown search engine '{engine}'. Available: {', '.join(ENGINES)}")
+    url = template.format(query=quote_plus(query))
+    self.command("navigate.open", {"url": url, "background": background or not focus, "focus": focus, "window": window, "group": group})

browser_cli/sdk/perf.py

@@ -0,0 +1,23 @@
+"""Performance and background-jobs namespace: ``b.perf.*``."""
+from __future__ import annotations
+
+from browser_cli.sdk.base import Namespace, sdk_command
+
+class PerfNS(Namespace):
+  """Inspect the performance profile and manage background jobs."""
+
+  @sdk_command("perf.status", default={})
+  def status(self) -> dict:
+    """Return current performance profile, throttle info, and running jobs."""
+
+  @sdk_command("perf.set_profile", lambda self, profile: {"profile": profile}, default={})
+  def set_profile(self, profile: str) -> dict:
+    """Set the global extension performance profile."""
+
+  @sdk_command("jobs.status", lambda self, job_id: {"jobId": job_id}, default={})
+  def job_status(self, job_id: str) -> dict:
+    """Return status/progress for a background job."""
+
+  @sdk_command("jobs.cancel", lambda self, job_id: {"jobId": job_id}, default={})
+  def job_cancel(self, job_id: str) -> dict:
+    """Request cancellation for a background job."""

browser_cli/sdk/routing.py

@@ -0,0 +1,149 @@
+"""Multi-browser routing mixin for :class:`~browser_cli.BrowserCLI`.
+
+When no specific browser is selected and more than one browser (local or
+remote) is active, list/count commands fan out to every target and aggregate
+the results. This mixin holds that fan-out machinery plus a few small response
+helpers; single-browser mode falls straight through to ``_cmd``.
+"""
+from __future__ import annotations
+
+import importlib
+import sys
+from collections.abc import Callable, Iterable
+from typing import TYPE_CHECKING, Protocol, cast
+
+from browser_cli.client import BrowserTarget
+from browser_cli.errors import BrowserNotConnected
+from browser_cli.models import BrowserCounts, Tab
+
+if TYPE_CHECKING:
+  from browser_cli.sdk.tabs import TabsNS
+
+class _RoutingClient(Protocol):
+  _browser: str | None
+  _remote: str | None
+  _key: str | None
+  tabs: "TabsNS"
+
+  def dispatch(self, command: str, args: dict | None = None): ...
+
+# send_command / active_browser_targets / remote_browser_targets are resolved
+# through the ``browser_cli`` package namespace at call time, not bound here at
+# import, so tests patching ``browser_cli.send_command`` still take effect —
+# without a module-level import cycle back into browser_cli.__init__.
+
+_UNSET = object()
+
+def _browser_cli_package():
+  return sys.modules.get("browser_cli") or importlib.import_module("browser_cli")
+
+class RoutingMixin:
+  """Fan-out + aggregation across active browsers, mixed into ``BrowserCLI``.
+
+  Relies on the client exposing ``_browser``/``_remote``/``_key``, ``_cmd``,
+  and a ``tabs`` namespace.
+  """
+
+  @property
+  def _client(self) -> _RoutingClient:
+    return cast(_RoutingClient, cast(object, self))
+
+  def _multi_browser_targets(self) -> list[BrowserTarget]:
+    client = self._client
+    package = _browser_cli_package()
+    if client._browser is not None:
+      return []
+    if client._remote:
+      targets = package.remote_browser_targets(client._remote, key=client._key)
+    else:
+      targets = package.active_browser_targets()
+    if len(targets) <= 1 and not any(target.remote for target in targets):
+      return []
+    return targets
+
+  def _collect_multi_browser(self, command: str, args: dict | None = None):
+    results = []
+    targets = self._multi_browser_targets()
+    for target in targets:
+      try:
+        if target.remote:
+          data = _browser_cli_package().send_command(
+            command, args, profile=target.profile, remote=target.remote, key=self._client._key
+          )
+        else:
+          data = _browser_cli_package().send_command(command, args, profile=target.profile)
+      except (BrowserNotConnected, RuntimeError):
+        continue
+      results.append((target, data))
+    if results:
+      return results
+    if targets:
+      raise BrowserNotConnected(
+        "Cannot resolve a browser socket automatically.\n"
+        "Make sure the browser is running with the browser-cli extension enabled,\n"
+        "or pass --browser <alias> / set BROWSER_CLI_PROFILE to a known alias."
+      )
+    return []
+
+  @staticmethod
+  def _field(result, key, default=None, *, fallback=_UNSET):
+    """Pull *key* out of a dict response, with a non-dict fallback.
+
+    Returns ``result[key]`` (or *default*) when *result* is a dict. When it
+    is not a dict, returns *fallback* if given, else *default*.
+    """
+    if isinstance(result, dict):
+      return result.get(key, default)
+    return default if fallback is _UNSET else fallback
+
+  def toggle_tab(self, command: str, tab_id: int | None) -> int:
+    """Run a tab toggle command (mute/pin/...) and return the target tab ID."""
+    result = self._client.dispatch(command, {"tabId": tab_id})
+    return self._field(result, "tabId", tab_id, fallback=int(tab_id or 0))
+
+  def multi_count(self, command: str, args: dict | None = None) -> "int | BrowserCounts":
+    """Count command that aggregates into :class:`BrowserCounts` in multi-browser mode."""
+    multi_results = self._collect_multi_browser(command, args or {})
+    if not multi_results:
+      return self._client.dispatch(command, args or {})
+    by_browser = {target.display_name: int(count or 0) for target, count in multi_results}
+    return BrowserCounts(total=sum(by_browser.values()), by_browser=by_browser)
+
+  def multi_list(self, command: str, args: dict | None, mapper):
+    """List command, flattening per-browser results in multi-browser mode.
+
+    *mapper* is ``(item, target) -> mapped`` where ``target`` is the source
+    :class:`BrowserTarget` in multi mode, or ``None`` in single-browser mode.
+    """
+    multi_results = self._collect_multi_browser(command, args or {})
+    if multi_results:
+      return [
+        mapper(item, target)
+        for target, items in multi_results
+        for item in (items or [])
+      ]
+    return [mapper(item, None) for item in (self._client.dispatch(command, args or {}) or [])]
+
+  def apply_tab_filter(self, filter_fn: Callable[[Tab], bool] | Callable[[list[Tab]], Iterable[Tab]]) -> list[Tab]:
+    tabs = self._client.tabs.list()
+
+    try:
+      transformed = filter_fn(tabs)
+    except (AttributeError, TypeError):
+      return [tab for tab in tabs if filter_fn(tab)]
+
+    if isinstance(transformed, list):
+      return transformed
+    if isinstance(transformed, tuple):
+      return list(transformed)
+    if isinstance(transformed, set):
+      return list(transformed)
+    if transformed is tabs:
+      return tabs
+    if isinstance(transformed, bool):
+      return [tab for tab in tabs if filter_fn(tab)]
+
+    try:
+      return list(transformed)
+    except TypeError:
+      return [tab for tab in tabs if filter_fn(tab)]