pjdev-gitlab 5.1.7__tar.gz → 5.1.9__tar.gz

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pjdev-gitlab
-Version: 5.1.7
+Version: 5.1.9
 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 the GitLab REST API v4 directly with `httpx.AsyncClient` and Pydantic models. Covers issues, 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), merge requests, repository files, and the generic package registry.
 
 -----
 
@@ -48,11 +48,38 @@ via `init()`):
 
 | variable | required | purpose |
 | --- | --- | --- |
-| `GL_TOKEN` | yes | personal/group/project access token (`api` scope) |
+| `GL_TOKEN` | yes | access token (`api` scope) — a PAT, or an OAuth token with `GL_AUTH_SCHEME=bearer` |
 | `GL_GITLAB_URL` | yes | base URL, e.g. `https://gitlab.com` |
+| `GL_AUTH_SCHEME` | no | `private-token` (default, PAT header) or `bearer` (OAuth access token) |
 | `GL_DEFAULT_PROJECT_ID` | no | default project for service helpers |
 | `GL_OUTPUT_PATH` | no | directory for downloaded files |
 
+### OAuth 2.0 (per-user attribution)
+
+To attribute API writes to a real person instead of a shared bot token, mint a
+short-lived OAuth access token with the interactive Authorization Code + PKCE
+flow and initialize with `auth_scheme="bearer"`:
+
+```python
+from pjdev_gitlab import config_service, oauth_service
+
+# Opens a browser for sign-in/consent on first run; caches + refreshes the token
+# per host under ~/.config/pjdev-gitlab/tokens/ (0600) on subsequent runs.
+token = oauth_service.get_access_token(
+    gitlab_url="https://gitlab.example.com",
+    client_id="<registered PKCE app client id>",
+)
+config_service.init(
+    token=token, gitlab_url="https://gitlab.example.com", auth_scheme="bearer"
+)
+```
+
+The OAuth application must be registered as a non-confidential (PKCE) app with
+**scope** `api` and **Redirect URI** exactly `http://localhost:7331/callback`
+(override the port via `get_access_token(redirect_port=...)`). A `bearer` token
+is sent as `Authorization: Bearer <token>`; the default `private-token` scheme
+sends `PRIVATE-TOKEN` for personal/project/group access tokens.
+
 ### Recommended: 1Password + `op run`
 
 On a developer laptop, keep the token in 1Password and inject it into the host
@@ -120,9 +147,51 @@ asyncio.run(main())
 
 Run it: `op run --env-file=.env.op -- python my_script.py`.
 
+### WorkItems (GraphQL)
+
+`workItem` is GitLab's unified replacement for the legacy `Issue` type — use
+`work_items_service` for status/comments/labels on modern GitLab instances:
+
+```python
+import asyncio
+from pjdev_gitlab import config_service, work_items_service
+from pjdev_gitlab.models import WorkItemState, WorkItemStateEvent
+
+async def main() -> None:
+    config_service.init()
+
+    open_bugs = await work_items_service.search_work_items(
+        project_path="my-group/my-project",
+        state=WorkItemState.OPEN,
+        labels=["bug"],
+        search="timeout",
+    )
+
+    label = await work_items_service.create_label(
+        "needs-review", project_path="my-group/my-project", color="#FFAA00"
+    )
+    await work_items_service.set_work_item_labels(
+        open_bugs[0].iid,
+        [label.id],
+        mode="add",
+        project_path="my-group/my-project",
+    )
+    await work_items_service.comment_on_work_item(
+        open_bugs[0].iid,
+        "Triaged — assigning a reviewer.",
+        project_path="my-group/my-project",
+    )
+    await work_items_service.set_work_item_state(
+        open_bugs[0].iid, WorkItemStateEvent.CLOSE,
+        project_path="my-group/my-project",
+    )
+
+asyncio.run(main())
+```
+
 ## 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, 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, merge requests, repository files, generic packages.
 
 ## License
 

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.9}/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 the GitLab REST API v4 directly with `httpx.AsyncClient` and Pydantic models. Covers issues, 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), merge requests, repository files, and the generic package registry.
 
 -----
 
@@ -20,11 +20,38 @@ via `init()`):
 
 | variable | required | purpose |
 | --- | --- | --- |
-| `GL_TOKEN` | yes | personal/group/project access token (`api` scope) |
+| `GL_TOKEN` | yes | access token (`api` scope) — a PAT, or an OAuth token with `GL_AUTH_SCHEME=bearer` |
 | `GL_GITLAB_URL` | yes | base URL, e.g. `https://gitlab.com` |
+| `GL_AUTH_SCHEME` | no | `private-token` (default, PAT header) or `bearer` (OAuth access token) |
 | `GL_DEFAULT_PROJECT_ID` | no | default project for service helpers |
 | `GL_OUTPUT_PATH` | no | directory for downloaded files |
 
+### OAuth 2.0 (per-user attribution)
+
+To attribute API writes to a real person instead of a shared bot token, mint a
+short-lived OAuth access token with the interactive Authorization Code + PKCE
+flow and initialize with `auth_scheme="bearer"`:
+
+```python
+from pjdev_gitlab import config_service, oauth_service
+
+# Opens a browser for sign-in/consent on first run; caches + refreshes the token
+# per host under ~/.config/pjdev-gitlab/tokens/ (0600) on subsequent runs.
+token = oauth_service.get_access_token(
+    gitlab_url="https://gitlab.example.com",
+    client_id="<registered PKCE app client id>",
+)
+config_service.init(
+    token=token, gitlab_url="https://gitlab.example.com", auth_scheme="bearer"
+)
+```
+
+The OAuth application must be registered as a non-confidential (PKCE) app with
+**scope** `api` and **Redirect URI** exactly `http://localhost:7331/callback`
+(override the port via `get_access_token(redirect_port=...)`). A `bearer` token
+is sent as `Authorization: Bearer <token>`; the default `private-token` scheme
+sends `PRIVATE-TOKEN` for personal/project/group access tokens.
+
 ### Recommended: 1Password + `op run`
 
 On a developer laptop, keep the token in 1Password and inject it into the host
@@ -92,9 +119,51 @@ asyncio.run(main())
 
 Run it: `op run --env-file=.env.op -- python my_script.py`.
 
+### WorkItems (GraphQL)
+
+`workItem` is GitLab's unified replacement for the legacy `Issue` type — use
+`work_items_service` for status/comments/labels on modern GitLab instances:
+
+```python
+import asyncio
+from pjdev_gitlab import config_service, work_items_service
+from pjdev_gitlab.models import WorkItemState, WorkItemStateEvent
+
+async def main() -> None:
+    config_service.init()
+
+    open_bugs = await work_items_service.search_work_items(
+        project_path="my-group/my-project",
+        state=WorkItemState.OPEN,
+        labels=["bug"],
+        search="timeout",
+    )
+
+    label = await work_items_service.create_label(
+        "needs-review", project_path="my-group/my-project", color="#FFAA00"
+    )
+    await work_items_service.set_work_item_labels(
+        open_bugs[0].iid,
+        [label.id],
+        mode="add",
+        project_path="my-group/my-project",
+    )
+    await work_items_service.comment_on_work_item(
+        open_bugs[0].iid,
+        "Triaged — assigning a reviewer.",
+        project_path="my-group/my-project",
+    )
+    await work_items_service.set_work_item_state(
+        open_bugs[0].iid, WorkItemStateEvent.CLOSE,
+        project_path="my-group/my-project",
+    )
+
+asyncio.run(main())
+```
+
 ## 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, 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, merge requests, repository files, generic packages.
 
 ## License
 

pjdev_gitlab-5.1.9/src/pjdev_gitlab/.agents/skills/pjdev_gitlab_work_items/SKILL.md

@@ -0,0 +1,173 @@
+---
+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.
+---
+
+# pjdev_gitlab_work_items
+
+Async helpers for GitLab workItems, built on `httpx.AsyncClient` against the
+[GitLab GraphQL API](https://docs.gitlab.com/api/graphql/).
+
+`workItem` is GitLab's unified replacement for the legacy `Issue` type. New
+behavior (custom statuses, hierarchy, the typed-issuable system) lives on
+workItems and is only reachable via GraphQL. Use this module instead of
+`issues_service` when working on a modern GitLab instance.
+
+Reference docs (source of truth for behavior):
+- [GraphQL API](https://docs.gitlab.com/api/graphql/)
+- [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/)
+- [Comments and threads](https://docs.gitlab.com/user/discussions/)
+
+## Setup
+
+`pjdev_gitlab` reads `GL_TOKEN` and `GL_GITLAB_URL` from the environment.
+Recommended pattern: keep the token in 1Password and inject it with
+[`op run`](https://developer.1password.com/docs/cli/secrets-environment-variables/).
+
+```bash
+# .env.op
+GL_TOKEN="op://Private/GitLab — <host>/credential"
+GL_GITLAB_URL="https://gitlab.example.com"
+```
+
+```bash
+op run --env-file=.env.op -- python my_script.py
+```
+
+```python
+from pjdev_gitlab import config_service, work_items_service
+
+config_service.init()  # token/url from env
+```
+
+The token needs `api` scope (mutations) or at least `read_api` (queries only).
+
+## Identifiers
+
+Every workItem-facing helper accepts either:
+
+- A **Global ID** like `gid://gitlab/WorkItem/12345`.
+- A **numeric DB id** (`12345`), which is auto-coerced to a Global ID.
+- A project/group-scoped **iid** (the number users see in the URL) plus
+  `project_path=...` or `group_path=...` — the helper resolves it to a
+  Global ID with one extra query.
+
+Pick whichever you have on hand:
+
+```python
+# By iid (common when scripting against URLs the user shared)
+item = await work_items_service.get_work_item(42, project_path="group/proj")
+
+# By Global ID (zero-lookup path)
+item = await work_items_service.get_work_item("gid://gitlab/WorkItem/12345")
+```
+
+## Search & filter
+
+`search_work_items` walks the namespace's `workItems` connection and follows
+`pageInfo.endCursor` until exhausted (set `paginate_results=False` for a
+single page). Either `project_path` or `group_path` is required.
+
+```python
+from pjdev_gitlab.models import WorkItemState
+
+open_bugs = await work_items_service.search_work_items(
+    project_path="group/proj",
+    state=WorkItemState.OPEN,
+    labels=["bug"],
+    search="timeout",  # matches title/description
+)
+
+across_group = await work_items_service.search_work_items(
+    group_path="group",
+    state=WorkItemState.OPEN,
+    page_size=50,
+)
+```
+
+## View / update status
+
+```python
+from pjdev_gitlab.models import WorkItemStateEvent
+
+item = await work_items_service.get_work_item(42, project_path="group/proj")
+print(item.state)  # WorkItemState.OPEN | CLOSED
+
+await work_items_service.set_work_item_state(
+    42, WorkItemStateEvent.CLOSE, project_path="group/proj"
+)
+```
+
+## Comments and threaded replies
+
+```python
+# Read all human comments (system notes filtered out by default)
+notes = await work_items_service.list_work_item_notes(
+    42, project_path="group/proj"
+)
+for n in notes:
+    print(n.author.username if n.author else "?", "->", n.body)
+
+# Post a new top-level comment (starts a new discussion thread)
+await work_items_service.comment_on_work_item(
+    42, "Looking into this now.", project_path="group/proj"
+)
+
+# Reply to an existing thread
+discussions = await work_items_service.list_work_item_discussions(
+    42, project_path="group/proj"
+)
+await work_items_service.reply_to_work_item_discussion(
+    42,
+    discussion_id=discussions[0].id,
+    body="Confirmed — pushing a fix shortly.",
+    project_path="group/proj",
+)
+```
+
+## Manage labels
+
+Label management uses a **delta API** — add or remove specific labels. There
+is no "replace" mode; compute the diff yourself if you need one.
+
+```python
+# Look up labels (includes parent group labels for projects)
+labels = await work_items_service.list_labels(
+    project_path="group/proj", search="prio"
+)
+# [ProjectLabel(id='gid://gitlab/ProjectLabel/7', title='priority::high', ...), ...]
+
+# Apply / remove on a workItem
+await work_items_service.set_work_item_labels(
+    42, [labels[0].id], mode="add", project_path="group/proj"
+)
+await work_items_service.set_work_item_labels(
+    42, [labels[0].id], mode="remove", project_path="group/proj"
+)
+
+# Create a brand-new project label
+new_label = await work_items_service.create_label(
+    "needs-review",
+    project_path="group/proj",
+    color="#FFAA00",
+    description="Awaiting reviewer triage",
+)
+```
+
+Group labels (visible to all child projects) are created the same way with
+`group_path=` instead of `project_path=`.
+
+## Tips for AI agents
+
+- Prefer batching label changes into one `set_work_item_labels(mode="add", labels=[a, b, c])`
+  call — that's one mutation instead of three.
+- When you only have an iid, pass `project_path=` once and reuse the
+  `WorkItem.id` (Global ID) on follow-up mutations to skip the lookup round-trip.
+- `WorkItem.state` is `OPEN`/`CLOSED` (uppercase, matches the GraphQL enum
+  directly), but the **filter** uses lowercase `opened`/`closed` — the helper
+  translates `WorkItemState.OPEN` automatically when you pass it to
+  `search_work_items(state=...)`.
+- A workItem returned by a mutation always reflects the post-mutation state,
+  so you can read `result.state` / `result.labels` instead of re-fetching.

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.9}/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.7"
+__version__ = "5.1.9"

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.9}/src/pjdev_gitlab/__init__.py

@@ -12,6 +12,8 @@ __all__ = [
     "issues_service",
     "merge_requests_service",
     "models",
+    "oauth_service",
     "packages_service",
     "repo_files_service",
+    "work_items_service",
 ]

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.9}/src/pjdev_gitlab/api_utilities.py

@@ -12,12 +12,32 @@ from loguru import logger
 from pjdev_gitlab.config_service import get_config
 
 
+class GraphQLError(RuntimeError):
+    """Raised when a GraphQL response contains top-level ``errors``.
+
+    The original error list is exposed on ``self.errors`` so callers can
+    inspect ``extensions`` (e.g. ``needsCaptchaResponse``) or match on
+    individual messages.
+    """
+
+    def __init__(self, errors: List[Dict[str, Any]]) -> None:
+        self.errors = errors
+        messages = "; ".join(str(e.get("message", e)) for e in errors)
+        super().__init__(messages)
+
+
 def encode_path_segment(value: Any) -> str:
     """URL-encode a path segment (e.g. project id 'group/sub/project' -> 'group%2Fsub%2Fproject')."""
     return quote(str(value), safe="")
 
 
 class GitlabTokenAuth(httpx.Auth):
+    """Send the credential in the ``PRIVATE-TOKEN`` header.
+
+    GitLab accepts this header for personal/project/group access tokens. This is
+    the default scheme (``config.auth_scheme == "private-token"``).
+    """
+
     def __init__(self, token: str) -> None:
         self.token = token
 
@@ -26,6 +46,30 @@ class GitlabTokenAuth(httpx.Auth):
         yield request
 
 
+class GitlabBearerAuth(httpx.Auth):
+    """Send the credential as an OAuth 2.0 ``Authorization: Bearer`` header.
+
+    GitLab requires OAuth access tokens (e.g. those minted by
+    :mod:`pjdev_gitlab.oauth_service`) to be sent as Bearer credentials; the
+    ``PRIVATE-TOKEN`` header is rejected for them. Selected when
+    ``config.auth_scheme == "bearer"``.
+    """
+
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def auth_flow(self, request):
+        request.headers["Authorization"] = f"Bearer {self.token}"
+        yield request
+
+
+def build_auth(config) -> httpx.Auth:
+    """Return the httpx auth for the configured scheme (bearer for OAuth tokens)."""
+    if str(config.auth_scheme).lower() == "bearer":
+        return GitlabBearerAuth(config.token)
+    return GitlabTokenAuth(config.token)
+
+
 async def log_request_headers(request: httpx.Request) -> None:
     logger.debug(f"Request: {request.method} {request.url}")
 
@@ -43,7 +87,7 @@ def get_http_client() -> httpx.AsyncClient:
 
     return httpx.AsyncClient(
         base_url=config.api_base_url,
-        auth=GitlabTokenAuth(config.token),
+        auth=build_auth(config),
         verify=ssl.create_default_context() if config.verify_ssl else False,
         timeout=config.request_timeout_seconds,
         event_hooks={
@@ -59,6 +103,114 @@ async def http_client() -> AsyncIterator[httpx.AsyncClient]:
         yield _client
 
 
+def get_graphql_client() -> httpx.AsyncClient:
+    """Build an httpx client pointed at the instance root.
+
+    The GraphQL endpoint lives at ``{gitlab_url}/api/graphql`` (NOT under
+    ``/api/v4``), so it can't share a ``base_url`` with the REST helpers.
+    """
+    config = get_config()
+    if not config.token:
+        raise ValueError("GitLab token is not configured -- set GL_TOKEN or pass token=...")
+
+    return httpx.AsyncClient(
+        base_url=config.gitlab_url.rstrip("/"),
+        auth=build_auth(config),
+        verify=ssl.create_default_context() if config.verify_ssl else False,
+        timeout=config.request_timeout_seconds,
+        event_hooks={
+            "request": [log_request_headers],
+            "response": [log_response_headers],
+        },
+    )
+
+
+@asynccontextmanager
+async def graphql_client() -> AsyncIterator[httpx.AsyncClient]:
+    async with get_graphql_client() as _client:
+        yield _client
+
+
+async def graphql(
+    query: str,
+    variables: Optional[Dict[str, Any]] = None,
+    *,
+    client: Optional[httpx.AsyncClient] = None,
+) -> Dict[str, Any]:
+    """Execute a GraphQL query or mutation and return the ``data`` payload.
+
+    Raises :class:`GraphQLError` when the response contains top-level
+    ``errors``. Resource-level errors that GitLab surfaces as part of a
+    mutation's payload (e.g. ``mutationName.errors``) are returned as-is
+    in the data and are the caller's responsibility to check.
+    """
+    payload: Dict[str, Any] = {"query": query, "variables": variables or {}}
+
+    async def _exec(_client: httpx.AsyncClient) -> Dict[str, Any]:
+        r = await _client.post("/api/graphql", json=payload)
+        r.raise_for_status()
+        body = r.json()
+        if body.get("errors"):
+            raise GraphQLError(body["errors"])
+        return body.get("data") or {}
+
+    if client is None:
+        async with graphql_client() as _client:
+            return await _exec(_client)
+    return await _exec(client)
+
+
+async def paginate_graphql(
+    query: str,
+    variables: Dict[str, Any],
+    *,
+    connection_path: List[str],
+    page_size: int = 100,
+    client: Optional[httpx.AsyncClient] = None,
+) -> List[Dict[str, Any]]:
+    """Follow ``pageInfo.endCursor`` through a Relay-style GraphQL connection.
+
+    The supplied ``query`` MUST declare an ``$after: String`` variable, pass it
+    as ``after: $after`` to the connection, and select both ``pageInfo {
+    endCursor hasNextPage }`` and ``nodes { ... }``. ``connection_path`` is the
+    list of keys to walk from the top of ``data`` down to the connection
+    object (e.g. ``["group", "workItems"]``).
+
+    The variable ``first`` is set to ``page_size`` on every page.
+    """
+
+    def _walk(data: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+        current: Any = data
+        for key in connection_path:
+            if current is None:
+                return None
+            current = current.get(key)
+        return current
+
+    nodes: List[Dict[str, Any]] = []
+    page_vars: Dict[str, Any] = {**variables, "first": page_size, "after": None}
+
+    async def _run(_client: Optional[httpx.AsyncClient]) -> None:
+        while True:
+            data = await graphql(query, page_vars, client=_client)
+            connection = _walk(data)
+            if connection is None:
+                break
+            nodes.extend(connection.get("nodes") or [])
+            page_info = connection.get("pageInfo") or {}
+            if not page_info.get("hasNextPage"):
+                break
+            page_vars["after"] = page_info.get("endCursor")
+
+    if client is None:
+        async with graphql_client() as _client:
+            await _run(_client)
+    else:
+        await _run(client)
+
+    return nodes
+
+
 def async_retry_http(
     default_value: Optional[Any] = None,
     status_codes_to_ignore: Optional[List[int]] = None,

{pjdev_gitlab-5.1.7 → pjdev_gitlab-5.1.9}/src/pjdev_gitlab/config_service.py

@@ -16,6 +16,7 @@ def init(
     env_path: Optional[Path] = None,
     token: Optional[str] = None,
     gitlab_url: Optional[str] = None,
+    auth_scheme: Optional[str] = None,
     default_project_id: Optional[ProjectId] = None,
     output_path: Optional[Path] = None,
     http_retry_max_count: Optional[int] = None,
@@ -31,6 +32,8 @@ def init(
         kwargs["token"] = token
     if gitlab_url is not None:
         kwargs["gitlab_url"] = gitlab_url
+    if auth_scheme is not None:
+        kwargs["auth_scheme"] = auth_scheme
     if default_project_id is not None:
         kwargs["default_project_id"] = default_project_id
     if output_path is not None: