git-alternative 0.2.2__py3-none-any.whl

git_alternative/models.py

@@ -0,0 +1,291 @@
+"""Data models for the Forge Git collaboration platform SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class IssueState(str, Enum):
+    """Lifecycle state of an issue."""
+
+    OPEN = "open"
+    CLOSED = "closed"
+
+
+class PrState(str, Enum):
+    """Lifecycle state of a pull request."""
+
+    OPEN = "open"
+    MERGED = "merged"
+    CLOSED = "closed"
+    DRAFT = "draft"
+
+
+class MergeStrategy(str, Enum):
+    """Strategy used to merge a pull request."""
+
+    MERGE = "merge"
+    SQUASH = "squash"
+    REBASE = "rebase"
+
+
+class PipelineState(str, Enum):
+    """Execution state of a CI pipeline or job."""
+
+    PENDING = "pending"
+    RUNNING = "running"
+    SUCCESS = "success"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class PipelineTrigger(str, Enum):
+    """Event that triggered a CI pipeline."""
+
+    PUSH = "push"
+    PULL_REQUEST = "pull_request"
+    MANUAL = "manual"
+
+
+@dataclass
+class User:
+    """Represents a Forge user account."""
+
+    id: str
+    username: str
+    email: str
+    display_name: str
+    created_at: datetime
+    updated_at: datetime
+    bio: str | None = None
+    avatar_url: str | None = None
+
+
+@dataclass
+class Repository:
+    """Represents a Forge repository."""
+
+    id: str
+    owner_id: str
+    name: str
+    description: str | None
+    is_private: bool
+    is_fork: bool
+    default_branch: str
+    created_at: datetime
+    updated_at: datetime
+    star_count: int = 0
+    fork_count: int = 0
+    fork_of: str | None = None
+
+
+@dataclass
+class CreateRepoRequest:
+    """Request payload for creating a new repository."""
+
+    name: str
+    description: str | None = None
+    is_private: bool = False
+    default_branch: str = "main"
+    auto_init: bool = False
+
+
+@dataclass
+class Branch:
+    """Represents a git branch."""
+
+    name: str
+    sha: str
+    is_default: bool = False
+    is_protected: bool = False
+
+
+@dataclass
+class CommitSummary:
+    """Summary of a git commit."""
+
+    sha: str
+    message: str
+    author_name: str
+    author_email: str
+    authored_at: datetime
+    committer_name: str
+    committer_email: str
+    committed_at: datetime
+    parents: list[str] = field(default_factory=list)
+
+
+@dataclass
+class Label:
+    """Represents an issue/PR label."""
+
+    id: str
+    name: str
+    color: str
+    description: str | None = None
+
+
+@dataclass
+class Issue:
+    """Represents a Forge issue."""
+
+    id: str
+    repo_id: str
+    number: int
+    title: str
+    author_id: str
+    state: IssueState
+    created_at: datetime
+    updated_at: datetime
+    body: str | None = None
+    labels: list[Label] = field(default_factory=list)
+    assignees: list[str] = field(default_factory=list)
+    milestone_id: str | None = None
+    closed_at: datetime | None = None
+    comment_count: int = 0
+
+
+@dataclass
+class Comment:
+    """Represents a comment on an issue or pull request."""
+
+    id: str
+    author_id: str
+    body: str
+    created_at: datetime
+    updated_at: datetime
+
+
+@dataclass
+class Reviewer:
+    """Represents a PR reviewer and their approval status."""
+
+    user_id: str
+    approved: bool = False
+    reviewed_at: datetime | None = None
+
+
+@dataclass
+class PullRequest:
+    """Represents a Forge pull request."""
+
+    id: str
+    repo_id: str
+    number: int
+    title: str
+    author_id: str
+    state: PrState
+    head_branch: str
+    head_sha: str
+    base_branch: str
+    base_sha: str
+    created_at: datetime
+    updated_at: datetime
+    body: str | None = None
+    merge_sha: str | None = None
+    merge_strategy: MergeStrategy | None = None
+    reviewers: list[Reviewer] = field(default_factory=list)
+    merged_at: datetime | None = None
+    has_conflicts: bool = False
+
+
+@dataclass
+class PipelineJob:
+    """Represents a single job within a CI pipeline."""
+
+    id: str
+    name: str
+    state: PipelineState
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+    steps: list[dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class Pipeline:
+    """Represents a CI pipeline run."""
+
+    id: str
+    repo_id: str
+    commit_sha: str
+    branch: str
+    trigger: PipelineTrigger
+    state: PipelineState
+    created_at: datetime
+    jobs: list[PipelineJob] = field(default_factory=list)
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+@dataclass
+class CommitStatus:
+    """Aggregated CI status for a commit."""
+
+    sha: str
+    state: PipelineState
+    pipeline_count: int = 0
+
+
+@dataclass
+class SshKey:
+    """Represents an SSH public key attached to a user account."""
+
+    id: str
+    user_id: str
+    title: str
+    key: str
+    fingerprint: str
+    created_at: datetime
+
+
+@dataclass
+class PaginatedResponse(Generic[T]):
+    """A paginated list of items from the API."""
+
+    items: list[T]
+    page: int
+    per_page: int
+    has_next_page: bool
+    total_count: int | None = None
+
+
+@dataclass
+class CIJobStep:
+    """A single step within a CI job definition."""
+
+    name: str
+    run: str | None = None
+    uses: str | None = None
+    with_params: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class CIJobDefinition:
+    """Definition of a CI job from the pipeline config file."""
+
+    name: str
+    runs_on: str
+    steps: list[CIJobStep] = field(default_factory=list)
+    needs: list[str] = field(default_factory=list)
+
+
+@dataclass
+class CITrigger:
+    """Trigger conditions for a CI pipeline."""
+
+    push_branches: list[str] = field(default_factory=list)
+    pr_branches: list[str] = field(default_factory=list)
+
+
+@dataclass
+class CIConfig:
+    """Parsed representation of a .forge/ci.yml configuration file."""
+
+    name: str
+    trigger: CITrigger
+    jobs: dict[str, CIJobDefinition] = field(default_factory=dict)

git_alternative/pagination.py

@@ -0,0 +1,45 @@
+"""Pagination utilities for the Forge API."""
+
+from __future__ import annotations
+
+from git_alternative.models import PaginatedResponse, T
+
+
+def paginate_commits(
+    raw_commits: list[T],
+    page: int,
+    per_page: int,
+) -> PaginatedResponse[T]:
+    """Apply server-side pagination logic to a list of commits.
+
+    Fetches ``per_page + 1`` items and uses the extra item as a sentinel to
+    determine whether a next page exists, without requiring an expensive
+    ``COUNT(*)`` query.
+
+    Args:
+        raw_commits: List of commit objects fetched with ``limit = per_page + 1``.
+        page: The current page number (1-based).
+        per_page: Maximum number of items per page.
+
+    Returns:
+        A :class:`~git_alternative.models.PaginatedResponse` with the correct
+        items slice and ``has_next_page`` flag.
+
+    Example:
+        >>> items = list(range(11))  # fetched with limit=11
+        >>> result = paginate_commits(items, page=1, per_page=10)
+        >>> result.has_next_page
+        True
+        >>> len(result.items)
+        10
+    """
+    per_page = min(per_page, 100)
+    has_next = len(raw_commits) > per_page
+    items = raw_commits[:per_page] if has_next else raw_commits
+
+    return PaginatedResponse(
+        items=items,
+        page=page,
+        per_page=per_page,
+        has_next_page=has_next,
+    )

git_alternative/resources/__init__.py

@@ -0,0 +1 @@
+"""Resource sub-clients for the Forge API."""

git_alternative/resources/issues.py

@@ -0,0 +1,291 @@
+"""Issues resource client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from git_alternative.http import HttpClient
+from git_alternative.models import Comment, Issue, IssueState, Label, PaginatedResponse
+
+
+class IssuesResource:
+    """Client for issue-related API endpoints.
+
+    Args:
+        http: Shared HTTP client instance.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(
+        self,
+        owner: str,
+        repo: str,
+        state: str = "open",
+        label: str | None = None,
+        assignee: str | None = None,
+        page: int = 1,
+        per_page: int = 30,
+    ) -> PaginatedResponse[Issue]:
+        """List issues in a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            state: Filter by state — ``"open"``, ``"closed"``, or ``"all"``
+                (default: ``"open"``).
+            label: Filter by label name.
+            assignee: Filter by assignee username.
+            page: Page number (1-based, default: 1).
+            per_page: Items per page (max: 100, default: 30).
+
+        Returns:
+            A :class:`~git_alternative.models.PaginatedResponse` of
+            :class:`~git_alternative.models.Issue` instances.
+        """
+        params: dict[str, Any] = {"state": state, "page": page, "per_page": per_page}
+        if label:
+            params["label"] = label
+        if assignee:
+            params["assignee"] = assignee
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/issues", params=params)
+        items = data.get("items", data if isinstance(data, list) else [])
+        issues = [Issue(**i) for i in items]
+        if isinstance(data, dict):
+            return PaginatedResponse[Issue](
+                items=issues,
+                page=data.get("page", page),
+                per_page=data.get("per_page", per_page),
+                has_next_page=data.get("has_next_page", False),
+                total_count=data.get("total_count"),
+            )
+        return PaginatedResponse[Issue](
+            items=issues,
+            page=page,
+            per_page=per_page,
+            has_next_page=False,
+        )
+
+    def get(self, owner: str, repo: str, number: int) -> Issue:
+        """Fetch a single issue by number.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: Issue number.
+
+        Returns:
+            An :class:`~git_alternative.models.Issue` instance.
+
+        Raises:
+            ForgeNotFoundError: If the issue does not exist.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/issues/{number}")
+        return Issue(**data)
+
+    def create(
+        self,
+        owner: str,
+        repo: str,
+        title: str,
+        body: str | None = None,
+        labels: list[str] | None = None,
+        assignees: list[str] | None = None,
+        milestone_id: str | None = None,
+    ) -> Issue:
+        """Create a new issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            title: Issue title.
+            body: Optional Markdown body.
+            labels: Optional list of label names to attach.
+            assignees: Optional list of usernames to assign.
+            milestone_id: Optional milestone UUID string.
+
+        Returns:
+            The newly created :class:`~git_alternative.models.Issue`.
+        """
+        payload: dict[str, Any] = {"title": title}
+        if body is not None:
+            payload["body"] = body
+        if labels:
+            payload["labels"] = labels
+        if assignees:
+            payload["assignees"] = assignees
+        if milestone_id:
+            payload["milestone_id"] = milestone_id
+        data = self._http.post(f"/api/v1/repos/{owner}/{repo}/issues", json=payload)
+        return Issue(**data)
+
+    def update(
+        self,
+        owner: str,
+        repo: str,
+        number: int,
+        title: str | None = None,
+        body: str | None = None,
+        state: IssueState | None = None,
+    ) -> Issue:
+        """Update an existing issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: Issue number.
+            title: New title (omit to leave unchanged).
+            body: New body (omit to leave unchanged).
+            state: New state (omit to leave unchanged).
+
+        Returns:
+            The updated :class:`~git_alternative.models.Issue`.
+        """
+        payload: dict[str, Any] = {}
+        if title is not None:
+            payload["title"] = title
+        if body is not None:
+            payload["body"] = body
+        if state is not None:
+            payload["state"] = state.value
+        data = self._http.patch(f"/api/v1/repos/{owner}/{repo}/issues/{number}", json=payload)
+        return Issue(**data)
+
+    def close(self, owner: str, repo: str, number: int) -> Issue:
+        """Close an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: Issue number.
+
+        Returns:
+            The updated :class:`~git_alternative.models.Issue`.
+        """
+        return self.update(owner, repo, number, state=IssueState.CLOSED)
+
+    def reopen(self, owner: str, repo: str, number: int) -> Issue:
+        """Reopen a closed issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: Issue number.
+
+        Returns:
+            The updated :class:`~git_alternative.models.Issue`.
+        """
+        return self.update(owner, repo, number, state=IssueState.OPEN)
+
+    def delete(self, owner: str, repo: str, number: int) -> None:
+        """Delete an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: Issue number.
+        """
+        self._http.delete(f"/api/v1/repos/{owner}/{repo}/issues/{number}")
+
+    def list_comments(self, owner: str, repo: str, number: int) -> list[Comment]:
+        """List comments on an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: Issue number.
+
+        Returns:
+            List of :class:`~git_alternative.models.Comment` instances.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/issues/{number}/comments")
+        return [Comment(**c) for c in data]
+
+    def add_comment(self, owner: str, repo: str, issue_number: int, body: str) -> Comment:
+        """Add a comment to an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+            body: Comment body (Markdown supported).
+
+        Returns:
+            The newly created :class:`~git_alternative.models.Comment`.
+        """
+        data = self._http.post(
+            f"/api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments",
+            json={"body": body},
+        )
+        return Comment(**data)
+
+    def update_comment(
+        self, owner: str, repo: str, issue_number: int, comment_id: str, body: str
+    ) -> Comment:
+        """Update an existing comment.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+            comment_id: Comment UUID string.
+            body: New comment body.
+
+        Returns:
+            The updated :class:`~git_alternative.models.Comment`.
+        """
+        data = self._http.patch(
+            f"/api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments/{comment_id}",
+            json={"body": body},
+        )
+        return Comment(**data)
+
+    def delete_comment(
+        self, owner: str, repo: str, issue_number: int, comment_id: str
+    ) -> None:
+        """Delete a comment from an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+            comment_id: Comment UUID string.
+        """
+        self._http.delete(
+            f"/api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments/{comment_id}"
+        )
+
+    def list_labels(self, owner: str, repo: str) -> list[Label]:
+        """List all labels in a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+
+        Returns:
+            List of :class:`~git_alternative.models.Label` instances.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/labels")
+        return [Label(**lb) for lb in data]
+
+    def create_label(
+        self, owner: str, repo: str, name: str, color: str, description: str | None = None
+    ) -> Label:
+        """Create a new label in a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            name: Label name.
+            color: Hex color string (e.g., ``"#ff0000"``).
+            description: Optional label description.
+
+        Returns:
+            The newly created :class:`~git_alternative.models.Label`.
+        """
+        payload: dict[str, Any] = {"name": name, "color": color}
+        if description is not None:
+            payload["description"] = description
+        data = self._http.post(f"/api/v1/repos/{owner}/{repo}/labels", json=payload)
+        return Label(**data)