gitcode-api 1.1.2__tar.gz → 1.2.0__tar.gz

{gitcode_api-1.1.2 → gitcode_api-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitcode-api
-Version: 1.1.2
+Version: 1.2.0
 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/`.
 
@@ -46,7 +46,7 @@ Dynamic: license-file
 Install from PyPI:
 
 ```bash
-pip install gitcode-api
+pip install -U gitcode-api
 ```
 
 ## Authentication
@@ -71,6 +71,19 @@ client = GitCode(
 )
 ```
 
+## CLI
+
+After installation, you can invoke the SDK directly from the command line:
+
+```bash
+gitcode-api repos get --api-key "$GITCODE_ACCESS_TOKEN" --owner SushiNinja --repo GitCode-API
+python -m gitcode_api pulls list --api-key "$GITCODE_ACCESS_TOKEN" --owner SushiNinja --repo GitCode-API --state open
+```
+
+Commands mirror the synchronous resource methods on `GitCode`, using the pattern
+`gitcode-api <resource> <method> ...`. For methods that accept extra `**params`
+or `**payload`, pass repeated `--set key=value` flags or `--set-json '{"key": "value"}'`.
+
 ## Quick Start
 
 ### Sync client
@@ -190,6 +203,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.2 → gitcode_api-1.2.0}/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/`.
 
@@ -19,7 +19,7 @@
 Install from PyPI:
 
 ```bash
-pip install gitcode-api
+pip install -U gitcode-api
 ```
 
 ## Authentication
@@ -44,6 +44,19 @@ client = GitCode(
 )
 ```
 
+## CLI
+
+After installation, you can invoke the SDK directly from the command line:
+
+```bash
+gitcode-api repos get --api-key "$GITCODE_ACCESS_TOKEN" --owner SushiNinja --repo GitCode-API
+python -m gitcode_api pulls list --api-key "$GITCODE_ACCESS_TOKEN" --owner SushiNinja --repo GitCode-API --state open
+```
+
+Commands mirror the synchronous resource methods on `GitCode`, using the pattern
+`gitcode-api <resource> <method> ...`. For methods that accept extra `**params`
+or `**payload`, pass repeated `--set key=value` flags or `--set-json '{"key": "value"}'`.
+
 ## Quick Start
 
 ### Sync client
@@ -163,6 +176,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.2.0/gitcode_api/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{gitcode_api-1.1.2 → gitcode_api-1.2.0}/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.0/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.0/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.2.0/gitcode_api/cli.py

@@ -0,0 +1,366 @@
+"""Command-line interface for the GitCode SDK."""
+
+import argparse
+import inspect
+import json
+import re
+import sys
+import textwrap
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any, List, Optional, Union, get_args, get_origin
+
+import httpx
+
+from . import GitCode, __version__
+from ._base_client import DEFAULT_BASE_URL, DEFAULT_TOKEN_ENV
+from ._cli_banner import format_default_welcome
+from ._exceptions import GitCodeError
+from .resources._shared import SyncResource
+
+
+class _CLIHelpFormatter(argparse.RawDescriptionHelpFormatter, argparse.ArgumentDefaultsHelpFormatter):
+    """Preserve paragraph breaks in descriptions; wider columns for signatures."""
+
+    def __init__(self, prog: str) -> None:
+        super().__init__(prog, width=108, max_help_position=32)
+
+
+def _plain_cli_inline(text: str) -> str:
+    """Strip Sphinx-style inline markup (roles, doubled literals) for terminal text."""
+    if not text:
+        return ""
+    t = re.sub(r"``\s*([^`]+?)\s*``", r"\1", text)
+    t = re.sub(r":\w+:`([^`]*)`", r"\1", t)
+    t = re.sub(r"`([^`]+)`", r"\1", t)
+    return t
+
+
+def _unwrap_optional(annotation: Any) -> Any:
+    origin = get_origin(annotation)
+    if origin is Union:
+        args = [arg for arg in get_args(annotation) if arg is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return annotation
+
+
+def _is_list_annotation(annotation: Any) -> bool:
+    annotation = _unwrap_optional(annotation)
+    return get_origin(annotation) in (list, List)
+
+
+def _list_item_type(annotation: Any) -> Any:
+    annotation = _unwrap_optional(annotation)
+    args = get_args(annotation)
+    if not args:
+        return str
+    item_type = _unwrap_optional(args[0])
+    if item_type in (int, float):
+        return item_type
+    return str
+
+
+def _argument_kwargs(parameter: inspect.Parameter) -> dict[str, Any]:
+    annotation = _unwrap_optional(parameter.annotation)
+    if annotation is bool:
+        return {"action": argparse.BooleanOptionalAction, "default": parameter.default}
+    if _is_list_annotation(parameter.annotation):
+        return {"nargs": "+", "type": _list_item_type(parameter.annotation), "default": None}
+    if annotation in (int, float):
+        return {"type": annotation}
+    return {"type": str}
+
+
+def _first_doc_line(obj: Any) -> str:
+    doc = inspect.getdoc(obj).removeprefix("Synchronous ").capitalize() or ""
+    for line in doc.splitlines():
+        stripped = line.strip()
+        if stripped:
+            return _plain_cli_inline(stripped)
+    return ""
+
+
+def _method_cli_summary(doc: str) -> str:
+    """Text before the first ':param' in the docstring, collapsed to one line for CLI help."""
+    return doc.split(":param", 1)[0].strip().replace("\n", " ")
+
+
+def _resource_types() -> dict[str, type[SyncResource]]:
+    resources: dict[str, type[SyncResource]] = {}
+    for name, annotation in GitCode.__annotations__.items():
+        if inspect.isclass(annotation) and issubclass(annotation, SyncResource):
+            resources[name] = annotation
+    return resources
+
+
+def _probe_gitcode() -> GitCode:
+    """Lightweight client used only while building -h/--help metadata (no network)."""
+    transport = httpx.MockTransport(lambda _request: httpx.Response(200, json={}))
+    return GitCode(api_key="__cli_help__", http_client=httpx.Client(transport=transport))
+
+
+def _resource_commands_epilog(resource: SyncResource) -> str:
+    """List CLI subcommand names in the same order as resource.methods on the client."""
+    kebab_names = [_kebab_case(name) for name in resource.methods]
+    joined = ", ".join(kebab_names)
+    wrapped = textwrap.fill(
+        joined,
+        width=120,
+        initial_indent="  ",
+        subsequent_indent="  ",
+        break_long_words=False,
+        break_on_hyphens=False,
+    )
+    return "Subcommands (stable SDK order, same as resource.methods):\n" + wrapped
+
+
+def _kebab_case(value: str) -> str:
+    return value.replace("_", "-")
+
+
+def _load_json_value(raw: str) -> Any:
+    if raw.startswith("@"):
+        return json.loads(Path(raw[1:]).read_text(encoding="utf-8"))
+    return json.loads(raw)
+
+
+def _parse_scalar(raw: str) -> Any:
+    try:
+        return _load_json_value(raw)
+    except (OSError, ValueError, json.JSONDecodeError):
+        return raw
+
+
+def _parse_key_value(raw: str) -> tuple[str, Any]:
+    if "=" not in raw:
+        raise ValueError(f"Expected KEY=VALUE, got: {raw}")
+    key, value = raw.split("=", maxsplit=1)
+    if not key:
+        raise ValueError(f"Expected KEY=VALUE, got: {raw}")
+    return key, _parse_scalar(value)
+
+
+def _to_data(value: Any) -> Any:
+    if hasattr(value, "to_dict") and callable(value.to_dict):
+        return _to_data(value.to_dict())
+    if isinstance(value, Mapping):
+        return {key: _to_data(item) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_to_data(item) for item in value]
+    return value
+
+
+def _write_output(value: Any, *, output_file: Optional[str], compact: bool) -> None:
+    if value is None:
+        return
+    if isinstance(value, bytes):
+        if output_file:
+            Path(output_file).write_bytes(value)
+        else:
+            sys.stdout.buffer.write(value)
+        return
+
+    payload = _to_data(value)
+    if isinstance(payload, str):
+        text = payload
+    else:
+        text = json.dumps(payload, indent=None if compact else 2, ensure_ascii=True, sort_keys=True)
+
+    if output_file:
+        Path(output_file).write_text(text + ("\n" if not text.endswith("\n") else ""), encoding="utf-8")
+    else:
+        print(text)
+
+
+def _invocation_parent_parser() -> argparse.ArgumentParser:
+    """Flags for real API calls (attached only to leaf METHOD parsers, not top-level usage)."""
+    parser = argparse.ArgumentParser(add_help=False)
+    parser.add_argument("--api-key", help=f"GitCode access token. Defaults to {DEFAULT_TOKEN_ENV}.")
+    parser.add_argument("--owner", help="Default repository owner.")
+    parser.add_argument("--repo", help="Default repository name.")
+    parser.add_argument("--base-url", default=DEFAULT_BASE_URL, help="Base URL for the REST API.")
+    parser.add_argument("--timeout", type=float, default=None, help="Request timeout in seconds.")
+    parser.add_argument("--output-file", help="Write the response to a file instead of stdout.")
+    parser.add_argument("--compact", action="store_true", help="Print JSON without indentation.")
+    return parser
+
+
+def _root_banner() -> str:
+    return "Connection and defaults are documented on each method's help: %(prog)s RESOURCE METHOD -h."
+
+
+def build_parser() -> argparse.ArgumentParser:
+    common = _invocation_parent_parser()
+    epilog = """\
+Examples:
+  %(prog)s pulls list --api-key "$GITCODE_ACCESS_TOKEN" --owner my-org --repo my-repo
+  %(prog)s users me --api-key "$GITCODE_ACCESS_TOKEN"
+  %(prog)s pulls list --set only_count=true --set reviewer=demo
+
+Extra keyword arguments (**params / **payload on some methods):
+  Repeat --set key=value (value is JSON if it parses as JSON; otherwise a string).
+  --set-json merges one JSON object (or @path/to/file.json) into those kwargs.
+
+Each resource -h lists subcommands in SDK order (resource.methods).
+Each method -h opens with resource.method_signature("<name>") from the Python SDK.
+"""
+    parser = argparse.ArgumentParser(
+        prog="gitcode-api",
+        usage="%(prog)s [-h] [--version] RESOURCE ...",
+        description=_root_banner(),
+        epilog=epilog,
+        formatter_class=_CLIHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    client = _probe_gitcode()
+    try:
+        resource_parsers = parser.add_subparsers(
+            dest="resource",
+            required=True,
+            metavar="RESOURCE",
+            title="resources",
+            description="Pick a resource group (same attribute names as on GitCode, e.g. pulls, repos).",
+        )
+        for resource_name, resource_type in _resource_types().items():
+            resource = getattr(client, resource_name)
+            class_doc = inspect.getdoc(resource_type).removeprefix("Synchronous ").capitalize() or ""
+            class_lead = class_doc.split("\n\n", maxsplit=1)[0].strip() if class_doc else ""
+            class_lead = _plain_cli_inline(class_lead) if class_lead else ""
+            resource_desc_parts = [
+                class_lead or _first_doc_line(resource_type),
+                "",
+                _resource_commands_epilog(resource),
+            ]
+            resource_parser = resource_parsers.add_parser(
+                _kebab_case(resource_name),
+                help=_first_doc_line(resource_type) or f"GitCode {resource_name} endpoints.",
+                description="\n".join(resource_desc_parts),
+                formatter_class=_CLIHelpFormatter,
+            )
+            method_parsers = resource_parser.add_subparsers(
+                dest="method",
+                required=True,
+                title="methods",
+                metavar="METHOD",
+                description=(
+                    "Method names use kebab-case. The opening line of each command's help matches "
+                    "resource.method_signature('<name>') on the Python client."
+                ),
+            )
+
+            for method_name in resource.methods:
+                method = getattr(resource, method_name)
+                sig_line = resource.method_signature(method_name)
+                doc = inspect.getdoc(method).removeprefix("Synchronous ").capitalize() or ""
+                summary = _method_cli_summary(doc)
+                if summary and len(summary) > 90:
+                    method_help = summary[:87] + "..."
+                else:
+                    method_help = summary or (sig_line if len(sig_line) <= 90 else sig_line[:87] + "...")
+                method_description = f"{summary}\n\n{sig_line}" if summary else sig_line
+
+                method_parser = method_parsers.add_parser(
+                    _kebab_case(method_name),
+                    help=method_help,
+                    description=method_description,
+                    formatter_class=_CLIHelpFormatter,
+                    parents=[common],
+                )
+                signature = inspect.signature(method)
+                for parameter in signature.parameters.values():
+                    if parameter.name == "self":
+                        continue
+                    if parameter.kind == inspect.Parameter.VAR_KEYWORD:
+                        method_parser.add_argument(
+                            "--set",
+                            dest="extra_items",
+                            action="append",
+                            default=None,
+                            metavar="KEY=VALUE",
+                            help="Extra keyword argument (merged into **params / **payload).",
+                        )
+                        method_parser.add_argument(
+                            "--set-json",
+                            dest="extra_json",
+                            default=None,
+                            metavar="JSON_OR_@FILE",
+                            help="JSON object merged into extra keyword arguments.",
+                        )
+                        continue
+
+                    flag = f"--{parameter.name.replace('_', '-')}"
+                    if flag in method_parser._option_string_actions:
+                        continue
+                    kwargs = _argument_kwargs(parameter)
+                    kwargs["dest"] = parameter.name
+                    kwargs["required"] = parameter.default is inspect.Signature.empty
+                    method_parser.add_argument(flag, **kwargs)
+
+                method_parser.set_defaults(resource_name=resource_name, method_name=method_name)
+    finally:
+        client.close()
+
+    return parser
+
+
+def _collect_kwargs(args: argparse.Namespace, method: Any) -> dict[str, Any]:
+    signature = inspect.signature(method)
+    kwargs: dict[str, Any] = {}
+    for parameter in signature.parameters.values():
+        if parameter.name == "self":
+            continue
+        if parameter.kind == inspect.Parameter.VAR_KEYWORD:
+            extra_kwargs: dict[str, Any] = {}
+            if getattr(args, "extra_json", None):
+                raw_extra = _load_json_value(args.extra_json)
+                if not isinstance(raw_extra, dict):
+                    raise ValueError("--set-json must decode to a JSON object.")
+                extra_kwargs.update(raw_extra)
+            for item in getattr(args, "extra_items", []) or []:
+                key, value = _parse_key_value(item)
+                extra_kwargs[key] = value
+            kwargs.update(extra_kwargs)
+            continue
+
+        value = getattr(args, parameter.name)
+        if value is None:
+            if parameter.default is inspect.Signature.empty:
+                raise ValueError(f"--{parameter.name.replace('_', '-')} is required.")
+            continue
+        kwargs[parameter.name] = value
+    return kwargs
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    parser = build_parser()
+    effective = list(sys.argv[1:] if argv is None else argv)
+    if not effective:
+        print(format_default_welcome(__version__), end="")
+        saved_epilog = parser.epilog
+        parser.epilog = None
+        try:
+            parser.print_help()
+        finally:
+            parser.epilog = saved_epilog
+        return 0
+    args = parser.parse_args(effective)
+
+    try:
+        with GitCode(
+            api_key=args.api_key,
+            owner=args.owner,
+            repo=args.repo,
+            base_url=args.base_url,
+            timeout=args.timeout,
+        ) as client:
+            resource = getattr(client, args.resource_name)
+            method = getattr(resource, args.method_name)
+            result = method(**_collect_kwargs(args, method))
+    except (GitCodeError, OSError, TypeError, ValueError) as exc:  # pragma: no cover - integration style
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    _write_output(result, output_file=args.output_file, compact=args.compact)
+    return 0

{gitcode_api-1.1.2 → gitcode_api-1.2.0}/gitcode_api/resources/_shared.py

@@ -3,10 +3,11 @@
 from typing import Any, Dict, List, Optional, Union
 
 from .._base_client import AsyncAPIClient, SyncAPIClient
+from .._base_resource import BaseResource
 from .._models import APIObject, ModelT, as_model, as_model_list
 
 
-class SyncResource:
+class SyncResource(BaseResource):
     """Base class for synchronous resource groups."""
 
     def __init__(self, client: SyncAPIClient) -> None:
@@ -74,7 +75,7 @@ class SyncResource:
         return APIObject({"value": data})
 
 
-class AsyncResource:
+class AsyncResource(BaseResource):
     """Base class for asynchronous resource groups."""
 
     def __init__(self, client: AsyncAPIClient) -> None:

{gitcode_api-1.1.2 → gitcode_api-1.2.0}/gitcode_api/resources/collaboration.py

@@ -476,7 +476,7 @@ class PullsResource(SyncResource):
         """Create a pull request.
 
         :param title: Pull request title.
-        :param head: Source branch ref (head branch).
+        :param head: Source branch ref (head branch, in forks use ``owner:branch`` like "SushiNinja:develop").
         :param base: Target branch ref (base branch).
         :param owner: Repository owner path. Uses the client default when omitted.
         :param repo: Repository path. Uses the client default when omitted.
@@ -490,7 +490,7 @@ class PullsResource(SyncResource):
         :param prune_source_branch: Whether to delete the source branch after merge when applicable.
         :param squash: Squash-merge preference where supported.
         :param squash_commit_message: Custom squash commit message.
-        :param fork_path: Fork namespace/path when opening a PR from a fork.
+        :param fork_path: Fork ``owner/repo`` when opening a PR from a fork, like "SushiNinja/agent-core-contrib".
         :returns: Created pull request.
         """
         return self._model(
@@ -1662,7 +1662,7 @@ class AsyncPullsResource(AsyncResource):
         """Create a pull request.
 
         :param title: Pull request title.
-        :param head: Source branch ref (head branch).
+        :param head: Source branch ref (head branch, in forks use ``owner:branch`` like "SushiNinja:develop").
         :param base: Target branch ref (base branch).
         :param owner: Repository owner path. Uses the client default when omitted.
         :param repo: Repository path. Uses the client default when omitted.
@@ -1676,7 +1676,7 @@ class AsyncPullsResource(AsyncResource):
         :param prune_source_branch: Whether to delete the source branch after merge when applicable.
         :param squash: Squash-merge preference where supported.
         :param squash_commit_message: Custom squash commit message.
-        :param fork_path: Fork namespace/path when opening a PR from a fork.
+        :param fork_path: Fork ``owner/repo`` when opening a PR from a fork, like "SushiNinja/agent-core-contrib".
         :returns: Created pull request.
         """
         return await self._model(

gitcode_api-1.2.0/gitcode_api/version.txt

@@ -0,0 +1 @@
+1.2.0

{gitcode_api-1.1.2 → gitcode_api-1.2.0}/gitcode_api.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitcode-api
-Version: 1.1.2
+Version: 1.2.0
 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/`.
 
@@ -46,7 +46,7 @@ Dynamic: license-file
 Install from PyPI:
 
 ```bash
-pip install gitcode-api
+pip install -U gitcode-api
 ```
 
 ## Authentication
@@ -71,6 +71,19 @@ client = GitCode(
 )
 ```
 
+## CLI
+
+After installation, you can invoke the SDK directly from the command line:
+
+```bash
+gitcode-api repos get --api-key "$GITCODE_ACCESS_TOKEN" --owner SushiNinja --repo GitCode-API
+python -m gitcode_api pulls list --api-key "$GITCODE_ACCESS_TOKEN" --owner SushiNinja --repo GitCode-API --state open
+```
+
+Commands mirror the synchronous resource methods on `GitCode`, using the pattern
+`gitcode-api <resource> <method> ...`. For methods that accept extra `**params`
+or `**payload`, pass repeated `--set key=value` flags or `--set-json '{"key": "value"}'`.
+
 ## Quick Start
 
 ### Sync client
@@ -190,6 +203,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.2 → gitcode_api-1.2.0}/gitcode_api.egg-info/SOURCES.txt

@@ -2,14 +2,19 @@ LICENSE
 README.md
 pyproject.toml
 gitcode_api/__init__.py
+gitcode_api/__main__.py
 gitcode_api/_base_client.py
+gitcode_api/_base_resource.py
+gitcode_api/_cli_banner.py
 gitcode_api/_client.py
 gitcode_api/_exceptions.py
 gitcode_api/_models.py
+gitcode_api/cli.py
 gitcode_api/version.txt
 gitcode_api.egg-info/PKG-INFO
 gitcode_api.egg-info/SOURCES.txt
 gitcode_api.egg-info/dependency_links.txt
+gitcode_api.egg-info/entry_points.txt
 gitcode_api.egg-info/requires.txt
 gitcode_api.egg-info/top_level.txt
 gitcode_api/resources/__init__.py
@@ -19,6 +24,7 @@ gitcode_api/resources/collaboration.py
 gitcode_api/resources/misc.py
 gitcode_api/resources/repositories.py
 tests/test_base_client.py
+tests/test_cli.py
 tests/test_client.py
 tests/test_models.py
 tests/test_resources_account.py

gitcode_api-1.2.0/gitcode_api.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+gitcode-api = gitcode_api.cli:main

{gitcode_api-1.1.2 → gitcode_api-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gitcode-api"
-version = "1.1.2"
+version = "1.2.0"
 description = "Easy to use Python SDK for the GitCode REST API, community-maintained."
 keywords = ["gitcode", "git", "devops", "api", "sdk", "python", "httpx", "client"]
 readme = "README.md"
@@ -51,6 +51,9 @@ documentation = "https://gitcode-api.readthedocs.io"
 gitcode = "https://gitcode.com/SushiNinja/GitCode-API"
 github = "https://github.com/Trenza1ore/GitCode-API"
 
+[project.scripts]
+gitcode-api = "gitcode_api.cli:main"
+
 [tool.uv]
 default-groups = ['test']
 
@@ -69,3 +72,10 @@ addopts = ["-v"]
 [tool.ruff]
 line-length = 120
 target-version = "py39"
+
+[tool.pylint.MAIN]
+ignore-paths = ["^(examples|tests|docs|scripts)/.*"]
+py-version = "3.9"
+
+[tool.pylint.FORMAT]
+max-line-length = 120

gitcode_api-1.2.0/tests/test_cli.py

@@ -0,0 +1,195 @@
+import sys
+from contextlib import redirect_stdout
+from io import StringIO
+from pathlib import Path
+from typing import Any, Dict
+
+import httpx
+import pytest
+
+from gitcode_api.cli import _kebab_case, _probe_gitcode, build_parser, main
+
+
+def _mock_sync_client(monkeypatch: Any, handler: Any) -> None:
+    mock_transport = httpx.MockTransport(handler)
+    real_client = httpx.Client
+
+    def client_with_mock_transport(*args: object, **kwargs: object) -> httpx.Client:
+        merged = dict(kwargs)
+        merged.setdefault("transport", mock_transport)
+        return real_client(*args, **merged)
+
+    monkeypatch.setattr(httpx, "Client", client_with_mock_transport)
+
+
+def test_cli_no_args_prints_help_and_exits_zero(capsys: Any, monkeypatch: Any) -> None:
+    monkeypatch.setattr(sys, "argv", ["gitcode-api"])
+    assert main() == 0
+    out = capsys.readouterr().out
+    assert "usage:" in out.lower()
+    assert "gitcode-api" in out
+    assert "_____" in out
+    assert "Examples:" not in out
+
+
+def test_cli_empty_argv_prints_help(capsys: Any) -> None:
+    assert main([]) == 0
+    out = capsys.readouterr().out.lower()
+    assert "usage:" in out
+    assert "examples:" not in out
+
+
+def test_cli_root_explicit_help_includes_epilog() -> None:
+    buf = StringIO()
+    with redirect_stdout(buf):
+        with pytest.raises(SystemExit) as exc_info:
+            build_parser().parse_args(["--help"])
+    assert exc_info.value.code == 0
+    assert "Examples:" in buf.getvalue()
+
+
+def test_cli_method_subcommands_follow_resource_methods_order() -> None:
+    """CLI lists methods in the same order as client.<resource>.methods."""
+    parser = build_parser()
+    client = _probe_gitcode()
+    try:
+        resources_action = next(
+            action for action in parser._actions if getattr(action, "choices", None) and "pulls" in action.choices
+        )
+        pulls_parser = resources_action.choices["pulls"]
+        methods_action = next(
+            action for action in pulls_parser._actions if getattr(action, "choices", None)
+        )
+        cli_kebab_order = list(methods_action.choices.keys())
+        assert cli_kebab_order == [_kebab_case(name) for name in client.pulls.methods]
+    finally:
+        client.close()
+
+
+def test_cli_method_help_description_has_summary_then_signature() -> None:
+    client = _probe_gitcode()
+    try:
+        parser = build_parser()
+        resources_action = next(
+            action for action in parser._actions if getattr(action, "choices", None) and "pulls" in action.choices
+        )
+        pulls_parser = resources_action.choices["pulls"]
+        methods_action = next(
+            action for action in pulls_parser._actions if getattr(action, "choices", None)
+        )
+        list_parser = methods_action.choices["list"]
+        sig = client.pulls.method_signature("list")
+        assert list_parser.description is not None
+        assert list_parser.description.startswith("List pull requests for a repository.")
+        assert list_parser.description.endswith(sig)
+    finally:
+        client.close()
+
+
+def test_cli_build_parser_exposes_generated_commands() -> None:
+    parser = build_parser()
+    args = parser.parse_args(
+        [
+            "oauth",
+            "build-authorize-url",
+            "--api-key",
+            "test-token",
+            "--client-id",
+            "cid",
+            "--redirect-uri",
+            "https://example.com/callback",
+        ]
+    )
+
+    assert args.resource_name == "oauth"
+    assert args.method_name == "build_authorize_url"
+
+
+def test_cli_invokes_resource_methods_and_prints_json(capsys: Any, monkeypatch: Any) -> None:
+    captured: Dict[str, Any] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["url"] = str(request.url)
+        return httpx.Response(200, json={"full_name": "SushiNinja/GitCode-API"})
+
+    _mock_sync_client(monkeypatch, handler)
+
+    exit_code = main(
+        [
+            "repos",
+            "get",
+            "--api-key",
+            "test-token",
+            "--owner",
+            "SushiNinja",
+            "--repo",
+            "GitCode-API",
+        ]
+    )
+
+    stdout = capsys.readouterr().out
+    assert exit_code == 0
+    assert "/repos/SushiNinja/GitCode-API" in captured["url"]
+    assert '"full_name": "SushiNinja/GitCode-API"' in stdout
+
+
+def test_cli_supports_extra_kwargs_via_set_flags(capsys: Any, monkeypatch: Any) -> None:
+    captured: Dict[str, Any] = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["params"] = dict(request.url.params)
+        return httpx.Response(200, json={"open": 3, "closed": 1})
+
+    _mock_sync_client(monkeypatch, handler)
+
+    exit_code = main(
+        [
+            "pulls",
+            "list",
+            "--api-key",
+            "test-token",
+            "--owner",
+            "SushiNinja",
+            "--repo",
+            "GitCode-API",
+            "--set",
+            "only_count=true",
+            "--set",
+            "reviewer=octocat",
+        ]
+    )
+
+    stdout = capsys.readouterr().out
+    assert exit_code == 0
+    assert captured["params"]["only_count"] == "true"
+    assert captured["params"]["reviewer"] == "octocat"
+    assert '"open": 3' in stdout
+
+
+def test_cli_writes_raw_bytes_to_output_file(tmp_path: Path, monkeypatch: Any) -> None:
+    output_path = tmp_path / "README.txt"
+
+    def handler(_request: httpx.Request) -> httpx.Response:
+        return httpx.Response(200, content=b"hello from gitcode")
+
+    _mock_sync_client(monkeypatch, handler)
+
+    exit_code = main(
+        [
+            "contents",
+            "get-raw",
+            "--api-key",
+            "test-token",
+            "--owner",
+            "SushiNinja",
+            "--repo",
+            "GitCode-API",
+            "--path",
+            "README.md",
+            "--output-file",
+            str(output_path),
+        ]
+    )
+
+    assert exit_code == 0
+    assert output_path.read_bytes() == b"hello from gitcode"

{gitcode_api-1.1.2 → gitcode_api-1.2.0}/tests/test_client.py

@@ -13,7 +13,7 @@ def test_client_reads_api_key_from_environment(monkeypatch: pytest.MonkeyPatch)
         assert client.api_key == "env-token"
 
 
-def test_sync_client_exposes_resource_namespaces() -> None:
+def test_sync_client_exposes_resource_groups() -> None:
     with httpx.Client(transport=httpx.MockTransport(lambda request: httpx.Response(200, json={}))) as http_client:
         client = GitCode(api_key="test-token", http_client=http_client)
         assert client.repos is not None
@@ -23,7 +23,7 @@ def test_sync_client_exposes_resource_namespaces() -> None:
 
 
 @pytest.mark.asyncio
-async def test_async_client_exposes_resource_namespaces() -> None:
+async def test_async_client_exposes_resource_groups() -> None:
     async_client = httpx.AsyncClient(transport=httpx.MockTransport(lambda request: httpx.Response(200, json={})))
     client = AsyncGitCode(api_key="test-token", http_client=async_client)
     try:
@@ -50,15 +50,12 @@ def test_sync_client_context_manager_closes_owned_http_client(monkeypatch: pytes
     assert client._client.is_closed is True
 
 
-def test_sync_client_context_manager_does_not_close_injected_http_client() -> None:
+def test_sync_client_context_manager_closes_injected_http_client() -> None:
     transport = httpx.MockTransport(lambda request: httpx.Response(200, json={}))
     http_client = httpx.Client(transport=transport)
-    try:
-        with GitCode(api_key="test-token", http_client=http_client, owner="o", repo="r"):
-            pass
+    with GitCode(api_key="test-token", http_client=http_client, owner="o", repo="r"):
         assert http_client.is_closed is False
-    finally:
-        http_client.close()
+    assert http_client.is_closed is True
 
 
 @pytest.mark.asyncio
@@ -78,12 +75,9 @@ async def test_async_client_context_manager_closes_owned_http_client(monkeypatch
 
 
 @pytest.mark.asyncio
-async def test_async_client_context_manager_does_not_close_injected_http_client() -> None:
+async def test_async_client_context_manager_closes_injected_http_client() -> None:
     transport = httpx.MockTransport(lambda request: httpx.Response(200, json={}))
     http_client = httpx.AsyncClient(transport=transport)
-    try:
-        async with AsyncGitCode(api_key="test-token", http_client=http_client, owner="o", repo="r"):
-            pass
+    async with AsyncGitCode(api_key="test-token", http_client=http_client, owner="o", repo="r"):
         assert http_client.is_closed is False
-    finally:
-        await http_client.aclose()
+    assert http_client.is_closed is True

gitcode_api-1.1.2/gitcode_api/version.txt

@@ -1 +0,0 @@
-1.1.2