gitcode-api 1.0.0__py3-none-any.whl

gitcode_api/__init__.py

@@ -0,0 +1,23 @@
+"""Public package exports for the GitCode SDK."""
+
+from pathlib import Path
+
+from ._client import AsyncGitCode, GitCode
+from ._exceptions import (
+    GitCodeAPIError,
+    GitCodeConfigurationError,
+    GitCodeError,
+    GitCodeHTTPStatusError,
+)
+
+__version__ = (Path(__file__).parent / "version.txt").read_text().strip()
+
+__all__ = [
+    "__version__",
+    "AsyncGitCode",
+    "GitCode",
+    "GitCodeAPIError",
+    "GitCodeConfigurationError",
+    "GitCodeError",
+    "GitCodeHTTPStatusError",
+]

gitcode_api/_base_client.py

@@ -0,0 +1,324 @@
+"""Shared transport helpers for the GitCode SDK.
+
+The classes in this module normalize authentication, URL construction,
+payload cleanup, and response parsing for both sync and async clients.
+"""
+
+import os
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from ._exceptions import GitCodeConfigurationError, GitCodeHTTPStatusError
+
+DEFAULT_BASE_URL = "https://api.gitcode.com/api/v5"
+DEFAULT_TIMEOUT = 30.0
+DEFAULT_TOKEN_ENV = "GITCODE_ACCESS_TOKEN"
+
+
+def _drop_none_values(mapping: dict[str, Any]) -> dict[str, Any]:
+    """Return a copy of ``mapping`` without keys that have ``None`` values."""
+    return {key: value for key, value in mapping.items() if value is not None}
+
+
+class BaseGitCodeClient:
+    """Base configuration shared by synchronous and asynchronous clients.
+
+    :param api_key: Personal access token for the GitCode API.
+    :param owner: Default repository owner for repository-scoped calls.
+    :param repo: Default repository name for repository-scoped calls.
+    :param base_url: Base URL for the GitCode REST API.
+    :param timeout: Request timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        owner: str | None = None,
+        repo: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = None,
+    ) -> None:
+        """Store client configuration and resolve authentication."""
+        self.api_key = self._resolve_api_key(api_key)
+        self.owner = owner
+        self.repo = repo
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout if timeout is not None else DEFAULT_TIMEOUT
+
+    def _resolve_api_key(self, api_key: str | None) -> str:
+        """Resolve the access token from an argument or environment variable."""
+        token = api_key or os.getenv(DEFAULT_TOKEN_ENV)
+        if not token:
+            raise GitCodeConfigurationError("No API key provided. Pass api_key=... or set GITCODE_ACCESS_TOKEN.")
+        return token
+
+    def _resolve_repo_context(
+        self,
+        owner: str | None = None,
+        repo: str | None = None,
+    ) -> tuple[str, str]:
+        """Return the effective repository owner and name for a request."""
+        resolved_owner = owner or self.owner
+        resolved_repo = repo or self.repo
+        if not resolved_owner or not resolved_repo:
+            raise GitCodeConfigurationError(
+                "Repository methods require owner and repo, either per-call or on the client."
+            )
+        return resolved_owner, resolved_repo
+
+    def _headers(self, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+        """Build request headers for authenticated JSON API calls."""
+        headers = {
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self.api_key}",
+        }
+        if extra_headers:
+            headers.update(extra_headers)
+        return headers
+
+    def _encode_segment(self, value: str | int) -> str:
+        """Percent-encode a single URL path segment."""
+        return quote(str(value), safe="")
+
+    def _encode_path_value(self, value: str) -> str:
+        """Percent-encode a repository path while preserving slashes."""
+        return quote(value, safe="/")
+
+    def _join_path(self, *segments: str | int) -> str:
+        """Join URL path segments into an API path."""
+        return "/" + "/".join(self._encode_segment(segment) for segment in segments)
+
+    def _repo_path(
+        self,
+        *segments: str | int,
+        owner: str | None = None,
+        repo: str | None = None,
+    ) -> str:
+        """Build a path under ``/repos/{owner}/{repo}``."""
+        resolved_owner, resolved_repo = self._resolve_repo_context(owner, repo)
+        return self._join_path("repos", resolved_owner, resolved_repo, *segments)
+
+    def _repo_file_path(
+        self,
+        prefix: str,
+        file_path: str,
+        *,
+        owner: str | None = None,
+        repo: str | None = None,
+    ) -> str:
+        """Build a file-oriented repository path such as ``contents`` or ``raw``."""
+        resolved_owner, resolved_repo = self._resolve_repo_context(owner, repo)
+        return (
+            f"/repos/{self._encode_segment(resolved_owner)}/"
+            f"{self._encode_segment(resolved_repo)}/{self._encode_segment(prefix)}/"
+            f"{self._encode_path_value(file_path)}"
+        )
+
+    def _path(self, *segments: str | int) -> str:
+        """Build a non-repository API path."""
+        return self._join_path(*segments)
+
+    def _full_url(self, path: str) -> str:
+        """Return an absolute URL for a relative API path."""
+        if path.startswith("http://") or path.startswith("https://"):
+            return path
+        return f"{self.base_url}{path}"
+
+    def _coerce_payload(
+        self,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: dict[str, Any] | None = None,
+    ) -> tuple[dict[str, Any] | None, Any, dict[str, Any] | None]:
+        """Drop ``None`` values from params and form payloads before sending."""
+        clean_params = _drop_none_values(params or {}) or None
+        clean_data = _drop_none_values(data or {}) or None
+        return clean_params, json, clean_data
+
+    def _raise_for_error(self, response: httpx.Response) -> None:
+        """Raise a typed SDK error for non-successful HTTP responses."""
+        if response.is_success:
+            return
+
+        payload: Any
+        message = response.text
+        try:
+            payload = response.json()
+            if isinstance(payload, dict) and payload.get("message"):
+                message = str(payload["message"])
+        except ValueError:
+            payload = response.text
+
+        raise GitCodeHTTPStatusError(
+            message or f"GitCode API request failed with status {response.status_code}.",
+            status_code=response.status_code,
+            request_id=response.headers.get("X-Request-Id"),
+            payload=payload,
+        )
+
+    def _parse_response(self, response: httpx.Response, *, raw: bool = False) -> Any:
+        """Parse a GitCode API response as raw bytes, JSON, text, or ``None``."""
+        self._raise_for_error(response)
+        if response.status_code == 204:
+            return None
+        if raw:
+            return response.content
+        if not response.content:
+            return None
+        content_type = response.headers.get("Content-Type", "")
+        if "application/json" in content_type or "text/json" in content_type:
+            return response.json()
+        try:
+            return response.json()
+        except ValueError:
+            return response.text
+
+
+class SyncAPIClient(BaseGitCodeClient):
+    """Low-level synchronous HTTP transport used by resource classes.
+
+    :param api_key: Personal access token for the GitCode API.
+    :param owner: Default repository owner for repository-scoped calls.
+    :param repo: Default repository name for repository-scoped calls.
+    :param base_url: Base URL for the GitCode REST API.
+    :param timeout: Request timeout in seconds.
+    :param http_client: Optional pre-configured ``httpx.Client`` instance.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        owner: str | None = None,
+        repo: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        """Create or reuse an ``httpx.Client`` for synchronous requests."""
+        super().__init__(api_key=api_key, owner=owner, repo=repo, base_url=base_url, timeout=timeout)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.Client(timeout=self.timeout)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        raw: bool = False,
+    ) -> Any:
+        """Send an HTTP request to the GitCode API and parse the response.
+
+        :param method: HTTP method such as ``"GET"`` or ``"POST"``.
+        :param path: Relative API path or absolute URL.
+        :param params: Optional query parameters.
+        :param json: Optional JSON request body.
+        :param data: Optional form payload.
+        :param headers: Optional extra HTTP headers.
+        :param raw: When ``True``, return response bytes instead of parsed JSON.
+        :returns: Parsed JSON payload, raw bytes, text, or ``None``.
+        """
+        clean_params, clean_json, clean_data = self._coerce_payload(params=params, json=json, data=data)
+        response = self._client.request(
+            method,
+            self._full_url(path),
+            params=clean_params,
+            json=clean_json,
+            data=clean_data,
+            headers=self._headers(headers),
+        )
+        return self._parse_response(response, raw=raw)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client if this instance created it."""
+        if self._owns_client:
+            self._client.close()
+
+    def __enter__(self) -> "SyncAPIClient":
+        """Enter a context manager and return the client instance."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        """Close the client when leaving a context manager."""
+        self.close()
+
+
+class AsyncAPIClient(BaseGitCodeClient):
+    """Low-level asynchronous HTTP transport used by async resource classes.
+
+    :param api_key: Personal access token for the GitCode API.
+    :param owner: Default repository owner for repository-scoped calls.
+    :param repo: Default repository name for repository-scoped calls.
+    :param base_url: Base URL for the GitCode REST API.
+    :param timeout: Request timeout in seconds.
+    :param http_client: Optional pre-configured ``httpx.AsyncClient`` instance.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        owner: str | None = None,
+        repo: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """Create or reuse an ``httpx.AsyncClient`` for asynchronous requests."""
+        super().__init__(api_key=api_key, owner=owner, repo=repo, base_url=base_url, timeout=timeout)
+        self._owns_client = http_client is None
+        self._client = http_client or httpx.AsyncClient(timeout=self.timeout)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json: Any = None,
+        data: dict[str, Any] | None = None,
+        headers: dict[str, str] | None = None,
+        raw: bool = False,
+    ) -> Any:
+        """Send an asynchronous HTTP request to the GitCode API.
+
+        :param method: HTTP method such as ``"GET"`` or ``"POST"``.
+        :param path: Relative API path or absolute URL.
+        :param params: Optional query parameters.
+        :param json: Optional JSON request body.
+        :param data: Optional form payload.
+        :param headers: Optional extra HTTP headers.
+        :param raw: When ``True``, return response bytes instead of parsed JSON.
+        :returns: Parsed JSON payload, raw bytes, text, or ``None``.
+        """
+        clean_params, clean_json, clean_data = self._coerce_payload(params=params, json=json, data=data)
+        response = await self._client.request(
+            method,
+            self._full_url(path),
+            params=clean_params,
+            json=clean_json,
+            data=clean_data,
+            headers=self._headers(headers),
+        )
+        return self._parse_response(response, raw=raw)
+
+    async def close(self) -> None:
+        """Close the underlying async HTTP client if this instance created it."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncAPIClient":
+        """Enter an async context manager and return the client instance."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        """Close the client when leaving an async context manager."""
+        await self.close()

gitcode_api/_client.py

@@ -0,0 +1,235 @@
+"""Top-level synchronous and asynchronous GitCode API clients.
+
+These client classes expose grouped resource helpers that mirror the
+published GitCode REST API documentation.
+"""
+
+import httpx
+
+from ._base_client import DEFAULT_BASE_URL, AsyncAPIClient, SyncAPIClient
+from .resources import (
+    AsyncBranchesResource,
+    AsyncCommitsResource,
+    AsyncIssuesResource,
+    AsyncLabelsResource,
+    AsyncMembersResource,
+    AsyncMilestonesResource,
+    AsyncOAuthResource,
+    AsyncOrgsResource,
+    AsyncPullsResource,
+    AsyncReleasesResource,
+    AsyncRepoContentsResource,
+    AsyncReposResource,
+    AsyncSearchResource,
+    AsyncTagsResource,
+    AsyncUsersResource,
+    AsyncWebhooksResource,
+    BranchesResource,
+    CommitsResource,
+    IssuesResource,
+    LabelsResource,
+    MembersResource,
+    MilestonesResource,
+    OAuthResource,
+    OrgsResource,
+    PullsResource,
+    ReleasesResource,
+    RepoContentsResource,
+    ReposResource,
+    SearchResource,
+    TagsResource,
+    UsersResource,
+    WebhooksResource,
+)
+
+
+class GitCode(SyncAPIClient):
+    """Synchronous GitCode API client.
+
+    :param api_key: Personal access token used for GitCode API requests.
+    :param owner: Default repository owner used by repository-scoped helpers.
+    :param repo: Default repository name used by repository-scoped helpers.
+    :param base_url: Base URL for the GitCode REST API.
+    :param timeout: Request timeout in seconds.
+    :param http_client: Optional pre-configured ``httpx.Client`` instance.
+    """
+
+    repos: ReposResource
+    """Repository endpoints exposed as ``client.repos``."""
+
+    contents: RepoContentsResource
+    """Repository content endpoints exposed as ``client.contents``."""
+
+    branches: BranchesResource
+    """Repository branch endpoints exposed as ``client.branches``."""
+
+    commits: CommitsResource
+    """Repository commit endpoints exposed as ``client.commits``."""
+
+    issues: IssuesResource
+    """Issue endpoints exposed as ``client.issues``."""
+
+    pulls: PullsResource
+    """Pull request endpoints exposed as ``client.pulls``."""
+
+    labels: LabelsResource
+    """Label endpoints exposed as ``client.labels``."""
+
+    milestones: MilestonesResource
+    """Milestone endpoints exposed as ``client.milestones``."""
+
+    members: MembersResource
+    """Repository member endpoints exposed as ``client.members``."""
+
+    releases: ReleasesResource
+    """Release endpoints exposed as ``client.releases``."""
+
+    tags: TagsResource
+    """Tag endpoints exposed as ``client.tags``."""
+
+    webhooks: WebhooksResource
+    """Webhook endpoints exposed as ``client.webhooks``."""
+
+    users: UsersResource
+    """User endpoints exposed as ``client.users``."""
+
+    orgs: OrgsResource
+    """Organization endpoints exposed as ``client.orgs``."""
+
+    search: SearchResource
+    """Search endpoints exposed as ``client.search``."""
+
+    oauth: OAuthResource
+    """OAuth helper endpoints exposed as ``client.oauth``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        owner: str | None = None,
+        repo: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = None,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        """Create a synchronous client and attach resource groups."""
+        super().__init__(
+            api_key=api_key,
+            owner=owner,
+            repo=repo,
+            base_url=base_url,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.repos = ReposResource(self)
+        self.contents = RepoContentsResource(self)
+        self.branches = BranchesResource(self)
+        self.commits = CommitsResource(self)
+        self.issues = IssuesResource(self)
+        self.pulls = PullsResource(self)
+        self.labels = LabelsResource(self)
+        self.milestones = MilestonesResource(self)
+        self.members = MembersResource(self)
+        self.releases = ReleasesResource(self)
+        self.tags = TagsResource(self)
+        self.webhooks = WebhooksResource(self)
+        self.users = UsersResource(self)
+        self.orgs = OrgsResource(self)
+        self.search = SearchResource(self)
+        self.oauth = OAuthResource(self)
+
+
+class AsyncGitCode(AsyncAPIClient):
+    """Asynchronous GitCode API client.
+
+    :param api_key: Personal access token used for GitCode API requests.
+    :param owner: Default repository owner used by repository-scoped helpers.
+    :param repo: Default repository name used by repository-scoped helpers.
+    :param base_url: Base URL for the GitCode REST API.
+    :param timeout: Request timeout in seconds.
+    :param http_client: Optional pre-configured ``httpx.AsyncClient`` instance.
+    """
+
+    repos: AsyncReposResource
+    """Repository endpoints exposed as ``client.repos``."""
+
+    contents: AsyncRepoContentsResource
+    """Repository content endpoints exposed as ``client.contents``."""
+
+    branches: AsyncBranchesResource
+    """Repository branch endpoints exposed as ``client.branches``."""
+
+    commits: AsyncCommitsResource
+    """Repository commit endpoints exposed as ``client.commits``."""
+
+    issues: AsyncIssuesResource
+    """Issue endpoints exposed as ``client.issues``."""
+
+    pulls: AsyncPullsResource
+    """Pull request endpoints exposed as ``client.pulls``."""
+
+    labels: AsyncLabelsResource
+    """Label endpoints exposed as ``client.labels``."""
+
+    milestones: AsyncMilestonesResource
+    """Milestone endpoints exposed as ``client.milestones``."""
+
+    members: AsyncMembersResource
+    """Repository member endpoints exposed as ``client.members``."""
+
+    releases: AsyncReleasesResource
+    """Release endpoints exposed as ``client.releases``."""
+
+    tags: AsyncTagsResource
+    """Tag endpoints exposed as ``client.tags``."""
+
+    webhooks: AsyncWebhooksResource
+    """Webhook endpoints exposed as ``client.webhooks``."""
+
+    users: AsyncUsersResource
+    """User endpoints exposed as ``client.users``."""
+
+    orgs: AsyncOrgsResource
+    """Organization endpoints exposed as ``client.orgs``."""
+
+    search: AsyncSearchResource
+    """Search endpoints exposed as ``client.search``."""
+
+    oauth: AsyncOAuthResource
+    """OAuth helper endpoints exposed as ``client.oauth``."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        owner: str | None = None,
+        repo: str | None = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        """Create an asynchronous client and attach resource groups."""
+        super().__init__(
+            api_key=api_key,
+            owner=owner,
+            repo=repo,
+            base_url=base_url,
+            timeout=timeout,
+            http_client=http_client,
+        )
+        self.repos = AsyncReposResource(self)
+        self.contents = AsyncRepoContentsResource(self)
+        self.branches = AsyncBranchesResource(self)
+        self.commits = AsyncCommitsResource(self)
+        self.issues = AsyncIssuesResource(self)
+        self.pulls = AsyncPullsResource(self)
+        self.labels = AsyncLabelsResource(self)
+        self.milestones = AsyncMilestonesResource(self)
+        self.members = AsyncMembersResource(self)
+        self.releases = AsyncReleasesResource(self)
+        self.tags = AsyncTagsResource(self)
+        self.webhooks = AsyncWebhooksResource(self)
+        self.users = AsyncUsersResource(self)
+        self.orgs = AsyncOrgsResource(self)
+        self.search = AsyncSearchResource(self)
+        self.oauth = AsyncOAuthResource(self)

gitcode_api/_exceptions.py

@@ -0,0 +1,39 @@
+"""Custom exceptions raised by the GitCode SDK."""
+
+from typing import Any
+
+
+class GitCodeError(Exception):
+    """Base exception for all GitCode SDK errors."""
+
+
+class GitCodeConfigurationError(GitCodeError):
+    """Raised when client configuration is incomplete or invalid."""
+
+
+class GitCodeAPIError(GitCodeError):
+    """Raised when the GitCode API returns an error response.
+
+    :param message: Human-readable error message.
+    :param status_code: HTTP status code returned by the API.
+    :param request_id: Optional GitCode request identifier.
+    :param payload: Parsed error payload when available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        request_id: str | None = None,
+        payload: Any = None,
+    ) -> None:
+        """Store structured error metadata from a failed API response."""
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+        self.payload = payload
+
+
+class GitCodeHTTPStatusError(GitCodeAPIError):
+    """Raised for non-success HTTP responses from the GitCode API."""