gitea.cli.issue.get

get

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.

Functions:

gitea.cli.issue.get.get_command

get_command(
    ctx: Context,
    owner: Annotated[
        str,
        Option("--owner", help="Owner of the repository."),
    ],
    repository: Annotated[
        str | None,
        Option(
            "--repository", help=REPOSITORY_REQUIRED_HELP
        ),
    ] = None,
    issue_ids: Annotated[
        list[int] | None,
        Option("--issue-id", help=ISSUE_IDS_HELP),
    ] = None,
    issue_id_file: Annotated[
        str | None,
        Option("--issue-id-file", help=ISSUE_ID_FILE_HELP),
    ] = None,
    resolve_columns: Annotated[
        bool,
        Option(
            "--columns/--no-columns",
            help=ISSUE_COLUMNS_HELP,
        ),
    ] = True,
    index: Annotated[
        int | None,
        Option(
            "--index",
            help=DEPRECATED_INDEX_HELP,
            hidden=True,
        ),
    ] = None,
    account_name: Annotated[
        str | None,
        Option(
            "--account-name",
            help="Name of the account to use for authentication.",
        ),
    ] = None,
    token: Annotated[
        str | None,
        Option(
            "--token",
            help="Token for authentication. If not provided, the token from the specified account will be used.",
        ),
    ] = None,
    base_url: Annotated[
        str | None,
        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.

Parameters:

Name	Type	Description	Default
ctx	Context	The Typer context.	required
owner	Annotated[str, Option('--owner', help='Owner of the repository.')]	The owner of the repository.	required
repository	Annotated[str | None, Option('--repository', help=REPOSITORY_REQUIRED_HELP)]	The name of the repository, which this command requires.	None
issue_ids	Annotated[list[int] | None, Option('--issue-id', help=ISSUE_IDS_HELP)]	The issue numbers shown in the web UI.	None
issue_id_file	Annotated[str | None, Option('--issue-id-file', help=ISSUE_ID_FILE_HELP)]	A file listing more issue numbers, or - to read them from stdin.	None
resolve_columns	Annotated[bool, Option('--columns/--no-columns', help=ISSUE_COLUMNS_HELP)]	Whether to resolve the column each issue's card sits in.	True
index	Annotated[int | None, Option('--index', help=DEPRECATED_INDEX_HELP, hidden=True)]	The deprecated name of --issue-id, which names one issue.	None
account_name	Annotated[str | None, Option('--account-name', help='Name of the account to use for authentication.')]	Name of the account to use for authentication.	None
token	Annotated[str | None, Option('--token', help='Token for authentication. If not provided, the token from the specified account will be used.')]	Token for authentication. If not provided, the token from the specified account will be used.	None
base_url	Annotated[str | None, Option('--base-url', help='Base URL of the Gitea platform. If not provided, the base URL from the specified account will be used.')]	Base URL of the Gitea platform. If not provided, the base URL from the specified account will be used.	None

Source code in src/gitea/cli/issue/get.py

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)