linear-python-client 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

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.0"
+__version__ = "0.2.0"
 
 __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/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/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/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/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]."""
 

{linear_python_client-0.1.0.dist-info → linear_python_client-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: linear-python-client
-Version: 0.1.0
+Version: 0.2.0
 Summary: Pragmatic Python client for the Linear GraphQL API
 Keywords: linear,linear.app,graphql,api,client,sdk
 Author: eli-the-wizard
@@ -15,13 +15,12 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Typing :: Typed
 Requires-Dist: httpx>=0.27
-Requires-Dist: jupyter>=1.1.1
 Requires-Dist: pydantic>=2.7
 Requires-Python: >=3.14
-Project-URL: Homepage, https://github.com/Hacker0x01/linear-python
-Project-URL: Documentation, https://hacker0x01.github.io/linear-python/
-Project-URL: Repository, https://github.com/Hacker0x01/linear-python
-Project-URL: Issues, https://github.com/Hacker0x01/linear-python/issues
+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
+Project-URL: Issues, https://github.com/Hacker0x01/linear-python-client/issues
 Description-Content-Type: text/markdown
 
 # linear-python-client
@@ -35,7 +34,7 @@ covers anything the typed methods don't.
 
 Built against the [Linear developer docs](https://linear.app/developers).
 
-📖 **Full documentation:** <https://hacker0x01.github.io/linear-python/>
+📖 **Full documentation:** <https://hacker0x01.github.io/linear-python-client/>
 
 ## Installation
 
@@ -188,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()`
@@ -251,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 |
 
@@ -314,7 +344,7 @@ Publishing uses [PyPI Trusted Publishing](https://docs.pypi.org/trusted-publishe
    (Settings → Environments).
 
 To cut a release: bump `version` in `pyproject.toml`, then create a matching GitHub
-Release (e.g. tag `v0.1.0`) — the workflow builds and uploads it to PyPI.
+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+.

linear_python_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+linear_python_client/__init__.py,sha256=iDaARod9vM0dy4oV3qvuB_2vioR3rjPKrFbmrGg-GXg,3369
+linear_python_client/client.py,sha256=0NdMCSrQGsuIGgRvCKvZjFJHBruj8sXJHRRK1_f_Z20,26782
+linear_python_client/errors.py,sha256=TBdv1mqPIQJjSUf42YQakAS4A9GN7PQKPnzdptTR7-k,2838
+linear_python_client/graphql/__init__.py,sha256=7Km7YkHvWrRMD4GRJo7PNRD-4271e3jPDNqFy5zam1w,228
+linear_python_client/graphql/queries.py,sha256=3ckrYY4yTRSDtLHfahUOpZsezEfNntFjMk7Kz2KO2o0,7431
+linear_python_client/models/__init__.py,sha256=qYpFuDINpOUdD0PgsbKgUnwq8HSyQY3n-AtsYfMSDWU,3065
+linear_python_client/models/entities.py,sha256=mE1ejvrXjhHFXnjU3ctlVAbmWL9TpLL2vz317ve5w1M,5450
+linear_python_client/models/requests.py,sha256=2zXXsyppqR-vDIQE21QIx7Gl2NqdPt7jo56hLJ5RZD0,10380
+linear_python_client/models/responses.py,sha256=73rEx9ajfb6Iqt0Ng2HX0peika2vJJa-bCrzdWSpbgY,4979
+linear_python_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+linear_python_client-0.2.0.dist-info/licenses/LICENSE,sha256=CcQjmF-Tw7VtkjYGvej9Df6Dz-AztG1aTRtMAiLoL7w,1066
+linear_python_client-0.2.0.dist-info/WHEEL,sha256=wXwAVsgVaOZ_pwDFqQm5Rd6PID-Fc74nkLc8X8gHiDo,81
+linear_python_client-0.2.0.dist-info/METADATA,sha256=yqAIyj-I3iI_iQBpiPXbhms_zyQUWR0wzdZwBkHFvUk,13518
+linear_python_client-0.2.0.dist-info/RECORD,,

linear_python_client-0.1.0.dist-info/RECORD

@@ -1,14 +0,0 @@
-linear_python_client/__init__.py,sha256=2L9lnijqqbAytIC5fp_OnvZvhQji9RxOhNubbW7816Q,3135
-linear_python_client/client.py,sha256=oMWwM94I_46iYQVKfpnmAyICvPAUkyKPdv--QXOYG7I,24233
-linear_python_client/errors.py,sha256=TBdv1mqPIQJjSUf42YQakAS4A9GN7PQKPnzdptTR7-k,2838
-linear_python_client/graphql/__init__.py,sha256=7Km7YkHvWrRMD4GRJo7PNRD-4271e3jPDNqFy5zam1w,228
-linear_python_client/graphql/queries.py,sha256=3ckrYY4yTRSDtLHfahUOpZsezEfNntFjMk7Kz2KO2o0,7431
-linear_python_client/models/__init__.py,sha256=zJM7GsvUwPuGibRwdugerSyJkTH8opWjVJD8yus6Rxk,2831
-linear_python_client/models/entities.py,sha256=mE1ejvrXjhHFXnjU3ctlVAbmWL9TpLL2vz317ve5w1M,5450
-linear_python_client/models/requests.py,sha256=Yss-zSo6gWWMqX4Qh1-P_n1sWbe176tL04LECnyASv4,7282
-linear_python_client/models/responses.py,sha256=lLsJz35XruT0g4qnGF9g7sc_lNWcPNzy-QP5tW9tIUA,4830
-linear_python_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-linear_python_client-0.1.0.dist-info/licenses/LICENSE,sha256=CcQjmF-Tw7VtkjYGvej9Df6Dz-AztG1aTRtMAiLoL7w,1066
-linear_python_client-0.1.0.dist-info/WHEEL,sha256=wXwAVsgVaOZ_pwDFqQm5Rd6PID-Fc74nkLc8X8gHiDo,81
-linear_python_client-0.1.0.dist-info/METADATA,sha256=t0dlnHz0hHBKvHfEawnH0cCgc00k_GHppLTdhBg0b0s,12355
-linear_python_client-0.1.0.dist-info/RECORD,,