gitcode-api 1.2.20__py3-none-any.whl → 1.3.0__py3-none-any.whl

gitcode_api/resources/{_shared.py → _shared/fetch_template.py}

@@ -1,12 +1,136 @@
-"""Shared resource base classes for the GitCode SDK."""
+"""Template resolution helpers for the GitCode SDK."""
 
-from typing import Any, Dict, List, Optional, Pattern, Tuple, Union
+from typing import Any, List, Optional, Pattern, Tuple
 
-from .._base_client import AsyncAPIClient, SyncAPIClient
-from .._base_resource import BaseResource
-from .._exceptions import GitCodeHTTPStatusError
-from .._models import APIObject, ModelT, as_model, as_model_list
-from ..constants import GITCODE_TEMPLATE_REPO
+from ..._base_client import AsyncAPIClient, SyncAPIClient
+from ..._exceptions import GitCodeHTTPStatusError
+from ...constants import GITCODE_TEMPLATE_REPO
+
+# pylint: disable=invalid-overridden-method,protected-access,redefined-builtin
+
+
+def list_gitcode_template_rows_sync(
+    client: SyncAPIClient,
+    owner: str,
+    repo: str,
+    path_pattern: Pattern[str],
+) -> List[Tuple[str, str, str, str]]:
+    """Return ``(template_owner, template_repo, path, sha)`` from the first resolution source with matches."""
+    for so, sr in _resolution_sources_sync(client, owner, repo):
+        acc: List[Tuple[str, str, str, str]] = []
+        try:
+            _walk_dot_gitcode_contents_sync(client, so, sr, ".gitcode", acc)
+            if sr != GITCODE_TEMPLATE_REPO:
+                _walk_dot_gitcode_contents_sync(client, so, sr, ".github", acc)
+        except GitCodeHTTPStatusError:
+            continue
+        rows = [(t_o, t_r, p, s) for t_o, t_r, p, s in acc if path_pattern.match(p)]
+        if rows:
+            return rows
+    return []
+
+
+async def list_gitcode_template_rows_async(
+    client: AsyncAPIClient,
+    owner: str,
+    repo: str,
+    path_pattern: Pattern[str],
+) -> List[Tuple[str, str, str, str]]:
+    """Return ``(template_owner, template_repo, path, sha)`` from the first resolution source with matches."""
+    for so, sr in await _resolution_sources_async(client, owner, repo):
+        acc: List[Tuple[str, str, str, str]] = []
+        try:
+            await _walk_dot_gitcode_contents_async(client, so, sr, ".gitcode", acc)
+            if sr != GITCODE_TEMPLATE_REPO:
+                await _walk_dot_gitcode_contents_async(client, so, sr, ".github", acc)
+        except GitCodeHTTPStatusError:
+            continue
+        rows = [(t_o, t_r, p, s) for t_o, t_r, p, s in acc if path_pattern.match(p)]
+        if rows:
+            return rows
+    return []
+
+
+def get_gitcode_template_body_sync(
+    client: SyncAPIClient,
+    path: str,
+    path_pattern: Pattern[str],
+    owner: str,
+    repo: str,
+    encoding: str = "utf-8",
+    **decoding_kwargs,
+) -> str:
+    """Fetch raw template text from the first resolution source that serves ``path``."""
+    if not path_pattern.match(path):
+        raise GitCodeHTTPStatusError(
+            "Path does not match the expected GitCode template pattern for this resource.",
+            status_code=404,
+            payload=None,
+        )
+    last_error: Optional[GitCodeHTTPStatusError] = None
+    for so, sr in _resolution_sources_sync(client, owner, repo):
+        try:
+            raw = client.request(
+                "GET",
+                client._repo_file_path("raw", path, owner=so, repo=sr),
+                raw=True,
+            )
+        except GitCodeHTTPStatusError as exc:
+            last_error = exc
+            continue
+        if isinstance(raw, bytes):
+            return raw.decode(encoding=encoding, **decoding_kwargs)
+        if isinstance(raw, str):
+            return raw
+        return str(raw)
+    if last_error is not None:
+        raise last_error
+    raise GitCodeHTTPStatusError(
+        "No template found for the given path.",
+        status_code=404,
+        payload=None,
+    )
+
+
+async def get_gitcode_template_body_async(
+    client: AsyncAPIClient,
+    path: str,
+    path_pattern: Pattern[str],
+    owner: str,
+    repo: str,
+    encoding: str = "utf-8",
+    **decoding_kwargs,
+) -> str:
+    """Fetch raw template text from the first resolution source that serves ``path``."""
+    if not path_pattern.match(path):
+        raise GitCodeHTTPStatusError(
+            "Path does not match the expected GitCode template pattern for this resource.",
+            status_code=404,
+            payload=None,
+        )
+    last_error: Optional[GitCodeHTTPStatusError] = None
+    for so, sr in await _resolution_sources_async(client, owner, repo):
+        try:
+            raw = await client.request(
+                "GET",
+                client._repo_file_path("raw", path, owner=so, repo=sr),
+                raw=True,
+            )
+        except GitCodeHTTPStatusError as exc:
+            last_error = exc
+            continue
+        if isinstance(raw, bytes):
+            return raw.decode(encoding=encoding, **decoding_kwargs)
+        if isinstance(raw, str):
+            return raw
+        return str(raw)
+    if last_error is not None:
+        raise last_error
+    raise GitCodeHTTPStatusError(
+        "No template found for the given path.",
+        status_code=404,
+        payload=None,
+    )
 
 
 def _parse_parent_owner_repo(repo_obj: Any) -> Optional[Tuple[str, str]]:
@@ -32,8 +156,6 @@ def _resolution_sources_sync(client: SyncAPIClient, owner: str, repo: str) -> Li
     fork (per ``GET /repos/{owner}/{repo}``), appends that repository's parent main repo and
     ``(parent_owner, ".gitcode")`` when not already listed (deduplicated, breadth-first).
     """
-    from .repositories import ReposResource
-
     sources: List[Tuple[str, str]] = []
     seen: set[Tuple[str, str]] = set()
 
@@ -51,7 +173,7 @@ def _resolution_sources_sync(client: SyncAPIClient, owner: str, repo: str) -> Li
         so, sr = sources[index]
         index += 1
         try:
-            meta = ReposResource(client).get(owner=so, repo=sr)
+            meta = getattr(client, "repos").get(owner=so, repo=sr)
         except GitCodeHTTPStatusError:
             continue
         if not getattr(meta, "fork", None):
@@ -68,8 +190,6 @@ def _resolution_sources_sync(client: SyncAPIClient, owner: str, repo: str) -> Li
 
 async def _resolution_sources_async(client: AsyncAPIClient, owner: str, repo: str) -> List[Tuple[str, str]]:
     """Async counterpart of :func:`_resolution_sources_sync`."""
-    from .repositories import AsyncReposResource
-
     sources: List[Tuple[str, str]] = []
     seen: set[Tuple[str, str]] = set()
 
@@ -87,7 +207,7 @@ async def _resolution_sources_async(client: AsyncAPIClient, owner: str, repo: st
         so, sr = sources[index]
         index += 1
         try:
-            meta = await AsyncReposResource(client).get(owner=so, repo=sr)
+            meta = await getattr(client, "repos").get(owner=so, repo=sr)
         except GitCodeHTTPStatusError:
             continue
         if not getattr(meta, "fork", None):
@@ -190,249 +310,3 @@ async def _walk_dot_gitcode_contents_async(
                     acc.append((template_owner, template_repo, str(pth), str(sha)))
             elif t in ("dir", "directory", "tree") and pth:
                 await _walk_dot_gitcode_contents_async(client, template_owner, template_repo, str(pth), acc)
-
-
-def list_gitcode_template_rows_sync(
-    client: SyncAPIClient,
-    owner: str,
-    repo: str,
-    path_pattern: Pattern[str],
-) -> List[Tuple[str, str, str, str]]:
-    """Return ``(template_owner, template_repo, path, sha)`` from the first resolution source with matches."""
-    for so, sr in _resolution_sources_sync(client, owner, repo):
-        acc: List[Tuple[str, str, str, str]] = []
-        try:
-            _walk_dot_gitcode_contents_sync(client, so, sr, ".gitcode", acc)
-            if sr != GITCODE_TEMPLATE_REPO:
-                _walk_dot_gitcode_contents_sync(client, so, sr, ".github", acc)
-        except GitCodeHTTPStatusError:
-            continue
-        rows = [(t_o, t_r, p, s) for t_o, t_r, p, s in acc if path_pattern.match(p)]
-        if rows:
-            return rows
-    return []
-
-
-async def list_gitcode_template_rows_async(
-    client: AsyncAPIClient,
-    owner: str,
-    repo: str,
-    path_pattern: Pattern[str],
-) -> List[Tuple[str, str, str, str]]:
-    """Return ``(template_owner, template_repo, path, sha)`` from the first resolution source with matches."""
-    for so, sr in await _resolution_sources_async(client, owner, repo):
-        acc: List[Tuple[str, str, str, str]] = []
-        try:
-            await _walk_dot_gitcode_contents_async(client, so, sr, ".gitcode", acc)
-            if sr != GITCODE_TEMPLATE_REPO:
-                await _walk_dot_gitcode_contents_async(client, so, sr, ".github", acc)
-        except GitCodeHTTPStatusError:
-            continue
-        rows = [(t_o, t_r, p, s) for t_o, t_r, p, s in acc if path_pattern.match(p)]
-        if rows:
-            return rows
-    return []
-
-
-def get_gitcode_template_body_sync(
-    client: SyncAPIClient,
-    path: str,
-    path_pattern: Pattern[str],
-    owner: str,
-    repo: str,
-    encoding: str = "utf-8",
-    **decoding_kwargs,
-) -> str:
-    """Fetch raw template text from the first resolution source that serves ``path``."""
-    if not path_pattern.match(path):
-        raise GitCodeHTTPStatusError(
-            "Path does not match the expected GitCode template pattern for this resource.",
-            status_code=404,
-            payload=None,
-        )
-    last_error: Optional[GitCodeHTTPStatusError] = None
-    for so, sr in _resolution_sources_sync(client, owner, repo):
-        try:
-            raw = client.request(
-                "GET",
-                client._repo_file_path("raw", path, owner=so, repo=sr),
-                raw=True,
-            )
-        except GitCodeHTTPStatusError as exc:
-            last_error = exc
-            continue
-        if isinstance(raw, bytes):
-            return raw.decode(encoding=encoding, **decoding_kwargs)
-        if isinstance(raw, str):
-            return raw
-        return str(raw)
-    if last_error is not None:
-        raise last_error
-    raise GitCodeHTTPStatusError(
-        "No template found for the given path.",
-        status_code=404,
-        payload=None,
-    )
-
-
-async def get_gitcode_template_body_async(
-    client: AsyncAPIClient,
-    path: str,
-    path_pattern: Pattern[str],
-    owner: str,
-    repo: str,
-    encoding: str = "utf-8",
-    **decoding_kwargs,
-) -> str:
-    """Fetch raw template text from the first resolution source that serves ``path``."""
-    if not path_pattern.match(path):
-        raise GitCodeHTTPStatusError(
-            "Path does not match the expected GitCode template pattern for this resource.",
-            status_code=404,
-            payload=None,
-        )
-    last_error: Optional[GitCodeHTTPStatusError] = None
-    for so, sr in await _resolution_sources_async(client, owner, repo):
-        try:
-            raw = await client.request(
-                "GET",
-                client._repo_file_path("raw", path, owner=so, repo=sr),
-                raw=True,
-            )
-        except GitCodeHTTPStatusError as exc:
-            last_error = exc
-            continue
-        if isinstance(raw, bytes):
-            return raw.decode(encoding=encoding, **decoding_kwargs)
-        if isinstance(raw, str):
-            return raw
-        return str(raw)
-    if last_error is not None:
-        raise last_error
-    raise GitCodeHTTPStatusError(
-        "No template found for the given path.",
-        status_code=404,
-        payload=None,
-    )
-
-
-class SyncResource(BaseResource):
-    """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) -> 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) -> 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) -> 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(BaseResource):
-    """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) -> 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) -> 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)

gitcode_api/resources/account/__init__.py

@@ -0,0 +1,17 @@
+"""Classes for resource groups: OAuth, organizations, search, and users."""
+
+from .oauth_resource_group import AsyncOAuthResource, OAuthResource
+from .orgs_resource_group import AsyncOrgsResource, OrgsResource
+from .search_resource_group import AsyncSearchResource, SearchResource
+from .users_resource_group import AsyncUsersResource, UsersResource
+
+__all__ = [
+    "AsyncOAuthResource",
+    "AsyncOrgsResource",
+    "AsyncSearchResource",
+    "AsyncUsersResource",
+    "OAuthResource",
+    "OrgsResource",
+    "SearchResource",
+    "UsersResource",
+]

gitcode_api/resources/account/oauth_resource_group.py

@@ -0,0 +1,159 @@
+"""AbstractOAuthResource, OAuthResource, and AsyncOAuthResource resource group."""
+
+from abc import ABC, abstractmethod
+from typing import Optional
+from urllib.parse import urlencode
+
+import httpx
+
+from ..._models import OAuthToken
+from .._shared import AsyncResource, SyncResource
+
+# mypy: disable-error-code=override
+# pylint: disable=invalid-overridden-method,protected-access,redefined-builtin
+
+OAUTH_BASE_URL = "https://gitcode.com"
+
+
+class AbstractOAuthResource(ABC):
+    """Interface for OAuth resource endpoints."""
+
+    @abstractmethod
+    def build_authorize_url(
+        self,
+        *,
+        client_id: str,
+        redirect_uri: str,
+        scope: Optional[str] = None,
+        state: Optional[str] = None,
+        response_type: str = "code",
+    ) -> str:
+        """Build the GitCode OAuth authorization URL.
+
+        :param client_id: OAuth application client ID.
+        :param redirect_uri: Registered redirect URI.
+        :param scope: Optional OAuth scopes.
+        :param state: Optional CSRF protection value.
+        :param response_type: OAuth response type, defaults to ``"code"``.
+        :returns: Browser URL for the authorization step.
+        """
+
+    @abstractmethod
+    def exchange_token(self, *, code: str, client_id: str, client_secret: str) -> OAuthToken:
+        """Exchange an authorization code for an OAuth token.
+
+        :param code: Authorization code returned by GitCode.
+        :param client_id: OAuth application client ID.
+        :param client_secret: OAuth application client secret.
+        :returns: OAuth access token payload.
+        """
+
+    @abstractmethod
+    def refresh_token(self, *, refresh_token: str) -> OAuthToken:
+        """Refresh an OAuth token.
+
+        :param refresh_token: Refresh token previously issued by GitCode.
+        :returns: Refreshed OAuth token payload.
+        """
+
+
+class OAuthResource(SyncResource, AbstractOAuthResource):
+    """Helpers for GitCode OAuth URLs and token exchange."""
+
+    def build_authorize_url(
+        self,
+        *,
+        client_id: str,
+        redirect_uri: str,
+        scope: Optional[str] = None,
+        state: Optional[str] = None,
+        response_type: str = "code",
+    ) -> str:
+        query = urlencode(
+            {
+                key: value
+                for key, value in {
+                    "client_id": client_id,
+                    "redirect_uri": redirect_uri,
+                    "response_type": response_type,
+                    "scope": scope,
+                    "state": state,
+                }.items()
+                if value is not None
+            }
+        )
+        return f"{OAUTH_BASE_URL}/oauth/authorize?{query}"
+
+    def exchange_token(self, *, code: str, client_id: str, client_secret: str) -> OAuthToken:
+        response = httpx.post(
+            f"{OAUTH_BASE_URL}/oauth/token",
+            params={"grant_type": "authorization_code", "code": code, "client_id": client_id},
+            data={"client_secret": client_secret},
+            headers={"Accept": "application/json"},
+            timeout=self._client.timeout,
+        )
+        response.raise_for_status()
+        return OAuthToken(dict(response.json()))
+
+    def refresh_token(self, *, refresh_token: str) -> OAuthToken:
+        response = httpx.post(
+            f"{OAUTH_BASE_URL}/oauth/token",
+            params={"grant_type": "refresh_token", "refresh_token": refresh_token},
+            headers={"Accept": "application/json"},
+            timeout=self._client.timeout,
+        )
+        response.raise_for_status()
+        return OAuthToken(dict(response.json()))
+
+
+class AsyncOAuthResource(AsyncResource, AbstractOAuthResource):
+    """Asynchronous helpers for GitCode OAuth flows.
+
+    ``build_authorize_url`` matches :class:`OAuthResource` exactly. Token helpers mirror
+    :meth:`OAuthResource.exchange_token` and :meth:`OAuthResource.refresh_token` (see ``docs/rest_api/oauth``).
+    """
+
+    def build_authorize_url(
+        self,
+        *,
+        client_id: str,
+        redirect_uri: str,
+        scope: Optional[str] = None,
+        state: Optional[str] = None,
+        response_type: str = "code",
+    ) -> str:
+        query = urlencode(
+            {
+                key: value
+                for key, value in {
+                    "client_id": client_id,
+                    "redirect_uri": redirect_uri,
+                    "response_type": response_type,
+                    "scope": scope,
+                    "state": state,
+                }.items()
+                if value is not None
+            }
+        )
+        return f"{OAUTH_BASE_URL}/oauth/authorize?{query}"
+
+    async def exchange_token(self, *, code: str, client_id: str, client_secret: str) -> OAuthToken:
+        async with httpx.AsyncClient(timeout=self._client.timeout) as client:
+            response = await client.post(
+                f"{OAUTH_BASE_URL}/oauth/token",
+                params={"grant_type": "authorization_code", "code": code, "client_id": client_id},
+                data={"client_secret": client_secret},
+                headers={"Accept": "application/json"},
+            )
+        response.raise_for_status()
+        return OAuthToken(dict(response.json()))
+
+    async def refresh_token(self, *, refresh_token: str) -> OAuthToken:
+        async with httpx.AsyncClient(timeout=self._client.timeout) as client:
+            response = await client.post(
+                f"{OAUTH_BASE_URL}/oauth/token",
+                params={"grant_type": "refresh_token", "refresh_token": refresh_token},
+                headers={"Accept": "application/json"},
+            )
+        response.raise_for_status()
+        return OAuthToken(dict(response.json()))