Fix Sphinx links in documentation
MODIFY
docs/conf.py
docs/conf.py
@@ -82,3 +82,24 @@ html_theme_options = {
}
intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+# Show typehints as content of the function or method
+autodoc_typehints = "description"
+
+# Warn about all references to unknown targets
+nitpicky = True
+# Except for these ones, which we expect to point to unknown targets:
+nitpick_ignore = [
+ ("py:class", "Literal"),
+ ("py:class", "email.errors.MessageDefect"),
+ ("py:class", "http.client.HTTPMessage"),
+ ("py:class", "RequestHistory"),
+ ("py:class", "SSLTransportType"),
+ ("py:class", "VerifyMode"),
+ ("py:class", "_ssl._SSLContext"),
+ ("py:class", "urllib3._collections.HTTPHeaderDict"),
+ ("py:class", "urllib3._collections.RecentlyUsedContainer"),
+ ("py:class", "urllib3._request_methods.RequestMethods"),
+ ("py:class", "urllib3.contrib.socks._TYPE_SOCKS_OPTIONS"),
+ ("py:class", "urllib3.util.timeout._TYPE_DEFAULT"),
+]

MODIFY
docs/reference/urllib3.connection.rst
docs/reference/urllib3.connection.rst
@@ -9,3 +9,7 @@ Connections
.. autoclass:: urllib3.connection.HTTPSConnection
:members:
:show-inheritance:
+
+.. autoclass:: urllib3.connection.ProxyConfig
+ :members:
+ :show-inheritance:

MODIFY
docs/reference/urllib3.connectionpool.rst
docs/reference/urllib3.connectionpool.rst
@@ -15,3 +15,5 @@ Connection Pools
:members:
:undoc-members:
:show-inheritance:
+
+.. autofunction:: urllib3.connectionpool.connection_from_url

MODIFY
docs/reference/urllib3.poolmanager.rst
docs/reference/urllib3.poolmanager.rst
@@ -5,8 +5,14 @@ Pool Manager
:members:
:undoc-members:
:show-inheritance:
+ :inherited-members:
.. autoclass:: urllib3.ProxyManager
:members:
:undoc-members:
:show-inheritance:
+
+.. autoclass:: urllib3.poolmanager.PoolKey
+ :members:
+ :undoc-members:
+ :show-inheritance:

MODIFY
docs/reference/urllib3.response.rst
docs/reference/urllib3.response.rst
@@ -4,10 +4,20 @@ Response and Decoders
Response
--------
+.. autoclass:: urllib3.response.BaseHTTPResponse
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
.. autoclass:: urllib3.response.HTTPResponse
:members:
:undoc-members:
:show-inheritance:
+ :inherited-members: json
+
+ .. autoattribute:: auto_close
+ .. autoattribute:: status
+ .. autoattribute:: headers
Decoders
--------

MODIFY
docs/reference/urllib3.util.rst
docs/reference/urllib3.util.rst
@@ -4,11 +4,11 @@ Utilities
Useful methods for working with :mod:`http.client`, completely decoupled from
code specific to **urllib3**.
-At the very core, just like its predecessors, :mod:`urllib3` is built on top of
+At the very core, just like its predecessors, urllib3 is built on top of
:mod:`http.client` -- the lowest level HTTP library included in the Python
standard library.
-To aid the limited functionality of the :mod:`http.client` module, :mod:`urllib3`
+To aid the limited functionality of the :mod:`http.client` module, urllib3
provides various helper methods which are used with the higher level components
but can also be used independently.

MODIFY
docs/requirements.txt
docs/requirements.txt
-r ../dev-requirements.txt
+# We pin the pip version to 22.0.4 because of a bug in 22.1
+# It can be removed when the bug fixed.
+# https://github.com/pypa/pip/issues/11110
+pip==22.0.4
sphinx>3.0.0
requests>=2,<2.16
furo

MODIFY
docs/user-guide.rst
docs/user-guide.rst
@@ -30,7 +30,7 @@ so that you don't have to:
http = urllib3.PoolManager()
-To make a request use :meth:`~poolmanager.PoolManager.request`:
+To make a request use :meth:`~urllib3.PoolManager.request`:
.. code-block:: python
@@ -49,7 +49,7 @@ To make a request use :meth:`~poolmanager.PoolManager.request`:
``request()`` returns a :class:`~response.HTTPResponse` object, the
:ref:`response_content` section explains how to handle various responses.
-You can use :meth:`~poolmanager.PoolManager.request` to make requests using any
+You can use :meth:`~urllib3.PoolManager.request` to make requests using any
HTTP verb:
.. code-block:: python
@@ -179,7 +179,7 @@ Request Data
Headers
~~~~~~~
-You can specify headers as a dictionary in the ``headers`` argument in :meth:`~poolmanager.PoolManager.request`:
+You can specify headers as a dictionary in the ``headers`` argument in :meth:`~urllib3.PoolManager.request`:
.. code-block:: python
@@ -258,7 +258,7 @@ Query Parameters
For ``GET``, ``HEAD``, and ``DELETE`` requests, you can simply pass the
arguments as a dictionary in the ``fields`` argument to
-:meth:`~poolmanager.PoolManager.request`:
+:meth:`~urllib3.PoolManager.request`:
.. code-block:: python
@@ -299,7 +299,7 @@ Form Data
For ``PUT`` and ``POST`` requests, urllib3 will automatically form-encode the
dictionary in the ``fields`` argument provided to
-:meth:`~poolmanager.PoolManager.request`:
+:meth:`~urllib3.PoolManager.request`:
.. code-block:: python
@@ -323,7 +323,7 @@ You can send a JSON request by specifying the data as ``json`` argument,
urllib3 automatically encodes data using ``json`` module with ``UTF-8``
encoding. Also by default ``"Content-Type"`` in headers is set to
``"application/json"`` if not specified when calling
-:meth:`~poolmanager.PoolManager.request`:
+:meth:`~urllib3.PoolManager.request`:
.. code-block:: python
@@ -471,7 +471,7 @@ Using Timeouts
Timeouts allow you to control how long (in seconds) requests are allowed to run
before being aborted. In simple cases, you can specify a timeout as a ``float``
-to :meth:`~poolmanager.PoolManager.request`:
+to :meth:`~urllib3.PoolManager.request`:
.. code-block:: python
@@ -532,14 +532,14 @@ the timeout at the :class:`~urllib3.poolmanager.PoolManager` level:
)
You still override this pool-level timeout by specifying ``timeout`` to
-:meth:`~poolmanager.PoolManager.request`.
+:meth:`~urllib3.PoolManager.request`.
Retrying Requests
-----------------
urllib3 can automatically retry idempotent requests. This same mechanism also
handles redirects. You can control the retries using the ``retries`` parameter
-to :meth:`~poolmanager.PoolManager.request`. By default, urllib3 will retry
+to :meth:`~urllib3.PoolManager.request`. By default, urllib3 will retry
requests 3 times and follow up to 3 redirects.
To change the number of retries just specify an integer:
@@ -630,7 +630,7 @@ specify the retry at the :class:`~urllib3.poolmanager.PoolManager` level:
)
You still override this pool-level retry policy by specifying ``retries`` to
-:meth:`~poolmanager.PoolManager.request`.
+:meth:`~urllib3.PoolManager.request`.
Errors & Exceptions
-------------------

MODIFY
src/urllib3/connectionpool.py
src/urllib3/connectionpool.py
@@ -557,8 +557,8 @@ class HTTPConnectionPool(ConnectionPool, RequestMethods):
.. note::
- More commonly, it's appropriate to use a convenience method provided
- by :class:`.RequestMethods`, such as :meth:`request`.
+ More commonly, it's appropriate to use a convenience method
+ such as :meth:`request`.
.. note::

MODIFY
src/urllib3/exceptions.py
src/urllib3/exceptions.py
@@ -93,8 +93,9 @@ class MaxRetryError(RequestError):
:param pool: The connection pool
:type pool: :class:`~urllib3.connectionpool.HTTPConnectionPool`
- :param string url: The requested Url
- :param exceptions.Exception reason: The underlying error
+ :param str url: The requested Url
+ :param reason: The underlying error
+ :type reason: :class:`Exception`
"""

MODIFY
src/urllib3/util/retry.py
src/urllib3/util/retry.py
@@ -128,7 +128,7 @@ class Retry:
If ``total`` is not set, it's a good idea to set this to 0 to account
for unexpected edge cases and avoid infinite retry loops.
- :param iterable allowed_methods:
+ :param Collection allowed_methods:
Set of uppercased HTTP method verbs that we should retry on.
By default, we only retry on methods which are considered to be
@@ -137,7 +137,7 @@ class Retry:
Set to a ``None`` value to retry on any verb.
- :param iterable status_forcelist:
+ :param Collection status_forcelist:
A set of integer HTTP status codes that we should force a retry on.
A retry is initiated if the request method is in ``allowed_methods``
and the response status code is in ``status_forcelist``.
@@ -151,9 +151,9 @@ class Retry:
{backoff factor} * (2 ** ({number of total retries} - 1))
- seconds. If the backoff_factor is 0.1, then :func:`.sleep` will sleep
+ seconds. If the backoff_factor is 0.1, then :func:`Retry.sleep` will sleep
for [0.0s, 0.2s, 0.4s, ...] between retries. It will never be longer
- than :attr:`Retry.backoff_max`.
+ than `backoff_max`.
By default, backoff is disabled (set to 0).
@@ -174,7 +174,7 @@ class Retry:
Whether to respect Retry-After header on status codes defined as
:attr:`Retry.RETRY_AFTER_STATUS_CODES` or not.
- :param iterable remove_headers_on_redirect:
+ :param Collection remove_headers_on_redirect:
Sequence of headers to remove from the request when a response
indicating a redirect is returned before firing off the redirected
request.

MODIFY
src/urllib3/util/timeout.py
src/urllib3/util/timeout.py
@@ -179,7 +179,7 @@ class Timeout:
passed to this function.
:param timeout: The legacy timeout value.
- :type timeout: integer, float, sentinel default object, or None
+ :type timeout: integer, float, :attr:`urllib3.util.Timeout.DEFAULT_TIMEOUT`, or None
:return: Timeout object
:rtype: :class:`Timeout`
"""

MODIFY
src/urllib3/util/url.py
src/urllib3/util/url.py
@@ -364,7 +364,7 @@ def parse_url(url: str) -> Url:
:param str url: URL to parse into a :class:`.Url` namedtuple.
- Partly backwards-compatible with :mod:`urlparse`.
+ Partly backwards-compatible with :mod:`urllib.parse`.
Example:

Fix Sphinx links in documentation (#2604)