github-issue-list 0.0.1__py3-none-any.whl

github_issue_list-0.0.1.dist-info/METADATA

@@ -0,0 +1,92 @@
+Metadata-Version: 2.4
+Name: github-issue-list
+Version: 0.0.1
+Summary: List open GitHub issues assigned to a user in an organization.
+Author: Kaizten Analytics
+License-Expression: LicenseRef-Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# GitHub Issue List
+
+`github-issue-list` uses the authenticated GitHub CLI account to list open issues assigned to a user in an organization's non-archived repositories.
+
+Issues are printed in a table sorted globally from the oldest creation time to the most recent. Issue titles are normalized to one line and limited to 30 characters.
+
+## Requirements
+
+- Python 3.10 or newer
+- GitHub CLI (`gh`)
+- An authenticated GitHub CLI session:
+
+```bash
+gh auth login
+```
+
+## Usage
+
+After installing the package, run:
+
+```bash
+github-issue-list
+```
+
+The organization defaults to `kaizten`, and the username defaults to the active `gh` account. Override either value with named arguments:
+
+```bash
+github-issue-list --organization octo --username monalisa
+```
+
+From a source checkout, the wrapper exposes the same interface:
+
+```bash
+./github-issue-list.py --organization octo --username monalisa
+```
+
+```text
+usage: github-issue-list [-h] [--organization ORGANIZATION] [--username USERNAME]
+
+List open GitHub issues assigned to a user in an organization.
+
+options:
+  -h, --help            show this help message and exit
+  --organization ORGANIZATION
+                        GitHub organization. Default: kaizten
+  --username USERNAME   GitHub assignee. Defaults to the authenticated gh user.
+```
+
+The table contains the full repository name, issue number, truncated title, UTC creation time, and elapsed time since creation. The search returns at most 1,000 issues, matching GitHub's issue-search result limit.
+
+## Development
+
+Run the unit tests:
+
+```bash
+python3 -m unittest discover -s tests -v
+```
+
+Build and validate the wheel and source distribution:
+
+```bash
+./build-package.sh
+```
+
+Artifacts are written under `dist/` and checked with Twine.
+
+Publish previously built artifacts to PyPI:
+
+```bash
+./publish-pypi.sh
+```
+
+If PyPI reports that the version already exists, increment the version in `pyproject.toml`, rebuild, and publish again.
+
+Install the package in a virtual environment:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python3 -m pip install .
+```

github_issue_list-0.0.1.dist-info/RECORD

@@ -0,0 +1,6 @@
+github_issue_list.py,sha256=zuHxskC65-RUp7kB7aXNoVj0ord6F4KO5lgOQ7-HOWs,7948
+github_issue_list-0.0.1.dist-info/METADATA,sha256=UIUBh1fKgFumYD5Lg3m-Fhez9X2gJMeMBlPb4B5LRHk,2444
+github_issue_list-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+github_issue_list-0.0.1.dist-info/entry_points.txt,sha256=nwPkRnbyYop3woGXD0ZK18aR4HDVmeDmpaZPlxnwDpU,61
+github_issue_list-0.0.1.dist-info/top_level.txt,sha256=Vi7KdWU5HNKt1jGQCOU94I_CU98ySLou_75x-yqVHeo,18
+github_issue_list-0.0.1.dist-info/RECORD,,

github_issue_list-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

github_issue_list-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+github-issue-list = github_issue_list:main

github_issue_list-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+github_issue_list

github_issue_list.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""List open GitHub issues assigned to a user in an organization."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+
+DEFAULT_ORGANIZATION = "kaizten"
+SEARCH_LIMIT = 1000
+TITLE_LIMIT = 30
+NAME_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+REPOSITORY_RE = re.compile(r"^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$")
+
+
+class IssueListError(Exception):
+    """Expected user-facing error."""
+
+
+@dataclass(frozen=True)
+class Issue:
+    repository: str
+    number: int
+    title: str
+    created_at: datetime
+
+
+def utc_now() -> datetime:
+    return datetime.now(timezone.utc).replace(microsecond=0)
+
+
+def parse_github_datetime(value: str) -> datetime:
+    try:
+        parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError as exc:
+        raise IssueListError(f"Invalid GitHub datetime: {value}") from exc
+    if parsed.tzinfo is None:
+        raise IssueListError(f"Invalid GitHub datetime: {value}")
+    return parsed.astimezone(timezone.utc)
+
+
+def format_github_datetime(value: datetime) -> str:
+    return value.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def elapsed_time(created_at: datetime, now: datetime) -> str:
+    seconds = max(0, int((now - created_at).total_seconds()))
+    days, seconds = divmod(seconds, 24 * 60 * 60)
+    hours, seconds = divmod(seconds, 60 * 60)
+    minutes = seconds // 60
+    return f"{days}d {hours}h {minutes}m"
+
+
+def validate_name(value: str, label: str) -> str:
+    if not NAME_RE.fullmatch(value):
+        raise IssueListError(f"{label} must contain only letters, numbers, underscores, dots, or hyphens.")
+    return value
+
+
+def validate_repository(value: str) -> str:
+    if not REPOSITORY_RE.fullmatch(value):
+        raise IssueListError(f"Invalid repository name returned by GitHub: {value}")
+    return value
+
+
+def require_gh() -> None:
+    if shutil.which("gh") is None:
+        raise IssueListError("GitHub CLI 'gh' is required but was not found. Install it from https://cli.github.com/.")
+    result = subprocess.run(
+        ["gh", "auth", "status"],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        text=True,
+    )
+    if result.returncode != 0:
+        raise IssueListError("GitHub CLI is not authenticated. Run: gh auth login")
+
+
+def run_gh_json(args: list[str]) -> Any:
+    result = subprocess.run(["gh", *args], capture_output=True, text=True)
+    if result.returncode != 0:
+        details = result.stderr.strip() or result.stdout.strip() or f"exit code {result.returncode}"
+        raise IssueListError(f"gh command failed: gh {' '.join(args)}\n{details}")
+    try:
+        return json.loads(result.stdout or "null")
+    except json.JSONDecodeError as exc:
+        raise IssueListError(f"gh returned invalid JSON for: gh {' '.join(args)}") from exc
+
+
+def current_username() -> str:
+    user = run_gh_json(["api", "user"])
+    if not isinstance(user, dict) or not isinstance(user.get("login"), str):
+        raise IssueListError("Unable to read authenticated GitHub username.")
+    return validate_name(user["login"], "GitHub username")
+
+
+def repository_name(value: Any) -> str:
+    if isinstance(value, str):
+        return validate_repository(value)
+    if isinstance(value, dict) and isinstance(value.get("nameWithOwner"), str):
+        return validate_repository(value["nameWithOwner"])
+    raise IssueListError("GitHub returned an issue without a valid repository name.")
+
+
+def normalize_issue(value: Any) -> Issue | None:
+    if not isinstance(value, dict):
+        raise IssueListError("GitHub returned an invalid issue entry.")
+    if value.get("isPullRequest"):
+        return None
+
+    number = value.get("number")
+    title = value.get("title")
+    created_at = value.get("createdAt")
+    if not isinstance(number, int) or isinstance(number, bool):
+        raise IssueListError("GitHub returned an issue without a numeric issue number.")
+    if not isinstance(title, str):
+        raise IssueListError(f"GitHub returned issue #{number} without a valid title.")
+    if not isinstance(created_at, str):
+        raise IssueListError(f"GitHub returned issue #{number} without a valid creation time.")
+
+    return Issue(
+        repository=repository_name(value.get("repository")),
+        number=number,
+        title=title,
+        created_at=parse_github_datetime(created_at),
+    )
+
+
+def fetch_issues(organization: str, username: str) -> list[Issue]:
+    data = run_gh_json(
+        [
+            "search",
+            "issues",
+            "--owner",
+            organization,
+            "--assignee",
+            username,
+            "--state",
+            "open",
+            "--archived=false",
+            "--sort",
+            "created",
+            "--order",
+            "asc",
+            "--limit",
+            str(SEARCH_LIMIT),
+            "--json",
+            "repository,number,title,createdAt,isPullRequest",
+        ]
+    )
+    if not isinstance(data, list):
+        raise IssueListError("Unexpected issue search response from gh.")
+
+    issues = []
+    for value in data:
+        issue = normalize_issue(value)
+        if issue is not None:
+            issues.append(issue)
+    return sorted(issues, key=lambda issue: (issue.created_at, issue.repository, issue.number))
+
+
+def truncate_title(title: str, limit: int = TITLE_LIMIT) -> str:
+    clean = " ".join(title.split())
+    if len(clean) <= limit:
+        return clean
+    if limit <= 3:
+        return clean[:limit]
+    return clean[: limit - 3] + "..."
+
+
+def table(headers: list[str], rows: list[list[str]]) -> str:
+    widths = [len(header) for header in headers]
+    for row in rows:
+        for index, cell in enumerate(row):
+            widths[index] = max(widths[index], len(cell))
+
+    separator = ["-" * width for width in widths]
+    lines = [
+        "| " + " | ".join(header.ljust(widths[index]) for index, header in enumerate(headers)) + " |",
+        "| " + " | ".join(separator[index] for index in range(len(headers))) + " |",
+    ]
+    for row in rows:
+        lines.append("| " + " | ".join(cell.ljust(widths[index]) for index, cell in enumerate(row)) + " |")
+    return "\n".join(lines)
+
+
+def render_issue_table(issues: list[Issue], now: datetime) -> str:
+    if not issues:
+        return "(none found)"
+    rows = [
+        [
+            issue.repository,
+            f"#{issue.number}",
+            truncate_title(issue.title),
+            format_github_datetime(issue.created_at),
+            elapsed_time(issue.created_at, now),
+        ]
+        for issue in issues
+    ]
+    return table(
+        ["Repository", "Issue number", "Issue title", "Creation time", "Time since creation"],
+        rows,
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="List open GitHub issues assigned to a user in an organization.")
+    parser.add_argument(
+        "--organization",
+        default=DEFAULT_ORGANIZATION,
+        help=f"GitHub organization. Default: {DEFAULT_ORGANIZATION}",
+    )
+    parser.add_argument("--username", help="GitHub assignee. Defaults to the authenticated gh user.")
+    return parser
+
+
+def run(argv: list[str]) -> int:
+    args = build_parser().parse_args(argv)
+    organization = validate_name(args.organization, "Organization")
+    require_gh()
+    username = validate_name(args.username, "Username") if args.username else current_username()
+    print(render_issue_table(fetch_issues(organization, username), utc_now()))
+    return 0
+
+
+def main() -> int:
+    try:
+        return run(sys.argv[1:])
+    except IssueListError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+    except OSError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())