python-gitea 0.12.2__py3-none-any.whl → 0.13.0__py3-none-any.whl

gitea/cli/issue/get.py

@@ -7,22 +7,54 @@ An earlier version of this command renamed it to `comment_count` to say so, and
 was the only command emitting an issue that did - the same count arrived under
 two names depending on which command fetched the issue, which was the worse
 surprise of the two.
+
+Several issues can be read in one run: `--issue-id` may be repeated, and
+`--issue-id-file` reads a list of numbers from a file or from stdin, so a set of
+hundreds need not fit on a command line. The shape of `data` follows from how
+the command was invoked, never from what the API answered: one `--issue-id` and
+no file gives the issue itself, as it always has; anything else gives a list of
+issues in the order they were asked for, each once. An issue that does not exist
+fails the run, after every requested issue has been tried, with an error naming
+each missing one, so a single typo in a long list is not reported one run at a
+time.
+
+Every project an issue is on is emitted with the column its card sits in there,
+resolved from that project's board: the issue payload names the projects without
+saying where on them the card sits, so the column costs a walk of the board's
+columns and their issue listings, a few requests per project. `--no-columns`
+turns that walk off. Every project entry is then emitted as the API sent it,
+without a `column_id`, and the run reads no board at all - one request per issue,
+whatever boards the issues are on. It is the form to use when the issue's own
+fields are what is wanted - `state`, `labels`, `title` - since it is the board
+walk that a read of a set of issues pays most for.
 """
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from typing import Annotated, Any
 
 import typer
 
-from gitea.cli.utils.options import DEPRECATED_INDEX_HELP, ISSUE_ID_HELP, REPOSITORY_REQUIRED_HELP
+from gitea.cli.issue.ids import ISSUE_ID_FILE_HELP
+from gitea.cli.utils.options import DEPRECATED_INDEX_HELP, REPOSITORY_REQUIRED_HELP
+
+_NOT_FOUND = 404
+
+ISSUE_IDS_HELP = "Issue number shown in the web UI. Repeat the option to read several issues."
+ISSUE_COLUMNS_HELP = (
+    "Resolve the project column of each issue's card. Pass --no-columns to leave every project entry "
+    "as the API sent it and read no board, which is what a read of the issue's own fields wants."
+)
 
 
 def get_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_id: Annotated[int | None, typer.Option("--issue-id", help=ISSUE_ID_HELP)] = None,
+    issue_ids: Annotated[list[int] | None, typer.Option("--issue-id", help=ISSUE_IDS_HELP)] = None,
+    issue_id_file: Annotated[str | None, typer.Option("--issue-id-file", help=ISSUE_ID_FILE_HELP)] = None,
+    resolve_columns: Annotated[bool, typer.Option("--columns/--no-columns", help=ISSUE_COLUMNS_HELP)] = True,
     index: Annotated[int | None, typer.Option("--index", help=DEPRECATED_INDEX_HELP, hidden=True)] = None,
     account_name: Annotated[
         str | None,
@@ -46,14 +78,16 @@ def get_command(
         ),
     ] = None,
 ) -> None:
-    """Get a specific issue in a repository.
+    """Get one or more issues in a repository.
 
     Args:
         ctx: The Typer context.
         owner: The owner of the repository.
         repository: The name of the repository, which this command requires.
-        issue_id: The issue number shown in the web UI.
-        index: The deprecated name of `issue_id`.
+        issue_ids: The issue numbers shown in the web UI.
+        issue_id_file: A file listing more issue numbers, or `-` to read them from stdin.
+        resolve_columns: Whether to resolve the column each issue's card sits in.
+        index: The deprecated name of `--issue-id`, which names one issue.
         account_name: Name of the account to use for authentication.
         token: Token for authentication. If not provided, the token from the specified account will be used.
         base_url: Base URL of the Gitea platform. If not provided, the base URL from the specified account will be used.
@@ -61,10 +95,11 @@ def get_command(
     """
     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, resolve_issue_id  # noqa: PLC0415
+    from gitea.cli.utils.options import require_repository  # noqa: PLC0415
     from gitea.client.gitea import Gitea  # noqa: PLC0415
-    from gitea.issue.project_column import resolve_project_column_ids  # noqa: PLC0415
+    from gitea.issue.project_column import ColumnListings, resolve_project_column_ids  # noqa: PLC0415
 
+    command = "gitea-cli issue get"
     token, base_url = get_auth_params(
         config_path=ctx.obj.get("config_path"),
         account_name=account_name,
@@ -72,27 +107,135 @@ def get_command(
         base_url=base_url,
     )
 
-    def api_call() -> tuple[dict[str, Any], dict[str, Any]]:
-        """Get issue information.
+    def api_call() -> tuple[dict[str, Any] | list[dict[str, Any]], dict[str, Any]]:
+        """Get the issues' information.
 
-        The column of each project the issue is on is resolved from the project's
+        The column of each project an issue is on is resolved from the project's
         board, because the issue payload names the projects without saying where
-        on them the issue's card sits.
+        on them the issue's card sits. The issues of one run share the listings
+        of their boards' columns, so a board is listed once however many of the
+        issues are on it. `--no-columns` asks for no such resolution: the issues
+        are emitted as the API sent them and no board is read, which is what a
+        read of the issues' own fields wants.
 
         Returns:
-            A tuple containing the issue data and metadata.
+            A tuple containing the issue data, or a list of it, and metadata.
 
         """
-        target_repository = require_repository(repository, command="gitea-cli issue get")
-        target_issue = resolve_issue_id(issue_id=issue_id, index=index, command="gitea-cli issue get")
+        target_repository = require_repository(repository, command=command)
+        targets, single = _requested_issues(issue_ids, issue_id_file, index, command=command)
 
         with Gitea(token=token, base_url=base_url) as client:
-            data, metadata = client.issue.get_issue(
-                owner=owner,
-                repository=target_repository,
-                index=target_issue,
+            columns = ColumnListings()
+
+            def get_one(number: int) -> tuple[dict[str, Any], dict[str, Any]]:
+                data, metadata = client.issue.get_issue(owner=owner, repository=target_repository, index=number)
+                if not resolve_columns:
+                    return data, metadata
+                data = resolve_project_column_ids(
+                    client=client, owner=owner, repository=target_repository, issue=data, columns=columns
+                )
+                return data, metadata
+
+            if single:
+                return get_one(targets[0])
+            return _get_each(targets, get_one, owner=owner, repository=target_repository, command=command)
+
+    execute_api_command(api_call=api_call, base_url=base_url, command_name=command)
+
+
+def _requested_issues(
+    issue_ids: list[int] | None, issue_id_file: str | None, index: int | None, *, command: str
+) -> tuple[list[int], bool]:
+    """Read which issues the command reads, and whether it was asked for exactly one.
+
+    Args:
+        issue_ids: The values passed as --issue-id, or None when it was omitted.
+        issue_id_file: The value passed as --issue-id-file, or None when it was omitted.
+        index: The value passed as the deprecated --index, 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 with those of the file last, each
+        once; and True when one --issue-id (or --index) and no file named them,
+        which is the invocation that reports the issue itself rather than a list.
+
+    Raises:
+        CommandError: If no issue was given, or --index was combined with
+            several issues.
+
+    """
+    from gitea.cli.issue.ids import read_issue_id_file  # noqa: PLC0415
+    from gitea.cli.utils.errors import CommandError  # noqa: PLC0415
+    from gitea.cli.utils.options import resolve_issue_id  # noqa: PLC0415
+
+    given = list(issue_ids or [])
+    if index is not None:
+        if len(given) > 1 or issue_id_file is not None:
+            raise CommandError(
+                f"'{command}': --index names one issue and cannot be combined with several. "
+                f"It is the deprecated name of --issue-id: pass --issue-id once per issue instead."
+            )
+        given = [resolve_issue_id(issue_id=given[0] if given else None, index=index, command=command)]
+
+    if issue_id_file is None:
+        if not given:
+            raise CommandError(
+                f"'{command}' needs an issue: pass --issue-id NUMBER, once per issue, or --issue-id-file PATH."
             )
-            data = resolve_project_column_ids(client=client, owner=owner, repository=target_repository, issue=data)
-        return data, metadata
+        return list(dict.fromkeys(given)), len(given) == 1
+
+    given += read_issue_id_file(issue_id_file, command=command)
+    return list(dict.fromkeys(given)), False
+
+
+def _get_each(
+    numbers: list[int],
+    get_one: Callable[[int], tuple[dict[str, Any], dict[str, Any]]],
+    *,
+    owner: str,
+    repository: str,
+    command: str,
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Read each issue in turn, and report every one that does not exist together.
 
-    execute_api_command(api_call=api_call, base_url=base_url, command_name="gitea-cli issue get")
+    Args:
+        numbers: The issues to read.
+        get_one: Callable reading one issue and returning its data and metadata.
+        owner: The owner of the repository.
+        repository: The name of the repository.
+        command: The command being run, named as the user invoked it.
+
+    Returns:
+        A tuple containing the issues, in the order asked for, and the metadata
+        of the last response.
+
+    Raises:
+        CommandError: If any of the issues does not exist. Any other failure is
+            raised as it was, on the issue that met it.
+
+    """
+    from requests import HTTPError  # noqa: PLC0415
+
+    from gitea.cli.utils.errors import CommandError  # noqa: PLC0415
+
+    issues: list[dict[str, Any]] = []
+    missing: list[int] = []
+    metadata: dict[str, Any] = {}
+    for number in numbers:
+        try:
+            data, metadata = get_one(number)
+        except HTTPError as e:
+            response = getattr(e, "response", None)
+            if response is None or response.status_code != _NOT_FOUND:
+                raise
+            missing.append(number)
+            continue
+        issues.append(data)
+
+    if missing:
+        raise CommandError(
+            f"'{command}': no issue {', '.join(str(number) for number in missing)} in {owner}/{repository}; "
+            f"the other {len(issues)} of the {len(numbers)} requested exist. Nothing was printed."
+        )
+    return issues, {"status_code": metadata["status_code"]}

gitea/cli/issue/ids.py

@@ -0,0 +1,85 @@
+"""Reading a set of issue numbers given as text: a comma list, a file, or stdin.
+
+`issue get` reads several issues at once and `issue list` can be narrowed to a
+known set, so both need the numbers as a set rather than one option value per
+issue. The numbers are separated by commas, whitespace or newlines, in any mix,
+so a list written by hand, one printed by `jq -r '.[]'`, and one pasted from a
+comma-separated cell all read the same. A value that is not a positive whole
+number is an error naming it, rather than a number quietly dropped.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+from gitea.cli.utils.errors import CommandError
+
+# The value of `--issue-id-file` that asks for the numbers to be read from stdin.
+FROM_STDIN = "-"
+
+ISSUE_ID_FILE_HELP = (
+    "File listing issue numbers, separated by commas, whitespace or newlines. Pass '-' to read them from stdin."
+)
+
+_SEPARATORS = re.compile(r"[\s,]+")
+_ISSUE_NUMBER = re.compile(r"[0-9]+")
+
+
+def parse_issue_numbers(text: str, *, source: str, command: str) -> list[int]:
+    """Read the issue numbers in a piece of text.
+
+    Args:
+        text: The numbers, separated by commas, whitespace or newlines.
+        source: Where the text came from, for the error, e.g. "--issue-ids".
+        command: The command being run, named as the user invoked it.
+
+    Returns:
+        The numbers, in the order given, repeats included.
+
+    Raises:
+        CommandError: If a value is not a positive whole number.
+
+    """
+    tokens = [token for token in _SEPARATORS.split(text) if token]
+    invalid = [token for token in tokens if not _ISSUE_NUMBER.fullmatch(token) or int(token) == 0]
+    if invalid:
+        raise CommandError(
+            f"'{command}': {source} holds {', '.join(repr(token) for token in invalid)}, "
+            f"which {'is not an issue number' if len(invalid) == 1 else 'are not issue numbers'}. "
+            f"Issue numbers are the positive whole numbers shown in the web UI."
+        )
+    return [int(token) for token in tokens]
+
+
+def read_issue_id_file(path: str, *, command: str) -> list[int]:
+    """Read the issue numbers listed in a file, or on stdin.
+
+    Args:
+        path: The value passed as --issue-id-file, or `-` to read stdin.
+        command: The command being run, named as the user invoked it.
+
+    Returns:
+        The numbers, in the order listed, repeats included.
+
+    Raises:
+        CommandError: If the file cannot be read, lists no number, or lists a
+            value that is not one. A file listing nothing is an error rather than
+            an empty result, since that is what a pipeline that failed upstream
+            looks like.
+
+    """
+    source = "stdin" if path == FROM_STDIN else path
+    if path == FROM_STDIN:
+        text = sys.stdin.read()
+    else:
+        try:
+            text = Path(path).read_text(encoding="utf-8")
+        except OSError as e:
+            raise CommandError(f"'{command}' could not read --issue-id-file {path}: {e.strerror or e}.") from e
+
+    numbers = parse_issue_numbers(text, source=f"--issue-id-file {source}", command=command)
+    if not numbers:
+        raise CommandError(f"'{command}': --issue-id-file {source} lists no issue number.")
+    return numbers

gitea/cli/issue/list.py

@@ -1,14 +1,31 @@
-"""List issues command."""
+"""List issues command.
+
+`--issue-ids` narrows the listing to a known set of issues. Gitea's listing takes
+no such filter, so the set is applied here, over the listing the other filters
+select: its pages are walked until every requested issue has been seen or the
+listing ends, and the issues are emitted in the order they were asked for. An
+issue of the set that the other filters exclude - a closed one under the default
+`--state open`, say - is simply not listed, which is what makes "which of these
+are open" one call; `metadata.not_listed` names each such issue, so it can be
+told apart from one that was listed. `issue get` is the command that fails on an
+issue that does not exist.
+"""
 
 from __future__ import annotations
 
+from collections.abc import Callable
 from datetime import datetime
-from typing import Annotated, Literal
+from typing import Annotated, Any, Literal
 
 import typer
 
 from gitea.cli.utils.options import REPOSITORY_REQUIRED_HELP
 
+ISSUE_IDS_FILTER_HELP = (
+    "List only these issues, given as numbers separated by commas, in the order given. "
+    "The other filters still apply. Cannot be combined with --page."
+)
+
 
 def list_command(
     ctx: typer.Context,
@@ -53,6 +70,10 @@ def list_command(
         str | None,
         typer.Option("--mentioned-by", help="Filter issues mentioning this user."),
     ] = None,
+    issue_ids: Annotated[
+        str | None,
+        typer.Option("--issue-ids", help=ISSUE_IDS_FILTER_HELP),
+    ] = None,
     page: Annotated[
         int | None,
         typer.Option("--page", help="The page number for pagination."),
@@ -99,6 +120,7 @@ def list_command(
         created_by: Filter issues created by this user.
         assigned_by: Filter issues assigned to this user.
         mentioned_by: Filter issues mentioning this user.
+        issue_ids: List only these issues, given as comma-separated numbers.
         page: The page number for pagination.
         limit: The number of issues per page.
         account_name: Name of the account to use for authentication.
@@ -106,14 +128,14 @@ def list_command(
         base_url: Base URL of the Gitea platform. If not provided, the base URL from the specified account will be used.
 
     """
-    from typing import Any  # 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.convert import list_str_to_list_int_or_none  # noqa: PLC0415
     from gitea.cli.utils.options import require_repository  # noqa: PLC0415
     from gitea.client.gitea import Gitea  # noqa: PLC0415
+    from gitea.utils.pagination import PAGE_SIZE  # noqa: PLC0415
 
+    command = "gitea-cli issue list"
     token, base_url = get_auth_params(
         config_path=ctx.obj.get("config_path"),
         account_name=account_name,
@@ -130,24 +152,96 @@ def list_command(
             The issue information as a dictionary.
 
         """
-        target_repository = require_repository(repository, command="gitea-cli issue list")
+        target_repository = require_repository(repository, command=command)
+        requested = _requested_issues(issue_ids, page, command=command)
 
         with Gitea(token=token, base_url=base_url) as client:
-            return client.issue.list_issues(
-                owner=owner,
-                repository=target_repository,
-                state=state,
-                labels=labels,
-                search_string=search_string,
-                issue_type=issue_type,
-                milestones=milestones_values,
-                since=since,
-                before=before,
-                created_by=created_by,
-                assigned_by=assigned_by,
-                mentioned_by=mentioned_by,
-                page=page,
-                limit=limit,
-            )
-
-    execute_api_command(api_call=api_call, base_url=base_url, command_name="gitea-cli issue list")
+
+            def fetch(page_number: int | None, page_size: int | None) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+                return client.issue.list_issues(
+                    owner=owner,
+                    repository=target_repository,
+                    state=state,
+                    labels=labels,
+                    search_string=search_string,
+                    issue_type=issue_type,
+                    milestones=milestones_values,
+                    since=since,
+                    before=before,
+                    created_by=created_by,
+                    assigned_by=assigned_by,
+                    mentioned_by=mentioned_by,
+                    page=page_number,
+                    limit=page_size,
+                )
+
+            if requested is None:
+                return fetch(page, limit)
+            return _list_requested(requested, lambda number: fetch(number, limit or PAGE_SIZE))
+
+    execute_api_command(api_call=api_call, base_url=base_url, command_name=command)
+
+
+def _requested_issues(issue_ids: str | None, page: int | None, *, command: str) -> list[int] | None:
+    """Read the set of issues the listing is narrowed to.
+
+    Args:
+        issue_ids: The value passed as --issue-ids, or None when it was omitted.
+        page: The value passed as --page, 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, or None when the
+        listing is not narrowed.
+
+    Raises:
+        CommandError: If the set is empty or holds a value that is not an issue
+            number, or --page was passed with it: the set is looked for across
+            every page, so a page number would have nothing to select.
+
+    """
+    from gitea.cli.issue.ids import parse_issue_numbers  # noqa: PLC0415
+    from gitea.cli.utils.errors import CommandError  # noqa: PLC0415
+
+    if issue_ids is None:
+        return None
+    if page is not None:
+        raise CommandError(
+            f"'{command}': --issue-ids is looked for across every page of the listing, so --page cannot be "
+            f"combined with it. Drop --page; --limit still sets how many issues each request asks for."
+        )
+    numbers = parse_issue_numbers(issue_ids, source="--issue-ids", command=command)
+    if not numbers:
+        raise CommandError(f"'{command}': --issue-ids names no issue. Pass the numbers separated by commas.")
+    return list(dict.fromkeys(numbers))
+
+
+def _list_requested(
+    numbers: list[int],
+    fetch_page: Callable[[int], tuple[list[dict[str, Any]], dict[str, Any]]],
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Walk a listing until every requested issue has been seen, and keep only those.
+
+    Args:
+        numbers: The requested issue numbers, each once.
+        fetch_page: Callable returning the items and metadata of the given page number.
+
+    Returns:
+        A tuple containing the requested issues the listing holds, in the order
+        requested, and the metadata of the last response with `not_listed`
+        naming the requested issues it does not hold.
+
+    """
+    from gitea.utils.pagination import iter_pages  # noqa: PLC0415
+
+    wanted = set(numbers)
+    found: dict[int, dict[str, Any]] = {}
+    metadata: dict[str, Any] = {}
+    for batch, page_metadata in iter_pages(fetch_page):
+        metadata = page_metadata
+        found.update({issue["number"]: issue for issue in batch if issue.get("number") in wanted})
+        if len(found) == len(wanted):
+            break
+
+    issues = [found[number] for number in numbers if number in found]
+    return issues, {**metadata, "not_listed": [number for number in numbers if number not in found]}

gitea/cli/project/column/issues.py

@@ -6,6 +6,8 @@ from typing import Annotated
 
 import typer
 
+from gitea.cli.utils.projection import FIELDS_HELP
+
 
 def list_column_issues_command(
     ctx: typer.Context,
@@ -24,6 +26,10 @@ def list_column_issues_command(
         str | None,
         typer.Option("--repository", help="Name of the repository. Omit for organization projects."),
     ] = None,
+    fields: Annotated[
+        str | None,
+        typer.Option("--fields", help=FIELDS_HELP),
+    ] = None,
     account_name: Annotated[
         str | None,
         typer.Option(
@@ -46,7 +52,11 @@ def list_column_issues_command(
         ),
     ] = None,
 ) -> None:
-    """List the issues in a project's column.
+    """List the issues in a project's column, together with the column read.
+
+    The column is echoed by the ID and title the API reports for it, so a read of
+    the wrong column of the right project says which column it read instead of
+    passing for the intended one.
 
     Args:
         ctx: The Typer context.
@@ -56,6 +66,7 @@ def list_column_issues_command(
         column_id: The ID of the column.
         page: The page number for pagination.
         limit: The number of issues per page.
+        fields: Comma-separated fields to keep on each issue, or None for all of them.
         account_name: Name of the account to use for authentication.
         token: Token for authentication.
         base_url: Base URL of the Gitea platform.
@@ -65,6 +76,7 @@ def list_column_issues_command(
 
     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.projection import parse_fields, project_records  # noqa: PLC0415
     from gitea.client.gitea import Gitea  # noqa: PLC0415
 
     token, base_url = get_auth_params(
@@ -78,11 +90,18 @@ def list_column_issues_command(
         """List the issues in a project column.
 
         Returns:
-            A tuple containing the issue data and metadata.
+            A tuple containing the column read with its issues, and metadata.
 
         """
+        names = parse_fields(fields)
         with Gitea(token=token, base_url=base_url) as client:
-            return client.project.list_project_column_issues(
+            column, _ = client.project.get_project_column(
+                owner=owner,
+                repository=repository,
+                project_id=project_id,
+                column_id=column_id,
+            )
+            issues, metadata = client.project.list_project_column_issues(
                 owner=owner,
                 repository=repository,
                 project_id=project_id,
@@ -90,5 +109,10 @@ def list_column_issues_command(
                 page=page,
                 limit=limit,
             )
+        data = {
+            "column": {"id": column.get("id"), "title": column.get("title")},
+            "issues": project_records(issues, names),
+        }
+        return data, metadata
 
     execute_api_command(api_call=api_call, base_url=base_url, command_name="gitea-cli project column issues")

gitea/cli/project/column/list.py

@@ -6,6 +6,8 @@ from typing import Annotated
 
 import typer
 
+from gitea.cli.utils.projection import FIELDS_HELP
+
 
 def list_columns_command(
     ctx: typer.Context,
@@ -23,6 +25,10 @@ def list_columns_command(
         str | None,
         typer.Option("--repository", help="Name of the repository. Omit for organization projects."),
     ] = None,
+    fields: Annotated[
+        str | None,
+        typer.Option("--fields", help=FIELDS_HELP),
+    ] = None,
     account_name: Annotated[
         str | None,
         typer.Option(
@@ -54,6 +60,7 @@ def list_columns_command(
         project_id: The ID of the project.
         page: The page number for pagination.
         limit: The number of columns per page.
+        fields: Comma-separated fields to keep on each column, or None for all of them.
         account_name: Name of the account to use for authentication.
         token: Token for authentication.
         base_url: Base URL of the Gitea platform.
@@ -63,6 +70,7 @@ def list_columns_command(
 
     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.projection import parse_fields, project_records  # noqa: PLC0415
     from gitea.client.gitea import Gitea  # noqa: PLC0415
 
     token, base_url = get_auth_params(
@@ -79,13 +87,15 @@ def list_columns_command(
             A tuple containing the column data and metadata.
 
         """
+        names = parse_fields(fields)
         with Gitea(token=token, base_url=base_url) as client:
-            return client.project.list_project_columns(
+            columns, metadata = client.project.list_project_columns(
                 owner=owner,
                 repository=repository,
                 project_id=project_id,
                 page=page,
                 limit=limit,
             )
+        return project_records(columns, names), metadata
 
     execute_api_command(api_call=api_call, base_url=base_url, command_name="gitea-cli project column list")

gitea/cli/project/issues.py

@@ -6,6 +6,7 @@ from typing import Annotated, Any
 
 import typer
 
+from gitea.cli.utils.projection import FIELDS_HELP
 from gitea.utils.pagination import PAGE_SIZE, collect_all_pages
 
 
@@ -17,6 +18,10 @@ def list_project_issues_command(
         str | None,
         typer.Option("--repository", help="Name of the repository. Omit for organization projects."),
     ] = None,
+    fields: Annotated[
+        str | None,
+        typer.Option("--fields", help=FIELDS_HELP),
+    ] = None,
     account_name: Annotated[
         str | None,
         typer.Option(
@@ -46,6 +51,7 @@ def list_project_issues_command(
         owner: The owner of the repository.
         repository: The name of the repository, or None for organization projects.
         project_id: The ID of the project.
+        fields: Comma-separated fields to keep on each issue, or None for all of them.
         account_name: Name of the account to use for authentication.
         token: Token for authentication.
         base_url: Base URL of the Gitea platform.
@@ -53,6 +59,7 @@ def list_project_issues_command(
     """
     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.projection import parse_fields, project_records  # noqa: PLC0415
     from gitea.client.gitea import Gitea  # noqa: PLC0415
 
     token, base_url = get_auth_params(
@@ -71,6 +78,7 @@ def list_project_issues_command(
             A tuple containing one entry per column, each with its issues, and metadata.
 
         """
+        names = parse_fields(fields)
         with Gitea(token=token, base_url=base_url) as client:
             columns, metadata = collect_all_pages(
                 lambda page: client.project.list_project_columns(
@@ -99,7 +107,7 @@ def list_project_issues_command(
                 data.append(
                     {
                         "column": {"id": column["id"], "title": column.get("title")},
-                        "issues": issues,
+                        "issues": project_records(issues, names),
                     }
                 )
 

gitea/cli/utils/projection.py

@@ -0,0 +1,61 @@
+"""Cut the records a listing emits down to the fields the caller asked for.
+
+A board listing carries every issue as the API sends it, a full `user` object
+and all, so a read meant to answer "which cards are where" runs to a hundred
+kilobytes on a board of a dozen cards. `--fields` keeps the keys named and
+drops the rest.
+
+A field named but absent from a record is emitted as `null` rather than left
+out, so a misspelled field shows up in the output as a column of nulls instead
+of as records that quietly lost it.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from gitea.cli.utils.errors import CommandError
+
+FIELDS_HELP = (
+    "Comma-separated fields to keep on each record, e.g. id,number,title,state. "
+    "A field a record does not carry is emitted as null. Omit to emit every field."
+)
+
+
+def parse_fields(fields: str | None) -> list[str] | None:
+    """Read the value of `--fields`.
+
+    Args:
+        fields: The value passed as --fields, or None when omitted.
+
+    Returns:
+        The field names in the order given, without repeats, or None when the
+        option was omitted.
+
+    Raises:
+        CommandError: If the option was passed but names no field.
+
+    """
+    if fields is None:
+        return None
+    names = list(dict.fromkeys(name.strip() for name in fields.split(",") if name.strip()))
+    if not names:
+        raise CommandError(f"--fields names no field: {fields!r}. Pass a comma-separated list, e.g. id,title.")
+    return names
+
+
+def project_records(records: list[dict[str, Any]], fields: list[str] | None) -> list[dict[str, Any]]:
+    """Keep only the named fields of each record.
+
+    Args:
+        records: The records of a listing.
+        fields: The fields to keep, or None to keep every field.
+
+    Returns:
+        The records unchanged when `fields` is None, and otherwise each record
+        cut down to `fields`, in that order.
+
+    """
+    if fields is None:
+        return records
+    return [{name: record.get(name) for name in fields} for record in records]

gitea/issue/project_column.py

@@ -34,6 +34,17 @@ lists the issue. It is the answer to "has this issue a card on this project, and
 where" wherever that has to be told apart from "the board could not be read" -
 the project issue commands ask it before moving a card, because Gitea's move
 endpoint reports success without doing anything when there is no card to move.
+
+A caller resolving many issues in one run - ``gitea-cli issue get`` given a list
+of them - passes one ``ColumnListings`` to every lookup, so that a board the
+issues share has its columns listed once for the run rather than once per issue.
+The listing is still paged only as far as some walk needed it, and a lookup that
+fails while paging it is forgotten rather than kept, so the next issue on that
+board pages it afresh: each issue meets the failures a walk of its own would have
+met, and only the requests already answered are not repeated. The columns' issue
+listings are not kept, since they are what tells one issue's card from another's.
+A column added to a board during the run is not seen by the issues after the
+listing was paged, which is the same race the walk already has within one issue.
 """
 
 from __future__ import annotations
@@ -47,6 +58,8 @@ from requests import RequestException
 from gitea.utils.pagination import PAGE_SIZE, iter_async_pages, iter_pages
 
 if TYPE_CHECKING:
+    from collections.abc import Iterator
+
     from gitea.client.async_gitea import AsyncGitea
     from gitea.client.gitea import Gitea
 
@@ -123,6 +136,101 @@ def _holds_issue(issues: list[Any], issue_id: int) -> bool:
     return any(_identifier(issue) == issue_id for issue in issues)
 
 
+class _ColumnListing:
+    """The IDs of one project's columns, paged in as a walk asks for them.
+
+    Every walk over it replays the IDs already paged in and asks for the next
+    page only once it has passed them all, so walks sharing the listing request
+    each page once. A page that fails propagates its error and ends the listing.
+    """
+
+    def __init__(self, pages: Iterator[tuple[list[Any], dict[str, Any]]]) -> None:
+        """Wrap the pages of a column listing.
+
+        Args:
+            pages: The listing's pages, each fetched when it is first reached.
+
+        """
+        self._pages = pages
+        self._ids: list[int] = []
+        self._complete = False
+
+    def __iter__(self) -> Iterator[int]:
+        """Walk the column IDs in board order.
+
+        Yields:
+            The ID of each column that carries a usable one.
+
+        """
+        index = 0
+        while True:
+            if index < len(self._ids):
+                yield self._ids[index]
+                index += 1
+                continue
+            # An exhausted generator stops without a request, but `pages` may be any
+            # Iterator: once complete, never ask the source for another page.
+            if self._complete:
+                return
+            try:
+                columns, _ = next(self._pages)
+            except StopIteration:
+                self._complete = True
+                return
+            self._ids.extend(column_id for column in columns if (column_id := _identifier(column)) is not None)
+
+
+class ColumnListings:
+    """The column listings of the projects one run has looked a card up on.
+
+    Meant to live for one run and no longer: a listing kept is not listed again,
+    so a board edited between two runs would otherwise be read as it was.
+    """
+
+    def __init__(self) -> None:
+        """Start with no project listed."""
+        self._listings: dict[tuple[str, str | None, int], _ColumnListing] = {}
+
+    def column_ids(self, *, client: Gitea, owner: str, repository: str | None, project_id: int) -> Iterator[int]:
+        """Walk the IDs of a project's columns, listing them only as far as no walk has before.
+
+        Args:
+            client: The Gitea client used for the lookups.
+            owner: The owner of the repository or organization holding the project.
+            repository: The name of the repository holding the project, or None for
+                an organization project.
+            project_id: The ID of the project.
+
+        Yields:
+            The ID of each column of the project, in board order.
+
+        Raises:
+            Exception: Whatever listing a page raised. The listing is then
+                forgotten, so the next walk of the project lists it afresh.
+
+        """
+        key = (owner, repository, project_id)
+        listing = self._listings.get(key)
+        if listing is None:
+            listing = self._listings[key] = _ColumnListing(
+                iter_pages(
+                    lambda page: client.project.list_project_columns(
+                        owner=owner,
+                        repository=repository,
+                        project_id=project_id,
+                        page=page,
+                        limit=PAGE_SIZE,
+                    )
+                )
+            )
+        try:
+            yield from listing
+        except Exception:
+            if self._listings.get(key) is listing:
+                del self._listings[key]
+            raise
+
+
 _LOOKUP_FAILED = "Could not resolve the column of issue %s on project %s, reporting it as null: %s"
 
 # aiohttp raises its total timeout as a bare asyncio.TimeoutError, which is the
@@ -138,6 +246,7 @@ def resolve_project_column_ids(
     owner: str,
     repository: str,
     issue: dict[str, Any],
+    columns: ColumnListings | None = None,
 ) -> dict[str, Any]:
     """Populate the ``column_id`` of every project an issue is on.
 
@@ -146,6 +255,8 @@ def resolve_project_column_ids(
         owner: The owner of the repository holding the issue.
         repository: The name of the repository holding the issue.
         issue: The issue data returned by the API.
+        columns: The column listings to share with the other issues of the run,
+            or None to list each project's columns for this issue alone.
 
     Returns:
         The issue data with a ``column_id`` on every project entry, holding the
@@ -178,6 +289,7 @@ def resolve_project_column_ids(
                     repository=_column_scope_repository(project, repository),
                     project_id=project_id,
                     issue_id=issue_id,
+                    columns=columns,
                 )
             except RequestException as e:
                 # Enriching the issue is not worth failing the issue over: the
@@ -195,6 +307,7 @@ def find_card_column_id(
     repository: str | None,
     project_id: int,
     issue_id: int,
+    columns: ColumnListings | None = None,
 ) -> int | None:
     """Find the column of a project that lists an issue.
 
@@ -205,34 +318,25 @@ def find_card_column_id(
             an organization project.
         project_id: The ID of the project.
         issue_id: The global ID of the issue.
+        columns: The column listings to share with the other lookups of the run,
+            or None to list the project's columns for this lookup alone.
 
     Returns:
         The ID of the column listing the issue, or None when no column of the
         project lists it.
 
     """
-    for columns, _ in iter_pages(
-        lambda page: client.project.list_project_columns(
+    listings = ColumnListings() if columns is None else columns
+    for column_id in listings.column_ids(client=client, owner=owner, repository=repository, project_id=project_id):
+        if column_holds_card(
+            client=client,
             owner=owner,
             repository=repository,
             project_id=project_id,
-            page=page,
-            limit=PAGE_SIZE,
-        )
-    ):
-        for column in columns:
-            column_id = _identifier(column)
-            if column_id is None:
-                continue
-            if column_holds_card(
-                client=client,
-                owner=owner,
-                repository=repository,
-                project_id=project_id,
-                column_id=column_id,
-                issue_id=issue_id,
-            ):
-                return column_id
+            column_id=column_id,
+            issue_id=issue_id,
+        ):
+            return column_id
     return None
 
 

{python_gitea-0.12.2.dist-info → python_gitea-0.13.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-gitea
-Version: 0.12.2
+Version: 0.13.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.12.2.dist-info → python_gitea-0.13.0.dist-info}/RECORD

@@ -78,8 +78,9 @@ gitea/cli/issue/__init__.py,sha256=I-46LqvYmDgd08yMiFDPU2oE313uT-06nUUpVxs_dTg,4
 gitea/cli/issue/close.py,sha256=3L1Hvwndq4aNl-G5KWueyJ-tnbHTP0NzXGfeACJZzE4,4127
 gitea/cli/issue/create.py,sha256=g0x33xFt_USPJ0szspa7M_uWK728lnzDP6m0CYlJ0p4,4544
 gitea/cli/issue/edit.py,sha256=QdUtWVBZoK2UjWXnAAvR-eMKmtOM2Yw51uy1sTsCKRo,5204
-gitea/cli/issue/get.py,sha256=qEUnoXioVfvOBU0P4tLaKTtEjonvUHCs1XkUscfJZCY,4066
-gitea/cli/issue/list.py,sha256=AjnrA1LwJwtUn596JimUhKSjyMDWRsm9ywBdaxtZSHk,5584
+gitea/cli/issue/get.py,sha256=LYLZIwCVC67Ypn2WSoIo_6mz8eiseIlOjZEfLHRbfhI,10754
+gitea/cli/issue/ids.py,sha256=ndwZINbRE-Ax_1mu6QTaOocVjFxmUXIHLdskGadsK-U,3251
+gitea/cli/issue/list.py,sha256=_QEZ7fhyxD9z_rPIo-w68lW3xgJGVMGba-8wJ126Fic,9869
 gitea/cli/issue/main.py,sha256=LdqQh_zEh-bJK0kTwxIyRDRWi3bXwXBX4UW2RkGOq28,1685
 gitea/cli/issue/dependency/__init__.py,sha256=cbMVSnGnivUIYUcEwjQkaJ-7FmjzPftKYtnp0xjDBvY,52
 gitea/cli/issue/dependency/add.py,sha256=jlfGJt-5H5WF55m5WBPAlWdGdlEurBhIExUicbE34qM,4542
@@ -116,14 +117,14 @@ gitea/cli/project/create.py,sha256=Ku0zwVgEP4RwvOcu16VUiQluTaK6vRrOZ__i40hiFAo,3
 gitea/cli/project/delete.py,sha256=XbGgn9ccD6AAzozHCjjT0PIO2WmV-OngGTgYmkyVbBc,2565
 gitea/cli/project/edit.py,sha256=HYk1ucsjxctmKqb6w3oDp4giX7eZy8tKbY_vcQ7nFj4,3438
 gitea/cli/project/get.py,sha256=Fb8REqjoZkXkPqGIsGz_53c9hNRkF3xxoDOiv6XsXxs,2546
-gitea/cli/project/issues.py,sha256=fgwM90ckiIcZx8EWKLdFrXJDQrntc0Bzp6rVBYDtwWs,3851
+gitea/cli/project/issues.py,sha256=ffwIlW9Xik3zRs00ZFmUd6chm5oDTiNh05Uqdsl_Un4,4249
 gitea/cli/project/list.py,sha256=_VjnD0Tzjk_Pl9Ir-Tfb-J-cO-5P08vBjKEM0erlZEQ,3020
 gitea/cli/project/main.py,sha256=lRswFzhJ3B54IkGT0v2ZaLsvkvVELH-W_zJfSjs019k,3527
 gitea/cli/project/show.py,sha256=C6OTlzjvjfdpS3RF_XTBKaBAdaI4WSKJU2Sdi1kTAF0,5657
 gitea/cli/project/column/__init__.py,sha256=GiQ-qrPCzeUcu-V1YzJrm-dqP2vsSt1e1j4UsXoMSNA,49
 gitea/cli/project/column/create.py,sha256=VnrFYSnsjqBdmzeT5Hn-sDwIRD8uQp2bA4iDZvLL2v4,2989
-gitea/cli/project/column/issues.py,sha256=j48Pfmg1dxBjnBAdNBdDO5kZciqX2hkkaT8L_NB2TDc,3186
-gitea/cli/project/column/list.py,sha256=_cuKmTeN4W-S8ixAXFs1178zPg9p5LJbUsGlSUR8q1g,2988
+gitea/cli/project/column/issues.py,sha256=jyxYdRDpCIp8q2v3pXX6pqJcWf4-g9O0c_2Hx-aqGo4,4224
+gitea/cli/project/column/list.py,sha256=Ij_ucIlBRJBtQ2anIwBomwhDv_vdBDJr4M4kcbKg6Tk,3434
 gitea/cli/project/issue/__init__.py,sha256=MnZE61XcpwD5MGvOcTZkYdyDe7LLdzLEehuXmrSI6q4,48
 gitea/cli/project/issue/add.py,sha256=uQ72ffrHQt9OGjXsls6HZiUrpLPkx65lrOglEDLhcVc,4373
 gitea/cli/project/issue/move.py,sha256=X4tQ7oBMsCuE2LlUQrRUpO4qvUlGGQYGST6LL9fUxIg,4876
@@ -145,6 +146,7 @@ gitea/cli/utils/convert.py,sha256=kf2txtS976rM9d7U-NhyqKUQLm7fQjx-y9Qr6fHSLq0,97
 gitea/cli/utils/errors.py,sha256=KRKsqTumWTr7OZnjK6LudPv2Rx42WCrDj2RETGMmCa0,2148
 gitea/cli/utils/issue.py,sha256=kaa4Ek7NY8ItR5Ng66jjFs0OLzMo9rAy3dxO4_Q_FG8,52359
 gitea/cli/utils/options.py,sha256=-UXhhSQoAQAYTka4-zIP2Cju6Ku_gGS27THkTrRn0IQ,7585
+gitea/cli/utils/projection.py,sha256=1uhSoYU7rBKvT-_ISL_4B_RlCTfjbS6MFi00cwSsr28,2026
 gitea/cli/watch/__init__.py,sha256=6PWnogslBxaoc7j1GBRalQhF1pwiDofKy24zwiWTjcg,52
 gitea/cli/watch/advance.py,sha256=l3pMuRrvadcVFxPTUDAbv7abFEQ6oZ5XPBrR34OXFp8,9250
 gitea/cli/watch/list.py,sha256=FhRlW1cgfYtrlk-8xj2hqPdzgF6weYPJz2qplwHs37I,7730
@@ -165,7 +167,7 @@ gitea/issue/__init__.py,sha256=gScB9oA-26poYwUEw1Ce-xx4rmh2GS4uNn94s_3E_Yc,1514
 gitea/issue/async_issue.py,sha256=1ME-nN5usqoyCbwtaBmSiHbN-QfHIHFQq2gFbG7A_5U,29500
 gitea/issue/base.py,sha256=Q13QLwxKGozvmd7oPiex9Kw5unsdvCKF-GCvdg0-zJQ,15298
 gitea/issue/issue.py,sha256=wpXoGH9JQps3ypbGyzOkqKacGGnDxXxwFWrPEtORXfw,28894
-gitea/issue/project_column.py,sha256=7TpnQcq9-hqc9eEciluplHQmSLiEBkRBr-lH7y6L9s8,15005
+gitea/issue/project_column.py,sha256=WmjeX1T_uVykxpOQmWKEqFQrV_jlXGr4F4X0CTF7vx8,19487
 gitea/label/__init__.py,sha256=cHdpsWsPWOX-q6k1JRzPOFSRafJUj907lmndLntjZjQ,690
 gitea/label/async_label.py,sha256=11UPD9T15Z3_Z2f63a9oxnwy__qDXTrIECZ03S0ecgE,10049
 gitea/label/base.py,sha256=8zD3r7n6iC4d4bnnDgTB8yfuu0GuZQFoNTC6T7xUcQ4,6483
@@ -210,8 +212,8 @@ gitea/utils/response.py,sha256=dDk-joN6TA3blefFGTxWTs41dHOUapQs3OxoOqiMg6o,5945
 gitea/watch/__init__.py,sha256=xeLLpoldkTAJda4WPOVa6NvE1i_X2VcUcgiMFoK9ImU,1422
 gitea/watch/changes.py,sha256=lSeq3-V8IjvcoZFp5teciiezOlQa89vhaWju80JEHO4,14418
 gitea/watch/state.py,sha256=ZmwPnTRavdyIJuXIY0QllVCh56O_p9oPdVzS-pt0oCs,17856
-python_gitea-0.12.2.dist-info/METADATA,sha256=PgXEdpd3tfl6AKhOdc6MqZ-XrpRqAkb0wluhPpmf9Go,7634
-python_gitea-0.12.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-python_gitea-0.12.2.dist-info/entry_points.txt,sha256=m5yt-1RMRZRFMj_M-Un5E4eOkM113S9EppAHp0aCzEY,49
-python_gitea-0.12.2.dist-info/licenses/LICENSE,sha256=4dW9zcCxiQKAu4CyNKJTRmvzdJCCHDxbPGuQ-YALpsY,1137
-python_gitea-0.12.2.dist-info/RECORD,,
+python_gitea-0.13.0.dist-info/METADATA,sha256=WsXaKSGlrnS0XzU67GBhqUmUQbwhucS_0OwqMgyMuIQ,7634
+python_gitea-0.13.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+python_gitea-0.13.0.dist-info/entry_points.txt,sha256=m5yt-1RMRZRFMj_M-Un5E4eOkM113S9EppAHp0aCzEY,49
+python_gitea-0.13.0.dist-info/licenses/LICENSE,sha256=4dW9zcCxiQKAu4CyNKJTRmvzdJCCHDxbPGuQ-YALpsY,1137
+python_gitea-0.13.0.dist-info/RECORD,,