python-gitea 0.10.0__tar.gz → 0.10.1__tar.gz

{python_gitea-0.10.0 → python_gitea-0.10.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@7cce60e19b902747b4267c4f8e53820e3f3656ea # v0.2.4
+              uses: isaac-cf-wong/dependency-support-policy-action@c00466ca1b1d902260e56e087c072cbb41ac038b # v0.2.5
               with:
                   mode: update
 

{python_gitea-0.10.0 → python_gitea-0.10.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.3
+      rev: v0.16.4
       hooks:
           - id: ruff
             args: [--fix, --config=pyproject.toml]

{python_gitea-0.10.0 → python_gitea-0.10.1}/PKG-INFO

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

@@ -320,7 +320,11 @@ gitea-cli project list --owner my-org --repository my-repo  # that repository's
 - `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>`
-    - Optional: `--sorting`, `--issue-repository`
+    - Optional: `--sorting`, `--issue-repository`, `--add-if-missing`
+    - Moves the card the issue already has on the project, and confirms it
+      arrived in `--column-id`. An issue with no card there is reported as an
+      error naming `project issue add`; `--add-if-missing` has this command put
+      it in `--column-id` instead.
 - `gitea-cli project issue remove --owner <owner> [--repository <repo>] --project-id <id> --column-id <id> --issue-id <id>`
     - Optional: `--issue-repository`
 
@@ -338,6 +342,40 @@ for you:
   ID. `--issue-repository` also overrides `--repository`, for the case of a
   repository project holding an issue from elsewhere.
 
+`add` and `move` are not two ways of doing the same thing. `add` puts an issue
+on a board, giving it a card in a column; `move` relocates the card it already
+has there, and an issue with no card has nothing to relocate. Gitea's move
+endpoint does not say so - it moves the row relating the issue to the project,
+of which there is none, and answers with a success and an empty body having
+moved nothing - so the command finds the card first and reports its absence
+itself:
+
+```console
+$ gitea-cli project issue move --owner my-org --project-id 1 --column-id 2 \
+      --issue-repository my-repo --issue-id 42
+No column of project 1 holds issue #42 of my-org/my-repo (global ID 1854), so there is
+no card to move. [...] Put the issue on the board with 'gitea-cli project issue add
+--owner my-org --project-id 1 --column-id 2 --issue-id 42 --issue-repository my-repo',
+or pass --add-if-missing to have this command do that when there is no card yet.
+```
+
+`--add-if-missing` makes the one call do either, which is what a script
+advancing cards through columns wants: the card is moved when it exists and
+created in `--column-id` when it does not. `--sorting` is refused on that second
+path rather than dropped, since the endpoint putting a card on a board takes no
+position within the column. A board that cannot be read is reported as such and
+stops the move: a failed lookup is not evidence that the issue has no card.
+
+Whichever call is made, `--column-id` is then read back, because the success the
+endpoint answers with has already been shown not to mean the card went anywhere.
+A zero exit status therefore says the card was seen in that column, rather than
+that Gitea accepted a request to put it there - and the three ways that can fail
+are reported apart: the issue has no card at all, the card is not in the column
+it was sent to, or the reading back could not be done and it is unknown which.
+It does not say the card is still there: the calls are separate requests, and
+Gitea has no conditional move to make them one, so a card taken off the board
+after the command read it is outside what any client can report on.
+
 The global ID the command used comes back as `metadata.resolved_issue_id`. A
 number the repository does not have, and a call the project endpoint refuses,
 are both reported as errors naming the issue and what to check - never as an
@@ -527,8 +565,8 @@ gitea-cli issue create \
     --milestone 3
 ```
 
-Move an issue into a project column, addressing it by the number shown in the
-web UI:
+Put an issue on a project board, in a column of it, addressing the issue by the
+number shown in the web UI:
 
 ```bash
 gitea-cli project issue add \
@@ -539,8 +577,9 @@ gitea-cli project issue add \
     --issue-id 42
 ```
 
-Move `my-repo#42` on an organization project, where the repository holding the
-issue has to be named separately:
+Move the card of `my-repo#42` on an organization project, where the repository
+holding the issue has to be named separately, and put it on the board if it is
+not there yet:
 
 ```bash
 gitea-cli project issue move \
@@ -548,7 +587,8 @@ gitea-cli project issue move \
     --project-id 1 \
     --column-id 2 \
     --issue-repository my-repo \
-    --issue-id 42
+    --issue-id 42 \
+    --add-if-missing
 ```
 
 List the issues sitting in one column of an organization project (omit

{python_gitea-0.10.0 → python_gitea-0.10.1}/docs/user-guide/python-api.md

@@ -90,6 +90,38 @@ Both are best-effort, and `column_id` should be read with that in mind:
 - The columns of a user-owned (individual) project live under endpoints this
   library does not wrap, so such a project's `column_id` is always `None`.
 
+That last point is about the enrichment and not about the walk itself.
+`find_card_column_id` is the walk on its own — one project, one issue, the
+column holding its card or `None` when no column of the board lists it — and it
+raises what the lookup raised rather than logging it, for a caller that has to
+tell "no card" apart from "could not be read":
+
+```python
+from gitea.client.gitea import Gitea
+from gitea.issue import find_card_column_id
+
+with Gitea(token="TOKEN", base_url="https://gitea.example.com") as client:
+    column_id = find_card_column_id(
+        client=client,
+        owner="my-org",
+        repository=None,  # the organization's own project; a repository's names it
+        project_id=1,
+        issue_id=1854,  # the global ID, which is what the columns list their issues by
+    )
+    print("not on the board" if column_id is None else column_id)
+```
+
+`find_async_card_column_id` is its `await`-based twin. Asking this before moving
+a card is what `gitea-cli project issue move` does: Gitea's move endpoint moves
+the row relating an issue to a project, and for an issue that is not on the
+project there is none to move, so the call comes back a success having done
+nothing.
+
+`column_holds_card` is the same question about a single named column, at the
+cost of that column's listing rather than the board's — which is what the walk
+above asks per column, and what the same command asks again after the move to
+confirm the card arrived. `async_column_holds_card` is its `await`-based twin.
+
 ## Asynchronous Client
 
 The `AsyncGitea` client has the same structure but `await`-based, and it uses

{python_gitea-0.10.0 → python_gitea-0.10.1}/pyproject.toml

@@ -35,7 +35,7 @@ dev = [
   # 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.7.0",
-  "prek>=0.4.13",
+  "prek>=0.4.14",
   "pytest-github-actions-annotate-failures>=0.4.2",
   "pytest-cov>=7.1.0",
   "pytest-mock>=3.15.1",

{python_gitea-0.10.0 → python_gitea-0.10.1}/src/gitea/cli/project/issue/add.py

@@ -54,6 +54,12 @@ def add_issue_command(
 ) -> None:
     """Add an issue to a project column.
 
+    This is the command for putting an issue on a board, where 'project issue
+    move' relocates a card the issue already has on the project. An issue with
+    none is not something a move can act on, so this is what runs for it -
+    either on its own, or as what 'project issue move --add-if-missing' falls
+    back to when it finds no card.
+
     Args:
         ctx: The Typer context.
         owner: The owner of the repository.

{python_gitea-0.10.0 → python_gitea-0.10.1}/src/gitea/cli/project/issue/move.py

@@ -23,6 +23,13 @@ def move_issue_command(
         int | None,
         typer.Option("--sorting", help="Position within the column, ascending."),
     ] = None,
+    add_if_missing: Annotated[
+        bool,
+        typer.Option(
+            "--add-if-missing",
+            help="Put the issue in the target column when it has no card on the project yet, instead of failing.",
+        ),
+    ] = False,
     repository: Annotated[
         str | None,
         typer.Option("--repository", help="Name of the repository. Omit for organization projects."),
@@ -56,7 +63,14 @@ def move_issue_command(
         ),
     ] = None,
 ) -> None:
-    """Move an issue between a project's columns.
+    """Move an issue's card between a project's columns.
+
+    The issue has to be on the project already: a move relocates the card the
+    issue has there, and an issue with no card has nothing to relocate. Gitea
+    answers such a call with a success all the same, so the card is looked for
+    first and its absence is reported as an error naming 'project issue add',
+    which is the command that puts an issue on a board. Pass --add-if-missing to
+    have this command do that itself when there is no card yet.
 
     Args:
         ctx: The Typer context.
@@ -67,6 +81,8 @@ def move_issue_command(
             global issue ID when that repository is not known.
         column_id: The target column ID.
         sorting: The position within the column, ascending.
+        add_if_missing: Whether to put the issue in the target column when it has
+            no card on the project yet, rather than reporting that it has none.
         issue_repository: The name of the repository holding the issue,
             defaulting to the repository holding the project.
         account_name: Name of the account to use for authentication.
@@ -78,7 +94,7 @@ def move_issue_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.issue import run_project_issue_call  # noqa: PLC0415
+    from gitea.cli.utils.issue import run_project_issue_move  # noqa: PLC0415
     from gitea.client.gitea import Gitea  # noqa: PLC0415
 
     token, base_url = get_auth_params(
@@ -96,21 +112,16 @@ def move_issue_command(
 
         """
         with Gitea(token=token, base_url=base_url) as client:
-            return run_project_issue_call(
+            return run_project_issue_move(
                 client=client,
-                call=lambda resolved_issue_id: client.project.move_project_issue(
-                    owner=owner,
-                    repository=repository,
-                    project_id=project_id,
-                    issue_id=resolved_issue_id,
-                    column_id=column_id,
-                    sorting=sorting,
-                ),
-                action="move",
                 owner=owner,
+                repository=repository,
                 project_id=project_id,
                 issue_number=issue_id,
+                column_id=column_id,
+                sorting=sorting,
                 issue_repository=issue_repository or repository,
+                add_if_missing=add_if_missing,
             )
 
     execute_api_command(api_call=api_call, base_url=base_url, command_name="gitea-cli project issue move")

{python_gitea-0.10.0 → python_gitea-0.10.1}/src/gitea/cli/project/main.py

@@ -48,8 +48,18 @@ def register_commands() -> None:
     project_app.add_typer(column_app, name="column", help="Commands for managing project columns.")
 
     issue_app = typer.Typer(name="issue", help="Commands for managing project issues.", rich_markup_mode="rich")
-    issue_app.command("add", help="Add an issue to a project column.")(add_issue_command)
-    issue_app.command("move", help="Move an issue between a project's columns.")(move_issue_command)
+    issue_app.command(
+        "add",
+        help="Add an issue to a project column. This is what puts an issue on a board that has no card for it.",
+    )(add_issue_command)
+    issue_app.command(
+        "move",
+        help=(
+            "Move an issue's card between a project's columns. The issue has to be on the project already, "
+            "since a move relocates the card it has there; pass --add-if-missing to put it in the target column "
+            "when it has none."
+        ),
+    )(move_issue_command)
     issue_app.command("remove", help="Remove an issue from a project column.")(remove_issue_command)
     project_app.add_typer(issue_app, name="issue", help="Commands for managing project issues.")