python-gitea 0.11.6__tar.gz → 0.12.0__tar.gz

{python_gitea-0.11.6 → python_gitea-0.12.0}/.github/workflows/codeql.yml

@@ -22,13 +22,13 @@ jobs:
               uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
 
             - name: Initialize CodeQL
-              uses: github/codeql-action/init@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+              uses: github/codeql-action/init@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
               with:
                   languages: python
                   queries: security-and-quality
 
             - name: Autobuild
-              uses: github/codeql-action/autobuild@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+              uses: github/codeql-action/autobuild@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4
 
             - name: Perform CodeQL Analysis
-              uses: github/codeql-action/analyze@b96794f015dfd88f77b49b1c93e0fa7110f94c63 # v4
+              uses: github/codeql-action/analyze@2892aa5e19bbd11bc0cff5427e3b750a04d9e3c2 # v4

{python_gitea-0.11.6 → python_gitea-0.12.0}/.github/workflows/draft_release.yml

@@ -22,7 +22,7 @@ jobs:
 
             - name: Generate changelog
               id: changelog
-              uses: orhun/git-cliff-action@3d96a18cc4ec17e9dc69ddcc424ccafaf1f78ce2 # v4.9.0
+              uses: orhun/git-cliff-action@a9a95522b26fe6403f7bb24031f21fb573d0f5ff # v4.9.1
               with:
                   config: cliff.toml
                   args: --unreleased --verbose

{python_gitea-0.11.6 → python_gitea-0.12.0}/.github/workflows/release.yml

@@ -30,7 +30,7 @@ jobs:
 
             - name: Generate changelog
               id: changelog
-              uses: orhun/git-cliff-action@3d96a18cc4ec17e9dc69ddcc424ccafaf1f78ce2 # v4.9.0
+              uses: orhun/git-cliff-action@a9a95522b26fe6403f7bb24031f21fb573d0f5ff # v4.9.1
               with:
                   config: cliff.toml
                   args: --current --verbose

{python_gitea-0.11.6 → python_gitea-0.12.0}/.github/workflows/scheduled_release.yml

@@ -31,7 +31,7 @@ jobs:
 
             - name: Check for new commits
               id: check_commits
-              uses: isaac-cf-wong/detect-git-changes-action@10d1e3ac7c5ee0997d7b370e9929cacac9c87013 # v0.0.19
+              uses: isaac-cf-wong/detect-git-changes-action@a8b0d224a4fdff017607079f83f01f013b9d66a6 # v0.0.20
               with:
                   use-latest-tag: true
 

{python_gitea-0.11.6 → python_gitea-0.12.0}/.github/workflows/support_floor_update.yml

@@ -22,7 +22,7 @@ jobs:
 
             - name: Apply support policy (spec0, from pyproject tool table)
               id: policy
-              uses: isaac-cf-wong/dependency-support-policy-action@74dfcfcc079cd22b26713242940f65ba2b3c70c7 # v0.2.9
+              uses: isaac-cf-wong/dependency-support-policy-action@dfc24273d70d9730ede96b5fdef09a8d7887cf04 # v0.2.10
               with:
                   mode: update
 

{python_gitea-0.11.6 → python_gitea-0.12.0}/.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
           - id: check-json
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.16.8
+      rev: v0.16.9
       hooks:
           - id: ruff
             args: [--fix, --config=pyproject.toml]
@@ -28,13 +28,13 @@ repos:
           - id: taplo-format
 
     - repo: https://github.com/crate-ci/typos
-      rev: v1.50.2
+      rev: v1.50.3
       hooks:
           - id: typos
             args: []
 
     - repo: https://github.com/rbubley/mirrors-prettier
-      rev: v3.9.8
+      rev: v3.9.9
       hooks:
           - id: prettier
 
@@ -52,7 +52,7 @@ repos:
           - id: actionlint
 
     - repo: https://github.com/astral-sh/uv-pre-commit
-      rev: 0.12.17
+      rev: 0.12.21
       hooks:
           # Update the uv lockfile
           - id: uv-lock

{python_gitea-0.11.6 → python_gitea-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-gitea
-Version: 0.11.6
+Version: 0.12.0
 Summary: A Python package for interacting with the Gitea API, offering a simple interface to access repositories, users, organizations, issues, and more for automation and data management.
 Project-URL: Documentation, https://isaac-cf-wong.github.io/python-gitea
 Project-URL: Source, https://github.com/isaac-cf-wong/python-gitea

{python_gitea-0.11.6 → python_gitea-0.12.0}/docs/dev/architecture.md

@@ -58,7 +58,7 @@ src/gitea/
 │   ├── main.py              # gitea-cli entry point, command registration
 │   ├── config/              # config commands
 │   ├── actions/             # actions workflow, run, job, artifact, secret, variable, runner commands
-│   ├── issue/               # issue + issue dependency commands
+│   ├── issue/               # issue, issue dependency + issue label commands
 │   ├── pull_request/        # pull-request commands
 │   ├── comment/             # comment commands
 │   ├── label/               # label commands
@@ -150,7 +150,8 @@ absence of any module-level import cycle anywhere in `gitea`.
 
 The CLI is a single Typer application registered in `cli/main.py`. Each resource
 has a command group (e.g. `gitea-cli issue`, `gitea-cli project`), and nested
-groups exist where the domain nests (e.g. `project column`, `issue dependency`).
+groups exist where the domain nests (e.g. `project column`, `issue dependency`,
+`issue label`).
 
 CLI commands reuse the client through thin helper functions in `cli/utils/`
 (`auth.py` resolves authentication, `api.py` and `convert.py` handle requests

{python_gitea-0.11.6 → python_gitea-0.12.0}/docs/user-guide/cli.md

@@ -478,6 +478,36 @@ otherwise look like.
 - `gitea-cli issue dependency remove --owner <owner> --repository <repo> --issue-id <number>`
     - Required: `--dependency-owner <owner>`, `--dependency-repository <repo>`,
       `--dependency-issue-id <number>`
+- `gitea-cli issue label list --owner <owner> --repository <repo> --issue-id <number>`
+- `gitea-cli issue label add --owner <owner> --repository <repo> --issue-id <number> --label <name-or-id>`
+    - Adds the labels and keeps the ones the issue already has.
+- `gitea-cli issue label remove --owner <owner> --repository <repo> --issue-id <number> --label <name-or-id>`
+    - A label the issue does not carry is left alone: the command still
+      succeeds, logs a warning, and names the label's ID in `not_on_issue` in
+      the issue's metadata.
+- `gitea-cli issue label set --owner <owner> --repository <repo> --issue-id <number> --label <name-or-id>`
+    - Replaces every label of the issue with the given ones.
+- `gitea-cli issue label clear --owner <owner> --repository <repo> --issue-id <number>`
+    - Removes every label from the issue.
+
+The `issue label` commands act on the labels an issue carries; the
+[`label` commands](#label---manage-labels) manage the labels a repository
+defines. In all of them:
+
+- `--label` is repeated once per label, and takes a label's name or its numeric
+  ID. A name is resolved to its ID through the repository's labels before
+  anything is written, so it works on a Gitea that only accepts IDs. Names are
+  matched exactly, case included. A name that matches no label, or more than
+  one, fails the command and no issue is changed. A value made only of digits is
+  taken as an ID and sent as it is, which is how a label defined on the
+  organization rather than the repository is named.
+- `--issue-id` can be repeated to act on several issues in one run. With one
+  issue, `data` is the list of labels the issue is left with. With several,
+  `data` holds one entry per issue, in the order given:
+  `{"issue_id": <number>, "labels": [...]}`, plus `not_on_issue` for `remove`.
+  The issues are changed one after another; if one fails, the command stops,
+  prints nothing on stdout, and its error names the issues that were already
+  changed.
 
 ### Pull Request - manage pull requests
 
@@ -886,6 +916,16 @@ gitea-cli issue create \
     --milestone 3
 ```
 
+Add a label to several existing issues, keeping the labels they already have:
+
+```bash
+gitea-cli issue label add \
+    --owner my-org \
+    --repository my-repo \
+    --issue-id 12 --issue-id 13 --issue-id 14 \
+    --label "needs review"
+```
+
 Start a workflow, then follow the run it started:
 
 ```bash

{python_gitea-0.11.6 → python_gitea-0.12.0}/docs/user-guide/python-api.md

@@ -155,12 +155,12 @@ is simpler and sufficient.
 | Client attribute      | Gitea domain                                                           |
 | --------------------- | ---------------------------------------------------------------------- |
 | `client.actions`      | Actions: workflows, runs, jobs, artifacts, secrets, variables, runners |
-| `client.issue`        | Issues and issue dependencies                                          |
+| `client.issue`        | Issues, issue dependencies and issue labels                            |
 | `client.pull_request` | Pull requests                                                          |
 | `client.repository`   | Repositories                                                           |
 | `client.user`         | Users and user settings                                                |
 | `client.comment`      | Issue comments                                                         |
-| `client.label`        | Issue labels                                                           |
+| `client.label`        | The labels a repository defines                                        |
 | `client.milestone`    | Milestones                                                             |
 | `client.notification` | Notifications                                                          |
 | `client.project`      | Projects, columns, and project issues                                  |

{python_gitea-0.11.6 → python_gitea-0.12.0}/pyproject.toml

@@ -29,7 +29,7 @@ dependencies = [
 
 [dependency-groups]
 dev = [
-  "ruff>=0.16.8",
+  "ruff>=0.16.9",
   # The mutation runner, in the environment `uv run` resolves, so that
   # `uv run mutmut run` reaches the same interpreter as `uv run pytest` and finds
   # the pytest plugins the suite's own options need. Run from a tool environment
@@ -52,7 +52,7 @@ docs = [
   "mike>=2.2.0",
 ]
 build = ["hatch>=1.18.1"]
-release = ["git-cliff>=2.13.1"]
+release = ["git-cliff>=2.14.2"]
 
 [project.scripts]
 gitea-cli = "gitea.cli.main:app"

python_gitea-0.12.0/src/gitea/cli/issue/label/__init__.py

@@ -0,0 +1 @@
+"""CLI commands for managing the labels of issues."""

python_gitea-0.12.0/src/gitea/cli/issue/label/add.py

@@ -0,0 +1,97 @@
+"""Add issue labels command."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from gitea.cli.issue.label.common import ISSUE_IDS_HELP, LABEL_HELP
+from gitea.cli.utils.options import REPOSITORY_REQUIRED_HELP
+
+
+def add_command(
+    ctx: typer.Context,
+    owner: Annotated[str, typer.Option("--owner", help="Owner of the repository.")],
+    repository: Annotated[str | None, typer.Option("--repository", help=REPOSITORY_REQUIRED_HELP)] = None,
+    issue_ids: Annotated[list[int] | None, typer.Option("--issue-id", help=ISSUE_IDS_HELP)] = None,
+    labels: Annotated[list[str] | None, typer.Option("--label", help=LABEL_HELP)] = None,
+    account_name: Annotated[
+        str | None,
+        typer.Option(
+            "--account-name",
+            help="Name of the account to use for authentication.",
+        ),
+    ] = None,
+    token: Annotated[
+        str | None,
+        typer.Option(
+            "--token",
+            help="Token for authentication. If not provided, the token from the specified account will be used.",
+        ),
+    ] = None,
+    base_url: Annotated[
+        str | None,
+        typer.Option(
+            "--base-url",
+            help="Base URL of the Gitea platform. If not provided, the base URL from the specified account will be used.",
+        ),
+    ] = None,
+) -> None:
+    """Add labels to one or more issues, keeping the labels they already have.
+
+    Args:
+        ctx: The Typer context.
+        owner: The owner of the repository.
+        repository: The name of the repository, which this command requires.
+        issue_ids: The issue numbers shown in the web UI.
+        labels: The labels, each a name or a numeric ID.
+        account_name: Name of the account to use for authentication.
+        token: Token for authentication.
+        base_url: Base URL of the Gitea platform.
+
+    """
+    from typing import Any  # noqa: PLC0415
+
+    from gitea.cli.issue.label.common import (  # noqa: PLC0415
+        for_each_issue,
+        require_issue_ids,
+        require_labels,
+        resolve_label_ids,
+    )
+    from gitea.cli.utils.api import execute_api_command  # noqa: PLC0415
+    from gitea.cli.utils.auth import get_auth_params  # noqa: PLC0415
+    from gitea.cli.utils.options import require_repository  # noqa: PLC0415
+    from gitea.client.gitea import Gitea  # noqa: PLC0415
+
+    command = "gitea-cli issue label add"
+    token, base_url = get_auth_params(
+        config_path=ctx.obj.get("config_path"),
+        account_name=account_name,
+        token=token,
+        base_url=base_url,
+    )
+
+    def api_call() -> tuple[dict[str, Any] | list[dict[str, Any]], dict[str, Any]]:
+        """Add the labels to each issue.
+
+        Returns:
+            A tuple containing the issue's resulting labels, or one entry per issue, and metadata.
+
+        """
+        target_repository = require_repository(repository, command=command)
+        targets = require_issue_ids(issue_ids, command=command)
+        requested = require_labels(labels, command=command)
+
+        with Gitea(token=token, base_url=base_url) as client:
+            label_ids = resolve_label_ids(client, owner, target_repository, requested, command=command)
+            # POST appends to the issue's labels; PUT would replace them.
+            return for_each_issue(
+                targets,
+                lambda issue_id: client.issue.add_issue_labels(
+                    owner=owner, repository=target_repository, index=issue_id, labels=list(label_ids)
+                ),
+                command=command,
+            )
+
+    execute_api_command(api_call=api_call, base_url=base_url, command_name=command)

python_gitea-0.12.0/src/gitea/cli/issue/label/clear.py

@@ -0,0 +1,94 @@
+"""Clear issue labels command."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from gitea.cli.issue.label.common import ISSUE_IDS_HELP
+from gitea.cli.utils.options import REPOSITORY_REQUIRED_HELP
+
+
+def clear_command(
+    ctx: typer.Context,
+    owner: Annotated[str, typer.Option("--owner", help="Owner of the repository.")],
+    repository: Annotated[str | None, typer.Option("--repository", help=REPOSITORY_REQUIRED_HELP)] = None,
+    issue_ids: Annotated[list[int] | None, typer.Option("--issue-id", help=ISSUE_IDS_HELP)] = None,
+    account_name: Annotated[
+        str | None,
+        typer.Option(
+            "--account-name",
+            help="Name of the account to use for authentication.",
+        ),
+    ] = None,
+    token: Annotated[
+        str | None,
+        typer.Option(
+            "--token",
+            help="Token for authentication. If not provided, the token from the specified account will be used.",
+        ),
+    ] = None,
+    base_url: Annotated[
+        str | None,
+        typer.Option(
+            "--base-url",
+            help="Base URL of the Gitea platform. If not provided, the base URL from the specified account will be used.",
+        ),
+    ] = None,
+) -> None:
+    """Remove every label from one or more issues.
+
+    Args:
+        ctx: The Typer context.
+        owner: The owner of the repository.
+        repository: The name of the repository, which this command requires.
+        issue_ids: The issue numbers shown in the web UI.
+        account_name: Name of the account to use for authentication.
+        token: Token for authentication.
+        base_url: Base URL of the Gitea platform.
+
+    """
+    from typing import Any  # noqa: PLC0415
+
+    from gitea.cli.issue.label.common import for_each_issue, require_issue_ids  # noqa: PLC0415
+    from gitea.cli.utils.api import execute_api_command  # noqa: PLC0415
+    from gitea.cli.utils.auth import get_auth_params  # noqa: PLC0415
+    from gitea.cli.utils.options import require_repository  # noqa: PLC0415
+    from gitea.client.gitea import Gitea  # noqa: PLC0415
+
+    command = "gitea-cli issue label clear"
+    token, base_url = get_auth_params(
+        config_path=ctx.obj.get("config_path"),
+        account_name=account_name,
+        token=token,
+        base_url=base_url,
+    )
+
+    def api_call() -> tuple[dict[str, Any] | list[dict[str, Any]], dict[str, Any]]:
+        """Remove every label from each issue.
+
+        Returns:
+            A tuple containing the issue's resulting labels, or one entry per issue, and metadata.
+
+        """
+        target_repository = require_repository(repository, command=command)
+        targets = require_issue_ids(issue_ids, command=command)
+
+        def clear(issue_id: int) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+            """Remove every label from one issue, and read back what it is left with.
+
+            Args:
+                issue_id: The issue to clear.
+
+            Returns:
+                A tuple containing the issue's resulting labels and metadata.
+
+            """
+            client.issue.clear_issue_labels(owner=owner, repository=target_repository, index=issue_id)
+            return client.issue.list_issue_labels(owner=owner, repository=target_repository, index=issue_id)
+
+        with Gitea(token=token, base_url=base_url) as client:
+            return for_each_issue(targets, clear, command=command)
+
+    execute_api_command(api_call=api_call, base_url=base_url, command_name=command)

python_gitea-0.12.0/src/gitea/cli/issue/label/common.py

@@ -0,0 +1,217 @@
+"""What the `issue label` commands share: reading labels and issues, and reporting per issue.
+
+A label is named on the command line by its name or by its numeric ID. Names are
+resolved to IDs here, through the repository's label listing, rather than sent to
+the API as they are: only a recent Gitea accepts names in an issue's label list,
+and one that does not rejects the whole request. Resolving first also means an
+unknown name is an error before anything is written, rather than a label silently
+not applied, and before the first of several issues has been changed.
+
+A value made only of ASCII digits is taken to be an ID and is sent as it is,
+without being looked up. That is what lets a label defined on the organization,
+which the repository's listing does not include, be applied at all.
+
+Every command takes one `--issue-id` or several. With one, `data` is that issue's
+labels, as `gitea-cli issue label list` emits them. With several, `data` holds one
+entry per issue, `{"issue_id": ..., "labels": [...]}`, in the order the issues were
+given, so that which issue was left with which labels can be read back. The shape
+follows from how the command was invoked, never from what the API answered.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+from gitea.cli.utils.errors import CommandError
+from gitea.utils.pagination import PAGE_SIZE, collect_all_pages
+
+if TYPE_CHECKING:
+    from gitea.client.gitea import Gitea
+
+logger = logging.getLogger("gitea")
+
+ISSUE_IDS_HELP = "Issue number shown in the web UI. Repeat the option to act on several issues."
+LABEL_HELP = "Label name or numeric ID. Repeat the option for several labels."
+
+_NUMERIC_ID = re.compile(r"[0-9]+")
+
+
+def require_issue_ids(issue_ids: list[int] | None, *, command: str) -> list[int]:
+    """Read the issues a command acts on.
+
+    Args:
+        issue_ids: The values passed as --issue-id, or None when it was omitted.
+        command: The command being run, named as the user invoked it.
+
+    Returns:
+        The issue numbers, in the order given, each once.
+
+    Raises:
+        CommandError: If no issue was given.
+
+    """
+    if not issue_ids:
+        raise CommandError(f"'{command}' needs an issue: pass --issue-id NUMBER, once per issue.")
+    return list(dict.fromkeys(issue_ids))
+
+
+def require_labels(labels: list[str] | None, *, command: str, hint: str = "") -> list[str]:
+    """Read the labels a command acts on.
+
+    Args:
+        labels: The values passed as --label, or None when it was omitted.
+        command: The command being run, named as the user invoked it.
+        hint: A sentence appended to the error, pointing at a command that needs no label.
+
+    Returns:
+        The labels, as they were given.
+
+    Raises:
+        CommandError: If no label was given.
+
+    """
+    if not labels:
+        message = f"'{command}' needs a label: pass --label NAME_OR_ID, once per label."
+        raise CommandError(f"{message} {hint}" if hint else message)
+    return labels
+
+
+def resolve_label_ids(client: Gitea, owner: str, repository: str, labels: list[str], *, command: str) -> list[int]:
+    """Resolve the labels given on the command line to their IDs.
+
+    The repository's labels are listed only when a name has to be resolved, and
+    then only once for all of them.
+
+    Args:
+        client: The client to list the repository's labels with.
+        owner: The owner of the repository.
+        repository: The name of the repository.
+        labels: The labels, each a name or a numeric ID.
+        command: The command being run, named as the user invoked it.
+
+    Returns:
+        The label IDs, in the order given, each once.
+
+    Raises:
+        CommandError: If a name matches no label of the repository, or more than one.
+
+    """
+    names = [label for label in labels if not _NUMERIC_ID.fullmatch(label)]
+    by_name: dict[str, list[int]] = {}
+    if names:
+        defined, _ = collect_all_pages(
+            lambda page: client.label.list_labels(owner=owner, repository=repository, page=page, limit=PAGE_SIZE)
+        )
+        for label in defined:
+            by_name.setdefault(label["name"], []).append(label["id"])
+
+    unknown = [name for name in names if name not in by_name]
+    if unknown:
+        raise CommandError(
+            f"'{command}': no label named {', '.join(repr(name) for name in unknown)} in {owner}/{repository}. "
+            f"Names are matched exactly, case included; 'gitea-cli label list' shows the repository's labels. "
+            f"A label defined on the organization is not looked up by name: pass its numeric ID."
+        )
+    ambiguous = [name for name in names if len(by_name[name]) > 1]
+    if ambiguous:
+        raise CommandError(
+            f"'{command}': more than one label is named {', '.join(repr(name) for name in ambiguous)} "
+            f"in {owner}/{repository}. Pass the numeric ID of the one you mean."
+        )
+
+    ids = [int(label) if _NUMERIC_ID.fullmatch(label) else by_name[label][0] for label in labels]
+    return list(dict.fromkeys(ids))
+
+
+def for_each_issue(
+    issue_ids: list[int],
+    action: Callable[[int], tuple[list[dict[str, Any]], dict[str, Any]]],
+    *,
+    command: str,
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Run a command on each issue in turn and shape what it reports.
+
+    The issues are acted on one after another, so a failure part-way leaves the
+    ones before it changed. The error then names them, since the command prints
+    nothing on stdout when it fails and the caller could not tell otherwise.
+
+    Args:
+        issue_ids: The issues to act on.
+        action: Callable acting on one issue and returning its resulting labels
+            and the metadata of the last response. Extra keys in the metadata
+            beyond `status_code` are reported with that issue.
+        command: The command being run, named as the user invoked it.
+
+    Returns:
+        A tuple containing the data and the metadata of the envelope: for one
+        issue, its labels and its metadata; for several, one entry per issue.
+
+    Raises:
+        CommandError: If acting on an issue after the first failed. A failure
+            on the first issue is raised as it was, since nothing else changed.
+
+    """
+    entries: list[dict[str, Any]] = []
+    metadata: dict[str, Any] = {}
+    for issue_id in issue_ids:
+        try:
+            labels, metadata = action(issue_id)
+        except Exception as e:
+            if not entries:
+                raise
+            done = ", ".join(str(entry["issue_id"]) for entry in entries)
+            raise CommandError(
+                f"'{command}' failed on issue {issue_id}: {e}. "
+                f"Issues {done} were already done, and issue {issue_id} may be partly done; "
+                f"the rest were not attempted."
+            ) from e
+        extra = {key: value for key, value in metadata.items() if key != "status_code"}
+        entries.append({"issue_id": issue_id, "labels": labels, **extra})
+
+    if len(entries) == 1:
+        return entries[0]["labels"], metadata
+    return entries, {"status_code": metadata["status_code"]}
+
+
+def remove_carried_labels(
+    client: Gitea, owner: str, repository: str, issue_id: int, label_ids: list[int]
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Remove from one issue those of the labels it carries, and read back what it is left with.
+
+    A label the issue does not carry is not an error: removing it would leave the
+    issue as it is either way, and a command run over several issues meets that
+    routinely. It is not silent either: it is logged, and named in the metadata
+    as `not_on_issue`, so a caller can tell a removal from a label that was never
+    there.
+
+    Args:
+        client: The client to act with.
+        owner: The owner of the repository.
+        repository: The name of the repository.
+        issue_id: The issue to remove the labels from.
+        label_ids: The IDs of the labels to remove.
+
+    Returns:
+        A tuple containing the issue's resulting labels, and metadata naming the
+        IDs of the requested labels it did not carry.
+
+    """
+    current, _ = client.issue.list_issue_labels(owner=owner, repository=repository, index=issue_id)
+    carried = {label["id"] for label in current}
+    absent = [label_id for label_id in label_ids if label_id not in carried]
+    if absent:
+        logger.warning(
+            "Issue %s does not carry label %s; left as it is.",
+            issue_id,
+            ", ".join(str(label_id) for label_id in absent),
+        )
+
+    for label_id in label_ids:
+        if label_id in carried:
+            client.issue.remove_issue_label(owner=owner, repository=repository, index=issue_id, label=label_id)
+
+    remaining, metadata = client.issue.list_issue_labels(owner=owner, repository=repository, index=issue_id)
+    return remaining, {**metadata, "not_on_issue": absent}