bugpipe 3.0.1__py3-none-any.whl

bugpipe/cli/__init__.py

@@ -0,0 +1,69 @@
+import logging
+import sys
+from datetime import datetime
+
+import httpx
+from rich.logging import RichHandler
+
+from ..api.client import TRACKERS
+from . import update_checker
+from .cmd import dispatch_client, parse_args
+from .term import FAIL, INFO, WARN, console, print_out
+
+
+def format_option(value) -> str:
+    """
+    Render an option value for the startup line: lists in brackets, strings
+    quoted so Rich's URL highlighting stops at the value.
+
+    :param value: The option value.
+    :return: Markup text.
+    """
+
+    if isinstance(value, list):
+        return f"[[italic]{', '.join(map(str, value))}[/italic]]"
+    if isinstance(value, str):
+        return f"'[italic]{value}[/italic]'"
+    return f"[italic]{value}[/italic]"
+
+
+def start():
+    """
+    CLI entry point.
+    """
+
+    args = parse_args()
+
+    if args.command == "trackers":
+        print_out(output=TRACKERS, as_raw=args.raw)
+        console.print(f"\n{len(TRACKERS)} trackers available")
+        return
+
+    logging.basicConfig(
+        level=logging.WARNING,
+        handlers=[RichHandler(markup=True, show_level=True)],
+    )
+
+    start_time = datetime.now().astimezone()
+    try:
+        overrides: str = ", ".join(
+            f"{name}={format_option(value)}" for name, value in args.overrides.items()
+        )
+        overrides_text: str = f" ({overrides})" if overrides else ""
+        console.log(
+            f"{INFO} Started bugpipe CLI {update_checker.__version__[:3]}{overrides_text} "
+            f"at {datetime.now().astimezone().strftime('%x %X')}"
+        )
+        with console.status("[dim]Initialising…[/dim]") as status:
+            update_checker.check(status=status)
+            dispatch_client(args=args, status=status)
+    except KeyboardInterrupt:
+        console.log(f"{WARN} User interrupted ([bold yellow]CTRL+C[/bold yellow])")
+        sys.exit(0)
+    except httpx.ConnectError as err:
+        console.log(f"{FAIL} {err}")
+    except httpx.ConnectTimeout:
+        console.log(f"{WARN} Connection timed out")
+    finally:
+        elapsed = (datetime.now().astimezone() - start_time).total_seconds()
+        console.log(f"{INFO} Finished in {elapsed:.1f} seconds")

bugpipe/cli/cmd.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import argparse
+import typing as t
+from datetime import datetime
+
+from ..api.client import TRACKERS, Bugpipe
+from ..api.models import Results
+from .term import FAIL, OK, console, export, print_out
+from .update_checker import __pkg__, __version__
+
+if t.TYPE_CHECKING:
+    from rich.status import Status
+
+    from ..api.models import Issue
+
+__all__ = ["dispatch_client", "parse_args"]
+
+
+def parse_args() -> argparse.Namespace:
+    """
+    Parse command-line arguments and return the populated namespace.
+
+    :return: Parsed arguments with the selected subcommand function in ``.func``.
+    """
+
+    parser = argparse.ArgumentParser(
+        prog=__pkg__,
+        description="Unofficial Python client for Buganizer; the Google Issue Tracking system.",
+        epilog=f"© {datetime.now().astimezone().year} Ritchie Mwewa",
+    )
+    parser.add_argument(
+        "-r",
+        "--raw",
+        action="store_true",
+        help="show raw output",
+    )
+    parser.add_argument(
+        "-p",
+        "--proxy",
+        metavar="URL",
+        help="proxy URL for all requests (e.g. http://localhost:8080)",
+    )
+    parser.add_argument(
+        "-t",
+        "--timeout",
+        type=int,
+        default=30,
+        metavar="SECONDS",
+        help="request timeout (default %(default)s)",
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action="version",
+        version=f"{__pkg__} {__version__}",
+    )
+    # Shared by commands that return issue data.
+    exportable = argparse.ArgumentParser(add_help=False)
+    exportable.add_argument(
+        "-e",
+        "--export",
+        action="append",
+        choices=["csv", "json"],
+        help="export format (repeatable)",
+    )
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # search
+    search_parser = subparsers.add_parser(
+        "search", parents=[exportable], help="search for issues"
+    )
+    search_parser.add_argument("query", help="search query")
+    search_parser.add_argument(
+        "-t",
+        "--tracker",
+        action="append",
+        choices=[tracker["slug"] for tracker in TRACKERS],
+        help="tracker slug (repeatable, see `bugpipe trackers`). Defaults to all",
+    )
+    search_parser.add_argument(
+        "-n",
+        "--per-page",
+        type=int,
+        default=25,
+        choices=[25, 50, 100, 250],
+        help="results per page (default: 25)",
+    )
+    search_parser.add_argument(
+        "-l",
+        "--limit",
+        type=int,
+        default=None,
+        metavar="N",
+        help="total results to fetch, paginating as needed",
+    )
+
+    search_parser.set_defaults(func=cmd_search)
+
+    # get
+    issue_parser = subparsers.add_parser(
+        "issue", parents=[exportable], help="get a single issue"
+    )
+    issue_parser.add_argument("issue_id", type=int, help="issue ID")
+    issue_parser.set_defaults(func=cmd_issue)
+
+    # batch
+    issues_parser = subparsers.add_parser(
+        "issues", parents=[exportable], help="batch get issues"
+    )
+    issues_parser.add_argument("issue_ids", type=int, nargs="+", help="issue IDs")
+    issues_parser.set_defaults(func=cmd_issues)
+
+    # comments
+    comments_parser = subparsers.add_parser(
+        "comments", parents=[exportable], help="get comments on an issue"
+    )
+    comments_parser.add_argument("issue_id", type=int, help="issue ID")
+    comments_parser.set_defaults(func=cmd_comments)
+
+    # trackers
+    subparsers.add_parser("trackers", help="list available trackers")
+
+    # echo (health check)
+    echo_parser = subparsers.add_parser(
+        "echo",
+        help="check whether the issue tracker backend is reachable",
+        description=(
+            "Ping the Buganizer backend (GET /action/yes) and print its "
+            "response. 'yes' means the backend is reachable and healthy; "
+            "'no' means it is unreachable or returned an error."
+        ),
+    )
+    echo_parser.set_defaults(func=cmd_echo)
+
+    args = parser.parse_args()
+    args.overrides = _overrides(args, parser, subparsers.choices[args.command])
+    return args
+
+
+def _overrides(args: argparse.Namespace, *parsers: argparse.ArgumentParser) -> dict:
+    """
+    Collect the options whose value differs from their default.
+
+    :param args: Parsed arguments.
+    :param parsers: The parsers that produced them.
+    :return: Long option name (without dashes) to value.
+    """
+
+    return {
+        action.option_strings[-1].lstrip("-"): getattr(args, action.dest)
+        for parser in parsers
+        for action in parser._actions
+        if action.option_strings
+        and action.dest in args
+        and getattr(args, action.dest) != action.default
+    }
+
+
+def cmd_search(client: Bugpipe, args: argparse.Namespace, status: Status):
+    """
+    Handle the 'search' subcommand.
+
+    :param client: Shared API client instance.
+    :param args: Parsed arguments with ``.query``, ``.per_page``, and ``.limit``.
+    :param status: Rich status spinner for progress updates.
+    """
+
+    query = args.query
+    per_page = args.per_page
+    limit = args.limit
+    tracker_label = ", ".join(args.tracker) if args.tracker else "all"
+
+    status.update(
+        f"[dim][bold]Searching [italic]{tracker_label}[/] issues for [bold green]{query}[/bold green]…[/dim]"
+    )
+    result = client.search(query=query, page_size=per_page)
+    issues: Results[Issue] = Results(result.issues)
+
+    while limit is not None and result.has_more and len(issues) < limit:
+        status.update(
+            f"[dim]Collected [cyan]{len(issues)}[/] of [cyan]{limit}[/] issues…[/dim]"
+        )
+        page = client.next_page(result)
+        if page is None:
+            break
+        result = page
+        issues.extend(result.issues)
+    if limit is not None:
+        issues = Results(issues[:limit])
+
+    console.log(
+        f"{OK} Got {len(issues)} of ~{result.total_count}+ issues for '{query}'\n"
+    )
+    # Rich's Status redirects sys.stdout, which makes the pager (and the
+    # TTY check) see a non-tty. Stop it first so paging can take over.
+    status.stop()
+    print_out(output=issues, as_raw=args.raw)
+
+    if args.export:
+        export(output=issues, formats=args.export)
+
+    if result.has_more:
+        print()
+        console.log(f"~{result.total_count - len(issues)}+ more results available")
+
+
+def cmd_issue(client: Bugpipe, args: argparse.Namespace, status: Status):
+    """
+    Handle the 'issue' subcommand.
+
+    :param client: Shared API client instance.
+    :param args: Parsed arguments with ``.issue_id``.
+    :param status: Rich status spinner for progress updates.
+    """
+
+    issue_id = args.issue_id
+    status.update(f"[dim]Getting issue {issue_id}…[/]")
+    issue = client.issue(issue_id=issue_id)
+
+    status.stop()  # restore stdout so the pager works (Status redirects it)
+    print_out(output=issue)
+    if args.export:
+        export(output=issue, formats=args.export)
+
+
+def cmd_issues(client: Bugpipe, args: argparse.Namespace, status: Status):
+    """
+    Handle the 'issues' subcommand.
+
+    :param client: Shared API client instance.
+    :param args: Parsed arguments with ``.issue_ids``.
+    :param status: Rich status spinner for progress updates.
+    """
+
+    issue_ids = args.issue_ids
+    status.update(f"[dim]Getting issues {issue_ids}…[/]")
+    issues = client.issues(issue_ids=issue_ids)
+
+    status.stop()  # restore stdout so the pager works (Status redirects it)
+    print_out(output=issues)
+    if args.export:
+        export(output=issues, formats=args.export)
+
+
+def cmd_comments(client: Bugpipe, args: argparse.Namespace, status: Status):
+    """
+    Handle the 'comments' subcommand.
+
+    :param client: Shared API client instance.
+    :param args: Parsed arguments with ``.issue_id``.
+    :param status: Rich status spinner for progress updates.
+    """
+
+    issue_id = args.issue_id
+
+    status.update(status=f"[dim]Getting comments for issue {issue_id}…[/]")
+    result = client.comments(issue_id=issue_id)
+
+    status.stop()  # restore stdout so the pager works (Status redirects it)
+    console.print(f"Issue #{issue_id} — {len(result.comments)} comments\n")
+    print_out(output=result.comments)
+    if args.export:
+        export(output=result.comments, formats=args.export)
+
+
+# noinspection PyUnusedLocal
+def cmd_echo(client: Bugpipe, args: argparse.Namespace, status: Status):
+    """
+    Handle the 'echo' subcommand: ping the backend and print its response.
+
+    Prints a green ``✔`` when the backend is reachable and healthy
+    (``echo: yes``), or a red ``✘`` when it is unreachable or returned
+    an error (``echo: no``).
+
+    :param client: Shared API client instance.
+    :param args: Parsed arguments (unused).
+    :param status: Rich status spinner for progress updates.
+    """
+
+    status.update("[dim]Pinging issue tracker backend…[/dim]")
+    response = client.echo()
+    if response == "yes":
+        console.log(f"{OK} echo: {response}")
+    else:
+        console.log(f"{FAIL} echo: {response}")
+
+
+def dispatch_client(args: argparse.Namespace, status: Status):
+    """
+    Check for updates, then create a single client and dispatch to the
+    chosen subcommand.
+
+    :param args: Parsed arguments with ``.func`` set to the subcommand handler.
+    :param status: Rich status spinner for progress updates.
+    """
+
+    with Bugpipe(
+        trackers=getattr(args, "tracker", None),
+        timeout=args.timeout,
+        proxy=args.proxy,
+    ) as client:
+        args.func(client=client, args=args, status=status)

bugpipe/cli/term.py

@@ -0,0 +1,234 @@
+"""
+Console output for the CLI.
+
+Results print as their dataclasses through a pager, so bulk output scrolls
+instead of flooding the terminal. Writing them to file is left to the models'
+own ``to_json()``/``to_csv()``.
+"""
+
+import enum
+import typing as t
+from contextlib import nullcontext
+from datetime import datetime
+
+from rich.box import ASCII
+from rich.console import Console
+from rich.pretty import Pretty
+from rich.table import Table
+from rich.text import Text
+
+from ..api.models import (
+    Comment,
+    Exportable,
+    Issue,
+    IssueType,
+    Priority,
+    Results,
+    Severity,
+    Status,
+)
+
+__all__ = ["FAIL", "INFO", "OK", "WARN", "export", "print_out"]
+
+#: Style for values the API sent that the enum doesn't define (e.g. ``TYPE_7``).
+UNKNOWN_STYLE = "magenta"
+
+#: Priority cell styles. Other known values (P3, P4) are plain yellow.
+PRIORITY_STYLES = {
+    Priority.P0: "bold red",
+    Priority.P1: "red",
+    Priority.P2: "bold yellow",
+}
+
+#: Severity cell styles. Other known values (S3, S4) are plain yellow.
+SEVERITY_STYLES = {
+    Severity.S0: "bold red",
+    Severity.S1: "red",
+    Severity.S2: "bold yellow",
+}
+
+#: Issue type cell styles. Other known values (INTERNAL_CLEANUP, PROCESS) are unstyled.
+ISSUE_TYPE_STYLES = {
+    IssueType.VULNERABILITY: "bold red",
+    IssueType.BUG: "red",
+    IssueType.CUSTOMER_ISSUE: "bold yellow",
+    IssueType.FEATURE_REQUEST: "bold green",
+}
+
+#: Status cell styles. Open statuses are blue, fixed ones green. Other closed
+#: statuses (NOT_REPRODUCIBLE, INTENDED_BEHAVIOR, OBSOLETE, INFEASIBLE, DUPLICATE)
+#: are dim.
+STATUS_STYLES = {
+    Status.NEW: "bold blue",
+    Status.ASSIGNED: "cyan",
+    Status.ACCEPTED: "bold cyan",
+    Status.FIXED: "green",
+    Status.VERIFIED: "bold green",
+}
+
+#: Issue table columns: header -> cell builder. Int cells are right-aligned.
+ISSUE_COLUMNS: dict[str, t.Callable[[Issue], t.Any]] = {
+    "ID": lambda issue: issue.id,
+    "Title": lambda issue: issue.title,
+    "Type": lambda issue: _style_cell(
+        value=issue.issue_type, styles=ISSUE_TYPE_STYLES, default="dim"
+    ),
+    "Priority": lambda issue: _style_cell(
+        value=issue.priority, styles=PRIORITY_STYLES, default="yellow"
+    ),
+    "Severity": lambda issue: _style_cell(
+        value=issue.severity, styles=SEVERITY_STYLES, default="green"
+    ),
+    "Status": lambda issue: _style_cell(
+        value=issue.status, styles=STATUS_STYLES, default="dim"
+    ),
+    "24h Views": lambda issue: issue.views_24h,
+    "7d Views": lambda issue: issue.views_7d,
+    "30d Views": lambda issue: issue.views_30d,
+    "Created At": lambda issue: issue.created_at,
+    "Modified At": lambda issue: issue.modified_at,
+}
+
+#: Success marker (green ✔).
+OK = "[bold green]✔[/bold green]"
+
+#: Failure/error marker (red ✘).
+FAIL = "[bold red]✘[/bold red]"
+
+#: Warning/interrupted marker (yellow ✘).
+WARN = "[bold yellow]✘[/bold yellow]"
+
+#: Informational marker (blue *).
+INFO = "[bold blue]*[/bold blue]"
+
+console = Console(log_time=False, log_path=False)
+
+
+def _style_cell(value: enum.Enum | None, styles: dict, default: str = "") -> Text | str:
+    """
+    Build a table cell for an enum value, styled by its member.
+
+    :param value: The enum value, or None when the issue has none.
+    :param styles: Style per known member.
+    :param default: Style for known members missing from ``styles``.
+    :return: The styled name, or an empty string for None.
+    """
+
+    if value is None:
+        return ""
+    if value.name not in type(value).__members__:
+        return Text(value.name, style=UNKNOWN_STYLE)
+    return Text(value.name, style=styles.get(value, default))
+
+
+def _pretty_print(output: t.Any):
+    """
+    Show a result, paging it.
+
+    :param output: A single item, or a list of them.
+    """
+
+    if not output:
+        console.log("No results.")
+        return
+
+    context = console.pager(styles=True) if console.is_terminal else nullcontext()
+    if not console.is_terminal:
+        console.print(f"{WARN} Not a TTY — output won't be paged.")
+
+    with context:
+        if isinstance(output, list):
+            for index, item in enumerate(output):
+                if index:
+                    console.print()
+                console.print(Pretty(item))
+        else:
+            console.print(Pretty(output))
+
+
+def _print_table(rows: t.Sequence[dict | Exportable]):
+    """
+    Print and page rows in a table. Headers come from the first row.
+
+    :param rows: Dicts (headers are the keys), issues (headers from
+        ``ISSUE_COLUMNS``), or other exportables (headers from ``to_dict``).
+    """
+
+    if not rows:
+        return
+    dicts = [
+        (
+            {header: cell(row) for header, cell in ISSUE_COLUMNS.items()}
+            if isinstance(row, Issue)
+            else row.to_dict() if isinstance(row, Exportable) else row
+        )
+        for row in rows
+    ]
+
+    table = Table(box=ASCII, highlight=True, expand=True, header_style="bold")
+    for header, value in dicts[0].items():
+        table.add_column(
+            str(header).title(),
+            justify="right" if isinstance(value, int) else "left",
+            overflow="fold",
+        )
+    for row in dicts:
+        table.add_row(
+            *(cell if isinstance(cell, Text) else str(cell) for cell in row.values())
+        )
+
+    if not console.is_terminal:
+        console.print(f"{WARN} Not a TTY — output won't be paged.")
+    with console.pager(styles=True) if console.is_terminal else nullcontext():
+        console.print(table)
+
+
+def print_out(
+    output: list[dict] | Results[Issue] | Results[Comment] | Issue, as_raw: bool = False
+):
+    """
+    Show a result, paging it. Issues and dicts go in a table; a single issue
+    and comments print as their dataclasses.
+
+    :param output: A single issue, a list of issues or comments, or a list of dicts.
+    :param as_raw: Print tabular results as dataclasses instead of a table.
+    """
+
+    if (
+        isinstance(output, Issue)
+        or isinstance(output, Results)
+        and all(isinstance(item, Comment) for item in output)
+    ):
+        _pretty_print(output=output)
+
+    elif (
+        isinstance(output, Results)
+        and all(isinstance(item, Issue) for item in output)
+        or isinstance(output, list)
+        and all(isinstance(item, dict) for item in output)
+    ):
+        if as_raw:
+            _pretty_print(output=output)
+        else:
+            _print_table(rows=output)
+
+
+def export(output: Exportable | Results[t.Any], formats: list[str]):
+    """
+    Write a result to timestamped files, one per format.
+
+    :param output: A single item, or a list of them.
+    :param formats: Format strings, each one of ``"csv"`` or ``"json"``.
+    """
+
+    if not output:
+        return
+
+    base = f"bugpipe-{datetime.now().astimezone().strftime('%Y%m%d_%H%M%S')}"
+    for fmt in formats:
+        if fmt == "json":
+            console.print(f"\n{OK} JSON exported to {output.to_json(f'{base}.json')}")
+        elif fmt == "csv":
+            console.print(f"\n{OK} CSV exported to {output.to_csv(f'{base}.csv')}")
+        else:
+            continue