blotre

Thin Python Blot're client.


Keywords
blotre, blot're, REST, oauth2
License
MIT
Install
pip install blotre==0.0.4

Documentation

Thin Python Blot're client.

Supports

  • Unauthenticated queries.
  • Authorization flows.
  • Exchange authorization code for creds.
  • Disposable client creation and redemption.
  • Authorized requests.
  • Automatic exchanges refresh token if available.
  • Easy disposable client creation for command line apps.

Examples

  • Plant're - Uses an disposable client app to upload plant soil moisutre readings to Blot're from a Raspberry Pi.

Client Creation

Basic Client Creation

To create a new client application after registering on Blot're.

import blotre

blotre.Blotre({
    'client_id': "Client id from Blot're",
    'client_secret': "Client secret from Blot're",
    'redirect_uri': "Redirect uri registed with Blot're",
})

You can also manually provide credentials to be used in requests

blotre.Blotre({ ... }, creds = {
    'access_token' = "token value",
    'refresh_token' = "optional, refresh token value"
})

Authorization Code Flow

The OAuth2 authorization code flow is the preferred method to obtain user authorization.

First create a new client using the information you registered with Blot're.

import blotre

client = blotre.Blotre({
    'client_id': "55614f0630042c617481d7c3",
    'client_secret': "YTY1Njg2MDctZTdjYy00ODlhLWFkNmYtNjkzYjI3N2M0MDRl",
    'redirect_uri': "http://localhost:50000",
})

Then, display the authorization page to the user

print client.get_authorization_url()

https://blot.re/v0/oauth2/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A50000&response_type=code&client_id=55614f0630042c617481d7c3

After the user has authorized and your app has the authorization code, you can exchange the code for credentials.

try:
    # Exchange the code for creds and update the current client
    client.redeem_authorization_code(returned_code)
    # Client is now authorized
except blotre.TokenEndpointError as e:
    # Something went wrong.
    print e

Basic Disposable Client Creation

Alternately, for simple applications you can use the Blot're disposable client authorization flow. This allows you to register a client application that can be authorized by at most one user.

import blotre

client = blotre.create_disposable({
    'name': "Toa*",
    'blurb': "The Pintrest of toast"
})

Now the user must redeem the code to authorized your app

print client.get_redeem_url()
print client.client.code

# Wait for user to redeem, and then
try:
    # Exchange the code for creds and update the current client
    client.redeem_onetime_code()
    # Client is now authorized
except blotre.TokenEndpointError as e:
    # Something went wrong.
    print e

Making Requests

Query operations do not require any user authorization:

import blotre

client = blotre.Blotre({})
print client.get_streams()

Successful operations return parsed JSON data. All operations also take a list of query parameters

client.get_streams({
    'query': 'toast'
})

Create, update, and delete operations all require client authorization.

try:
    client.create_stream({
        'name': 'Temperature'
        'uri': "toastmastergeneral/temperature"
    })
except blotre.RestError as e:
    print e # not authorized in this case

All the APIs are extremely simple and just forward to Blot're. This means that you are responsible for correctly formating the request.

try:
    client.create_stream({
        'name': 'A B C'
        'uri': "toastmastergeneral/a b c"
    })
except blotre.RestError as e:
    print e # Invalid uri, uri may not contains spaces
# Instead you must escape the uri client side first
name = 'A B C'
client.create_stream({
    'name': 
    'uri': client.join_uri('toastmastergeneral', name)
})

If the access_token has expired when you make a request and a refresh token is available, the client will silently attempt to exchange the refresh token and replay the request.

Disposable Command Line Apps

Disposable client apps are good for prototyping and hacking together simple applications. You can create a disposable app manually using blotre.create_disposable, but a helper for command line applications is also provided. This helper persists client data and prompts the user with instructions on how to authorized the disposable app.

Using it is simple:

import blotre

client = blotre.create_disposable_app({
    'name': "FaceToast",
    'blurb': "Your face on toast!"
})

Unlike create_disposable, this will look for existing client data in a file and make sure this client has valid credentials. If the creds are valid, no further steps are required. client can make authorized requests.

If no persisted creds are available or the client data has expired, a new disposable app is registred with Blot're. The user is then prompted to redeem the code and press enter once they have completed this. Once they do this, the client exchanges its secret for an access token and becomes authorized.

All this happens synchronously so client will always be authorized when it is returned, unless of course the user does not redeem the code. The credentials and client info are automatically persisted to a json file and can be picked up later.