beanbag.v2 – REST API access¶
A quick example:
>>> from beanbag.v2 import BeanBag, GET
>>> gh = BeanBag("https://api.github.com/")
>>> watchers = GET(gh.repos.ajtowns.beanbag.watchers)
>>> for w in watchers:
... print(w.login)
Setup:
>>> import beanbag.v2 as beanbag
>>> from beanbag.v2 import GET, POST, PUT, PATCH, DELETE
>>> myapi = beanbag.BeanBag("http://hostname/api/")
To constuct URLs, you can use attribute-style access or dict-style access:
>>> print(myapi.foo)
http://hostname/api/foo
>>> print(myapi["bar"])
http://hostname/api/bar
You can chain paths as well:
>>> print(myapi.foo.bar["baz"][3].xyzzy)
http://hostname/api/foo/bar/baz/3/xyzzy
To do a request on a resource that requires a trailing slash:
>>> print(myapi.foo._)
http://hostname/api/foo/
>>> print(myapi.foo[""])
http://hostname/api/foo/
>>> print(myapi.foo["/"])
http://hostname/api/foo/
>>> print(myapi["foo/"])
http://hostname/api/foo/
>>> print(myapi.foo._.x == myapi.foo.x)
True
>>> print(myapi.foo["_"])
http://hostname/api/foo/_
You can add URL parameters using function calls:
>>> print(myapi.foo(a=1, b="foo"))
http://hostname/api/foo?a=1;b=foo
Finally, to actually do REST queries on these queries you can use the GET, POST, PUT, PATCH and DELETE functions. The first argument should be a BeanBag url, and the second argument (if provided) should be the request body, which will be json encoded before being sent. The return value is the request’s response (decoded from json).
>>> res = GET( foo.resource )
>>> res = POST( foo.resource, {"a": 12} )
>>> DELETE( foo.resource )
To access REST interfaces that require authentication, you need to specify a session object when instantiating the BeanBag initially. BeanBag supplies helpers to make Kerberos and OAuth 1.0a authentication easier.
BeanBag class¶
The BeanBag class does all the magic described above, using
beanbag.namespace
.
-
class
beanbag.v2.
BeanBag
(base_url, ext='', session=None, use_attrdict=True)¶ -
__init__
(base_url, ext='', session=None, use_attrdict=True)¶ 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.
- use_attrdict – if true,
decode()
will wrap dicts and lists in abeanbag.attrdict.AttrDict
for syntactic sugar.
-
__call__
(*args, **kwargs)¶ Set URL parameters
-
__eq__
(other)¶ self == other
-
__getattr__
(attr)¶ self.attr
-
__getitem__
(item)¶ self[attr]
-
__invert__
()¶ Provide access to the base/path via the namespace object
bb = BeanBag(...) base, path = ~bb.foo assert isinstance(base, BeanBagBase)
This is the little bit of glue needed so that it’s possible to call methods defined in BeanBagBase directly rather than just the operators BeanBag supports.
-
__ne__
(other)¶ self != other
-
__repr__
()¶ Human readable representation of object
-
__str__
()¶ Obtain the URL of a resource
-
This class can be subclassed. In particular, if you need to use something
other than JSON for requests or responses, subclassing BeanBagBase
and overriding the encode
and decode
methods is probably what you
want to do. One caveat: due to the way beanbag.namespace
works, if you
wish to invoke the parent classes method, you’ll usually need the parent
base class, accessed via ~BeanBag
or super(~SubClass, self)
.
HTTP Verbs¶
Functions are provided for the standard set of HTTP verbs.
-
beanbag.v2.
GET
(url, body=None)¶ GET verb function
-
beanbag.v2.
HEAD
(url, body=None)¶ HEAD verb function
-
beanbag.v2.
POST
(url, body=None)¶ POST verb function
-
beanbag.v2.
PUT
(url, body=None)¶ PUT verb function
-
beanbag.v2.
PATCH
(url, body=None)¶ PATCH verb function
-
beanbag.v2.
DELETE
(url, body=None)¶ DELETE verb function
The verb function is used to create BeanBag compatible verbs. It is used as:
GET = verb("GET")
-
beanbag.v2.
verb
(verbname)¶ Construct a BeanBag compatible verb function
Parameters: verbname – verb to use (GET, POST, etc)
Request¶
The Request
class serves as a place holder for arguments to
requests.Session.request
. Normally this is constructed from a dict
object passed to POST
or PUT
via json.dumps()
however a
Request
object can also be created by hand and passed in as the
body
parameter in a POST
or similar BeanBag
request. For
example to make a POST request with a body that isn’t valid JSON:
POST(bbexample.path.to.resource, Request(body="MAGIC STRING"))
This can be useful with GET requests as well, even though GET requests don’t have a body per se:
GET(bbexample.path.to.resource, Request(headers={"X-Magic": "String"}))
-
class
beanbag.v2.
Request
(**kwargs)¶ Bases:
beanbag.attrdict.AttrDict
-
__init__
(**kwargs)¶ Create a Request object
Request objects act as placeholders for the arguments to the requests() function of the requests.Session being used. They are used as the interface between the encode() and make_request() functions, and may also be used by the API caller.
NB: A Request object is only suitable for one use, as it may be modified in-place during the request. For this reason, __init__ makes a (shallow) copy of all the keyword arguments supplied rather than using them directly.
-
BeanBagException¶
-
exception
beanbag.v2.
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