diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dea0090..c4eaf6f 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -24,7 +24,7 @@ repos: files: ^(.*\.toml)$ - repo: https://github.com/astral-sh/ruff-pre-commit - rev: v0.13.3 + rev: v0.14.6 hooks: - id: ruff args: [ --exit-non-zero-on-fix, --fix ] @@ -35,4 +35,4 @@ repos: hooks: - id: docstrfmt require_serial: true - rev: v1.11.1 + rev: v2.0.0 diff --git a/AUTHORS.rst b/AUTHORS.rst index e197318..74bdd17 100644 --- a/AUTHORS.rst +++ b/AUTHORS.rst @@ -1,10 +1,12 @@ -Maintainers -=========== +############# + Maintainers +############# - Bryce Boe `@bboe `_ -Contributors -============ +############## + Contributors +############## - nmtake `@nmtake `_ - elnuno `@elnuno `_ diff --git a/CHANGES.rst b/CHANGES.rst index 5a9f5af..46e0b53 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,27 +1,32 @@ -Change Log -========== +############ + Change Log +############ prawcore follows `semantic versioning `_. -Unreleased ----------- +************ + Unreleased +************ -3.0.2 (2025/02/10) ------------------- +******************** + 3.0.2 (2025/02/10) +******************** **Changed** - Improved type hinting. -3.0.1 (2025/01/26) ------------------- +******************** + 3.0.1 (2025/01/26) +******************** **Fixed** - Increase half-second delay introduced in ``3.0.0`` to a full second delay. -3.0.0 (2025/01/25) ------------------- +******************** + 3.0.0 (2025/01/25) +******************** **Changed** @@ -39,8 +44,9 @@ Unreleased - Remove :class:`RateLimiter` attribute ``reset_timestamp``. -2.4.0 (2023/10/01) ------------------- +******************** + 2.4.0 (2023/10/01) +******************** **Changed** @@ -48,8 +54,9 @@ Unreleased - Updated rate limit algorithm to better handle Reddit's new rate limits. - Drop support for Python 3.7, which was end-of-life on 2023-06-27. -2.3.0 (2021-07-26) ------------------- +******************** + 2.3.0 (2021-07-26) +******************** **Added** @@ -64,8 +71,9 @@ Unreleased - :class:`DeviceIDAuthorizer` can be now used with :class:`TrustedAuthenticator`. -2.2.0 (2021-06-10) ------------------- +******************** + 2.2.0 (2021-06-10) +******************** **Added** @@ -76,8 +84,9 @@ Unreleased - The expected HTTP response status code for a request made with the proper credentials to api/v1/revoke_token has been changed from 204 to 200. -2.1.0 (2021-06-07) ------------------- +******************** + 2.1.0 (2021-06-07) +******************** **Added** @@ -86,8 +95,9 @@ Unreleased OTPs (One-Time Passcodes) when :meth:`.ScriptAuthorizer.refresh` is called. - Add a :class:`TooManyRequests` exception. -2.0.0 (2021-02-23) ------------------- +******************** + 2.0.0 (2021-02-23) +******************** **Added** @@ -103,15 +113,17 @@ Unreleased - The ``refresh_token`` argument to :class:`Authorizer` must now be passed by keyword, and cannot be passed as a positional argument. -1.5.0 (2020-08-04) ------------------- +******************** + 1.5.0 (2020-08-04) +******************** **Changed** - Drop support for Python 3.5, which was end-of-life on 2020-09-13. -1.4.0 (2020-05-28) ------------------- +******************** + 1.4.0 (2020-05-28) +******************** **Added** @@ -123,16 +135,18 @@ Unreleased - (Non-breaking) Requests to ``www.reddit.com`` use the ``Connection: close`` header to avoid warnings when tokens are refreshed after their one-hour expiration. -1.3.0 (2020-04-23) ------------------- +******************** + 1.3.0 (2020-04-23) +******************** **Added** - All other requestor methods, most notably :meth:`.Session.request`, now contain a ``timeout`` parameter. -1.2.0 (2020-04-23) ------------------- +******************** + 1.2.0 (2020-04-23) +******************** **Added** @@ -145,15 +159,17 @@ Unreleased requests remaining. - Drop python 2.7 support. -1.0.1 (2019-02-05) ------------------- +******************** + 1.0.1 (2019-02-05) +******************** **Fixed** - :class:`RateLimiter` will not sleep longer than ``next_request_timestamp``. -1.0.0 (2018-04-26) ------------------- +******************** + 1.0.0 (2018-04-26) +******************** I am releasing 1.0.0 as prawcore is quite stable and it's unlikely that any breaking changes will need to be introduced in the near future. @@ -162,15 +178,17 @@ changes will need to be introduced in the near future. - Log debug messages for all sleep times. -0.15.0 (2018-03-31) -------------------- +********************* + 0.15.0 (2018-03-31) +********************* **Added** - ``SpecialError`` is raised on HTTP 415. -0.14.0 (2018-02-10) -------------------- +********************* + 0.14.0 (2018-02-10) +********************* **Added** @@ -180,37 +198,42 @@ changes will need to be introduced in the near future. - Drop support for Python 3.3 as it is no longer supported by requests. -0.13.0 (2017-12-16) -------------------- +********************* + 0.13.0 (2017-12-16) +********************* **Added** - ``UnavailableForLegalReasons`` exception raised when HTTP Response 451 is encountered. -0.12.0 (2017-08-30) -------------------- +********************* + 0.12.0 (2017-08-30) +********************* **Added** - ``BadJSON`` exception for the rare cases that a response that should contain valid JSON has unparsable JSON. -0.11.0 (2017-05-27) -------------------- +********************* + 0.11.0 (2017-05-27) +********************* **Added** - ``Conflict`` exception is raised when response status 409 is returned. -0.10.1 (2017-04-10) -------------------- +********************* + 0.10.1 (2017-04-10) +********************* **Fixed** - ``InvalidToken`` is again raised on 401 when a non-refreshable application is in use. -0.10.0 (2017-04-10) -------------------- +********************* + 0.10.0 (2017-04-10) +********************* **Added** @@ -231,16 +254,18 @@ changes will need to be introduced in the near future. request,rather than just before the request flow. This new approach accounts for failure retries, and rate limiter delay. -0.9.0 (2017-03-11) ------------------- +******************** + 0.9.0 (2017-03-11) +******************** **Added** - Add ``session`` parameter to Requestor to ease support of custom sessions (e.g. caching or mock ones). -0.8.0 (2017-01-29) ------------------- +******************** + 0.8.0 (2017-01-29) +******************** **Added** @@ -251,38 +276,43 @@ changes will need to be introduced in the near future. - Avoid modifying passed in ``data`` and ``params`` to ``Session.request``. -0.7.0 (2017-01-16) ------------------- +******************** + 0.7.0 (2017-01-16) +******************** **Added** ``ChunkedEncodingError`` is automatically retried like the server errors. -0.6.0 (2016-12-24) ------------------- +******************** + 0.6.0 (2016-12-24) +******************** **Added** - Handle 500 responses. - Handle Cloudflare 520 responses. -0.5.0 (2016-12-13) ------------------- +******************** + 0.5.0 (2016-12-13) +******************** **Added** All network requests now have a 16 second timeout by default. The environment variable ``prawcore_timeout`` can be used to adjust the value. -0.4.0 (2016-12-09) ------------------- +******************** + 0.4.0 (2016-12-09) +******************** **Changed** - Prevent '(None)' from appearing in OAuthException message. -0.3.0 (2016-11-20) ------------------- +******************** + 0.3.0 (2016-11-20) +******************** **Added** @@ -295,15 +325,17 @@ All network requests now have a 16 second timeout by default. The environment va - :class:`Authorizer` class can be used with :class:`UntrustedAuthenticator`. -0.2.1 (2016-08-07) ------------------- +******************** + 0.2.1 (2016-08-07) +******************** **Fixed** - ``session`` works with :class:`DeviceIDAuthorizer` and :class:`ImplicitAuthorizer`. -0.2.0 (2016-08-07) ------------------- +******************** + 0.2.0 (2016-08-07) +******************** **Added** @@ -314,15 +346,17 @@ All network requests now have a 16 second timeout by default. The environment va - Split ``Authenticator`` into :class:`TrustedAuthenticator` and :class:`UntrustedAuthenticator`. -0.1.1 (2016-08-06) ------------------- +******************** + 0.1.1 (2016-08-06) +******************** **Added** - Add :class:`DeviceIDAuthorizer` that permits installed application access to the API. -0.1.0 (2016-08-05) ------------------- +******************** + 0.1.0 (2016-08-05) +******************** **Added** @@ -333,15 +367,17 @@ All network requests now have a 16 second timeout by default. The environment va - What was previously ``RequestException`` is now ``ResponseException``. -0.0.15 (2016-08-02) -------------------- +********************* + 0.0.15 (2016-08-02) +********************* **Added** - Handle Cloudflare 522 responses. -0.0.14 (2016-07-25) -------------------- +********************* + 0.0.14 (2016-07-25) +********************* **Added** @@ -349,8 +385,9 @@ All network requests now have a 16 second timeout by default. The environment va raised after three failed attempts to make the request. - Add ``json`` parameter to ``Session.request``. -0.0.13 (2016-07-24) -------------------- +********************* + 0.0.13 (2016-07-24) +********************* **Added** @@ -362,23 +399,26 @@ All network requests now have a 16 second timeout by default. The environment va - Consider access tokens expired slightly earlier than allowed for to prevent InvalidToken exceptions from occuring. -0.0.12 (2016-07-17) -------------------- +********************* + 0.0.12 (2016-07-17) +********************* **Added** - Handle 0-byte HTTP 200 responses. -0.0.11 (2016-07-16) -------------------- +********************* + 0.0.11 (2016-07-16) +********************* **Added** - Add a ``NotFound`` exception. - Support 404 "Not Found" HTTP responses. -0.0.10 (2016-07-10) -------------------- +********************* + 0.0.10 (2016-07-10) +********************* **Added** @@ -386,67 +426,76 @@ All network requests now have a 16 second timeout by default. The environment va - Support 400 "Bad Request" HTTP responses. - Support 204 "No Content" HTTP responses. -0.0.9 (2016-07-09) ------------------- +******************** + 0.0.9 (2016-07-09) +******************** **Added** - Support 201 "Created" HTTP responses used in some v1 endpoints. -0.0.8 (2016-03-21) ------------------- +******************** + 0.0.8 (2016-03-21) +******************** **Added** - Sort ``Session.request`` ``data`` values. Sorting the values permits betamax body matcher to work as expected. -0.0.7 (2016-03-18) ------------------- +******************** + 0.0.7 (2016-03-18) +******************** **Added** - Added ``data`` parameter to ``Session.request``. -0.0.6 (2016-03-14) ------------------- +******************** + 0.0.6 (2016-03-14) +******************** **Fixed** - prawcore objects can be pickled. -0.0.5 (2016-03-12) ------------------- +******************** + 0.0.5 (2016-03-12) +******************** **Added** - 302 redirects result in a ``Redirect`` exception. -0.0.4 (2016-03-12) ------------------- +******************** + 0.0.4 (2016-03-12) +******************** **Added** - Add a generic ``Forbidden`` exception for 403 responses without the ``www-authenticate`` header. -0.0.3 (2016-02-29) ------------------- +******************** + 0.0.3 (2016-02-29) +******************** **Added** - Added ``params`` parameter to ``Session.request``. - Log requests to the ``prawcore`` logger in debug mode. -0.0.2 (2016-02-21) ------------------- +******************** + 0.0.2 (2016-02-21) +******************** **Fixed** - README.rst for display purposes on pypi. -0.0.1 (2016-02-17) [YANKED] ---------------------------- +***************************** + 0.0.1 (2016-02-17) [YANKED] +***************************** **Added** diff --git a/README.rst b/README.rst index e15742b..2a73fe1 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,8 @@ .. _main_page: -prawcore -======== +########## + prawcore +########## .. image:: https://img.shields.io/pypi/v/prawcore.svg :alt: Latest prawcore Version @@ -33,8 +34,9 @@ prawcore prawcore is a low-level communication layer used by PRAW 4+. -Installation ------------- +************** + Installation +************** Install prawcore using ``pip`` via: @@ -42,8 +44,9 @@ Install prawcore using ``pip`` via: pip install prawcore -Execution Example ------------------ +******************* + Execution Example +******************* The following example demonstrates how to use prawcore to obtain the list of trophies for a given user using the script-app type. This example assumes you have the @@ -77,8 +80,9 @@ Save the above as ``trophies.py`` and then execute via: Additional examples can be found at: https://github.com/praw-dev/prawcore/tree/main/examples -Depending on prawcore ---------------------- +*********************** + Depending on prawcore +*********************** prawcore follows `semantic versioning `_ with the exception that deprecations will not be preceded by a minor release. In essence, expect only major @@ -89,14 +93,14 @@ prawcore your package requires, but to also limit the major version. Below are two examples of how you may want to specify your prawcore dependency: setup.py -~~~~~~~~ +======== .. code-block:: python setup(..., install_requires=["prawcore >=0.1, <1"], ...) requirements.txt -~~~~~~~~~~~~~~~~ +================ .. code-block:: text