############################ Copyrights and license ############################ # # # Copyright 2023 Enrico Minack # # Copyright 2023 Jirka Borovec <6035284+Borda@users.noreply.github.com> # # Copyright 2023 Patryk Szulczyk # # Copyright 2023 Trim21 # # Copyright 2024 Austin Sasko # # Copyright 2024 Enrico Minack # # Copyright 2024 Jirka Borovec <6035284+Borda@users.noreply.github.com> # # # # This file is part of PyGithub. # # http://pygithub.readthedocs.io/ # # # # PyGithub is free software: you can redistribute it and/or modify it under # # the terms of the GNU Lesser General Public License as published by the Free # # Software Foundation, either version 3 of the License, or (at your option) # # any later version. # # # # PyGithub is distributed in the hope that it will be useful, but WITHOUT ANY # # WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS # # FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more # # details. # # # # You should have received a copy of the GNU Lesser General Public License # # along with PyGithub. If not, see . # # # ################################################################################ import json import logging from datetime import datetime, timezone from logging import Logger from types import TracebackType from typing import Any, Optional from requests import Response from requests.models import CaseInsensitiveDict from requests.utils import get_encoding_from_headers from typing_extensions import Self from urllib3 import Retry from urllib3.connectionpool import ConnectionPool from urllib3.exceptions import MaxRetryError from urllib3.response import HTTPResponse from github.GithubException import GithubException from github.Requester import Requester DEFAULT_SECONDARY_RATE_WAIT: int = 60 class GithubRetry(Retry): """ A Github-specific implementation of `urllib3.Retry` This retries 403 responses if they are retry-able. Github requests are retry-able when the response provides a `"Retry-After"` header, or the content indicates a rate limit error. By default, response codes 403, and 500 up to 599 are retried. This can be configured via the `status_forcelist` argument. By default, all methods defined in `Retry.DEFAULT_ALLOWED_METHODS` are retried, plus GET and POST. This can be configured via the `allowed_methods` argument. """ __logger: Optional[Logger] = None # used to mock datetime, mock.patch("github.GithubRetry.date") does not work as this # references the class, not the module (due to re-exporting in github/__init__.py) __datetime = datetime def __init__(self, secondary_rate_wait: float = DEFAULT_SECONDARY_RATE_WAIT, **kwargs: Any) -> None: """ :param secondary_rate_wait: seconds to wait before retrying secondary rate limit errors :param kwargs: see urllib3.Retry for more arguments """ self.secondary_rate_wait = secondary_rate_wait # 403 is too broad to be retried, but GitHub API signals rate limits via 403 # we retry 403 and look into the response header via Retry.increment # to determine if we really retry that 403 kwargs["status_forcelist"] = kwargs.get("status_forcelist", list(range(500, 600))) + [403] kwargs["allowed_methods"] = kwargs.get("allowed_methods", Retry.DEFAULT_ALLOWED_METHODS.union({"GET", "POST"})) super().__init__(**kwargs) def new(self, **kw: Any) -> Self: kw.update(dict(secondary_rate_wait=self.secondary_rate_wait)) return super().new(**kw) # type: ignore def increment( # type: ignore[override] self, method: Optional[str] = None, url: Optional[str] = None, response: Optional[HTTPResponse] = None, # type: ignore[override] error: Optional[Exception] = None, _pool: Optional[ConnectionPool] = None, _stacktrace: Optional[TracebackType] = None, ) -> Retry: if response: # we retry 403 only when there is a Retry-After header (indicating it is retry-able) # or the body message does imply a rate limit error if response.status == 403: self.__log( logging.INFO, f"Request {method} {url} failed with {response.status}: {response.reason}", ) if "Retry-After" in response.headers: # Sleeping 'Retry-After' seconds is implemented in urllib3.Retry.sleep() and called by urllib3 self.__log( logging.INFO, f'Retrying after {response.headers.get("Retry-After")} seconds', ) else: content = response.reason # to identify retry-able methods, we inspect the response body try: content = self.get_content(response, url) # type: ignore content = json.loads(content) # type: ignore message = content.get("message") # type: ignore except Exception as e: # we want to fall back to the actual github exception (probably a rate limit error) # but provide some context why we could not deal with it without another exception try: raise RuntimeError("Failed to inspect response message") from e except RuntimeError as e: raise GithubException(response.status, content, response.headers) from e # type: ignore try: if Requester.isRateLimitError(message): rate_type = "primary" if Requester.isPrimaryRateLimitError(message) else "secondary" self.__log( logging.DEBUG, f"Response body indicates retry-able {rate_type} rate limit error: {message}", ) # check early that we are retrying at all retry = super().increment(method, url, response, error, _pool, _stacktrace) # we backoff primary rate limit at least until X-RateLimit-Reset, # we backoff secondary rate limit at for secondary_rate_wait seconds backoff = 0.0 if Requester.isPrimaryRateLimitError(message): if "X-RateLimit-Reset" in response.headers: value = response.headers.get("X-RateLimit-Reset") if value and value.isdigit(): reset = self.__datetime.fromtimestamp(int(value), timezone.utc) delta = reset - self.__datetime.now(timezone.utc) resetBackoff = delta.total_seconds() if resetBackoff > 0: self.__log( logging.DEBUG, f"Reset occurs in {str(delta)} ({value} / {reset})", ) # plus 1s as it is not clear when in that second the reset occurs backoff = resetBackoff + 1 else: backoff = self.secondary_rate_wait # we backoff at least retry's next backoff retry_backoff = retry.get_backoff_time() if retry_backoff > backoff: if backoff > 0: self.__log( logging.DEBUG, f"Retry backoff of {retry_backoff}s exceeds " f"required rate limit backoff of {backoff}s".replace(".0s", "s"), ) backoff = retry_backoff def get_backoff_time() -> float: return backoff self.__log( logging.INFO, f"Setting next backoff to {backoff}s".replace(".0s", "s"), ) retry.get_backoff_time = get_backoff_time # type: ignore return retry self.__log( logging.DEBUG, "Response message does not indicate retry-able error", ) raise Requester.createException(response.status, response.headers, content) # type: ignore except (MaxRetryError, GithubException): raise except Exception as e: # we want to fall back to the actual github exception (probably a rate limit error) # but provide some context why we could not deal with it without another exception try: raise RuntimeError("Failed to determine retry backoff") from e except RuntimeError as e: raise GithubException(response.status, content, response.headers) from e # type: ignore raise GithubException( response.status, # type: ignore content, # type: ignore response.headers, # type: ignore ) # type: ignore # retry the request as usual return super().increment(method, url, response, error, _pool, _stacktrace) @staticmethod def get_content(resp: HTTPResponse, url: str) -> bytes: # type: ignore[override] # logic taken from HTTPAdapter.build_response (requests.adapters) response = Response() # Fallback to None if there's no status_code, for whatever reason. response.status_code = getattr(resp, "status", None) # type: ignore # Make headers case-insensitive. response.headers = CaseInsensitiveDict(getattr(resp, "headers", {})) # Set encoding. response.encoding = get_encoding_from_headers(response.headers) response.raw = resp response.reason = response.raw.reason # type: ignore response.url = url return response.content def __log(self, level: int, message: str, **kwargs: Any) -> None: if self.__logger is None: self.__logger = logging.getLogger(__name__) if self.__logger.isEnabledFor(level): self.__logger.log(level, message, **kwargs)