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

linear_python_client/errors.py

@@ -0,0 +1,78 @@
+"""Exception types raised by the Linear client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class LinearError(Exception):
+    """Base class for all errors raised by ``linear_python_client``."""
+
+
+class LinearAuthenticationError(LinearError):
+    """Raised when the API rejects the supplied credentials (HTTP 401/403)."""
+
+
+class LinearRateLimitError(LinearError):
+    """Raised when a request is rejected for exceeding a rate limit.
+
+    Linear signals rate limiting with an HTTP 400 response whose GraphQL error
+    carries the `RATELIMITED` code. The relevant `X-RateLimit-*` headers are
+    exposed as attributes when present (otherwise `None`).
+
+    Attributes:
+        requests_limit: Max requests allowed in the current window.
+        requests_remaining: Requests left in the current window.
+        requests_reset: Window reset time (UTC epoch milliseconds).
+        complexity_limit: Max complexity points allowed in the current window.
+        complexity_remaining: Complexity points left in the current window.
+        complexity_reset: Complexity window reset time (UTC epoch milliseconds).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        requests_limit: int | None = None,
+        requests_remaining: int | None = None,
+        requests_reset: int | None = None,
+        complexity_limit: int | None = None,
+        complexity_remaining: int | None = None,
+        complexity_reset: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.requests_limit = requests_limit
+        self.requests_remaining = requests_remaining
+        self.requests_reset = requests_reset
+        self.complexity_limit = complexity_limit
+        self.complexity_remaining = complexity_remaining
+        self.complexity_reset = complexity_reset
+
+
+class LinearGraphQLError(LinearError):
+    """Raised when the API returns one or more GraphQL `errors`.
+
+    The raw error list returned by the API is available as `errors`, and the
+    code of the first error carrying one (if any) is exposed via `code`.
+
+    Attributes:
+        errors: The raw GraphQL error objects returned by the API.
+    """
+
+    def __init__(self, message: str, *, errors: list[dict[str, Any]] | None = None) -> None:
+        super().__init__(message)
+        self.errors: list[dict[str, Any]] = errors or []
+
+    @property
+    def code(self) -> str | None:
+        """The error code of the first error that carries one, else `None`."""
+        for error in self.errors:
+            extensions = error.get("extensions") or {}
+            code = extensions.get("code") or error.get("code")
+            if code:
+                return str(code)
+        return None
+
+
+class LinearNetworkError(LinearError):
+    """Raised when the request fails to reach the API or returns an unexpected response."""

linear_python_client/graphql/__init__.py

@@ -0,0 +1,10 @@
+"""GraphQL operation strings used by the client.
+
+Import the query/mutation module with ``from linear_python_client.graphql import queries``.
+"""
+
+from __future__ import annotations
+
+from . import queries
+
+__all__ = ["queries"]

linear_python_client/graphql/queries.py

@@ -0,0 +1,405 @@
+"""GraphQL query and mutation strings used by :class:`linear_python_client.client.LinearClient`.
+
+Field selections are factored into reusable fragments so the operations below stay
+readable and the requested fields line up with the dataclasses in ``models.py``.
+"""
+
+from __future__ import annotations
+
+# --- Field fragments -------------------------------------------------------
+
+USER_FIELDS = """
+fragment UserFields on User {
+  id
+  name
+  displayName
+  email
+  active
+  admin
+  createdAt
+}
+"""
+
+TEAM_FIELDS = """
+fragment TeamFields on Team {
+  id
+  name
+  key
+  description
+  private
+  createdAt
+}
+"""
+
+STATE_FIELDS = """
+fragment StateFields on WorkflowState {
+  id
+  name
+  type
+  color
+  position
+}
+"""
+
+LABEL_FIELDS = """
+fragment LabelFields on IssueLabel {
+  id
+  name
+  color
+}
+"""
+
+PROJECT_FIELDS = """
+fragment ProjectFields on Project {
+  id
+  name
+  description
+  slugId
+  state
+  progress
+  createdAt
+}
+"""
+
+COMMENT_FIELDS = """
+fragment CommentFields on Comment {
+  id
+  body
+  url
+  createdAt
+  updatedAt
+  user { ...UserFields }
+}
+"""
+
+ISSUE_FIELDS = """
+fragment IssueFields on Issue {
+  id
+  identifier
+  title
+  description
+  url
+  priority
+  estimate
+  branchName
+  createdAt
+  updatedAt
+  completedAt
+  assignee { ...UserFields }
+  creator { ...UserFields }
+  team { ...TeamFields }
+  state { ...StateFields }
+  labels { nodes { ...LabelFields } }
+}
+"""
+
+ATTACHMENT_FIELDS = """
+fragment AttachmentFields on Attachment {
+  id
+  title
+  subtitle
+  url
+  createdAt
+}
+"""
+
+CYCLE_FIELDS = """
+fragment CycleFields on Cycle {
+  id
+  number
+  name
+  startsAt
+  endsAt
+}
+"""
+
+# A shallow issue projection used for parent / sub-issues / related issues so the
+# detailed query stays bounded (no recursion into their relations).
+ISSUE_SUMMARY_FIELDS = """
+fragment IssueSummaryFields on Issue {
+  id
+  identifier
+  title
+  url
+  priority
+  state { ...StateFields }
+}
+"""
+
+# Full issue detail: the base fields plus the heavier related collections.
+ISSUE_DETAIL_FIELDS = """
+fragment IssueDetailFields on Issue {
+  ...IssueFields
+  comments { nodes { ...CommentFields } }
+  attachments { nodes { ...AttachmentFields } }
+  project { ...ProjectFields }
+  cycle { ...CycleFields }
+  parent { ...IssueSummaryFields }
+  children { nodes { ...IssueSummaryFields } }
+  subscribers { nodes { ...UserFields } }
+  relations { nodes { type relatedIssue { ...IssueSummaryFields } } }
+}
+"""
+
+
+def _compose(*parts: str) -> str:
+    """Join an operation body with the fragments it depends on."""
+    return "\n".join(part.strip() for part in parts)
+
+
+# --- Queries ---------------------------------------------------------------
+
+VIEWER = _compose(
+    USER_FIELDS,
+    """
+query Viewer {
+  viewer { ...UserFields }
+}
+""",
+)
+
+USER = _compose(
+    USER_FIELDS,
+    """
+query User($id: String!) {
+  user(id: $id) { ...UserFields }
+}
+""",
+)
+
+USERS = _compose(
+    USER_FIELDS,
+    """
+query Users($first: Int, $after: String, $filter: UserFilter) {
+  users(first: $first, after: $after, filter: $filter) {
+    nodes { ...UserFields }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+  }
+}
+""",
+)
+
+TEAM = _compose(
+    TEAM_FIELDS,
+    """
+query Team($id: String!) {
+  team(id: $id) { ...TeamFields }
+}
+""",
+)
+
+TEAMS = _compose(
+    TEAM_FIELDS,
+    """
+query Teams($first: Int, $after: String, $filter: TeamFilter) {
+  teams(first: $first, after: $after, filter: $filter) {
+    nodes { ...TeamFields }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+  }
+}
+""",
+)
+
+ISSUE = _compose(
+    ISSUE_FIELDS,
+    USER_FIELDS,
+    TEAM_FIELDS,
+    STATE_FIELDS,
+    LABEL_FIELDS,
+    """
+query Issue($id: String!) {
+  issue(id: $id) { ...IssueFields }
+}
+""",
+)
+
+ISSUE_DETAILS = _compose(
+    ISSUE_DETAIL_FIELDS,
+    ISSUE_FIELDS,
+    ISSUE_SUMMARY_FIELDS,
+    USER_FIELDS,
+    TEAM_FIELDS,
+    STATE_FIELDS,
+    LABEL_FIELDS,
+    PROJECT_FIELDS,
+    COMMENT_FIELDS,
+    ATTACHMENT_FIELDS,
+    CYCLE_FIELDS,
+    """
+query IssueDetails($id: String!) {
+  issue(id: $id) { ...IssueDetailFields }
+}
+""",
+)
+
+ISSUES = _compose(
+    ISSUE_FIELDS,
+    USER_FIELDS,
+    TEAM_FIELDS,
+    STATE_FIELDS,
+    LABEL_FIELDS,
+    """
+query Issues($first: Int, $after: String, $filter: IssueFilter, $orderBy: PaginationOrderBy) {
+  issues(first: $first, after: $after, filter: $filter, orderBy: $orderBy) {
+    nodes { ...IssueFields }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+  }
+}
+""",
+)
+
+PROJECT = _compose(
+    PROJECT_FIELDS,
+    """
+query Project($id: String!) {
+  project(id: $id) { ...ProjectFields }
+}
+""",
+)
+
+PROJECTS = _compose(
+    PROJECT_FIELDS,
+    """
+query Projects($first: Int, $after: String, $filter: ProjectFilter) {
+  projects(first: $first, after: $after, filter: $filter) {
+    nodes { ...ProjectFields }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+  }
+}
+""",
+)
+
+COMMENT = _compose(
+    COMMENT_FIELDS,
+    USER_FIELDS,
+    """
+query Comment($id: String!) {
+  comment(id: $id) { ...CommentFields }
+}
+""",
+)
+
+COMMENTS = _compose(
+    COMMENT_FIELDS,
+    USER_FIELDS,
+    """
+query Comments($first: Int, $after: String, $filter: CommentFilter) {
+  comments(first: $first, after: $after, filter: $filter) {
+    nodes { ...CommentFields }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+  }
+}
+""",
+)
+
+WORKFLOW_STATES = _compose(
+    STATE_FIELDS,
+    """
+query WorkflowStates($first: Int, $after: String, $filter: WorkflowStateFilter) {
+  workflowStates(first: $first, after: $after, filter: $filter) {
+    nodes { ...StateFields }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+  }
+}
+""",
+)
+
+ISSUE_LABELS = _compose(
+    LABEL_FIELDS,
+    """
+query IssueLabels($first: Int, $after: String, $filter: IssueLabelFilter) {
+  issueLabels(first: $first, after: $after, filter: $filter) {
+    nodes { ...LabelFields }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+  }
+}
+""",
+)
+
+
+# --- Mutations -------------------------------------------------------------
+
+ISSUE_CREATE = _compose(
+    ISSUE_FIELDS,
+    USER_FIELDS,
+    TEAM_FIELDS,
+    STATE_FIELDS,
+    LABEL_FIELDS,
+    """
+mutation IssueCreate($input: IssueCreateInput!) {
+  issueCreate(input: $input) {
+    success
+    issue { ...IssueFields }
+  }
+}
+""",
+)
+
+ISSUE_UPDATE = _compose(
+    ISSUE_FIELDS,
+    USER_FIELDS,
+    TEAM_FIELDS,
+    STATE_FIELDS,
+    LABEL_FIELDS,
+    """
+mutation IssueUpdate($id: String!, $input: IssueUpdateInput!) {
+  issueUpdate(id: $id, input: $input) {
+    success
+    issue { ...IssueFields }
+  }
+}
+""",
+)
+
+ISSUE_ARCHIVE = """
+mutation IssueArchive($id: String!) {
+  issueArchive(id: $id) {
+    success
+  }
+}
+""".strip()
+
+COMMENT_CREATE = _compose(
+    COMMENT_FIELDS,
+    USER_FIELDS,
+    """
+mutation CommentCreate($input: CommentCreateInput!) {
+  commentCreate(input: $input) {
+    success
+    comment { ...CommentFields }
+  }
+}
+""",
+)
+
+ISSUE_ADD_LABEL = _compose(
+    ISSUE_FIELDS,
+    USER_FIELDS,
+    TEAM_FIELDS,
+    STATE_FIELDS,
+    LABEL_FIELDS,
+    """
+mutation IssueAddLabel($id: String!, $labelId: String!) {
+  issueAddLabel(id: $id, labelId: $labelId) {
+    success
+    issue { ...IssueFields }
+  }
+}
+""",
+)
+
+ISSUE_REMOVE_LABEL = _compose(
+    ISSUE_FIELDS,
+    USER_FIELDS,
+    TEAM_FIELDS,
+    STATE_FIELDS,
+    LABEL_FIELDS,
+    """
+mutation IssueRemoveLabel($id: String!, $labelId: String!) {
+  issueRemoveLabel(id: $id, labelId: $labelId) {
+    success
+    issue { ...IssueFields }
+  }
+}
+""",
+)

linear_python_client/models/__init__.py

@@ -0,0 +1,132 @@
+"""Data models: entities, request inputs, and response outputs.
+
+Re-exports everything so you can import from the package directly, e.g.
+``from linear_python_client.models import Issue, IssueCreateRequest, IssuesResponse``.
+"""
+
+from __future__ import annotations
+
+from .entities import (
+    Attachment,
+    Comment,
+    Cycle,
+    Issue,
+    IssueDetail,
+    IssueLabel,
+    IssueRelation,
+    LinearModel,
+    PageInfo,
+    Project,
+    Team,
+    User,
+    WorkflowState,
+)
+from .requests import (
+    CommentCreateRequest,
+    CommentRequest,
+    CommentsRequest,
+    FindWorkflowStateRequest,
+    IssueAddLabelRequest,
+    IssueArchiveRequest,
+    IssueCreateRequest,
+    IssueLabelsRequest,
+    IssueRemoveLabelRequest,
+    IssueRequest,
+    IssueSetStateRequest,
+    IssuesRequest,
+    IssueUpdateRequest,
+    PaginatedRequest,
+    ProjectRequest,
+    ProjectsRequest,
+    TeamRequest,
+    TeamsRequest,
+    UserRequest,
+    UsersRequest,
+    WorkflowStatesRequest,
+)
+from .responses import (
+    AddLabelResponse,
+    ArchiveIssueResponse,
+    CommentResponse,
+    CommentsResponse,
+    ConnectionResponse,
+    CreateCommentResponse,
+    CreateIssueResponse,
+    IssueDetailsResponse,
+    IssueLabelsResponse,
+    IssueResponse,
+    IssuesResponse,
+    ProjectResponse,
+    ProjectsResponse,
+    RemoveLabelResponse,
+    TeamResponse,
+    TeamsResponse,
+    UpdateIssueResponse,
+    UserResponse,
+    UsersResponse,
+    ViewerResponse,
+    WorkflowStateResponse,
+    WorkflowStatesResponse,
+)
+
+__all__ = [
+    # entities
+    "LinearModel",
+    "Attachment",
+    "Comment",
+    "Cycle",
+    "Issue",
+    "IssueDetail",
+    "IssueLabel",
+    "IssueRelation",
+    "PageInfo",
+    "Project",
+    "Team",
+    "User",
+    "WorkflowState",
+    # requests
+    "PaginatedRequest",
+    "UserRequest",
+    "UsersRequest",
+    "TeamRequest",
+    "TeamsRequest",
+    "IssueRequest",
+    "IssuesRequest",
+    "IssueCreateRequest",
+    "IssueUpdateRequest",
+    "IssueArchiveRequest",
+    "IssueAddLabelRequest",
+    "IssueRemoveLabelRequest",
+    "IssueSetStateRequest",
+    "FindWorkflowStateRequest",
+    "ProjectRequest",
+    "ProjectsRequest",
+    "CommentRequest",
+    "CommentsRequest",
+    "CommentCreateRequest",
+    "WorkflowStatesRequest",
+    "IssueLabelsRequest",
+    # responses
+    "ConnectionResponse",
+    "ViewerResponse",
+    "UserResponse",
+    "UsersResponse",
+    "TeamResponse",
+    "TeamsResponse",
+    "IssueResponse",
+    "IssueDetailsResponse",
+    "IssuesResponse",
+    "CreateIssueResponse",
+    "UpdateIssueResponse",
+    "ArchiveIssueResponse",
+    "AddLabelResponse",
+    "RemoveLabelResponse",
+    "ProjectResponse",
+    "ProjectsResponse",
+    "CommentResponse",
+    "CommentsResponse",
+    "CreateCommentResponse",
+    "WorkflowStateResponse",
+    "WorkflowStatesResponse",
+    "IssueLabelsResponse",
+]