PK 8'DAjuA A slumber-v0.6.0/searchindex.jsSearch.setIndex({envversion:42,terms:{oper:3,all:1,code:3,just:[1,2,3],queri:3,consult:1,speedup:[0,2],rest:[0,2],own:1,baseseri:1,follow:[0,3],yet:0,digest:1,paramet:[0,1],current:1,onli:1,hold:3,depend:2,easi:[1,2],delet:[2,3],"true":3,api_kei:2,param:3,should:1,yaml:[0,1,2],add:3,content_typ:1,str:3,bounc:0,"case":3,"return":1,around:[0,3],get:3,fragment:3,pypi:2,auth:[1,2],framework:3,made:2,"new":2,resourc:[0,3],password:[1,2],"class":1,awai:0,python2:2,name:[1,3],level:2,list:3,upload:0,authent:0,patch:[1,2],provid:0,resource_nam:1,each:[1,3],resource1:2,page:0,mean:3,pleas:1,correct:3,set:[1,3],dump:1,myuser:1,bacon:2,idea:0,freenod:0,pickleseri:1,see:2,multipart:1,arg:3,home:1,orient:0,librari:0,out:1,index:0,power:[0,3],channel:0,open:1,primari:0,content:[1,2,3],jsonseri:1,outgo:3,slash:0,"import":[1,2],net:0,irc:0,method:[1,2],attribut:3,singl:2,kei:1,post:[1,2,3],gener:0,like:[1,2],bodi:3,"1639eb74e86717f410c640d2712557aac0e989c8":2,dictionari:1,put:[1,2,3],path:1,philip:1,come:1,valu:[1,3],box:1,pyyaml:[0,2,3],wai:[0,1],howev:1,tastypi:2,equal:3,filter:2,thing:3,instanc:1,act:0,mypass:1,chang:[1,2],principl:3,com:1,title__startswith:2,first:3,load:1,control:[1,3],via:1,directli:1,onc:1,modul:0,prefer:2,automat:3,append_slash:1,api:[0,1,2,3],suppli:1,instal:0,txt:1,assum:1,your:1,from:[1,3],helper:3,coupl:1,segment:3,support:1,two:0,wrapper:[0,3],custom:1,avail:2,start:0,json:[0,1,2,3],call:[1,3],breez:0,basic:[1,2,3],interfac:0,wat:2,type:[1,3],"final":[1,3],includ:1,"function":3,desir:0,option:0,form:1,search:0,ani:[1,2,3],part:3,togeth:3,particular:1,oauth:1,essenti:3,exactli:1,realli:3,those:1,must:1,shoot:0,conveni:0,join:3,"default":1,when:[1,3],request:[0,1,3],defin:1,note:[2,3],apikei:2,can:[1,2],behavior:1,could:2,def:1,connect:2,overrid:1,sai:[2,3],file:0,creat:1,applic:1,process:0,demo:2,"abstract":0,pass:[1,2,3],argument:1,accept:1,kwarg:[1,2,3],have:[0,1],pip:[0,2],incom:3,doe:3,well:1,string:[1,3],again:3,end:[1,3],simplejson:[0,2],want:[0,1,2],anoth:3,self:1,format:1,excel:0,same:[1,3],member:1,also:[1,2,3],other:3,which:[1,2,3],test:[0,1,2],instead:1,you:[0,1,2,3],simpl:3,mock:0,either:1,deseri:3,http:[1,2,3],thi:[1,2,3],usernam:[1,2],nest:[0,3],object:[0,1],fairli:3,user:2,mai:1,data:1,implement:1,resource2:2,built:3,handl:0,attempt:1,thu:1,credenti:1,inherit:1,django:2,pickl:1,portion:3,exampl:[1,2],allow:1,titl:2,yamlseri:1,get_content_typ:1},objtypes:{},objnames:{},filenames:["index","options","tutorial","howitworks"],titles:["Slumber documentation","Options","Getting Started with Slumber","How Slumber Works Behind the Scenes"],objects:{},titleterms:{help:0,scene:3,indic:0,file:1,tabl:0,instal:2,serial:[1,3],paramet:2,start:2,how:3,behind:3,slash:1,document:0,resourc:2,option:1,get:[0,2],python:3,nest:2,specifi:1,translat:3,requir:0,quickstart:0,slumber:[0,2,3],work:3,upload:1,authent:1,url:[2,3]}})PK 8'D= A slumber-v0.6.0/search.html
Slumber comes with only a couple options.
Out of the box Slumber should support any authentication method supported by requests. These include Basic, Digest, OAuth. However only Basic and Digest get tested currently.
Specifying authentication credentials is easy. When you create your slumber api instance, instead of doing:
api = slumber.API("http://path/to/my/api/")
You supply the username and password (for Basic Auth) like:
api = slumber.API("http://path/to/my/api/", auth=("myuser", "mypass"))
And slumber will attempt to use those credentials with each request.
To Use Digest or OAuth please consult the requests documentation. The auth argument is passed directly to requests and thus works exactly the same way and accepts exactly the same arguments.
You may upload files by supplying a dictionary in the form {‘key’: file-like-object} as the value of the files parameter in post, patch or put calls. E.g.:
with open('/home/philip/out.txt') as fp:
api.file.post({'name': 'my file'}, files={'file': fp})
Will do a POST to /api/file/ with a multipart-form-data request.
Slumber allows you to use any serialization you want. It comes with json and yaml but creating your own is easy. By default it will attempt to use json. You can change the default by specifying a format argument to your api class.:
# Use Yaml instead of Json
api = slumber.API("http://path/to/my/api/", format="yaml")
If you want to override the serializer for a particular request, you can do that as well:
# Use Yaml instead of Json for just this request.
api = slumber.API("http://path/to/my/api/") # Serializer defaults to Json
api.resource_name(format="yaml").get() # Serializer will be Yaml
If you want to create your own serializer you can do so. A serialize inherits from slumber.serialize.BaseSerializer and implements loads, dumps. It also must have a class member of key which will be the string key for this serialization (such as “json”).The final requirement is either a class member of content_type which is the content type to use for requests (such as “application/json”) or define a get_content_type method.
An example:
class PickleSerializer(slumber.serialize.BaseSerializer):
key = "pickle"
content_type = "x-application/pickle"
def loads(self, data):
return pickle.loads(data)
def dumps(self, data):
return pickle.dumps(data)
Once you have a custom serializer you can pass it to slumber like so:
from slumber import serialize
import slumber
s = serialize.Serializer(
default="pickle",
serializers=[
serialize.JsonSerializer(),
serialize.YamlSerializer(),
PickleSerializer(),
]
)
api = slumber.API("http://example.com/api/v1/", format="pickle", serializer=s)
Slumber assumes by default that all urls should end with a slash. If you do not want this behavior you can control it via the append_slash option which can be set by passing append_slash to the slumber.API kwargs.
Behind the scenes slumber is really 2 things. It is a translator from python code into urls, and it is a serializer/deserializer helper.
The Url Translation portion of slumber is fairly simple but powerful. It is basically a list of url fragments that get joined together.
In the call:
>>> api.note.get()
Slumber translates this by adding the url value for api (say http://slumber.in/api/v1/) with the url value for note. The url value for an attribute is equal to it’s name, so in this case slumber essentially does "http://slumber.in/api/v1/" + "note",
The same holds true when you pass in an ID to a resource. It just adds another segment to the url list.
This means that in this call:
>>> api.note(1).get()
Slumber translates it to:
>>> "http://slumber.in/api/v1/" + "note" + "/" + str(1)
Nested Resources follow the same principle.
The other part of an url that Slumber translates is kwargs to get(), post(), put(), delete() into query string params. This again is a fairly simple operation which then gets added to the end of the url.
The Final portion of Slumber’s Python to HTTP is that the first arg passed to each of the HTTP functions is serialized, and then passed into the HTTP request as the body of the request.
Slumber also has a built in Serialization framework. This is a fairly simple wrapper around (simple)json and/or pyyaml that controls setting the correct content-type on a request, and will automatically serialize or deserialize any incoming or outgoing request body.
Slumber is available on PyPi and the preferred method of install is using Pip.
Install Slumber:
$ pip install slumber
Install Optional Dependencies
[OPTIONAL] PyYaml (Required for the yaml serializer):
$ pip install pyyaml
[OPTIONAL] SimpleJson (Required for the json serializer on Python2.5, or for speedups):
$ pip install simplejson
Using Slumber is easy. Using an example ReST API made with django-tastypie which you can see at http://slumber.in/api/v1/.
>>> import slumber
>>> ## Connect to http://slumber.in/api/v1/ with the Basic Auth user/password of demo/demo
>>> api = slumber.API("http://slumber.in/api/v1/", auth=("demo", "demo"))
>>> ## GET http://slumber.in/api/v1/note/
>>> ## Note: Any kwargs passed to get(), post(), put(), delete() will be used as url parameters
>>> api.note.get()
>>> ## POST http://slumber.in/api/v1/note/
>>> new = api.note.post({"title": "My Test Note", "content": "This is the content of my Test Note!"})
>>> ## PUT http://slumber.in/api/v1/note/{id}/
>>> api.note(new["id"]).put({"content": "I just changed the content of my Test Note!"})
>>> ## PATCH http://slumber.in/api/v1/note/{id}/
>>> api.note(new["id"]).patch({"content": "Wat!"})
>>> ## GET http://slumber.in/api/v1/note/{id}/
>>> api.note(new["id"]).get()
>>> ## DELETE http://slumber.in/api/v1/note/{id}/
>>> api.note(new["id"]).delete()
Passing an url parameter to Slumber is easy. If you wanted to say, use Tastypie’s ApiKey authentication, you could do so like:
>>> api.resource.get(username="example", api_key="1639eb74e86717f410c640d2712557aac0e989c8")
If you wanted to filter the Slumber demo api for notes that start with Bacon, you could do:
>>> import slumber
>>> api = slumber.API("http://slumber.in/api/v1/", auth=("demo", "demo"))
>>> ## GET http://slumber.in/api/v1/note/?title__startswith=Bacon
>>> api.note.get(title__startswith="Bacon")
Nested resources are also easy and works just how a single level resource works:
>>> ## GET /resource1/resource2/
>>> api.resource1.resource2.get()
>>> ## GET /resource1/1/resource2/
>>> api.resource1(1).resource2.get()
Slumber is a python library that provides a convenient yet powerful object orientated interface to ReSTful APIs. It acts as a wrapper around the excellent requests library and abstracts away the handling of urls, serialization, and processing requests.
There are two primary ways of getting help. I have an IRC channel (#slumber on irc.freenode.net) to get help, want to bounce idea or generally shoot the breeze.
Install Slumber:
$ pip install slumber
Install Optional Requirements:
pip install simplejson pyyaml
Use Slumber!
Slumber requires the following modules:
Testing Slumber requires the following modules: