gitcode-api 1.1.3__tar.gz → 1.2.1__tar.gz

{gitcode_api-1.1.3 → gitcode_api-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitcode-api
-Version: 1.1.3
+Version: 1.2.1
 Summary: Easy to use Python SDK for the GitCode REST API, community-maintained.
 Author-email: Hugo Huang <hugo@hugohuang.com>
 License-Expression: MIT
@@ -29,7 +29,7 @@ Dynamic: license-file
 
 [![PyPI - Version](https://img.shields.io/pypi/v/gitcode-api?link=https%3A%2F%2Fpypi.org%2Fproject%2Fgitcode-api%2F)](https://pypi.org/project/gitcode-api) [![GitHub Badge](https://img.shields.io/badge/github-repo-blue?logo=github&link=https%3A%2F%2Fgithub.com%2FTrenza1ore%2FGitCode-API)](https://github.com/Trenza1ore/GitCode-API) [![GitCode Badge](https://img.shields.io/badge/gitcode-repo-brown?logo=gitcode&link=https%3A%2F%2Fgitcode.com%2FSushiNinja%2FGitCode-API)](https://gitcode.com/SushiNinja/GitCode-API) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/gitcode-api?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=RED&left_text=downloads)](https://pepy.tech/projects/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)](https://gitcode-api.readthedocs.io) [![中文README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-brown?style=for-the-badge&logo=googledocs&link=README.zh.md)](README.zh.md) [![English README](https://img.shields.io/badge/English-README-blue?style=for-the-badge&logo=googledocs&link=README.md)](README.md)
+[![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)](https://gitcode-api.readthedocs.io) [![中文README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-brown?style=for-the-badge&logo=googledocs&link=README.zh.md)](README.zh.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.
 
@@ -37,7 +37,7 @@ Dynamic: license-file
 
 - Community project for developers who want a practical GitCode Python library.
 - Sync and async clients with a consistent API surface.
-- Resource namespaces such as `client.repos`, `client.pulls`, and `client.users`.
+- Resource groups such as `client.repos`, `client.pulls`, and `client.users`.
 - Repository defaults via `owner=` and `repo=` on the client.
 - Sphinx docs plus a mirrored GitCode REST API reference in `docs/`.
 
@@ -120,7 +120,7 @@ asyncio.run(main())
 
 ### Context managers
 
-`GitCode` and `AsyncGitCode` (and the lower-level `SyncAPIClient` / `AsyncAPIClient`) support `with` / `async with`. Leaving the block calls `close()` / `await close()` on the underlying client automatically, including a custom `http_client=` you passed in.
+`GitCode` and `AsyncGitCode` (and the lower-level `SyncAPIClient` / `AsyncAPIClient`) support `with` / `async with`. Leaving the block calls `close()` / `await close()` on the underlying client automatically, including a custom `http_client=` you passed in. `close()` also clears the LRU cache used by each resource group's `method_signature(...)` helper (see the [Available Resources](#available-resources) section).
 
 ```python
 from gitcode_api import GitCode
@@ -151,16 +151,13 @@ from gitcode_api import GitCode
 
 client = GitCode(owner="SushiNinja", repo="GitCode-API")
 
-try:
-    pull = client.pulls.create(
-        title="Add feature",
-        head="feature-branch",
-        base="main",
-        body="Implements the new flow.",
-    )
-    print(pull.number)
-finally:
-    client.close()
+pull = client.pulls.create(
+    title="Add feature",
+    head="feature-branch",
+    base="main",
+    body="Implements the new flow.",
+)
+print(pull.number)
 ```
 
 Get the authenticated user:
@@ -170,11 +167,8 @@ from gitcode_api import GitCode
 
 client = GitCode()
 
-try:
-    user = client.users.me()
-    print(user.login)
-finally:
-    client.close()
+user = client.users.me()
+print(user.login)
 ```
 
 Search repositories:
@@ -184,12 +178,9 @@ from gitcode_api import GitCode
 
 client = GitCode()
 
-try:
-    repos = client.search.repositories(q="sdk language:python", per_page=10)
-    for repo in repos:
-        print(repo.full_name)
-finally:
-    client.close()
+repos = client.search.repositories(q="sdk language:python", per_page=10)
+for repo in repos:
+    print(repo.full_name)
 ```
 
 ## Available Resources
@@ -203,6 +194,8 @@ Both `GitCode` and `AsyncGitCode` expose:
 - `releases`, `tags`, and `webhooks`
 - `users`, `orgs`, `search`, and `oauth`
 
+Every resource group inherits a cached `methods` property from the shared resource base: a `tuple` of public callable names in stable SDK order (underscore-segment sort key, not plain A–Z on the full identifier). Private names and the introspection helpers `methods` and `method_signature` are omitted. For example, `client.pulls.methods` helps with discovery or tooling without reading the full manual list. For one method’s parameters and return type, call `client.pulls.method_signature("list_issues")` (a cached string from `inspect.signature`, with `gitcode_api._models.` stripped from annotations).
+
 ## Examples
 
 Runnable examples live in `examples/`:

{gitcode_api-1.1.3 → gitcode_api-1.2.1}/README.md

@@ -2,7 +2,7 @@
 
 [![PyPI - Version](https://img.shields.io/pypi/v/gitcode-api?link=https%3A%2F%2Fpypi.org%2Fproject%2Fgitcode-api%2F)](https://pypi.org/project/gitcode-api) [![GitHub Badge](https://img.shields.io/badge/github-repo-blue?logo=github&link=https%3A%2F%2Fgithub.com%2FTrenza1ore%2FGitCode-API)](https://github.com/Trenza1ore/GitCode-API) [![GitCode Badge](https://img.shields.io/badge/gitcode-repo-brown?logo=gitcode&link=https%3A%2F%2Fgitcode.com%2FSushiNinja%2FGitCode-API)](https://gitcode.com/SushiNinja/GitCode-API) [![PyPI Downloads](https://static.pepy.tech/personalized-badge/gitcode-api?period=total&units=INTERNATIONAL_SYSTEM&left_color=GRAY&right_color=RED&left_text=downloads)](https://pepy.tech/projects/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)](https://gitcode-api.readthedocs.io) [![中文README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-brown?style=for-the-badge&logo=googledocs&link=README.zh.md)](README.zh.md) [![English README](https://img.shields.io/badge/English-README-blue?style=for-the-badge&logo=googledocs&link=README.md)](README.md)
+[![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)](https://gitcode-api.readthedocs.io) [![中文README](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-brown?style=for-the-badge&logo=googledocs&link=README.zh.md)](README.zh.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.
 
@@ -10,7 +10,7 @@
 
 - Community project for developers who want a practical GitCode Python library.
 - Sync and async clients with a consistent API surface.
-- Resource namespaces such as `client.repos`, `client.pulls`, and `client.users`.
+- Resource groups such as `client.repos`, `client.pulls`, and `client.users`.
 - Repository defaults via `owner=` and `repo=` on the client.
 - Sphinx docs plus a mirrored GitCode REST API reference in `docs/`.
 
@@ -93,7 +93,7 @@ asyncio.run(main())
 
 ### Context managers
 
-`GitCode` and `AsyncGitCode` (and the lower-level `SyncAPIClient` / `AsyncAPIClient`) support `with` / `async with`. Leaving the block calls `close()` / `await close()` on the underlying client automatically, including a custom `http_client=` you passed in.
+`GitCode` and `AsyncGitCode` (and the lower-level `SyncAPIClient` / `AsyncAPIClient`) support `with` / `async with`. Leaving the block calls `close()` / `await close()` on the underlying client automatically, including a custom `http_client=` you passed in. `close()` also clears the LRU cache used by each resource group's `method_signature(...)` helper (see the [Available Resources](#available-resources) section).
 
 ```python
 from gitcode_api import GitCode
@@ -124,16 +124,13 @@ from gitcode_api import GitCode
 
 client = GitCode(owner="SushiNinja", repo="GitCode-API")
 
-try:
-    pull = client.pulls.create(
-        title="Add feature",
-        head="feature-branch",
-        base="main",
-        body="Implements the new flow.",
-    )
-    print(pull.number)
-finally:
-    client.close()
+pull = client.pulls.create(
+    title="Add feature",
+    head="feature-branch",
+    base="main",
+    body="Implements the new flow.",
+)
+print(pull.number)
 ```
 
 Get the authenticated user:
@@ -143,11 +140,8 @@ from gitcode_api import GitCode
 
 client = GitCode()
 
-try:
-    user = client.users.me()
-    print(user.login)
-finally:
-    client.close()
+user = client.users.me()
+print(user.login)
 ```
 
 Search repositories:
@@ -157,12 +151,9 @@ from gitcode_api import GitCode
 
 client = GitCode()
 
-try:
-    repos = client.search.repositories(q="sdk language:python", per_page=10)
-    for repo in repos:
-        print(repo.full_name)
-finally:
-    client.close()
+repos = client.search.repositories(q="sdk language:python", per_page=10)
+for repo in repos:
+    print(repo.full_name)
 ```
 
 ## Available Resources
@@ -176,6 +167,8 @@ Both `GitCode` and `AsyncGitCode` expose:
 - `releases`, `tags`, and `webhooks`
 - `users`, `orgs`, `search`, and `oauth`
 
+Every resource group inherits a cached `methods` property from the shared resource base: a `tuple` of public callable names in stable SDK order (underscore-segment sort key, not plain A–Z on the full identifier). Private names and the introspection helpers `methods` and `method_signature` are omitted. For example, `client.pulls.methods` helps with discovery or tooling without reading the full manual list. For one method’s parameters and return type, call `client.pulls.method_signature("list_issues")` (a cached string from `inspect.signature`, with `gitcode_api._models.` stripped from annotations).
+
 ## Examples
 
 Runnable examples live in `examples/`:

{gitcode_api-1.1.3 → gitcode_api-1.2.1}/gitcode_api/__main__.py

@@ -1,3 +1,5 @@
+"""Run the package CLI via ``python -m gitcode_api``."""
+
 from .cli import main
 
 if __name__ == "__main__":

{gitcode_api-1.1.3 → gitcode_api-1.2.1}/gitcode_api/_base_client.py

@@ -10,6 +10,7 @@ from urllib.parse import quote
 
 import httpx
 
+from ._base_resource import BaseResource
 from ._exceptions import GitCodeConfigurationError, GitCodeHTTPStatusError
 
 DEFAULT_BASE_URL = "https://api.gitcode.com/api/v5"
@@ -181,6 +182,13 @@ class BaseGitCodeClient:
         except ValueError:
             return response.text
 
+    def _close_resources(self) -> None:
+        """Release resource group caches to allow for garbage collection."""
+        for attr in dir(self):
+            resource = getattr(self, attr)
+            if isinstance(resource, BaseResource):
+                resource.method_signature.cache_clear()
+
 
 class SyncAPIClient(BaseGitCodeClient):
     """Low-level synchronous HTTP transport used by resource classes.
@@ -207,7 +215,6 @@ class SyncAPIClient(BaseGitCodeClient):
     ) -> 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, decrypt=decrypt)
-        self._owns_client = http_client is None
         self._client = http_client or httpx.Client(timeout=self.timeout)
 
     def request(
@@ -244,7 +251,8 @@ class SyncAPIClient(BaseGitCodeClient):
         return self._parse_response(response, raw=raw)
 
     def close(self) -> None:
-        """Close the underlying HTTP client."""
+        """Close the underlying HTTP client and clear cache for garbage collection."""
+        self._close_resources()
         self._client.close()
 
     def __enter__(self) -> "SyncAPIClient":
@@ -281,7 +289,6 @@ class AsyncAPIClient(BaseGitCodeClient):
     ) -> 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, decrypt=decrypt)
-        self._owns_client = http_client is None
         self._client = http_client or httpx.AsyncClient(timeout=self.timeout)
 
     async def request(
@@ -318,7 +325,8 @@ class AsyncAPIClient(BaseGitCodeClient):
         return self._parse_response(response, raw=raw)
 
     async def close(self) -> None:
-        """Close the underlying async HTTP client."""
+        """Close the underlying async HTTP client and clear cache for garbage collection."""
+        self._close_resources()
         await self._client.aclose()
 
     async def __aenter__(self) -> "AsyncAPIClient":

gitcode_api-1.2.1/gitcode_api/_base_resource.py

@@ -0,0 +1,60 @@
+"""Resource base classe for the GitCode SDK."""
+
+from functools import cached_property, lru_cache
+
+_UTILITY_METHODS = {"methods", "method_signature"}
+_DATA_MODEL_PATH = "gitcode_api._models."
+
+
+class BaseResource:
+    """Resource group base class."""
+
+    def __del__(self) -> None:
+        """Attempt to clear the lru cache."""
+        self.method_signature.cache_clear()
+
+    @cached_property
+    def methods(self) -> tuple[str, ...]:
+        """Public callable names on this resource group in stable SDK order.
+
+        Ordering uses :func:`sorted` with a key derived from each name's
+        underscore-separated segments (for example two-part names are ordered
+        as if ``second_first``). This is not plain lexicographic order on the
+        full method string. Excludes ``methods``, names starting with ``_``,
+        and non-callables. The result is cached on first access.
+
+        :returns: Tuple of method names in that order.
+        """
+
+        def _is_valid_func(name: str):
+            return not (name.startswith("_") or name in _UTILITY_METHODS) and callable(getattr(self, name))
+
+        def _sort_helper(method_name: str):
+            name_parts = method_name.split("_")
+            num_part = len(name_parts)
+            if num_part == 2:
+                return f"{name_parts[1]}_{name_parts[0]}"
+            if num_part == 3:
+                return f"{{{name_parts[0]}_"
+            return "_" + method_name
+
+        return tuple(
+            sorted(
+                (func for func in dir(self) if _is_valid_func(func)),
+                key=_sort_helper,
+            )
+        )
+
+    @lru_cache(maxsize=50)
+    def method_signature(self, method_name: str) -> str:
+        """Return signature for a method in this resource group, result is cached.
+
+        For example ``client.pulls.method_signature("list_issues")`` would return:
+        list_issues(*, number: Union[int, str], owner: Optional[str] = None, repo: Optional[str] = None) -> List[Issue]
+
+        :param method_name: Attribute name of a callable on this resource.
+        :returns: Formatted signature.
+        """
+        import inspect
+
+        return method_name + str(inspect.signature(getattr(self, method_name))).replace(_DATA_MODEL_PATH, "")

gitcode_api-1.2.1/gitcode_api/_cli_banner.py

@@ -0,0 +1,31 @@
+"""ASCII art banner for command-line interface."""
+
+from functools import lru_cache
+import sys
+
+# ANSI Colour Codes
+CREDBG = "\033[41m"
+CRED = "\033[91m"
+CBLU = "\033[94m"
+CCYN = "\033[96m"
+CGRN = "\033[92m"
+CYEL = "\033[41m"
+CEND = "\033[0m"
+
+# ASCII Art Banner
+BANNER = r"""
+   _____ _ _    _____          _                 _____ _____ 
+  / ____(_) |  / ____|        | |          /\   |  __ \_   _|
+ | |  __ _| |_| |     ___   __| | ___     /  \  | |__) || |  
+ | | |_ | | __| |    / _ \ / _` |/ _ \   / /\ \ |  ___/ | |  
+ | |__| | | |_| |___| (_) | (_| |  __/  / ____ \| |    _| |_ 
+  \_____|_|\__|\_____\___/ \__,_|\___| /_/    \_\_|   |_____|
+""".strip("\n")
+
+
+@lru_cache(maxsize=1)
+def format_default_welcome(version: str) -> str:
+    """Colored banner and version line for the no-arguments launcher (plain if not a TTY)."""
+    if sys.stdout.isatty():
+        return f"{CRED}{BANNER}{CEND}\n{CBLU}  Ver. {version}{CEND}\n\n"
+    return f"{BANNER}\n  Ver. {version}\n\n"

{gitcode_api-1.1.3 → gitcode_api-1.2.1}/gitcode_api/_client.py

@@ -144,6 +144,7 @@ class GitCode(SyncAPIClient):
         self.oauth = OAuthResource(self)
 
     def __enter__(self) -> "GitCode":
+        """Enter synchronous context and return this client."""
         return self
 
 
@@ -246,4 +247,5 @@ class AsyncGitCode(AsyncAPIClient):
         self.oauth = AsyncOAuthResource(self)
 
     async def __aenter__(self) -> "AsyncGitCode":
+        """Enter asynchronous context and return this client."""
         return self

{gitcode_api-1.1.3 → gitcode_api-1.2.1}/gitcode_api/_models.py

@@ -73,6 +73,7 @@ class APIObject(Mapping[str, Any]):
     data: MutableMapping[str, Any] = field(init=False, repr=False)
 
     def __init__(self, data: Mapping[str, Any]):
+        """Initialize from API response data."""
         payload = dict(data)
         object.__setattr__(self, "data", payload)
         type_hints = get_type_hints(self.__class__)
@@ -95,24 +96,30 @@ class APIObject(Mapping[str, Any]):
             object.__setattr__(self, model_field.name, value)
 
     def __getitem__(self, key: str) -> Any:
+        """Return the value for ``key`` from the backing mapping."""
         return _wrap_value(self.data[key])
 
     def __iter__(self) -> Iterator[str]:
+        """Iterate keys of the backing mapping."""
         return iter(self.data)
 
     def __len__(self) -> int:
+        """Return the number of keys in the backing mapping."""
         return len(self.data)
 
     def __getattr__(self, name: str) -> Any:
+        """Resolve unknown attributes from the backing mapping."""
         try:
             return _wrap_value(self.data[name])
         except KeyError as exc:
             raise AttributeError(name) from exc
 
     def get(self, key: str, default: Any = None) -> Any:
+        """Return the value for ``key``, or ``default`` if missing."""
         return _wrap_value(self.data.get(key, default))
 
     def to_dict(self) -> Dict[str, Any]:
+        """Return a shallow copy of the backing mapping."""
         return dict(self.data)