Ignore:
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:
2 edited

Legend:

Unmodified
Added
Removed

  • python/trunk

  • python/trunk/Doc/library/urllib2.rst

    r2 r391  
    1010.. note::
    1111   The :mod:`urllib2` module has been split across several modules in
    12    Python 3.0 named :mod:`urllib.request` and :mod:`urllib.error`.
     12   Python 3 named :mod:`urllib.request` and :mod:`urllib.error`.
    1313   The :term:`2to3` tool will automatically adapt imports when converting
    14    your sources to 3.0.
     14   your sources to Python 3.
    1515
    1616
    … …  
    1919redirections, cookies and more.
    2020
     21
    2122The :mod:`urllib2` module defines the following functions:
    2223
    … …  
    2526
    2627   Open the URL *url*, which can be either a string or a :class:`Request` object.
     28
     29   .. warning::
     30      HTTPS requests do not do any verification of the server's certificate.
     31
     32   *data* may be a string specifying additional data to send to the server, or
     33   ``None`` if no such data is needed.  Currently HTTP requests are the only ones
     34   that use *data*; the HTTP request will be a POST instead of a GET when the
     35   *data* parameter is provided.  *data* should be a buffer in the standard
     36   :mimetype:`application/x-www-form-urlencoded` format.  The
     37   :func:`urllib.urlencode` function takes a mapping or sequence of 2-tuples and
     38   returns a string in this format. urllib2 module sends HTTP/1.1 requests with
     39   ``Connection:close`` header included.
     40
     41   The optional *timeout* parameter specifies a timeout in seconds for blocking
     42   operations like the connection attempt (if not specified, the global default
     43   timeout setting will be used).  This actually only works for HTTP, HTTPS and
     44   FTP connections.
     45
     46   This function returns a file-like object with two additional methods:
     47
     48   * :meth:`geturl` --- return the URL of the resource retrieved, commonly used to
     49     determine if a redirect was followed
     50
     51   * :meth:`info` --- return the meta-information of the page, such as headers,
     52     in the form of an :class:`mimetools.Message` instance
     53     (see `Quick Reference to HTTP Headers <http://www.cs.tut.fi/~jkorpela/http.html>`_)
     54
     55   * :meth:`getcode` --- return the HTTP status code of the response.
     56
     57   Raises :exc:`URLError` on errors.
     58
     59   Note that ``None`` may be returned if no handler handles the request (though the
     60   default installed global :class:`OpenerDirector` uses :class:`UnknownHandler` to
     61   ensure this never happens).
     62
     63   In addition, if proxy settings are detected (for example, when a ``*_proxy``
     64   environment variable like :envvar:`http_proxy` is set),
     65   :class:`ProxyHandler` is default installed and makes sure the requests are
     66   handled through the proxy.
     67
     68   .. versionchanged:: 2.6
     69      *timeout* was added.
     70
     71
     72.. function:: install_opener(opener)
     73
     74   Install an :class:`OpenerDirector` instance as the default global opener.
     75   Installing an opener is only necessary if you want urlopen to use that opener;
     76   otherwise, simply call :meth:`OpenerDirector.open` instead of :func:`urlopen`.
     77   The code does not check for a real :class:`OpenerDirector`, and any class with
     78   the appropriate interface will work.
     79
     80
     81.. function:: build_opener([handler, ...])
     82
     83   Return an :class:`OpenerDirector` instance, which chains the handlers in the
     84   order given. *handler*\s can be either instances of :class:`BaseHandler`, or
     85   subclasses of :class:`BaseHandler` (in which case it must be possible to call
     86   the constructor without any parameters).  Instances of the following classes
     87   will be in front of the *handler*\s, unless the *handler*\s contain them,
     88   instances of them or subclasses of them: :class:`ProxyHandler` (if proxy
     89   settings are detected),
     90   :class:`UnknownHandler`, :class:`HTTPHandler`, :class:`HTTPDefaultErrorHandler`,
     91   :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`,
     92   :class:`HTTPErrorProcessor`.
     93
     94   If the Python installation has SSL support (i.e., if the :mod:`ssl` module can be imported),
     95   :class:`HTTPSHandler` will also be added.
     96
     97   Beginning in Python 2.3, a :class:`BaseHandler` subclass may also change its
     98   :attr:`handler_order` attribute to modify its position in the handlers
     99   list.
     100
     101The following exceptions are raised as appropriate:
     102
     103
     104.. exception:: URLError
     105
     106   The handlers raise this exception (or derived exceptions) when they run into a
     107   problem.  It is a subclass of :exc:`IOError`.
     108
     109   .. attribute:: reason
     110
     111      The reason for this error.  It can be a message string or another exception
     112      instance (:exc:`socket.error` for remote URLs, :exc:`OSError` for local
     113      URLs).
     114
     115
     116.. exception:: HTTPError
     117
     118   Though being an exception (a subclass of :exc:`URLError`), an :exc:`HTTPError`
     119   can also function as a non-exceptional file-like return value (the same thing
     120   that :func:`urlopen` returns).  This is useful when handling exotic HTTP
     121   errors, such as requests for authentication.
     122
     123   .. attribute:: code
     124
     125      An HTTP status code as defined in `RFC 2616 <http://www.faqs.org/rfcs/rfc2616.html>`_.
     126      This numeric value corresponds to a value found in the dictionary of
     127      codes as found in :attr:`BaseHTTPServer.BaseHTTPRequestHandler.responses`.
     128
     129   .. attribute:: reason
     130
     131      The reason for this error.  It can be a message string or another exception
     132      instance.
     133
     134The following classes are provided:
     135
     136
     137.. class:: Request(url[, data][, headers][, origin_req_host][, unverifiable])
     138
     139   This class is an abstraction of a URL request.
     140
     141   *url* should be a string containing a valid URL.
    27142
    28143   *data* may be a string specifying additional data to send to the server, or
    … …  
    34149   returns a string in this format.
    35150
    36    The optional *timeout* parameter specifies a timeout in seconds for blocking
    37    operations like the connection attempt (if not specified, the global default
    38    timeout setting will be used).  This actually only works for HTTP, HTTPS,
    39    FTP and FTPS connections.
    40 
    41    This function returns a file-like object with two additional methods:
    42 
    43    * :meth:`geturl` --- return the URL of the resource retrieved, commonly used to
    44      determine if a redirect was followed
    45 
    46    * :meth:`info` --- return the meta-information of the page, such as headers, in
    47      the form of an ``httplib.HTTPMessage`` instance
    48      (see `Quick Reference to HTTP Headers <http://www.cs.tut.fi/~jkorpela/http.html>`_)
    49 
    50    Raises :exc:`URLError` on errors.
    51 
    52    Note that ``None`` may be returned if no handler handles the request (though the
    53    default installed global :class:`OpenerDirector` uses :class:`UnknownHandler` to
    54    ensure this never happens).
    55 
    56    In addition, default installed :class:`ProxyHandler` makes sure the requests
    57    are handled through the proxy when they are set.
    58 
    59    .. versionchanged:: 2.6
    60       *timeout* was added.
    61 
    62 
    63 .. function:: install_opener(opener)
    64 
    65    Install an :class:`OpenerDirector` instance as the default global opener.
    66    Installing an opener is only necessary if you want urlopen to use that opener;
    67    otherwise, simply call :meth:`OpenerDirector.open` instead of :func:`urlopen`.
    68    The code does not check for a real :class:`OpenerDirector`, and any class with
    69    the appropriate interface will work.
    70 
    71 
    72 .. function:: build_opener([handler, ...])
    73 
    74    Return an :class:`OpenerDirector` instance, which chains the handlers in the
    75    order given. *handler*\s can be either instances of :class:`BaseHandler`, or
    76    subclasses of :class:`BaseHandler` (in which case it must be possible to call
    77    the constructor without any parameters).  Instances of the following classes
    78    will be in front of the *handler*\s, unless the *handler*\s contain them,
    79    instances of them or subclasses of them: :class:`ProxyHandler`,
    80    :class:`UnknownHandler`, :class:`HTTPHandler`, :class:`HTTPDefaultErrorHandler`,
    81    :class:`HTTPRedirectHandler`, :class:`FTPHandler`, :class:`FileHandler`,
    82    :class:`HTTPErrorProcessor`.
    83 
    84    If the Python installation has SSL support (i.e., if the :mod:`ssl` module can be imported),
    85    :class:`HTTPSHandler` will also be added.
    86 
    87    Beginning in Python 2.3, a :class:`BaseHandler` subclass may also change its
    88    :attr:`handler_order` member variable to modify its position in the handlers
    89    list.
    90 
    91 The following exceptions are raised as appropriate:
    92 
    93 
    94 .. exception:: URLError
    95 
    96    The handlers raise this exception (or derived exceptions) when they run into a
    97    problem.  It is a subclass of :exc:`IOError`.
    98 
    99    .. attribute:: reason
    100 
    101       The reason for this error.  It can be a message string or another exception
    102       instance (:exc:`socket.error` for remote URLs, :exc:`OSError` for local
    103       URLs).
    104 
    105 
    106 .. exception:: HTTPError
    107 
    108    Though being an exception (a subclass of :exc:`URLError`), an :exc:`HTTPError`
    109    can also function as a non-exceptional file-like return value (the same thing
    110    that :func:`urlopen` returns).  This is useful when handling exotic HTTP
    111    errors, such as requests for authentication.
    112 
    113    .. attribute:: code
    114 
    115       An HTTP status code as defined in `RFC 2616 <http://www.faqs.org/rfcs/rfc2616.html>`_.
    116       This numeric value corresponds to a value found in the dictionary of
    117       codes as found in :attr:`BaseHTTPServer.BaseHTTPRequestHandler.responses`.
    118 
    119 
    120 
    121 The following classes are provided:
    122 
    123 
    124 .. class:: Request(url[, data][, headers][, origin_req_host][, unverifiable])
    125 
    126    This class is an abstraction of a URL request.
    127 
    128    *url* should be a string containing a valid URL.
    129 
    130    *data* may be a string specifying additional data to send to the server, or
    131    ``None`` if no such data is needed.  Currently HTTP requests are the only ones
    132    that use *data*; the HTTP request will be a POST instead of a GET when the
    133    *data* parameter is provided.  *data* should be a buffer in the standard
    134    :mimetype:`application/x-www-form-urlencoded` format.  The
    135    :func:`urllib.urlencode` function takes a mapping or sequence of 2-tuples and
    136    returns a string in this format.
    137 
    138151   *headers* should be a dictionary, and will be treated as if :meth:`add_header`
    139152   was called with each key and value as arguments.  This is often used to "spoof"
    … …  
    193206   dictionary mapping protocol names to URLs of proxies. The default is to read
    194207   the list of proxies from the environment variables
    195    :envvar:`<protocol>_proxy`.  If no proxy environment variables are set, in a
    196    Windows environment, proxy settings are obtained from the registry's
    197    Internet Settings section and in a Mac OS X  environment, proxy information
     208   :envvar:`<protocol>_proxy`.  If no proxy environment variables are set, then
     209   in a Windows environment proxy settings are obtained from the registry's
     210   Internet Settings section, and in a Mac OS X environment proxy information
    198211   is retrieved from the OS X System Configuration Framework.
    199212
    … …  
    291304
    292305   A catch-all class to handle unknown URLs.
     306
     307
     308.. class:: HTTPErrorProcessor()
     309
     310   Process HTTP error responses.
    293311
    294312
    … …  
    371389
    372390
     391.. method:: Request.get_header(header_name, default=None)
     392
     393   Return the value of the given header. If the header is not present, return
     394   the default value.
     395
     396
     397.. method:: Request.header_items()
     398
     399   Return a list of tuples (header_name, header_value) of the Request headers.
     400
     401
    373402.. method:: Request.set_proxy(host, type)
    374403
    … …  
    428457   optional *timeout* parameter specifies a timeout in seconds for blocking
    429458   operations like the connection attempt (if not specified, the global default
    430    timeout setting will be usedi). The timeout feature actually works only for
    431    HTTP, HTTPS, FTP and FTPS connections).
     459   timeout setting will be used). The timeout feature actually works only for
     460   HTTP, HTTPS and FTP connections).
    432461
    433462   .. versionchanged:: 2.6
    … …  
    465494
    466495   Note that the implementation of these methods may involve calls of the parent
    467    :class:`OpenerDirector` instance's :meth:`.open` and :meth:`.error` methods.
     496   :class:`OpenerDirector` instance's :meth:`~OpenerDirector.open` and
     497   :meth:`~OpenerDirector.error` methods.
    468498
    469499#. Every handler with a method named like :samp:`{protocol}_response` has that
    … …  
    490520   Remove any parents.
    491521
    492 The following members and methods should only be used by classes derived from
     522The following attributes and methods should only be used by classes derived from
    493523:class:`BaseHandler`.
    494524
    … …  
    876906
    877907
    878 .. method:: HTTPErrorProcessor.unknown_open()
     908.. method:: HTTPErrorProcessor.http_response()
    879909
    880910   Process HTTP error responses.
    … …  
    887917   :class:`urllib2.HTTPDefaultErrorHandler` will raise an :exc:`HTTPError` if no
    888918   other handler handles the error.
     919
     920.. method:: HTTPErrorProcessor.https_response()
     921
     922   Process HTTPS error responses.
     923
     924   The behavior is same as :meth:`http_response`.
    889925
    890926
Note: See TracChangeset for help on using the changeset viewer.