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.
The BeanBag class does all the magic described above, using beanbag.namespace.
Create a BeanBag referencing a base REST path.
Parameters: |
|
---|
Set URL parameters
self == other
self.attr
self[attr]
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.
self != other
Human readable representation of object
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).
Functions are provided for the standard set of HTTP verbs.
GET verb function
HEAD verb function
POST verb function
PUT verb function
PATCH verb function
DELETE verb function
The verb function is used to create BeanBag compatible verbs. It is used as:
GET = verb("GET")
Construct a BeanBag compatible verb function
Parameters: | verbname – verb to use (GET, POST, etc) |
---|
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"}))
Bases: beanbag.attrdict.AttrDict
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.
Exception thrown when a BeanBag request fails.
You can get the original request via bbe.response.request.
Create a BeanBagException