File: README.rst

package info (click to toggle)
python-restkit 4.1.3-2
  • links: PTS, VCS
  • area: main
  • in suites: wheezy
  • size: 1,864 kB
  • sloc: python: 5,950; makefile: 85; xml: 8; sh: 5
file content (189 lines) | stat: -rw-r--r-- 5,901 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
About
-----

Restkit is an HTTP resource kit for `Python <http://python.org>`_. It allows you to easily access to HTTP resource and build objects around it. It's the base of `couchdbkit <http://www.couchdbkit.org>`_ a Python `CouchDB <http://couchdb.org>`_ framework. 

Restkit is a full HTTP client using pure socket calls and its own HTTP parser. It's not based on httplib or urllib2. 

Installation
------------

Restkit requires Python 2.x superior to 2.5 and http-parser 0.5.3 or
sup.

To install restkit using pip you must make sure you have a
recent version of distribute installed::

    $ curl -O http://python-distribute.org/distribute_setup.py
    $ sudo python distribute_setup.py
    $ easy_install pip

To install or upgrade to the latest released version of restkit::

    $ pip install http-parser
    $ pip install restkit


Note: if you get an error on MacOSX try to install with the following
arguments::

    $ env ARCHFLAGS="-arch i386 -arch x86_64" pip install http-parser
  
Usage
=====

Perform HTTP call support  with `restkit.request`.
++++++++++++++++++++++++++++++++++++++++++++++++++

Usage example, get friendpaste page::

  from restkit import request
  resp = request('http://friendpaste.com')
  print resp.body_string()
  print resp.status_int
    
    
Create a simple Twitter Search resource
+++++++++++++++++++++++++++++++++++++++

Building a resource object is easy using `restkit.Resource` class. 
We use `simplejson <http://code.google.com/p/simplejson/>`_ to 
handle deserialisation of data.

Here is the snippet::

  from restkit import Resource

  try:
      import simplejson as json
  except ImportError:
      import json # py2.6 only
    
  class TwitterSearch(Resource):
    
      def __init__(self,  pool_instance=None, **kwargs):
          search_url = "http://search.twitter.com"
          super(TwitterSearch, self).__init__(search_url, follow_redirect=True, 
                                          max_follow_redirect=10,
                                          pool_instance=pool_instance,
                                          **kwargs)

      def search(self, query):
          return self.get('search.json', q=query)
        
      def request(self, *args, **kwargs):
          resp = super(TwitterSearch, self).request(*args, **kwargs)
          return json.loads(resp.body_string())
        
  if __name__ == "__main__":
      s = TwitterSearch()
      print s.search("gunicorn")

Reuses connections
------------------

Reusing connections is good. Restkit can maintain for you the http connections and
reuse them if the server allows it. To do that you can pass to any object a pool 
instance inheriting `reskit.pool.PoolInterface`. By default a threadsafe pool is
used in any application:

::

    from restkit import *
    from socketpool import ConnectionPool
     
    # set a pool 
    pool = ConnectionPool(factory=Connection, max_size=10)

    # do the connection
    res = Resource('http://friendpaste.com', pool=pool)


or if you use `Gevent <http://gevent.org>`_:

::

    from restkit import *
    from socketpool import ConnectionPool
     
    # set a pool 
    pool = ConnectionPool(factory=Connection, backend="gevent",
                    max_size=10)

    # do the connection
    res = Resource('http://friendpaste.com', pool=pool)


Authentication
==============

Restkit support for now `basic authentication`_  and `OAuth`_. But any
other authentication schema can easily be added using http filters.

Basic authentication
++++++++++++++++++++


To use `basic authentication` in a `Resource object` you can do::

  from restkit import Resource, BasicAuth
 
  auth = BasicAuth("username", "password")
  r = Resource("http://friendpaste.com", filters=[auth])
 
Or simply use an authentication url::

  r = Resource("http://username:password@friendpaste.com")
  
.. _basic authentification: http://www.ietf.org/rfc/rfc2617.txt
.. _OAuth: http://oauth.net/

OAuth
+++++

Restkit OAuth is based on `simplegeo python-oauth2 module <http://github.com/simplegeo/python-oauth2>`_ So you don't need other installation to use OAuth (you can also simply use `restkit.oauth2` module in your applications).
  
The OAuth filter `restkit.oauth2.filter.OAuthFilter` allow you to associate a consumer per resource (path). Initalize Oauth filter with::
      
          path, consumer, token, signaturemethod
          
`token` and `method signature` are optionnals. Consumer should be an instance of `restkit.oauth2.Consumer`, token an  instance of `restkit.oauth2.Token`  signature method an instance of `oauth2.SignatureMethod`  (`restkit.oauth2.Token` is only needed for three-legged requests.

The filter is appleid if the path match. It allows you to maintain different authorization per path. A wildcard at the indicate to the filter to match all path behind.

Example the rule `/some/resource/*` will match `/some/resource/other` and `/some/resource/other2`, while the rule `/some/resource` will only match the path `/some/resource`.

Simple client example:
~~~~~~~~~~~~~~~~~~~~~~

::

  from restkit import OAuthFilter, request
  import restkit.oauth2 as oauth

  # Create your consumer with the proper key/secret.
  consumer = oauth.Consumer(key="your-twitter-consumer-key", 
    secret="your-twitter-consumer-secret")

  # Request token URL for Twitter.
  request_token_url = "http://twitter.com/oauth/request_token"

  # Create our filter.
  auth = oauth.OAuthFilter('*', consumer)

  # The request.
  resp = request(request_token_url, filters=[auth])
  print resp.body_string()
  

If you want to add OAuth  to your `TwitterSearch` resource::

  # Create your consumer with the proper key/secret.
  consumer = oauth.Consumer(key="your-twitter-consumer-key", 
    secret="your-twitter-consumer-secret")
    
  # Create our filter.
  client = oauth.OAuthfilter('*', consumer)
    
  s = TwitterSearch(filters=[client])