| Name | ghreq JSON |
| Version |
0.5.0
JSON |
| download |
| home_page | |
| Summary | Minimal and opinionated GitHub API client |
| upload_time | 2023-12-17 16:08:03 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
github
github api
github rest api
rest api client
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: https://www.repostatus.org/badges/latest/active.svg
:target: https://www.repostatus.org/#active
:alt: Project Status: Active — The project has reached a stable, usable
state and is being actively developed.
.. image:: https://github.com/jwodder/ghreq/actions/workflows/test.yml/badge.svg
:target: https://github.com/jwodder/ghreq/actions/workflows/test.yml
:alt: CI Status
.. image:: https://codecov.io/gh/jwodder/ghreq/branch/master/graph/badge.svg
:target: https://codecov.io/gh/jwodder/ghreq
.. image:: https://img.shields.io/pypi/pyversions/ghreq.svg
:target: https://pypi.org/project/ghreq/
.. image:: https://img.shields.io/github/license/jwodder/ghreq.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT License
`GitHub <https://github.com/jwodder/ghreq>`_
| `PyPI <https://pypi.org/project/ghreq/>`_
| `Issues <https://github.com/jwodder/ghreq/issues>`_
| `Changelog <https://github.com/jwodder/ghreq/blob/master/CHANGELOG.md>`_
``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`` and ``X-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
.. _requests: https://requests.readthedocs.io
__ https://docs.github.com/en/rest/guides/best-practices-for-using-the-rest-api
?apiVersion=2022-11-28#dealing-with-rate-limits
Installation
============
``ghreq`` requires Python 3.8 or higher. Just use `pip <https://pip.pypa.io>`_
for Python 3 (You have pip, right?) to install it::
python3 -m pip install ghreq
Example
=======
.. code:: python
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']}")
API
===
``Client`` Class
----------------
.. code:: python
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`` is ``False`` or defaulted to
``False``.
``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`` is ``None``, it is defaulted to ``True`` if ``session`` is
``None`` and to ``False`` otherwise.
If ``set_headers`` is ``True`` or defaulted to ``True``, the following
request headers are set on the session:
- ``Accept`` (if ``accept`` is non-``None``)
- ``Authorization`` (set to ``"Bearer {token}"`` if ``token`` is
non-``None``)
- ``User-Agent`` (if ``user_agent`` is non-``None``)
- ``X-GitHub-Api-Version`` (if ``api_version`` is non-``None``)
- any additional headers included in ``headers``
If ``set_headers`` is ``False`` or defaulted to ``False``, then ``Client``
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`` is ``False`` or defaulted to
``False``.
``accept``
Value to set the ``Accept`` header to. Can be set to ``None`` to not set
the header at all.
This argument is ignored if ``set_headers`` is ``False`` or defaulted to
``False``.
``api_version``
Value to set the ``X-GitHub-Api-Version`` header to. Can be set to
``None`` to not set the header at all.
This argument is ignored if ``set_headers`` is ``False`` or defaulted to
``False``.
``headers``
Optional mapping of additional headers to set on the session after setting
all other headers.
This argument is ignored if ``set_headers`` is ``False`` or defaulted to
``False``.
``mutation_delay``
When making a ``POST``, ``PATCH``, ``PUT``, or ``DELETE`` request, if the
time since the last such request is fewer than ``mutation_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.
.. code:: python
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:
.. code:: python
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.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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.
.. code:: python
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.
``Endpoint`` Class
------------------
.. code:: python
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:
.. code:: python
client.get("repos/octocat/hello-world")
(client / "repos/octocat/hello-world").get()
(client / "repos" / "octocat" / "hello-world").get()
``RetryConfig`` Class
---------------------
.. code:: python
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.
``PrettyHTTPError`` Class
-------------------------
.. code:: python
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.
Constants
---------
.. code:: python
DEFAULT_ACCEPT = "application/vnd.github+json"
The default value of the ``accept`` argument to the ``Client`` constructor
.. code:: python
DEFAULT_API_URL = "https://api.github.com"
The default value of the ``api_url`` argument to the ``Client`` constructor
.. code:: python
DEFAULT_API_VERSION = "2022-11-28"
The default value of the ``api_version`` argument to the ``Client`` constructor
Utility Functions
-----------------
.. code:: python
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.
.. code:: 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.
Raw data
{
"_id": null,
"home_page": "",
"name": "ghreq",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "GitHub,GitHub API,GitHub REST API,REST API client",
"author": "",
"author_email": "John Thorvald Wodder II <ghreq@varonathe.org>",
"download_url": "https://files.pythonhosted.org/packages/6b/55/811bbc3aba7697a0b8e7a2d0e2491d7bdf3df8900e1850c58b21deaeada8/ghreq-0.5.0.tar.gz",
"platform": null,
"description": ".. image:: https://www.repostatus.org/badges/latest/active.svg\n :target: https://www.repostatus.org/#active\n :alt: Project Status: Active \u2014 The project has reached a stable, usable\n state and is being actively developed.\n\n.. image:: https://github.com/jwodder/ghreq/actions/workflows/test.yml/badge.svg\n :target: https://github.com/jwodder/ghreq/actions/workflows/test.yml\n :alt: CI Status\n\n.. image:: https://codecov.io/gh/jwodder/ghreq/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/jwodder/ghreq\n\n.. image:: https://img.shields.io/pypi/pyversions/ghreq.svg\n :target: https://pypi.org/project/ghreq/\n\n.. image:: https://img.shields.io/github/license/jwodder/ghreq.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT License\n\n`GitHub <https://github.com/jwodder/ghreq>`_\n| `PyPI <https://pypi.org/project/ghreq/>`_\n| `Issues <https://github.com/jwodder/ghreq/issues>`_\n| `Changelog <https://github.com/jwodder/ghreq/blob/master/CHANGELOG.md>`_\n\n``ghreq`` is a simple wrapper around requests_ with various customizations\naimed at working with the GitHub REST API. Notable features include:\n\n- When making a request, you only need to specify the part of the URL after the\n API base URL. You can even construct objects for making requests with a URL\n baked in.\n\n- All request methods return decoded JSON by default.\n\n- 4xx and 5xx responses are automatically raised as errors without needing to\n call ``raise_for_status()``.\n\n- Errors raised for 4xx and 5xx responses include the body of the response in\n the error message.\n\n- Support for iterating over paginated results\n\n- The ``Accept`` and ``X-GitHub-Api-Version`` headers are automatically set to\n their recommended values.\n\n- Follows `GitHub's recommendations for dealing with rate limits`__, including\n waiting between mutating requests and waiting & retrying in response to\n rate-limit errors\n\n- Automatic retrying on 5xx errors with exponential backoff\n\n.. _requests: https://requests.readthedocs.io\n\n__ https://docs.github.com/en/rest/guides/best-practices-for-using-the-rest-api\n ?apiVersion=2022-11-28#dealing-with-rate-limits\n\nInstallation\n============\n``ghreq`` requires Python 3.8 or higher. Just use `pip <https://pip.pypa.io>`_\nfor Python 3 (You have pip, right?) to install it::\n\n python3 -m pip install ghreq\n\n\nExample\n=======\n\n.. code:: python\n\n from ghreq import Client\n\n with Client(token=\"your-api-token-here\") as client:\n user = client.get(\"/user\")\n print(\"I am user\", user[\"login\"])\n print()\n\n print(\"Here are my repositories:\")\n for repo in client.paginate(\"/user/repos\"):\n print(repo[\"full_name\"])\n print()\n\n hello_world = client / \"repos\" / \"octocat\" / \"Hello-World\"\n details = hello_world.get()\n print(f\"{details['full_name']} has been starred {details['stargazers_count']} times.\")\n print(\"Here is the first page of its open issues & PRs:\")\n for issue in (hello_world / \"issues\").get():\n print(f\"#{issue['number']}: {issue['title']}\")\n\n\nAPI\n===\n\n``Client`` Class\n----------------\n\n.. code:: python\n\n class Client:\n def __init__(\n *,\n token: str | None = None,\n api_url: str = DEFAULT_API_URL,\n session: requests.Session | None = None,\n set_headers: bool | None = None,\n user_agent: str | None = None,\n accept: str | None = DEFAULT_ACCEPT,\n api_version: str | None = DEFAULT_API_VERSION,\n mutation_delay: float = 1.0,\n retry_config: RetryConfig | None = None,\n )\n\nAn HTTP client class for interacting with the GitHub REST API (or sufficiently\nsimilar APIs).\n\nConstructor arguments:\n\n``token``\n The GitHub access token, if any, to use to authenticate to the API.\n\n This argument is ignored if ``set_headers`` is ``False`` or defaulted to\n ``False``.\n\n``api_url``\n The base URL to which to append paths passed to the request methods\n\n``session``\n A pre-configured ``requests.Session`` instance to use for making requests.\n If no session is supplied, a new session is instantiated.\n\n``set_headers``\n Whether to set various headers for requests made via the session. If\n ``set_headers`` is ``None``, it is defaulted to ``True`` if ``session`` is\n ``None`` and to ``False`` otherwise.\n\n If ``set_headers`` is ``True`` or defaulted to ``True``, the following\n request headers are set on the session:\n\n - ``Accept`` (if ``accept`` is non-``None``)\n - ``Authorization`` (set to ``\"Bearer {token}\"`` if ``token`` is\n non-``None``)\n - ``User-Agent`` (if ``user_agent`` is non-``None``)\n - ``X-GitHub-Api-Version`` (if ``api_version`` is non-``None``)\n - any additional headers included in ``headers``\n\n If ``set_headers`` is ``False`` or defaulted to ``False``, then ``Client``\n does not set any headers on the session, and the other header-related\n parameters are ignored.\n\n``user_agent``\n A user agent string to include in the headers of requests. If not set, the\n ``requests`` library's default user agent is used.\n\n This argument is ignored if ``set_headers`` is ``False`` or defaulted to\n ``False``.\n\n``accept``\n Value to set the ``Accept`` header to. Can be set to ``None`` to not set\n the header at all.\n\n This argument is ignored if ``set_headers`` is ``False`` or defaulted to\n ``False``.\n\n``api_version``\n Value to set the ``X-GitHub-Api-Version`` header to. Can be set to\n ``None`` to not set the header at all.\n\n This argument is ignored if ``set_headers`` is ``False`` or defaulted to\n ``False``.\n\n``headers``\n Optional mapping of additional headers to set on the session after setting\n all other headers.\n\n This argument is ignored if ``set_headers`` is ``False`` or defaulted to\n ``False``.\n\n``mutation_delay``\n When making a ``POST``, ``PATCH``, ``PUT``, or ``DELETE`` request, if the\n time since the last such request is fewer than ``mutation_delay`` seconds,\n then the client will sleep long enough to make up the difference before\n performing the request.\n\n``retry_config``\n Configuration for the request retrying mechanism. If not set, a\n ``RetryConfig`` instance with all default attributes will be used; see\n below.\n\n``Client`` instances can be used as context managers, in which case they close\ntheir internal ``requests.Session`` instances on exit (regardless of whether\nthe session was user-provided or not).\n\nA ``Client`` instance can be \"divided\" by a string (e.g., ``client / \"user\"``)\nto obtain an ``Endpoint`` instance that makes requests to the URL formed from\n``api_url`` and the \"divisor\"; see below.\n\n.. code:: python\n\n Client.request(\n method: str,\n path: str,\n json: Any = None,\n *,\n params: ParamsType = None,\n headers: HeadersType = None,\n data: DataType = None,\n timeout: TimeoutType = None,\n allow_redirects: bool = True,\n stream: bool = False,\n raw: bool = False,\n ) -> Any\n\nPerform an HTTP request with the given method/verb. If ``path`` begins with\n``http://`` or ``https://``, it is used as-is for the URL of the request.\nOtherwise, ``path`` is appended to the ``api_url`` value supplied to the\nconstructor, with a forward slash inserted in between if there isn't one\npresent already. Thus, given a ``client`` constructed with the default\n``api_url``, the following are equivalent:\n\n.. code:: python\n\n client.request(\"GET\", \"user\")\n\n client.request(\"GET\", \"/user\")\n\n client.request(\"GET\", \"https://api.github.com/user\")\n\nIf the request is successful, the body is decoded as JSON and returned; if the\nbody is empty (except possibly for whitespace), ``None`` is returned. To make\nthe method return the actual ``requests.Response`` object instead, pass\n``raw=True`` (or ``stream=True``, which implies it).\n\nThe remaining arguments have the same meaning as in ``requests``.\n\nIf the request fails, it may be retried with exponentially increasing wait\ntimes between attempts; see the documentation of ``RetryConfig`` below. If all\nretries are exhausted without success, the exception from the final request is\nraised.\n\nIf the request fails with a 4xx or 5xx response, a ``PrettyHTTPError`` is\nraised.\n\n.. code:: python\n\n Client.get(\n path: str,\n *,\n params: ParamsType = None,\n headers: HeadersType = None,\n timeout: TimeoutType = None,\n stream: bool = False,\n raw: bool = False,\n ) -> Any\n\nPerform a ``GET`` request. See the documentation of ``request()`` for more\ninformation.\n\n.. code:: python\n\n Client.post(\n path: str,\n json: Any = None,\n *,\n params: ParamsType = None,\n headers: HeadersType = None,\n data: DataType = None,\n timeout: TimeoutType = None,\n stream: bool = False,\n raw: bool = False,\n ) -> Any\n\nPerform a ``POST`` request. See the documentation of ``request()`` for more\ninformation.\n\n.. code:: python\n\n Client.put(\n path: str,\n json: Any = None,\n *,\n params: ParamsType = None,\n headers: HeadersType = None,\n data: DataType = None,\n timeout: TimeoutType = None,\n stream: bool = False,\n raw: bool = False,\n ) -> Any\n\nPerform a ``PUT`` request. See the documentation of ``request()`` for more\ninformation.\n\n.. code:: python\n\n Client.patch(\n path: str,\n json: Any = None,\n *,\n params: ParamsType = None,\n headers: HeadersType = None,\n data: DataType = None,\n timeout: TimeoutType = None,\n stream: bool = False,\n raw: bool = False,\n ) -> Any\n\nPerform a ``PATCH`` request. See the documentation of ``request()`` for more\ninformation.\n\n.. code:: python\n\n Client.delete(\n path: str,\n json: Any = None,\n *,\n params: ParamsType = None,\n headers: HeadersType = None,\n data: DataType = None,\n timeout: TimeoutType = None,\n stream: bool = False,\n raw: bool = False,\n ) -> Any\n\nPerform a ``DELETE`` request. See the documentation of ``request()`` for more\ninformation.\n\n.. code:: python\n\n Client.paginate(\n path: str,\n *,\n params: ParamsType = None,\n headers: HeadersType = None,\n timeout: TimeoutType = None,\n raw: Literal[True, False] = False,\n ) -> Iterator\n\nPerform a series of paginated ``GET`` requests and yield the items from each\npage. The ``path`` and ``params`` arguments are only used for the initial\nrequest; further requests follow the \"next\" entry in the ``Link`` header of\neach response.\n\nThe bodies of the responses must be either JSON lists (in which case the list\nelements are yielded) or JSON objects in which exactly one field is a list (in\nwhich case the elements of that list are yielded); otherwise, an error occurs.\n\nIf ``raw`` is ``True``, then instead of yielding each page's items, the\nreturned iterator will yield each page as a ``requests.Response`` object.\n\n.. code:: python\n\n Client.close() -> None\n\nClose the client's internal ``requests.Session``. No more request methods may\nbe called afterwards.\n\nThis method is called automatically on exit when using ``Client`` as a context\nmanager.\n\n\n``Endpoint`` Class\n------------------\n\n.. code:: python\n\n class Endpoint:\n client: Client\n url: str\n\nA combination of a ``Client`` instance and a URL. ``Endpoint`` has\n``request()``, ``get()``, ``post()``, ``put()``, ``patch()``, ``delete()``, and\n``paginate()`` methods that work the same way as for ``Client``, except that\n``Endpoint``'s methods do not take ``path`` arguments; instead, they make\nrequests to the stored URL. This is useful if you find yourself making\nrequests to the same URL and/or paths under the same URL over & over.\n\nAn ``Endpoint`` instance is constructed by applying the ``/`` (division)\noperator to a ``Client`` or ``Endpoint`` instance on the left and a string on\nthe right. If the string begins with ``http://`` or ``https://``, it is used\nas-is for the URL of the resulting ``Endpoint``. Otherwise, the string is\nappended to the ``api_url`` or ``url`` attribute of the object on the left,\nwith a forward slash inserted in between if there isn't one present already.\nThus, given a ``client`` constructed with the default ``api_url``, the\nfollowing are equivalent:\n\n.. code:: python\n\n client.get(\"repos/octocat/hello-world\")\n\n (client / \"repos/octocat/hello-world\").get()\n\n (client / \"repos\" / \"octocat\" / \"hello-world\").get()\n\n\n``RetryConfig`` Class\n---------------------\n\n.. code:: python\n\n class RetryConfig:\n def __init__(\n retries: int = 10,\n backoff_factor: float = 1.0,\n backoff_base: float = 1.25,\n backoff_jitter: float = 0.0\n backoff_max: float = 120.0,\n total_wait: float | None = 300.0,\n retry_statuses: Container[int] = range(500, 600),\n )\n\nA container for storing configuration for ``ghreq``'s retrying mechanism. A\nrequest is retried if (a) a ``response.RequestException`` is raised that is not\na ``ValueError`` (e.g., a connection or timeout error), (b) the server responds\nwith a 403 status code and either the ``Retry-After`` header is present or the\nbody contains the string ``\"rate limit\"``, or (c) the server responds with a\nstatus code listed in ``retry_statuses``.\n\nWhen a request is retried, the client sleeps for increasing amounts of time\nbetween repeated requests until either a non-retriable response is obtained,\n``retries`` retry attempts have been performed, or the total amount of time\nelapsed since the start of the first request exceeds ``total_wait``, if set.\n\nThe first retry happens after sleeping for ``backoff_factor * 0.1`` seconds,\nand subsequent retries happen after sleeping for ``backoff_factor *\nbackoff_base ** (retry_number - 1) + random.random() * backoff_jitter``\nseconds, up to a maximum of ``backoff_max`` per retry. If a ``Retry-After`` or\n``x-ratelimit-reset`` header indicates a larger duration to sleep for, that\nvalue is used instead. If the duration indicated by such a header would result\nin the next retry attempt being after ``total_wait`` is exceeded, retrying\nstops early.\n\n\n``PrettyHTTPError`` Class\n-------------------------\n\n.. code:: python\n\n class PrettyHTTPError(requests.HTTPError)\n\nA subclass of ``requests.HTTPError`` raised automatically by the request\nmethods if a response with a 4xx or 5xx status code is received. Unlike its\nparent class, stringifying a ``PrettyHTTPError`` will produce a string that\ncontains the body of the response; if the body was JSON, that JSON will be\npretty-printed.\n\n\nConstants\n---------\n\n.. code:: python\n\n DEFAULT_ACCEPT = \"application/vnd.github+json\"\n\nThe default value of the ``accept`` argument to the ``Client`` constructor\n\n.. code:: python\n\n DEFAULT_API_URL = \"https://api.github.com\"\n\nThe default value of the ``api_url`` argument to the ``Client`` constructor\n\n.. code:: python\n\n DEFAULT_API_VERSION = \"2022-11-28\"\n\nThe default value of the ``api_version`` argument to the ``Client`` constructor\n\n\nUtility Functions\n-----------------\n\n.. code:: python\n\n make_user_agent(name: str, version: str | None = None, url: str | None = None) -> str\n\nCreate a user agent string with the given client name, optional version, and\noptional URL. The string will also include the version of the ``requests``\nlibrary used and the implemention & version of Python.\n\n.. code:: python\n\n get_github_api_url() -> str\n\nIf the ``GITHUB_API_URL`` environment variable is set to a nonempty string,\nthat string is returned; otherwise, ``DEFAULT_API_URL`` is returned.\n",
"bugtrack_url": null,
"license": "",
"summary": "Minimal and opinionated GitHub API client",
"version": "0.5.0",
"project_urls": {
"Bug Tracker": "https://github.com/jwodder/ghreq/issues",
"Source Code": "https://github.com/jwodder/ghreq"
},
"split_keywords": [
"github",
"github api",
"github rest api",
"rest api client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50a966ab6b19f9e2648f872eabaf452da3dfeb3a0ead0bb724a01fcc0a289e11",
"md5": "b9018bfe198a051534a4314bc46c48c0",
"sha256": "17c76e17c678f7e5b1e63aba68cef309540f2618544c09bf8f03dc02dbab4d59"
},
"downloads": -1,
"filename": "ghreq-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b9018bfe198a051534a4314bc46c48c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 14921,
"upload_time": "2023-12-17T16:08:02",
"upload_time_iso_8601": "2023-12-17T16:08:02.252042Z",
"url": "https://files.pythonhosted.org/packages/50/a9/66ab6b19f9e2648f872eabaf452da3dfeb3a0ead0bb724a01fcc0a289e11/ghreq-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6b55811bbc3aba7697a0b8e7a2d0e2491d7bdf3df8900e1850c58b21deaeada8",
"md5": "3088c7a270efd8e86b311b0e3c494942",
"sha256": "f51cf64d0a6f425970180ffd9942bc308fc37fc85a32e2f6236db9fb822e44cd"
},
"downloads": -1,
"filename": "ghreq-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "3088c7a270efd8e86b311b0e3c494942",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 21443,
"upload_time": "2023-12-17T16:08:03",
"upload_time_iso_8601": "2023-12-17T16:08:03.458459Z",
"url": "https://files.pythonhosted.org/packages/6b/55/811bbc3aba7697a0b8e7a2d0e2491d7bdf3df8900e1850c58b21deaeada8/ghreq-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-17 16:08:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jwodder",
"github_project": "ghreq",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "ghreq"
}
