GitHubKit 0.12.9__py3-none-any.whl → 0.12.10__py3-none-any.whl

githubkit/paginator.py

@@ -1,6 +1,6 @@
 from collections.abc import Awaitable
 from typing import Any, Callable, Generic, Optional, TypeVar, Union, cast, overload
-from typing_extensions import ParamSpec, Self
+from typing_extensions import ParamSpec, Self, deprecated
 
 from .response import Response
 from .utils import is_async
@@ -16,6 +16,10 @@ R = Union[
 ]
 
 
+@deprecated(
+    "Legacy pagination based on page and per_page is deprecated. "
+    "Use github.rest.paginate instead."
+)
 class Paginator(Generic[RT]):
     """Paginate through the responses of the rest api request."""
 

githubkit/rest/__init__.py

@@ -219,6 +219,10 @@ if TYPE_CHECKING:
     from githubkit.versions.v2022_11_28.models import (
         BranchWithProtectionPropLinks as BranchWithProtectionPropLinks,
     )
+    from githubkit.versions.v2022_11_28.models import CampaignSummary as CampaignSummary
+    from githubkit.versions.v2022_11_28.models import (
+        CampaignSummaryPropAlertStats as CampaignSummaryPropAlertStats,
+    )
     from githubkit.versions.v2022_11_28.models import CheckAnnotation as CheckAnnotation
     from githubkit.versions.v2022_11_28.models import (
         CheckAutomatedSecurityFixes as CheckAutomatedSecurityFixes,
@@ -555,15 +559,9 @@ if TYPE_CHECKING:
     from githubkit.versions.v2022_11_28.models import (
         CopilotSeatDetails as CopilotSeatDetails,
     )
-    from githubkit.versions.v2022_11_28.models import (
-        CopilotUsageMetrics as CopilotUsageMetrics,
-    )
     from githubkit.versions.v2022_11_28.models import (
         CopilotUsageMetricsDay as CopilotUsageMetricsDay,
     )
-    from githubkit.versions.v2022_11_28.models import (
-        CopilotUsageMetricsPropBreakdownItems as CopilotUsageMetricsPropBreakdownItems,
-    )
     from githubkit.versions.v2022_11_28.models import (
         CustomDeploymentRuleApp as CustomDeploymentRuleApp,
     )
@@ -1287,6 +1285,15 @@ if TYPE_CHECKING:
     from githubkit.versions.v2022_11_28.models import (
         OrgsOrgAttestationsSubjectDigestGetResponse200PropAttestationsItemsPropBundlePropVerificationMaterial as OrgsOrgAttestationsSubjectDigestGetResponse200PropAttestationsItemsPropBundlePropVerificationMaterial,
     )
+    from githubkit.versions.v2022_11_28.models import (
+        OrgsOrgCampaignsCampaignNumberPatchBody as OrgsOrgCampaignsCampaignNumberPatchBody,
+    )
+    from githubkit.versions.v2022_11_28.models import (
+        OrgsOrgCampaignsPostBody as OrgsOrgCampaignsPostBody,
+    )
+    from githubkit.versions.v2022_11_28.models import (
+        OrgsOrgCampaignsPostBodyPropCodeScanningAlertsItems as OrgsOrgCampaignsPostBodyPropCodeScanningAlertsItems,
+    )
     from githubkit.versions.v2022_11_28.models import (
         OrgsOrgCodeSecurityConfigurationsConfigurationIdAttachPostBody as OrgsOrgCodeSecurityConfigurationsConfigurationIdAttachPostBody,
     )
@@ -2798,6 +2805,9 @@ if TYPE_CHECKING:
     from githubkit.versions.v2022_11_28.models import (
         ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropAdvancedSecurity as ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropAdvancedSecurity,
     )
+    from githubkit.versions.v2022_11_28.models import (
+        ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropCodeSecurity as ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropCodeSecurity,
+    )
     from githubkit.versions.v2022_11_28.models import (
         ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropSecretScanning as ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropSecretScanning,
     )
@@ -3077,6 +3087,9 @@ if TYPE_CHECKING:
     from githubkit.versions.v2022_11_28.models import (
         SecurityAndAnalysisPropAdvancedSecurity as SecurityAndAnalysisPropAdvancedSecurity,
     )
+    from githubkit.versions.v2022_11_28.models import (
+        SecurityAndAnalysisPropCodeSecurity as SecurityAndAnalysisPropCodeSecurity,
+    )
     from githubkit.versions.v2022_11_28.models import (
         SecurityAndAnalysisPropDependabotSecurityUpdates as SecurityAndAnalysisPropDependabotSecurityUpdates,
     )
@@ -3784,6 +3797,9 @@ if TYPE_CHECKING:
     from githubkit.versions.v2022_11_28.models import (
         WebhookCustomPropertyDeletedPropDefinition as WebhookCustomPropertyDeletedPropDefinition,
     )
+    from githubkit.versions.v2022_11_28.models import (
+        WebhookCustomPropertyPromotedToEnterprise as WebhookCustomPropertyPromotedToEnterprise,
+    )
     from githubkit.versions.v2022_11_28.models import (
         WebhookCustomPropertyUpdated as WebhookCustomPropertyUpdated,
     )
@@ -5089,6 +5105,9 @@ if TYPE_CHECKING:
     from githubkit.versions.v2022_11_28.models import (
         WebhookIssuesTransferredPropChangesPropNewRepositoryPropPermissions as WebhookIssuesTransferredPropChangesPropNewRepositoryPropPermissions,
     )
+    from githubkit.versions.v2022_11_28.models import (
+        WebhookIssuesTyped as WebhookIssuesTyped,
+    )
     from githubkit.versions.v2022_11_28.models import (
         WebhookIssuesUnassigned as WebhookIssuesUnassigned,
     )
@@ -5140,6 +5159,9 @@ if TYPE_CHECKING:
     from githubkit.versions.v2022_11_28.models import (
         WebhookIssuesUnpinned as WebhookIssuesUnpinned,
     )
+    from githubkit.versions.v2022_11_28.models import (
+        WebhookIssuesUntyped as WebhookIssuesUntyped,
+    )
     from githubkit.versions.v2022_11_28.models import (
         WebhookLabelCreated as WebhookLabelCreated,
     )
@@ -9818,6 +9840,7 @@ else:
             "ApiOverviewPropDomainsPropArtifactAttestations",
             "SecurityAndAnalysis",
             "SecurityAndAnalysisPropAdvancedSecurity",
+            "SecurityAndAnalysisPropCodeSecurity",
             "SecurityAndAnalysisPropDependabotSecurityUpdates",
             "SecurityAndAnalysisPropSecretScanning",
             "SecurityAndAnalysisPropSecretScanningPushProtection",
@@ -9854,6 +9877,11 @@ else:
             "AuthenticationToken",
             "AuthenticationTokenPropPermissions",
             "ActionsPublicKey",
+            "TeamSimple",
+            "Team",
+            "TeamPropPermissions",
+            "CampaignSummary",
+            "CampaignSummaryPropAlertStats",
             "CodeScanningAlertRuleSummary",
             "CodeScanningAnalysisTool",
             "CodeScanningAlertInstance",
@@ -9867,9 +9895,6 @@ else:
             "CodespacesPublicKey",
             "CopilotOrganizationDetails",
             "CopilotOrganizationSeatBreakdown",
-            "TeamSimple",
-            "Team",
-            "TeamPropPermissions",
             "CopilotSeatDetails",
             "EnterpriseTeam",
             "OrgsOrgCopilotBillingSeatsGetResponse200",
@@ -9887,8 +9912,6 @@ else:
             "CopilotIdeCodeCompletionsPropEditorsItems",
             "CopilotIdeCodeCompletionsPropEditorsItemsPropModelsItems",
             "CopilotIdeCodeCompletionsPropEditorsItemsPropModelsItemsPropLanguagesItems",
-            "CopilotUsageMetrics",
-            "CopilotUsageMetricsPropBreakdownItems",
             "DependabotPublicKey",
             "Package",
             "OrganizationInvitation",
@@ -10761,6 +10784,7 @@ else:
             "WebhookCustomPropertyCreated",
             "WebhookCustomPropertyDeleted",
             "WebhookCustomPropertyDeletedPropDefinition",
+            "WebhookCustomPropertyPromotedToEnterprise",
             "WebhookCustomPropertyUpdated",
             "WebhookCustomPropertyValuesUpdated",
             "WebhookDelete",
@@ -11198,6 +11222,7 @@ else:
             "WebhookIssuesTransferredPropChangesPropNewIssuePropReactions",
             "WebhookIssuesTransferredPropChangesPropNewIssuePropSubIssuesSummary",
             "WebhookIssuesTransferredPropChangesPropNewIssuePropUser",
+            "WebhookIssuesTyped",
             "WebhookIssuesUnassigned",
             "WebhookIssuesUnlabeled",
             "WebhookIssuesUnlocked",
@@ -11215,6 +11240,7 @@ else:
             "WebhookIssuesUnlockedPropIssuePropSubIssuesSummary",
             "WebhookIssuesUnlockedPropIssuePropUser",
             "WebhookIssuesUnpinned",
+            "WebhookIssuesUntyped",
             "WebhookLabelCreated",
             "WebhookLabelDeleted",
             "WebhookLabelEdited",
@@ -12683,6 +12709,9 @@ else:
             "OrgsOrgAttestationsSubjectDigestGetResponse200PropAttestationsItemsPropBundle",
             "OrgsOrgAttestationsSubjectDigestGetResponse200PropAttestationsItemsPropBundlePropVerificationMaterial",
             "OrgsOrgAttestationsSubjectDigestGetResponse200PropAttestationsItemsPropBundlePropDsseEnvelope",
+            "OrgsOrgCampaignsPostBody",
+            "OrgsOrgCampaignsPostBodyPropCodeScanningAlertsItems",
+            "OrgsOrgCampaignsCampaignNumberPatchBody",
             "OrgsOrgCodeSecurityConfigurationsPostBody",
             "OrgsOrgCodeSecurityConfigurationsPostBodyPropDependencyGraphAutosubmitActionOptions",
             "OrgsOrgCodeSecurityConfigurationsPostBodyPropSecretScanningDelegatedBypassOptions",
@@ -12788,6 +12817,7 @@ else:
             "ReposOwnerRepoPatchBody",
             "ReposOwnerRepoPatchBodyPropSecurityAndAnalysis",
             "ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropAdvancedSecurity",
+            "ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropCodeSecurity",
             "ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropSecretScanning",
             "ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropSecretScanningPushProtection",
             "ReposOwnerRepoPatchBodyPropSecurityAndAnalysisPropSecretScanningAiDetection",

githubkit/rest/paginator.py

@@ -0,0 +1,214 @@
+from collections.abc import Awaitable
+import re
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    Optional,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+from typing_extensions import ParamSpec, Self
+
+import httpx
+
+from githubkit.response import Response
+from githubkit.utils import is_async
+
+if TYPE_CHECKING:
+    from githubkit.versions import RestVersionSwitcher
+
+CP = ParamSpec("CP")
+CT = TypeVar("CT")
+RT = TypeVar("RT")
+RTS = TypeVar("RTS")
+
+R = Union[
+    Callable[CP, Response[RT]],
+    Callable[CP, Awaitable[Response[RT]]],
+]
+
+# https://github.com/octokit/plugin-paginate-rest.js/blob/1f44b5469b31ddec9621000e6e1aee63c71ea8bf/src/iterator.ts#L40
+NEXT_LINK_PATTERN = r'<([^<>]+)>;\s*rel="next"'
+
+
+# https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api
+# https://github.com/octokit/plugin-paginate-rest.js/blob/1f44b5469b31ddec9621000e6e1aee63c71ea8bf/src/iterator.ts
+class Paginator(Generic[RT]):
+    """Paginate through the responses of the rest api request."""
+
+    @overload
+    def __init__(
+        self: "Paginator[RTS]",
+        rest: "RestVersionSwitcher",
+        request: R[CP, list[RTS]],
+        map_func: None = None,
+        *args: CP.args,
+        **kwargs: CP.kwargs,
+    ): ...
+
+    @overload
+    def __init__(
+        self: "Paginator[RTS]",
+        rest: "RestVersionSwitcher",
+        request: R[CP, CT],
+        map_func: Callable[[Response[CT]], list[RTS]],
+        *args: CP.args,
+        **kwargs: CP.kwargs,
+    ): ...
+
+    def __init__(
+        self,
+        rest: "RestVersionSwitcher",
+        request: R[CP, CT],
+        map_func: Optional[Callable[[Response[CT]], list[RT]]] = None,
+        *args: CP.args,
+        **kwargs: CP.kwargs,
+    ):
+        self.rest = rest
+
+        self.request = request
+        self.args = args
+        self.kwargs = kwargs
+
+        self.map_func = map_func
+
+        self._initialized: bool = False
+        self._request_method: Optional[str] = None
+        self._response_model: Optional[Any] = None
+        self._next_link: Optional[httpx.URL] = None
+
+        self._index: int = 0
+        self._cached_data: list[RT] = []
+
+    @property
+    def finalized(self) -> bool:
+        """Whether the paginator is finalized or not."""
+        return self._initialized and self._next_link is None
+
+    def reset(self) -> None:
+        """Reset the paginator to the initial state."""
+
+        self._initialized = False
+        self._next_link = None
+        self._index = 0
+        self._cached_data = []
+
+    def __next__(self) -> RT:
+        while self._index >= len(self._cached_data):
+            self._get_next_page()
+            if self.finalized:
+                raise StopIteration
+
+        current = self._cached_data[self._index]
+        self._index += 1
+        return current
+
+    def __iter__(self: Self) -> Self:
+        if is_async(self.request):
+            raise TypeError(f"Request method {self.request} is not an sync function")
+        return self
+
+    async def __anext__(self) -> RT:
+        while self._index >= len(self._cached_data):
+            await self._aget_next_page()
+            if self.finalized:
+                raise StopAsyncIteration
+
+        current = self._cached_data[self._index]
+        self._index += 1
+        return current
+
+    def __aiter__(self: Self) -> Self:
+        if not is_async(self.request):
+            raise TypeError(f"Request method {self.request} is not an async function")
+        return self
+
+    def _find_next_link(self, response: Response[Any]) -> Optional[httpx.URL]:
+        """Find the next link in the response headers."""
+        if links := response.headers.get("link"):
+            if match := re.search(NEXT_LINK_PATTERN, links):
+                return httpx.URL(match.group(1))
+        return None
+
+    def _apply_map_func(self, response: Response[Any]) -> list[RT]:
+        if self.map_func is not None:
+            result = self.map_func(response)
+            if not isinstance(result, list):
+                raise TypeError(f"Map function must return a list, got {type(result)}")
+        else:
+            result = cast(Response[list[RT]], response).parsed_data
+            if not isinstance(result, list):
+                raise TypeError(f"Response is not a list, got {type(result)}")
+        return result
+
+    def _fill_cache_data(self, data: list[RT]) -> None:
+        """Fill the cache with the data."""
+        self._cached_data = data
+        self._index = 0
+
+    def _get_next_page(self) -> None:
+        if not self._initialized:
+            # First request
+            response = cast(
+                Response[Any],
+                self.request(*self.args, **self.kwargs),
+            )
+            self._initialized = True
+            self._request_method = response.raw_request.method
+        else:
+            # Next request
+            if self._next_link is None:
+                raise RuntimeError("Paginator is finalized, no more pages to fetch.")
+            if self._request_method is None:
+                raise RuntimeError("Request method is not set, this should not happen.")
+            if self._response_model is None:
+                raise RuntimeError("Response model is not set, this should not happen.")
+
+            # we request the next page with the same method and response model
+            response = cast(
+                Response[Any],
+                self.rest._github.request(
+                    self._request_method,
+                    self._next_link,
+                    headers=self.kwargs.get("headers"),  # type: ignore
+                    response_model=self._response_model,  # type: ignore
+                ),
+            )
+
+        self._next_link = self._find_next_link(response)
+        self._fill_cache_data(self._apply_map_func(response))
+
+    async def _aget_next_page(self) -> None:
+        if not self._initialized:
+            # First request
+            response = cast(
+                Response[Any],
+                await self.request(*self.args, **self.kwargs),  # type: ignore
+            )
+            self._initialized = True
+            self._request_method = response.raw_request.method
+        else:
+            # Next request
+            if self._next_link is None:
+                raise RuntimeError("Paginator is finalized, no more pages to fetch.")
+            if self._request_method is None:
+                raise RuntimeError("Request method is not set, this should not happen.")
+            if self._response_model is None:
+                raise RuntimeError("Response model is not set, this should not happen.")
+
+            response = cast(
+                Response[Any],
+                await self.rest._github.request(
+                    self._request_method,
+                    self._next_link,
+                    headers=self.kwargs.get("headers"),  # type: ignore
+                    response_model=self._response_model,  # type: ignore
+                ),
+            )
+
+        self._next_link = self._find_next_link(response)
+        self._fill_cache_data(self._apply_map_func(response))

githubkit/utils.py

@@ -1,4 +1,5 @@
 from enum import Enum
+from functools import partial
 import inspect
 from typing import Any, Generic, Literal, Optional, TypeVar, final
 
@@ -61,7 +62,18 @@ def exclude_unset(data: Any) -> Any:
     return data
 
 
+def _unwrap_partial(func: T) -> T:
+    while isinstance(func, partial):
+        func = func.func
+    return func
+
+
 def is_async(obj: Any) -> bool:
+    """Check if an object is a async callable (coroutine function)."""
+
+    # unwrap partials first
+    obj = _unwrap_partial(obj)
+
     if inspect.isroutine(obj):
         return inspect.iscoroutinefunction(obj)
     if inspect.isclass(obj):