Quickstart

Using a aiotapioca 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 aiotapioca-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 aiotapioca-package available.

What’s aiotapioca?

aiotapioca 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 aiotapioca here.

All wrappers made with aiotapioca follow a simple interaction pattern that works uniformly, so once you learn how aiotapioca works, you will be able to work with any aiotapioca package available.

Getting started

We will use aiotapioca-facebook as example to guide us through aiotapioca concepts. Let’s install aiotapioca-facebook:

$ pip install aiotapioca-facebook

To better experience aiotapioca, 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 aiotapioca client:

from aiotapioca_facebook import Facebook

async with Facebook(access_token='{your_genereated_access_token}') as api:
        ...
# or

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 = await 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 = await api.user_likes(id='me').get()

for like in likes.data:
        print(like.id())

Items passed to the for loop will be wrapped in aiotapioca 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 aiohttp library to make requests so HTTP methods will work just the same (get()/post()/patch()/put()/delete()/head()/options()). The only difference is that we don’t need to pass a URL since aiotapioca will take care of this.

likes = await api.user_likes(id='me').get()

URL params

To pass query string parameters in the URL, you can use the `params` parameter:

likes = await 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
await api.user_feed(id='me').post(
        data={'message': 'I love tapiocas!! S2'})

Please read aiohttp for more detailed information about how to use HTTP methods.

Multiple requests

To perform multiple requests asynchronously, you can use batch methods (post_batch()/patch_batch()/put_batch()/delete_batch()):

# this will only work if you have a post to wall permission
await api.user_feed(id='me').post_batch(
        data=[
                {'message': 'I love tapiocas!! S2'},
                {'message': 'I love tapiocas too!!'},
                ...
        ])

Accessing raw data

Use data() to return data contained in the ProcessData object.

>>> likes = await 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 = await api.user_likes(id='me').get()

async for like in likes().pages():
        print(like.data.name())

This will keep fetching user likes until there are none left. Items passed to the for loop will be wrapped in aiotapioca 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:

async 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 = await 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 aiotapioca 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()