githubkit 0.15.2__tar.gz → 0.15.3__tar.gz

githubkit-0.15.3/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: GitHubKit
+Version: 0.15.3
+Summary: GitHub SDK for Python
+Keywords: github,octokit
+Author: yanyongyu
+Author-email: yanyongyu <yyy@yyydl.top>
+License-Expression: MIT
+Requires-Dist: anyio>=3.6.1,<5.0.0
+Requires-Dist: httpx>=0.23.0,<1.0.0
+Requires-Dist: hishel>=0.0.21,<=0.2.0
+Requires-Dist: typing-extensions>=4.11.0,<5.0.0
+Requires-Dist: pydantic>=1.9.1,!=2.5.0,!=2.5.1,<3.0.0
+Requires-Dist: pyjwt[crypto]>=2.4.0,<3.0.0 ; extra == 'all'
+Requires-Dist: pyjwt[crypto]>=2.4.0,<3.0.0 ; extra == 'auth'
+Requires-Dist: pyjwt[crypto]>=2.4.0,<3.0.0 ; extra == 'auth-app'
+Requires-Dist: pyjwt[crypto]>=2.4.0,<3.0.0 ; extra == 'jwt'
+Requires-Python: >=3.9, <4.0
+Project-URL: Homepage, https://github.com/yanyongyu/githubkit
+Project-URL: Repository, https://github.com/yanyongyu/githubkit
+Project-URL: Documentation, https://github.com/yanyongyu/githubkit
+Project-URL: Bug Tracker, https://github.com/yanyongyu/githubkit/issues
+Provides-Extra: all
+Provides-Extra: auth
+Provides-Extra: auth-app
+Provides-Extra: auth-oauth-device
+Provides-Extra: jwt
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable MD041 -->
+<div align="center">
+
+[![githubkit](https://socialify.git.ci/yanyongyu/githubkit/image?custom_description=%E2%9C%A8+The+modern%2C+all-batteries-included+GitHub+SDK+for+Python+%E2%9C%A8&description=1&descriptionEditable=%E2%9C%A8+GitHub+SDK+for+Python+%E2%9C%A8&font=Bitter&language=1&pattern=Circuit+Board&theme=Light)](https://github.com/yanyongyu/githubkit)
+
+</div>
+
+<p align="center">
+  <a href="https://raw.githubusercontent.com/yanyongyu/githubkit/master/LICENSE">
+    <img src="https://img.shields.io/github/license/yanyongyu/githubkit" alt="license">
+  </a>
+  <a href="https://pypi.python.org/pypi/githubkit">
+    <img src="https://img.shields.io/pypi/v/githubkit?logo=python&logoColor=edb641" alt="pypi">
+  </a>
+  <img src="https://img.shields.io/badge/python-3.9+-blue?logo=python&logoColor=edb641" alt="python">
+  <a href="https://github.com/psf/black">
+    <img src="https://img.shields.io/badge/code%20style-black-000000.svg?logo=python&logoColor=edb641" alt="black">
+  </a>
+  <a href="https://github.com/Microsoft/pyright">
+    <img src="https://img.shields.io/badge/types-pyright-797952.svg?logo=python&logoColor=edb641" alt="pyright">
+  </a>
+  <a href="https://github.com/astral-sh/ruff">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v2.json" alt="ruff">
+  </a>
+  <a href="https://results.pre-commit.ci/latest/github/yanyongyu/githubkit/master">
+    <img src="https://results.pre-commit.ci/badge/github/yanyongyu/githubkit/master.svg" alt="pre-commit" />
+  </a>
+</p>
+
+<div align="center">
+
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable MD036 -->
+
+_✨ The modern, all-batteries-included GitHub SDK for Python ✨_
+
+_✨ Support both **sync** and **async** calls, **fully typed** ✨_
+
+_✨ Always up to date, like octokit ✨_
+
+<!-- markdownlint-restore -->
+
+</div>
+
+<p align="center">
+  <a href="https://yanyongyu.github.io/githubkit/"><b>Documentation</b></a> |
+  <a href="https://github.com/yanyongyu/githubkit/issues"><b>Report Bug</b></a> |
+  <a href="https://docs.github.com/"><b>GitHub Docs</b></a>
+</p>
+
+githubkit aims to be an easy-to-use, fully typed, and always up-to-date GitHub SDK for Python. It is inspired by [octokit](https://github.com/octokit).
+
+githubkit provides several features including:
+
+- Support both sync and async calls
+- Multiple authentication ways and OAuth flow support
+- Calling REST API and GraphQL easily
+- REST API versioning, including GHEC
+- Built-in pagination support
+- Optional data validation with [Pydantic](https://docs.pydantic.dev/latest/), for both webhook events and REST API responses
+- Built-in http cache (powered by [Hishel](https://hishel.com/) for HTTPX) and auto retry
+- Lazy loading of APIs and models
+- Fully typed APIs
+
+## Getting Started
+
+For more, see the [documentation](https://yanyongyu.github.io/githubkit).
+
+### Installation
+
+Install githubkit with the package manager of your choice:
+
+```bash
+pip install githubkit
+# or, use poetry
+poetry add githubkit
+# or, use pdm
+pdm add githubkit
+# or, use uv
+uv add githubkit
+```
+
+### Usage
+
+Create a [Personal Access Token (PAT)](https://github.com/settings/personal-access-tokens/new) and use it to create a `GitHub` instance:
+
+```python
+from githubkit import GitHub
+
+github = GitHub("<your_token_here>")
+```
+
+Then, enjoy githubkit now!
+
+```python
+from githubkit import Response
+from githubkit.versions.latest.models import FullRepository
+
+resp: Response[FullRepository] = github.rest.repos.get("owner", "repo")
+repo: FullRepository = resp.parsed_data
+print(repo.full_name)
+```
+
+## Development
+
+> [!TIP]
+> Open in Codespaces (Dev Container):
+>
+> [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=master&repo=512138996)
+
+See the [development](https://yanyongyu.github.io/githubkit/contributing/) in the contributing guide.
+
+## Contributors
+
+Thanks to the following people who have contributed to this project:
+
+<a href="https://github.com/yanyongyu/githubkit/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=yanyongyu/githubkit&max=1000" alt="contributors" />
+</a>

githubkit-0.15.3/githubkit/config.py

@@ -0,0 +1,149 @@
+from collections.abc import Sequence
+from dataclasses import dataclass, fields
+from typing import TYPE_CHECKING, Any, Optional, Union
+from typing_extensions import Self
+
+import httpx
+
+from .cache import DEFAULT_CACHE_STRATEGY, BaseCacheStrategy
+from .retry import RETRY_DEFAULT
+from .throttling import BaseThrottler, LocalThrottler
+from .typing import EventHookTypes, ProxyTypes, RetryDecisionFunc
+
+if TYPE_CHECKING:
+    import ssl
+
+
+@dataclass(frozen=True)
+class Config:
+    base_url: httpx.URL
+    accept: str
+    user_agent: str
+    follow_redirects: bool
+    timeout: httpx.Timeout
+    ssl_verify: Union[bool, "ssl.SSLContext"]
+    trust_env: bool  # effects the `httpx` proxy and ssl cert
+    proxy: Optional[ProxyTypes]
+    transport: Optional[httpx.BaseTransport]
+    async_transport: Optional[httpx.AsyncBaseTransport]
+    event_hooks: Optional[EventHookTypes]
+    async_event_hooks: Optional[EventHookTypes]
+    cache_strategy: BaseCacheStrategy
+    http_cache: bool
+    throttler: BaseThrottler
+    auto_retry: Optional[RetryDecisionFunc]
+    rest_api_validate_body: bool
+
+    def dict(self) -> dict[str, Any]:
+        """Return the config as a dictionary without copy values."""
+        return {field.name: getattr(self, field.name) for field in fields(self)}
+
+    def copy(self) -> Self:
+        """Return a shallow copy of the config."""
+        return self.__class__(**self.dict())
+
+
+def build_base_url(base_url: Optional[Union[str, httpx.URL]]) -> httpx.URL:
+    base_url = base_url or httpx.URL("https://api.github.com/")
+    base_url = base_url if isinstance(base_url, httpx.URL) else httpx.URL(base_url)
+    # enforce trailing slash
+    if not base_url.raw_path.endswith(b"/"):
+        base_url = base_url.copy_with(raw_path=base_url.raw_path + b"/")
+    return base_url
+
+
+def build_accept(
+    accept_format: Optional[str] = None, previews: Optional[Sequence[str]] = None
+) -> str:
+    if accept_format:
+        accept_format = (
+            accept_format if accept_format.startswith(".") else f".{accept_format}"
+        )
+    accept_format = accept_format or "+json"
+
+    if previews:
+        accepts = [
+            f"application/vnd.github.{preview}-preview{accept_format}"
+            for preview in previews
+        ]
+    else:
+        accepts = [f"application/vnd.github{accept_format}"]
+    return ",".join(accepts)
+
+
+def build_user_agent(user_agent: Optional[str] = None) -> str:
+    return user_agent or "GitHubKit/Python"
+
+
+def build_timeout(
+    timeout: Optional[Union[float, httpx.Timeout]] = None,
+) -> httpx.Timeout:
+    return timeout if isinstance(timeout, httpx.Timeout) else httpx.Timeout(timeout)
+
+
+def build_cache_strategy(
+    cache_strategy: Optional[BaseCacheStrategy],
+) -> BaseCacheStrategy:
+    return cache_strategy or DEFAULT_CACHE_STRATEGY
+
+
+def build_throttler(
+    throttler: Optional[BaseThrottler],
+) -> BaseThrottler:
+    # https://docs.github.com/en/rest/using-the-rest-api/rate-limits-for-the-rest-api#about-secondary-rate-limits
+    # > No more than 100 concurrent requests are allowed
+    return throttler or LocalThrottler(100)
+
+
+def build_auto_retry(
+    auto_retry: Union[bool, RetryDecisionFunc] = True,
+) -> Optional[RetryDecisionFunc]:
+    if auto_retry is True:
+        return RETRY_DEFAULT
+    elif auto_retry:
+        return auto_retry
+    else:
+        return None
+
+
+def get_config(
+    *,
+    base_url: Optional[Union[str, httpx.URL]] = None,
+    accept_format: Optional[str] = None,
+    previews: Optional[Sequence[str]] = None,
+    user_agent: Optional[str] = None,
+    follow_redirects: bool = True,
+    timeout: Optional[Union[float, httpx.Timeout]] = None,
+    ssl_verify: Union[bool, "ssl.SSLContext"] = True,
+    trust_env: bool = True,
+    proxy: Optional[ProxyTypes] = None,
+    transport: Optional[httpx.BaseTransport] = None,
+    async_transport: Optional[httpx.AsyncBaseTransport] = None,
+    event_hooks: Optional[EventHookTypes] = None,
+    async_event_hooks: Optional[EventHookTypes] = None,
+    cache_strategy: Optional[BaseCacheStrategy] = None,
+    http_cache: bool = True,
+    throttler: Optional[BaseThrottler] = None,
+    auto_retry: Union[bool, RetryDecisionFunc] = True,
+    rest_api_validate_body: bool = True,
+) -> Config:
+    """Build the configs from the given options."""
+    return Config(
+        build_base_url(base_url),
+        build_accept(accept_format, previews),
+        build_user_agent(user_agent),
+        follow_redirects,
+        build_timeout(timeout),
+        ssl_verify,
+        trust_env,
+        proxy,
+        transport,
+        async_transport,
+        event_hooks,
+        async_event_hooks,
+        build_cache_strategy(cache_strategy),
+        http_cache,
+        build_throttler(throttler),
+        build_auto_retry(auto_retry),
+        rest_api_validate_body,
+    )