gPodder

Web Services/API/Reference

From gPodderWiki

Jump to: navigation, search

This reference manual describes how to utilize the mygpoclient API Client Library to interface with the gpodder.net web service. The client library provides a well-tested implementation that adheres to the gpodder.net API Specification.

Contents

[edit] Preparation

This section describes how to obtain the source code and carry out basic tests to make sure your system has been set up correctly and all dependencies are fulfilled.

[edit] Getting the code

The code for the client library is hosted at http://repo.or.cz/w/mygpoclient.git. You can download the latest version of the code by using the command: 

git clone git://repo.or.cz/mygpoclient.git

[edit] Running Unit tests

To make sure that the library is working and all dependencies are installed, please install the dependencies listed in the DEPENDENCIES file. After that, you can easily run the unit tests that come with the library: 

make test

This will run all unit tests and doctests in the library. After the tests have been completed, you should get a summary with the test and code coverage statistics. The output should look like the following example if everything works (please note that the statement count could be different as development of the library continues): 

Name                  Stmts   Exec  Cover   Missing
---------------------------------------------------
mygpoclient               5      5   100%   
mygpoclient.api         155    155   100%   
mygpoclient.http         52     52   100%   
mygpoclient.json         22     22   100%   
mygpoclient.locator      52     52   100%   
mygpoclient.simple       16     16   100%   
mygpoclient.util         20     20   100%   
---------------------------------------------------
TOTAL                   322    322   100%
---------------------------------------------------
Ran 81 tests in 4.987s

[edit] Reading the module documentation

You can use the pydoc utility to read the documentation for the library. You probably want to use the following commands: 

pydoc mygpoclient.simple
pydoc mygpoclient.api

If you want, you can let Epydoc create the API documentation in the source tree: 

make docs

The resulting documentation will be created in the docs/ subdirectory.

A snapshot of the API documentation is available at:

[edit] Tutorial

This section gives a short how-to on how to use the library to interact with the web service.

[edit] The Simple API client (mygpoclient.simple.SimpleClient)

The SimpleClient class is the most basic way of interacting with the gpodder.net web service. You can use it to provide quick integration of an existing application or in cases where your client code has to be stateless. Please use the Advanced API client (which has a superset of SimpleClient's features) for more advanced use cases.

[edit] Importing the module

Make sure that the mygpoclient package is in your sys.path. You can set the PYTHONPATH environment variable to the Git checkout folder or add it to the sys.path list in Python. After that, you can import the simple module of the mygpoclient package: 

from mygpoclient import simple

[edit] Creating a SimpleClient instance

The client provides access to user-specific data, so you need to have the username and password of the user you want to authenticate as ready. Also, as gpodder.net is open source, and can potentially run on hosts different from gpodder.net, you can optionally provide the hostname.

Let's suppose we want to authenticate as user john and the password secret to the default web service (that's gpodder.net). To create a client object, we would use the following code: 

client = simple.SimpleClient('john', 'secret')

If you have the web service running on another host (for example on port 1337 on the local host or localhost), you can specify the host and port as third argument to the SimpleClient constructor (but you still need to provide username and password in this case): 

client = simple.SimpleClient('john', 'secret', 'localhost:1337')

[edit] Downloading subscription lists

You can download a list of podcast subscriptions with SimpleClient.get_subscriptions(device_id). The given device_id has to exist for the logged-in user. If the device does not exist, a mygpoclient.http.NotFound exception is thrown.

To download the subscription list of the device legacy, use: 

subscriptions = client.get_subscriptions('legacy')

The resulting list contains URLs of all the subscribed podcasts for this device: 

for url in subscriptions:
    print 'Subscribed to:', url

[edit] Uploading subscription lists

As with the download function, you can also upload subscriptions. For this, you need to use the SimpleClient.put_subscriptions(device_id, urls) function. The function returns True if the upload operation was successful, or False otherwise. An example usage would be like this: 

subscriptions = []
subscriptions.append('http://example.org/episodes.rss')
subscriptions.append('http://example.com/feeds/podcast.xml')
client.put_subscriptions('gpodder-example-device', subscriptions)

The existing list of subscriptions is always overwritten, and the user's subscription history will mark all podcasts that have been in the list before but have been removed from the uploaded subscription list as unsubscribed.

[edit] Putting it all together (complete example)

Now that we have discussed the basics, we can write a simple but feature-complete command-line application for downloading and uploading subscription lists (this code can also be found in the source tree as simple-client): 

import sys
import getpass

import mygpoclient

from mygpoclient import simple

def usage():
    print >>sys.stderr, """
    Usage: python %s {get|put} {username} {device_id} [host]
    """ % (sys.argv[0],)
    sys.exit(1)

if __name__ == '__main__':
    # Use the default host if not specified
    if len(sys.argv) == 4:
        sys.argv.append(mygpoclient.HOST)

    # Check for valid arguments
    if len(sys.argv) != 5:
        usage()

    # Split arguments in local variables
    progname, subcommand, username, device_id, host = sys.argv

    # Check for valid subcommand
    if subcommand not in ('get', 'put'):
        usage()

    # Read password from the terminal
    password = getpass.getpass("%s@%s's password: " % (username, host))

    # Create the client object with username/password/host set
    client = simple.SimpleClient(username, password, host)

    if subcommand == 'get':
        # Get the URL list and print it, one per line
        print '\n'.join(client.get_subscriptions(device_id))
    elif subcommand == 'put':
        # Read the URL list from standard input and upload it
        print >>sys.stderr, 'Enter podcast URLs, one per line.'
        urls = sys.stdin.read().splitlines()
        if client.put_subscriptions(device_id, urls):
            print >>sys.stderr, 'Upload successful.'
        else:
            print >>sys.stderr, 'Could not upload list.'

[edit] The Advanced API client (mygpoclient.api.MygPodderClient)

The api.MygPodderClient class inherits from simple.SimpleClient, so you can use both the Simple API and Advanced API functionality with this class.

[edit] Working with subscription lists

Given a device ID, you can update the list of subscriptions via the update_subscriptions() method. You need to pass a device_id and two lists (one for the URLs that have been added and one for the URLs that have been removed) to update the subscriptions on the server, for example: 

from mygpoclient import api

client = api.MygPodderClient('myusername', 'S3cr3tPassw0rd')

to_add = ['http://lugradio.org/episodes.rss']
to_remove = ['http://example.org/episodes.rss',
             'http://example.com/feed.xml']
result = client.update_subscriptions('abcdevice', to_add, to_remove)

You can use empty lists if you just add or remove items. As you can see in the code example, the function (if successful) returns a UpdateResult object. The UpdateResult object contains a "update_urls" attribute that is a list of (old_url, new_url) tuples in case the server has re-written URLs. According to the API documentation, the client application must update the old_url values with new_url values (these have been sanitized). The "since" attribute of the result object can be used for requesting changes since the last upload, like this: 

updates = client.pull_subscriptions('abcdevice', result.since)

The "updates" return value here is a SubscriptionChanges object that contains a new "since" attribute (that can be used for subsequent requests) and two lists ("add" and "remove") of URLs that should be processed by the client by creating and removing subscriptions.

[edit] Synchronizing episode actions

TODO

[edit] Enumerating and modifying devices

The api.MygPodderClient class provides two methods for dealing with devices: get_devices() (which returns a list of PodcastDevice objects) and update_device_settings() for modifying the device-specific settings on the server side. Here is an example script to use both functions to rename all users's device to "My Device" on the server: 

client = api.MygPodderClient('john', '53cr3t')

for device in client.get_devices():
    print 'Changing name of', device.device_id
    client.update_device_settings(device.device_id, caption='My Device')

[edit] The Public API client (mygpoclient.public.PublicClient)

This client does not need authentication and can be used to query and retrieve public data from the web service.

[edit] Toplist retrieval

You can use the get_toplist() method on a public.PublicClient instance to retrieve a list of podcast toplist entries: 

from mygpoclient import public

client = public.PublicClient()

toplist = client.get_toplist()
for index, entry in enumerate(toplist):
    print '%4d. %s (%d)' % (index+1, entry.title, entry.subscribers)

[edit] Searching for podcasts

Searching is done using the search_podcasts() method of public.PublicClient like this: 

from mygpoclient import public

client = public.PublicClient()

search_results = client.search_podcasts('outlaws')
for result in search_results:
    print result.title
    print result.url
    print '-'*50
Retrieved from "http://wiki.gpodder.org/wiki/Web_Services/API/Reference"
Personal tools