pjdev-gitlab 5.3.0__tar.gz → 2026.1007.82101__tar.gz

{pjdev_gitlab-5.3.0 → pjdev_gitlab-2026.1007.82101}/.gitignore

@@ -165,4 +165,6 @@ cython_debug/
 #.idea/
 
 **/uv.lock
-!./uv.lock
+!./uv.lock
+# Local scratch CLI for exercising libraries
+cli_testing/

{pjdev_gitlab-5.3.0 → pjdev_gitlab-2026.1007.82101}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pjdev-gitlab
-Version: 5.3.0
+Version: 2026.1007.82101
 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
@@ -31,7 +31,7 @@ Description-Content-Type: text/markdown
 [![PyPI - Version](https://img.shields.io/pypi/v/pjdev-gitlab.svg)](https://pypi.org/project/pjdev-gitlab)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pjdev-gitlab.svg)](https://pypi.org/project/pjdev-gitlab)
 
-Async GitLab automation SDK. Wraps both the GitLab REST API v4 and GraphQL API directly with `httpx.AsyncClient` and Pydantic models. Covers issues, workItems (the GraphQL replacement for issues — status, comments, labels), merge requests, repository files, and the generic package registry.
+Async GitLab automation SDK. Wraps both the GitLab REST API v4 and GraphQL API directly with `httpx.AsyncClient` and Pydantic models. Covers issues, workItems (the GraphQL replacement for issues — status, comments, labels, custom fields), merge requests, repository files, and the generic package registry.
 
 -----
 
@@ -383,9 +383,52 @@ items = await work_items_service.search_work_items(
 
 Status names are configured per namespace — match them case-insensitively.
 
+#### Custom fields
+
+Custom fields are typed properties (single/multi select, number, text, date)
+defined on a **top-level group** and inherited by every subgroup and project
+under it (Premium/Ultimate, GitLab 18.0+). `custom_fields_service` accepts
+either `group_path` or `project_path` everywhere and resolves it to that group:
+
+```python
+from pjdev_gitlab import custom_fields_service
+from pjdev_gitlab.models import CustomFieldType
+
+# Define once — lands on "my-group", the project's top-level group.
+team = await custom_fields_service.create_custom_field(
+    "Team",
+    CustomFieldType.SINGLE_SELECT,
+    project_path="my-group/my-project",
+    select_options=["Platform", "Payments"],
+    work_item_types=["Issue", "Task"],   # names, ids or Global IDs
+)
+await custom_fields_service.create_custom_field(
+    "Story points", CustomFieldType.NUMBER,
+    group_path="my-group", work_item_types=["Issue"],
+)
+
+# Set values on a work item: keyed by field name, plain Python values.
+await custom_fields_service.set_work_item_custom_fields(
+    42,
+    {"Team": "Platform", "Story points": 5},
+    project_path="my-group/my-project",
+)
+values = await custom_fields_service.get_work_item_custom_field_values(
+    42, project_path="my-group/my-project"
+)
+```
+
+Values are validated against the field definition before anything is sent;
+`None` clears a field. Updating many items? Fetch the definitions once with
+`list_custom_fields` and pass them as `fields=` to skip the per-call lookup.
+`update_custom_field(select_options=...)` **replaces** the option list (dropped
+options lose their selections) — use `add_custom_field_select_options` to
+append. There is no delete: `archive_custom_field` hides a field and keeps its
+values for `unarchive_custom_field`.
+
 ## 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.
+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 (including custom fields), merge requests, repository files, generic packages.
 
 ## License
 

{pjdev_gitlab-5.3.0 → pjdev_gitlab-2026.1007.82101}/README.md

@@ -3,7 +3,7 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/pjdev-gitlab.svg)](https://pypi.org/project/pjdev-gitlab)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pjdev-gitlab.svg)](https://pypi.org/project/pjdev-gitlab)
 
-Async GitLab automation SDK. Wraps both the GitLab REST API v4 and GraphQL API directly with `httpx.AsyncClient` and Pydantic models. Covers issues, workItems (the GraphQL replacement for issues — status, comments, labels), merge requests, repository files, and the generic package registry.
+Async GitLab automation SDK. Wraps both the GitLab REST API v4 and GraphQL API directly with `httpx.AsyncClient` and Pydantic models. Covers issues, workItems (the GraphQL replacement for issues — status, comments, labels, custom fields), merge requests, repository files, and the generic package registry.
 
 -----
 
@@ -355,9 +355,52 @@ items = await work_items_service.search_work_items(
 
 Status names are configured per namespace — match them case-insensitively.
 
+#### Custom fields
+
+Custom fields are typed properties (single/multi select, number, text, date)
+defined on a **top-level group** and inherited by every subgroup and project
+under it (Premium/Ultimate, GitLab 18.0+). `custom_fields_service` accepts
+either `group_path` or `project_path` everywhere and resolves it to that group:
+
+```python
+from pjdev_gitlab import custom_fields_service
+from pjdev_gitlab.models import CustomFieldType
+
+# Define once — lands on "my-group", the project's top-level group.
+team = await custom_fields_service.create_custom_field(
+    "Team",
+    CustomFieldType.SINGLE_SELECT,
+    project_path="my-group/my-project",
+    select_options=["Platform", "Payments"],
+    work_item_types=["Issue", "Task"],   # names, ids or Global IDs
+)
+await custom_fields_service.create_custom_field(
+    "Story points", CustomFieldType.NUMBER,
+    group_path="my-group", work_item_types=["Issue"],
+)
+
+# Set values on a work item: keyed by field name, plain Python values.
+await custom_fields_service.set_work_item_custom_fields(
+    42,
+    {"Team": "Platform", "Story points": 5},
+    project_path="my-group/my-project",
+)
+values = await custom_fields_service.get_work_item_custom_field_values(
+    42, project_path="my-group/my-project"
+)
+```
+
+Values are validated against the field definition before anything is sent;
+`None` clears a field. Updating many items? Fetch the definitions once with
+`list_custom_fields` and pass them as `fields=` to skip the per-call lookup.
+`update_custom_field(select_options=...)` **replaces** the option list (dropped
+options lose their selections) — use `add_custom_field_select_options` to
+append. There is no delete: `archive_custom_field` hides a field and keeps its
+values for `unarchive_custom_field`.
+
 ## 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.
+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 (including custom fields), merge requests, repository files, generic packages.
 
 ## License
 

{pjdev_gitlab-5.3.0 → pjdev_gitlab-2026.1007.82101}/src/pjdev_gitlab/.agents/skills/pjdev_gitlab_work_items/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pjdev_gitlab_work_items
-description: Use this skill to automate GitLab workItems via pjdev-gitlab — the GraphQL-backed successor to issues. Covers searching/filtering by project or group with pagination, viewing/updating status, reading/posting/replying to comments, and managing labels (including creating new project or group labels). Trigger when the user asks to query, create, or modify GitLab workItems (or "issues" on a recent GitLab instance) programmatically.
+description: Use this skill to automate GitLab workItems via pjdev-gitlab — the GraphQL-backed successor to issues. Covers searching/filtering by project or group with pagination, viewing/updating status, reading/posting/replying to comments, managing labels (including creating new project or group labels), and defining/setting custom fields (typed work item properties). Trigger when the user asks to query, create, or modify GitLab workItems (or "issues" on a recent GitLab instance) programmatically.
 ---
 
 # pjdev_gitlab_work_items
@@ -18,6 +18,7 @@ Reference docs (source of truth for behavior):
 - [GraphQL reference](https://docs.gitlab.com/api/graphql/reference/)
 - [WorkItems](https://docs.gitlab.com/user/work_items/)
 - [Labels](https://docs.gitlab.com/user/project/labels/)
+- [Custom fields](https://docs.gitlab.com/user/work_items/custom_fields/)
 - [Comments and threads](https://docs.gitlab.com/user/discussions/)
 
 ## Setup
@@ -133,6 +134,78 @@ items = await work_items_service.search_work_items(
 namespace, so **match them case-insensitively** rather than hard-coding an enum —
 `"Code Complete"` on one instance may be `"code complete"` on another.
 
+## Custom fields
+
+Typed properties on work items — `SINGLE_SELECT`, `MULTI_SELECT`, `NUMBER`,
+`TEXT`, `DATE` — via `custom_fields_service`. Premium/Ultimate, GitLab 18.0+.
+
+Definitions live **only on the top-level group** and are inherited by every
+subgroup and project below it. Every helper takes `group_path=` or
+`project_path=` and resolves to that group, so you never need to work out the
+root yourself. Each field is shown only on the work item types it is
+associated with — create it without `work_item_types` and it appears nowhere.
+
+```python
+import datetime
+
+from pjdev_gitlab import custom_fields_service
+from pjdev_gitlab.models import CustomFieldType
+
+# What exists already (active only by default; active=None for archived too)
+fields = await custom_fields_service.list_custom_fields(project_path="group/proj")
+types = await custom_fields_service.list_work_item_types(project_path="group/proj")
+
+# Define (Maintainer+ on the top-level group)
+team = await custom_fields_service.create_custom_field(
+    "Team",
+    CustomFieldType.SINGLE_SELECT,
+    project_path="group/proj",          # -> created on "group"
+    select_options=["Platform", "Payments"],
+    work_item_types=["Issue", "Task"],  # names, numeric ids or Global IDs
+)
+
+# Grow a select field without disturbing existing selections
+team = await custom_fields_service.add_custom_field_select_options(team, ["Mobile"])
+
+# Set values: keys are field names (case-insensitive) or Global IDs
+await custom_fields_service.set_work_item_custom_fields(
+    42,
+    {
+        "Team": "platform",                   # option value or option Global ID
+        "Components": ["API", "UI"],         # multi-select replaces the selection
+        "Story points": 5,
+        "Customer": "Acme",
+        "Target date": datetime.date(2026, 11, 1),
+        "Old field": None,                   # None clears
+    },
+    project_path="group/proj",
+)
+
+# Read
+for v in await custom_fields_service.get_work_item_custom_field_values(
+    42, project_path="group/proj"
+):
+    print(v.custom_field.name, v.value, [o.value for o in v.selected_options])
+```
+
+Gotchas:
+
+- `set_work_item_custom_fields` validates every value against the field type
+  and its options **before** sending; an unknown field or option raises
+  `ValueError` (wrapped in an `ExceptionGroup` by the retry decorator) listing
+  what is valid. Fields you do not name are left untouched.
+- GitLab answers "Invalid custom field ID" when the field is archived or not
+  associated with the item's work item type.
+- Bulk updates: call `list_custom_fields` once and pass `fields=` — otherwise
+  every call re-lists the definitions.
+- `update_custom_field(select_options=...)` **replaces** the whole option list:
+  pass existing `CustomFieldSelectOption` objects to keep them, strings to add.
+  Omitted options are deleted along with their selections on work items.
+- No hard delete: `archive_custom_field` hides a field (values kept),
+  `unarchive_custom_field` restores it.
+- Limits: 50 active fields per group, 10 per work item type, 50 options per
+  select field, 1024 characters per text value.
+
 ## Comments and threaded replies
 
 ```python

{pjdev_gitlab-5.3.0 → pjdev_gitlab-2026.1007.82101}/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.3.0"
+__version__ = "2026.1007.82101"

{pjdev_gitlab-5.3.0 → pjdev_gitlab-2026.1007.82101}/src/pjdev_gitlab/__init__.py

@@ -9,6 +9,7 @@ logger.disable("pjdev_gitlab")
 __all__ = [
     "api_utilities",
     "config_service",
+    "custom_fields_service",
     "issues_service",
     "merge_requests_service",
     "models",

{pjdev_gitlab-5.3.0 → pjdev_gitlab-2026.1007.82101}/src/pjdev_gitlab/api_utilities.py

@@ -166,6 +166,7 @@ async def paginate_graphql(
     *,
     connection_path: List[str],
     page_size: int = 100,
+    require_connection: bool = False,
     client: Optional[httpx.AsyncClient] = None,
 ) -> List[Dict[str, Any]]:
     """Follow ``pageInfo.endCursor`` through a Relay-style GraphQL connection.
@@ -177,6 +178,10 @@ async def paginate_graphql(
     object (e.g. ``["group", "workItems"]``).
 
     The variable ``first`` is set to ``page_size`` on every page.
+
+    GraphQL answers an unknown or inaccessible ``fullPath`` with ``null`` rather
+    than an error, which reads as "no results". ``require_connection=True``
+    raises :class:`LookupError` instead when the connection is missing.
     """
 
     def _walk(data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
@@ -195,6 +200,12 @@ async def paginate_graphql(
             data = await graphql(query, page_vars, client=_client)
             connection = _walk(data)
             if connection is None:
+                if require_connection:
+                    raise LookupError(
+                        f"{'.'.join(connection_path)} not found: "
+                        f"{variables.get('path', '<path>')!r} does not exist "
+                        "or is not visible to this token"
+                    )
                 break
             nodes.extend(connection.get("nodes") or [])
             page_info = connection.get("pageInfo") or {}