Quickstart¶
Using a tapioca package¶
Yes, you are in the right place
There is a good chance you found this page because you clicked a link from some python package called tapioca-SOMETHING. Well, welcome! You are in the right place. This page will teach you the basics of how to use the package that sent you here. If you didn’t arrive here from another package, then please keep reading. The concepts learned here apply to any tapioca-package available.
What’s tapioca?¶
tapioca is an API wrapper maker. It helps Python developers creating packages for APIs (like the Facebook Graph API or the Twitter REST API. You can find a full list of available API packages made with tapioca here.
All wrappers made with tapioca follow a simple interaction pattern that works uniformly, so once you learn how tapioca works, you will be able to work with any tapioca package available.
Getting started¶
We will use tapioca-facebook as example to guide us through tapioca concepts. Let’s install tapioca-facebook:
$ pip install tapioca-facebook
To better experience tapioca, we will also use IPython:
$ pip install ipython
Let’s explore!
Go to https://developers.facebook.com/tools/explorer/, click “Get Access Token”, select all “User Data Permissions” and “Extended Permissions”, and click “Get Access Token”. This will give you a temporary access token to play with Facebook API. In case it expires, just generate a new one.
TapiocaClient object¶
This is how you initialize your tapioca client:
from tapioca_facebook import Facebook
api = Facebook(access_token='{your_genereated_access_token}')
If you are using IPython, you can now list available endpoints by typing api. and pressing tab.
>>> api.
api.user_likes api.page_blocked api.page_locations
api.page_statuses api.user_applications_developer api.user_friends
api.user_invitable_friends api.user_photos api.user_videos
api.object api.page_conversations api.page_milestones
...
Resources¶
Those are the available endpoints for the Facebook API. As we can see, there is one called user_likes. Let’s take a closer look.
Type api.user_likes? and press enter.
In [3]: api.user_likes?
...
Docstring:
Automatic generated __doc__ from resource_mapping.
Resource: {id}/likes
Docs: https://developers.facebook.com/docs/graph-api/reference/v2.2/user/likes
As we can see, the user_likes resource requires an id to be passed to the URL. Let’s do it:
api.user_likes(id='me')
Fetching data¶
To request the current user likes, its easy:
likes = api.user_likes(id='me').get()
To print the returned data:
In [9]: likes().data
OUT [9]: {
'data': [...],
'paging': {...}
}
Exploring data¶
We can also explore the returned data using the IPython tab auto-complete:
In [9]: likes.
likes.data likes.paging
Iterating over data¶
You can iterate over returned data:
likes = api.user_likes(id='me').get()
for like in likes.data:
print(like.id().data)
Items passed to the for loop will be wrapped in tapioca so you still have access to all features.
TapiocaClientExecutor object¶
Whenever you make a “call” on a TapiocaClient, it will return an TapiocaClientExecutor object. You will use the executor every time you want to perform an action over data you possess.
We did this already when we filled the URL parameters for the user_like resource (calling it and passing the argument id='me'). In this new object, you will find many methods to help you play with the data available.
Here is the list of the methods available in a TapiocaClientExecutor:
Making requests¶
Tapioca uses the requests library to make requests so HTTP methods will work just the same (get()/post()/put()/delete()/head()/options()). The only difference is that we don’t need to pass a URL since tapioca will take care of this.
likes = api.user_likes(id='me').get()
URL params
To pass query string parameters in the URL, you can use the `params` parameter:
likes = api.user_likes(id='me').get(
params={'limit': 5})
This will return only 5 results.
Body data
If you need to pass data in the body of your request, you can use the `data` parameter. For example, let’s post a message to a Facebook wall:
# this will only work if you have a post to wall permission
api.user_feed(id='me').post(
data={'message': 'I love tapiocas!! S2'})
Please read requests for more detailed information about how to use HTTP methods.
Accessing raw data¶
Use data to return data contained in the Tapioca object.
>>> likes = api.user_likes(id='me').get()
>>> likes().data
{
'data': [...],
'paging': {...}
}
>>> # this will print only the array contained
>>> # in the 'data' field of the response
>>> likes.data().data
>>> [...]
Dynamically fetching pages¶
Many APIs use a paging concept to provide large amounts of data. This way, data is returned in multiple requests to avoid a single long request. Tapioca is built to provide an easy way to access paged data using the pages() method:
likes = api.user_likes(id='me').get()
for like in likes().pages():
print(like.name().data)
This will keep fetching user likes until there are none left. Items passed to the for loop will be wrapped in tapioca so you still have access to all features.
This method also accepts max_pages and max_items parameters. If both parameters are used, the for loop will stop after max_pages are fetched or max_items are yielded, whichever comes first:
for item in resp().pages(max_pages=2, max_items=40):
print(item)
# in this example, the for loop will stop after two pages are fetched or 40 items are yielded,
# whichever comes first.
Accessing wrapped data attributes¶
It’s possible to access wrapped data attributes on executor. For example, it’s possible to reverse a wrapped list:
likes = api.user_likes(id='me').get()
likes_list = likes.data
likes_list().reverse()
# items in the likes_list are now in reverse order
# but still wrapped in a tapioca object
Opening documentation in the browser¶
If you are accessing a resource, you can call open_docs to open the resource documentation in a browser:
api.user_likes().open_docs()