List of documented exceptions doesn't match reality / unused `URLRequired` exception

[The-Compiler]

The documentation lists a relatively small list of exceptions, among them:

exception requests.URLRequired(*args, **kwargs) A valid URL is required to make a request.

which would imply that passing an invalid URL raises URLRequired. However, that exception is actually dead code and not raised anywhere ever since ab27027aa8916e6e199bbb35083beb5d6339f6aa in 2012. Instead, with requests 2.32.3, invalid URLs raise something like MissingSchema, InvalidSchema or InvalidURL, none of which are documented.

Looking at exceptions.py, there seem to be various other undocumented exceptions in there:

• class InvalidJSONError(RequestException): (only JSONDecodeError which inherits from it)
• class ProxyError(ConnectionError):
• class SSLError(ConnectionError):
• class ConnectTimeout(ConnectionError, Timeout): (Timeout is documented)
• class ReadTimeout(Timeout): (Timeout is documented)
• class MissingSchema(RequestException, ValueError):
• class InvalidSchema(RequestException, ValueError):
• class InvalidURL(RequestException, ValueError):
• class InvalidHeader(RequestException, ValueError):
• class InvalidProxyURL(InvalidURL):
• class ChunkedEncodingError(RequestException):
• class ContentDecodingError(RequestException, BaseHTTPError):
• class StreamConsumedError(RequestException, TypeError):
• class RetryError(RequestException):
• class UnrewindableBodyError(RequestException):

(Some of those might be internal, or considered not worth documenting since they can be caught by except ValueError:. However, even e.g. Errors and Exceptions or the reference docs don't seem to point out that either.

[sethmlarson]

Thanks for reporting, if you could submit a PR fixing the issue it would be appreciated.

[The-Compiler]

The fix itself for this is probably trivial, at least for the "undocumented exceptions" part (adding a few .. autoexception:: requests.[...] lines). The bigger questions I cannot answer on my own are:

• Which of those exceptions above should be documented?
• What should happen to URLRequired, given that removing the unused exception class is a backwards-incompatible change? It seems to be used in the wild. Just let it be but remove the docs? Try to add a deprecation warning with a module-level __getattr__? Remove it completely?

[nateprewitt]

Removing the unused URLRequired from the docs is reasonable. The current listing is misleading. The exception itself needs to be left in the code for backwards compat. We could potentially make a note in the docstring it's deprecated if we're positive it's unused.

For intended workflow, this is in the linked docs which is the recommendation for exception handling within the library.

All exceptions that Requests explicitly raises inherit from requests.exceptions.RequestException.

Most of the unlisted exceptions are not particularly useful for application control flow. If there are specific ones users think are needed, we're happy to review those on a case-by-case basis.

[jakobheine]

I took a look into the init.py, all exceptions that are exported and hence intended to be used seem to be documented.

Add DepcrecationWarning to URLRequired with this PR: https://github.com/psf/requests/pull/6881

Remove it from docs with this PR: https://github.com/psf/requests/pull/6880