← Back to branch summary

~ubuntu-branches/ubuntu/precise/python-httplib2/precise-security

« back to all changes in this revision

Viewing changes to README

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Jahn
  • Date: 2006-10-11 08:39:48 UTC
  • Revision ID: james.westby@ubuntu.com-20061011083948-vhdyrq8x9925nnmo
Tags: upstream-0.2.0
Import upstream version 0.2.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
README
 
1
Httplib2
 
2
 
 
3
--------------------------------------------------------------------
 
4
Introduction
 
5
 
 
6
A comprehensive HTTP client library, httplib2.py supports many 
 
7
features left out of other HTTP libraries.
 
8
 
 
9
HTTP and HTTPS
 
10
    HTTPS support is only available if the socket module was 
 
11
    compiled with SSL support. 
 
12
Keep-Alive
 
13
    Supports HTTP 1.1 Keep-Alive, keeping the socket open and 
 
14
    performing multiple requests over the same connection if 
 
15
    possible. 
 
16
Authentication
 
17
    The following three types of HTTP Authentication are 
 
18
    supported. These can be used over both HTTP and HTTPS.
 
19
 
 
20
        * Digest
 
21
        * Basic
 
22
        * WSSE
 
23
 
 
24
Caching
 
25
    The module can optionally operate with a private cache that 
 
26
    understands the Cache-Control: header and uses both the ETag 
 
27
    and Last-Modified cache validators. 
 
28
All Methods
 
29
    The module can handle any HTTP request method, not just GET 
 
30
    and POST.
 
31
Redirects
 
32
    Automatically follows 3XX redirects on GETs.
 
33
Compression
 
34
    Handles both 'deflate' and 'gzip' types of compression.
 
35
Lost update support
 
36
    Automatically adds back ETags into PUT requests to resources 
 
37
    we have already cached. This implements Section 3.2 of 
 
38
    Detecting the Lost Update Problem Using Unreserved Checkout.
 
39
Unit Tested
 
40
    A large and growing set of unit tests. 
 
41
 
 
42
 
 
43
For more information on this module, see:
 
44
 
 
45
    http://bitworking.org/projects/httplib2/
 
46
 
 
47
 
 
48
--------------------------------------------------------------------
 
49
Installation
 
50
 
 
51
The httplib2 module is shipped as a distutils package.  To install
 
52
the library, unpack the distribution archive, and issue the following
 
53
command:
 
54
 
 
55
    $ python setup.py install
 
56
 
 
57
 
 
58
--------------------------------------------------------------------
 
59
Usage
 
60
A simple retrieval:
 
61
 
 
62
  import httplib2
 
63
  h = httplib2.Http(".cache")
 
64
  (resp_headers, content) = h.request("http://example.org/", "GET")
 
65
 
 
66
The 'content' is the content retrieved from the URL. The content 
 
67
is already decompressed or unzipped if necessary.
 
68
 
 
69
To PUT some content to a server that uses SSL and Basic authentication:
 
70
 
 
71
  import httplib2
 
72
  h = httplib2.Http(".cache")
 
73
  h.add_credentials('name', 'password')
 
74
  (resp, content) = h.request("https://example.org/chapter/2", 
 
75
                            "PUT", body="This is text", 
 
76
                            headers={'content-type':'text/plain'} )
 
77
 
 
78
Use the Cache-Control: header to control how the caching operates.
 
79
 
 
80
  import httplib2
 
81
  h = httplib2.Http(".cache")
 
82
  (resp, content) = h.request("http://bitworking.org/", "GET")
 
83
  ...
 
84
  (resp, content) = h.request("http://bitworking.org/", "GET", 
 
85
                            headers={'cache-control':'no-cache'})
 
86
 
 
87
The first request will be cached and since this is a request 
 
88
to bitworking.org it will be set to be cached for two hours, 
 
89
because that is how I have my server configured. Any subsequent 
 
90
GET to that URI will return the value from the on-disk cache 
 
91
and no request will be made to the server. You can use the 
 
92
Cache-Control: header to change the caches behavior and in 
 
93
this example the second request adds the Cache-Control: 
 
94
header with a value of 'no-cache' which tells the library 
 
95
that the cached copy must not be used when handling this request. 
 
96
 
 
97
 
 
98
--------------------------------------------------------------------
 
99
Httplib2 Software License
 
100
 
 
101
Copyright (c) 2006 by Joe Gregorio
 
102
 
 
103
Permission is hereby granted, free of charge, to any person 
 
104
obtaining a copy of this software and associated documentation 
 
105
files (the "Software"), to deal in the Software without restriction, 
 
106
including without limitation the rights to use, copy, modify, merge, 
 
107
publish, distribute, sublicense, and/or sell copies of the Software, 
 
108
and to permit persons to whom the Software is furnished to do so, 
 
109
subject to the following conditions:
 
110
 
 
111
The above copyright notice and this permission notice shall be 
 
112
included in all copies or substantial portions of the Software.
 
113
 
 
114
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 
 
115
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 
 
116
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 
 
117
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS 
 
118
BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 
 
119
ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 
 
120
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 
 
121
SOFTWARE.
 
122