prawcore

Added

• Add Sphinx-based documentation, published at https://prawcore.readthedocs.io/.

Changed

• Improve source docstrings and type annotations so that references render cleanly in
  the new documentation.

Added

• Add an __all__ to the prawcore package to explicitly define its public API.
• Add a py.typed marker (:PEP:561) so that downstream projects can type check
  against prawcore's inline annotations.
• Add read-only :attr:.Session.authorizer, :attr:.Session.rate_limiter, and
  :attr:.Session.requestor properties, a :attr:.BaseAuthorizer.authenticator
  property, and a :attr:.BaseAuthenticator.requestor property, so that downstream code
  can reach these objects without accessing protected attributes.

Changed

• Widen the authorizer parameter of :func:.session to BaseAuthorizer to match
  :class:.Session, so that passing an :class:.ImplicitAuthorizer or
  :class:.DeviceIDAuthorizer type checks.
• Widen the data, files, json, and params parameter annotations of
  :meth:.Session.request to reflect the values it already accepts at runtime (for
  example a non-dict data body, a list json payload, and any IO file
  object), so that callers no longer need to cast these arguments.

Added

• Add support for Python 3.14.

Changed

• Drop support for Python 3.9, which was end-of-life on 2025-10-31.
• Migrate the test suite from Betamax to VCR.py, enabling urllib3 2.x in the test
  environment. Existing cassettes were converted without re-recording.

3.1.0rc1 (2026/06/07)

---

Added

• Add support for Python 3.14.

Changed

• Drop support for Python 3.9, which was end-of-life on 2025-10-31.
• Migrate the test suite from Betamax to VCR.py, enabling urllib3 2.x in the test
  environment. Existing cassettes were converted without re-recording.

3.0.2 (2025/02/10)

Changed

• Improved type hinting.

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)

Changed

• Drop support for Python 3.8, which was end-of-life on 2024-10-07.
• :class:RateLimiter attribute next_request_timestamp has been removed and
  replaced with next_request_timestamp_ns.

Fixed

• Add a half-second delay when there are no more requests in the rate limit window and
  the window has zero seconds remaining to avoid a semi-rare case where Reddit will
  return a 429 response resulting in a :class:TooManyRequests exception.

Removed

• Remove :class:RateLimiter attribute reset_timestamp.

2.4.0 (2023/10/01)

Changed

• Drop support for Python 3.6, which is end-of-life on 2021-12-23.
• Updated rate limit algorithm to better handle reddit's new rate limits.
• Drop support for Python 3.7, which is end-of-life on 2023-06-27.

Added

• 301 redirects result in a Redirect exception.

• .Requestor is now initialized with a timeout parameter.

• .ScriptAuthorizer, .ReadOnlyAuthorizer, and .DeviceIDAuthorizer have a new parameter, scopes, which determines the scope of access requests.

• Retry 408 "Request Timeout" HTTP responses.

Changed

• .DeviceIDAuthorizer can be now used with .TrustedAuthenticator.

---

Added

• Support 202 "Accepted" HTTP responses.

Fixed

• 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.

---

Added

• Add a .URITooLong exception.

• .ScriptAuthorizer has a new parameter two_factor_callback that supplies OTPs (One-Time Passcodes) when .ScriptAuthorizer.refresh is called.

• Add a .TooManyRequests exception.

---

Added

• .Authorizer optionally takes a pre_refresh_callback keyword argument. If provided, the function will called with the instance of .Authorizer prior to refreshing the access and refresh tokens.

• .Authorizer optionally takes a post_refresh_callback keyword argument. If provided, the function will called with the instance of .Authorizer after refreshing the access and refresh tokens.

Changed

• The refresh_token argument to .Authorizer must now be passed by keyword, and cannot be passed as a positional argument.

---

Changed

• Drop support for Python 3.5, which was end-of-life on 2020-09-13.

---

Added

• When calling .Session.request, we add the key-value pair "api_type": "json" to the json parameter, if it is a dict.

Changed

• (Non-breaking) Requests to www.reddit.com use the Connection: close header to avoid warnings when tokens are refreshed after their one-hour expiration.

---

Added

• All other requestor methods, most notably .Session.request, now contain a timeout parameter.

---

Added

• .Requestor.request can be given a timeout parameter to control the amount of time to wait for a request to succeed.

Changed

• Updated rate limit algorithm to more intelligently rate limit when there are extra requests remaining.

• Drop python 2.7 support.

---

Fixed

• .RateLimiter will not sleep longer than next_request_timestamp.

---

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.

Added

• Log debug messages for all sleep times.

---

Added

• SpecialError is raised on HTTP 415.

---

Added

• ReadTimeout is automatically retried like the server errors.

Changed

• Drop support for Python 3.3 as it is no longer supported by requests.

---

Added

• UnavailableForLegalReasons exception raised when HTTP Response 451 is encountered.

---

Added

• BadJSON exception for the rare cases that a response that should contain valid JSON has unparsable JSON.

---

Added

• Conflict exception is raised when response status 409 is returned.

---

Fixed

• InvalidToken is again raised on 401 when a non-refreshable application is in use.

---

Added

• ConnectionError exceptions are automatically retried. This handles Connection Reset by Peer issues that appear to occur somewhat frequently when running on Amazon EC2.

Changed

• Calling RateLimiter now requires a second positional argument, set_header_callback.

• In the event a 401 unauthorized occurs, the access token is cleared and the request is retried.

Fixed

• Check if the access token is expired immediately before every authorized request,rather than just before the request flow. This new approach accounts for failure retries, and rate limiter delay.

---

Added

• Add session parameter to Requestor to ease support of custom sessions (e.g. caching or mock ones).

---

Added

• Handle 413 Request entity too large responses.

• reset_timestamp to RateLimiter.

Fixed

• Avoid modifying passed in data and params to Session.request.

---

Added

ChunkedEncodingError is automatically retried like the server errors.

---

Added

• Handle 500 responses.

• Handle Cloudflare 520 responses.

---

Added

All network requests now have a 16 second timeout by default. The environment variable prawcore_timeout can be used to adjust the value.

---

Changed

• Prevent '(None)' from appearing in OAuthException message.

---

Added

• Add files parameter to Session.request to support image upload operations.

• Add duration and implicit parameters to UntrustedAuthenticator.authorization_url so that the method also supports the code grant flow.

Fixed

• .Authorizer class can be used with .UntrustedAuthenticator.

---

Fixed

• session works with .DeviceIDAuthorizer and .ImplicitAuthorizer.

---

Added

• Add .ImplicitAuthorizer.

Changed

• Split Authenticator into .TrustedAuthenticator and .UntrustedAuthenticator.

---

Added

• Add .DeviceIDAuthorizer that permits installed application access to the API.

---

Added

• RequestException which wraps all exceptions that occur from requests.request in a prawcore.RequestException.

Changed

• What was previously RequestException is now ResponseException.

---

Added

• Handle Cloudflare 522 responses.

---

Added

• Add ServerError exception for 502, 503, and 504 HTTP status codes that is only raised after three failed attempts to make the request.

• Add json parameter to Session.request.

---

Added

• Automatically attempt to refresh access tokens when making a request if the access token is expired.

Fixed

• Consider access tokens expired slightly earlier than allowed for to prevent InvalidToken exceptions from occuring.

---

Added

• Handle 0-byte HTTP 200 responses.

---

Added

• Add a NotFound exception.

• Support 404 "Not Found" HTTP responses.

---

Added

• Add a BadRequest exception.

• Support 400 "Bad Request" HTTP responses.

• Support 204 "No Content" HTTP responses.

---

Added

• Support 201 "Created" HTTP responses used in some v1 endpoints.

---

Added

• Sort Session.request data values. Sorting the values permits betamax body matcher to work as expected.

---

Added

• Added data parameter to Session.request.

---

Fixed

• prawcore objects can be pickled.

---

Added

• 302 redirects result in a Redirect exception.

---

Added

• Add a generic Forbidden exception for 403 responses without the www-authenticate header.

---

Added

• Added params parameter to Session.request.

• Log requests to the prawcore logger in debug mode.

---

Fixed

• README.rst for display purposes on pypi.

---