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

linear_python_client/models/entities.py

@@ -0,0 +1,187 @@
+"""Pydantic models for Linear API entities.
+
+All models use snake_case attribute names with automatically generated camelCase
+aliases, so they parse the API's camelCase payloads (`displayName`, `createdAt`,
+…) and can be serialised back to them with `model_dump(by_alias=True)`. Because
+`populate_by_name=True`, you can construct them with either spelling.
+
+Only the fields a given query requested are populated; everything is optional and
+defaults to `None`, and unknown fields are ignored.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic.alias_generators import to_camel
+
+
+def _unwrap_nodes(value: object) -> object:
+    """Accept Linear's `{ nodes: [...] }` connection shape, returning the node list."""
+    if isinstance(value, dict) and "nodes" in value:
+        return value["nodes"]
+    return value
+
+
+class LinearModel(BaseModel):
+    """Base model: camelCase aliases, snake_case attributes, lenient parsing."""
+
+    model_config = ConfigDict(
+        alias_generator=to_camel,
+        populate_by_name=True,
+        extra="ignore",
+    )
+
+
+class PageInfo(LinearModel):
+    """Relay-style pagination metadata for a connection."""
+
+    has_next_page: bool = False
+    has_previous_page: bool = False
+    start_cursor: str | None = None
+    end_cursor: str | None = None
+
+
+class User(LinearModel):
+    """A Linear user."""
+
+    id: str | None = None
+    name: str | None = None
+    display_name: str | None = None
+    email: str | None = None
+    active: bool | None = None
+    admin: bool | None = None
+    created_at: datetime | None = None
+
+
+class Team(LinearModel):
+    """A Linear team."""
+
+    id: str | None = None
+    name: str | None = None
+    key: str | None = None
+    description: str | None = None
+    private: bool | None = None
+    created_at: datetime | None = None
+
+
+class WorkflowState(LinearModel):
+    """An issue workflow state (e.g. Todo, In Progress, Done)."""
+
+    id: str | None = None
+    name: str | None = None
+    type: str | None = None
+    color: str | None = None
+    position: float | None = None
+
+
+class IssueLabel(LinearModel):
+    """A label that can be applied to issues."""
+
+    id: str | None = None
+    name: str | None = None
+    color: str | None = None
+
+
+class Project(LinearModel):
+    """A Linear project."""
+
+    id: str | None = None
+    name: str | None = None
+    description: str | None = None
+    slug_id: str | None = None
+    state: str | None = None
+    progress: float | None = None
+    created_at: datetime | None = None
+
+
+class Comment(LinearModel):
+    """A comment on an issue."""
+
+    id: str | None = None
+    body: str | None = None
+    url: str | None = None
+    user: User | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class Issue(LinearModel):
+    """A Linear issue, with nested relations populated when requested."""
+
+    id: str | None = None
+    identifier: str | None = None
+    title: str | None = None
+    description: str | None = None
+    url: str | None = None
+    priority: int | None = None
+    estimate: float | None = None
+    branch_name: str | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+    completed_at: datetime | None = None
+    assignee: User | None = None
+    creator: User | None = None
+    team: Team | None = None
+    state: WorkflowState | None = None
+    labels: list[IssueLabel] = Field(default_factory=list)
+
+    @field_validator("labels", mode="before")
+    @classmethod
+    def _unwrap_label_nodes(cls, value: object) -> object:
+        """Accept Linear's `labels: { nodes: [...] }` connection shape."""
+        return _unwrap_nodes(value)
+
+
+class Attachment(LinearModel):
+    """A link or file attached to an issue."""
+
+    id: str | None = None
+    title: str | None = None
+    subtitle: str | None = None
+    url: str | None = None
+    created_at: datetime | None = None
+
+
+class Cycle(LinearModel):
+    """A team cycle (sprint)."""
+
+    id: str | None = None
+    number: int | None = None
+    name: str | None = None
+    starts_at: datetime | None = None
+    ends_at: datetime | None = None
+
+
+class IssueRelation(LinearModel):
+    """A relation from an issue to another (e.g. blocks, related, duplicate)."""
+
+    type: str | None = None
+    related_issue: Issue | None = None
+
+
+class IssueDetail(Issue):
+    """An issue plus its heavier related data, returned by `issue_details`.
+
+    Inherits every field of [`Issue`][linear_python_client.Issue] and adds the
+    related collections. As always, only the fields the query requested are
+    populated; `parent`, `children`, and relation targets are shallow issues.
+    """
+
+    comments: list[Comment] = Field(default_factory=list)
+    attachments: list[Attachment] = Field(default_factory=list)
+    project: Project | None = None
+    cycle: Cycle | None = None
+    parent: Issue | None = None
+    children: list[Issue] = Field(default_factory=list)
+    subscribers: list[User] = Field(default_factory=list)
+    relations: list[IssueRelation] = Field(default_factory=list)
+
+    @field_validator(
+        "comments", "attachments", "children", "subscribers", "relations", mode="before"
+    )
+    @classmethod
+    def _unwrap_connection_nodes(cls, value: object) -> object:
+        """Accept Linear's `{ nodes: [...] }` connection shape for the collections."""
+        return _unwrap_nodes(value)

linear_python_client/models/requests.py

@@ -0,0 +1,260 @@
+"""Typed request models for each :class:`~linear_python_client.client.LinearClient` call.
+
+Every client method takes exactly one of these. They carry snake_case fields with
+camelCase aliases, and expose helpers (`to_variables`, `to_input`) that serialise
+them into the GraphQL variables the API expects.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ConfigDict, Field
+
+from .entities import LinearModel
+
+# -- query requests ---------------------------------------------------------
+
+
+class IssueRequest(LinearModel):
+    """Fetch a single issue by id or human identifier (e.g. `"ENG-123"`)."""
+
+    id: str
+
+
+class UserRequest(LinearModel):
+    """Fetch a single user by UUID."""
+
+    id: str
+
+
+class TeamRequest(LinearModel):
+    """Fetch a single team by UUID."""
+
+    id: str
+
+
+class ProjectRequest(LinearModel):
+    """Fetch a single project by UUID."""
+
+    id: str
+
+
+class CommentRequest(LinearModel):
+    """Fetch a single comment by UUID."""
+
+    id: str
+
+
+class PaginatedRequest(LinearModel):
+    """Base for list requests: cursor pagination plus an optional filter.
+
+    Attributes:
+        first: Maximum number of results to return (Linear defaults to 50).
+        after: Pagination cursor; pass the previous page's `end_cursor`.
+        filter: A [Linear filter](https://linear.app/developers/filtering) dict.
+    """
+
+    first: int | None = None
+    after: str | None = None
+    filter: dict[str, Any] | None = None
+
+    def to_variables(self) -> dict[str, Any]:
+        """Serialise to GraphQL variables (camelCase, omitting unset values)."""
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+
+class IssuesRequest(PaginatedRequest):
+    """List issues, optionally filtered and ordered.
+
+    Attributes:
+        order_by: Sort order, either `"createdAt"` (default) or `"updatedAt"`.
+    """
+
+    order_by: str | None = None
+
+
+class UsersRequest(PaginatedRequest):
+    """List users in the workspace."""
+
+
+class TeamsRequest(PaginatedRequest):
+    """List teams in the workspace."""
+
+
+class ProjectsRequest(PaginatedRequest):
+    """List projects in the workspace."""
+
+
+class IssueLabelsRequest(PaginatedRequest):
+    """List issue labels in the workspace."""
+
+
+class CommentsRequest(PaginatedRequest):
+    """List comments, optionally scoped to a single issue.
+
+    Attributes:
+        issue_id: When set, only comments on this issue are returned (merged into
+            `filter`). Not sent as a raw variable.
+    """
+
+    issue_id: str | None = Field(default=None, exclude=True)
+
+
+class WorkflowStatesRequest(PaginatedRequest):
+    """List workflow states, optionally scoped to a single team.
+
+    Attributes:
+        team_id: When set, only states belonging to this team are returned (merged
+            into `filter`). Not sent as a raw variable.
+    """
+
+    team_id: str | None = Field(default=None, exclude=True)
+
+
+# -- mutation requests ------------------------------------------------------
+
+
+class IssueCreateRequest(LinearModel):
+    """Input for creating an issue.
+
+    Any field accepted by Linear's `IssueCreateInput` may also be passed as an
+    extra keyword argument using its camelCase API name (e.g. `dueDate="2026-01-01"`).
+
+    Attributes:
+        team_id: UUID of the team the issue belongs to (required).
+        title: The issue title (required).
+        description: Markdown body for the issue.
+        assignee_id: UUID of the user to assign.
+        state_id: UUID of the workflow state to set.
+        priority: Priority from 0 (none) to 4 (low); 1 is urgent.
+        label_ids: UUIDs of labels to attach.
+        project_id: UUID of the project to add the issue to.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    team_id: str
+    title: str
+    description: str | None = None
+    assignee_id: str | None = None
+    state_id: str | None = None
+    priority: int | None = None
+    label_ids: list[str] | None = None
+    project_id: str | None = None
+
+    def to_input(self) -> dict[str, Any]:
+        """Serialise to an `IssueCreateInput` dict (camelCase, omitting unset values)."""
+        return self.model_dump(by_alias=True, exclude_none=True)
+
+
+class IssueUpdateRequest(LinearModel):
+    """Input for updating an issue.
+
+    At least one field other than `id` must be set. Any field accepted by Linear's
+    `IssueUpdateInput` may also be passed as an extra keyword argument using its
+    camelCase API name.
+
+    Attributes:
+        id: UUID of the issue to update (required).
+        title: New title.
+        description: New markdown body.
+        assignee_id: UUID of the user to assign.
+        state_id: UUID of the workflow state to set.
+        priority: Priority from 0 (none) to 4 (low); 1 is urgent.
+        label_ids: UUIDs of labels to set.
+        project_id: UUID of the project to move the issue to.
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    id: str
+    title: str | None = None
+    description: str | None = None
+    assignee_id: str | None = None
+    state_id: str | None = None
+    priority: int | None = None
+    label_ids: list[str] | None = None
+    project_id: str | None = None
+
+    def to_input(self) -> dict[str, Any]:
+        """Serialise the update fields to an `IssueUpdateInput` dict (excluding `id`)."""
+        data = self.model_dump(by_alias=True, exclude_none=True)
+        data.pop("id", None)
+        return data
+
+
+class IssueArchiveRequest(LinearModel):
+    """Archive an issue by UUID."""
+
+    id: str
+
+
+class IssueAddLabelRequest(LinearModel):
+    """Add a single label to an issue, leaving its other labels untouched.
+
+    Attributes:
+        id: UUID of the issue.
+        label_id: UUID of the label to add.
+    """
+
+    id: str
+    label_id: str
+
+
+class IssueRemoveLabelRequest(LinearModel):
+    """Remove a single label from an issue, leaving its other labels untouched.
+
+    Attributes:
+        id: UUID of the issue.
+        label_id: UUID of the label to remove.
+    """
+
+    id: str
+    label_id: str
+
+
+class IssueSetStateRequest(LinearModel):
+    """Move an issue to a workflow state (status).
+
+    Attributes:
+        id: UUID of the issue.
+        state_id: UUID of the target workflow state. Resolve one by name with
+            [`find_workflow_state`][linear_python_client.client.LinearClient.find_workflow_state].
+    """
+
+    id: str
+    state_id: str
+
+
+class FindWorkflowStateRequest(LinearModel):
+    """Resolve a workflow state by name within a team.
+
+    Attributes:
+        team_id: UUID of the team that owns the state.
+        name: State name to match, case-insensitively (e.g. `"In Progress"`).
+    """
+
+    team_id: str
+    name: str
+
+
+class CommentCreateRequest(LinearModel):
+    """Input for adding a comment to an issue.
+
+    Any field accepted by Linear's `CommentCreateInput` may also be passed as an
+    extra keyword argument using its camelCase API name.
+
+    Attributes:
+        issue_id: UUID of the issue to comment on (required).
+        body: Markdown body of the comment (required).
+    """
+
+    model_config = ConfigDict(extra="allow")
+
+    issue_id: str
+    body: str
+
+    def to_input(self) -> dict[str, Any]:
+        """Serialise to a `CommentCreateInput` dict (camelCase, omitting unset values)."""
+        return self.model_dump(by_alias=True, exclude_none=True)

linear_python_client/models/responses.py

@@ -0,0 +1,169 @@
+"""Typed response models returned by each :class:`~linear_python_client.client.LinearClient` call.
+
+Single-entity queries return a wrapper exposing the entity (e.g.
+:class:`IssueResponse.issue`). List queries return a :class:`ConnectionResponse`
+subclass exposing `nodes` and `page_info`. Mutations mirror the GraphQL payload,
+exposing `success` alongside the affected entity.
+"""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from .entities import (
+    Comment,
+    Issue,
+    IssueDetail,
+    IssueLabel,
+    LinearModel,
+    PageInfo,
+    Project,
+    Team,
+    User,
+    WorkflowState,
+)
+
+
+class ConnectionResponse[NodeT](LinearModel):
+    """Base for list responses: a page of `nodes` plus its :class:`PageInfo`.
+
+    Iterable and sized, so you can loop over the response directly or read
+    `response.nodes` / `response.page_info`.
+    """
+
+    nodes: list[NodeT] = Field(default_factory=list)
+    page_info: PageInfo = Field(default_factory=PageInfo)
+
+    def __iter__(self):
+        """Iterate over `nodes`."""
+        return iter(self.nodes)
+
+    def __len__(self) -> int:
+        """Number of nodes on this page."""
+        return len(self.nodes)
+
+
+# -- single-entity query responses -----------------------------------------
+
+
+class ViewerResponse(LinearModel):
+    """Response for [`viewer`][linear_python_client.client.LinearClient.viewer]."""
+
+    viewer: User | None = None
+
+
+class UserResponse(LinearModel):
+    """Response for [`user`][linear_python_client.client.LinearClient.user]."""
+
+    user: User | None = None
+
+
+class TeamResponse(LinearModel):
+    """Response for [`team`][linear_python_client.client.LinearClient.team]."""
+
+    team: Team | None = None
+
+
+class IssueResponse(LinearModel):
+    """Response for [`issue`][linear_python_client.client.LinearClient.issue]."""
+
+    issue: Issue | None = None
+
+
+class IssueDetailsResponse(LinearModel):
+    """Response for [`issue_details`][linear_python_client.client.LinearClient.issue_details]."""
+
+    issue: IssueDetail | None = None
+
+
+class WorkflowStateResponse(LinearModel):
+    """Resolved workflow state from `find_workflow_state` (`None` if no match)."""
+
+    state: WorkflowState | None = None
+
+
+class ProjectResponse(LinearModel):
+    """Response for [`project`][linear_python_client.client.LinearClient.project]."""
+
+    project: Project | None = None
+
+
+class CommentResponse(LinearModel):
+    """Response for [`comment`][linear_python_client.client.LinearClient.comment]."""
+
+    comment: Comment | None = None
+
+
+# -- list query responses ---------------------------------------------------
+
+
+class UsersResponse(ConnectionResponse[User]):
+    """Response for [`users`][linear_python_client.client.LinearClient.users]."""
+
+
+class TeamsResponse(ConnectionResponse[Team]):
+    """Response for [`teams`][linear_python_client.client.LinearClient.teams]."""
+
+
+class IssuesResponse(ConnectionResponse[Issue]):
+    """Response for [`issues`][linear_python_client.client.LinearClient.issues]."""
+
+
+class ProjectsResponse(ConnectionResponse[Project]):
+    """Response for [`projects`][linear_python_client.client.LinearClient.projects]."""
+
+
+class CommentsResponse(ConnectionResponse[Comment]):
+    """Response for [`comments`][linear_python_client.client.LinearClient.comments]."""
+
+
+class WorkflowStatesResponse(ConnectionResponse[WorkflowState]):
+    """[`workflow_states`][linear_python_client.client.LinearClient.workflow_states] response."""
+
+
+class IssueLabelsResponse(ConnectionResponse[IssueLabel]):
+    """Response for [`issue_labels`][linear_python_client.client.LinearClient.issue_labels]."""
+
+
+# -- mutation responses -----------------------------------------------------
+
+
+class CreateIssueResponse(LinearModel):
+    """Response for [`create_issue`][linear_python_client.client.LinearClient.create_issue]."""
+
+    success: bool = False
+    issue: Issue | None = None
+
+
+class UpdateIssueResponse(LinearModel):
+    """Response for [`update_issue`][linear_python_client.client.LinearClient.update_issue]."""
+
+    success: bool = False
+    issue: Issue | None = None
+
+
+class ArchiveIssueResponse(LinearModel):
+    """Response for [`archive_issue`][linear_python_client.client.LinearClient.archive_issue]."""
+
+    success: bool = False
+
+
+class CreateCommentResponse(LinearModel):
+    """Response for [`create_comment`][linear_python_client.client.LinearClient.create_comment]."""
+
+    success: bool = False
+    comment: Comment | None = None
+
+
+class AddLabelResponse(LinearModel):
+    """Response for [`add_label`][linear_python_client.client.LinearClient.add_label]."""
+
+    success: bool = False
+    issue: Issue | None = None
+
+
+class RemoveLabelResponse(LinearModel):
+    """Response for [`remove_label`][linear_python_client.client.LinearClient.remove_label]."""
+
+    success: bool = False
+    issue: Issue | None = None