Changeset 391 for python/trunk/Doc/library/urllib.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/urllib.rst (modified) (11 diffs)

python/trunk/Doc/library/urllib.rst

@@ -7 +7 @@
 .. note::
     The :mod:`urllib` module has been split into parts and renamed in
-    Python 3.0 to :mod:`urllib.request`, :mod:`urllib.parse`,
+    Python 3 to :mod:`urllib.request`, :mod:`urllib.parse`,
     and :mod:`urllib.error`. The :term:`2to3` tool will automatically adapt
-    imports when converting your sources to 3.0.
+    imports when converting your sources to Python 3.
     Also note that the :func:`urllib.urlopen` function has been removed in
-    Python 3.0 in favor of :func:`urllib2.urlopen`.
+    Python 3 in favor of :func:`urllib2.urlopen`.
 
 .. index::
@@ -24 +24 @@
 reading, and no seek operations are available.
 
+.. warning:: When opening HTTPS URLs, it does not attempt to validate the
+   server certificate.  Use at your own risk!
+
+
 High-level interface
 --------------------
@@ -29 +33 @@
 .. function:: urlopen(url[, data[, proxies]])
 
-   Open a network object denoted by a URL for reading.  If the URL does not have a
-   scheme identifier, or if it has :file:`file:` as its scheme identifier, this
-   opens a local file (without universal newlines); otherwise it opens a socket to
-   a server somewhere on the network.  If the connection cannot be made the
-   :exc:`IOError` exception is raised.  If all went well, a file-like object is
-   returned.  This supports the following methods: :meth:`read`, :meth:`readline`,
-   :meth:`readlines`, :meth:`fileno`, :meth:`close`, :meth:`info`, :meth:`getcode` and
-   :meth:`geturl`.  It also has proper support for the :term:`iterator` protocol. One
-   caveat: the :meth:`read` method, if the size argument is omitted or negative,
-   may not read until the end of the data stream; there is no good way to determine
+   Open a network object denoted by a URL for reading.  If the URL does not
+   have a scheme identifier, or if it has :file:`file:` as its scheme
+   identifier, this opens a local file (without :term:`universal newlines`);
+   otherwise it opens a socket to a server somewhere on the network.  If the
+   connection cannot be made the :exc:`IOError` exception is raised.  If all
+   went well, a file-like object is returned.  This supports the following
+   methods: :meth:`read`, :meth:`readline`, :meth:`readlines`, :meth:`fileno`,
+   :meth:`close`, :meth:`info`, :meth:`getcode` and :meth:`geturl`.  It also
+   has proper support for the :term:`iterator` protocol. One caveat: the
+   :meth:`read` method, if the size argument is omitted or negative, may not
+   read until the end of the data stream; there is no good way to determine
    that the entire stream from a socket has been read in the general case.
 
@@ -50 +55 @@
 
    The :meth:`info` method returns an instance of the class
-   :class:`httplib.HTTPMessage` containing meta-information associated with the
+   :class:`mimetools.Message` containing meta-information associated with the
    URL.  When the method is HTTP, these headers are those returned by the server
    at the head of the retrieved HTML page (including Content-Length and
@@ -128 +133 @@
 
    .. deprecated:: 2.6
-      The :func:`urlopen` function has been removed in Python 3.0 in favor
+      The :func:`urlopen` function has been removed in Python 3 in favor
       of :func:`urllib2.urlopen`.
 
@@ -164 +169 @@
 
       The *Content-Length* is treated as a lower bound: if there's more data  to read,
-      urlretrieve reads more data, but if less data is available,  it raises the
-      exception.
+      :func:`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.
 
-      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
-      to assume that the download was successful.
+      If no *Content-Length* header was supplied, :func:`urlretrieve` can not check
+      the size of the data it has downloaded, and just returns it.  In this case you
+      just have to assume that the download was successful.
 
 
@@ -207 +212 @@
    Replace special characters in *string* using the ``%xx`` escape. Letters,
    digits, and the characters ``'_.-'`` are never quoted. By default, this
-   function is intended for quoting the path section of the URL.The optional
+   function is intended for quoting the path section of the URL. The optional
    *safe* parameter specifies additional characters that should not be quoted
    --- its default value is ``'/'``.
@@ -237 +242 @@
 .. function:: urlencode(query[, doseq])
 
-   Convert a mapping object or a sequence of two-element tuples  to a "url-encoded"
-   string, suitable to pass to :func:`urlopen` above as the optional *data*
-   argument.  This is useful to pass a dictionary of form fields to a ``POST``
-   request.  The resulting string is a series of ``key=value`` pairs separated by
-   ``'&'`` characters, where both *key* and *value* are quoted using
-   :func:`quote_plus` above.  If the optional parameter *doseq* is present and
-   evaluates to true, individual ``key=value`` pairs are generated for each element
-   of the sequence. When a sequence of two-element tuples is used as the *query*
-   argument, the first element of each tuple is a key and the second is a value.
-   The order of parameters in the encoded string will match the order of parameter
-   tuples in the sequence. The :mod:`urlparse` module provides the functions
+   Convert a mapping object or a sequence of two-element tuples to a
+   "percent-encoded" string, suitable to pass to :func:`urlopen` above as the
+   optional *data* argument.  This is useful to pass a dictionary of form
+   fields to a ``POST`` request.  The resulting string is a series of
+   ``key=value`` pairs separated by ``'&'`` characters, where both *key* and
+   *value* are quoted using :func:`quote_plus` above.  When a sequence of
+   two-element tuples is used as the *query* argument, the first element of
+   each tuple is a key and the second is a value. The value element in itself
+   can be a sequence and in that case, if the optional parameter *doseq* is
+   evaluates to *True*, individual ``key=value`` pairs separated by ``'&'`` are
+   generated for each element of the value sequence for the key.  The order of
+   parameters in the encoded string will match the order of parameter tuples in
+   the sequence. The :mod:`urlparse` module provides the functions
    :func:`parse_qs` and :func:`parse_qsl` which are used to parse query strings
    into Python data structures.
@@ -261 +268 @@
 .. function:: url2pathname(path)
 
-   Convert the path component *path* from an encoded URL to the local syntax for a
+   Convert the path component *path* from an percent-encoded URL to the local syntax for a
    path.  This does not accept a complete URL.  This function uses :func:`unquote`
    to decode *path*.
@@ -269 +276 @@
 
    This helper function returns a dictionary of scheme to proxy server URL
-   mappings. It scans the environment for variables named ``<scheme>_proxy``
-   for all operating systems first, and when it cannot find it, looks for proxy
-   information from Mac OSX System Configuration for Mac OS X and Windows
-   Systems Registry for Windows.
+   mappings. It scans the environment for variables named ``<scheme>_proxy``,
+   in case insensitive way, for all operating systems first, and when it cannot
+   find it, looks for proxy information from Mac OSX System Configuration for
+   Mac OS X and Windows Systems Registry for Windows.
+
+.. note::
+    urllib also exposes certain utility functions like splittype, splithost and
+    others parsing url into various components. But it is recommended to use
+    :mod:`urlparse` for parsing urls than using these functions directly.
+    Python 3 does not expose these helper functions from :mod:`urllib.parse`
+    module.
 
 
@@ -446 +460 @@
   code will try to read it, fail with a 550 error, and then perform a directory
   listing for the unreadable file. If fine-grained control is needed, consider
-  using the :mod:`ftplib` module, subclassing :class:`FancyURLOpener`, or changing
+  using the :mod:`ftplib` module, subclassing :class:`FancyURLopener`, or changing
   *_urlopener* to meet your needs.