git-alternative 0.2.2__py3-none-any.whl

git_alternative/resources/labels.py

@@ -0,0 +1,91 @@
+"""Label resource operations."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from git_alternative.models import Label, LabelCreate
+
+
+class LabelsResource:
+    """Operations on Forge repository labels.
+
+    Accessed via :attr:`ForgeClient.labels`.
+    """
+
+    def __init__(self, http: Any) -> None:
+        self._http = http
+
+    def list(self, owner: str, repo: str) -> list[Label]:
+        """List all labels in a repository.
+
+        Args:
+            owner: The repository owner's username.
+            repo: The repository name.
+
+        Returns:
+            A list of :class:`~git_alternative.models.Label` objects.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/labels")
+        return [Label(**item) for item in data]
+
+    def create(
+        self,
+        owner: str,
+        repo: str,
+        name: str,
+        color: str,
+        description: str | None = None,
+    ) -> Label:
+        """Create a new label.
+
+        Args:
+            owner: The repository owner's username.
+            repo: The repository name.
+            name: The label name.
+            color: The label color as a hex string (e.g., ``"#d73a4a"``).
+            description: Optional description.
+
+        Returns:
+            The newly created :class:`~git_alternative.models.Label`.
+        """
+        payload = LabelCreate(name=name, color=color, description=description)
+        data = self._http.post(
+            f"/api/v1/repos/{owner}/{repo}/labels",
+            json=payload.model_dump(exclude_none=True),
+        )
+        return Label(**data)
+
+    def update(
+        self,
+        owner: str,
+        repo: str,
+        label_id: str,
+        **kwargs: Any,
+    ) -> Label:
+        """Update an existing label.
+
+        Args:
+            owner: The repository owner's username.
+            repo: The repository name.
+            label_id: The label UUID.
+            **kwargs: Fields to update (name, color, description).
+
+        Returns:
+            The updated :class:`~git_alternative.models.Label`.
+        """
+        data = self._http.patch(
+            f"/api/v1/repos/{owner}/{repo}/labels/{label_id}",
+            json=kwargs,
+        )
+        return Label(**data)
+
+    def delete(self, owner: str, repo: str, label_id: str) -> None:
+        """Delete a label.
+
+        Args:
+            owner: The repository owner's username.
+            repo: The repository name.
+            label_id: The label UUID.
+        """
+        self._http.delete(f"/api/v1/repos/{owner}/{repo}/labels/{label_id}")

git_alternative/resources/pipelines.py

@@ -0,0 +1,118 @@
+"""CI pipelines resource client."""
+
+from __future__ import annotations
+
+from git_alternative.http import HttpClient
+from git_alternative.models import Job, Pipeline, PipelineState
+
+
+class PipelinesResource:
+    """Client for CI pipeline API endpoints.
+
+    Args:
+        http: Shared HTTP client instance.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def list(self, owner: str, repo: str, branch: str | None = None) -> list[Pipeline]:
+        """List CI pipelines for a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            branch: Filter by branch name (optional).
+
+        Returns:
+            List of :class:`~git_alternative.models.Pipeline` instances.
+        """
+        params = {}
+        if branch:
+            params["branch"] = branch
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/pipelines", params=params or None)
+        return [Pipeline(**p) for p in data]
+
+    def get(self, owner: str, repo: str, pipeline_id: str) -> Pipeline:
+        """Fetch a single pipeline by ID.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pipeline_id: Pipeline UUID string.
+
+        Returns:
+            A :class:`~git_alternative.models.Pipeline` instance.
+
+        Raises:
+            ForgeNotFoundError: If the pipeline does not exist.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/pipelines/{pipeline_id}")
+        return Pipeline(**data)
+
+    def cancel(self, owner: str, repo: str, pipeline_id: str) -> Pipeline:
+        """Cancel a running pipeline.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pipeline_id: Pipeline UUID string.
+
+        Returns:
+            The updated :class:`~git_alternative.models.Pipeline` with
+            state :attr:`PipelineState.CANCELLED`.
+        """
+        data = self._http.post(
+            f"/api/v1/repos/{owner}/{repo}/pipelines/{pipeline_id}/cancel"
+        )
+        return Pipeline(**data)
+
+    def list_jobs(self, owner: str, repo: str, pipeline_id: str) -> list[Job]:
+        """List jobs in a pipeline.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pipeline_id: Pipeline UUID string.
+
+        Returns:
+            List of :class:`~git_alternative.models.Job` instances.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/pipelines/{pipeline_id}/jobs")
+        return [Job(**j) for j in data]
+
+    def get_job_logs(
+        self, owner: str, repo: str, pipeline_id: str, job_id: str
+    ) -> str:
+        """Fetch the log output for a pipeline job.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pipeline_id: Pipeline UUID string.
+            job_id: Job UUID string.
+
+        Returns:
+            Log output as a plain text string.
+        """
+        data = self._http.get(
+            f"/api/v1/repos/{owner}/{repo}/pipelines/{pipeline_id}/jobs/{job_id}/logs"
+        )
+        if isinstance(data, dict):
+            return data.get("logs", "")
+        return str(data)
+
+    def get_commit_status(self, owner: str, repo: str, sha: str) -> PipelineState:
+        """Get the aggregate CI status for a commit.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            sha: Commit SHA.
+
+        Returns:
+            The :class:`~git_alternative.models.PipelineState` for the commit.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/commits/{sha}/status")
+        state_str = data.get("state", "pending") if isinstance(data, dict) else str(data)
+        return PipelineState(state_str)

git_alternative/resources/pulls.py

@@ -0,0 +1,207 @@
+"""Pull requests resource client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from git_alternative.http import HttpClient
+from git_alternative.models import Commit, MergeResult, MergeStrategy, PaginatedResponse, PrState, PullRequest
+
+
+class PullsResource:
+    """Client for pull request 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",
+        page: int = 1,
+        per_page: int = 30,
+    ) -> PaginatedResponse[PullRequest]:
+        """List pull requests in a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            state: Filter by state — ``"open"``, ``"closed"``, ``"merged"``,
+                or ``"all"`` (default: ``"open"``).
+            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.PullRequest` instances.
+        """
+        params: dict[str, Any] = {"state": state, "page": page, "per_page": per_page}
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/pulls", params=params)
+        items = data.get("items", data if isinstance(data, list) else [])
+        prs = [PullRequest(**p) for p in items]
+        if isinstance(data, dict):
+            return PaginatedResponse[PullRequest](
+                items=prs,
+                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[PullRequest](
+            items=prs,
+            page=page,
+            per_page=per_page,
+            has_next_page=False,
+        )
+
+    def get(self, owner: str, repo: str, number: int) -> PullRequest:
+        """Fetch a single pull request by number.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: Pull request number.
+
+        Returns:
+            A :class:`~git_alternative.models.PullRequest` instance.
+
+        Raises:
+            ForgeNotFoundError: If the PR does not exist.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/pulls/{number}")
+        return PullRequest(**data)
+
+    def create(
+        self,
+        owner: str,
+        repo: str,
+        title: str,
+        head_branch: str,
+        base_branch: str,
+        body: str | None = None,
+        draft: bool = False,
+        reviewers: list[str] | None = None,
+    ) -> PullRequest:
+        """Open a new pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            title: PR title.
+            head_branch: Source branch (may be ``owner:branch`` for cross-fork PRs).
+            base_branch: Target branch.
+            body: Optional Markdown description.
+            draft: Whether to open as a draft (default: False).
+            reviewers: Optional list of reviewer usernames.
+
+        Returns:
+            The newly created :class:`~git_alternative.models.PullRequest`.
+        """
+        payload: dict[str, Any] = {
+            "title": title,
+            "head_branch": head_branch,
+            "base_branch": base_branch,
+            "draft": draft,
+        }
+        if body is not None:
+            payload["body"] = body
+        if reviewers:
+            payload["reviewers"] = reviewers
+        data = self._http.post(f"/api/v1/repos/{owner}/{repo}/pulls", json=payload)
+        return PullRequest(**data)
+
+    def update(
+        self,
+        owner: str,
+        repo: str,
+        number: int,
+        title: str | None = None,
+        body: str | None = None,
+        state: PrState | None = None,
+    ) -> PullRequest:
+        """Update a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: PR 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.PullRequest`.
+        """
+        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}/pulls/{number}", json=payload)
+        return PullRequest(**data)
+
+    def merge(
+        self,
+        owner: str,
+        repo: str,
+        number: int,
+        strategy: MergeStrategy = MergeStrategy.MERGE,
+        commit_message: str | None = None,
+    ) -> MergeResult:
+        """Merge a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: PR number.
+            strategy: Merge strategy (default: :attr:`MergeStrategy.MERGE`).
+            commit_message: Optional custom commit message.
+
+        Returns:
+            A :class:`~git_alternative.models.MergeResult` instance.
+
+        Raises:
+            ForgeConflictError: If the PR has merge conflicts.
+        """
+        payload: dict[str, Any] = {"strategy": strategy.value}
+        if commit_message is not None:
+            payload["commit_message"] = commit_message
+        data = self._http.post(
+            f"/api/v1/repos/{owner}/{repo}/pulls/{number}/merge", json=payload
+        )
+        return MergeResult(**data)
+
+    def list_commits(self, owner: str, repo: str, number: int) -> list[Commit]:
+        """List commits in a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: PR number.
+
+        Returns:
+            List of :class:`~git_alternative.models.Commit` instances.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/pulls/{number}/commits")
+        return [Commit(**c) for c in data]
+
+    def list_files(self, owner: str, repo: str, number: int) -> list[dict[str, Any]]:
+        """List files changed in a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            number: PR number.
+
+        Returns:
+            List of file diff dictionaries with keys ``filename``,
+            ``additions``, ``deletions``, ``status``.
+        """
+        return self._http.get(f"/api/v1/repos/{owner}/{repo}/pulls/{number}/files")

git_alternative/resources/repos.py

@@ -0,0 +1,184 @@
+"""Repository resource client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from git_alternative.http import HttpClient
+from git_alternative.models import Branch, Commit, PaginatedResponse, Repository
+
+
+class ReposResource:
+    """Client for repository-related API endpoints.
+
+    Args:
+        http: Shared HTTP client instance.
+    """
+
+    def __init__(self, http: HttpClient) -> None:
+        self._http = http
+
+    def get(self, owner: str, repo: str) -> Repository:
+        """Fetch a repository by owner and name.
+
+        Args:
+            owner: Repository owner username or organisation.
+            repo: Repository name.
+
+        Returns:
+            A :class:`~git_alternative.models.Repository` instance.
+
+        Raises:
+            ForgeNotFoundError: If the repository does not exist.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}")
+        return Repository(**data)
+
+    def list(self, owner: str) -> list[Repository]:
+        """List all repositories for a user or organisation.
+
+        Args:
+            owner: Username or organisation name.
+
+        Returns:
+            List of :class:`~git_alternative.models.Repository` instances.
+        """
+        data = self._http.get(f"/api/v1/users/{owner}/repos")
+        return [Repository(**r) for r in data]
+
+    def create(
+        self,
+        name: str,
+        description: str | None = None,
+        is_private: bool = False,
+        default_branch: str = "main",
+    ) -> Repository:
+        """Create a new repository.
+
+        Args:
+            name: Repository name.
+            description: Optional description.
+            is_private: Whether the repository is private (default: False).
+            default_branch: Default branch name (default: ``main``).
+
+        Returns:
+            The newly created :class:`~git_alternative.models.Repository`.
+        """
+        payload: dict[str, Any] = {
+            "name": name,
+            "is_private": is_private,
+            "default_branch": default_branch,
+        }
+        if description is not None:
+            payload["description"] = description
+        data = self._http.post("/api/v1/repos", json=payload)
+        return Repository(**data)
+
+    def delete(self, owner: str, repo: str) -> None:
+        """Delete a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+
+        Raises:
+            ForgeNotFoundError: If the repository does not exist.
+        """
+        self._http.delete(f"/api/v1/repos/{owner}/{repo}")
+
+    def update(
+        self,
+        owner: str,
+        repo: str,
+        description: str | None = None,
+        is_private: bool | None = None,
+        default_branch: str | None = None,
+    ) -> Repository:
+        """Update repository metadata.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            description: New description (omit to leave unchanged).
+            is_private: New visibility (omit to leave unchanged).
+            default_branch: New default branch (omit to leave unchanged).
+
+        Returns:
+            The updated :class:`~git_alternative.models.Repository`.
+        """
+        payload: dict[str, Any] = {}
+        if description is not None:
+            payload["description"] = description
+        if is_private is not None:
+            payload["is_private"] = is_private
+        if default_branch is not None:
+            payload["default_branch"] = default_branch
+        data = self._http.patch(f"/api/v1/repos/{owner}/{repo}", json=payload)
+        return Repository(**data)
+
+    def fork(self, owner: str, repo: str) -> Repository:
+        """Fork a repository into the authenticated user's account.
+
+        Args:
+            owner: Source repository owner.
+            repo: Source repository name.
+
+        Returns:
+            The newly created fork as a :class:`~git_alternative.models.Repository`.
+        """
+        data = self._http.post(f"/api/v1/repos/{owner}/{repo}/forks")
+        return Repository(**data)
+
+    def list_branches(self, owner: str, repo: str) -> list[Branch]:
+        """List all branches in a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+
+        Returns:
+            List of :class:`~git_alternative.models.Branch` instances.
+        """
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/branches")
+        return [Branch(**b) for b in data]
+
+    def list_commits(
+        self,
+        owner: str,
+        repo: str,
+        branch: str | None = None,
+        page: int = 1,
+        per_page: int = 30,
+    ) -> PaginatedResponse[Commit]:
+        """List commits in a repository with pagination.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            branch: Branch name to list commits for (default: default branch).
+            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.Commit` instances.
+        """
+        params: dict[str, Any] = {"page": page, "per_page": per_page}
+        if branch:
+            params["branch"] = branch
+        data = self._http.get(f"/api/v1/repos/{owner}/{repo}/commits", params=params)
+        commits = [Commit(**c) for c in data.get("items", data if isinstance(data, list) else [])]
+        if isinstance(data, dict):
+            return PaginatedResponse[Commit](
+                items=commits,
+                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[Commit](
+            items=commits,
+            page=page,
+            per_page=per_page,
+            has_next_page=False,
+        )

git_alternative/resources/ssh_keys.py

@@ -0,0 +1,64 @@
+"""SSH key resource manager."""
+
+from __future__ import annotations
+
+from git_alternative.http import HttpSession
+from git_alternative.utils import compute_key_fingerprint
+
+
+class SshKeyResource:
+    """Manage SSH keys for Forge users.
+
+    Args:
+        session: An authenticated :class:`~git_alternative.http.HttpSession`.
+    """
+
+    def __init__(self, session: HttpSession) -> None:
+        self._session = session
+
+    def list(self, username: str) -> list[dict]:
+        """List SSH keys for a user.
+
+        Args:
+            username: The Forge username.
+
+        Returns:
+            A list of SSH key dicts with ``id``, ``title``, ``key``, and
+            ``fingerprint`` fields.
+        """
+        data = self._session.get(f"users/{username}/keys")
+        return data if isinstance(data, list) else data.get("items", [])
+
+    def add(self, username: str, key: str, title: str) -> dict:
+        """Add an SSH public key for a user.
+
+        The fingerprint is computed locally before submission so that the
+        server can enforce uniqueness on the canonical key material.
+
+        Args:
+            username: The Forge username.
+            key: The SSH public key string (``"<type> <base64> [comment]"``).
+            title: A human-readable label for the key.
+
+        Returns:
+            The created SSH key dict.
+
+        Raises:
+            ForgeValidationError: If the key string is malformed.
+            ForgeConflictError: If a key with the same fingerprint already exists.
+        """
+        fingerprint = compute_key_fingerprint(key)
+        data = self._session.post(
+            f"users/{username}/keys",
+            json={"key": key, "title": title, "fingerprint": fingerprint},
+        )
+        return data
+
+    def delete(self, username: str, key_id: str) -> None:
+        """Delete an SSH key.
+
+        Args:
+            username: The Forge username.
+            key_id: The key UUID.
+        """
+        self._session.delete(f"users/{username}/keys/{key_id}")