github-rest-api 0.48.0__py3-none-any.whl → 0.49.0__py3-none-any.whl

github_rest_api/__init__.py

@@ -1,19 +1,27 @@
 """GitHub REST APIs."""
 
 from .github import (
+    UNSET,
+    IssueState,
+    IssueStateReason,
     MergeMethod,
     Organization,
     Repository,
     RepositoryType,
     SecretVisibility,
+    Unset,
     User,
 )
 
 __all__ = [
+    "UNSET",
+    "IssueState",
+    "IssueStateReason",
     "MergeMethod",
     "Organization",
     "Repository",
     "RepositoryType",
     "SecretVisibility",
+    "Unset",
     "User",
 ]

github_rest_api/github.py

@@ -20,11 +20,18 @@ from github_rest_api.pr_content import (
     deterministic_title,
     generate_pr_content,
 )
+from github_rest_api.utils import as_str_sequence
 
 logger = logging.getLogger(__name__)
 
 URL_API = "https://api.github.com"
 
+# Default connect/read timeout (in seconds) for a GitHub REST API request. It is a
+# per-socket-operation deadline rather than a total-transfer one, so a slow but
+# progressing response is not cut off. Callers may pass their own `timeout` to any
+# of the request helpers, but never `None`: see `_apply_timeout`.
+DEFAULT_TIMEOUT = 10
+
 # Default LiteLLM 'provider/model' used to generate PR titles and descriptions.
 DEFAULT_PR_MODEL = "anthropic/claude-haiku-4-5-20251001"
 
@@ -66,6 +73,25 @@ def _validate_secret_name(name: str) -> None:
         )
 
 
+def _apply_timeout(kwargs: dict[str, Any]) -> None:
+    """Apply the default request timeout in place, rejecting an infinite one.
+
+    `requests` treats `timeout=None` as "wait forever", which can hang a caller
+    indefinitely on an unresponsive endpoint. No GitHub REST API call is worth
+    that, so `None` is rejected rather than silently replaced: a caller that
+    passed it meant to disable the deadline and should say what it wants instead.
+
+    :param kwargs: Keyword arguments destined for a `requests` call. A `timeout`
+        entry is added when absent; any other entry is left untouched.
+    :raises ValueError: If `timeout` is explicitly None.
+    """
+    if kwargs.setdefault("timeout", DEFAULT_TIMEOUT) is None:
+        raise ValueError(
+            "timeout=None would wait indefinitely; pass a positive number of "
+            f"seconds, or omit timeout to use the default of {DEFAULT_TIMEOUT}."
+        )
+
+
 def _encrypt_secret(public_key: str, value: str) -> str:
     """Encrypt a secret value using a LibSodium sealed box.
     :param public_key: The base64-encoded public key to encrypt against.
@@ -284,12 +310,13 @@ class GitHub:
         :param url: The endpoint URL to request.
         :param raise_for_status: Whether to raise on a non-2xx response.
         :param kwargs: Additional keyword arguments (e.g. `params`) forwarded
-            to `requests.get`.
+            to `requests.get`. `timeout` defaults to `DEFAULT_TIMEOUT`
+            seconds and must not be None (see `_apply_timeout`).
         """
+        _apply_timeout(kwargs)
         resp = requests.get(
             url=url,
             headers=self._headers,
-            timeout=10,
             **kwargs,
         )
         if raise_for_status:
@@ -304,22 +331,37 @@ class GitHub:
         :param headers: Request headers; defaults to the standard auth headers.
         :param raise_for_status: Whether to raise on a non-2xx response.
         :param kwargs: Additional keyword arguments (e.g. `json`) forwarded
-            to `requests.post`.
+            to `requests.post`. `timeout` defaults to `DEFAULT_TIMEOUT`
+            seconds and must not be None (see `_apply_timeout`).
         """
         if headers is None:
             headers = self._headers
+        _apply_timeout(kwargs)
         resp = requests.post(
             url=url,
             headers=headers,
-            timeout=10,
             **kwargs,
         )
         if raise_for_status:
             resp.raise_for_status()
         return resp
 
-    def _delete(self, url, raise_for_status: bool = True) -> requests.Response:
-        resp = requests.delete(url=url, headers=self._headers, timeout=10)
+    def _delete(
+        self, url, raise_for_status: bool = True, **kwargs
+    ) -> requests.Response:
+        """Send a DELETE request to a GitHub REST API endpoint.
+        :param url: The endpoint URL to request.
+        :param raise_for_status: Whether to raise on a non-2xx response.
+        :param kwargs: Additional keyword arguments (e.g. `json`) forwarded
+            to `requests.delete`. `timeout` defaults to `DEFAULT_TIMEOUT`
+            seconds and must not be None (see `_apply_timeout`).
+        """
+        _apply_timeout(kwargs)
+        resp = requests.delete(
+            url=url,
+            headers=self._headers,
+            **kwargs,
+        )
         if raise_for_status:
             resp.raise_for_status()
         return resp
@@ -331,12 +373,13 @@ class GitHub:
         :param url: The endpoint URL to request.
         :param raise_for_status: Whether to raise on a non-2xx response.
         :param kwargs: Additional keyword arguments (e.g. `json`) forwarded
-            to `requests.put`.
+            to `requests.put`. `timeout` defaults to `DEFAULT_TIMEOUT`
+            seconds and must not be None (see `_apply_timeout`).
         """
+        _apply_timeout(kwargs)
         resp = requests.put(
             url=url,
             headers=self._headers,
-            timeout=10,
             **kwargs,
         )
         if raise_for_status:
@@ -348,12 +391,13 @@ class GitHub:
         :param url: The endpoint URL to request.
         :param raise_for_status: Whether to raise on a non-2xx response.
         :param kwargs: Additional keyword arguments (e.g. `json`) forwarded
-            to `requests.patch`.
+            to `requests.patch`. `timeout` defaults to `DEFAULT_TIMEOUT`
+            seconds and must not be None (see `_apply_timeout`).
         """
+        _apply_timeout(kwargs)
         resp = requests.patch(
             url=url,
             headers=self._headers,
-            timeout=10,
             **kwargs,
         )
         if raise_for_status:
@@ -398,12 +442,56 @@ class IssueState(StrEnum):
     ALL = "all"
 
 
+class IssueStateReason(StrEnum):
+    """Why an issue was closed or reopened, accompanying an ``IssueState``."""
+
+    COMPLETED = "completed"
+    NOT_PLANNED = "not_planned"
+    DUPLICATE = "duplicate"
+    REOPENED = "reopened"
+
+
 class MergeMethod(StrEnum):
     MERGE = "merge"
     SQUASH = "squash"
     REBASE = "rebase"
 
 
+class Unset:
+    """The type of :data:`UNSET`."""
+
+    def __repr__(self) -> str:
+        return "UNSET"
+
+
+# Sentinel marking an update field the caller did not mention, so that a field
+# left out is distinguishable from one explicitly set to an empty/null value.
+# `None` cannot serve as that marker because GitHub gives it a meaning of its
+# own: `{"milestone": None}` detaches the milestone, while omitting the key
+# leaves it alone. See `Repository.update_issue`.
+UNSET = Unset()
+
+
+def _validate_issue_state(state: str, noun: str = "issue") -> None:
+    """Validate a state an issue or milestone can be *set* to.
+
+    ``IssueState.ALL`` is a filter for listing, not a state anything can hold;
+    GitHub rejects it with a 422. It is caught here so the mistake is reported
+    against the argument rather than as an opaque HTTP error.
+
+    :param state: The state to set (``open`` or ``closed``).
+    :param noun: What is being updated, for the error message.
+    :raises ValueError: If the state is anything other than open or closed.
+    """
+    if state not in (IssueState.OPEN, IssueState.CLOSED):
+        # `str(state)` so a StrEnum renders as 'all' rather than
+        # <IssueState.ALL: 'all'>, matching how a plain string argument reads.
+        raise ValueError(
+            f"Invalid {noun} state {str(state)!r}: a {noun} can only be set to "
+            f"'{IssueState.OPEN}' or '{IssueState.CLOSED}'."
+        )
+
+
 class Repository(GitHub):
     """Abstraction of a GitHub repository."""
 
@@ -421,6 +509,10 @@ class Repository(GitHub):
         self._url_branches = f"{self._url_repo}/branches"
         self._url_refs = f"{self._url_repo}/git/refs"
         self._url_issues = f"{self._url_repo}/issues"
+        # Issue comments are edited/deleted by comment id, not issue number, so
+        # this endpoint is not nested under a specific issue.
+        self._url_issue_comments = f"{self._url_issues}/comments"
+        self._url_milestones = f"{self._url_repo}/milestones"
         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"
@@ -505,6 +597,28 @@ class Repository(GitHub):
         """
         return self._extract_all(url=f"{self._url_pull}/{pr_number}/reviews", n=n)
 
+    def get_pull_request_review_comments(
+        self, pr_number: int, n: int = 0
+    ) -> list[dict[str, Any]]:
+        """List the review comments on a pull request.
+
+        These are the line-anchored comments left on the diff, each carrying
+        ``path``, ``line``/``original_line`` and ``diff_hunk``, and grouped into
+        threads via ``in_reply_to_id``. They are a different resource from the
+        conversation-level comments returned by ``get_issue_comments``, which the
+        pull request shares with its issue; a full picture of a PR's discussion
+        needs both.
+
+        Every review comment is listed, whether it belongs to a submitted review
+        or was posted as a standalone comment. Comments still pending in an
+        unsubmitted review are not visible to anyone but their author, so they
+        are absent.
+
+        :param pr_number: The number of the pull request.
+        :param n: The maximum number of review comments to return (0 means all).
+        """
+        return self._extract_all(url=f"{self._url_pull}/{pr_number}/comments", n=n)
+
     def get_issues(
         self, state: IssueState = IssueState.OPEN, n: int = 0
     ) -> list[dict[str, Any]]:
@@ -550,7 +664,7 @@ class Repository(GitHub):
 
     def create_pull_request(
         self,
-        json: dict[str, str],
+        json: dict[str, Any],
         model: str = "",
     ) -> dict[str, Any] | None:
         """Create a pull request.
@@ -598,7 +712,7 @@ class Repository(GitHub):
     def merge_pull_request(
         self,
         pr_number: int,
-        merge_method: MergeMethod | str = MergeMethod.MERGE,
+        merge_method: MergeMethod = MergeMethod.MERGE,
         sha: str = "",
     ) -> dict[str, Any]:
         """Merge a pull request in this repository.
@@ -662,9 +776,9 @@ class Repository(GitHub):
         self,
         pr_number: int,
         *,
-        authors: Sequence[str],
-        approvers: Sequence[str],
-        allowed_types: Sequence[str] = DEFAULT_AUTO_MERGE_TYPES,
+        authors: str | Sequence[str],
+        approvers: str | Sequence[str],
+        allowed_types: str | Sequence[str] = DEFAULT_AUTO_MERGE_TYPES,
         min_age_minutes: int = DEFAULT_MIN_AGE_MINUTES,
         marker: str = DEFAULT_AUTO_MERGE_MARKER,
     ) -> str | None:
@@ -687,9 +801,12 @@ class Repository(GitHub):
         the first failure so extra requests are avoided.
 
         :param pr_number: The number of the pull request.
-        :param authors: Logins whose PRs are eligible for auto-merge.
-        :param approvers: Logins whose reviews/marker comments grant approval.
-        :param allowed_types: Conventional-Commits title types eligible for auto-merge.
+        :param authors: Logins whose PRs are eligible for auto-merge, or a
+            single login as a bare string.
+        :param approvers: Logins whose reviews/marker comments grant approval,
+            or a single login as a bare string.
+        :param allowed_types: Conventional-Commits title types eligible for
+            auto-merge, or a single type as a bare string.
         :param min_age_minutes: The minimum head-commit age in minutes.
         :param marker: The marker substring an approver may comment to approve.
         :return: The validated head SHA when the PR is eligible, else ``None``.
@@ -697,6 +814,9 @@ class Repository(GitHub):
             commit checked here, so a push landing between this gate and the merge
             is rejected rather than silently merged.
         """
+        authors = as_str_sequence(authors)
+        approvers = as_str_sequence(approvers)
+        allowed_types = as_str_sequence(allowed_types)
         pr = self.get_pull_request(pr_number)
 
         def skip(reason: str) -> None:
@@ -735,20 +855,23 @@ class Repository(GitHub):
     def auto_merge_pull_requests(
         self,
         *,
-        authors: Sequence[str],
-        approvers: Sequence[str],
-        allowed_types: Sequence[str] = DEFAULT_AUTO_MERGE_TYPES,
+        authors: str | Sequence[str],
+        approvers: str | Sequence[str],
+        allowed_types: str | Sequence[str] = DEFAULT_AUTO_MERGE_TYPES,
         min_age_minutes: int = DEFAULT_MIN_AGE_MINUTES,
         marker: str = DEFAULT_AUTO_MERGE_MARKER,
-        merge_method: MergeMethod | str = MergeMethod.MERGE,
+        merge_method: MergeMethod = MergeMethod.MERGE,
         dry_run: bool = False,
     ) -> list[int]:
         """Auto-merge every open pull request that passes ``should_auto_merge``.
 
-        :param authors: Logins whose PRs are eligible for auto-merge. An empty
-            allowlist makes nothing eligible (fail-safe).
-        :param approvers: Logins whose reviews/marker comments grant approval.
-        :param allowed_types: Conventional-Commits title types eligible for auto-merge.
+        :param authors: Logins whose PRs are eligible for auto-merge, or a
+            single login as a bare string. An empty allowlist makes nothing
+            eligible (fail-safe).
+        :param approvers: Logins whose reviews/marker comments grant approval,
+            or a single login as a bare string.
+        :param allowed_types: Conventional-Commits title types eligible for
+            auto-merge, or a single type as a bare string.
         :param min_age_minutes: The minimum head-commit age in minutes.
         :param marker: The marker substring an approver may comment to approve.
         :param merge_method: The merge method to use (``merge``, ``squash`` or
@@ -758,6 +881,9 @@ class Repository(GitHub):
         :return: The numbers of the PRs that were merged (or, under ``dry_run``,
             that would have been merged).
         """
+        authors = as_str_sequence(authors)
+        approvers = as_str_sequence(approvers)
+        allowed_types = as_str_sequence(allowed_types)
         eligible = []
         for pr in self.get_pull_requests():
             number = pr["number"]
@@ -937,6 +1063,389 @@ class Repository(GitHub):
         """
         return self.pr_has_change(pr_number=pr_number, pred=pred)
 
+    def create_issue(
+        self,
+        title: str,
+        body: str = "",
+        labels: str | Sequence[str] = (),
+        assignees: str | Sequence[str] = (),
+        milestone: int | None = None,
+    ) -> dict[str, Any]:
+        """Create an issue in this repository.
+
+        :param title: The title of the new issue.
+        :param body: The Markdown body of the new issue.
+        :param labels: Names of labels to attach to the new issue, or a single
+            name as a bare string. Silently dropped unless the authenticated
+            user has push access to the repository. Labels that do not already
+            exist are created by GitHub.
+        :param assignees: Logins of users to assign to the new issue, or a
+            single login as a bare string. Silently dropped unless the
+            authenticated user has push access to the repository.
+        :param milestone: The number of the milestone to associate the new issue
+            with (see ``get_milestones``). Silently dropped unless the
+            authenticated user has push access to the repository.
+        """
+        labels = as_str_sequence(labels)
+        assignees = as_str_sequence(assignees)
+        json: dict[str, Any] = {"title": title}
+        if body:
+            json["body"] = body
+        if labels:
+            json["labels"] = list(labels)
+        if assignees:
+            json["assignees"] = list(assignees)
+        if milestone is not None:
+            json["milestone"] = milestone
+        return self._post(url=self._url_issues, json=json).json()
+
+    def get_issue(self, issue_number: int) -> dict[str, Any]:
+        """Get a single issue in this repository.
+
+        :param issue_number: The number of the issue. A pull request number is
+            also accepted, since GitHub models pull requests as issues; the
+            payload then carries a ``pull_request`` key.
+        """
+        return self._get(url=f"{self._url_issues}/{issue_number}").json()
+
+    def update_issue(
+        self,
+        issue_number: int,
+        *,
+        title: str | Unset = UNSET,
+        body: str | Unset = UNSET,
+        state: IssueState | Unset = UNSET,
+        state_reason: IssueStateReason | None | Unset = UNSET,
+        duplicate_issue_id: int | Unset = UNSET,
+        labels: str | Sequence[str] | Unset = UNSET,
+        assignees: str | Sequence[str] | Unset = UNSET,
+        milestone: int | None | Unset = UNSET,
+    ) -> dict[str, Any]:
+        """Update an issue in this repository.
+
+        Only the fields passed are sent, so an update never disturbs a field the
+        caller did not mention. That distinction is what the ``UNSET`` default
+        buys: ``None`` and the empty sequence are meaningful values here (they
+        detach the milestone and clear the labels/assignees respectively), so
+        they cannot double as "leave this alone".
+
+        ``labels`` and ``assignees`` replace the existing set rather than adding
+        to it; to add or remove a few entries without knowing the rest, use
+        ``add_issue_labels``/``remove_issue_label`` or
+        ``add_issue_assignees``/``remove_issue_assignees``.
+
+        :param issue_number: The number of the issue.
+        :param title: A new title.
+        :param body: A new Markdown body; pass ``""`` to empty it.
+        :param state: ``open`` or ``closed`` (see also ``close_issue``).
+        :param state_reason: Why the issue is in that state (``completed``,
+            ``not_planned``, ``duplicate`` or ``reopened``), or None to clear it.
+            It must be passed alongside ``state``, and GitHub applies it only
+            when the state actually changes: re-closing an already-closed issue
+            keeps the reason it was closed with.
+        :param duplicate_issue_id: The id (not the number) of the issue this one
+            duplicates. GitHub requires it when ``state_reason`` is ``duplicate``
+            and ignores it otherwise, so the two must be passed together.
+        :param labels: Names of the labels the issue should carry, replacing any
+            current ones; a bare string is one label, and an empty sequence
+            clears them all. Labels that do not already exist are created.
+        :param assignees: Logins the issue should be assigned to, replacing any
+            current ones; a bare string is one login, and an empty sequence
+            unassigns everyone.
+        :param milestone: The number of the milestone to associate the issue
+            with; pass None to detach it.
+        :raises ValueError: If no field is given (the request would be a no-op),
+            if ``state`` is neither open nor closed, if ``state_reason`` is given
+            without ``state``, or if ``state_reason='duplicate'`` and
+            ``duplicate_issue_id`` are not given together.
+        """
+        # GitHub documents state_reason as "ignored unless state is changed", so
+        # sending it alone silently does nothing. Refuse it rather than let the
+        # caller believe an update happened.
+        if isinstance(state, Unset) and not isinstance(state_reason, Unset):
+            raise ValueError(
+                "state_reason is ignored by GitHub unless state changes too; "
+                "pass state (e.g. IssueState.CLOSED) alongside it."
+            )
+        # `duplicate` and `duplicate_issue_id` are only meaningful together:
+        # without the id GitHub rejects the request, and without the reason it
+        # drops the id. Comparison is by value so an equivalent plain string
+        # still takes this path, as it does everywhere else a state is checked.
+        is_duplicate = (
+            not isinstance(state_reason, Unset)
+            and state_reason is not None
+            and str(state_reason) == IssueStateReason.DUPLICATE
+        )
+        if is_duplicate and isinstance(duplicate_issue_id, Unset):
+            raise ValueError(
+                "state_reason='duplicate' requires duplicate_issue_id, the id "
+                "of the issue this one duplicates."
+            )
+        if not is_duplicate and not isinstance(duplicate_issue_id, Unset):
+            raise ValueError(
+                "duplicate_issue_id is ignored by GitHub unless state_reason is "
+                "'duplicate'; pass IssueStateReason.DUPLICATE alongside it."
+            )
+        json: dict[str, Any] = {}
+        if not isinstance(title, Unset):
+            json["title"] = title
+        if not isinstance(body, Unset):
+            json["body"] = body
+        if not isinstance(state, Unset):
+            _validate_issue_state(state)
+            json["state"] = str(state)
+        if not isinstance(state_reason, Unset):
+            json["state_reason"] = None if state_reason is None else str(state_reason)
+        if not isinstance(duplicate_issue_id, Unset):
+            json["duplicate_issue_id"] = duplicate_issue_id
+        if not isinstance(labels, Unset):
+            json["labels"] = list(as_str_sequence(labels))
+        if not isinstance(assignees, Unset):
+            json["assignees"] = list(as_str_sequence(assignees))
+        if not isinstance(milestone, Unset):
+            json["milestone"] = milestone
+        if not json:
+            raise ValueError(
+                f"No field to update was given for issue #{issue_number}; "
+                "pass at least one of title, body, state, state_reason, "
+                "labels, assignees or milestone."
+            )
+        return self._patch(url=f"{self._url_issues}/{issue_number}", json=json).json()
+
+    def close_issue(
+        self,
+        issue_number: int,
+        state_reason: IssueStateReason = IssueStateReason.COMPLETED,
+        duplicate_issue_id: int | Unset = UNSET,
+    ) -> dict[str, Any]:
+        """Close an issue in this repository.
+
+        Closing an already-closed issue is not an error, but it is not a state
+        change either, so GitHub keeps the existing ``state_reason``. Reopen the
+        issue first to re-close it with a different reason.
+
+        :param issue_number: The number of the issue.
+        :param state_reason: Why the issue is being closed (``completed``, the
+            default, ``not_planned`` or ``duplicate``).
+        :param duplicate_issue_id: The id (not the number) of the issue this one
+            duplicates. Required when ``state_reason`` is ``duplicate``, and
+            rejected otherwise (see ``update_issue``).
+        """
+        return self.update_issue(
+            issue_number,
+            state=IssueState.CLOSED,
+            state_reason=state_reason,
+            duplicate_issue_id=duplicate_issue_id,
+        )
+
+    def reopen_issue(self, issue_number: int) -> dict[str, Any]:
+        """Reopen a closed issue in this repository.
+
+        :param issue_number: The number of the issue.
+        """
+        return self.update_issue(
+            issue_number, state=IssueState.OPEN, state_reason=IssueStateReason.REOPENED
+        )
+
+    def update_issue_comment(self, comment_id: int, body: str) -> dict[str, Any]:
+        """Edit an existing comment on an issue or pull request.
+
+        :param comment_id: The id of the comment (its ``id`` field, which is
+            unique repository-wide and unrelated to the issue number).
+        :param body: The new Markdown body, replacing the current one.
+        """
+        return self._patch(
+            url=f"{self._url_issue_comments}/{comment_id}",
+            json={"body": body},
+        ).json()
+
+    def delete_issue_comment(self, comment_id: int) -> requests.Response:
+        """Delete a comment from an issue or pull request.
+
+        :param comment_id: The id of the comment (its ``id`` field, which is
+            unique repository-wide and unrelated to the issue number).
+        """
+        return self._delete(url=f"{self._url_issue_comments}/{comment_id}")
+
+    def get_issue_labels(self, issue_number: int, n: int = 0) -> list[dict[str, Any]]:
+        """List the labels on an issue.
+
+        :param issue_number: The number of the issue.
+        :param n: The maximum number of labels to return (0 means all).
+        """
+        return self._extract_all(url=f"{self._url_issues}/{issue_number}/labels", n=n)
+
+    def add_issue_labels(
+        self, issue_number: int, labels: str | Sequence[str]
+    ) -> list[dict[str, Any]]:
+        """Add labels to an issue, keeping the ones already on it.
+
+        :param issue_number: The number of the issue.
+        :param labels: Names of the labels to add, or a single name as a bare
+            string. Labels that do not already exist are created by GitHub.
+        :return: All labels on the issue after the addition.
+        :raises ValueError: If no label is given. GitHub rejects an empty list
+            here with a 422; use ``set_issue_labels`` to clear labels instead.
+        """
+        names = list(as_str_sequence(labels))
+        if not names:
+            raise ValueError(
+                f"No label to add was given for issue #{issue_number}; "
+                "pass at least one name, or use set_issue_labels(..., ()) to "
+                "remove every label."
+            )
+        return self._post(
+            url=f"{self._url_issues}/{issue_number}/labels",
+            json={"labels": names},
+        ).json()
+
+    def set_issue_labels(
+        self, issue_number: int, labels: str | Sequence[str]
+    ) -> list[dict[str, Any]]:
+        """Replace all labels on an issue with the given ones.
+
+        :param issue_number: The number of the issue.
+        :param labels: Names of the labels the issue should carry, or a single
+            name as a bare string; an empty sequence removes every label.
+        :return: All labels on the issue after the replacement.
+        """
+        return self._put(
+            url=f"{self._url_issues}/{issue_number}/labels",
+            json={"labels": list(as_str_sequence(labels))},
+        ).json()
+
+    def remove_issue_label(self, issue_number: int, label: str) -> list[dict[str, Any]]:
+        """Remove a single label from an issue.
+
+        :param issue_number: The number of the issue.
+        :param label: The name of the label to remove. GitHub responds with 404
+            if the issue does not carry it.
+        :return: The labels remaining on the issue.
+        """
+        # A label name may contain spaces and slashes (e.g. "good first issue"),
+        # so it is URL-encoded rather than interpolated raw into the path.
+        return self._delete(
+            url=f"{self._url_issues}/{issue_number}/labels/{quote(label, safe='')}",
+        ).json()
+
+    def add_issue_assignees(
+        self, issue_number: int, assignees: str | Sequence[str]
+    ) -> dict[str, Any]:
+        """Assign users to an issue, keeping those already assigned.
+
+        :param issue_number: The number of the issue.
+        :param assignees: Logins to assign, or a single login as a bare string.
+            A login without push access to the repository is silently ignored.
+        :return: The updated issue.
+        """
+        return self._post(
+            url=f"{self._url_issues}/{issue_number}/assignees",
+            json={"assignees": list(as_str_sequence(assignees))},
+        ).json()
+
+    def remove_issue_assignees(
+        self, issue_number: int, assignees: str | Sequence[str]
+    ) -> dict[str, Any]:
+        """Unassign users from an issue, leaving the other assignees in place.
+
+        :param issue_number: The number of the issue.
+        :param assignees: Logins to unassign, or a single login as a bare string.
+        :return: The updated issue.
+        """
+        return self._delete(
+            url=f"{self._url_issues}/{issue_number}/assignees",
+            json={"assignees": list(as_str_sequence(assignees))},
+        ).json()
+
+    def get_milestones(
+        self, state: IssueState = IssueState.OPEN, n: int = 0
+    ) -> list[dict[str, Any]]:
+        """List milestones in this repository.
+
+        :param state: Filter milestones by state: ``open`` (the default),
+            ``closed``, or ``all``.
+        :param n: The maximum number of milestones to return (0 means all).
+        """
+        return self._extract_all(url=self._url_milestones, params={"state": state}, n=n)
+
+    def create_milestone(
+        self,
+        title: str,
+        description: str = "",
+        due_on: str = "",
+    ) -> dict[str, Any]:
+        """Create a milestone in this repository.
+
+        :param title: The title of the milestone.
+        :param description: A description of the milestone.
+        :param due_on: When the milestone is due, as an ISO-8601 timestamp
+            (e.g. ``2026-12-31T00:00:00Z``).
+        :return: The new milestone, whose ``number`` is what ``create_issue``
+            and ``update_issue`` take as their ``milestone``.
+        """
+        json: dict[str, Any] = {"title": title}
+        if description:
+            json["description"] = description
+        if due_on:
+            json["due_on"] = due_on
+        return self._post(url=self._url_milestones, json=json).json()
+
+    def update_milestone(
+        self,
+        milestone_number: int,
+        *,
+        title: str | Unset = UNSET,
+        description: str | Unset = UNSET,
+        state: IssueState | Unset = UNSET,
+        due_on: str | Unset = UNSET,
+    ) -> dict[str, Any]:
+        """Update a milestone in this repository.
+
+        As in ``update_issue``, only the fields passed are sent.
+
+        :param milestone_number: The ``number`` of the milestone (not its id).
+        :param title: A new title.
+        :param description: A new description; pass ``""`` to empty it.
+        :param state: ``open`` or ``closed``.
+        :param due_on: A new due date, as an ISO-8601 timestamp. GitHub's
+            milestone endpoint takes no null due date, so an existing one can be
+            moved but not removed.
+        :raises ValueError: If no field is given, if ``state`` is neither open
+            nor closed, or if ``due_on`` is empty.
+        """
+        json: dict[str, Any] = {}
+        if not isinstance(title, Unset):
+            json["title"] = title
+        if not isinstance(description, Unset):
+            json["description"] = description
+        if not isinstance(state, Unset):
+            _validate_issue_state(state, noun="milestone")
+            json["state"] = str(state)
+        if not isinstance(due_on, Unset):
+            if not due_on:
+                raise ValueError(
+                    "due_on must be a non-empty ISO-8601 timestamp; GitHub "
+                    "rejects an empty one and offers no way to clear a due date."
+                )
+            json["due_on"] = due_on
+        if not json:
+            raise ValueError(
+                f"No field to update was given for milestone #{milestone_number}; "
+                "pass at least one of title, description, state or due_on."
+            )
+        return self._patch(
+            url=f"{self._url_milestones}/{milestone_number}", json=json
+        ).json()
+
+    def delete_milestone(self, milestone_number: int) -> requests.Response:
+        """Delete a milestone from this repository.
+
+        Issues associated with the milestone are not deleted; they simply lose it.
+
+        :param milestone_number: The ``number`` of the milestone (not its id).
+        """
+        return self._delete(url=f"{self._url_milestones}/{milestone_number}")
+
     def get_issue_comments(self, issue_number: int, n: int = 0) -> list[dict[str, Any]]:
         """List comments on an issue in this repository.
 
@@ -954,7 +1463,6 @@ class Repository(GitHub):
         return self._post(
             url=f"{self._url_issues}/{issue_number}/comments",
             json={"body": body},
-            timeout=10,
         ).json()
 
     def archive(self) -> requests.Response:

github_rest_api/scripts/container/build_container_images.py

@@ -14,6 +14,8 @@ from dulwich.refs import Ref
 from dulwich.repo import Repo
 from tenacity import retry, stop_after_attempt, wait_exponential
 
+from github_rest_api.utils import as_str_sequence
+
 
 def _get_commit(name: bytes) -> bytes:
     """Resolve a commit SHA or branch name to a commit SHA string."""
@@ -69,6 +71,8 @@ def has_relevant_changes(
 ) -> bool:
     if not commit1 or not commit2:
         return True
+    image_dirs = as_str_sequence(image_dirs)
+    paths_monitoring = as_str_sequence(paths_monitoring)
     if isinstance(commit1, str):
         commit1 = commit1.encode()
     if isinstance(commit2, str):
@@ -149,6 +153,8 @@ def build_images(
     tool: str = "podman",
     registry: str = "quay.io/legendu",
 ):
+    image_dirs = as_str_sequence(image_dirs)
+    paths_monitoring = as_str_sequence(paths_monitoring)
     _validate_paths_exist(image_dirs, "image dirs")
     _validate_paths_exist(paths_monitoring, "monitored paths")
     if not has_relevant_changes(commit1, commit2, image_dirs, paths_monitoring):

github_rest_api/scripts/github/auto_merge_pull_request.py

@@ -70,8 +70,9 @@ def parse_args(args=None, namespace=None) -> Namespace:
     parser.add_argument(
         "--merge-method",
         dest="merge_method",
-        choices=[m.value for m in MergeMethod],
-        default=MergeMethod.MERGE.value,
+        type=MergeMethod,
+        choices=list(MergeMethod),
+        default=MergeMethod.MERGE,
         help="The merge method to use.",
     )
     parser.add_argument(

github_rest_api/scripts/github/create_github_repo.py

@@ -10,8 +10,10 @@ from collections.abc import Sequence
 from pathlib import Path
 
 from dulwich import porcelain
+from dulwich.refs import HEADREF, LOCAL_BRANCH_PREFIX, Ref
 
 from github_rest_api import Organization, User
+from github_rest_api.utils import as_str_sequence
 
 logger = logging.getLogger(__name__)
 
@@ -55,12 +57,27 @@ def _active_branch(path: Path) -> str:
         return porcelain.active_branch(path).decode()
     except (IndexError, ValueError) as e:
         raise ValueError(
-            f"HEAD of the local repo at '{path}' is detached (not on any branch), "
-            "which is unsupported (this happens, e.g., with a colocated Jujutsu repo). "
+            f"Cannot determine the initial branch of the local repo at '{path}' "
+            "as HEAD does not point at a branch. "
             "Check out a branch (e.g. `git switch -c main`) before running this command."
         ) from e
 
 
+def _head_and_branches(path: Path) -> tuple[str | None, set[str]]:
+    """Resolve HEAD and the local branches with a single open of the repo.
+
+    Returns the commit SHA HEAD points at (None if it does not resolve to one)
+    and the existing local branch names (without the `refs/heads/` prefix).
+    """
+    with porcelain.open_repo_closing(path) as repo:
+        try:
+            head = repo.refs[HEADREF].decode()
+        except KeyError:
+            head = None
+        branches = {b.decode() for b in repo.refs.keys(base=Ref(LOCAL_BRANCH_PREFIX))}
+    return head, branches
+
+
 def _init_local_repo(
     repo: str,
     language: str,
@@ -83,7 +100,9 @@ def _init_local_repo(
     if not (path / ".git").exists():
         porcelain.init(path=path)
         logger.info("Initialized empty Git repository in %s", path)
-    if not porcelain.branch_list(path):
+    head, existing_branches = _head_and_branches(path)
+    if head is None and not existing_branches:
+        # A brand new repository: no commit and no branch yet.
         initial_branch = _active_branch(path)
         porcelain.add(repo=path, paths=["README.md"])
         logger.info("Added README.md to staging")
@@ -99,11 +118,28 @@ def _init_local_repo(
             porcelain.branch_delete(repo=path, name=initial_branch)
             logger.info("Deleted initial branch '%s'", initial_branch)
     else:
-        existing_branches = {b.decode() for b in porcelain.branch_list(path)}
-        for branch in branches:
-            if branch not in existing_branches:
-                porcelain.branch_create(repo=path, name=branch)
-                logger.info("Created branch '%s' from HEAD", branch)
+        missing = [b for b in branches if b not in existing_branches]
+        if missing and head is None:
+            # HEAD is unborn (e.g. after `git switch --orphan`) but branches
+            # already exist, so there is no commit to branch from. Without this,
+            # dulwich falls back to its "HEAD" objectish default and fails deep
+            # inside the object store with "Invalid object name b'HEAD'".
+            # `existing_branches` is never empty here: an empty one with a None
+            # head takes the brand-new-repository path above.
+            raise ValueError(
+                "Cannot create the branch(es) "
+                f"{', '.join(repr(b) for b in missing)} in the local repo at "
+                f"'{path}' as HEAD does not point at a commit to branch from. "
+                f"Check out an existing branch (e.g. "
+                f"`git switch {sorted(existing_branches)[0]}`) "
+                "before running this command."
+            )
+        # Point new branches at HEAD's commit explicitly. Dulwich fails to resolve
+        # its default "HEAD" objectish when HEAD is detached, which is the normal
+        # state of a colocated Jujutsu repository.
+        for branch in missing:
+            porcelain.branch_create(repo=path, name=branch, objectish=head)
+            logger.info("Created branch '%s' from HEAD", branch)
     _ensure_remote(path, repo, protocol)
     if push:
         for branch in branches:
@@ -132,6 +168,7 @@ def create_github_repo(
     push: bool,
     branches: Sequence[str] = ("main",),
 ) -> None:
+    branches = as_str_sequence(branches)
     token = token or os.getenv("GITHUB_TOKEN", "")
     if not token:
         token = getpass.getpass("Please enter your GitHub token: ")

github_rest_api/scripts/github/create_pull_request.py

@@ -5,6 +5,7 @@ The branch is updated (using dev) before creating the PR.
 import os
 import sys
 from argparse import ArgumentParser, Namespace
+from typing import Any
 
 from github_rest_api import Repository
 from github_rest_api.github import DEFAULT_PR_MODEL
@@ -64,6 +65,12 @@ 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(
+        "--draft",
+        dest="draft",
+        action="store_true",
+        help="Create the pull request as a draft.",
+    )
     parser.add_argument(
         "--model",
         dest="model",
@@ -100,7 +107,7 @@ 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)
-    pull_request = {
+    pull_request: dict[str, Any] = {
         "base": args.base_branch,
         "head": args.head_branch,
     }
@@ -108,6 +115,8 @@ def main() -> int:
         pull_request["title"] = args.title
     if args.body:
         pull_request["body"] = args.body
+    if args.draft:
+        pull_request["draft"] = True
     # 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)

github_rest_api/scripts/utils.py

@@ -9,6 +9,8 @@ from typing import Any, Iterable
 from dulwich import porcelain
 from dulwich.repo import Repo
 
+from github_rest_api.utils import as_str_sequence
+
 
 def config_git(local_repo_dir: str | Path, user_email: str, user_name: str):
     """Config Git.
@@ -89,6 +91,7 @@ def find_project_root(path: Path | None = None) -> Path | None:
 
 
 def get_toml_value(path: Path, keys: Sequence[str]) -> Any:
+    keys = as_str_sequence(keys)
     if not keys or not path.exists():
         return None
     try:

github_rest_api/utils.py

@@ -14,6 +14,25 @@ def partition(pred, iterable):
     return filter(pred, it1), filterfalse(pred, it2)
 
 
+def as_str_sequence(value: str | Sequence[str]) -> Sequence[str]:
+    """Wrap a bare string into a one-element sequence, leaving others untouched.
+
+    A `str` is itself a `Sequence[str]` of its own characters, so a caller who
+    passes a single value where a collection is expected is silently exploded
+    into one entry per character. No type checker flags this, because the
+    annotation really is satisfied.
+
+    An empty string yields an empty sequence rather than `[""]`, so a caller
+    passing an unset optional (from `os.getenv`, a config field or an argparse
+    default) keeps meaning "nothing" instead of "one empty entry".
+
+    :param value: A sequence of strings, or a single string.
+    """
+    if isinstance(value, str):
+        return [value] if value else []
+    return value
+
+
 def compile_patterns(patterns: str | Sequence[str] | None) -> list[re.Pattern[str]]:
     """Compile a list of regular expression patterns.
 

{github_rest_api-0.48.0.dist-info → github_rest_api-0.49.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: github-rest-api
-Version: 0.48.0
+Version: 0.49.0
 Summary: Simple wrapper of GitHub REST APIs.
 Author-email: Ben Du <longendu@yahoo.com>
 Classifier: Programming Language :: Python :: 3 :: Only

{github_rest_api-0.48.0.dist-info → github_rest_api-0.49.0.dist-info}/RECORD

@@ -1,21 +1,21 @@
-github_rest_api/__init__.py,sha256=VVpiUHVLbjjJGNN88OmEvCwq4xmBnXv68T8Apk_lwVc,282
-github_rest_api/github.py,sha256=tcP2ETyIySFto82S73IZLDaRaRrj9bZjd9wi-VWKUIo,45427
+github_rest_api/__init__.py,sha256=cY28SPof_s_VfcsDe10lqfEFWFTpRkrmygz_EBsB-ec,410
+github_rest_api/github.py,sha256=K2zdt0faIC0CodI-Iu1gM97JYrVq7bzy-8CYimewoXU,68602
 github_rest_api/pr_content.py,sha256=og1VwsMtwqwl-HUJcJrkwjUjFPw9E1k5xDtJVMAXBRo,10039
-github_rest_api/utils.py,sha256=RspoIZik0g105KpyFXCf4epAtgu1dUsxwlwUSSGhXPI,2697
+github_rest_api/utils.py,sha256=it5zHCNhXTut4M-PWR-BtWm63_rpFSc_xRc4rbDJ8Qw,3496
 github_rest_api/scripts/__init__.py,sha256=NkHTngnnWXPc0JmO5mqVKjDf4JPofuwWjDW1SU3aE7Y,36
-github_rest_api/scripts/utils.py,sha256=o5GzgSNyGHUIHhaaG5QUfXvv6fsTQPCHD9clGRNMggU,4588
+github_rest_api/scripts/utils.py,sha256=y-qF_2cpf0KhMp9TWvpb6eBc8NW7Bu3fkQDdYlXG9Cc,4672
 github_rest_api/scripts/cargo/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 github_rest_api/scripts/cargo/benchmark.py,sha256=wtxM9nQxELEUliWu8EGWqb42TRTOK9ufj4GxqxJeIS4,8541
 github_rest_api/scripts/cargo/profiling.py,sha256=5jjTejhz3MmvOTz7cvdQGhkd6PB5salXnPwmhxeo2Ys,4279
 github_rest_api/scripts/cargo/utils.py,sha256=tXp5mnVz0OSWfZSIP8COiB9rjX9XKILcCV62kf0ZAXw,339
 github_rest_api/scripts/container/__init__.py,sha256=9faBHMYJhqU2BmVZootquPJIaYgW8hf6PfIlPnHyaU0,48
-github_rest_api/scripts/container/build_container_images.py,sha256=-ZPPKVUpc0v-_5DuPldBykSCBo8ojzriIgrU5ODIZXg,8384
+github_rest_api/scripts/container/build_container_images.py,sha256=7ifuyqZeOjjgx1B-R1lUc53uU4kbmWXMhPkO18TnwkQ,8639
 github_rest_api/scripts/container/config_container.py,sha256=BtOqgZlQFM9cWZMoHKvOzNsyXxCl_DLqYWbMqu1YOWM,2835
 github_rest_api/scripts/container/update_version_containerfile.py,sha256=1PkuJkAsJBCEMdacMSndbuZKcmgUyXy6nBArnxKoPZk,4535
 github_rest_api/scripts/github/__init__.py,sha256=tEU1SdCS51M4M13WoqXZt3rjGEAI_QgNljt5XAyQJ_w,38
-github_rest_api/scripts/github/auto_merge_pull_request.py,sha256=_5191Xt_b8DtxjIqHrdY-gKLxvkzWd8oWoSbF2uauc8,3527
-github_rest_api/scripts/github/create_github_repo.py,sha256=6WBMcHtY0rn_ZaF_3TN_sX2QFpklE4TPKNSXOPBwmw0,8919
-github_rest_api/scripts/github/create_pull_request.py,sha256=gXtRRsxzegGxagHb6k3kxtRd3mt4QVwSPZQpsFnzz1Y,3968
+github_rest_api/scripts/github/auto_merge_pull_request.py,sha256=x7oUN6wvlM61mHUic3r2SKnPz2xxFcX15c5ZuAmU78A,3534
+github_rest_api/scripts/github/create_github_repo.py,sha256=OYvlhzH65mIj41Z2daHs4EX-aoyG1Y1_tGSYYKSeb54,10812
+github_rest_api/scripts/github/create_pull_request.py,sha256=vmvZkQcQDjYHnECUW5q7B4DHkPDVaHEqKQPb2IzxewY,4216
 github_rest_api/scripts/github/release_on_github.py,sha256=9psaIv-GtrHdvE-tkw0yxCMDmW0bPts-db2vUxhoKXo,4368
 github_rest_api/scripts/github/remove_branch.py,sha256=iKZ4Y_lQlSOIfifC4plqP-B6pEMnFrknGMvV1oLnuLc,3538
 github_rest_api/scripts/github/workflows/auto_merge_pull_request.yaml,sha256=LOCYzTnubAqBbeGunSdnEt453ZLwJ2870YxRlcPJ7GE,768
@@ -25,7 +25,7 @@ github_rest_api/scripts/github/workflows/create_pr_to_main.yaml,sha256=mgHPlewkC
 github_rest_api/scripts/github/workflows/remove_branch.yaml,sha256=KDpB76ovrhuRdP0HN5j6Th9gjIQWSDdh8b4b4yAgtoI,544
 github_rest_api/scripts/github/workflows/python/lint.yaml,sha256=toP2oUdVIKyu_n20Dr14k5cJYxN8rPksfbX4sfflXxc,699
 github_rest_api/scripts/github/workflows/python/test.yaml,sha256=86MljYEWX1E9kJYmhMCLwu46WNEWvoyO9PwqeRew540,887
-github_rest_api-0.48.0.dist-info/METADATA,sha256=GUo2AkySz1q5KewbBDYUPV-2Yvbchmhd4WXyT2zescs,915
-github_rest_api-0.48.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-github_rest_api-0.48.0.dist-info/entry_points.txt,sha256=OfbP9GuQC7SyGbymfCYrXEG-TCcKuu31v0EPNvHc1Q4,659
-github_rest_api-0.48.0.dist-info/RECORD,,
+github_rest_api-0.49.0.dist-info/METADATA,sha256=yXdqqS70hYq-w5uu3-dMaCTAAh0xmtNWmOWBFlZgU9Q,915
+github_rest_api-0.49.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+github_rest_api-0.49.0.dist-info/entry_points.txt,sha256=OfbP9GuQC7SyGbymfCYrXEG-TCcKuu31v0EPNvHc1Q4,659
+github_rest_api-0.49.0.dist-info/RECORD,,