Add find_team, find_user, find_project, and find_label resolvers

Author: eli-the-wizard

README.md

@@ -162,6 +162,33 @@ for child in detail.children:
     print("sub-issue:", child.identifier, child.title)
 ```
 
+## Looking things up by name (instead of UUIDs)
+
+Most calls take UUIDs. Use the `find_*` resolvers to turn a human name/key/email into
+the entity (and its `.id`) first:
+
+```python
+from linear_python_client import (
+    FindTeamRequest, FindUserRequest, FindProjectRequest, FindLabelRequest,
+    IssueCreateRequest,
+)
+
+team = client.find_team(FindTeamRequest(key="RAV")).team        # or name="Ravens"
+assignee = client.find_user(FindUserRequest(name="Elijah Winter")).user  # or email=...
+bug = client.find_label(FindLabelRequest(name="bug", team_id=team.id)).label
+
+client.create_issue(IssueCreateRequest(
+    team_id=team.id,
+    title="New issue",
+    assignee_id=assignee.id,
+    label_ids=[bug.id],
+))
+```
+
+Each resolver returns the matching entity, or `None` if nothing matches. Name matching
+is case-insensitive; team `key` is matched exactly. `find_workflow_state` (for statuses)
+works the same way.
+
 ## Escape hatch: raw GraphQL
 
 Anything not covered by a convenience method can be run directly. `execute()`
@@ -225,8 +252,12 @@ Each method maps a `*Request` to a `*Response`:
 | `comments(...)` | `CommentsRequest` | `CommentsResponse` |
 | `create_comment(...)` | `CommentCreateRequest` | `CreateCommentResponse` |
 | `workflow_states(...)` | `WorkflowStatesRequest` | `WorkflowStatesResponse` |
-| `find_workflow_state(...)` | `FindWorkflowStateRequest` | `WorkflowStateResponse` |
 | `issue_labels(...)` | `IssueLabelsRequest` | `IssueLabelsResponse` |
+| `find_team(...)` | `FindTeamRequest` | `TeamResponse` |
+| `find_user(...)` | `FindUserRequest` | `UserResponse` |
+| `find_project(...)` | `FindProjectRequest` | `ProjectResponse` |
+| `find_label(...)` | `FindLabelRequest` | `IssueLabelResponse` |
+| `find_workflow_state(...)` | `FindWorkflowStateRequest` | `WorkflowStateResponse` |
 | `execute(query, variables)` | – | `dict` |
 | `paginate(method, request)` | a `*Request` | iterator of nodes |
 

docs/api/requests.md

@@ -28,4 +28,8 @@ method takes exactly one of these.
         - IssueRemoveLabelRequest
         - IssueSetStateRequest
         - FindWorkflowStateRequest
+        - FindTeamRequest
+        - FindUserRequest
+        - FindProjectRequest
+        - FindLabelRequest
         - CommentCreateRequest

docs/api/responses.md

@@ -23,6 +23,7 @@ The typed result models returned by each
         - CommentsResponse
         - WorkflowStateResponse
         - WorkflowStatesResponse
+        - IssueLabelResponse
         - IssueLabelsResponse
         - CreateIssueResponse
         - UpdateIssueResponse

docs/usage.md

@@ -214,6 +214,23 @@ states = client.workflow_states(WorkflowStatesRequest(team_id="..."))
 labels = client.issue_labels(IssueLabelsRequest(first=100))
 ```
 
+## Resolving names to UUIDs
+
+Most methods take UUIDs. The `find_*` resolvers turn a human name/key/email into the
+entity (read its `.id` to pass elsewhere). Each returns the matching entity or `None`;
+name matching is case-insensitive, team `key` is exact.
+
+```python
+from linear_python_client import (
+    FindTeamRequest, FindUserRequest, FindProjectRequest, FindLabelRequest,
+)
+
+team = client.find_team(FindTeamRequest(key="RAV")).team           # or name="Ravens"
+user = client.find_user(FindUserRequest(name="Elijah Winter")).user  # or email="..."
+project = client.find_project(FindProjectRequest(name="Roadmap")).project
+bug = client.find_label(FindLabelRequest(name="bug", team_id=team.id)).label
+```
+
 ## Raw GraphQL
 
 Anything not covered by a typed method can be run directly with

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "linear-python-client"
-version = "0.1.1"
+version = "0.2.0"
 description = "Pragmatic Python client for the Linear GraphQL API"
 readme = "README.md"
 license = "MIT"

scripts/smoke_test.py

@@ -29,6 +29,10 @@
     CommentCreateRequest,
     CommentRequest,
     CommentsRequest,
+    FindLabelRequest,
+    FindProjectRequest,
+    FindTeamRequest,
+    FindUserRequest,
     FindWorkflowStateRequest,
     IssueAddLabelRequest,
     IssueArchiveRequest,
@@ -162,6 +166,30 @@ def main() -> int:
         except Exception as exc:  # noqa: BLE001
             r.check("paginate(issues)", False, f"raised {type(exc).__name__}: {exc}")
 
+        # -- name/key resolvers ---------------------------------------------
+        section("Resolvers (name/key -> entity)")
+        resolved_team = r.run(
+            "find_team(by key)",
+            lambda: client.find_team(FindTeamRequest(key=team.key)).team,
+        )
+        r.check(
+            "find_team resolves to same id",
+            bool(resolved_team and resolved_team.id == team_id),
+        )
+        if viewer and viewer.name:
+            found_user = r.run(
+                "find_user(by name)",
+                lambda: client.find_user(FindUserRequest(name=viewer.name)).user,
+            )
+            r.check("find_user resolves to a user", bool(found_user and found_user.id))
+        if projects:
+            r.run(
+                "find_project(by name)",
+                lambda: client.find_project(FindProjectRequest(name=projects[0].name)).project,
+            )
+        else:
+            r.skip("find_project()", "no projects in workspace")
+
         # -- create + verify ------------------------------------------------
         section("Create issue (+ pull to verify)")
         title = f"{MARKER} {int(time.time())}"
@@ -244,6 +272,13 @@ def pull():
             )
             if team_labels:
                 label = team_labels[0]
+                resolved_label = r.run(
+                    "find_label(by name)",
+                    lambda: client.find_label(
+                        FindLabelRequest(name=label.name, team_id=team_id)
+                    ).label,
+                )
+                r.check("find_label resolves a label", bool(resolved_label and resolved_label.id))
                 r.run(
                     "add_label()",
                     lambda: client.add_label(

src/linear_python_client/__init__.py

@@ -29,6 +29,10 @@
     CommentCreateRequest,
     CommentRequest,
     CommentsRequest,
+    FindLabelRequest,
+    FindProjectRequest,
+    FindTeamRequest,
+    FindUserRequest,
     FindWorkflowStateRequest,
     IssueAddLabelRequest,
     IssueArchiveRequest,
@@ -57,6 +61,7 @@
     CreateCommentResponse,
     CreateIssueResponse,
     IssueDetailsResponse,
+    IssueLabelResponse,
     IssueLabelsResponse,
     IssueResponse,
     IssuesResponse,
@@ -73,7 +78,7 @@
     WorkflowStatesResponse,
 )
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 __all__ = [
     "DEFAULT_ENDPOINT",
@@ -113,6 +118,10 @@
     "IssueRemoveLabelRequest",
     "IssueSetStateRequest",
     "FindWorkflowStateRequest",
+    "FindTeamRequest",
+    "FindUserRequest",
+    "FindLabelRequest",
+    "FindProjectRequest",
     "ProjectRequest",
     "ProjectsRequest",
     "CommentRequest",
@@ -142,6 +151,7 @@
     "CreateCommentResponse",
     "WorkflowStateResponse",
     "WorkflowStatesResponse",
+    "IssueLabelResponse",
     "IssueLabelsResponse",
     "__version__",
 ]

src/linear_python_client/client.py

@@ -24,6 +24,10 @@
     CommentCreateRequest,
     CommentRequest,
     CommentsRequest,
+    FindLabelRequest,
+    FindProjectRequest,
+    FindTeamRequest,
+    FindUserRequest,
     FindWorkflowStateRequest,
     IssueAddLabelRequest,
     IssueArchiveRequest,
@@ -52,6 +56,7 @@
     CreateCommentResponse,
     CreateIssueResponse,
     IssueDetailsResponse,
+    IssueLabelResponse,
     IssueLabelsResponse,
     IssueResponse,
     IssuesResponse,
@@ -83,6 +88,12 @@ def _to_int(value: str | None) -> int | None:
         return None
 
 
+def _first_node(data: dict[str, Any], key: str) -> dict[str, Any] | None:
+    """Return the first node of a connection in ``data[key]``, or ``None``."""
+    nodes = (data.get(key) or {}).get("nodes") or []
+    return nodes[0] if nodes else None
+
+
 class LinearClient:
     """Client for Linear's GraphQL API.
 
@@ -556,17 +567,66 @@ def find_workflow_state(self, request: FindWorkflowStateRequest) -> WorkflowStat
             A [`WorkflowStateResponse`][linear_python_client.WorkflowStateResponse];
             `.state` is `None` if no state matches.
         """
-        variables = {
-            "first": 1,
-            "after": None,
-            "filter": {
-                "team": {"id": {"eq": request.team_id}},
-                "name": {"eqIgnoreCase": request.name},
-            },
+        filter_ = {
+            "team": {"id": {"eq": request.team_id}},
+            "name": {"eqIgnoreCase": request.name},
         }
-        data = self.execute(queries.WORKFLOW_STATES, variables)
-        nodes = (data.get("workflowStates") or {}).get("nodes") or []
-        return WorkflowStateResponse.model_validate({"state": nodes[0] if nodes else None})
+        data = self.execute(queries.WORKFLOW_STATES, {"first": 1, "filter": filter_})
+        return WorkflowStateResponse.model_validate({"state": _first_node(data, "workflowStates")})
+
+    def find_team(self, request: FindTeamRequest) -> TeamResponse:
+        """Resolve a team by display name or key.
+
+        Args:
+            request: A [`FindTeamRequest`][linear_python_client.FindTeamRequest]
+                with `name` and/or `key`.
+
+        Returns:
+            A [`TeamResponse`][linear_python_client.TeamResponse]; `.team` is
+            `None` if no team matches.
+        """
+        data = self.execute(queries.TEAMS, {"first": 1, "filter": request.to_filter()})
+        return TeamResponse.model_validate({"team": _first_node(data, "teams")})
+
+    def find_user(self, request: FindUserRequest) -> UserResponse:
+        """Resolve a user by name, display name, or email.
+
+        Args:
+            request: A [`FindUserRequest`][linear_python_client.FindUserRequest]
+                with `name` and/or `email`.
+
+        Returns:
+            A [`UserResponse`][linear_python_client.UserResponse]; `.user` is
+            `None` if no user matches.
+        """
+        data = self.execute(queries.USERS, {"first": 1, "filter": request.to_filter()})
+        return UserResponse.model_validate({"user": _first_node(data, "users")})
+
+    def find_project(self, request: FindProjectRequest) -> ProjectResponse:
+        """Resolve a project by name (case-insensitive).
+
+        Args:
+            request: A [`FindProjectRequest`][linear_python_client.FindProjectRequest].
+
+        Returns:
+            A [`ProjectResponse`][linear_python_client.ProjectResponse]; `.project`
+            is `None` if no project matches.
+        """
+        data = self.execute(queries.PROJECTS, {"first": 1, "filter": request.to_filter()})
+        return ProjectResponse.model_validate({"project": _first_node(data, "projects")})
+
+    def find_label(self, request: FindLabelRequest) -> IssueLabelResponse:
+        """Resolve an issue label by name, optionally scoped to a team.
+
+        Args:
+            request: A [`FindLabelRequest`][linear_python_client.FindLabelRequest].
+
+        Returns:
+            An [`IssueLabelResponse`][linear_python_client.IssueLabelResponse];
+            `.label` is `None` if no label matches.
+        """
+        data = self.execute(queries.ISSUE_LABELS, {"first": 1, "filter": request.to_filter()})
+        return IssueLabelResponse.model_validate({"label": _first_node(data, "issueLabels")})
 
     def issue_labels(self, request: IssueLabelsRequest | None = None) -> IssueLabelsResponse:
         """List issue labels in the workspace.

src/linear_python_client/models/__init__.py

@@ -25,6 +25,10 @@
     CommentCreateRequest,
     CommentRequest,
     CommentsRequest,
+    FindLabelRequest,
+    FindProjectRequest,
+    FindTeamRequest,
+    FindUserRequest,
     FindWorkflowStateRequest,
     IssueAddLabelRequest,
     IssueArchiveRequest,
@@ -53,6 +57,7 @@
     CreateCommentResponse,
     CreateIssueResponse,
     IssueDetailsResponse,
+    IssueLabelResponse,
     IssueLabelsResponse,
     IssueResponse,
     IssuesResponse,
@@ -99,6 +104,10 @@
     "IssueRemoveLabelRequest",
     "IssueSetStateRequest",
     "FindWorkflowStateRequest",
+    "FindTeamRequest",
+    "FindUserRequest",
+    "FindLabelRequest",
+    "FindProjectRequest",
     "ProjectRequest",
     "ProjectsRequest",
     "CommentRequest",
@@ -128,5 +137,6 @@
     "CreateCommentResponse",
     "WorkflowStateResponse",
     "WorkflowStatesResponse",
+    "IssueLabelResponse",
     "IssueLabelsResponse",
 ]