mirror of
https://github.com/python/cpython
synced 2024-10-14 19:21:29 +00:00
gh-101100: Fix Sphinx warnings in howto/urllib2.rst
and library/http.client.rst
(#114060)
This commit is contained in:
parent
5dbcdfdeb8
commit
c2808431b3
|
@ -392,16 +392,16 @@ info and geturl
|
|||
===============
|
||||
|
||||
The response returned by urlopen (or the :exc:`~urllib.error.HTTPError` instance) has two
|
||||
useful methods :meth:`info` and :meth:`geturl` and is defined in the module
|
||||
:mod:`urllib.response`..
|
||||
useful methods :meth:`!info` and :meth:`!geturl` and is defined in the module
|
||||
:mod:`urllib.response`.
|
||||
|
||||
**geturl** - this returns the real URL of the page fetched. This is useful
|
||||
because ``urlopen`` (or the opener object used) may have followed a
|
||||
redirect. The URL of the page fetched may not be the same as the URL requested.
|
||||
* **geturl** - this returns the real URL of the page fetched. This is useful
|
||||
because ``urlopen`` (or the opener object used) may have followed a
|
||||
redirect. The URL of the page fetched may not be the same as the URL requested.
|
||||
|
||||
**info** - this returns a dictionary-like object that describes the page
|
||||
fetched, particularly the headers sent by the server. It is currently an
|
||||
:class:`http.client.HTTPMessage` instance.
|
||||
* **info** - this returns a dictionary-like object that describes the page
|
||||
fetched, particularly the headers sent by the server. It is currently an
|
||||
:class:`http.client.HTTPMessage` instance.
|
||||
|
||||
Typical headers include 'Content-length', 'Content-type', and so on. See the
|
||||
`Quick Reference to HTTP Headers <https://jkorpela.fi/http.html>`_
|
||||
|
@ -507,7 +507,7 @@ than the URL you pass to .add_password() will also match. ::
|
|||
|
||||
In the above example we only supplied our ``HTTPBasicAuthHandler`` to
|
||||
``build_opener``. By default openers have the handlers for normal situations
|
||||
-- ``ProxyHandler`` (if a proxy setting such as an :envvar:`http_proxy`
|
||||
-- ``ProxyHandler`` (if a proxy setting such as an :envvar:`!http_proxy`
|
||||
environment variable is set), ``UnknownHandler``, ``HTTPHandler``,
|
||||
``HTTPDefaultErrorHandler``, ``HTTPRedirectHandler``, ``FTPHandler``,
|
||||
``FileHandler``, ``DataHandler``, ``HTTPErrorProcessor``.
|
||||
|
|
|
@ -92,7 +92,7 @@ The module provides the following classes:
|
|||
.. versionchanged:: 3.4.3
|
||||
This class now performs all the necessary certificate and hostname checks
|
||||
by default. To revert to the previous, unverified, behavior
|
||||
:func:`ssl._create_unverified_context` can be passed to the *context*
|
||||
:func:`!ssl._create_unverified_context` can be passed to the *context*
|
||||
parameter.
|
||||
|
||||
.. versionchanged:: 3.8
|
||||
|
@ -103,7 +103,7 @@ The module provides the following classes:
|
|||
.. versionchanged:: 3.10
|
||||
This class now sends an ALPN extension with protocol indicator
|
||||
``http/1.1`` when no *context* is given. Custom *context* should set
|
||||
ALPN protocols with :meth:`~ssl.SSLContext.set_alpn_protocol`.
|
||||
ALPN protocols with :meth:`~ssl.SSLContext.set_alpn_protocols`.
|
||||
|
||||
.. versionchanged:: 3.12
|
||||
The deprecated *key_file*, *cert_file* and *check_hostname* parameters
|
||||
|
@ -124,7 +124,7 @@ This module provides the following function:
|
|||
.. function:: parse_headers(fp)
|
||||
|
||||
Parse the headers from a file pointer *fp* representing a HTTP
|
||||
request/response. The file has to be a :class:`BufferedIOBase` reader
|
||||
request/response. The file has to be a :class:`~io.BufferedIOBase` reader
|
||||
(i.e. not text) and must provide a valid :rfc:`2822` style header.
|
||||
|
||||
This function returns an instance of :class:`http.client.HTTPMessage`
|
||||
|
@ -416,7 +416,7 @@ HTTPConnection Objects
|
|||
.. versionadded:: 3.7
|
||||
|
||||
|
||||
As an alternative to using the :meth:`request` method described above, you can
|
||||
As an alternative to using the :meth:`~HTTPConnection.request` method described above, you can
|
||||
also send your request step by step, by using the four functions below.
|
||||
|
||||
|
||||
|
@ -648,6 +648,8 @@ method attribute. Here is an example session that uses the ``PUT`` method::
|
|||
HTTPMessage Objects
|
||||
-------------------
|
||||
|
||||
.. class:: HTTPMessage(email.message.Message)
|
||||
|
||||
An :class:`http.client.HTTPMessage` instance holds the headers from an HTTP
|
||||
response. It is implemented using the :class:`email.message.Message` class.
|
||||
|
||||
|
|
|
@ -78,7 +78,7 @@ The :mod:`urllib.request` module defines the following functions:
|
|||
:class:`UnknownHandler` to ensure this never happens).
|
||||
|
||||
In addition, if proxy settings are detected (for example, when a ``*_proxy``
|
||||
environment variable like :envvar:`http_proxy` is set),
|
||||
environment variable like :envvar:`!http_proxy` is set),
|
||||
:class:`ProxyHandler` is default installed and makes sure the requests are
|
||||
handled through the proxy.
|
||||
|
||||
|
@ -113,7 +113,7 @@ The :mod:`urllib.request` module defines the following functions:
|
|||
.. versionchanged:: 3.10
|
||||
HTTPS connection now send an ALPN extension with protocol indicator
|
||||
``http/1.1`` when no *context* is given. Custom *context* should set
|
||||
ALPN protocols with :meth:`~ssl.SSLContext.set_alpn_protocol`.
|
||||
ALPN protocols with :meth:`~ssl.SSLContext.set_alpn_protocols`.
|
||||
|
||||
.. versionchanged:: 3.13
|
||||
Remove *cafile*, *capath* and *cadefault* parameters: use the *context*
|
||||
|
@ -618,25 +618,25 @@ OpenerDirector Objects
|
|||
the actual HTTP code, for example :meth:`http_error_404` would handle HTTP
|
||||
404 errors.
|
||||
|
||||
* :meth:`<protocol>_open` --- signal that the handler knows how to open *protocol*
|
||||
* :meth:`!<protocol>_open` --- signal that the handler knows how to open *protocol*
|
||||
URLs.
|
||||
|
||||
See |protocol_open|_ for more information.
|
||||
|
||||
* :meth:`http_error_\<type\>` --- signal that the handler knows how to handle HTTP
|
||||
* :meth:`!http_error_\<type\>` --- signal that the handler knows how to handle HTTP
|
||||
errors with HTTP error code *type*.
|
||||
|
||||
See |http_error_nnn|_ for more information.
|
||||
|
||||
* :meth:`<protocol>_error` --- signal that the handler knows how to handle errors
|
||||
* :meth:`!<protocol>_error` --- signal that the handler knows how to handle errors
|
||||
from (non-\ ``http``) *protocol*.
|
||||
|
||||
* :meth:`<protocol>_request` --- signal that the handler knows how to pre-process
|
||||
* :meth:`!<protocol>_request` --- signal that the handler knows how to pre-process
|
||||
*protocol* requests.
|
||||
|
||||
See |protocol_request|_ for more information.
|
||||
|
||||
* :meth:`<protocol>_response` --- signal that the handler knows how to
|
||||
* :meth:`!<protocol>_response` --- signal that the handler knows how to
|
||||
post-process *protocol* responses.
|
||||
|
||||
See |protocol_response|_ for more information.
|
||||
|
@ -663,7 +663,7 @@ OpenerDirector Objects
|
|||
Handle an error of the given protocol. This will call the registered error
|
||||
handlers for the given protocol with the given arguments (which are protocol
|
||||
specific). The HTTP protocol is a special case which uses the HTTP response
|
||||
code to determine the specific error handler; refer to the :meth:`http_error_\<type\>`
|
||||
code to determine the specific error handler; refer to the :meth:`!http_error_\<type\>`
|
||||
methods of the handler classes.
|
||||
|
||||
Return values and exceptions raised are the same as those of :func:`urlopen`.
|
||||
|
@ -673,25 +673,25 @@ OpenerDirector objects open URLs in three stages:
|
|||
The order in which these methods are called within each stage is determined by
|
||||
sorting the handler instances.
|
||||
|
||||
#. Every handler with a method named like :meth:`<protocol>_request` has that
|
||||
#. Every handler with a method named like :meth:`!<protocol>_request` has that
|
||||
method called to pre-process the request.
|
||||
|
||||
#. Handlers with a method named like :meth:`<protocol>_open` are called to handle
|
||||
#. Handlers with a method named like :meth:`!<protocol>_open` are called to handle
|
||||
the request. This stage ends when a handler either returns a non-\ :const:`None`
|
||||
value (ie. a response), or raises an exception (usually
|
||||
:exc:`~urllib.error.URLError`). Exceptions are allowed to propagate.
|
||||
|
||||
In fact, the above algorithm is first tried for methods named
|
||||
:meth:`default_open`. If all such methods return :const:`None`, the algorithm
|
||||
is repeated for methods named like :meth:`<protocol>_open`. If all such methods
|
||||
:meth:`~BaseHandler.default_open`. If all such methods return :const:`None`, the algorithm
|
||||
is repeated for methods named like :meth:`!<protocol>_open`. If all such methods
|
||||
return :const:`None`, the algorithm is repeated for methods named
|
||||
:meth:`unknown_open`.
|
||||
:meth:`~BaseHandler.unknown_open`.
|
||||
|
||||
Note that the implementation of these methods may involve calls of the parent
|
||||
:class:`OpenerDirector` instance's :meth:`~OpenerDirector.open` and
|
||||
:meth:`~OpenerDirector.error` methods.
|
||||
|
||||
#. Every handler with a method named like :meth:`<protocol>_response` has that
|
||||
#. Every handler with a method named like :meth:`!<protocol>_response` has that
|
||||
method called to post-process the response.
|
||||
|
||||
|
||||
|
@ -740,7 +740,7 @@ The following attribute and methods should only be used by classes derived from
|
|||
the return value of the :meth:`~OpenerDirector.open` method of :class:`OpenerDirector`, or ``None``.
|
||||
It should raise :exc:`~urllib.error.URLError`, unless a truly exceptional
|
||||
thing happens (for example, :exc:`MemoryError` should not be mapped to
|
||||
:exc:`URLError`).
|
||||
:exc:`~urllib.error.URLError`).
|
||||
|
||||
This method will be called before any protocol-specific open method.
|
||||
|
||||
|
@ -753,7 +753,7 @@ The following attribute and methods should only be used by classes derived from
|
|||
define it if they want to handle URLs with the given protocol.
|
||||
|
||||
This method, if defined, will be called by the parent :class:`OpenerDirector`.
|
||||
Return values should be the same as for :meth:`default_open`.
|
||||
Return values should be the same as for :meth:`~BaseHandler.default_open`.
|
||||
|
||||
|
||||
.. method:: BaseHandler.unknown_open(req)
|
||||
|
@ -793,7 +793,7 @@ The following attribute and methods should only be used by classes derived from
|
|||
Subclasses should override this method to handle specific HTTP errors.
|
||||
|
||||
Arguments, return values and exceptions raised should be the same as for
|
||||
:meth:`http_error_default`.
|
||||
:meth:`~BaseHandler.http_error_default`.
|
||||
|
||||
|
||||
.. _protocol_request:
|
||||
|
@ -833,7 +833,7 @@ HTTPRedirectHandler Objects
|
|||
is the case, :exc:`~urllib.error.HTTPError` is raised. See :rfc:`2616` for
|
||||
details of the precise meanings of the various redirection codes.
|
||||
|
||||
An :class:`HTTPError` exception raised as a security consideration if the
|
||||
An :exc:`~urllib.error.HTTPError` exception raised as a security consideration if the
|
||||
HTTPRedirectHandler is presented with a redirected URL which is not an HTTP,
|
||||
HTTPS or FTP URL.
|
||||
|
||||
|
@ -910,7 +910,7 @@ ProxyHandler Objects
|
|||
.. method:: ProxyHandler.<protocol>_open(request)
|
||||
:noindex:
|
||||
|
||||
The :class:`ProxyHandler` will have a method :meth:`<protocol>_open` for every
|
||||
The :class:`ProxyHandler` will have a method :meth:`!<protocol>_open` for every
|
||||
*protocol* which has a proxy in the *proxies* dictionary given in the
|
||||
constructor. The method will modify requests to go through the proxy, by
|
||||
calling ``request.set_proxy()``, and call the next handler in the chain to
|
||||
|
@ -1166,7 +1166,7 @@ HTTPErrorProcessor Objects
|
|||
For 200 error codes, the response object is returned immediately.
|
||||
|
||||
For non-200 error codes, this simply passes the job on to the
|
||||
:meth:`http_error_\<type\>` handler methods, via :meth:`OpenerDirector.error`.
|
||||
:meth:`!http_error_\<type\>` handler methods, via :meth:`OpenerDirector.error`.
|
||||
Eventually, :class:`HTTPDefaultErrorHandler` will raise an
|
||||
:exc:`~urllib.error.HTTPError` if no other handler handles the error.
|
||||
|
||||
|
@ -1273,7 +1273,7 @@ Use of Basic HTTP Authentication::
|
|||
:func:`build_opener` provides many handlers by default, including a
|
||||
:class:`ProxyHandler`. By default, :class:`ProxyHandler` uses the environment
|
||||
variables named ``<scheme>_proxy``, where ``<scheme>`` is the URL scheme
|
||||
involved. For example, the :envvar:`http_proxy` environment variable is read to
|
||||
involved. For example, the :envvar:`!http_proxy` environment variable is read to
|
||||
obtain the HTTP proxy's URL.
|
||||
|
||||
This example replaces the default :class:`ProxyHandler` with one that uses
|
||||
|
@ -1368,7 +1368,7 @@ some point in the future.
|
|||
points to a local file, the object will not be copied unless filename is supplied.
|
||||
Return a tuple ``(filename, headers)`` where *filename* is the
|
||||
local file name under which the object can be found, and *headers* is whatever
|
||||
the :meth:`info` method of the object returned by :func:`urlopen` returned (for
|
||||
the :meth:`!info` method of the object returned by :func:`urlopen` returned (for
|
||||
a remote object). Exceptions are the same as for :func:`urlopen`.
|
||||
|
||||
The second argument, if present, specifies the file location to copy to (if
|
||||
|
@ -1393,7 +1393,7 @@ some point in the future.
|
|||
:mimetype:`application/x-www-form-urlencoded` format; see the
|
||||
:func:`urllib.parse.urlencode` function.
|
||||
|
||||
:func:`urlretrieve` will raise :exc:`ContentTooShortError` when it detects that
|
||||
:func:`urlretrieve` will raise :exc:`~urllib.error.ContentTooShortError` when it detects that
|
||||
the amount of data available was less than the expected amount (which is the
|
||||
size reported by a *Content-Length* header). This can occur, for example, when
|
||||
the download is interrupted.
|
||||
|
@ -1402,8 +1402,8 @@ some point in the future.
|
|||
urlretrieve reads more data, but if less data is available, it raises the
|
||||
exception.
|
||||
|
||||
You can still retrieve the downloaded data in this case, it is stored in the
|
||||
:attr:`content` attribute of the exception instance.
|
||||
You can still retrieve the downloaded data in this case, it is stored in the
|
||||
:attr:`!content` attribute of the exception instance.
|
||||
|
||||
If no *Content-Length* header was supplied, urlretrieve can not check the size
|
||||
of the data it has downloaded, and just returns it. In this case you just have
|
||||
|
@ -1497,7 +1497,7 @@ some point in the future.
|
|||
authentication is performed. For the 30x response codes, recursion is bounded
|
||||
by the value of the *maxtries* attribute, which defaults to 10.
|
||||
|
||||
For all other response codes, the method :meth:`http_error_default` is called
|
||||
For all other response codes, the method :meth:`~BaseHandler.http_error_default` is called
|
||||
which you can override in subclasses to handle the error appropriately.
|
||||
|
||||
.. note::
|
||||
|
|
|
@ -24,7 +24,6 @@ Doc/glossary.rst
|
|||
Doc/howto/descriptor.rst
|
||||
Doc/howto/enum.rst
|
||||
Doc/howto/logging.rst
|
||||
Doc/howto/urllib2.rst
|
||||
Doc/library/ast.rst
|
||||
Doc/library/asyncio-extending.rst
|
||||
Doc/library/asyncio-policy.rst
|
||||
|
@ -49,7 +48,6 @@ Doc/library/faulthandler.rst
|
|||
Doc/library/fcntl.rst
|
||||
Doc/library/ftplib.rst
|
||||
Doc/library/functools.rst
|
||||
Doc/library/http.client.rst
|
||||
Doc/library/http.cookiejar.rst
|
||||
Doc/library/http.server.rst
|
||||
Doc/library/importlib.rst
|
||||
|
|
|
@ -1220,7 +1220,7 @@ class
|
|||
|
||||
Previously there was no way to check that without using private API. See the
|
||||
`relevant issue in python/typing
|
||||
<https://github.com/python/typing/issues/751>`
|
||||
<https://github.com/python/typing/issues/751>`_.
|
||||
|
||||
..
|
||||
|
||||
|
|
|
@ -584,8 +584,8 @@ Use the frame bound builtins when offering a name suggestion in
|
|||
.. nonce: qtm-9T
|
||||
.. section: Library
|
||||
|
||||
In :mod:`importlib._bootstrap`, enhance namespace package repr to `<module
|
||||
'x' (namespace) from ['path']>`.
|
||||
In :mod:`importlib._bootstrap`, enhance namespace package repr to ``<module
|
||||
'x' (namespace) from ['path']>``.
|
||||
|
||||
..
|
||||
|
||||
|
|
|
@ -199,7 +199,7 @@ their debugging to ``PYTHON_UOPS`` and ``PYTHON_LLTRACE``.
|
|||
.. nonce: 11h6Mc
|
||||
.. section: Core and Builtins
|
||||
|
||||
Speed up :obj:`Traceback` object creation by lazily compute the line number.
|
||||
Speed up :class:`Traceback` object creation by lazily compute the line number.
|
||||
Patch by Pablo Galindo
|
||||
|
||||
..
|
||||
|
|
|
@ -2857,8 +2857,8 @@ Patch by Justin Blanchard.
|
|||
Add formal support for UDPLITE sockets. Support was present before, but it
|
||||
is now easier to detect support with ``hasattr(socket, 'IPPROTO_UDPLITE')``
|
||||
and there are constants defined for each of the values needed:
|
||||
:py:obj:`socket.IPPROTO_UDPLITE`, :py:obj:`UDPLITE_SEND_CSCOV`, and
|
||||
:py:obj:`UDPLITE_RECV_CSCOV`. Patch by Gabe Appleton.
|
||||
``socket.IPPROTO_UDPLITE``, ``UDPLITE_SEND_CSCOV``, and
|
||||
``UDPLITE_RECV_CSCOV``. Patch by Gabe Appleton.
|
||||
|
||||
..
|
||||
|
||||
|
|
|
@ -112,8 +112,8 @@ Port :mod:`syslog` to multiphase initialization (:pep:`489`).
|
|||
Reporting a specialised error message for invalid string prefixes, which was
|
||||
introduced in :issue:`40246`, is being reverted due to backwards
|
||||
compatibility concerns for strings that immediately follow a reserved
|
||||
keyword without whitespace between them. Constructs like `bg="#d00" if clear
|
||||
else"#fca"` were failing to parse, which is not an acceptable breakage on
|
||||
keyword without whitespace between them. Constructs like ``bg="#d00" if clear
|
||||
else"#fca"`` were failing to parse, which is not an acceptable breakage on
|
||||
such short notice.
|
||||
|
||||
..
|
||||
|
|
Loading…
Reference in a new issue