rest25/library/httplib.rst => rest262/library/httplib.rst
n1- 
2:mod:`httplib` --- HTTP protocol client
3=======================================
4
5.. module:: httplib
6   :synopsis: HTTP and HTTPS protocol client (requires sockets).
n6+ 
7+.. note::
8+   The :mod:`httplib` module has been renamed to :mod:`http.client` in Python
9+   3.0.  The :term:`2to3` tool will automatically adapt imports when converting
10+   your sources to 3.0.
7
8
9.. index::
10   pair: HTTP; protocol
11   single: HTTP; httplib (standard module)
12
13.. index:: module: urllib
14
25
26   The public interface for this module changed substantially in Python 2.0.  The
27   :class:`HTTP` class is retained only for backward compatibility with 1.5.2.  It
28   should not be used in new code.  Refer to the online docstrings for usage.
29
30The module provides the following classes:
31
32
n33-.. class:: HTTPConnection(host[, port])
n37+.. class:: HTTPConnection(host[, port[, strict[, timeout]]])
34
35   An :class:`HTTPConnection` instance represents one transaction with an HTTP
n36-   server.  It should be instantiated passing it a host and optional port number.
n40+   server.  It should be instantiated passing it a host and optional port
37-   If no port number is passed, the port is extracted from the host string if it
41+   number.  If no port number is passed, the port is extracted from the host
38-   has the form ``host:port``, else the default HTTP port (80) is used.  For
42+   string if it has the form ``host:port``, else the default HTTP port (80) is
43+   used.  When True, the optional parameter *strict* (which defaults to a false
44+   value) causes ``BadStatusLine`` to
45+   be raised if the status line can't be parsed as a valid HTTP/1.0 or 1.1
46+   status line.  If the optional *timeout* parameter is given, blocking
47+   operations (like connection attempts) will timeout after that many seconds
48+   (if it is not given, the global default timeout setting is used).
49+ 
39-   example, the following calls all create instances that connect to the server at
50+   For example, the following calls all create instances that connect to the server
40-   the same host and port::
51+   at the same host and port::
41
42      >>> h1 = httplib.HTTPConnection('www.cwi.nl')
43      >>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
44      >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
n56+      >>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)
45
n58+   .. versionadded:: 2.0
59+ 
46-   .. versionadded:: 2.0
60+   .. versionchanged:: 2.6
61+      *timeout* was added.
47
48
n49-.. class:: HTTPSConnection(host[, port, key_file, cert_file])
n64+.. class:: HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout]]]]])
50
51   A subclass of :class:`HTTPConnection` that uses SSL for communication with
52   secure servers.  Default port is ``443``. *key_file* is the name of a PEM
53   formatted file that contains your private key. *cert_file* is a PEM formatted
54   certificate chain file.
55
56   .. warning::
57
58      This does not do any certificate verification!
59
60   .. versionadded:: 2.0
61
n77+   .. versionchanged:: 2.6
78+      *timeout* was added.
79+ 
62
63.. class:: HTTPResponse(sock[, debuglevel=0][, strict=0])
64
65   Class whose instances are returned upon successful connection.  Not instantiated
66   directly by user.
67
68   .. versionadded:: 2.0
69
82
83   A subclass of :exc:`HTTPException`.
84
85   .. versionadded:: 2.0
86
87
88.. exception:: InvalidURL
89
n90-   A subclass of :exc:`HTTPException`, raised if a port is given and is either non-
n108+   A subclass of :exc:`HTTPException`, raised if a port is given and is either
91-   numeric or empty.
109+   non-numeric or empty.
92
93   .. versionadded:: 2.3
94
95
96.. exception:: UnknownProtocol
97
98   A subclass of :exc:`HTTPException`.
99
374.. _httpconnection-objects:
375
376HTTPConnection Objects
377----------------------
378
379:class:`HTTPConnection` instances have the following methods:
380
381
n382-.. method:: XXX Class.request(method, url[, body[, headers]])
n400+.. method:: HTTPConnection.request(method, url[, body[, headers]])
383
384   This will send a request to the server using the HTTP request method *method*
385   and the selector *url*.  If the *body* argument is present, it should be a
n386-   string of data to send after the headers are finished. The header Content-Length
n404+   string of data to send after the headers are finished. Alternatively, it may
405+   be an open file object, in which case the contents of the file is sent; this
406+   file object should support ``fileno()`` and ``read()`` methods. The header
387-   is automatically set to the correct value. The *headers* argument should be a
407+   Content-Length is automatically set to the correct value. The *headers*
388-   mapping of extra HTTP headers to send with the request.
408+   argument should be a mapping of extra HTTP headers to send with the request.
389
n410+   .. versionchanged:: 2.6
411+      *body* can be a file object.
390
n391-.. method:: XXX Class.getresponse()
n413+ 
414+.. method:: HTTPConnection.getresponse()
392
393   Should be called after a request is sent to get the response from the server.
394   Returns an :class:`HTTPResponse` instance.
395
396   .. note::
397
398      Note that you must have read the whole response before you can send a new
399      request to the server.
400
401
n402-.. method:: XXX Class.set_debuglevel(level)
n425+.. method:: HTTPConnection.set_debuglevel(level)
403
404   Set the debugging level (the amount of debugging output printed). The default
405   debug level is ``0``, meaning no debugging output is printed.
406
407
n408-.. method:: XXX Class.connect()
n431+.. method:: HTTPConnection.connect()
409
410   Connect to the server specified when the object was created.
411
412
n413-.. method:: XXX Class.close()
n436+.. method:: HTTPConnection.close()
414
415   Close the connection to the server.
416
417As an alternative to using the :meth:`request` method described above, you can
418also send your request step by step, by using the four functions below.
419
420
n421-.. method:: XXX Class.putrequest(request, selector[, skip_host[, skip_accept_encoding]])
n444+.. method:: HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]])
422
423   This should be the first call after the connection to the server has been made.
424   It sends a line to the server consisting of the *request* string, the *selector*
425   string, and the HTTP version (``HTTP/1.1``).  To disable automatic sending of
426   ``Host:`` or ``Accept-Encoding:`` headers (for example to accept additional
427   content encodings), specify *skip_host* or *skip_accept_encoding* with non-False
428   values.
429
430   .. versionchanged:: 2.4
431      *skip_accept_encoding* argument added.
432
433
n434-.. method:: XXX Class.putheader(header, argument[, ...])
n457+.. method:: HTTPConnection.putheader(header, argument[, ...])
435
436   Send an :rfc:`822`\ -style header to the server.  It sends a line to the server
437   consisting of the header, a colon and a space, and the first argument.  If more
438   arguments are given, continuation lines are sent, each consisting of a tab and
439   an argument.
440
441
n442-.. method:: XXX Class.endheaders()
n465+.. method:: HTTPConnection.endheaders()
443
444   Send a blank line to the server, signalling the end of the headers.
445
446
n447-.. method:: XXX Class.send(data)
n470+.. method:: HTTPConnection.send(data)
448
449   Send data to the server.  This should be used directly only after the
450   :meth:`endheaders` method has been called and before :meth:`getresponse` is
451   called.
452
453
454.. _httpresponse-objects:
455
456HTTPResponse Objects
457--------------------
458
459:class:`HTTPResponse` instances have the following methods and attributes:
460
461
n462-.. method:: XXX Class.read([amt])
n485+.. method:: HTTPResponse.read([amt])
463
464   Reads and returns the response body, or up to the next *amt* bytes.
465
466
n467-.. method:: XXX Class.getheader(name[, default])
n490+.. method:: HTTPResponse.getheader(name[, default])
468
469   Get the contents of the header *name*, or *default* if there is no matching
470   header.
471
472
n473-.. method:: XXX Class.getheaders()
n496+.. method:: HTTPResponse.getheaders()
474
475   Return a list of (header, value) tuples.
476
477   .. versionadded:: 2.4
478
479
n480-.. data:: msg
n503+.. attribute:: HTTPResponse.msg
481
482   A :class:`mimetools.Message` instance containing the response headers.
483
484
n485-.. data:: version
n508+.. attribute:: HTTPResponse.version
486
487   HTTP protocol version used by server.  10 for HTTP/1.0, 11 for HTTP/1.1.
488
489
n490-.. data:: status
n513+.. attribute:: HTTPResponse.status
491
492   Status code returned by server.
493
494
t495-.. data:: reason
t518+.. attribute:: HTTPResponse.reason
496
497   Reason phrase returned by server.
498
499
500.. _httplib-examples:
501
502Examples
503--------
Legends
Colors
 Added 
Changed
Deleted
Links
(f)irst change
(n)ext change
(t)op