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