githubkit 0.11.0a0__tar.gz → 0.11.0a1__tar.gz

{githubkit-0.11.0a0 → githubkit-0.11.0a1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: GitHubKit
-Version: 0.11.0a0
+Version: 0.11.0a1
 Summary: GitHub SDK for Python
 Home-page: https://github.com/yanyongyu/githubkit
 License: MIT
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Provides-Extra: all
 Provides-Extra: auth
 Provides-Extra: auth-app
@@ -21,8 +22,9 @@ 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,<4.0.0) ; extra == "auth-oauth-device" or extra == "auth" or extra == "all"
+Requires-Dist: hishel (>=0.0.21,<0.0.22)
 Requires-Dist: httpx (>=0.23.0,<1.0.0)
-Requires-Dist: pydantic (>=2.0.0,<3.0.0)
+Requires-Dist: pydantic (>=2.0.0,<3.0.0,!=2.5.0,!=2.5.1)
 Requires-Dist: typing-extensions (>=4.3.0,<5.0.0)
 Project-URL: Documentation, https://github.com/yanyongyu/githubkit
 Project-URL: Repository, https://github.com/yanyongyu/githubkit
@@ -178,6 +180,28 @@ from githubkit import GitHub, ActionAuthStrategy
 github = GitHub(ActionAuthStrategy())
 ```
 
+### Config
+
+githubkit is highly configurable, you can change the default config by passing config options to `GitHub`:
+
+```python
+from githubkit import GitHub
+
+github = GitHub(
+    base_url="https://api.github.com/",
+    accept_format="full+json",
+    previews=["starfox"],
+    user_agent="GitHubKit/Python",
+    follow_redirects=True,
+    timeout=None,
+    http_cache=True
+)
+```
+
+The `accept_format` and `previews` are used to set the default `Accept` header, you can find more details in [GitHub API docs](https://docs.github.com/en/rest/overview/media-types).
+
+The `http_cache` option enables the http caching feature powered by [Hishel](https://hishel.com/) for HTTPX. GitHub API limits the number of requests that you can make within a specific amount of time. This feature is useful to reduce the number of requests to GitHub API and avoid hitting the rate limit.
+
 ### Calling Rest API
 
 > APIs are fully typed. Typing in the following examples is just for reference only.
@@ -186,7 +210,7 @@ Simple sync call:
 
 ```python
 from githubkit import Response
-from githubkit.rest import FullRepository
+from githubkit.versions.latest.models import FullRepository
 
 resp: Response[FullRepository] = github.rest.repos.get(owner="owner", repo="repo")
 repo: FullRepository = resp.parsed_data
@@ -196,7 +220,7 @@ Simple async call:
 
 ```python
 from githubkit import Response
-from githubkit.rest import FullRepository
+from githubkit.versions.latest.models import FullRepository
 
 resp: Response[FullRepository] = await github.rest.repos.async_get(owner="owner", repo="repo")
 repo: FullRepository = resp.parsed_data
@@ -206,7 +230,7 @@ Call API with context (reusing client):
 
 ```python
 from githubkit import Response
-from githubkit.rest import FullRepository
+from githubkit.versions.latest.models import FullRepository
 
 with GitHub("<your_token_here>") as github:
     resp: Response[FullRepository] = github.rest.repos.get(owner="owner", repo="repo")
@@ -215,13 +239,60 @@ with GitHub("<your_token_here>") as github:
 
 ```python
 from githubkit import Response
-from githubkit.rest import FullRepository
+from githubkit.versions.latest.models import FullRepository
 
 async with GitHub("<your_token_here>") as github:
     resp: Response[FullRepository] = await github.rest.repos.async_get(owner="owner", repo="repo")
     repo: FullRepository = resp.parsed_data
 ```
 
+### Data Validation
+
+As shown above, the response data is parsed and validated by accessing the `response.parsed_data` property. This ensures that the data type returned by the API is as expected and your code is safe to use it (with static type checking). But sometimes you may want to get the raw data returned by the API, such as when the schema is not correct. You can use the `response.text` property or `response.json()` method to get the raw data:
+
+```python
+from typing import Any, Dict
+from githubkit import Response
+
+resp: Response[FullRepository] = github.rest.repos.get(owner="owner", repo="repo")
+repo: Dict[str, Any] = resp.json()
+```
+
+### Rest API Versioning
+
+> APIs are fully typed. Different versions of APIs are typed separately.
+
+githubkit supports all versions of GitHub API, you can switch between versions as follows:
+
+```python
+github.rest("2022-11-28").repos.get(owner="owner", repo="repo")
+```
+
+The models of versions can be imported from `githubkit.versions.<version>.models`, for example:
+
+```python
+from githubkit.versions.v2022_11_28.models import FullRepository
+```
+
+Specially, the `latest` version is always linked to the latest version of GitHub API:
+
+```python
+from githubkit.versions.latest.models import FullRepository
+```
+
+> [!NOTE]
+> For backward compatibility, the `githubkit.rest` module is linked to the models of `latest` version by default.
+>
+> ```python
+> from githubkit.rest import FullRepository
+> ```
+
+You can also get the latest version name of GitHub API and all versions mapping of GitHub API:
+
+```python
+from githubkit.versions import LATEST_VERSION, VERSIONS
+```
+
 ### Pagination
 
 Pagination type checking is also supported:
@@ -229,7 +300,7 @@ Pagination type checking is also supported:
 > Typing is tested with Pylance (Pyright).
 
 ```python
-from githubkit.rest import Issue
+from githubkit.versions.latest.models import Issue
 
 for issue in github.paginate(
     github.rest.issues.list_for_repo, owner="owner", repo="repo", state="open"
@@ -239,7 +310,7 @@ for issue in github.paginate(
 ```
 
 ```python
-from githubkit.rest import Issue
+from githubkit.versions.latest.models import Issue
 
 async for issue in github.paginate(
     github.rest.issues.async_list_for_repo, owner="owner", repo="repo", state="open"
@@ -271,11 +342,13 @@ data: Dict[str, Any] = github.graphql(query, variables={"foo": "bar"})
 Simple async call:
 
 ```python
-data: Dict[str, Any] = github.async_graphql(query, variables={"foo": "bar"})
+data: Dict[str, Any] = await github.async_graphql(query, variables={"foo": "bar"})
 ```
 
 ### Webhook Verification
 
+> `githubkit.webhooks` module contains some shortcut functions to help you verify and parse webhook payload.
+
 Simple webhook payload verification:
 
 ```python
@@ -294,29 +367,41 @@ signature: str = sign(secret, payload, method="sha256")
 
 ### Webhook Parsing
 
+> `githubkit.webhooks` module contains some shortcut functions to help you verify and parse webhook payload.
+
 Parse the payload with event name:
 
 ```python
-from githubkit.webhooks import parse, WebhookEvent
+from githubkit.webhooks import parse
 
-event: WebhookEvent = parse(request.headers["X-GitHub-Event"], request.body)
+event = parse(request.headers["X-GitHub-Event"], request.body)
 ```
 
-Parse the payload without event name (may cost longer time):
+(NOT RECOMMENDED) Parse the payload without event name (may cost longer time and more memory):
 
 ```python
-from githubkit.webhooks import parse_without_name, WebhookEvent
+from githubkit.webhooks import parse_without_name
 
-event: WebhookEvent = parse_without_name(request.body)
+event = parse_without_name(request.body)
 ```
 
 Parse dict like payload:
 
 ```python
-from githubkit.webhooks import parse_obj, parse_obj_without_name, WebhookEvent
+from githubkit.webhooks import parse_obj, parse_obj_without_name
+
+event = parse_obj(request.headers["X-GitHub-Event"], request.json())
+event = parse_obj_without_name(request.json())  # NOT RECOMMENDED
+```
+
+The `parse` and `parse_obj` function supports type overload, if you provide static value for the `event_name` parameter, the return type will be inferred automatically.
+
+Webhook also supports versioning, you can switch between versions as follows:
+
+```python
+from githubkit import GitHub
 
-event: WebhookEvent = parse_obj(request.headers["X-GitHub-Event"], request.json())
-event: WebhookEvent = parse_obj_without_name(request.json())
+event = GitHub.webhooks("2022-11-28").parse(request.headers["X-GitHub-Event"], request.body)
 ```
 
 ### Switch between AuthStrategy
@@ -351,7 +436,24 @@ Open in Codespaces (Dev Container):
 
 Generate latest models and apis:
 
+> [!WARNING]
+> This may use a lot of memory (**16G+** RAM) and take a long time.
+
 ```bash
 python -m codegen && isort . && black .
 ```
 
+Run tests:
+
+```bash
+pytest -n auto tests
+```
+
+## 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.11.0a0 → githubkit-0.11.0a1}/README.md

@@ -148,6 +148,28 @@ from githubkit import GitHub, ActionAuthStrategy
 github = GitHub(ActionAuthStrategy())
 ```
 
+### Config
+
+githubkit is highly configurable, you can change the default config by passing config options to `GitHub`:
+
+```python
+from githubkit import GitHub
+
+github = GitHub(
+    base_url="https://api.github.com/",
+    accept_format="full+json",
+    previews=["starfox"],
+    user_agent="GitHubKit/Python",
+    follow_redirects=True,
+    timeout=None,
+    http_cache=True
+)
+```
+
+The `accept_format` and `previews` are used to set the default `Accept` header, you can find more details in [GitHub API docs](https://docs.github.com/en/rest/overview/media-types).
+
+The `http_cache` option enables the http caching feature powered by [Hishel](https://hishel.com/) for HTTPX. GitHub API limits the number of requests that you can make within a specific amount of time. This feature is useful to reduce the number of requests to GitHub API and avoid hitting the rate limit.
+
 ### Calling Rest API
 
 > APIs are fully typed. Typing in the following examples is just for reference only.
@@ -156,7 +178,7 @@ Simple sync call:
 
 ```python
 from githubkit import Response
-from githubkit.rest import FullRepository
+from githubkit.versions.latest.models import FullRepository
 
 resp: Response[FullRepository] = github.rest.repos.get(owner="owner", repo="repo")
 repo: FullRepository = resp.parsed_data
@@ -166,7 +188,7 @@ Simple async call:
 
 ```python
 from githubkit import Response
-from githubkit.rest import FullRepository
+from githubkit.versions.latest.models import FullRepository
 
 resp: Response[FullRepository] = await github.rest.repos.async_get(owner="owner", repo="repo")
 repo: FullRepository = resp.parsed_data
@@ -176,7 +198,7 @@ Call API with context (reusing client):
 
 ```python
 from githubkit import Response
-from githubkit.rest import FullRepository
+from githubkit.versions.latest.models import FullRepository
 
 with GitHub("<your_token_here>") as github:
     resp: Response[FullRepository] = github.rest.repos.get(owner="owner", repo="repo")
@@ -185,13 +207,60 @@ with GitHub("<your_token_here>") as github:
 
 ```python
 from githubkit import Response
-from githubkit.rest import FullRepository
+from githubkit.versions.latest.models import FullRepository
 
 async with GitHub("<your_token_here>") as github:
     resp: Response[FullRepository] = await github.rest.repos.async_get(owner="owner", repo="repo")
     repo: FullRepository = resp.parsed_data
 ```
 
+### Data Validation
+
+As shown above, the response data is parsed and validated by accessing the `response.parsed_data` property. This ensures that the data type returned by the API is as expected and your code is safe to use it (with static type checking). But sometimes you may want to get the raw data returned by the API, such as when the schema is not correct. You can use the `response.text` property or `response.json()` method to get the raw data:
+
+```python
+from typing import Any, Dict
+from githubkit import Response
+
+resp: Response[FullRepository] = github.rest.repos.get(owner="owner", repo="repo")
+repo: Dict[str, Any] = resp.json()
+```
+
+### Rest API Versioning
+
+> APIs are fully typed. Different versions of APIs are typed separately.
+
+githubkit supports all versions of GitHub API, you can switch between versions as follows:
+
+```python
+github.rest("2022-11-28").repos.get(owner="owner", repo="repo")
+```
+
+The models of versions can be imported from `githubkit.versions.<version>.models`, for example:
+
+```python
+from githubkit.versions.v2022_11_28.models import FullRepository
+```
+
+Specially, the `latest` version is always linked to the latest version of GitHub API:
+
+```python
+from githubkit.versions.latest.models import FullRepository
+```
+
+> [!NOTE]
+> For backward compatibility, the `githubkit.rest` module is linked to the models of `latest` version by default.
+>
+> ```python
+> from githubkit.rest import FullRepository
+> ```
+
+You can also get the latest version name of GitHub API and all versions mapping of GitHub API:
+
+```python
+from githubkit.versions import LATEST_VERSION, VERSIONS
+```
+
 ### Pagination
 
 Pagination type checking is also supported:
@@ -199,7 +268,7 @@ Pagination type checking is also supported:
 > Typing is tested with Pylance (Pyright).
 
 ```python
-from githubkit.rest import Issue
+from githubkit.versions.latest.models import Issue
 
 for issue in github.paginate(
     github.rest.issues.list_for_repo, owner="owner", repo="repo", state="open"
@@ -209,7 +278,7 @@ for issue in github.paginate(
 ```
 
 ```python
-from githubkit.rest import Issue
+from githubkit.versions.latest.models import Issue
 
 async for issue in github.paginate(
     github.rest.issues.async_list_for_repo, owner="owner", repo="repo", state="open"
@@ -241,11 +310,13 @@ data: Dict[str, Any] = github.graphql(query, variables={"foo": "bar"})
 Simple async call:
 
 ```python
-data: Dict[str, Any] = github.async_graphql(query, variables={"foo": "bar"})
+data: Dict[str, Any] = await github.async_graphql(query, variables={"foo": "bar"})
 ```
 
 ### Webhook Verification
 
+> `githubkit.webhooks` module contains some shortcut functions to help you verify and parse webhook payload.
+
 Simple webhook payload verification:
 
 ```python
@@ -264,29 +335,41 @@ signature: str = sign(secret, payload, method="sha256")
 
 ### Webhook Parsing
 
+> `githubkit.webhooks` module contains some shortcut functions to help you verify and parse webhook payload.
+
 Parse the payload with event name:
 
 ```python
-from githubkit.webhooks import parse, WebhookEvent
+from githubkit.webhooks import parse
 
-event: WebhookEvent = parse(request.headers["X-GitHub-Event"], request.body)
+event = parse(request.headers["X-GitHub-Event"], request.body)
 ```
 
-Parse the payload without event name (may cost longer time):
+(NOT RECOMMENDED) Parse the payload without event name (may cost longer time and more memory):
 
 ```python
-from githubkit.webhooks import parse_without_name, WebhookEvent
+from githubkit.webhooks import parse_without_name
 
-event: WebhookEvent = parse_without_name(request.body)
+event = parse_without_name(request.body)
 ```
 
 Parse dict like payload:
 
 ```python
-from githubkit.webhooks import parse_obj, parse_obj_without_name, WebhookEvent
+from githubkit.webhooks import parse_obj, parse_obj_without_name
+
+event = parse_obj(request.headers["X-GitHub-Event"], request.json())
+event = parse_obj_without_name(request.json())  # NOT RECOMMENDED
+```
+
+The `parse` and `parse_obj` function supports type overload, if you provide static value for the `event_name` parameter, the return type will be inferred automatically.
+
+Webhook also supports versioning, you can switch between versions as follows:
+
+```python
+from githubkit import GitHub
 
-event: WebhookEvent = parse_obj(request.headers["X-GitHub-Event"], request.json())
-event: WebhookEvent = parse_obj_without_name(request.json())
+event = GitHub.webhooks("2022-11-28").parse(request.headers["X-GitHub-Event"], request.body)
 ```
 
 ### Switch between AuthStrategy
@@ -321,6 +404,23 @@ Open in Codespaces (Dev Container):
 
 Generate latest models and apis:
 
+> [!WARNING]
+> This may use a lot of memory (**16G+** RAM) and take a long time.
+
 ```bash
 python -m codegen && isort . && black .
 ```
+
+Run tests:
+
+```bash
+pytest -n auto tests
+```
+
+## 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.11.0a0 → githubkit-0.11.0a1}/githubkit/__init__.py

@@ -1,8 +1,13 @@
+from . import lazy_module
+
+lazy_module.apply()
+
 from .config import Config as Config
 from .github import GitHub as GitHub
 from .core import GitHubCore as GitHubCore
 from .response import Response as Response
 from .paginator import Paginator as Paginator
+from .compat import GitHubModel as GitHubModel
 from .auth import AppAuthStrategy as AppAuthStrategy
 from .auth import BaseAuthStrategy as BaseAuthStrategy
 from .auth import TokenAuthStrategy as TokenAuthStrategy

{githubkit-0.11.0a0 → githubkit-0.11.0a1}/githubkit/auth/_url.py

@@ -26,21 +26,38 @@ APP_ROUTES = {
 }
 
 BYPASS_REGEX = re.compile(r"/login/(oauth/access_token|device/code)$")
-APP_AUTH_REGEX = re.compile(rf"(?:{'|'.join(APP_ROUTES)})[^/]*$", re.I)
+"""Regex to match routes that should bypass auth.
+
+See: https://github.com/octokit/auth-oauth-user.js/blob/b8b1141b21f285027e36a4a1670163e4db51d30f/src/hook.ts#L44
+"""
+APP_AUTH_REGEX = re.compile(rf"^(?:{'|'.join(APP_ROUTES)})$", re.I)
+"""Regex to match app authentication routes.
+
+See: https://github.com/octokit/auth-app.js/blob/c0068e06081a5d930799285a7c79c9c948b676b6/src/requires-app-auth.ts#L45
+"""
 BASIC_AUTH_REGEX = re.compile(r"/applications/[^/]+/(token|grant)s?")
+"""Regex to match basic authentication routes.
+
+See: https://github.com/octokit/auth-oauth-user.js/blob/b8b1141b21f285027e36a4a1670163e4db51d30f/src/requires-basic-auth.ts#L17
+"""
 OAUTH_BASE_REGEX = re.compile(r"^https://(api\.)?github\.com/?$")
 
 
 def require_bypass(url: httpx.URL) -> bool:
-    # bypass oauth web flow and device flow
+    """Check if the request should bypass auth."""
     return bool(BYPASS_REGEX.search(url.path))
 
 
 def require_app_auth(url: httpx.URL) -> bool:
+    """Check if the request should use app authentication.
+
+    Note: the input url must remove the base url first.
+    """
     return bool(APP_AUTH_REGEX.search(url.path))
 
 
 def require_basic_auth(url: httpx.URL) -> bool:
+    """Check if the request should use basic authentication."""
     return bool(BASIC_AUTH_REGEX.search(url.path))
 
 

{githubkit-0.11.0a0 → githubkit-0.11.0a1}/githubkit/auth/app.py

@@ -7,12 +7,7 @@ import httpx
 from githubkit.exception import AuthCredentialError
 from githubkit.cache import DEFAULT_CACHE, BaseCache
 from githubkit.utils import UNSET, Unset, exclude_unset
-from githubkit.rest import (
-    BasicError,
-    ValidationError,
-    InstallationToken,
-    AppInstallationsInstallationIdAccessTokensPostBody,
-)
+from githubkit.compat import model_dump, type_validate_python
 
 from .base import BaseAuthStrategy
 from .oauth import OAuthAppAuthStrategy
@@ -25,7 +20,8 @@ except ImportError:
 
 if TYPE_CHECKING:
     from githubkit import Response, GitHubCore
-    from githubkit.rest.types import AppPermissionsType
+    from githubkit.versions.latest.models import InstallationToken
+    from githubkit.versions.latest.types import AppPermissionsType
 
 
 @dataclass
@@ -49,6 +45,16 @@ class AppAuth(httpx.Auth):
         "{installation_id}:{permissions}:{repositories}:{repository_ids}"
     )
 
+    def _get_api_route(self, url: httpx.URL) -> httpx.URL:
+        """Get the api route (path only) for the given url."""
+        base_url_path = self.github.config.base_url.path
+        if (path := url.path).startswith(base_url_path):
+            path = path[len(base_url_path) :]
+            # add leading slash
+            if not path.startswith("/"):
+                path = "/" + path
+        return httpx.URL(path=path)
+
     def _create_jwt(self) -> str:
         """Create a JWT authenticating as GitHub APP.
 
@@ -80,6 +86,10 @@ class AppAuth(httpx.Auth):
         return token
 
     def _build_installation_auth_request(self) -> httpx.Request:
+        from githubkit.versions.latest.models import (
+            AppInstallationsInstallationIdAccessTokensPostBody,
+        )
+
         if self.installation_id is UNSET:
             raise AuthCredentialError(
                 "GitHub APP installation_id must be provided "
@@ -91,13 +101,16 @@ class AppAuth(httpx.Auth):
             raw_path=base_url.raw_path
             + f"app/installations/{self.installation_id}/access_tokens".encode("ascii")
         )
-        body = AppInstallationsInstallationIdAccessTokensPostBody.model_validate(
-            {
-                "repositories": self.repositories,
-                "repository_ids": self.repository_ids,
-                "permissions": self.permissions,
-            }
-        ).model_dump(by_alias=True)
+        body = model_dump(
+            type_validate_python(
+                AppInstallationsInstallationIdAccessTokensPostBody,
+                {
+                    "repositories": self.repositories,
+                    "repository_ids": self.repository_ids,
+                    "permissions": self.permissions,
+                },
+            )
+        )
         return httpx.Request(
             "POST",
             url,
@@ -111,6 +124,12 @@ class AppAuth(httpx.Auth):
     def _parse_installation_auth_response(
         self, response: httpx.Response
     ) -> "Response[InstallationToken]":
+        from githubkit.versions.latest.models import (
+            BasicError,
+            ValidationError,
+            InstallationToken,
+        )
+
         return self.github._check(
             response,
             response_model=InstallationToken,
@@ -150,7 +169,7 @@ class AppAuth(httpx.Auth):
         if require_bypass(request.url):
             yield request
             return
-        if require_app_auth(request.url):
+        if require_app_auth(self._get_api_route(request.url)):
             request.headers["Authorization"] = f"Bearer {self.get_jwt()}"
             yield request
             return
@@ -186,7 +205,7 @@ class AppAuth(httpx.Auth):
         if require_bypass(request.url):
             yield request
             return
-        if require_app_auth(request.url):
+        if require_app_auth(self._get_api_route(request.url)):
             request.headers["Authorization"] = f"Bearer {await self.aget_jwt()}"
             yield request
             return