beanbag.v1 – Original-style REST API access¶
Setup:
>>> import beanbag.v1 as beanbag
>>> foo = beanbag.BeanBag("http://hostname/api/")
To do REST queries, then:
>>> r = foo.resource(p1=3.14, p2=2.718) # GET request
>>> r = foo.resource( {"a": 3, "b": 7} ) # POST request
>>> del foo.resource # DELETE request
>>> foo.resource = {"a" : 7, "b": 3} # PUT request
>>> foo.resource += {"a" : 7, "b": 3} # PATCH request
You can chain paths as well:
>>> print(foo.bar.baz[3]["xyzzy"].q)
http://hostname/api/foo/bar/baz/3/xyzzy/q
To do a request on a resource that requires a trailing slash:
>>> print(foo.bar._)
http://hostname/api/foo/bar/
>>> print(foo.bar[""])
http://hostname/api/foo/bar/
>>> print(foo.bar["/"])
http://hostname/api/foo/bar/
>>> print(foo["bar/"])
http://hostname/api/foo/bar/
>>> print(foo.bar._.x == foo.bar.x)
True
>>> print(foo.bar["_"])
http://hostname/api/foo/bar/_
To access REST interfaces that require authentication, you need to specify a session object. BeanBag supplies helpers to make Kerberos and OAuth 1.0a authentication easier.
To setup oauth using OAuth1 directly:
>>> import requests
>>> from requests_oauth import OAuth1
>>> session = requests.Session()
>>> session.auth = OAuth1( consumer creds, user creds )
>>> foo = beanbag.BeanBag("http://hostname/api/", session=session)
Using the OAuth10aDance
helper is probably a good plan though.
BeanBag class¶
-
class
beanbag.v1.
BeanBag
(base_url, ext='', session=None, fmt='json')¶ -
__init__
(base_url, ext='', session=None, fmt='json')¶ Create a BeanBag referencing a base REST path.
Parameters: - base_url – the base URL prefix for all resources
- ext – extension to add to resource URLs, eg “.json”
- session – requests.Session instance used for this API. Useful to set an auth procedure, or change verify parameter.
- fmt – either ‘json’ for json data, or a tuple specifying a content-type string, encode function (for encoding the request body) and a decode function (for decoding responses)
-
__call__
(*args, **kwargs)¶ Make a GET, POST or generic request to a resource.
Example: >>> x = BeanBag("http://host/api") >>> r = x() # GET request >>> r = x(p1='foo', p2=3) # GET request with parameters passed via query string >>> r = x( {'a': 1, 'b': 2} ) # POST request >>> r = x( "RANDOMIZE", {'a': 1, 'b': 2} ) # Custom HTTP verb with request body >>> r = x( "OPTIONS", None ) # Custom HTTP verb with empty request body
-
__delattr__
(attr)¶ del self.attr
-
__delitem__
(item)¶ del self[item]
-
__getattr__
(attr)¶ self.attr
-
__getitem__
(item)¶ self[attr]
-
__iadd__
(val)¶ Make a PATCH request to a resource.
Example: >>> x = BeanBag("http://host/api") >>> x += {"op": "replace", "path": "/a", "value": 3}
-
__setattr__
(attr, val)¶ self.attr = val
-
__setitem__
(item, val)¶ self[item] = val
-
__str__
()¶ Obtain the URL of a resource
-
BeanBagException¶
-
exception
beanbag.v1.
BeanBagException
(response, msg)¶ Exception thrown when a BeanBag request fails.
- Data members:
- msg – exception string, brief and human readable
- response – response object
You can get the original request via bbe.response.request.
-
__init__
(response, msg)¶ Create a BeanBagException
-
__repr__
()¶ Return repr(self).
-
__str__
()¶ Return str(self).