python-gitea 0.12.2__tar.gz → 0.13.1__tar.gz

{python_gitea-0.12.2 → python_gitea-0.13.1}/.github/workflows/codeql.yml

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

{python_gitea-0.12.2 → python_gitea-0.13.1}/.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@051225b2ef2faf2a02d61f16d1a027cdf941498d # v0.0.21
+              uses: isaac-cf-wong/detect-git-changes-action@9863c3c0ba155ed10b54072f711ae8807aedbc87 # v0.0.22
               with:
                   use-latest-tag: true
 

{python_gitea-0.12.2 → python_gitea-0.13.1}/.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@af9e20cfdcb7d14a4c08614e981e8c2339d3da0f # v0.2.11
+              uses: isaac-cf-wong/dependency-support-policy-action@f83b1c576c82b2a7dde5d3c38c222d68b76bb9cf # v0.2.12
               with:
                   mode: update
 

{python_gitea-0.12.2 → python_gitea-0.13.1}/.pre-commit-config.yaml

@@ -16,7 +16,7 @@ repos:
           - id: check-json
 
     - repo: https://github.com/astral-sh/ruff-pre-commit
-      rev: v0.16.10
+      rev: v0.17.0
       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.3
+      rev: v1.51.1
       hooks:
           - id: typos
             args: []
 
     - repo: https://github.com/rbubley/mirrors-prettier
-      rev: v3.9.9
+      rev: v3.9.10
       hooks:
           - id: prettier
 
@@ -52,7 +52,7 @@ repos:
           - id: actionlint
 
     - repo: https://github.com/astral-sh/uv-pre-commit
-      rev: 0.12.23
+      rev: 0.13.0
       hooks:
           # Update the uv lockfile
           - id: uv-lock

{python_gitea-0.12.2 → python_gitea-0.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: python-gitea
-Version: 0.12.2
+Version: 0.13.1
 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 → python_gitea-0.13.1}/docs/user-guide/cli.md

@@ -74,10 +74,10 @@ non-zero, so nothing is printed on stdout for a failed command. Log output also
 goes to stderr in both formats, so stdout stays parsable.
 
 One failure is deliberately not an error: the board lookup that fills in the
-`column_id` of `issue get`. A refused, timed-out or otherwise failed lookup logs
-a warning to stderr and reports that project's column as `null`, because the
-issue the command was asked for has already been retrieved and is not worth
-failing over an enrichment of it.
+`column_id` of `issue get`, unless `--no-columns` turns it off. A refused,
+timed-out or otherwise failed lookup logs a warning to stderr and reports that
+project's column as `null`, because the issue the command was asked for has
+already been retrieved and is not worth failing over an enrichment of it.
 
 Tokens are never included in the output of `config` commands in either format.
 
@@ -91,9 +91,9 @@ which command fetched it.
 
 A field the API cannot send is added only where it carries something the API has
 no way of saying, and is documented with the command that adds it: `column_id`
-on the project entries of `issue get`, and `issue_count` and `issue_ids` on the
-columns of `project show`, are the ones today. Such a field is never a second
-name for a field already in the payload.
+on the project entries of `issue get` (omitted under `--no-columns`), and
+`issue_count` and `issue_ids` on the columns of `project show`, are the ones
+today. Such a field is never a second name for a field already in the payload.
 
 Two consequences worth knowing:
 
@@ -442,17 +442,31 @@ otherwise look like.
       `--due-date`, `--closed`
 - `gitea-cli issue list --owner <owner> --repository <repo>`
     - Optional: `--state`, `--labels`, `--search-string`, `--created-by`,
-      `--assigned-by`, `--since`, `--before`, `--page`, `--limit`
+      `--assigned-by`, `--since`, `--before`, `--page`, `--limit`, `--issue-ids`
+    - `--issue-ids 12,7,40` lists only those issues, in that order. Gitea's
+      listing has no such filter, so its pages are walked until every one of
+      them has been seen; the other filters still apply, so
+      `--state open --issue-ids ...` answers "which of these are open" in one
+      call. `metadata.not_listed` names each requested issue the listing did not
+      hold - one the filters exclude, or one that does not exist. `--page`
+      cannot be combined with it; `--limit` still sets the page size.
 - `gitea-cli issue get --owner <owner> --repository <repo> --issue-id <number>`
+    - `--issue-id` can be repeated, and `--issue-id-file <path>` reads more
+      numbers - separated by commas, whitespace or newlines - from a file, or
+      from stdin when the path is `-`. With one `--issue-id` and no file, `data`
+      is the issue, as it always was; otherwise it is a list of the issues in
+      the order requested, each once. An issue that does not exist fails the
+      run, which prints nothing on stdout and names every missing issue.
     - The `comments` field is the number of comments on the issue, not the
       comments themselves; use `gitea-cli issue comment list` to read the
       bodies. The field keeps the API's name, as
       [the field-name convention](#field-names) requires: this command used to
       rename it to `comment_count` and was alone in doing so.
-    - Each entry of `projects` carries a `column_id`: the column the issue's
-      card sits in, or `null` when the issue has no card on that project. Gitea
-      does not report it on the issue itself, so it is resolved from each
-      project's board, which costs a few extra requests per project.
+    - Unless `--no-columns` is passed, each entry of `projects` carries a
+      `column_id`: the column the issue's card sits in, or `null` when the issue
+      has no card on that project. Gitea does not report it on the issue itself,
+      so it is resolved from each project's board, which costs a few extra
+      requests per project.
     - Resolution is best-effort. It reflects the board as it was during the
       walk, not at one instant: a card moved while the columns are being read
       may be reported under either column or as `null`. A lookup that is
@@ -461,6 +475,13 @@ otherwise look like.
       so `null` means "no card here" and "could not tell" alike. The columns of
       a user-owned (individual) project cannot be listed at all, so its
       `column_id` is always `null`.
+    - `--no-columns` turns that resolution off. Every project entry is then
+      emitted as the API sent it, without a `column_id`, and no board is read:
+      the run costs one request per issue however many projects the issues are
+      on. `--columns`, the default, resolves the columns. Reach for
+      `--no-columns` 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.
 - `gitea-cli issue edit --owner <owner> --repository <repo> --issue-id <number>`
     - Optional: `--title`, `--body`, `--state`, `--assignees`, `--milestone`,
       `--due-date`
@@ -579,9 +600,15 @@ gitea-cli project list --owner my-org --repository my-repo  # that repository's
 - `gitea-cli project column create --owner <owner> [--repository <repo>] --project-id <id> --title <title>`
     - Optional: `--color`
 - `gitea-cli project column list --owner <owner> [--repository <repo>] --project-id <id>`
+    - Optional: `--fields`
 - `gitea-cli project column issues --owner <owner> [--repository <repo>] --project-id <id> --column-id <id>`
-    - Optional: `--page`, `--limit`
+    - Optional: `--page`, `--limit`, `--fields`
+    - `data` is `{"column": {"id": ..., "title": ...}, "issues": [...]}`: the
+      column is echoed by the ID and title the API reports for `--column-id`, so
+      a read of another column of the same project says which column it read.
+      Earlier releases emitted the list of issues alone as `data`.
 - `gitea-cli project issues --owner <owner> [--repository <repo>] --project-id <id>`
+    - Optional: `--fields`
 - `gitea-cli project issue add --owner <owner> [--repository <repo>] --project-id <id> --column-id <id> --issue-id <id>`
     - Optional: `--issue-repository`
 - `gitea-cli project issue move --owner <owner> [--repository <repo>] --project-id <id> --column-id <id> --issue-id <id>`
@@ -596,6 +623,12 @@ gitea-cli project list --owner my-org --repository my-repo  # that repository's
       card is in, and is found on the board when it is omitted; an issue with no
       card there is reported as having none.
 
+`--fields id,number,title,state` cuts every record of the listing - each column
+for `column list`, each issue for `column issues` and `project issues` - down to
+the named fields, in that order. The echoed column is never cut. A field a
+record does not carry is emitted as `null`, so a misspelled field shows up as
+nulls rather than disappearing.
+
 The project endpoints identify an issue by its global ID, which is not the
 number shown in the web UI: `my-org/my-repo#15` may well be global ID `1854`.
 The three `project issue` commands therefore take `--issue-id` as the number

{python_gitea-0.12.2 → python_gitea-0.13.1}/pyproject.toml

@@ -29,13 +29,13 @@ dependencies = [
 
 [dependency-groups]
 dev = [
-  "ruff>=0.16.10",
+  "ruff>=0.17.0",
   # 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
   # of its own it cannot read `--cov`, and the run dies at collection.
   "mutmut>=3.8.0",
-  "prek>=0.5.4",
+  "prek>=0.5.5",
   "pytest-github-actions-annotate-failures>=0.4.2",
   "pytest-cov>=7.1.0",
   "pytest-mock>=3.16.0",

python_gitea-0.13.1/src/gitea/cli/issue/get.py

@@ -0,0 +1,241 @@
+"""Get issues command.
+
+The issue is emitted with the field names the API sends, as `gitea.utils.fields`
+requires. `comments` is one worth knowing about: it is the *number* of comments
+on the issue and not their bodies, which `gitea-cli issue comment list` is for.
+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.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_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,
+        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:
+    """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_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.
+
+    """
+    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
+    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,
+        token=token,
+        base_url=base_url,
+    )
+
+    def api_call() -> tuple[dict[str, Any] | list[dict[str, Any]], dict[str, Any]]:
+        """Get the issues' information.
+
+        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. 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, or a list of it, and metadata.
+
+        """
+        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:
+            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."
+            )
+        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.
+
+    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"]}

python_gitea-0.13.1/src/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