Usage

To use libsaas, you first create a service object and then use the method it provides to send and fetch data from a software as a service API.

With libsaas you always work with Python objects, serialization of data sent and received is provided by the library. Here’s an example of using libsaas to check what’s the most watched repository from all people that follow you.

from __future__ import print_function

from libsaas.services import github

# use basic authentication to create a token for libsaas
basic = github.GitHub('me@example.org', 'my-github-password')

auth = basic.authorizations().create({'scopes': 'repo,gist',
                                      'note': 'libsaas example'})

# use token authentication for the rest of the calls
gh = github.GitHub(auth['token'])

# go through your followers
for follower in gh.user().followers():
    username = follower['login']

    # get the source repositories owned by each follower
    repos = gh.user(username).repos().get(type='owner')
    sources = [repo for repo in repos if not repo['fork']]

    # handle the case where a user has no repos
    if not sources:
        print("{0} has no repositories".format(username))
        continue

    # print the most watched repo of each follower, excluding forks
    most = sorted(sources, key=lambda repo: repo['watchers'])[-1]
    print("{0}'s most watched repository: {1}".format(username, most['name']))

Consulting original documentation

The most productive way to use libsaas is to keep the original API documentation and the libsaas documentation open side-by-side. Since every API has its own data format, the abstraction provided by libsaas ends at providing you with Python objects. You should refer to the original service documentation in order to fully interpret the results.

Combining services

Libsaas is most useful when you combine access to different services. This allows you to quickly create mashups without worrying about all the little quirks of each API. Here’s how you’d get the tickets solved yesterday in your Zendesk and accordingly tag users who reported those tickets in Mailchimp.

You could then run this script nightly and create an automatic mailing campaign to send quality surveys to users who’s tickets have been solved recently.

from datetime import datetime, timedelta

from libsaas.services import mailchimp, zendesk

# create Zendesk and Mailchimp services
zd = zendesk.Zendesk('mycompany', 'username', 'password')
mc = mailchimp.Mailchimp('8ac789caf98879caf897a678fa76daf-us2')

# get tickets solved yesterday
yesterday = (datetime.now() - timedelta(days=1)).strftime('%Y-%m-%d')
tickets = zd.search('updated>{0} status:solved type:ticket'.format(yesterday))

# get emails of users who requested those tickets
user_ids = [ticket['requester_id'] for ticket in tickets['results']]
emails = [zd.user(user_id).get()['user']['email'] for user_id in user_ids]

# grab the ID of the "Users" list
lists = mc.lists(filters={'list_name': 'Users'})
list_id = lists['data'][0]['id']

# set the SOLVED variable for those users in Mailchimp to yesterday
batch = [{'EMAIL': email, 'SOLVED': yesterday} for email in emails]
mc.listBatchSubscribe(list_id, batch, double_optin=False, update_existing=True)

Pluggable executors

Everything out there uses HTTP, but there’s more than one way to skin a request. By default libsaas uses Python’s standard urllib2 to make HTTP requests, but it provides a few other executor modules and you can even plug in your own.

Here’s an example of using the Requests executor in order to add a user agent and a timeout every time libsaas makes a HTTP request. The example code will unstar all gists a user has previously starred.

import libsaas
from libsaas.executors import requests_executor
from libsaas.services import github

# use the Requests executor with a custom timeout and make it always send a
# user agent string
uastring = 'libsaas {0}'.format(libsaas.__versionstr__)

requests_executor.use(timeout=5.0,
                      config={'base_headers': {'User-agent': uastring}})

# unstar all starred gists
gh = github.GitHub('my-github-token')

for gist in gh.gists().starred():
    gh.gist(gist['id']).unstar()

Another executor included in libsaas is the Twisted executor that makes it easy to integrate libsaas in Twisted programs. When using the Twisted executor, libsaas will return Deferreds that will fire with the fetched data.

The saas script

If you want to quickly interact with a SaaS API, you can use the saas command line program. It can execute any method provided by libsaas and has some limited discoverability features.

To use it, call it with the desired service as the first argument, followed by the service parameters and the path to the method you want to call.

This means that code like this:

>>> from libsaas.services import zendesk
>>> service = zendesk.Zendesk('myapp', 'myuser', 's3cr3t')
>>> service.user(364).tickets_requested()

Translates to:

$ saas zendesk --subdomain=myapp --username=myuser --password=s3cr3t \
    user 364 tickets_requested

The saas script can also choose executors and output some debugging information while executing:

$ saas mailchimp --api_key=8ac789caf98879caf897a678fa76daf-us2 \
    --executor requests campaignContent 8df731

Another useful feature is that saas will try to interpret every parameter as JSON, making it easier to use methods that need Python dictionaries:

$ saas github --token_or_password=my-gh-token \
    gist 125342 update '{"description": "my gist"}'