pjdev-gitlab 5.1.12__tar.gz → 5.1.14__tar.gz

{pjdev_gitlab-5.1.12 → pjdev_gitlab-5.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: pjdev-gitlab
-Version: 5.1.12
+Version: 5.1.14
 Project-URL: Documentation, https://gitlab.purplejay.io/keystone/python/-/tree/main/pjdev-gitlab/README.md
 Project-URL: Issues, https://gitlab.purplejay.io/keystone/python/-/issues
 Project-URL: Source, https://gitlab.purplejay.io/keystone/python
@@ -192,6 +192,68 @@ asyncio.run(main())
 
 Run it: `op run --env-file=.env.op -- python my_script.py`.
 
+### Notes (comments) and replies
+
+`notes_service` reads and replies to comments on **both** issues and merge
+requests — they share the same endpoint shape, so one `Noteable` parameter
+selects which.
+
+GitLab only lets you reply to a *discussion* (a thread), never to a note id, so
+`reply_to_note` resolves the note to its containing thread for you:
+
+```python
+import asyncio
+from pjdev_gitlab import config_service, notes_service
+from pjdev_gitlab.notes_service import Noteable, QuickActionOnlyError
+
+async def main() -> None:
+    config_service.init()
+
+    # Fetch. Notes come back newest-first; pass sort="asc" to read in order.
+    notes = await notes_service.list_notes(
+        "my-group/my-project", Noteable.merge_request, 166,
+        include_system=False,   # drop "assigned to @x", "changed milestone", ...
+        sort="asc",
+    )
+
+    # Threads, when you need a discussion id to answer into.
+    threads = await notes_service.list_discussions(
+        "my-group/my-project", Noteable.merge_request, 166
+    )
+
+    # Reply, addressing the note you're answering.
+    await notes_service.reply_to_note(
+        "my-group/my-project", Noteable.merge_request, 166,
+        note_id=notes[0].id,
+        body="Good catch — fixed in the next push.",
+    )
+
+    # Or straight into a known thread.
+    await notes_service.reply_to_discussion(
+        "my-group/my-project", Noteable.issue, 730,
+        discussion_id=threads[0].id,
+        body="Verified on TEST1.",
+    )
+
+asyncio.run(main())
+```
+
+`list_merge_request_notes` / `list_issue_notes` remain as thin aliases for
+`list_notes`.
+
+A body made up of **only** quick actions (e.g. `/milestone %"v2.0.6"`) creates no
+note — GitLab runs the command and returns the commands it executed instead. The
+reply helpers raise `QuickActionOnlyError` for that case, carrying the outcome so
+you can confirm the side effect landed:
+
+```python
+try:
+    await notes_service.reply_to_discussion(..., body='/milestone %"v2.0.6"')
+except QuickActionOnlyError as exc:
+    print(exc.summary)           # ['Set milestone to %"v2.0.6".']
+    print(exc.commands_changes)  # {'milestone': {...}}
+```
+
 ### WorkItems (GraphQL)
 
 `workItem` is GitLab's unified replacement for the legacy `Issue` type — use
@@ -234,6 +296,31 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+#### Custom statuses
+
+The workflow status an instance defines for itself (`Ready`, `In progress`, ...)
+is neither a label nor the open/closed `state`, and REST does not expose it.
+Reading it is opt-in, because GitLab ships the status widget as an experiment
+(**17.11+**) and selecting it against an older instance fails the whole query:
+
+```python
+# Just the status — one small query. Preferred on a hot path.
+status = await work_items_service.get_work_item_status(
+    42, project_path="my-group/my-project"
+)
+print(status.name if status else "no status set")
+
+# Or folded into a read you were making anyway.
+item = await work_items_service.get_work_item(
+    42, project_path="my-group/my-project", include_status=True
+)
+items = await work_items_service.search_work_items(
+    project_path="my-group/my-project", include_status=True
+)
+```
+
+Status names are configured per namespace — match them case-insensitively.
+
 ## Bundled agent skills
 
 Skill files for AI agents ship under `.agents/skills/` inside the installed package, following the [library-skills.io](https://library-skills.io/create/) convention. Topics: issues, workItems, merge requests, repository files, generic packages.

{pjdev_gitlab-5.1.12 → pjdev_gitlab-5.1.14}/README.md

@@ -164,6 +164,68 @@ asyncio.run(main())
 
 Run it: `op run --env-file=.env.op -- python my_script.py`.
 
+### Notes (comments) and replies
+
+`notes_service` reads and replies to comments on **both** issues and merge
+requests — they share the same endpoint shape, so one `Noteable` parameter
+selects which.
+
+GitLab only lets you reply to a *discussion* (a thread), never to a note id, so
+`reply_to_note` resolves the note to its containing thread for you:
+
+```python
+import asyncio
+from pjdev_gitlab import config_service, notes_service
+from pjdev_gitlab.notes_service import Noteable, QuickActionOnlyError
+
+async def main() -> None:
+    config_service.init()
+
+    # Fetch. Notes come back newest-first; pass sort="asc" to read in order.
+    notes = await notes_service.list_notes(
+        "my-group/my-project", Noteable.merge_request, 166,
+        include_system=False,   # drop "assigned to @x", "changed milestone", ...
+        sort="asc",
+    )
+
+    # Threads, when you need a discussion id to answer into.
+    threads = await notes_service.list_discussions(
+        "my-group/my-project", Noteable.merge_request, 166
+    )
+
+    # Reply, addressing the note you're answering.
+    await notes_service.reply_to_note(
+        "my-group/my-project", Noteable.merge_request, 166,
+        note_id=notes[0].id,
+        body="Good catch — fixed in the next push.",
+    )
+
+    # Or straight into a known thread.
+    await notes_service.reply_to_discussion(
+        "my-group/my-project", Noteable.issue, 730,
+        discussion_id=threads[0].id,
+        body="Verified on TEST1.",
+    )
+
+asyncio.run(main())
+```
+
+`list_merge_request_notes` / `list_issue_notes` remain as thin aliases for
+`list_notes`.
+
+A body made up of **only** quick actions (e.g. `/milestone %"v2.0.6"`) creates no
+note — GitLab runs the command and returns the commands it executed instead. The
+reply helpers raise `QuickActionOnlyError` for that case, carrying the outcome so
+you can confirm the side effect landed:
+
+```python
+try:
+    await notes_service.reply_to_discussion(..., body='/milestone %"v2.0.6"')
+except QuickActionOnlyError as exc:
+    print(exc.summary)           # ['Set milestone to %"v2.0.6".']
+    print(exc.commands_changes)  # {'milestone': {...}}
+```
+
 ### WorkItems (GraphQL)
 
 `workItem` is GitLab's unified replacement for the legacy `Issue` type — use
@@ -206,6 +268,31 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+#### Custom statuses
+
+The workflow status an instance defines for itself (`Ready`, `In progress`, ...)
+is neither a label nor the open/closed `state`, and REST does not expose it.
+Reading it is opt-in, because GitLab ships the status widget as an experiment
+(**17.11+**) and selecting it against an older instance fails the whole query:
+
+```python
+# Just the status — one small query. Preferred on a hot path.
+status = await work_items_service.get_work_item_status(
+    42, project_path="my-group/my-project"
+)
+print(status.name if status else "no status set")
+
+# Or folded into a read you were making anyway.
+item = await work_items_service.get_work_item(
+    42, project_path="my-group/my-project", include_status=True
+)
+items = await work_items_service.search_work_items(
+    project_path="my-group/my-project", include_status=True
+)
+```
+
+Status names are configured per namespace — match them case-insensitively.
+
 ## Bundled agent skills
 
 Skill files for AI agents ship under `.agents/skills/` inside the installed package, following the [library-skills.io](https://library-skills.io/create/) convention. Topics: issues, workItems, merge requests, repository files, generic packages.

{pjdev_gitlab-5.1.12 → pjdev_gitlab-5.1.14}/src/pjdev_gitlab/.agents/skills/pjdev_gitlab_work_items/SKILL.md

@@ -87,7 +87,7 @@ across_group = await work_items_service.search_work_items(
 )
 ```
 
-## View / update status
+## Open/closed state
 
 ```python
 from pjdev_gitlab.models import WorkItemStateEvent
@@ -100,6 +100,39 @@ await work_items_service.set_work_item_state(
 )
 ```
 
+## Custom status
+
+Separate from open/closed: the workflow status an instance defines for itself
+(`Ready`, `In progress`, `Code Complete`, ...). It is **not** a label, and the
+REST API does not expose it at all — GraphQL's status widget is the only way to
+read it.
+
+Reading it is opt-in, because the widget is a GitLab *experiment* introduced in
+**17.11**: selecting it against an older instance fails the entire query, so it
+is never requested unless asked for.
+
+```python
+# Just the status — one small query, no discussions dragged along.
+# This is the right call on a hot path (e.g. per webhook event).
+status = await work_items_service.get_work_item_status(42, project_path="group/proj")
+print(status.name if status else "no status set")
+
+# Or alongside everything else, when you were fetching the item anyway.
+item = await work_items_service.get_work_item(
+    42, project_path="group/proj", include_status=True
+)
+print(item.status.name if item.status else "no status set")
+
+# Also available on searches.
+items = await work_items_service.search_work_items(
+    project_path="group/proj", include_status=True
+)
+```
+
+`None` means the item has no status assigned. Status names are configured per
+namespace, so **match them case-insensitively** rather than hard-coding an enum —
+`"Code Complete"` on one instance may be `"code complete"` on another.
+
 ## Comments and threaded replies
 
 ```python

{pjdev_gitlab-5.1.12 → pjdev_gitlab-5.1.14}/src/pjdev_gitlab/__about__.py

@@ -1,4 +1,4 @@
 # SPDX-FileCopyrightText: 2026-present Chris O'Neill <chris@purplejay.io>
 #
 # SPDX-License-Identifier: MIT
-__version__ = "5.1.12"
+__version__ = "5.1.14"

{pjdev_gitlab-5.1.12 → pjdev_gitlab-5.1.14}/src/pjdev_gitlab/__init__.py

@@ -12,6 +12,7 @@ __all__ = [
     "issues_service",
     "merge_requests_service",
     "models",
+    "notes_service",
     "oauth_cli",
     "oauth_service",
     "packages_service",

{pjdev_gitlab-5.1.12 → pjdev_gitlab-5.1.14}/src/pjdev_gitlab/issues_service.py

@@ -6,6 +6,7 @@ from typing import Any, Dict, List, Literal, Optional
 from httpx import AsyncClient
 from loguru import logger
 
+from pjdev_gitlab import notes_service
 from pjdev_gitlab.api_utilities import (
     async_retry_http,
     encode_path_segment,
@@ -227,6 +228,31 @@ async def comment_on_issue(
     return await _exec(client)
 
 
+async def list_issue_notes(
+    project_id: ProjectId,
+    issue_iid: int,
+    *,
+    include_system: bool = True,
+    page_size: int = 100,
+    client: Optional[AsyncClient] = None,
+) -> List[Note]:
+    """Fetch every note on an issue.
+
+    Thin alias for :func:`pjdev_gitlab.notes_service.list_notes`; see that module
+    for threads, single-note reads, and replying. Deliberately undecorated -- the
+    delegate already retries, and stacking the decorator would square the attempt
+    count.
+    """
+    return await notes_service.list_notes(
+        project_id,
+        notes_service.Noteable.issue,
+        issue_iid,
+        include_system=include_system,
+        page_size=page_size,
+        client=client,
+    )
+
+
 @async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
 async def start_issue_discussion(
     project_id: ProjectId,

{pjdev_gitlab-5.1.12 → pjdev_gitlab-5.1.14}/src/pjdev_gitlab/merge_requests_service.py

@@ -2,6 +2,7 @@ from typing import Any, Dict, List, Optional
 
 from httpx import AsyncClient
 
+from pjdev_gitlab import notes_service
 from pjdev_gitlab.api_utilities import (
     async_retry_http,
     encode_path_segment,
@@ -181,24 +182,29 @@ async def comment_on_merge_request_diff(
     return await _exec(client)
 
 
-@async_retry_http(status_codes_to_ignore=_IGNORE_4XX)
 async def list_merge_request_notes(
     project_id: ProjectId,
     mr_iid: int,
     *,
+    include_system: bool = True,
     page_size: int = 100,
     client: Optional[AsyncClient] = None,
 ) -> List[Note]:
-    url = f"{_mr_base(project_id, mr_iid)}/notes"
+    """Fetch every note on a merge request.
 
-    async def _exec(_client: AsyncClient) -> List[Note]:
-        rows = await paginate(_client, url, params={}, page_size=page_size)
-        return [Note.model_validate(row) for row in rows]
-
-    if client is None:
-        async with http_client() as _client:
-            return await _exec(_client)
-    return await _exec(client)
+    Thin alias for :func:`pjdev_gitlab.notes_service.list_notes`; see that module
+    for threads, single-note reads, and replying. Deliberately undecorated -- the
+    delegate already retries, and stacking the decorator would square the attempt
+    count.
+    """
+    return await notes_service.list_notes(
+        project_id,
+        notes_service.Noteable.merge_request,
+        mr_iid,
+        include_system=include_system,
+        page_size=page_size,
+        client=client,
+    )
 
 
 @async_retry_http(status_codes_to_ignore=_IGNORE_4XX)

{pjdev_gitlab-5.1.12 → pjdev_gitlab-5.1.14}/src/pjdev_gitlab/models.py

@@ -265,6 +265,32 @@ class WorkItemIteration(GraphQLBase):
     web_url: Optional[str] = None
 
 
+class WorkItemStatus(GraphQLBase):
+    """A custom work-item status (``Ready``, ``In progress``, ``Code Complete``, ...).
+
+    Distinct from :class:`WorkItemState`, which is only ``OPEN``/``CLOSED``.
+    Statuses are defined per namespace, so the names are whatever the instance's
+    administrators configured — match them case-insensitively rather than
+    hard-coding an enum.
+
+    GitLab exposes this as an **experiment** (``WorkItemWidgetStatus``,
+    introduced in 17.11), which is why the widget is opt-in throughout
+    :mod:`pjdev_gitlab.work_items_service` — see ``include_status``. ``category``
+    and ``description`` are 18.1+ and are deliberately not selected, so the
+    queries here stay valid against 17.11.
+
+    Every field is optional: an instance may return a status object before it has
+    been fully configured, and a parse failure here would take down the whole
+    work-item read.
+    """
+
+    id: Optional[str] = None
+    name: Optional[str] = None
+    icon_name: Optional[str] = None
+    color: Optional[str] = None
+    position: Optional[int] = None
+
+
 class WorkItemNote(GraphQLBase):
     id: str
     body: str
@@ -316,6 +342,9 @@ class WorkItem(GraphQLBase):
     start_date: Optional[str] = None
     due_date: Optional[str] = None
     discussions: List[WorkItemDiscussion] = []
+    status: Optional[WorkItemStatus] = None
+    """Only populated when the read requested ``include_status=True``; ``None``
+    otherwise, which is indistinguishable from "this item has no status set"."""
 
     widgets: List[Dict[str, Any]] = []
 
@@ -345,6 +374,11 @@ class WorkItem(GraphQLBase):
             elif widget_type == "START_AND_DUE_DATE":
                 flat["start_date"] = widget.get("startDate")
                 flat["due_date"] = widget.get("dueDate")
+            elif widget_type == "STATUS":
+                # Only present when the query opted in via include_status; a work
+                # item with no status assigned still sends the widget, with a
+                # null status.
+                flat["status"] = widget.get("status")
             elif widget_type == "NOTES":
                 nodes = (widget.get("discussions") or {}).get("nodes") or []
                 flat["discussions"] = [