requake 0.8.2__tar.gz → 0.8.4__tar.gz

{requake-0.8.2 → requake-0.8.4}/CHANGELOG.md

@@ -2,6 +2,86 @@
 
 Copyright (c) 2021-2026 Claudio Satriano <satriano@ipgp.fr>
 
+## [0.8.4] - 2026-10-23
+
+- ``plot_families``: new ``--mode`` option, to draw the families as a
+  heatmap (``--mode heatmap``): one row per event, with the trace
+  amplitudes encoded in color and the family average drawn as a wiggle
+  below. The default remains the wiggle plot (``--mode wiggle``).
+- ``plot_families``: the family average is now drawn in its own panel
+  also in ``--mode wiggle``, and both modes show an extra panel below
+  it, where all the traces of the family are drawn stacked on top of
+  each other, with the average highlighted on top, so that the waveform
+  similarity can be judged at a glance.
+- ``plot_families``: new ``--max-labels`` option (default 15), to set
+  the maximum number of traces carrying a label. When a family has more
+  traces than that, only a subset of them is labeled (in wiggle mode,
+  the labeled traces are also highlighted and the traces are scaled up),
+  so that large families remain readable. Use 0 to label every trace.
+- New ``-E``/``--events`` option for ``print_families``, to print one
+  row per event (ordered by family number and origin time), instead of
+  one row per family; combine with ``-f csv`` to export the list.
+- New ``dedup_events`` command: flags likely duplicate events (event
+  pairs with high cross-correlation, close in time and space) with the
+  new ``duplicate`` column in the catalog, and marks all the pairs
+  involving them as invalid (new ``invalid`` column in ``event_pairs``);
+  ``build_families`` ignores the invalid pairs. A compact report is
+  printed at the end (``-n``/``--dry-run`` only prints it) and
+  ``--reset`` clears the flags.
+- ``print_pairs`` hides the invalid pairs by default; the new
+  ``--include-invalid`` option lists them as well.
+- Long operations now show a progress indicator, and long database
+  queries can be interrupted with ``Ctrl+C`` (pressed twice): the
+  database is closed cleanly (no stray ``-wal``/``-shm`` files) and the
+  abort is no longer reported as a bug.
+- Fixed the non-paged table output (``--no-pager``), which dropped all
+  the rows but the last batch.
+- Stylized ``◀◀ RƎQuake`` logo, shown in the command line help.
+- Colored terminal output for help and usage messages, log messages,
+  errors, table headers and waveform-cache diagnostics. Colors are used
+  only on interactive terminals, and are therefore automatically removed
+  when the output is piped or redirected. The ``NO_COLOR`` and
+  ``FORCE_COLOR`` environment variables can be used to force colors off
+  or on.
+- New interactive curses pager for all ``print_`` commands
+  (``print_catalog``, ``print_pairs``, ``print_families``).
+  Automatically activated when output is a terminal; use ``--no-pager``
+  to fall back to plain-text output. Requesting a specific output format
+  with ``-f``/``--format`` implies ``--no-pager``.
+- New ``-b/--backend`` option for ``map_families``, to plot families on
+  an interactive HTML map using
+  [folium](https://python-visualization.github.io/folium/), instead of
+  the default static Cartopy map. Folium is an optional dependency (not
+  installed by default): the folium backend is only used if folium is
+  installed.
+- Family marker size is now scaled with a quantity selected with the new
+  ``-s/--sizeby`` option (default: number of events), and a legend on the
+  map explains the marker size. This applies to both the Cartopy and the
+  Folium map backends.
+- Clickable URLs in terminal output for compatible terminals, e.g. in the
+  help messages and in the bug report.
+- New documentation page on event pairs, covering `print_pairs`,
+  `plot_pair` and `dedup_events`.
+
+## [0.8.3] - 2026-06-19
+
+Note: you should run `requake update_config` to update your config file
+to the latest version.
+
+The waveform disk cache is now a single SQLite database
+(`OUTDIR/waveform_cache.sqlite`) with a persistent negative cache that
+remembers failed downloads across runs, eliminating redundant HTTP requests.
+
+- New `wfcache` CLI: `prefetch`, `print`/`inspect`, `extract`,
+  `reset-failures`.
+- New config: `catalog_waveform_cache_failure_max_retries`,
+  `catalog_waveform_cache_failure_backoff_s`,
+  `catalog_waveform_require_prefetch`.
+- Several optimization for parallel runs in `scan_catalog` (especially on
+  Slurm clusters) and for startup time of `scan_catalog -c` (continue an
+  interrupted scan).
+- Extended documentation for `read_catalog`, `scan_catalog` and `wfcache`.
+
 ## [0.8.2] - 2026-06-03
 
 Note: you might want to run `requake update_config` to update your config file
@@ -187,6 +267,8 @@ Mostly a bugfix release with a slightly improved trace plotting.
 
 - Initial release, not yet feature complete
 
+[0.8.4]: https://github.com/SeismicSource/requake/compare/v0.8.3...v0.8.4
+[0.8.3]: https://github.com/SeismicSource/requake/compare/v0.8.2...v0.8.3
 [0.8.2]: https://github.com/SeismicSource/requake/compare/v0.8.1...v0.8.2
 [0.8.1]: https://github.com/SeismicSource/requake/compare/v0.8...v0.8.1
 [0.8]: https://github.com/SeismicSource/requake/compare/v0.7.3...v0.8

{requake-0.8.2 → requake-0.8.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: requake
-Version: 0.8.2
+Version: 0.8.4
 Summary: Repeating earthquakes search and analysis
 Author-email: Claudio Satriano <satriano@ipgp.fr>
 License-Expression: GPL-3.0-or-later
@@ -33,11 +33,13 @@ Requires-Dist: argcomplete
 Requires-Dist: tqdm
 Requires-Dist: tabulate
 Requires-Dist: pygments
+Provides-Extra: folium
+Requires-Dist: folium; extra == "folium"
 Dynamic: description
 Dynamic: description-content-type
 Dynamic: license-file
 
-<img src="https://cdn.jsdelivr.net/gh/SeismicSource/requake@9071fd7343802f3ef642a16f6bb02ff5ce1d88f5/imgs/Requake_logo.svg" width="400">
+<img src="https://cdn.jsdelivr.net/gh/SeismicSource/requake@5cd818d88427140b2705841c2046f72b10612d72/imgs/Requake_logo.svg" width="400">
 
 # Requake
 
@@ -167,6 +169,8 @@ Different commands are available:
     print_catalog       print the event catalog to screen
     scan_catalog        scan an existing catalog for earthquake pairs
     print_pairs         print pairs to screen
+    dedup_events        detect and flag duplicate events in the catalog from
+                        close event pairs
     plot_pair           plot traces for a given event pair
     build_families      build families of repeating earthquakes from a catalog
                         of pairs
@@ -181,6 +185,8 @@ Different commands are available:
                         families
     scan_templates      scan a continuous waveform stream using one or more
                         templates
+    wfcache             manage persistent waveform cache (prefetch, print,
+                        inspect, extract, reset_failures)
 
 Certain commands (e.g., `plot_pair`) require further arguments (use, e.g.,
 `requake plot_pair -h` to get help).
@@ -216,6 +222,14 @@ Now, build the catalog of event pairs with:
 
     requake scan_catalog
 
+When relying on FDSN web services for waveform data, it is strongly
+recommended to prefetch all waveform windows before running the scan.
+This downloads every required waveform once and stores it in a local
+SQLite cache, avoiding repeated downloads and dramatically reducing
+overall runtime for large catalogs:
+
+    requake wfcache prefetch
+
 Once done ([it will take time!](#performances)), you are ready to build
 repeating earthquake families:
 
@@ -232,6 +246,12 @@ repeating earthquake families:
   performance is typically dominated by waveform download latency rather than
   computation.
 
+- For large FDSN-based runs, use `requake wfcache prefetch` before
+  `requake scan_catalog` to download all waveforms upfront into a local
+  SQLite cache.  This eliminates repeated downloads, lets the scan read
+  exclusively from disk, and is the single most effective way to speed up
+  catalog scanning.
+
 - `requake build_families` is fast™.
 
 ## How to Cite
@@ -244,7 +264,7 @@ If you used Requake for a scientific paper, please cite it as:
 Please replace `X.Y` with the Requake version number you used.
 
 You can also cite the following abstract presented at the
-2016 AGU Fall Meeting:
+2021 AGU Fall Meeting:
 
 > Satriano, C., Doucet, A. & Bouin, M.-P. (2021).
 > Probing the creep rate along the Lesser Antilles Subduction Zone through repeating earthquakes.
@@ -260,7 +280,7 @@ You can also cite the following abstract presented at the
 [docs-link]: https://requake.readthedocs.io/en/latest/?badge=latest
 [changelog-badge]: https://img.shields.io/badge/Changelog-136CB6.svg
 [changelog-link]: https://github.com/SeismicSource/requake/blob/main/CHANGELOG.md
-[DOI-badge]: https://zenodo.org/badge/DOI/10.5281/zenodo.10832203.svg
+[DOI-badge]: https://img.shields.io/badge/DOI-10.5281%2Fzenodo.10832203-blue.svg 
 [DOI-link]: https://doi.org/10.5281/zenodo.10832203
 [Requake GitHub repository]: https://github.com/SeismicSource/requake
 

{requake-0.8.2 → requake-0.8.4}/README.md

@@ -128,6 +128,8 @@ Different commands are available:
     print_catalog       print the event catalog to screen
     scan_catalog        scan an existing catalog for earthquake pairs
     print_pairs         print pairs to screen
+    dedup_events        detect and flag duplicate events in the catalog from
+                        close event pairs
     plot_pair           plot traces for a given event pair
     build_families      build families of repeating earthquakes from a catalog
                         of pairs
@@ -142,6 +144,8 @@ Different commands are available:
                         families
     scan_templates      scan a continuous waveform stream using one or more
                         templates
+    wfcache             manage persistent waveform cache (prefetch, print,
+                        inspect, extract, reset_failures)
 
 Certain commands (e.g., `plot_pair`) require further arguments (use, e.g.,
 `requake plot_pair -h` to get help).
@@ -177,6 +181,14 @@ Now, build the catalog of event pairs with:
 
     requake scan_catalog
 
+When relying on FDSN web services for waveform data, it is strongly
+recommended to prefetch all waveform windows before running the scan.
+This downloads every required waveform once and stores it in a local
+SQLite cache, avoiding repeated downloads and dramatically reducing
+overall runtime for large catalogs:
+
+    requake wfcache prefetch
+
 Once done ([it will take time!](#performances)), you are ready to build
 repeating earthquake families:
 
@@ -193,6 +205,12 @@ repeating earthquake families:
   performance is typically dominated by waveform download latency rather than
   computation.
 
+- For large FDSN-based runs, use `requake wfcache prefetch` before
+  `requake scan_catalog` to download all waveforms upfront into a local
+  SQLite cache.  This eliminates repeated downloads, lets the scan read
+  exclusively from disk, and is the single most effective way to speed up
+  catalog scanning.
+
 - `requake build_families` is fast™.
 
 ## How to Cite
@@ -205,7 +223,7 @@ If you used Requake for a scientific paper, please cite it as:
 Please replace `X.Y` with the Requake version number you used.
 
 You can also cite the following abstract presented at the
-2016 AGU Fall Meeting:
+2021 AGU Fall Meeting:
 
 > Satriano, C., Doucet, A. & Bouin, M.-P. (2021).
 > Probing the creep rate along the Lesser Antilles Subduction Zone through repeating earthquakes.
@@ -221,7 +239,7 @@ You can also cite the following abstract presented at the
 [docs-link]: https://requake.readthedocs.io/en/latest/?badge=latest
 [changelog-badge]: https://img.shields.io/badge/Changelog-136CB6.svg
 [changelog-link]: https://github.com/SeismicSource/requake/blob/main/CHANGELOG.md
-[DOI-badge]: https://zenodo.org/badge/DOI/10.5281/zenodo.10832203.svg
+[DOI-badge]: https://img.shields.io/badge/DOI-10.5281%2Fzenodo.10832203-blue.svg 
 [DOI-link]: https://doi.org/10.5281/zenodo.10832203
 [Requake GitHub repository]: https://github.com/SeismicSource/requake
 

{requake-0.8.2 → requake-0.8.4}/pyproject.toml

@@ -38,6 +38,11 @@ dependencies = [
     "pygments",
 ]
 
+[project.optional-dependencies]
+folium = [
+    "folium",
+]
+
 [project.urls]
 Homepage = "https://requake.seismicsource.org"
 Source = "https://github.com/SeismicSource/requake"

{requake-0.8.2 → requake-0.8.4}/requake/_version.py

@@ -8,11 +8,11 @@ import json
 
 version_json = '''
 {
- "date": "2026-06-03T14:39:27+0200",
+ "date": "2026-10-23T18:15:54+0200",
  "dirty": false,
  "error": null,
- "full-revisionid": "9071fd7343802f3ef642a16f6bb02ff5ce1d88f5",
- "version": "0.8.2"
+ "full-revisionid": "5cd818d88427140b2705841c2046f72b10612d72",
+ "version": "0.8.4"
 }
 '''  # END VERSION_JSON
 

{requake-0.8.2 → requake-0.8.4}/requake/catalog/catalog.py

@@ -26,7 +26,8 @@ class RequakeEvent():
     def __init__(self, evid=None, orig_time=None, lon=None, lat=None,
                  depth=None, mag_type=None, mag=None, author=None,
                  catalog=None, contributor=None, contributor_id=None,
-                 mag_author=None, location_name=None, trace_id=None):
+                 mag_author=None, location_name=None, trace_id=None,
+                 duplicate=False):
         """Initialize an event container."""
         self.evid = evid
         self.orig_time = orig_time
@@ -42,6 +43,7 @@ class RequakeEvent():
         self.mag_author = mag_author
         self.location_name = location_name
         self.trace_id = trace_id
+        self.duplicate = duplicate
         self.correlations = {}
 
     def __eq__(self, other):

{requake-0.8.2 → requake-0.8.4}/requake/catalog/print_catalog.py

@@ -10,7 +10,8 @@ Print the event catalog to screen.
     (https://www.gnu.org/licenses/gpl-3.0-standalone.html)
 """
 import logging
-from ..config import rq_exit, generic_printer
+from ..config import rq_exit
+from ..config.generic_printer import _display_table
 from .catalog import read_stored_catalog
 logger = logging.getLogger(__name__.rsplit('.', maxsplit=1)[-1])
 
@@ -30,7 +31,8 @@ def print_catalog():
         ('latitude', '.4f'),
         ('depth\n(km)', '.3f'),
         ('mag\ntype', None),
-        ('mag', '.1f')
+        ('mag', '.1f'),
+        ('dup', None)
     ]
     rows = [
         [
@@ -40,8 +42,14 @@ def print_catalog():
             ev.lat,
             ev.depth,
             ev.mag_type,
-            ev.mag
+            ev.mag,
+            ev.duplicate
         ]
         for ev in catalog
     ]
-    generic_printer(rows, headers_fmt)
+    _display_table(
+        headers_fmt, rows,
+        row_label='Events',
+        copy_label='evid',
+        detail_title='Event Details',
+    )

{requake-0.8.2 → requake-0.8.4}/requake/catalog/read_catalog.py

@@ -13,6 +13,7 @@ import os
 import logging
 import contextlib
 from ..config import config, rq_exit
+from ..config.utils import run_with_spinner
 from ..database.db import get_db_path
 from ..database.catalog import write_catalog as write_stored_catalog
 from .catalog import RequakeEvent, RequakeCatalog
@@ -120,11 +121,14 @@ def read_catalog():
                 f'{nevs_read:n} events read from db file '
                 f'{get_db_path()}'
             )
-    logger.info('Reading catalog...')
+    logger.debug('Reading catalog...')
     input_cat_file = config.args.catalog_file
     if input_cat_file is not None:
         try:
-            catalog += _read_catalog_from_file()
+            catalog += run_with_spinner(
+                'Reading catalog...',
+                _read_catalog_from_file,
+            )
             # Filter catalog based on configuration
             catalog = _filter_catalog(catalog)
         except FileNotFoundError:

{requake-0.8.2 → requake-0.8.4}/requake/catalog/read_catalog_from_fdsnws.py

@@ -15,6 +15,7 @@ import urllib.request
 from obspy import UTCDateTime
 from obspy.clients.fdsn.header import URL_MAPPINGS
 from ..config import config
+from ..config.utils import run_with_spinner
 from .catalog import RequakeCatalog, RequakeEvent
 logger = logging.getLogger(__name__.rsplit('.', maxsplit=1)[-1])
 
@@ -110,7 +111,19 @@ def read_catalog_from_fdsnws():
     :return: Event catalog.
     :rtype: requake.catalog.RequakeCatalog
     """
-    logger.info('Downloading events from FDSN web services...')
+    download_message = 'Downloading events from FDSN web services...'
+    logger.debug(download_message)
+    event_list = run_with_spinner(
+        download_message,
+        _download_catalog_events,
+    )
+    catalog = RequakeCatalog(event_list)
+    logger.info(f'{len(catalog)} events downloaded')
+    return catalog
+
+
+def _download_catalog_events():
+    """Download events for all the configured FDSN web services."""
     cat_info = zip(
         config.catalog_fdsn_event_urls,
         config.catalog_start_times,
@@ -135,6 +148,4 @@ def read_catalog_from_fdsnws():
                 f'Unable to download events from {url} for period '
                 f'{start_time} - {end_time}. {msg}'
             )
-    catalog = RequakeCatalog(event_list)
-    logger.info(f'{len(catalog)} events downloaded')
-    return catalog
+    return event_list

{requake-0.8.2 → requake-0.8.4}/requake/config/configspec.conf

@@ -76,9 +76,19 @@ catalog_waveform_cache_size = integer(min=2, default=5000)
 ## Set to 0 to derive it automatically from catalog_waveform_cache_size.
 catalog_waveform_cache_size_parallel = integer(min=0, default=0)
 ## Keep a persistent copy of fetched event waveforms on disk to speed up
-## reruns. This on-disk cache lives in OUTDIR/waveform_cache and is not
+## reruns. This on-disk cache lives in OUTDIR/waveform_cache.sqlite and is
 ## limited by catalog_waveform_cache_size.
 catalog_waveform_disk_cache_enabled = boolean(default=true)
+## Maximum number of retries for a failed waveform download before
+## suppressing new attempts for the same cache key.
+catalog_waveform_cache_failure_max_retries = integer(min=0, default=3)
+## Base backoff in seconds for persistent waveform download failures.
+## The retry delay grows exponentially with each failure.
+catalog_waveform_cache_failure_backoff_s = float(min=0, default=600)
+## When True, skip live downloads for events absent from both positive
+## and negative cache, trusting a prior prefetch run to have covered
+## all fetchable events. Requires disk cache to be enabled.
+catalog_waveform_require_prefetch = boolean(default=false)
 ## Number of worker processes for catalog scan.
 ## 0 means automatic selection; 1 disables parallelism.
 catalog_scan_nprocs = integer(min=0, default=0)

requake-0.8.4/requake/config/generic_printer.py

@@ -0,0 +1,208 @@
+# -*- coding: utf8 -*-
+# SPDX-License-Identifier: GPL-3.0-or-later
+"""
+Generic printer functions for Requake.
+
+:copyright:
+    2021-2026 Claudio Satriano <satriano@ipgp.fr>
+:license:
+    GNU General Public License v3.0 or later
+    (https://www.gnu.org/licenses/gpl-3.0-standalone.html)
+"""
+import sys
+import os
+import csv
+import contextlib
+import logging
+from tabulate import tabulate
+from ..terminal import color_enabled, style
+from .config import config
+logger = logging.getLogger(__name__.rsplit('.', maxsplit=1)[-1])
+
+# Characters appearing in a ``tabulate`` separator (or divider) line.
+_TABLE_SEPARATOR_CHARS = frozenset('-|=+: ')
+
+
+def _is_separator_line(line):
+    """Return True if ``line`` is a table separator (or divider) line."""
+    stripped = line.strip()
+    return bool(stripped) and set(stripped) <= _TABLE_SEPARATOR_CHARS
+
+
+def _style_table(text, has_header=True):
+    """
+    Colorize a plain-text table produced by :func:`tabulate`.
+
+    Header lines are highlighted in bold cyan, separator lines are
+    dimmed, and data rows are left untouched.
+
+    :param text: table text
+    :type text: str
+    :param has_header: whether the table starts with a header
+    :type has_header: bool
+
+    :return: colorized table text
+    :rtype: str
+    """
+    if not color_enabled():
+        return text
+    lines = text.split('\n')
+    separator_index = next(
+        (i for i, line in enumerate(lines) if _is_separator_line(line)),
+        None,
+    )
+    if separator_index is None:
+        separator_index = 1 if has_header else 0
+    styled_lines = []
+    for index, line in enumerate(lines):
+        if _is_separator_line(line):
+            styled_lines.append(style(line, 'dim'))
+        elif has_header and index < separator_index:
+            styled_lines.append(style(line, 'bold', 'cyan'))
+        else:
+            styled_lines.append(line)
+    return '\n'.join(styled_lines)
+
+
+def _drop_header_block(text):
+    """
+    Return ``text`` without the table header and its separator line.
+
+    Used for continuation batches, which must not repeat the header
+    but must keep all their data rows.
+
+    :param text: table text
+    :type text: str
+    :return: table text without the header block
+    :rtype: str
+    """
+    lines = text.split('\n')
+    separator_index = next(
+        (i for i, line in enumerate(lines) if _is_separator_line(line)),
+        None,
+    )
+    if separator_index is None:
+        return '\n'.join(lines[1:])
+    return '\n'.join(lines[separator_index + 1:])
+
+
+def generic_printer(rows, headers_fmt, print_headers=True):
+    """
+    Print rows using the configured output format.
+
+    :param rows: Rows to print.
+    :type rows: list of rows
+    :param headers_fmt: Headers and format strings.
+    :type headers_fmt: list of tuples of str
+    """
+    headers = [h[0] for h in headers_fmt]
+    # Replace None with a safe default so tabulate never receives
+    # None as a format specifier (crashes on float columns).
+    floatfmt = [
+        h[1] if h[1] is not None else '.6g' for h in headers_fmt
+    ]
+    tablefmt = config.args.format
+    if tablefmt == 'csv':
+        writer = csv.writer(sys.stdout)
+        if print_headers:
+            # replace newlines with spaces in headers
+            headers = [h.replace('\n', ' ') for h in headers]
+            writer.writerow(headers)
+    elif tablefmt == 'markdown':
+        headers = [h.replace('\n', '<br>') for h in headers]
+    if tablefmt == 'csv':
+        try:
+            writer.writerows(rows)
+        except BrokenPipeError:
+            # Redirect remaining output to devnull to avoid another
+            # BrokenPipeError at shutdown
+            devnull = os.open(os.devnull, os.O_WRONLY)
+            os.dup2(devnull, sys.stdout.fileno())
+    else:
+        format_dict = {
+            'simple': 'simple',
+            'markdown': 'github'
+        }
+        tablefmt = format_dict[config.args.format]
+        with contextlib.suppress(BrokenPipeError):
+            kwargs = {
+                'headers': headers,
+                'floatfmt': floatfmt,
+                'tablefmt': tablefmt
+            }
+            line = tabulate(rows, **kwargs)
+            if not print_headers:
+                line = _drop_header_block(line)
+                if not line:
+                    return
+            print(_style_table(line, has_header=print_headers))
+
+
+def _display_table(headers_fmt, rows=None, data_source=None,
+                   row_label='Rows', copy_label=None,
+                   copy_fn=None, detail_title='Row Details',
+                   print_headers=True):
+    """
+    Display a table using the interactive curses pager.
+
+    When stdout is a TTY (and ``--no-pager`` is not set), the
+    interactive pager is used.  Otherwise the table is printed
+    to stdout via :func:`generic_printer`.
+
+    :param headers_fmt: Headers and format strings
+        (list of (name, fmt) tuples).
+    :param rows: In-memory rows (list of lists).  Ignored when
+        *data_source* is given.
+    :param data_source: Optional :class:`~requake.pager.DataSource`
+        for database-backed pagination.
+    :param row_label: Label for rows in the pager status bar.
+    :param copy_label: Label for the copy-to-clipboard message.
+    :param copy_fn: Optional callable ``copy_fn(row) -> str`` for
+        custom copy behaviour.
+    :param detail_title: Title for the detail popup.
+    :param print_headers: Whether to include the header row
+        (used for iterative printing fallback).
+    """
+    # Determine whether to use the pager
+    use_pager = sys.stdout.isatty()
+    if use_pager:
+        no_pager = getattr(config.args, 'no_pager', False)
+        if no_pager:
+            use_pager = False
+
+    if use_pager:
+        from ..pager import (
+            display_table_pager,
+            PagerException,
+            ListDataSource,
+        )
+        with contextlib.suppress(PagerException):
+            if data_source is not None:
+                ds = data_source
+            else:
+                fields = [h[0].replace('\n', ' ') for h in headers_fmt]
+                ds = ListDataSource(fields, rows or [])
+            display_table_pager(
+                ds,
+                row_label=row_label,
+                copy_label=copy_label,
+                copy_fn=copy_fn,
+                detail_title=detail_title,
+            )
+            return
+    # Fallback: plain-text output via generic_printer
+    if data_source is not None:
+        # For DB-backed sources, stream rows via generic_printer
+        fields = data_source.fields
+        total = data_source.total_count
+        batch_size = 1000
+        for offset in range(0, total, batch_size):
+            batch = data_source.get_rows(offset, batch_size, None, True)
+            # Rebuild headers_fmt for generic_printer
+            batch_headers_fmt = [(f, None) for f in fields]
+            generic_printer(
+                batch, batch_headers_fmt,
+                print_headers=(offset == 0 and print_headers)
+            )
+    else:
+        generic_printer(rows, headers_fmt, print_headers)