What follows are some examples of using BeanBag for various services.


GitHub’s REST API, using JSON for data and either HTTP Basic Auth or OAuth2 for authentication. Basic Auth is perfect for a command line app, since the user can just use their github account password directly.

The following example uses the github API to list everyone who’s starred one of your repos, and which repo it is that they’ve starred.

#!/usr/bin/env python

import beanbag.v1 as beanbag
import os
import requests

sess = requests.Session()
sess.auth = (os.environ["GITHUB_ACCT"], os.environ["GITHUB_PASS"])

github = beanbag.BeanBag("https://api.github.com/", session=sess)

myuser = github.user()
me = myuser["login"]
repos = github.users[me].repos()

repo = {}
who = {}

for r in repos:
    rn = r["name"]
    repo[rn] = github.repos[me][rn]()
    stars = github.repos[me][rn].stargazers()
    for s in stars:
        sn = s["login"]
        if sn not in who:
            who[sn] = set()

for w in sorted(who):
    print("%s:" % (w,))
    for rn in sorted(who[w]):
        print("  %s -- %s" % (rn, repo[rn]["description"]))


Twitter’s REST API is slightly more complicated. It still uses JSON, but requires OAuth 1.0a to be used for authentication. OAuth is designed primarily for webapps, where the application is controlled by a third party. In particular it is designed to allow an “application” to authenticate as “authorised by a particular user”, rather than allowing the application to directly authenticate itself as the user (eg, by using the user’s username and password directly, as we did above with github).

This in turn means that the application has to be able to identify itself. This is done by gaining “client credential”, in Twitter’s case via Twitter Apps.

The process of having an application to ask a user to provide a token that allows it to access Twitter on behalf of the user is encapsulated in the OAuth10aDance class. In the example below is subclassed in order to provide the Twitter-specific URLs that the user and application will need to visit in order to gain the right tokens to do the authentication. The obtain_creds() method is called, which will instruct the user to enter any necessary credentials, after which a Session object is created and setup to perform OAuth authentication using the provided credentials.

The final minor complication is that Twitter’s endpoints all end with ”.json”, which would be annoying to have to specify via beanbag (since ”.” is not a valid part of an attribute). The ext= keyword argument of the BeanBag constructor is used to supply this as the standard extension for all URLs in the Twitter API.

#!/usr/bin/env python

import beanbag
import requests

class OAuthDanceTwitter(beanbag.OAuth10aDance):
    req_token = "https://api.twitter.com/oauth/request_token"
    authorize = "https://api.twitter.com/oauth/authorize"
    acc_token = "https://api.twitter.com/oauth/access_token"

client_key, client_secret = (None, None)
user_key, user_secret = (None, None)

oauthDance = OAuthDanceTwitter(
        client_key=client_key, client_secret=client_secret,
        user_key=user_key, user_secret=user_secret)

session = requests.Session()
session.auth = oauthDance.oauth()

twitter = beanbag.BeanBag("https://api.twitter.com/1.1/", ext=".json",

myacct = twitter.account.settings()
me = myacct["screen_name"]
tweets = twitter.statuses.user_timeline(screen_name=me, count=7)
for tweet in tweets: