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.