flattrclient

Implementation of a python library for the flattr restful api


Keywords
flattr
License
Apache-2.0
Install
pip install flattrclient==0.2

Documentation

python-flattr

python-flattr is a client library to the micro payment service flattr. It implements most aspects of the flattr rest api. You may use it, to integrate flattr-Support into your python program. For example creating things for new blog posts. Or you write some kind of podcatcher and want to automatically flattr (support) each downloaded episode.

Features

  • create and update things
  • delete things
  • get things by id
  • search things
  • list things of a known user
  • list your things
  • list your subscriptions
  • subscribe to things
  • pause/resume subscriptions
  • flattr/support things

Installation

pip install flattr

Usage

DISCLAIMER: The following code examples are python3. If you are using python2, you have to pass unicodes especially to attributes of flattrclient.things.Thing.

First of all. You need to get an auth token. The implementation is up to you, with only little help of python-flattr.

Workflow to get the auth token

Follow the authorization workflow. First of all, register your app in your user profile on flattr, to get the Client ID and Client Secret.

With this credentials you can set up an api-connection

>>> import flattrclient.oauth
>>> auth_api = flattrclient.oauth.get()

You can call authorize to get the URL, you have to point your user to.

>>> auth_api.authorize(CLIENT_ID, 'flattr,thing,email,extendedread', 'http://localhost:8080')
'https://flattr.com/oauth/authorize?scope=flattr%2Cthing%2Cemail%2Cextendedread&redirect_uri=http%3A%2F%2Flocalhost%3A8080&response_type=code&client_id=CLIENT_ID'

However, you decide which scopes you need.

You may want to listen to localhost:8080 or whatever callback you used. flattr will redirect the user to this URL, and send you (on success), a code. Pick this up and get the access token. This is also the only time, you need the Client Secret.

>>> auth_api.set_auth(CLIENT_ID, CLIENT_SECRET)
>>> auth_api.token(CODE, 'http://localhost:8080')
'XXXXX'

The entire process of getting the code an requesting the token should not take too long. Anyway, it is still fast enough, if you copying the code from another terminal window and call token in an interactive session.

Working with python-flattr

In fact. The access token is the only thing you need to store somewhere. From now on. You should be able to talk to the flattr rest api. Give it a try and get all things of the user flattr

>>> import flattrclient.api
>>> api = flattrclient.api.get(AUTH_TOKEN)
>>> f = api.users('flattr')
>>> f
<flattrclient.user.User flattr>
>>> things = list(f.get_things())
[<flattrclient.things.Thing Bielefeld gibts wirklich! Zumindest im Fußball>,
 <flattrclient.things.Thing Tweet by @Flattr, 25 Feb>,
 ...]

That was fun. But what happened?

First, we introduced the session between flattr and us, using flattrclient.api.get. This is very likely always the first thing, you do. Currently I use requests.sessions.Session in the background, without any pooling.

Then we create a lightweight flattrclient.user.User-object. This does not perform any api-call. So if there is a typo, the next call (get_things), will cause the error. If you want, to perform an api-call for the user, use api.users.get('flattr').

The nect call to f.get_things() returns all things as a generator. So to make it more verbose here, we converted it into a list. All things? Not really. By default, the api only returns 30 results per page. But you can use count and page to override this.

>>> f.get_things(count=10, page=2)

You get page 2 of the results. Each page batched to 10 results.

Let's step back to the api. The api consits of a bunch of different other apis, to which the request.session.Session object is passed.

api.things: Talk to flattrs things api. get, lookup and search for things.

api.users: Talk to flattrs user api. __call__ and get, described above.

api.authenticated: Talk to flattrs authenticated api. Which means... list stuff of the authenticated user. get_activities, get_flattrs, get_things and get_subscriptions.

However. You may want to create a new thing on flattr.

>>> mything = api.things.new(url='http://example.com', title='crazy title')
>>> mything
<flattrclient.things.Thing craty title>
>>> mything.description = 'Some more context'
>>> mything.commit()

You should use api.things.new to get a new object of flattrclient.things.Thing because it again takes care of setting the session.

Same if you want to update one of your things.

>>> mythings = list(api.authenticated.get_things())
>>> some_thing = mythings[0]
>>> some_thing.title = 'Some new Title'
>>> some_thing.commit()

You may not just create or update your own things, but also flattr someones stuff. Each thing you got by user, or fetch via api.things is supportable.

>>> thing = api.things.get('4085245')
>>> thing
<flattrclient.things.Thing chrigl/python-flattr on GitHub>
>>> thing.support()
{...}

Just supporting is not enough? Subscribe to the thing

>>> thing = api.things.get('4085245')
>>> thing
<flattrclient.things.Thing chrigl/python-flattr on GitHub>
>>> thing.subscribe()
{...}

There is also a unsubscribe and a pause_subscription, which is a toggle to pause and resume this subscription.

Feel free to use help on different stuff. Where it is much more useful to use python3, since internaly some decorators are used, which results in *args, **kwargs-argument-lists in python2.

Issues

You are welcome to file issues or pull requests on github.

License

Apache License 2.0