github-rest-api 0.42.1__tar.gz → 0.44.0__tar.gz

{github_rest_api-0.42.1/github_rest_api/scripts/github → github_rest_api-0.44.0/.github}/workflows/create_pr_to_main.yaml

@@ -16,5 +16,5 @@ jobs:
           uvx --from github-rest-api@latest create_pull_request \
             --head-branch ${{ github.ref_name }} \
             --base-branch main \
-            --token ${{ secrets.GITHUBACTIONS }}
+            --token ${{ secrets.ACTIONS_TOKEN }}
 

{github_rest_api-0.42.1 → github_rest_api-0.44.0}/.github/workflows/lint.yaml

@@ -14,6 +14,8 @@ jobs:
       run: |
         curl -LsSf https://astral.sh/uv/install.sh | sudo env UV_INSTALL_DIR="/usr/local/bin" sh
         uv sync --all-extras
+    - name: Check pyproject.toml formatting
+      run: uv run pyproject-fmt --check pyproject.toml
     - name: Check code format
       run: uv run ruff format --check ./
     - name: Lint with ruff

{github_rest_api-0.42.1 → github_rest_api-0.44.0}/.github/workflows/remove_branch.yaml

@@ -15,4 +15,4 @@ jobs:
           uvx --from github-rest-api@latest remove_branch \
             --repo ${{ github.repository }} \
             --pattern '^(?!main$)' \
-            --token ${{ secrets.GITHUBACTIONS }}
+            --token ${{ secrets.ACTIONS_TOKEN }}

{github_rest_api-0.42.1 → github_rest_api-0.44.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-rest-api
-Version: 0.42.1
+Version: 0.44.0
 Summary: Simple wrapper of GitHub REST APIs.
 Author-email: Ben Du <longendu@yahoo.com>
 Classifier: Programming Language :: Python :: 3 :: Only
@@ -15,6 +15,8 @@ Requires-Dist: pyyaml>=6
 Requires-Dist: requests>=2.28.2
 Requires-Dist: tenacity>=9.1.4
 Requires-Dist: tomli-w>=1
+Provides-Extra: ai
+Requires-Dist: litellm>=1.50; extra == 'ai'
 Description-Content-Type: text/markdown
 
 # GitHub REST APIs  |  [@GitHub](https://github.com/legendu-net/github_rest_api)  |  [@PyPI](https://pypi.org/project/github-rest-api/)

{github_rest_api-0.42.1 → github_rest_api-0.44.0}/github_rest_api/github.py

@@ -1,5 +1,6 @@
 """Simple wrapper of GitHub REST APIs."""
 
+import logging
 import re
 from abc import ABCMeta, abstractmethod
 from base64 import b64encode
@@ -7,13 +8,23 @@ from collections.abc import Sequence
 from enum import StrEnum
 from pathlib import Path
 from typing import Any, Callable
+from urllib.parse import quote
 
 import requests
 from nacl import encoding, public
 
+from github_rest_api.pr_content import (
+    deterministic_body,
+    deterministic_title,
+    generate_pr_content,
+)
+
+logger = logging.getLogger(__name__)
+
 URL_API = "https://api.github.com"
 
-_SECRET_NAME_PATTERN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+# Default LiteLLM 'provider/model' used to generate PR titles and descriptions.
+DEFAULT_PR_MODEL = "anthropic/claude-haiku-4-5-20251001"
 
 
 def _validate_secret_name(name: str) -> None:
@@ -34,7 +45,7 @@ def _validate_secret_name(name: str) -> None:
             f"Invalid secret name {name!r}: names must not start with the "
             "reserved 'GITHUB_' prefix."
         )
-    if not _SECRET_NAME_PATTERN.fullmatch(name):
+    if not re.fullmatch(r"^[A-Za-z_][A-Za-z0-9_]*$", name):
         raise ValueError(
             f"Invalid secret name {name!r}: names may only contain alphanumeric "
             "characters and underscores, and must not start with a digit."
@@ -192,6 +203,12 @@ class GitHub:
             params["page"] += 1
 
 
+class IssueState(StrEnum):
+    OPEN = "open"
+    CLOSED = "closed"
+    ALL = "all"
+
+
 class Repository(GitHub):
     """Abstraction of a GitHub repository."""
 
@@ -211,6 +228,7 @@ class Repository(GitHub):
         self._url_issues = f"{self._url_repo}/issues"
         self._url_releases = f"{self._url_repo}/releases"
         self._url_secrets = f"{self._url_repo}/actions/secrets"
+        self._url_compare = f"{self._url_repo}/compare"
 
     def get_releases(self, n: int = 0) -> list[dict[str, Any]]:
         """List releases in this repository."""
@@ -270,21 +288,86 @@ class Repository(GitHub):
         """List pull requests in this repository."""
         return self._extract_all(url=self._url_pull, n=n)
 
-    def create_pull_request(self, json: dict[str, str]) -> dict[str, Any] | None:
+    def get_issues(
+        self, state: IssueState = IssueState.OPEN, n: int = 0
+    ) -> list[dict[str, Any]]:
+        """List issues in this repository.
+
+        :param state: Filter issues by state: ``open`` (the default),
+            ``closed``, or ``all``. Note that GitHub's issues endpoint also
+            returns pull requests; each pull request carries a
+            ``pull_request`` key.
+        :param n: The maximum number of issues to return (0 means all).
+        """
+        return self._extract_all(url=self._url_issues, params={"state": state}, n=n)
+
+    def _generate_pull_request_content(
+        self, base: str, head: str, model: str
+    ) -> tuple[str, str] | None:
+        """Generate a `(title, body)` for a new PR from the head/base comparison.
+
+        Returns None when there is nothing to describe (an empty comparison), so
+        the caller keeps the provided title.
+
+        :param base: The base branch the PR merges into.
+        :param head: The head branch containing the changes.
+        :param model: The LiteLLM 'provider/model' string for LLM generation.
+            When empty, the title and body are generated deterministically from
+            the commit messages and changed files; otherwise an LLM is used,
+            falling back to deterministic generation on failure.
+        """
+        compare = self.compare(base=base, head=head)
+        if not compare.get("commits"):
+            return None
+        if model:
+            try:
+                return generate_pr_content(compare, model=model)
+            except Exception as error:
+                logger.warning(
+                    "LLM PR generation failed (%s); "
+                    "falling back to deterministic content.",
+                    error,
+                    exc_info=True,
+                )
+        return deterministic_title(compare), deterministic_body(compare)
+
+    def create_pull_request(
+        self,
+        json: dict[str, str],
+        model: str = "",
+    ) -> dict[str, Any] | None:
         """Create a pull request.
 
+        A Conventional-Commits title and a detailed Markdown body are generated
+        for a newly created PR. A caller-provided 'title' or 'body' in `json`
+        takes precedence; only the missing field(s) are generated. To skip
+        generation entirely, provide both 'title' and 'body' in `json`.
+
         :param json: A dict containing info (e.g., base, head, title, body, etc.)
         about the pull request to be created.
         It's passed to the json parameter of requests.post.
+        :param model: The LiteLLM 'provider/model' string. When empty (the
+            default), missing title/body are generated deterministically from
+            the commit messages and changed files. When non-empty, an LLM is
+            used (with the optional 'ai' extra installed and the matching
+            provider API key read from the environment), falling back to
+            deterministic generation on failure.
         """
         if not ("head" in json and "base" in json):
             raise ValueError("The data dict must contains keys head and base!")
         # return an existing PR
-        prs = self.get_pull_requests()
-        for pr in prs:
+        for pr in self.get_pull_requests():
             if pr["head"]["ref"] == json["head"] and pr["base"]["ref"] == json["base"]:
                 return pr
-        # creat a new PR
+        # generate any title/body not already provided by the caller
+        if "title" not in json or "body" not in json:
+            content = self._generate_pull_request_content(
+                base=json["base"], head=json["head"], model=model
+            )
+            if content is not None:
+                # caller-provided title/body take precedence over generated ones
+                json = {"title": content[0], "body": content[1], **json}
+        # create a new PR
         resp = self._post(
             url=self._url_pull,
             json=json,
@@ -308,11 +391,14 @@ class Repository(GitHub):
         :param update: The branch to update.
         :param upstream: The upstream branch.
         """
+        # Provide a title and an (empty) body so no description is generated for
+        # this mechanical, immediately merged update PR.
         pr = self.create_pull_request(
             {
                 "base": update,
                 "head": upstream,
                 "title": f"Merge {upstream} into {update}",
+                "body": "",
             },
         )
         if pr is None:
@@ -328,6 +414,21 @@ class Repository(GitHub):
         """
         return self._extract_all(url=f"{self._url_pull}/{pr_number}/files", n=n)
 
+    def compare(self, base: str, head: str) -> dict[str, Any]:
+        """Compare two commits/branches in this repository.
+
+        :param base: The base branch (or commit) of the comparison.
+        :param head: The head branch (or commit) of the comparison.
+        :return: The comparison result containing `commits` and `files`
+            (each file with `filename`, `status`, `additions`, `deletions`,
+            and `patch`). See
+            https://docs.github.com/en/rest/commits/commits#compare-two-commits.
+        """
+        # Branch names may contain slashes, so each ref is URL-encoded while the
+        # literal `...` separator between them is preserved.
+        basehead = f"{quote(base, safe='')}...{quote(head, safe='')}"
+        return self._get(url=f"{self._url_compare}/{basehead}").json()
+
     def get_branches(self, n: int = 0) -> list[dict[str, Any]]:
         """List branches in this repository."""
         return self._extract_all(url=self._url_branches, n=n)
@@ -417,6 +518,14 @@ class Repository(GitHub):
         """
         return self.pr_has_change(pr_number=pr_number, pred=pred)
 
+    def get_issue_comments(self, issue_number: int, n: int = 0) -> list[dict[str, Any]]:
+        """List comments on an issue in this repository.
+
+        :param issue_number: The number of the issue.
+        :param n: The maximum number of comments to return (0 means all).
+        """
+        return self._extract_all(url=f"{self._url_issues}/{issue_number}/comments", n=n)
+
     def create_issue_comment(self, issue_number: int, body: str) -> dict[str, Any]:
         """Add a new comment to an issue.
 

github_rest_api-0.44.0/github_rest_api/pr_content.py

@@ -0,0 +1,227 @@
+"""Generate pull request titles and descriptions from a comparison result.
+
+The functions here operate on the JSON returned by the GitHub "compare two
+commits" endpoint (see `Repository.compare`). They provide two layers:
+
+- A deterministic layer (`deterministic_title` / `deterministic_body`) that
+  derives a Conventional-Commits title and a Markdown body purely from commit
+  messages and changed files. It has no extra dependencies and is always
+  available.
+- An optional AI layer (`generate_pr_content`) that uses LiteLLM to produce a
+  richer title and description. It raises on any failure (missing `litellm`,
+  missing provider key, malformed reply) so the caller can fall back to the
+  deterministic layer.
+"""
+
+import json
+import re
+from collections import Counter
+from typing import Any, cast
+
+_CONVENTIONAL_PATTERN = re.compile(
+    r"^(?P<type>feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)"
+    r"(?:\((?P<scope>[^)]+)\))?(?P<breaking>!)?: (?P<description>.+)$"
+)
+# The Conventional Commits spec allows the breaking-change footer token to be
+# spelled either "BREAKING CHANGE" or "BREAKING-CHANGE".
+_BREAKING_CHANGE_PATTERN = re.compile(r"BREAKING[ -]CHANGE")
+
+
+def parse_conventional(subject: str) -> tuple[str, str | None, bool, str] | None:
+    """Parse a Conventional-Commits subject line.
+
+    :param subject: The first line of a commit message.
+    :return: A `(type, scope, breaking, description)` tuple, or None when the
+        subject does not follow the Conventional-Commits grammar.
+    """
+    match = _CONVENTIONAL_PATTERN.match(subject)
+    if match is None:
+        return None
+    return (
+        match["type"],
+        match["scope"],
+        bool(match["breaking"]),
+        match["description"],
+    )
+
+
+def _commit_messages(compare: dict[str, Any], skip_merges: bool = True) -> list[str]:
+    """Extract commit messages from a comparison result.
+
+    :param compare: The comparison result from `Repository.compare`.
+    :param skip_merges: Whether to skip merge commits (subjects starting with
+        ``Merge ``).
+    """
+    messages = []
+    for commit in compare.get("commits") or []:
+        message = (commit.get("commit") or {}).get("message", "")
+        if not message:
+            continue
+        subject = message.splitlines()[0].strip()
+        if skip_merges and subject.startswith("Merge "):
+            continue
+        messages.append(message)
+    return messages
+
+
+def _common_scope(compare: dict[str, Any]) -> str | None:
+    """Derive a Conventional-Commits scope from the changed files.
+
+    The scope is the common top-level directory shared by every changed file,
+    or None when the files do not share one (or live at the repository root).
+    """
+    filenames = [
+        file["filename"] for file in compare.get("files") or [] if file.get("filename")
+    ]
+    if not filenames or not all("/" in name for name in filenames):
+        return None
+    segments = {name.split("/", 1)[0] for name in filenames}
+    return next(iter(segments)) if len(segments) == 1 else None
+
+
+def deterministic_title(compare: dict[str, Any]) -> str:
+    """Derive a Conventional-Commits title from a comparison result.
+
+    The type is the most significant type present across the commits
+    (``feat`` > ``fix`` > the most frequent parsed type > ``chore``); the scope
+    is the common top-level directory of the changed files; ``!`` is appended
+    for breaking changes.
+
+    :param compare: The comparison result from `Repository.compare`.
+    """
+    messages = _commit_messages(compare)
+    subjects = [message.splitlines()[0].strip() for message in messages]
+    parsed = [parse_conventional(subject) for subject in subjects]
+    types = [item[0] for item in parsed if item]
+    scope = _common_scope(compare)
+    prefix_scope = f"({scope})" if scope else ""
+    if not subjects:
+        return f"chore{prefix_scope}: update"
+    if "feat" in types:
+        type_ = "feat"
+    elif "fix" in types:
+        type_ = "fix"
+    elif types:
+        type_ = Counter(types).most_common(1)[0][0]
+    else:
+        type_ = "chore"
+    breaking = any(item[2] for item in parsed if item) or any(
+        _BREAKING_CHANGE_PATTERN.search(message) for message in messages
+    )
+    if len(subjects) == 1:
+        description = parsed[0][3] if parsed[0] else subjects[0]
+    else:
+        description = next(
+            (item[3] for item in parsed if item and item[0] == type_),
+            f"update {len(subjects)} commits",
+        )
+    return f"{type_}{prefix_scope}{'!' if breaking else ''}: {description}"
+
+
+def deterministic_body(compare: dict[str, Any]) -> str:
+    """Build a Markdown PR body from a comparison result.
+
+    :param compare: The comparison result from `Repository.compare`.
+    """
+    sections = []
+    subjects = [
+        message.splitlines()[0].strip() for message in _commit_messages(compare)
+    ]
+    if subjects:
+        summary = "\n".join(f"- {subject}" for subject in subjects)
+        sections.append(f"## Summary\n\n{summary}")
+    files = compare.get("files") or []
+    if files:
+        # Conventional-Commit statuses ordered for a stable, readable "Changed
+        # files" section. Any status not listed is appended afterwards.
+        status_order = ("added", "modified", "removed", "renamed", "copied", "changed")
+        by_status: dict[str, list[dict[str, Any]]] = {}
+        for file in files:
+            by_status.setdefault(file.get("status") or "modified", []).append(file)
+        ordered = [status for status in status_order if status in by_status]
+        ordered += [status for status in by_status if status not in status_order]
+        lines = []
+        for status in ordered:
+            lines.append(f"**{status.capitalize()}**")
+            for file in by_status[status]:
+                lines.append(
+                    f"- `{file.get('filename', '')}` "
+                    f"(+{file.get('additions', 0)}/-{file.get('deletions', 0)})"
+                )
+        sections.append("## Changed files\n\n" + "\n".join(lines))
+    commits = compare.get("commits") or []
+    if commits:
+        lines = []
+        for commit in commits:
+            sha = (commit.get("sha") or "")[:7]
+            message = (commit.get("commit") or {}).get("message", "")
+            subject = message.splitlines()[0].strip() if message else ""
+            lines.append(f"- {sha} {subject}")
+        sections.append("## Commits\n\n" + "\n".join(lines))
+    return "\n\n".join(sections)
+
+
+def summarize_for_ai(compare: dict[str, Any], max_chars: int = 12000) -> str:
+    """Assemble a compact, size-capped context for the AI prompt.
+
+    Combines the deterministic body with per-file patches, truncating once the
+    character budget is exhausted so very large diffs do not blow up the prompt.
+
+    :param compare: The comparison result from `Repository.compare`.
+    :param max_chars: The approximate maximum size of the returned context.
+    """
+    parts = [deterministic_body(compare), "## Diff"]
+    budget = max_chars - sum(len(part) for part in parts)
+    for file in compare.get("files") or []:
+        patch = file.get("patch")
+        if not patch:
+            continue
+        chunk = f"### {file.get('filename', '')}\n{patch}"
+        if len(chunk) > budget:
+            parts.append("<remaining patches omitted: size limit reached>")
+            break
+        parts.append(chunk)
+        budget -= len(chunk)
+    return "\n\n".join(parts)
+
+
+def generate_pr_content(compare: dict[str, Any], model: str) -> tuple[str, str]:
+    """Generate a PR title and body with an LLM via LiteLLM.
+
+    :param compare: The comparison result from `Repository.compare`.
+    :param model: A LiteLLM ``provider/model`` string (e.g.
+        ``anthropic/claude-haiku-4-5-20251001``, ``gemini/gemini-2.5-flash``).
+        The matching provider API key is read from the environment by LiteLLM.
+    :return: A `(title, body)` tuple.
+    :raises Exception: If LiteLLM is not installed, no provider key is set, the
+        request fails, or the reply cannot be parsed. The caller is expected to
+        fall back to the deterministic layer.
+    """
+    import litellm
+
+    prompt = (
+        "You are writing a GitHub pull request from the changes below. "
+        "Respond with a JSON object containing exactly two string keys: "
+        "'title' and 'body'. The 'title' must be a single concise line "
+        "following the Conventional Commits specification "
+        "(e.g. 'feat(scope): summary'). The 'body' must be GitHub-flavored "
+        "Markdown describing the motivation and the key changes.\n\n"
+        f"{summarize_for_ai(compare)}"
+    )
+    response = litellm.completion(
+        model=model,
+        messages=[{"role": "user", "content": prompt}],
+        response_format={"type": "json_object"},
+        # Drop response_format for providers that do not support it rather than
+        # erroring; the prompt already requests JSON, so parsing still works.
+        drop_params=True,
+    )
+    response_any = cast(Any, response)
+    data = json.loads(response_any["choices"][0]["message"]["content"])
+    if not isinstance(data, dict):
+        raise ValueError("The model did not return a JSON object.")
+    title = str(data.get("title") or "").strip()
+    body = str(data.get("body") or "").strip()
+    if not title or not body:
+        raise ValueError("The model returned an empty title or body.")
+    return title, body

{github_rest_api-0.42.1 → github_rest_api-0.44.0}/github_rest_api/scripts/github/create_pull_request.py

@@ -7,6 +7,7 @@ import sys
 from argparse import ArgumentParser, Namespace
 
 from github_rest_api import Repository
+from github_rest_api.github import DEFAULT_PR_MODEL
 from github_rest_api.utils import compile_patterns
 
 
@@ -36,6 +37,20 @@ def parse_args(args=None, namespace=None) -> Namespace:
         required=True,
         help="The base branch to merge changes into.",
     )
+    parser.add_argument(
+        "--title",
+        dest="title",
+        default="",
+        help="The title of the pull request. Takes precedence over a generated "
+        "title and the default 'Merge <head> Into <base>' title.",
+    )
+    parser.add_argument(
+        "--body",
+        dest="body",
+        default="",
+        help="The body (description) of the pull request. Takes precedence over "
+        "a generated description.",
+    )
     parser.add_argument(
         "--ignore-patterns",
         dest="ignore_patterns",
@@ -49,6 +64,16 @@ def parse_args(args=None, namespace=None) -> Namespace:
         action="store_true",
         help="Update the head branch using the base branch before creating the pull request.",
     )
+    parser.add_argument(
+        "--model",
+        dest="model",
+        default="",
+        help="The LiteLLM 'provider/model' string for generating the title and "
+        f"description with an LLM (e.g. '{DEFAULT_PR_MODEL}' or "
+        "'gemini/gemini-2.5-flash'); the matching provider API key is read from "
+        "the environment. When omitted, the title and description are generated "
+        "deterministically from the commit messages and changed files.",
+    )
     return parser.parse_args(args=args, namespace=namespace)
 
 
@@ -75,13 +100,17 @@ def main() -> int:
     repo = Repository(args.token, os.environ["GITHUB_REPOSITORY"])
     if args.update:
         repo.update_branch(update=args.head_branch, upstream=args.base_branch)
-    repo.create_pull_request(
-        {
-            "base": args.base_branch,
-            "head": args.head_branch,
-            "title": f"Merge {args.head_branch} Into {args.base_branch}",
-        },
-    )
+    pull_request = {
+        "base": args.base_branch,
+        "head": args.head_branch,
+    }
+    if args.title:
+        pull_request["title"] = args.title
+    if args.body:
+        pull_request["body"] = args.body
+    # An empty model generates the title/body deterministically; a --model uses
+    # an LLM (falling back to deterministic generation on failure).
+    repo.create_pull_request(pull_request, model=args.model)
     return 0
 
 

{github_rest_api-0.42.1 → github_rest_api-0.44.0}/pyproject.toml

@@ -4,7 +4,7 @@ requires = [ "hatchling" ]
 
 [project]
 name = "github-rest-api"
-version = "0.42.1"
+version = "0.44.0"
 description = "Simple wrapper of GitHub REST APIs."
 readme = "README.md"
 authors = [ { name = "Ben Du", email = "longendu@yahoo.com" } ]
@@ -24,6 +24,9 @@ dependencies = [
   "tenacity>=9.1.4",
   "tomli-w>=1",
 ]
+optional-dependencies.ai = [
+  "litellm>=1.50",
+]
 scripts.add_github_repo = "github_rest_api.scripts.github.add_github_repo:main"
 scripts.build_container_images = "github_rest_api.scripts.container.build_container_images:main"
 scripts.config_container = "github_rest_api.scripts.container.config_container:main"
@@ -42,7 +45,6 @@ dev = [
   "ty>=0.0.8",
 ]
 
-[tool.ruff.lint]
+[tool.ruff]
 # select the 'I' rule set for import sorting
-extend-select = ["I"]
-
+lint.extend-select = [ "I" ]

github_rest_api-0.44.0/tests/test_create_pull_request.py

@@ -0,0 +1,55 @@
+import sys
+from unittest.mock import MagicMock, patch
+
+from github_rest_api.scripts.github import create_pull_request
+
+
+def test_parse_args_defaults():
+    args = create_pull_request.parse_args(
+        ["--token", "t", "--head-branch", "dev", "--base-branch", "main"]
+    )
+    assert args.title == ""
+    assert args.body == ""
+    # No model by default, so generation is deterministic.
+    assert args.model == ""
+
+
+def _run_main(monkeypatch, extra_argv):
+    argv = [
+        "create_pull_request",
+        "--token",
+        "t",
+        "--head-branch",
+        "dev",
+        "--base-branch",
+        "main",
+        *extra_argv,
+    ]
+    monkeypatch.setattr(sys, "argv", argv)
+    monkeypatch.setenv("GITHUB_REPOSITORY", "owner/name")
+    repo = MagicMock()
+    with patch.object(create_pull_request, "Repository", return_value=repo):
+        assert create_pull_request.main() == 0
+    return repo.create_pull_request.call_args
+
+
+def test_main_passes_title_and_body(monkeypatch):
+    call = _run_main(monkeypatch, ["--title", "My Title", "--body", "My Body"])
+    sent = call.args[0]
+    assert sent["title"] == "My Title"
+    assert sent["body"] == "My Body"
+
+
+def test_main_without_options_defaults_to_deterministic(monkeypatch):
+    call = _run_main(monkeypatch, [])
+    sent = call.args[0]
+    # No title/body are set here; create_pull_request generates them
+    # deterministically (empty model).
+    assert "title" not in sent
+    assert "body" not in sent
+    assert call.kwargs["model"] == ""
+
+
+def test_main_with_model_uses_llm(monkeypatch):
+    call = _run_main(monkeypatch, ["--model", "gemini/g"])
+    assert call.kwargs["model"] == "gemini/g"