gitcode-api 1.0.0__tar.gz → 1.1.0__tar.gz

{gitcode_api-1.0.0 → gitcode_api-1.1.0}/PKG-INFO

@@ -1,8 +1,13 @@
 Metadata-Version: 2.4
 Name: gitcode-api
-Version: 1.0.0
-Project-URL: github, https://github.com/Trenza1ore/GitCode-API
+Version: 1.1.0
+Summary: Easy to use Python SDK for the GitCode REST API, community-maintained.
+Author-email: Hugo Huang <hugo@hugohuang.com>
+License-Expression: MIT
+Project-URL: documentation, https://gitcode-api.readthedocs.io
 Project-URL: gitcode, https://gitcode.com/SushiNinja/GitCode-API
+Project-URL: github, https://github.com/Trenza1ore/GitCode-API
+Keywords: gitcode,git,devops,api,sdk,python,httpx,client
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: Implementation :: CPython
@@ -18,12 +23,13 @@ Requires-Python: <4,>=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx
-Requires-Dist: python-dotenv
 Dynamic: license-file
 
 # GitCode-API
 
-[中文说明](README.zh.md)
+![PyPI - Version](https://img.shields.io/pypi/v/gitcode-api?link=https%3A%2F%2Fpypi.org%2Fproject%2Fgitcode-api%2F) ![GitHub Badge](https://img.shields.io/badge/github-repo-blue?logo=github&link=https%3A%2F%2Fgithub.com%2FTrenza1ore%2FGitCode-API) ![GitCode Badge](https://img.shields.io/badge/gitcode-repo-brown?logo=gitcode&link=https%3A%2F%2Fgitcode.com%2FSushiNinja%2FGitCode-API) ![PyPI - License](https://img.shields.io/pypi/l/gitcode-api)
+
+![Docs](https://img.shields.io/badge/%E6%96%87%E6%A1%A3-Docs-cyan?style=for-the-badge&logo=readthedocs&link=https%3A%2F%2Fgitcode-api.readthedocs.io%2Fen%2Flatest%2Findex.html) ![中文README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-brown?style=for-the-badge&logo=googledocs&link=README.zh.md) ![English README](https://img.shields.io/badge/English-README-blue?style=for-the-badge&logo=googledocs&link=README.md)
 
 `gitcode-api` is a community-maintained Python SDK for the GitCode REST API. It provides easy-to-use synchronous and asynchronous clients, repository-scoped helpers, and lightweight response models so you can work with GitCode from Python without hand-writing raw HTTP requests.
 
@@ -43,18 +49,6 @@ Install from PyPI:
 pip install gitcode-api
 ```
 
-For local development from source:
-
-```bash
-uv sync
-```
-
-Install documentation dependencies:
-
-```bash
-uv sync --group docs
-```
-
 ## Authentication
 
 Pass `api_key=` directly, or set `GITCODE_ACCESS_TOKEN` in your environment:
@@ -106,6 +100,35 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### Context managers
+
+`GitCode` and `AsyncGitCode` (and the lower-level `SyncAPIClient` / `AsyncAPIClient`) support `with` / `async with`. When the SDK creates the underlying httpx client for you, leaving the block calls `close()` / `await close()` on that client automatically.
+
+```python
+from gitcode_api import GitCode
+
+with GitCode(owner="SushiNinja", repo="GitCode-API") as client:
+    repo = client.repos.get()
+    print(repo.full_name)
+```
+
+```python
+import asyncio
+
+from gitcode_api import AsyncGitCode
+
+
+async def main() -> None:
+    async with AsyncGitCode(owner="SushiNinja", repo="GitCode-API") as client:
+        pulls = await client.pulls.list(state="open", per_page=20)
+        print(len(pulls))
+
+
+asyncio.run(main())
+```
+
+If you pass a custom `http_client=`, the SDK does not close it; you still own that client’s lifecycle (for example `async with httpx.AsyncClient(...) as http:` plus `AsyncGitCode(http_client=http)`).
+
 ## Common Workflows
 
 Create a pull request:

{gitcode_api-1.0.0 → gitcode_api-1.1.0}/README.md

@@ -1,6 +1,8 @@
 # GitCode-API
 
-[中文说明](README.zh.md)
+![PyPI - Version](https://img.shields.io/pypi/v/gitcode-api?link=https%3A%2F%2Fpypi.org%2Fproject%2Fgitcode-api%2F) ![GitHub Badge](https://img.shields.io/badge/github-repo-blue?logo=github&link=https%3A%2F%2Fgithub.com%2FTrenza1ore%2FGitCode-API) ![GitCode Badge](https://img.shields.io/badge/gitcode-repo-brown?logo=gitcode&link=https%3A%2F%2Fgitcode.com%2FSushiNinja%2FGitCode-API) ![PyPI - License](https://img.shields.io/pypi/l/gitcode-api)
+
+![Docs](https://img.shields.io/badge/%E6%96%87%E6%A1%A3-Docs-cyan?style=for-the-badge&logo=readthedocs&link=https%3A%2F%2Fgitcode-api.readthedocs.io%2Fen%2Flatest%2Findex.html) ![中文README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-brown?style=for-the-badge&logo=googledocs&link=README.zh.md) ![English README](https://img.shields.io/badge/English-README-blue?style=for-the-badge&logo=googledocs&link=README.md)
 
 `gitcode-api` is a community-maintained Python SDK for the GitCode REST API. It provides easy-to-use synchronous and asynchronous clients, repository-scoped helpers, and lightweight response models so you can work with GitCode from Python without hand-writing raw HTTP requests.
 
@@ -20,18 +22,6 @@ Install from PyPI:
 pip install gitcode-api
 ```
 
-For local development from source:
-
-```bash
-uv sync
-```
-
-Install documentation dependencies:
-
-```bash
-uv sync --group docs
-```
-
 ## Authentication
 
 Pass `api_key=` directly, or set `GITCODE_ACCESS_TOKEN` in your environment:
@@ -83,6 +73,35 @@ async def main() -> None:
 asyncio.run(main())
 ```
 
+### Context managers
+
+`GitCode` and `AsyncGitCode` (and the lower-level `SyncAPIClient` / `AsyncAPIClient`) support `with` / `async with`. When the SDK creates the underlying httpx client for you, leaving the block calls `close()` / `await close()` on that client automatically.
+
+```python
+from gitcode_api import GitCode
+
+with GitCode(owner="SushiNinja", repo="GitCode-API") as client:
+    repo = client.repos.get()
+    print(repo.full_name)
+```
+
+```python
+import asyncio
+
+from gitcode_api import AsyncGitCode
+
+
+async def main() -> None:
+    async with AsyncGitCode(owner="SushiNinja", repo="GitCode-API") as client:
+        pulls = await client.pulls.list(state="open", per_page=20)
+        print(len(pulls))
+
+
+asyncio.run(main())
+```
+
+If you pass a custom `http_client=`, the SDK does not close it; you still own that client’s lifecycle (for example `async with httpx.AsyncClient(...) as http:` plus `AsyncGitCode(http_client=http)`).
+
 ## Common Workflows
 
 Create a pull request:

{gitcode_api-1.0.0 → gitcode_api-1.1.0}/gitcode_api/_base_client.py

@@ -5,7 +5,7 @@ payload cleanup, and response parsing for both sync and async clients.
 """
 
 import os
-from typing import Any
+from typing import Any, Dict, Optional, Tuple, Union
 from urllib.parse import quote
 
 import httpx
@@ -17,7 +17,7 @@ DEFAULT_TIMEOUT = 30.0
 DEFAULT_TOKEN_ENV = "GITCODE_ACCESS_TOKEN"
 
 
-def _drop_none_values(mapping: dict[str, Any]) -> dict[str, Any]:
+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}
 
@@ -35,11 +35,11 @@ class BaseGitCodeClient:
     def __init__(
         self,
         *,
-        api_key: str | None = None,
-        owner: str | None = None,
-        repo: str | None = None,
+        api_key: Optional[str] = None,
+        owner: Optional[str] = None,
+        repo: Optional[str] = None,
         base_url: str = DEFAULT_BASE_URL,
-        timeout: float | None = None,
+        timeout: Optional[float] = None,
     ) -> None:
         """Store client configuration and resolve authentication."""
         self.api_key = self._resolve_api_key(api_key)
@@ -48,7 +48,7 @@ class BaseGitCodeClient:
         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:
+    def _resolve_api_key(self, api_key: Optional[str]) -> str:
         """Resolve the access token from an argument or environment variable."""
         token = api_key or os.getenv(DEFAULT_TOKEN_ENV)
         if not token:
@@ -57,9 +57,9 @@ class BaseGitCodeClient:
 
     def _resolve_repo_context(
         self,
-        owner: str | None = None,
-        repo: str | None = None,
-    ) -> tuple[str, str]:
+        owner: Optional[str] = None,
+        repo: Optional[str] = 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
@@ -69,7 +69,7 @@ class BaseGitCodeClient:
             )
         return resolved_owner, resolved_repo
 
-    def _headers(self, extra_headers: dict[str, str] | None = None) -> dict[str, str]:
+    def _headers(self, extra_headers: Optional[Dict[str, str]] = None) -> Dict[str, str]:
         """Build request headers for authenticated JSON API calls."""
         headers = {
             "Accept": "application/json",
@@ -79,7 +79,7 @@ class BaseGitCodeClient:
             headers.update(extra_headers)
         return headers
 
-    def _encode_segment(self, value: str | int) -> str:
+    def _encode_segment(self, value: Union[int, str]) -> str:
         """Percent-encode a single URL path segment."""
         return quote(str(value), safe="")
 
@@ -87,15 +87,15 @@ class BaseGitCodeClient:
         """Percent-encode a repository path while preserving slashes."""
         return quote(value, safe="/")
 
-    def _join_path(self, *segments: str | int) -> str:
+    def _join_path(self, *segments: Union[int, str]) -> 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,
+        *segments: Union[int, str],
+        owner: Optional[str] = None,
+        repo: Optional[str] = None,
     ) -> str:
         """Build a path under ``/repos/{owner}/{repo}``."""
         resolved_owner, resolved_repo = self._resolve_repo_context(owner, repo)
@@ -106,8 +106,8 @@ class BaseGitCodeClient:
         prefix: str,
         file_path: str,
         *,
-        owner: str | None = None,
-        repo: str | None = None,
+        owner: Optional[str] = None,
+        repo: Optional[str] = None,
     ) -> str:
         """Build a file-oriented repository path such as ``contents`` or ``raw``."""
         resolved_owner, resolved_repo = self._resolve_repo_context(owner, repo)
@@ -117,7 +117,7 @@ class BaseGitCodeClient:
             f"{self._encode_path_value(file_path)}"
         )
 
-    def _path(self, *segments: str | int) -> str:
+    def _path(self, *segments: Union[int, str]) -> str:
         """Build a non-repository API path."""
         return self._join_path(*segments)
 
@@ -130,10 +130,10 @@ class BaseGitCodeClient:
     def _coerce_payload(
         self,
         *,
-        params: dict[str, Any] | None = None,
+        params: Optional[Dict[str, Any]] = None,
         json: Any = None,
-        data: dict[str, Any] | None = None,
-    ) -> tuple[dict[str, Any] | None, Any, dict[str, Any] | None]:
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Tuple[Optional[Dict[str, Any]], Any, Optional[Dict[str, Any]]]:
         """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
@@ -192,12 +192,12 @@ class SyncAPIClient(BaseGitCodeClient):
     def __init__(
         self,
         *,
-        api_key: str | None = None,
-        owner: str | None = None,
-        repo: str | None = None,
+        api_key: Optional[str] = None,
+        owner: Optional[str] = None,
+        repo: Optional[str] = None,
         base_url: str = DEFAULT_BASE_URL,
-        timeout: float | None = None,
-        http_client: httpx.Client | None = None,
+        timeout: Optional[float] = None,
+        http_client: Optional[httpx.Client] = 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)
@@ -209,10 +209,10 @@ class SyncAPIClient(BaseGitCodeClient):
         method: str,
         path: str,
         *,
-        params: dict[str, Any] | None = None,
+        params: Optional[Dict[str, Any]] = None,
         json: Any = None,
-        data: dict[str, Any] | None = None,
-        headers: dict[str, str] | None = None,
+        data: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
         raw: bool = False,
     ) -> Any:
         """Send an HTTP request to the GitCode API and parse the response.
@@ -265,12 +265,12 @@ class AsyncAPIClient(BaseGitCodeClient):
     def __init__(
         self,
         *,
-        api_key: str | None = None,
-        owner: str | None = None,
-        repo: str | None = None,
+        api_key: Optional[str] = None,
+        owner: Optional[str] = None,
+        repo: Optional[str] = None,
         base_url: str = DEFAULT_BASE_URL,
-        timeout: float | None = None,
-        http_client: httpx.AsyncClient | None = None,
+        timeout: Optional[float] = None,
+        http_client: Optional[httpx.AsyncClient] = 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)
@@ -282,10 +282,10 @@ class AsyncAPIClient(BaseGitCodeClient):
         method: str,
         path: str,
         *,
-        params: dict[str, Any] | None = None,
+        params: Optional[Dict[str, Any]] = None,
         json: Any = None,
-        data: dict[str, Any] | None = None,
-        headers: dict[str, str] | None = None,
+        data: Optional[Dict[str, Any]] = None,
+        headers: Optional[Dict[str, str]] = None,
         raw: bool = False,
     ) -> Any:
         """Send an asynchronous HTTP request to the GitCode API.

{gitcode_api-1.0.0 → gitcode_api-1.1.0}/gitcode_api/_client.py

@@ -4,6 +4,8 @@ These client classes expose grouped resource helpers that mirror the
 published GitCode REST API documentation.
 """
 
+from typing import Optional
+
 import httpx
 
 from ._base_client import DEFAULT_BASE_URL, AsyncAPIClient, SyncAPIClient
@@ -105,12 +107,12 @@ class GitCode(SyncAPIClient):
     def __init__(
         self,
         *,
-        api_key: str | None = None,
-        owner: str | None = None,
-        repo: str | None = None,
+        api_key: Optional[str] = None,
+        owner: Optional[str] = None,
+        repo: Optional[str] = None,
         base_url: str = DEFAULT_BASE_URL,
-        timeout: float | None = None,
-        http_client: httpx.Client | None = None,
+        timeout: Optional[float] = None,
+        http_client: Optional[httpx.Client] = None,
     ) -> None:
         """Create a synchronous client and attach resource groups."""
         super().__init__(
@@ -201,12 +203,12 @@ class AsyncGitCode(AsyncAPIClient):
     def __init__(
         self,
         *,
-        api_key: str | None = None,
-        owner: str | None = None,
-        repo: str | None = None,
+        api_key: Optional[str] = None,
+        owner: Optional[str] = None,
+        repo: Optional[str] = None,
         base_url: str = DEFAULT_BASE_URL,
-        timeout: float | None = None,
-        http_client: httpx.AsyncClient | None = None,
+        timeout: Optional[float] = None,
+        http_client: Optional[httpx.AsyncClient] = None,
     ) -> None:
         """Create an asynchronous client and attach resource groups."""
         super().__init__(

{gitcode_api-1.0.0 → gitcode_api-1.1.0}/gitcode_api/_exceptions.py

@@ -1,6 +1,6 @@
 """Custom exceptions raised by the GitCode SDK."""
 
-from typing import Any
+from typing import Any, Optional
 
 
 class GitCodeError(Exception):
@@ -25,7 +25,7 @@ class GitCodeAPIError(GitCodeError):
         message: str,
         *,
         status_code: int,
-        request_id: str | None = None,
+        request_id: Optional[str] = None,
         payload: Any = None,
     ) -> None:
         """Store structured error metadata from a failed API response."""

{gitcode_api-1.0.0 → gitcode_api-1.1.0}/gitcode_api/_models.py

@@ -1,7 +1,7 @@
 """Lightweight wrappers and typed payload hints for GitCode API responses."""
 
 from dataclasses import dataclass
-from typing import Any, Iterator, List, Mapping, MutableMapping, TypedDict, TypeVar
+from typing import Any, Dict, Iterator, List, Mapping, MutableMapping, TypedDict, TypeVar, Union
 
 JsonValue = Any
 
@@ -15,7 +15,7 @@ def _wrap_value(value: Any) -> Any:
     return value
 
 
-@dataclass(slots=True)
+@dataclass
 class APIObject(Mapping[str, Any]):
     """Dictionary-backed wrapper around GitCode JSON objects.
 
@@ -48,7 +48,7 @@ class APIObject(Mapping[str, Any]):
         """Return a wrapped value with an optional default."""
         return _wrap_value(self.data.get(key, default))
 
-    def to_dict(self) -> dict[str, Any]:
+    def to_dict(self) -> Dict[str, Any]:
         """Return a shallow ``dict`` copy of the underlying payload."""
         return dict(self.data)
 
@@ -91,7 +91,7 @@ class IssueCreateParams(TypedDict, total=False):
     body: str
     assignee: str
     labels: List[str]
-    milestone: int | str
+    milestone: Union[int, str]
 
 
 class PullRequestCreateParams(TypedDict, total=False):

gitcode_api-1.1.0/gitcode_api/resources/_shared.py

@@ -0,0 +1,128 @@
+"""Shared resource base classes for the GitCode SDK."""
+
+from typing import Any, Dict, List, Optional, Union
+
+from .._base_client import AsyncAPIClient, SyncAPIClient
+from .._models import APIObject, ModelT, as_model, as_model_list
+
+
+class SyncResource:
+    """Base class for synchronous resource groups."""
+
+    def __init__(self, client: SyncAPIClient) -> None:
+        """Bind the resource to a synchronous API client."""
+        self._client = client
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Any = None,
+        data: Optional[Dict[str, Any]] = None,
+        raw: bool = False,
+    ) -> Any:
+        """Dispatch a low-level request through the owning client.
+
+        :param method: HTTP verb (for example ``GET`` or ``POST``).
+        :param path: Absolute or root-relative URL path.
+        :param params: Optional query string parameters.
+        :param json: Optional JSON-serializable request body.
+        :param data: Optional form or body fields.
+        :param raw: When ``True``, return the raw response body (for example bytes).
+        :returns: Parsed JSON, raw body, or other value from the client.
+        """
+        return self._client.request(method, path, params=params, json=json, data=data, raw=raw)
+
+    def _model(self, method: str, path: str, model_type: type[ModelT], **kwargs: Any) -> ModelT:
+        """Send a request and wrap a JSON object in ``model_type``.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class for the top-level JSON object.
+        :param kwargs: Forwarded to :meth:`_request` (``params``, ``json``, ``data``, ``raw``, etc.).
+        :returns: An instance of ``model_type``.
+        """
+        data = self._request(method, path, **kwargs)
+        return as_model(data, model_type)
+
+    def _models(self, method: str, path: str, model_type: type[ModelT], **kwargs: Any) -> List[ModelT]:
+        """Send a request and wrap a JSON array in ``model_type`` instances.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class for each element of the JSON array.
+        :param kwargs: Forwarded to :meth:`_request`.
+        :returns: A list of ``model_type`` instances.
+        """
+        data = self._request(method, path, **kwargs)
+        return as_model_list(data, model_type)
+
+    def _maybe_model(self, method: str, path: str, model_type: type[ModelT], **kwargs: Any) -> Union[ModelT, APIObject]:
+        """Wrap dict responses as models and scalar responses as ``APIObject``.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class when the response is a JSON object.
+        :param kwargs: Forwarded to :meth:`_request`.
+        :returns: ``model_type`` for dict bodies; otherwise ``APIObject`` wrapping a ``value`` field.
+        """
+        data = self._request(method, path, **kwargs)
+        if isinstance(data, dict):
+            return as_model(data, model_type)
+        return APIObject({"value": data})
+
+
+class AsyncResource:
+    """Base class for asynchronous resource groups."""
+
+    def __init__(self, client: AsyncAPIClient) -> None:
+        """Bind the resource to an asynchronous API client."""
+        self._client = client
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        json: Any = None,
+        data: Optional[Dict[str, Any]] = None,
+        raw: bool = False,
+    ) -> Any:
+        """Dispatch a low-level async request through the owning client.
+
+        :param method: HTTP verb (for example ``GET`` or ``POST``).
+        :param path: Absolute or root-relative URL path.
+        :param params: Optional query string parameters.
+        :param json: Optional JSON-serializable request body.
+        :param data: Optional form or body fields.
+        :param raw: When ``True``, return the raw response body (for example bytes).
+        :returns: Parsed JSON, raw body, or other value from the client.
+        """
+        return await self._client.request(method, path, params=params, json=json, data=data, raw=raw)
+
+    async def _model(self, method: str, path: str, model_type: type[ModelT], **kwargs: Any) -> ModelT:
+        """Send a request and wrap a JSON object in ``model_type``.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class for the top-level JSON object.
+        :param kwargs: Forwarded to :meth:`_request`.
+        :returns: An instance of ``model_type``.
+        """
+        data = await self._request(method, path, **kwargs)
+        return as_model(data, model_type)
+
+    async def _models(self, method: str, path: str, model_type: type[ModelT], **kwargs: Any) -> List[ModelT]:
+        """Send a request and wrap a JSON array in ``model_type`` instances.
+
+        :param method: HTTP verb.
+        :param path: Request path.
+        :param model_type: Model class for each element of the JSON array.
+        :param kwargs: Forwarded to :meth:`_request`.
+        :returns: A list of ``model_type`` instances.
+        """
+        data = await self._request(method, path, **kwargs)
+        return as_model_list(data, model_type)