feat: add --dump-html option to dump raw HTML to stdout (#7)

Author: dreamiurg

peakbagger/cli.py

@@ -3,6 +3,7 @@
 from typing import TYPE_CHECKING
 
 import click
+from rich.console import Console
 
 from peakbagger import __version__
 from peakbagger.client import PeakBaggerClient
@@ -12,6 +13,42 @@
 if TYPE_CHECKING:
     from peakbagger.models import Peak
 
+# Module-level console for status messages (stderr to keep stdout clean for data)
+_console = Console(stderr=True)
+
+
+def _status(ctx: click.Context, message: str, style: str | None = None) -> None:
+    """
+    Print a status message to stderr using Rich.
+
+    Respects --quiet and --dump-html flags to keep output clean.
+
+    Args:
+        ctx: Click context containing options
+        message: Status message to display
+        style: Optional Rich style (e.g., "bold yellow", "red")
+    """
+    # Suppress status messages if --quiet or --dump-html is set
+    if ctx.obj.get("quiet") or ctx.obj.get("dump_html"):
+        return
+
+    if style:
+        _console.print(message, style=style)
+    else:
+        _console.print(message)
+
+
+def _error(message: str) -> None:
+    """
+    Print an error message to stderr using Rich.
+
+    Always shown regardless of --quiet or --dump-html flags.
+
+    Args:
+        message: Error message to display
+    """
+    _console.print(f"[bold red]Error:[/bold red] {message}")
+
 
 @click.group()
 @click.version_option(version=__version__)
@@ -21,11 +58,17 @@
     is_flag=True,
     help="Suppress informational messages",
 )
+@click.option(
+    "--dump-html",
+    is_flag=True,
+    help="Dump raw HTML to stdout instead of parsing",
+)
 @click.pass_context
-def main(ctx: click.Context, quiet: bool) -> None:
+def main(ctx: click.Context, quiet: bool, dump_html: bool) -> None:
     """PeakBagger CLI - Search and retrieve mountain peak data from PeakBagger.com"""
     ctx.ensure_object(dict)
     ctx.obj["quiet"] = quiet
+    ctx.obj["dump_html"] = dump_html
 
 
 @main.group()
@@ -60,7 +103,10 @@ def ascent() -> None:
     default=2.0,
     help="Seconds between requests (default: 2.0)",
 )
-def search(query: str, output_format: str, full: bool, rate_limit: float) -> None:
+@click.pass_context
+def search(
+    ctx: click.Context, query: str, output_format: str, full: bool, rate_limit: float
+) -> None:
     """
     Search for peaks by name.
 
@@ -80,19 +126,24 @@ def search(query: str, output_format: str, full: bool, rate_limit: float) -> Non
 
     try:
         # Fetch search results
-        click.echo(f"Searching for '{query}'...")
+        _status(ctx, f"Searching for '{query}'...")
         html = client.get("/search.aspx", params={"ss": query, "tid": "M"})
 
+        # If dump-html flag is set, print HTML and exit
+        if ctx.obj.get("dump_html"):
+            click.echo(html)
+            return
+
         # Parse results
         results = scraper.parse_search_results(html)
 
         if not results:
-            click.echo(f"No results found for '{query}'")
+            _status(ctx, f"No results found for '{query}'")
             return
 
         # If --full flag, fetch details for each peak
         if full:
-            click.echo(f"Fetching details for {len(results)} peak(s)...\n")
+            _status(ctx, f"Fetching details for {len(results)} peak(s)...\n")
             peaks: list[Peak] = []
             for result in results:
                 detail_html = client.get(f"/{result.url}")
@@ -106,7 +157,7 @@ def search(query: str, output_format: str, full: bool, rate_limit: float) -> Non
             formatter.format_search_results(results, output_format)
 
     except Exception as e:
-        click.echo(f"Error: {e}", err=True)
+        _error(str(e))
         raise click.Abort() from e
     finally:
         client.close()
@@ -127,7 +178,8 @@ def search(query: str, output_format: str, full: bool, rate_limit: float) -> Non
     default=2.0,
     help="Seconds between requests (default: 2.0)",
 )
-def show(peak_id: str, output_format: str, rate_limit: float) -> None:
+@click.pass_context
+def show(ctx: click.Context, peak_id: str, output_format: str, rate_limit: float) -> None:
     """
     Get detailed information about a specific peak.
 
@@ -145,21 +197,26 @@ def show(peak_id: str, output_format: str, rate_limit: float) -> None:
 
     try:
         # Fetch peak detail page
-        click.echo(f"Fetching peak {peak_id}...")
+        _status(ctx, f"Fetching peak {peak_id}...")
         html = client.get("/peak.aspx", params={"pid": peak_id})
 
+        # If dump-html flag is set, print HTML and exit
+        if ctx.obj.get("dump_html"):
+            click.echo(html)
+            return
+
         # Parse peak data
         peak_obj = scraper.parse_peak_detail(html, peak_id)
 
         if not peak_obj:
-            click.echo(f"Failed to parse peak data for ID {peak_id}", err=True)
+            _error(f"Failed to parse peak data for ID {peak_id}")
             raise click.Abort()
 
         # Display results
         formatter.format_peak_detail(peak_obj, output_format)
 
     except Exception as e:
-        click.echo(f"Error: {e}", err=True)
+        _error(str(e))
         raise click.Abort() from e
     finally:
         client.close()
@@ -211,7 +268,9 @@ def show(peak_id: str, output_format: str, rate_limit: float) -> None:
     default=2.0,
     help="Seconds between requests (default: 2.0)",
 )
+@click.pass_context
 def ascents(
+    ctx: click.Context,
     peak_id: str,
     output_format: str,
     after: str | None,
@@ -245,7 +304,7 @@ def ascents(
 
     # Validate mutually exclusive date filters
     if within and (after or before):
-        click.echo("Error: --within cannot be combined with --after/--before", err=True)
+        _error("--within cannot be combined with --after/--before")
         raise click.Abort()
 
     client: PeakBaggerClient = PeakBaggerClient(rate_limit_seconds=rate_limit)
@@ -255,19 +314,24 @@ def ascents(
 
     try:
         # Fetch ascent list page
-        click.echo(f"Fetching ascents for peak {peak_id}...")
+        _status(ctx, f"Fetching ascents for peak {peak_id}...")
         url = "/climber/PeakAscents.aspx"
         params = {"pid": peak_id, "sort": "ascentdate", "u": "ft", "y": "9999"}
         html = client.get(url, params=params)
 
+        # If dump-html flag is set, print HTML and exit
+        if ctx.obj.get("dump_html"):
+            click.echo(html)
+            return
+
         # Parse ascents
         ascent_list = scraper.parse_peak_ascents(html)
 
         if not ascent_list:
-            click.echo(f"No ascents found for peak ID {peak_id}", err=True)
+            _error(f"No ascents found for peak ID {peak_id}")
             return
 
-        click.echo(f"Found {len(ascent_list)} ascents\n")
+        _status(ctx, f"Found {len(ascent_list)} ascents\n")
 
         # Apply date filters
         filtered_ascents = ascent_list
@@ -276,26 +340,26 @@ def ascents(
                 period = analyzer.parse_within_period(within)
                 after_date = datetime.now() - period
                 filtered_ascents = analyzer.filter_by_date_range(filtered_ascents, after=after_date)
-                click.echo(f"Filtered to {len(filtered_ascents)} ascents within {within}\n")
+                _status(ctx, f"Filtered to {len(filtered_ascents)} ascents within {within}\n")
             except ValueError as e:
-                click.echo(f"Error: {e}", err=True)
+                _error(str(e))
                 raise click.Abort() from e
         elif after or before:
             after_date = datetime.strptime(after, "%Y-%m-%d") if after else None
             before_date = datetime.strptime(before, "%Y-%m-%d") if before else None
             filtered_ascents = analyzer.filter_by_date_range(
                 filtered_ascents, after=after_date, before=before_date
             )
-            click.echo(f"Filtered to {len(filtered_ascents)} ascents\n")
+            _status(ctx, f"Filtered to {len(filtered_ascents)} ascents\n")
 
         # Apply metadata filters
         if with_gpx:
             filtered_ascents = [a for a in filtered_ascents if a.has_gpx]
-            click.echo(f"Filtered to {len(filtered_ascents)} ascents with GPX tracks\n")
+            _status(ctx, f"Filtered to {len(filtered_ascents)} ascents with GPX tracks\n")
 
         if with_tr:
             filtered_ascents = [a for a in filtered_ascents if a.has_trip_report]
-            click.echo(f"Filtered to {len(filtered_ascents)} ascents with trip reports\n")
+            _status(ctx, f"Filtered to {len(filtered_ascents)} ascents with trip reports\n")
 
         # Display ascent list (not statistics)
         # Create a simple statistics object just for formatting the list
@@ -310,10 +374,10 @@ def ascents(
         )
 
         if len(filtered_ascents) > limit:
-            click.echo(f"\nShowing first {limit} of {len(filtered_ascents)} ascents")
+            _status(ctx, f"\nShowing first {limit} of {len(filtered_ascents)} ascents")
 
     except Exception as e:
-        click.echo(f"Error: {e}", err=True)
+        _error(str(e))
         raise click.Abort() from e
     finally:
         client.close()
@@ -360,7 +424,9 @@ def ascents(
     default=2.0,
     help="Seconds between requests (default: 2.0)",
 )
+@click.pass_context
 def stats(
+    ctx: click.Context,
     peak_id: str,
     output_format: str,
     after: str | None,
@@ -393,7 +459,7 @@ def stats(
 
     # Validate mutually exclusive date filters
     if within and (after or before):
-        click.echo("Error: --within cannot be combined with --after/--before", err=True)
+        _error("--within cannot be combined with --after/--before")
         raise click.Abort()
 
     client: PeakBaggerClient = PeakBaggerClient(rate_limit_seconds=rate_limit)
@@ -403,19 +469,24 @@ def stats(
 
     try:
         # Fetch ascent list page
-        click.echo(f"Fetching ascents for peak {peak_id}...")
+        _status(ctx, f"Fetching ascents for peak {peak_id}...")
         url = "/climber/PeakAscents.aspx"
         params = {"pid": peak_id, "sort": "ascentdate", "u": "ft", "y": "9999"}
         html = client.get(url, params=params)
 
+        # If dump-html flag is set, print HTML and exit
+        if ctx.obj.get("dump_html"):
+            click.echo(html)
+            return
+
         # Parse ascents
         ascent_list = scraper.parse_peak_ascents(html)
 
         if not ascent_list:
-            click.echo(f"No ascents found for peak ID {peak_id}", err=True)
+            _error(f"No ascents found for peak ID {peak_id}")
             return
 
-        click.echo(f"Found {len(ascent_list)} ascents\n")
+        _status(ctx, f"Found {len(ascent_list)} ascents\n")
 
         # Apply date filters
         filtered_ascents = ascent_list
@@ -424,25 +495,25 @@ def stats(
                 period = analyzer.parse_within_period(within)
                 after_date = datetime.now() - period
                 filtered_ascents = analyzer.filter_by_date_range(filtered_ascents, after=after_date)
-                click.echo(f"Analyzing {len(filtered_ascents)} ascents within {within}\n")
+                _status(ctx, f"Analyzing {len(filtered_ascents)} ascents within {within}\n")
             except ValueError as e:
-                click.echo(f"Error: {e}", err=True)
+                _error(str(e))
                 raise click.Abort() from e
         elif after or before:
             after_date = datetime.strptime(after, "%Y-%m-%d") if after else None
             before_date = datetime.strptime(before, "%Y-%m-%d") if before else None
             filtered_ascents = analyzer.filter_by_date_range(
                 filtered_ascents, after=after_date, before=before_date
             )
-            click.echo(f"Analyzing {len(filtered_ascents)} ascents\n")
+            _status(ctx, f"Analyzing {len(filtered_ascents)} ascents\n")
 
         # Parse reference date for seasonal analysis
         ref_date = None
         if reference_date:
             try:
                 ref_date = datetime.strptime(reference_date, "%Y-%m-%d")
             except ValueError as e:
-                click.echo(f"Error: Invalid reference date format: {reference_date}", err=True)
+                _error(f"Invalid reference date format: {reference_date}")
                 raise click.Abort() from e
 
         # Calculate statistics
@@ -461,7 +532,7 @@ def stats(
         )
 
     except Exception as e:
-        click.echo(f"Error: {e}", err=True)
+        _error(str(e))
         raise click.Abort() from e
     finally:
         client.close()
@@ -482,7 +553,8 @@ def stats(
     default=2.0,
     help="Seconds between requests (default: 2.0)",
 )
-def show_ascent(ascent_id: str, output_format: str, rate_limit: float) -> None:
+@click.pass_context
+def show_ascent(ctx: click.Context, ascent_id: str, output_format: str, rate_limit: float) -> None:
     """
     Get detailed information about a specific ascent.
 
@@ -500,21 +572,26 @@ def show_ascent(ascent_id: str, output_format: str, rate_limit: float) -> None:
 
     try:
         # Fetch ascent detail page
-        click.echo(f"Fetching ascent {ascent_id}...")
+        _status(ctx, f"Fetching ascent {ascent_id}...")
         html = client.get("/climber/ascent.aspx", params={"aid": ascent_id})
 
+        # If dump-html flag is set, print HTML and exit
+        if ctx.obj.get("dump_html"):
+            click.echo(html)
+            return
+
         # Parse ascent data
         ascent_obj = scraper.parse_ascent_detail(html, ascent_id)
 
         if not ascent_obj:
-            click.echo(f"Failed to parse ascent data for ID {ascent_id}", err=True)
+            _error(f"Failed to parse ascent data for ID {ascent_id}")
             raise click.Abort()
 
         # Display results
         formatter.format_ascent_detail(ascent_obj, output_format)
 
     except Exception as e:
-        click.echo(f"Error: {e}", err=True)
+        _error(str(e))
         raise click.Abort() from e
     finally:
         client.close()