Fix undocumented exceptions and deprecate URLRequired

docs/user/api.rst

@@ -0,0 +1,114 @@
+.. _api:
+
+API Reference
+=============
+
+This part of the documentation covers all the interfaces of `requests`. For parts where `requests` depends on external libraries, we document the most important right here and provide links to the canonical documentation.
+
+Main Interface
+--------------
+
+`requests` provides two main interfaces:
+
+- The :ref:`requests module <api-requests>`.
+- The :ref:`Session class <api-session>`.
+
+All of the requests functions and methods will return a :ref:`Response <api-response>` object. The :ref:`Response <api-response>` object contains all of the information returned by the server and will also contain the information you need.
+
+The :ref:`Session <api-session>` object allows you to persist certain parameters across requests. It also persists cookies across all requests made from the Session instance, and will use urllib3's connection pooling. So if you're making several requests to the same host, the underlying TCP connection will be reused, which can result in a significant performance increase (see HTTP persistent connection).
+
+The other :ref:`Session <api-session>` feature is that it will use per-host proxies which are defined in environment variables. This is particularly useful if you are using requests from an application which does not have permission to use proxies.
+
+.. _api-requests:
+
+The Requests module
+-------------------
+
+.. autofunction:: requests.request
+.. autofunction:: requests.get
+.. autofunction:: requests.head
+.. autofunction:: requests.post
+.. autofunction:: requests.put
+.. autofunction:: requests.patch
+.. autofunction:: requests.delete
+.. autofunction:: requests.options
+
+.. _api-session:
+
+The Session object
+------------------
+
+.. autoclass:: requests.Session
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. _api-response:
+
+The Response object
+-------------------
+
+.. autoclass:: requests.Response
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. _api-exceptions:
+
+Exceptions
+----------
+
+.. autoclass:: requests.RequestException
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.ConnectionError
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.HTTPError
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.URLRequired
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.TooManyRedirects
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.ConnectTimeout
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.ReadTimeout
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.Timeout
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.MissingSchema
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.InvalidSchema
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. autoclass:: requests.InvalidURL
+    :members:
+    :inherited-members:
+    :show-inheritance:

src/requests/exceptions.py

@@ -88,10 +88,6 @@ class ReadTimeout(Timeout):
     """The server did not send any data in the allotted amount of time."""
 
 
-class URLRequired(RequestException):
-    """A valid URL is required to make a request."""
-
-
 class TooManyRedirects(RequestException):
     """Too many redirects."""