GitHubKit 0.12.7__tar.gz → 0.12.8__tar.gz

githubkit-0.12.8/PKG-INFO

@@ -0,0 +1,147 @@
+Metadata-Version: 2.3
+Name: GitHubKit
+Version: 0.12.8
+Summary: GitHub SDK for Python
+License: MIT
+Keywords: github,octokit
+Author: yanyongyu
+Author-email: yyy@yyydl.top
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: all
+Provides-Extra: auth
+Provides-Extra: auth-app
+Provides-Extra: auth-oauth-device
+Provides-Extra: jwt
+Requires-Dist: PyJWT[crypto] (>=2.4.0,<3.0.0) ; extra == "jwt" or extra == "auth-app" or extra == "auth" or extra == "all"
+Requires-Dist: anyio (>=3.6.1,<5.0.0)
+Requires-Dist: hishel (>=0.0.21,<=0.2.0)
+Requires-Dist: httpx (>=0.23.0,<1.0.0)
+Requires-Dist: pydantic (>=1.9.1,<3.0.0,!=2.5.0,!=2.5.1)
+Requires-Dist: typing-extensions (>=4.11.0,<5.0.0)
+Project-URL: Documentation, https://github.com/yanyongyu/githubkit
+Project-URL: Homepage, https://github.com/yanyongyu/githubkit
+Project-URL: Repository, https://github.com/yanyongyu/githubkit
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable MD041 -->
+<div align="center">
+
+[![githubkit](https://socialify.git.ci/yanyongyu/githubkit/image?description=1&descriptionEditable=%E2%9C%A8%20GitHub%20SDK%20for%20Python%20%E2%9C%A8&font=Bitter&language=1&pattern=Circuit%20Board&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.8+-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
+
+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.12.8/githubkit/cache/base.py

@@ -0,0 +1,60 @@
+import abc
+from datetime import timedelta
+from typing import Optional
+
+from hishel import AsyncBaseStorage, BaseStorage, Controller
+
+
+class BaseCache(abc.ABC):
+    @abc.abstractmethod
+    def get(self, key: str) -> Optional[str]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def set(self, key: str, value: str, ex: timedelta) -> None:
+        raise NotImplementedError
+
+
+class AsyncBaseCache(abc.ABC):
+    @abc.abstractmethod
+    async def aget(self, key: str) -> Optional[str]:
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    async def aset(self, key: str, value: str, ex: timedelta) -> None:
+        raise NotImplementedError
+
+
+class BaseCacheStrategy(abc.ABC):
+    @abc.abstractmethod
+    def get_cache_storage(self) -> BaseCache:
+        """Get the cache storage instance used in sync context
+
+        raise CacheUnsupportedError if the strategy does not support sync usage
+        """
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_async_cache_storage(self) -> AsyncBaseCache:
+        """Get the cache storage instance used in async context
+
+        raise CacheUnsupportedError if the strategy does not support async usage
+        """
+        raise NotImplementedError
+
+    def get_hishel_controller(self) -> Optional[Controller]:
+        """Get the hishel controller instance
+
+        Return `None` to use the default controller
+        """
+        return None
+
+    @abc.abstractmethod
+    def get_hishel_storage(self) -> BaseStorage:
+        """Get the hishel storage instance used in sync context"""
+        raise NotImplementedError
+
+    @abc.abstractmethod
+    def get_async_hishel_storage(self) -> AsyncBaseStorage:
+        """Get the hishel storage instance used in async context"""
+        raise NotImplementedError

githubkit-0.12.8/githubkit/cache/redis.py

@@ -0,0 +1,127 @@
+from datetime import timedelta
+from functools import partial
+from typing import TYPE_CHECKING, Any, NoReturn, Optional
+from typing_extensions import override
+
+from hishel import AsyncBaseStorage, AsyncRedisStorage, Controller, RedisStorage
+
+from githubkit.exception import CacheUnsupportedError
+from githubkit.utils import hishel_key_generator_with_prefix
+
+from .base import AsyncBaseCache, BaseCache, BaseCacheStrategy
+
+if TYPE_CHECKING:
+    from redis import Redis
+    from redis.asyncio import Redis as AsyncRedis
+
+
+def _ensure_str_or_none(value: Any) -> Optional[str]:
+    if isinstance(value, str):
+        return value
+    elif isinstance(value, bytes):
+        return value.decode("utf-8")
+    elif value is None:
+        return None
+    else:
+        raise RuntimeError(f"Unexpected redis value {value!r} with type {type(value)}")
+
+
+class RedisCache(BaseCache):
+    def __init__(self, client: "Redis", prefix: Optional[str] = None) -> None:
+        self.client = client
+        self.prefix = prefix
+
+    def _get_key(self, key: str) -> str:
+        if self.prefix is not None:
+            return f"{self.prefix}{key}"
+        return key
+
+    @override
+    def get(self, key: str) -> Optional[str]:
+        data = self.client.get(self._get_key(key))
+        return _ensure_str_or_none(data)
+
+    @override
+    def set(self, key: str, value: str, ex: timedelta) -> None:
+        self.client.set(self._get_key(key), value, ex)
+
+
+class AsyncRedisCache(AsyncBaseCache):
+    def __init__(self, client: "AsyncRedis", prefix: Optional[str] = None) -> None:
+        self.client = client
+        self.prefix = prefix
+
+    def _get_key(self, key: str) -> str:
+        if self.prefix is not None:
+            return f"{self.prefix}{key}"
+        return key
+
+    @override
+    async def aget(self, key: str) -> Optional[str]:
+        data = await self.client.get(self._get_key(key))
+        return _ensure_str_or_none(data)
+
+    @override
+    async def aset(self, key: str, value: str, ex: timedelta) -> None:
+        await self.client.set(self._get_key(key), value, ex)
+
+
+class RedisCacheStrategy(BaseCacheStrategy):
+    def __init__(self, client: "Redis", prefix: Optional[str] = None) -> None:
+        self.client = client
+        self.prefix = prefix
+
+    @override
+    def get_cache_storage(self) -> RedisCache:
+        return RedisCache(self.client, self.prefix)
+
+    @override
+    def get_async_cache_storage(self) -> NoReturn:
+        raise CacheUnsupportedError(
+            "Sync redis cache strategy does not support async usage"
+        )
+
+    @override
+    def get_hishel_controller(self) -> Optional[Controller]:
+        if self.prefix is not None:
+            return Controller(
+                key_generator=partial(
+                    hishel_key_generator_with_prefix, prefix=self.prefix
+                )
+            )
+
+    @override
+    def get_hishel_storage(self) -> RedisStorage:
+        return RedisStorage(client=self.client)
+
+    @override
+    def get_async_hishel_storage(self) -> NoReturn:
+        raise CacheUnsupportedError(
+            "Sync redis cache strategy does not support async usage"
+        )
+
+
+class AsyncRedisCacheStrategy(BaseCacheStrategy):
+    def __init__(self, client: "AsyncRedis", prefix: Optional[str] = None) -> None:
+        self.client = client
+        self.prefix = prefix
+
+    @override
+    def get_cache_storage(self) -> NoReturn:
+        raise CacheUnsupportedError(
+            "Async redis cache strategy does not support sync usage"
+        )
+
+    @override
+    def get_async_cache_storage(self) -> AsyncRedisCache:
+        return AsyncRedisCache(self.client, self.prefix)
+
+    @override
+    def get_hishel_storage(self) -> NoReturn:
+        raise CacheUnsupportedError(
+            "Async redis cache strategy does not support sync usage"
+        )
+
+    @override
+    def get_async_hishel_storage(self) -> AsyncBaseStorage:
+        return AsyncRedisStorage(client=self.client)