GitHub | PyPI | Issues | Changelog
ghreq
is a simple wrapper around requests with various customizations aimed at working with the GitHub REST API. Notable features include:
- When making a request, you only need to specify the part of the URL after the API base URL. You can even construct objects for making requests with a URL baked in.
- All request methods return decoded JSON by default.
- 4xx and 5xx responses are automatically raised as errors without needing to call
raise_for_status()
. - Errors raised for 4xx and 5xx responses include the body of the response in the error message.
- Support for iterating over paginated results
- The
Accept
andX-GitHub-Api-Version
headers are automatically set to their recommended values. - Follows GitHub's recommendations for dealing with rate limits, including waiting between mutating requests and waiting & retrying in response to rate-limit errors
- Automatic retrying on 5xx errors with exponential backoff
ghreq
requires Python 3.8 or higher. Just use pip for Python 3 (You have pip, right?) to install it:
python3 -m pip install ghreq
from ghreq import Client
with Client(token="your-api-token-here") as client:
user = client.get("/user")
print("I am user", user["login"])
print()
print("Here are my repositories:")
for repo in client.paginate("/user/repos"):
print(repo["full_name"])
print()
hello_world = client / "repos" / "octocat" / "Hello-World"
details = hello_world.get()
print(f"{details['full_name']} has been starred {details['stargazers_count']} times.")
print("Here is the first page of its open issues & PRs:")
for issue in (hello_world / "issues").get():
print(f"#{issue['number']}: {issue['title']}")
class Client:
def __init__(
*,
token: str | None = None,
api_url: str = DEFAULT_API_URL,
session: requests.Session | None = None,
set_headers: bool | None = None,
user_agent: str | None = None,
accept: str | None = DEFAULT_ACCEPT,
api_version: str | None = DEFAULT_API_VERSION,
mutation_delay: float = 1.0,
retry_config: RetryConfig | None = None,
)
An HTTP client class for interacting with the GitHub REST API (or sufficiently similar APIs).
Constructor arguments:
token
The GitHub access token, if any, to use to authenticate to the API.
This argument is ignored if
set_headers
isFalse
or defaulted toFalse
.api_url
The base URL to which to append paths passed to the request methods
session
A pre-configured
requests.Session
instance to use for making requests. If no session is supplied, a new session is instantiated.set_headers
Whether to set various headers for requests made via the session. If
set_headers
isNone
, it is defaulted toTrue
ifsession
isNone
and toFalse
otherwise.If
set_headers
isTrue
or defaulted toTrue
, the following request headers are set on the session:Accept
(ifaccept
is non-None
)Authorization
(set to"Bearer {token}"
iftoken
is non-None
)User-Agent
(ifuser_agent
is non-None
)X-GitHub-Api-Version
(ifapi_version
is non-None
)- any additional headers included in
headers
If
set_headers
isFalse
or defaulted toFalse
, thenClient
does not set any headers on the session, and the other header-related parameters are ignored.user_agent
A user agent string to include in the headers of requests. If not set, the
requests
library's default user agent is used.This argument is ignored if
set_headers
isFalse
or defaulted toFalse
.accept
Value to set the
Accept
header to. Can be set toNone
to not set the header at all.This argument is ignored if
set_headers
isFalse
or defaulted toFalse
.api_version
Value to set the
X-GitHub-Api-Version
header to. Can be set toNone
to not set the header at all.This argument is ignored if
set_headers
isFalse
or defaulted toFalse
.headers
Optional mapping of additional headers to set on the session after setting all other headers.
This argument is ignored if
set_headers
isFalse
or defaulted toFalse
.mutation_delay
When making a
POST
,PATCH
,PUT
, orDELETE
request, if the time since the last such request is fewer thanmutation_delay
seconds, then the client will sleep long enough to make up the difference before performing the request.retry_config
Configuration for the request retrying mechanism. If not set, a
RetryConfig
instance with all default attributes will be used; see below.
Client
instances can be used as context managers, in which case they close their internal requests.Session
instances on exit (regardless of whether the session was user-provided or not).
A Client
instance can be "divided" by a string (e.g., client / "user"
) to obtain an Endpoint
instance that makes requests to the URL formed from api_url
and the "divisor"; see below.
Client.request(
method: str,
path: str,
json: Any = None,
*,
params: ParamsType = None,
headers: HeadersType = None,
data: DataType = None,
timeout: TimeoutType = None,
allow_redirects: bool = True,
stream: bool = False,
raw: bool = False,
) -> Any
Perform an HTTP request with the given method/verb. If path
begins with http://
or https://
, it is used as-is for the URL of the request. Otherwise, path
is appended to the api_url
value supplied to the constructor, with a forward slash inserted in between if there isn't one present already. Thus, given a client
constructed with the default api_url
, the following are equivalent:
client.request("GET", "user")
client.request("GET", "/user")
client.request("GET", "https://api.github.com/user")
If the request is successful, the body is decoded as JSON and returned; if the body is empty (except possibly for whitespace), None
is returned. To make the method return the actual requests.Response
object instead, pass raw=True
(or stream=True
, which implies it).
The remaining arguments have the same meaning as in requests
.
If the request fails, it may be retried with exponentially increasing wait times between attempts; see the documentation of RetryConfig
below. If all retries are exhausted without success, the exception from the final request is raised.
If the request fails with a 4xx or 5xx response, a PrettyHTTPError
is raised.
Client.get(
path: str,
*,
params: ParamsType = None,
headers: HeadersType = None,
timeout: TimeoutType = None,
stream: bool = False,
raw: bool = False,
) -> Any
Perform a GET
request. See the documentation of request()
for more information.
Client.post(
path: str,
json: Any = None,
*,
params: ParamsType = None,
headers: HeadersType = None,
data: DataType = None,
timeout: TimeoutType = None,
stream: bool = False,
raw: bool = False,
) -> Any
Perform a POST
request. See the documentation of request()
for more information.
Client.put(
path: str,
json: Any = None,
*,
params: ParamsType = None,
headers: HeadersType = None,
data: DataType = None,
timeout: TimeoutType = None,
stream: bool = False,
raw: bool = False,
) -> Any
Perform a PUT
request. See the documentation of request()
for more information.
Client.patch(
path: str,
json: Any = None,
*,
params: ParamsType = None,
headers: HeadersType = None,
data: DataType = None,
timeout: TimeoutType = None,
stream: bool = False,
raw: bool = False,
) -> Any
Perform a PATCH
request. See the documentation of request()
for more information.
Client.delete(
path: str,
json: Any = None,
*,
params: ParamsType = None,
headers: HeadersType = None,
data: DataType = None,
timeout: TimeoutType = None,
stream: bool = False,
raw: bool = False,
) -> Any
Perform a DELETE
request. See the documentation of request()
for more information.
Client.paginate(
path: str,
*,
params: ParamsType = None,
headers: HeadersType = None,
timeout: TimeoutType = None,
raw: Literal[True, False] = False,
) -> Iterator
Perform a series of paginated GET
requests and yield the items from each page. The path
and params
arguments are only used for the initial request; further requests follow the "next" entry in the Link
header of each response.
The bodies of the responses must be either JSON lists (in which case the list elements are yielded) or JSON objects in which exactly one field is a list (in which case the elements of that list are yielded); otherwise, an error occurs.
If raw
is True
, then instead of yielding each page's items, the returned iterator will yield each page as a requests.Response
object.
Client.close() -> None
Close the client's internal requests.Session
. No more request methods may be called afterwards.
This method is called automatically on exit when using Client
as a context manager.
class Endpoint:
client: Client
url: str
A combination of a Client
instance and a URL. Endpoint
has request()
, get()
, post()
, put()
, patch()
, delete()
, and paginate()
methods that work the same way as for Client
, except that Endpoint
's methods do not take path
arguments; instead, they make requests to the stored URL. This is useful if you find yourself making requests to the same URL and/or paths under the same URL over & over.
An Endpoint
instance is constructed by applying the /
(division) operator to a Client
or Endpoint
instance on the left and a string on the right. If the string begins with http://
or https://
, it is used as-is for the URL of the resulting Endpoint
. Otherwise, the string is appended to the api_url
or url
attribute of the object on the left, with a forward slash inserted in between if there isn't one present already. Thus, given a client
constructed with the default api_url
, the following are equivalent:
client.get("repos/octocat/hello-world")
(client / "repos/octocat/hello-world").get()
(client / "repos" / "octocat" / "hello-world").get()
class RetryConfig:
def __init__(
retries: int = 10,
backoff_factor: float = 1.0,
backoff_base: float = 1.25,
backoff_jitter: float = 0.0
backoff_max: float = 120.0,
total_wait: float | None = 300.0,
retry_statuses: Container[int] = range(500, 600),
)
A container for storing configuration for ghreq
's retrying mechanism. A request is retried if (a) a response.RequestException
is raised that is not a ValueError
(e.g., a connection or timeout error), (b) the server responds with a 403 status code and either the Retry-After
header is present or the body contains the string "rate limit"
, or (c) the server responds with a status code listed in retry_statuses
.
When a request is retried, the client sleeps for increasing amounts of time between repeated requests until either a non-retriable response is obtained, retries
retry attempts have been performed, or the total amount of time elapsed since the start of the first request exceeds total_wait
, if set.
The first retry happens after sleeping for backoff_factor * 0.1
seconds, and subsequent retries happen after sleeping for backoff_factor * backoff_base ** (retry_number - 1) + random.random() * backoff_jitter
seconds, up to a maximum of backoff_max
per retry. If a Retry-After
or x-ratelimit-reset
header indicates a larger duration to sleep for, that value is used instead. If the duration indicated by such a header would result in the next retry attempt being after total_wait
is exceeded, retrying stops early.
class PrettyHTTPError(requests.HTTPError)
A subclass of requests.HTTPError
raised automatically by the request methods if a response with a 4xx or 5xx status code is received. Unlike its parent class, stringifying a PrettyHTTPError
will produce a string that contains the body of the response; if the body was JSON, that JSON will be pretty-printed.
DEFAULT_ACCEPT = "application/vnd.github+json"
The default value of the accept
argument to the Client
constructor
DEFAULT_API_URL = "https://api.github.com"
The default value of the api_url
argument to the Client
constructor
DEFAULT_API_VERSION = "2022-11-28"
The default value of the api_version
argument to the Client
constructor
make_user_agent(name: str, version: str | None = None, url: str | None = None) -> str
Create a user agent string with the given client name, optional version, and optional URL. The string will also include the version of the requests
library used and the implemention & version of Python.
get_github_api_url() -> str
If the GITHUB_API_URL
environment variable is set to a nonempty string, that string is returned; otherwise, DEFAULT_API_URL
is returned.