linear-python-client 0.1.1__tar.gz → 0.2.1__tar.gz

{linear_python_client-0.1.1 → linear_python_client-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linear-python-client
-Version: 0.1.1
+Version: 0.2.1
 Summary: Pragmatic Python client for the Linear GraphQL API
 Keywords: linear,linear.app,graphql,api,client,sdk
 Author: eli-the-wizard
@@ -11,12 +11,12 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: httpx>=0.27
 Requires-Dist: pydantic>=2.7
-Requires-Python: >=3.14
+Requires-Python: >=3.13
 Project-URL: Homepage, https://github.com/Hacker0x01/linear-python-client
 Project-URL: Documentation, https://hacker0x01.github.io/linear-python-client/
 Project-URL: Repository, https://github.com/Hacker0x01/linear-python-client
@@ -50,7 +50,7 @@ Or for local development of this repo:
 uv sync
 ```
 
-Requires Python 3.14+.
+Requires Python 3.13+.
 
 ## Authentication
 
@@ -187,6 +187,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()`
@@ -250,8 +277,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 |
 
@@ -316,7 +347,7 @@ To cut a release: bump `version` in `pyproject.toml`, then create a matching Git
 Release (e.g. tag `v0.1.1`) — the workflow builds and uploads it to PyPI.
 
 > [!NOTE]
-> `requires-python` is `>=3.14`, so installs require Python 3.14+.
+> `requires-python` is `>=3.13`, so installs require Python 3.13+.
 
 ### Documentation
 

{linear_python_client-0.1.1 → linear_python_client-0.2.1}/README.md

@@ -25,7 +25,7 @@ Or for local development of this repo:
 uv sync
 ```
 
-Requires Python 3.14+.
+Requires Python 3.13+.
 
 ## Authentication
 
@@ -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 |
 
@@ -291,7 +322,7 @@ To cut a release: bump `version` in `pyproject.toml`, then create a matching Git
 Release (e.g. tag `v0.1.1`) — the workflow builds and uploads it to PyPI.
 
 > [!NOTE]
-> `requires-python` is `>=3.14`, so installs require Python 3.14+.
+> `requires-python` is `>=3.13`, so installs require Python 3.13+.
 
 ### Documentation
 

{linear_python_client-0.1.1 → linear_python_client-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "linear-python-client"
-version = "0.1.1"
+version = "0.2.1"
 description = "Pragmatic Python client for the Linear GraphQL API"
 readme = "README.md"
 license = "MIT"
@@ -8,14 +8,14 @@ license-files = ["LICENSE"]
 authors = [
     { name = "eli-the-wizard", email = "ewinter@hackerone.com" }
 ]
-requires-python = ">=3.14"
+requires-python = ">=3.13"
 keywords = ["linear", "linear.app", "graphql", "api", "client", "sdk"]
 classifiers = [
     "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.14",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Libraries :: Python Modules",
     "Typing :: Typed",
 ]

{linear_python_client-0.1.1 → linear_python_client-0.2.1}/src/linear_python_client/__init__.py

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

{linear_python_client-0.1.1 → linear_python_client-0.2.1}/src/linear_python_client/client.py

@@ -24,6 +24,10 @@ from .models.requests import (
     CommentCreateRequest,
     CommentRequest,
     CommentsRequest,
+    FindLabelRequest,
+    FindProjectRequest,
+    FindTeamRequest,
+    FindUserRequest,
     FindWorkflowStateRequest,
     IssueAddLabelRequest,
     IssueArchiveRequest,
@@ -52,6 +56,7 @@ from .models.responses import (
     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 @@ class LinearClient:
             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.

{linear_python_client-0.1.1 → linear_python_client-0.2.1}/src/linear_python_client/models/__init__.py

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

{linear_python_client-0.1.1 → linear_python_client-0.2.1}/src/linear_python_client/models/requests.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from pydantic import ConfigDict, Field
+from pydantic import ConfigDict, Field, model_validator
 
 from .entities import LinearModel
 
@@ -239,6 +239,106 @@ class FindWorkflowStateRequest(LinearModel):
     name: str
 
 
+class FindTeamRequest(LinearModel):
+    """Resolve a team by its display name or key.
+
+    Provide at least one of `name` / `key`. Matching is case-insensitive for the
+    name and exact for the key.
+
+    Attributes:
+        name: Team display name (e.g. `"Ravens"`).
+        key: Team key (e.g. `"RAV"`).
+    """
+
+    name: str | None = None
+    key: str | None = None
+
+    @model_validator(mode="after")
+    def _require_one(self) -> FindTeamRequest:
+        if not (self.name or self.key):
+            raise ValueError("FindTeamRequest requires at least one of `name` or `key`.")
+        return self
+
+    def to_filter(self) -> dict[str, Any]:
+        """Build the `TeamFilter` for this lookup."""
+        filter_: dict[str, Any] = {}
+        if self.key:
+            filter_["key"] = {"eq": self.key}
+        if self.name:
+            filter_["name"] = {"eqIgnoreCase": self.name}
+        return filter_
+
+
+class FindUserRequest(LinearModel):
+    """Resolve a user by name, display name, or email.
+
+    Provide at least one of `name` / `email`. The `name` value is matched
+    (case-insensitively) against both the full name and the display name.
+
+    Attributes:
+        name: Full name or display name (e.g. `"Elijah Winter"`).
+        email: Email address.
+    """
+
+    name: str | None = None
+    email: str | None = None
+
+    @model_validator(mode="after")
+    def _require_one(self) -> FindUserRequest:
+        if not (self.name or self.email):
+            raise ValueError("FindUserRequest requires at least one of `name` or `email`.")
+        return self
+
+    def to_filter(self) -> dict[str, Any]:
+        """Build the `UserFilter` for this lookup."""
+        clauses: list[dict[str, Any]] = []
+        if self.name:
+            clauses.append(
+                {
+                    "or": [
+                        {"name": {"eqIgnoreCase": self.name}},
+                        {"displayName": {"eqIgnoreCase": self.name}},
+                    ]
+                }
+            )
+        if self.email:
+            clauses.append({"email": {"eqIgnoreCase": self.email}})
+        return clauses[0] if len(clauses) == 1 else {"and": clauses}
+
+
+class FindLabelRequest(LinearModel):
+    """Resolve an issue label by name, optionally scoped to a team.
+
+    Attributes:
+        name: Label name to match, case-insensitively (e.g. `"bug"`).
+        team_id: Optional team UUID to disambiguate team-scoped labels.
+    """
+
+    name: str
+    team_id: str | None = None
+
+    def to_filter(self) -> dict[str, Any]:
+        """Build the `IssueLabelFilter` for this lookup."""
+        filter_: dict[str, Any] = {"name": {"eqIgnoreCase": self.name}}
+        if self.team_id:
+            filter_["team"] = {"id": {"eq": self.team_id}}
+        return filter_
+
+
+class FindProjectRequest(LinearModel):
+    """Resolve a project by name.
+
+    Attributes:
+        name: Project name to match, case-insensitively.
+    """
+
+    name: str
+
+    def to_filter(self) -> dict[str, Any]:
+        """Build the `ProjectFilter` for this lookup."""
+        return {"name": {"eqIgnoreCase": self.name}}
+
+
 class CommentCreateRequest(LinearModel):
     """Input for adding a comment to an issue.
 

{linear_python_client-0.1.1 → linear_python_client-0.2.1}/src/linear_python_client/models/responses.py

@@ -82,6 +82,12 @@ class WorkflowStateResponse(LinearModel):
     state: WorkflowState | None = None
 
 
+class IssueLabelResponse(LinearModel):
+    """Resolved issue label from `find_label` (`None` if no match)."""
+
+    label: IssueLabel | None = None
+
+
 class ProjectResponse(LinearModel):
     """Response for [`project`][linear_python_client.client.LinearClient.project]."""