Fix autodoc and intersphinx links in documentation
MODIFY
docs/reference/urllib3.connection.rst
docs/reference/urllib3.connection.rst
@@ -3,10 +3,9 @@ Connections
.. autoclass:: urllib3.connection.HTTPConnection
:members:
- :undoc-members:
+ :exclude-members: putrequest
:show-inheritance:
.. autoclass:: urllib3.connection.HTTPSConnection
:members:
- :undoc-members:
:show-inheritance:

MODIFY
src/urllib3/connection.py
src/urllib3/connection.py
@@ -196,7 +196,9 @@ class HTTPConnection(_HTTPConnection, object):
self._prepare_conn(conn)
def putrequest(self, method, url, *args, **kwargs):
- """Send a request to the server"""
+ """"""
+ # Empty docstring because the indentation of CPython's implementation
+ # is broken but we don't want this method in our documentation.
match = _CONTAINS_CONTROL_CHAR_RE.search(method)
if match:
raise ValueError(

MODIFY
src/urllib3/connectionpool.py
src/urllib3/connectionpool.py
@@ -112,16 +112,16 @@ class HTTPConnectionPool(ConnectionPool, RequestMethods):
:param host:
Host used for this HTTP Connection (e.g. "localhost"), passed into
- :class:`httplib.HTTPConnection`.
+ :class:`http.client.HTTPConnection`.
:param port:
Port used for this HTTP Connection (None is equivalent to 80), passed
- into :class:`httplib.HTTPConnection`.
+ into :class:`http.client.HTTPConnection`.
:param strict:
Causes BadStatusLine to be raised if the status line can't be parsed
as a valid HTTP/1.0 or 1.1 status line, passed into
- :class:`httplib.HTTPConnection`.
+ :class:`http.client.HTTPConnection`.
.. note::
Only works in Python 2. This parameter is ignored in Python 3.
@@ -155,11 +155,11 @@ class HTTPConnectionPool(ConnectionPool, RequestMethods):
:param _proxy:
Parsed proxy URL, should not be used directly, instead, see
- :class:`urllib3.connectionpool.ProxyManager`
+ :class:`urllib3.ProxyManager`
:param _proxy_headers:
A dictionary with proxy headers, should not be used directly,
- instead, see :class:`urllib3.connectionpool.ProxyManager`
+ instead, see :class:`urllib3.ProxyManager`
:param \\**conn_kw:
Additional parameters are used to create fresh :class:`urllib3.connection.HTTPConnection`,
@@ -273,7 +273,7 @@ class HTTPConnectionPool(ConnectionPool, RequestMethods):
conn.close()
if getattr(conn, "auto_open", 1) == 0:
# This is a proxied connection that has been mutated by
- # httplib._tunnel() and cannot be reused (since it would
+ # http.client._tunnel() and cannot be reused (since it would
# attempt to bypass the proxy)
conn = None
@@ -385,7 +385,7 @@ class HTTPConnectionPool(ConnectionPool, RequestMethods):
self._raise_timeout(err=e, url=url, timeout_value=conn.timeout)
raise
- # conn.request() calls httplib.*.request, not the method in
+ # conn.request() calls http.client.*.request, not the method in
# urllib3.request. It also calls makefile (recv) on the socket.
try:
if chunked:
@@ -584,7 +584,7 @@ class HTTPConnectionPool(ConnectionPool, RequestMethods):
:param assert_same_host:
If ``True``, will make sure that the host of the pool requests is
- consistent else will raise HostChangedError. When False, you can
+ consistent else will raise HostChangedError. When ``False``, you can
use the pool on an HTTP proxy and request foreign hosts.
:param timeout:
@@ -856,11 +856,7 @@ class HTTPSConnectionPool(HTTPConnectionPool):
"""
Same as :class:`.HTTPConnectionPool`, but HTTPS.
- When Python is compiled with the :mod:`ssl` module, then
- :class:`.VerifiedHTTPSConnection` is used, which *can* verify certificates,
- instead of :class:`.HTTPSConnection`.
-
- :class:`.VerifiedHTTPSConnection` uses one of ``assert_fingerprint``,
+ :class:`.HTTPSConnection` uses one of ``assert_fingerprint``,
``assert_hostname`` and ``host`` in this order to verify connections.
If ``assert_hostname`` is False, no verification is done.
@@ -957,7 +953,7 @@ class HTTPSConnectionPool(HTTPConnectionPool):
def _new_conn(self):
"""
- Return a fresh :class:`httplib.HTTPSConnection`.
+ Return a fresh :class:`http.client.HTTPSConnection`.
"""
self.num_connections += 1
log.debug(

MODIFY
src/urllib3/exceptions.py
src/urllib3/exceptions.py
@@ -5,17 +5,19 @@ from .packages.six.moves.http_client import IncompleteRead as httplib_Incomplete
class HTTPError(Exception):
- "Base exception used by this module."
+ """Base exception used by this module."""
+
pass
class HTTPWarning(Warning):
- "Base warning used by this module."
+ """Base warning used by this module."""
+
pass
class PoolError(HTTPError):
- "Base exception for errors caused within a pool."
+ """Base exception for errors caused within a pool."""
def __init__(self, pool, message):
self.pool = pool
@@ -27,7 +29,7 @@ class PoolError(HTTPError):
class RequestError(PoolError):
- "Base exception for PoolErrors that have associated URLs."
+ """Base exception for PoolErrors that have associated URLs."""
def __init__(self, pool, url, message):
self.url = url
@@ -39,12 +41,13 @@ class RequestError(PoolError):
class SSLError(HTTPError):
- "Raised when SSL certificate fails in an HTTPS connection."
+ """Raised when SSL certificate fails in an HTTPS connection."""
+
pass
class ProxyError(HTTPError):
- "Raised when the connection to a proxy fails."
+ """Raised when the connection to a proxy fails."""
def __init__(self, message, error, *args):
super(ProxyError, self).__init__(message, error, *args)
@@ -52,12 +55,14 @@ class ProxyError(HTTPError):
class DecodeError(HTTPError):
- "Raised when automatic decoding based on Content-Type fails."
+ """Raised when automatic decoding based on Content-Type fails."""
+
pass
class ProtocolError(HTTPError):
- "Raised when something unexpected happens mid-request/response."
+ """Raised when something unexpected happens mid-request/response."""
+
pass
@@ -87,7 +92,7 @@ class MaxRetryError(RequestError):
class HostChangedError(RequestError):
- "Raised when an existing pool gets a request for a foreign host."
+ """Raised when an existing pool gets a request for a foreign host."""
def __init__(self, pool, url, retries=3):
message = "Tried to open a foreign host with url: %s" % url
@@ -112,39 +117,45 @@ class TimeoutError(HTTPError):
class ReadTimeoutError(TimeoutError, RequestError):
- "Raised when a socket timeout occurs while receiving data from a server"
+ """Raised when a socket timeout occurs while receiving data from a server"""
+
pass
# This timeout error does not have a URL attached and needs to inherit from the
# base HTTPError
class ConnectTimeoutError(TimeoutError):
- "Raised when a socket timeout occurs while connecting to a server"
+ """Raised when a socket timeout occurs while connecting to a server"""
+
pass
class NewConnectionError(ConnectTimeoutError, PoolError):
- "Raised when we fail to establish a new connection. Usually ECONNREFUSED."
+ """Raised when we fail to establish a new connection. Usually ECONNREFUSED."""
+
pass
class EmptyPoolError(PoolError):
- "Raised when a pool runs out of connections and no more are allowed."
+ """Raised when a pool runs out of connections and no more are allowed."""
+
pass
class ClosedPoolError(PoolError):
- "Raised when a request enters a pool after the pool has been closed."
+ """Raised when a request enters a pool after the pool has been closed."""
+
pass
class LocationValueError(ValueError, HTTPError):
- "Raised when there is something wrong with a given URL input."
+ """Raised when there is something wrong with a given URL input."""
+
pass
class LocationParseError(LocationValueError):
- "Raised when get_host or similar fails to parse the URL input."
+ """Raised when get_host or similar fails to parse the URL input."""
def __init__(self, location):
message = "Failed to parse: %s" % location
@@ -154,7 +165,7 @@ class LocationParseError(LocationValueError):
class URLSchemeUnknown(LocationValueError):
- "Raised when a URL input has an unsupported scheme."
+ """Raised when a URL input has an unsupported scheme."""
def __init__(self, scheme):
message = "Not supported URL scheme %s" % scheme
@@ -164,38 +175,45 @@ class URLSchemeUnknown(LocationValueError):
class ResponseError(HTTPError):
- "Used as a container for an error reason supplied in a MaxRetryError."
+ """Used as a container for an error reason supplied in a MaxRetryError."""
+
GENERIC_ERROR = "too many error responses"
SPECIFIC_ERROR = "too many {status_code} error responses"
class SecurityWarning(HTTPWarning):
- "Warned when performing security reducing actions"
+ """Warned when performing security reducing actions"""
+
pass
class SubjectAltNameWarning(SecurityWarning):
- "Warned when connecting to a host with a certificate missing a SAN."
+ """Warned when connecting to a host with a certificate missing a SAN."""
+
pass
class InsecureRequestWarning(SecurityWarning):
- "Warned when making an unverified HTTPS request."
+ """Warned when making an unverified HTTPS request."""
+
pass
class SystemTimeWarning(SecurityWarning):
- "Warned when system time is suspected to be wrong"
+ """Warned when system time is suspected to be wrong"""
+
pass
class InsecurePlatformWarning(SecurityWarning):
- "Warned when certain SSL configuration is not available on a platform."
+ """Warned when certain TLS/SSL configuration is not available on a platform."""
+
pass
class SNIMissingWarning(HTTPWarning):
- "Warned when making a HTTPS request without SNI available."
+ """Warned when making a HTTPS request without SNI available."""
+
pass
@@ -209,14 +227,15 @@ class DependencyWarning(HTTPWarning):
class ResponseNotChunked(ProtocolError, ValueError):
- "Response needs to be chunked in order to read it as chunks."
+ """Response needs to be chunked in order to read it as chunks."""
+
pass
class BodyNotHttplibCompatible(HTTPError):
"""
- Body should be httplib.HTTPResponse like (have an fp attribute which
- returns raw chunks) for read_chunked().
+ Body should be :class:`http.client.HTTPResponse` like
+ (have an fp attribute which returns raw chunks) for read_chunked().
"""
pass
@@ -226,9 +245,8 @@ class IncompleteRead(HTTPError, httplib_IncompleteRead):
"""
Response length doesn't match expected Content-Length
- Subclass of http_client.IncompleteRead to allow int value
- for `partial` to avoid creating large objects on streamed
- reads.
+ Subclass of :class:`http.client.IncompleteRead` to allow int value
+ for ``partial`` to avoid creating large objects on streamed reads.
"""
def __init__(self, partial, expected):
@@ -259,12 +277,14 @@ class InvalidChunkLength(HTTPError, httplib_IncompleteRead):
class InvalidHeader(HTTPError):
- "The header provided was somehow invalid."
+ """The header provided was somehow invalid."""
+
pass
class ProxySchemeUnknown(AssertionError, URLSchemeUnknown):
- "ProxyManager does not support the supplied scheme"
+ """ProxyManager does not support the supplied scheme"""
+
# TODO(t-8ch): Stop inheriting from AssertionError in v2.0.
def __init__(self, scheme):
@@ -273,12 +293,13 @@ class ProxySchemeUnknown(AssertionError, URLSchemeUnknown):
class ProxySchemeUnsupported(ValueError):
- "Fetching HTTPS resources through HTTPS proxies is unsupported"
+ """Fetching HTTPS resources through HTTPS proxies is unsupported"""
+
pass
class HeaderParsingError(HTTPError):
- "Raised by assert_header_parsing, but we convert it to a log.warning statement."
+ """Raised by assert_header_parsing, but we convert it to a log.warning statement."""
def __init__(self, defects, unparsed_data):
message = "%s, unparsed data: %r" % (defects or "Unknown", unparsed_data)
@@ -286,5 +307,6 @@ class HeaderParsingError(HTTPError):
class UnrewindableBodyError(HTTPError):
- "urllib3 encountered an error when trying to rewind a body"
+ """urllib3 encountered an error when trying to rewind a body"""
+
pass

MODIFY
src/urllib3/fields.py
src/urllib3/fields.py
@@ -26,7 +26,8 @@ def format_header_param_rfc2231(name, value):
strategy defined in RFC 2231.
Particularly useful for header parameters which might contain
- non-ASCII values, like file names. This follows RFC 2388 Section 4.4.
+ non-ASCII values, like file names. This follows
+ `RFC 2388 Section 4.4 <https://tools.ietf.org/html/rfc2388#section-4.4>`_.
:param name:
The name of the parameter, a string expected to be ASCII only.

MODIFY
src/urllib3/poolmanager.py
src/urllib3/poolmanager.py
@@ -337,7 +337,7 @@ class PoolManager(RequestMethods):
def urlopen(self, method, url, redirect=True, **kw):
"""
- Same as :meth:`urllib3.connectionpool.HTTPConnectionPool.urlopen`
+ Same as :meth:`urllib3.HTTPConnectionPool.urlopen`
with custom cross-host redirect logic and only sends the request-uri
portion of the ``url``.

MODIFY
src/urllib3/request.py
src/urllib3/request.py
@@ -10,8 +10,8 @@ __all__ = ["RequestMethods"]
class RequestMethods(object):
"""
Convenience mixin for classes who implement a :meth:`urlopen` method, such
- as :class:`~urllib3.connectionpool.HTTPConnectionPool` and
- :class:`~urllib3.poolmanager.PoolManager`.
+ as :class:`urllib3.HTTPConnectionPool` and
+ :class:`urllib3.PoolManager`.
Provides behavior for making common types of HTTP request methods and
decides which type of request field encoding to use.
@@ -111,9 +111,9 @@ class RequestMethods(object):
the body. This is useful for request methods like POST, PUT, PATCH, etc.
When ``encode_multipart=True`` (default), then
- :meth:`urllib3.filepost.encode_multipart_formdata` is used to encode
+ :func:`urllib3.encode_multipart_formdata` is used to encode
the payload with the appropriate content type. Otherwise
- :meth:`urllib.urlencode` is used with the
+ :func:`urllib.parse.urlencode` is used with the
'application/x-www-form-urlencoded' content type.
Multipart encoding must be used when posting files, and it's reasonably

MODIFY
src/urllib3/response.py
src/urllib3/response.py
@@ -157,13 +157,13 @@ class HTTPResponse(io.IOBase):
"""
HTTP Response container.
- Backwards-compatible to httplib's HTTPResponse but the response ``body`` is
+ Backwards-compatible with :class:`http.client.HTTPResponse` but the response ``body`` is
loaded and decoded on-demand when the ``data`` property is accessed. This
class is also compatible with the Python standard library's :mod:`io`
module, and can hence be treated as a readable object in the context of that
framework.
- Extra parameters for behaviour not present in httplib.HTTPResponse:
+ Extra parameters for behaviour not present in :class:`http.client.HTTPResponse`:
:param preload_content:
If True, the response's body will be preloaded during construction.
@@ -173,7 +173,7 @@ class HTTPResponse(io.IOBase):
'content-encoding' header.
:param original_response:
- When this HTTPResponse wrapper is generated from an httplib.HTTPResponse
+ When this HTTPResponse wrapper is generated from an :class:`http.client.HTTPResponse`
object, it's convenient to include the original for debug purposes. It's
otherwise unused.
@@ -308,8 +308,8 @@ class HTTPResponse(io.IOBase):
def tell(self):
"""
Obtain the number of bytes pulled over the wire so far. May differ from
- the amount of content returned by :meth:``HTTPResponse.read`` if bytes
- are encoded on the wire (e.g, compressed).
+ the amount of content returned by :meth:``urllib3.response.HTTPResponse.read``
+ if bytes are encoded on the wire (e.g, compressed).
"""
return self._fp_bytes_read
@@ -479,7 +479,7 @@ class HTTPResponse(io.IOBase):
def read(self, amt=None, decode_content=None, cache_content=False):
"""
- Similar to :meth:`httplib.HTTPResponse.read`, but with two additional
+ Similar to :meth:`http.client.HTTPResponse.read`, but with two additional
parameters: ``decode_content`` and ``cache_content``.
:param amt:
@@ -580,7 +580,7 @@ class HTTPResponse(io.IOBase):
@classmethod
def from_httplib(ResponseCls, r, **response_kw):
"""
- Given an :class:`httplib.HTTPResponse` instance ``r``, return a
+ Given an :class:`http.client.HTTPResponse` instance ``r``, return a
corresponding :class:`urllib3.response.HTTPResponse` object.
Remaining parameters are passed to the HTTPResponse constructor, along
@@ -609,7 +609,7 @@ class HTTPResponse(io.IOBase):
)
return resp
- # Backwards-compatibility methods for httplib.HTTPResponse
+ # Backwards-compatibility methods for http.client.HTTPResponse
def getheaders(self):
return self.headers
@@ -679,8 +679,8 @@ class HTTPResponse(io.IOBase):
def supports_chunked_reads(self):
"""
Checks if the underlying file-like object looks like a
- httplib.HTTPResponse object. We do this by testing for the fp
- attribute. If it is present we assume it returns raw chunks as
+ :class:`http.client.HTTPResponse` object. We do this by testing for
+ the fp attribute. If it is present we assume it returns raw chunks as
processed by read_chunked().
"""
return hasattr(self._fp, "fp")
@@ -744,7 +744,7 @@ class HTTPResponse(io.IOBase):
)
if not self.supports_chunked_reads():
raise BodyNotHttplibCompatible(
- "Body should be httplib.HTTPResponse like. "
+ "Body should be http.client.HTTPResponse like. "
"It should have have an fp attribute which returns raw chunks."
)

MODIFY
src/urllib3/util/connection.py
src/urllib3/util/connection.py
@@ -9,7 +9,7 @@ def is_connection_dropped(conn): # Platform-specific
Returns True if the connection is dropped and should be closed.
:param conn:
- :class:`httplib.HTTPConnection` object.
+ :class:`http.client.HTTPConnection` object.
Note: For platforms like AppEngine, this will always return ``False`` to
let the platform handle connection recycling transparently for us.
@@ -42,7 +42,7 @@ def create_connection(
port)``) and return the socket object. Passing the optional
*timeout* parameter will set the timeout on the socket instance
before attempting to connect. If no *timeout* is supplied, the
- global default timeout setting returned by :func:`getdefaulttimeout`
+ global default timeout setting returned by :func:`socket.getdefaulttimeout`
is used. If *source_address* is set it must be a tuple of (host, port)
for the socket to bind as a source address before making the connection.
An host of '' or port 0 tells the OS to use the default.

MODIFY
src/urllib3/util/response.py
src/urllib3/util/response.py
@@ -43,8 +43,7 @@ def assert_header_parsing(headers):
Only works on Python 3.
- :param headers: Headers to verify.
- :type headers: `httplib.HTTPMessage`.
+ :param http.client.HTTPMessage headers: Headers to verify.
:raises urllib3.exceptions.HeaderParsingError:
If parsing errors are found.
@@ -96,8 +95,9 @@ def is_response_to_head(response):
Checks whether the request of a response has been a HEAD-request.
Handles the quirks of AppEngine.
- :param conn:
- :type conn: :class:`httplib.HTTPResponse`
+ :param http.client.HTTPResponse response:
+ Response to check if the originating request
+ used 'HEAD' as a method.
"""
# FIXME: Can we do this somehow without accessing private httplib _method?
method = response._method

MODIFY
src/urllib3/util/timeout.py
src/urllib3/util/timeout.py
@@ -19,17 +19,23 @@ current_time = getattr(time, "monotonic", time.time)
class Timeout(object):
"""Timeout configuration.
- Timeouts can be defined as a default for a pool::
+ Timeouts can be defined as a default for a pool:
+
+ .. code-block:: python
timeout = Timeout(connect=2.0, read=7.0)
http = PoolManager(timeout=timeout)
response = http.request('GET', 'http://example.com/')
- Or per-request (which overrides the default for the pool)::
+ Or per-request (which overrides the default for the pool):
+
+ .. code-block:: python
response = http.request('GET', 'http://example.com/', timeout=Timeout(10))
- Timeouts can be disabled by setting all the parameters to ``None``::
+ Timeouts can be disabled by setting all the parameters to ``None``:
+
+ .. code-block:: python
no_timeout = Timeout(connect=None, read=None)
response = http.request('GET', 'http://example.com/, timeout=no_timeout)
@@ -43,7 +49,7 @@ class Timeout(object):
Defaults to None.
- :type total: integer, float, or None
+ :type total: int, float, or None
:param connect:
The maximum amount of time (in seconds) to wait for a connection
@@ -53,7 +59,7 @@ class Timeout(object):
<http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.
None will set an infinite timeout for connection attempts.
- :type connect: integer, float, or None
+ :type connect: int, float, or None
:param read:
The maximum amount of time (in seconds) to wait between consecutive
@@ -63,7 +69,7 @@ class Timeout(object):
<http://hg.python.org/cpython/file/603b4d593758/Lib/socket.py#l535>`_.
None will set an infinite timeout.
- :type read: integer, float, or None
+ :type read: int, float, or None
.. note::

Fix autodoc and intersphinx links in documentation (#1966)