The mygpoclient package

Submodules

mygpoclient.api module

class mygpoclient.api.EpisodeAction(podcast, episode, action, device=None, timestamp=None, started=None, position=None, total=None)

Bases: object

This class encapsulates an episode action

The mandatory attributes are: podcast - The feed URL of the podcast episode - The enclosure URL or GUID of the episode action - One of ‘download’, ‘play’, ‘delete’ or ‘new’

The optional attributes are: device - The device_id on which the action has taken place timestamp - When the action took place (in XML time format) started - The start time of a play event in seconds position - The current position of a play event in seconds total - The total time of the episode (for play events)

The attribute “position” is only valid for “play” action types.

VALID_ACTIONS = ('download', 'play', 'delete', 'new', 'flattr')
classmethod from_dictionary(d)
to_dictionary()
class mygpoclient.api.EpisodeActionChanges(actions, since)

Bases: object

Container for added episode actions

Attributes: actions - A list of EpisodeAction objects since - A timestamp value for use in future requests

exception mygpoclient.api.InvalidResponse

Bases: exceptions.Exception

class mygpoclient.api.MygPodderClient(username, password, root_url='http://gpodder.net', client_class=<class 'mygpoclient.json.JsonClient'>)

Bases: mygpoclient.simple.SimpleClient

gpodder.net API Client

This is the API client that implements both the Simple and Advanced API of gpodder.net. See the SimpleClient class for a smaller class that only implements the Simple API.

download_episode_actions(*args, **kwargs)

Downloads a list of EpisodeAction objects from the server

Returns a EpisodeActionChanges object with the list of new actions and a “since” timestamp that can be used for future calls to this method when retrieving episodes.

get_devices(*args, **kwargs)

Returns a list of this user’s PodcastDevice objects

The resulting list can be used to display a selection list to the user or to determine device IDs to pull the subscription list from.

get_favorite_episodes()

Returns a List of Episode Objects containing the Users favorite Episodes

get_settings(type, scope_param1=None, scope_param2=None)

Returns a Dictionary with the set settings for the type & specified scope

get_subscriptions(*args, **kwargs)

Get a list of subscriptions for a device

Returns a list of URLs (one per subscription) for the given device_id that reflects the current list of subscriptions.

Raises http.NotFound if the device does not exist.

pull_subscriptions(*args, **kwargs)

Downloads subscriptions since the time of the last update

The “since” parameter should be a timestamp that has been retrieved previously by a call to update_subscriptions or pull_subscriptions.

Returns a SubscriptionChanges object with two lists (one for added and one for removed podcast URLs) and a “since” value that can be used for future calls to this method.

put_subscriptions(*args, **kwargs)

Update a device’s subscription list

Sets the server-side subscription list for the device “device_id” to be equivalent to the URLs in the list of strings “urls”.

The device will be created if it does not yet exist.

Returns True if the update was successful, False otherwise.

set_settings(type, scope_param1, scope_param2, set={}, remove=[])

Returns a Dictionary with the set settings for the type & specified scope

update_device_settings(*args, **kwargs)

Update the description of a device on the server

This changes the caption and/or type of a given device on the server. If the device does not exist, it is created with the given settings.

The parameters caption and type are both optional and when set to a value other than None will be used to update the device settings.

Returns True if the request succeeded, False otherwise.

update_subscriptions(*args, **kwargs)

Update the subscription list for a given device.

Returns a UpdateResult object that contains a list of (sanitized) URLs and a “since” value that can be used for future calls to pull_subscriptions.

For every (old_url, new_url) tuple in the updated_urls list of the resulting object, the client should rewrite the URL in its subscription list so that new_url is used instead of old_url.

upload_episode_actions(*args, **kwargs)

Uploads a list of EpisodeAction objects to the server

Returns the timestamp that can be used for retrieving changes.

class mygpoclient.api.PodcastDevice(device_id, caption, type, subscriptions)

Bases: object

This class encapsulates a podcast device

Attributes: device_id - The ID used to refer to this device caption - A user-defined “name” for this device type - A valid type of podcast device (see VALID_TYPES) subscriptions - The number of podcasts this device is subscribed to

VALID_TYPES = ('desktop', 'laptop', 'mobile', 'server', 'other')
classmethod from_dictionary(d)
class mygpoclient.api.SubscriptionChanges(add, remove, since)

Bases: object

Container for subscription changes

Attributes: add - A list of URLs that have been added remove - A list of URLs that have been removed since - A timestamp value for use in future requests

class mygpoclient.api.UpdateResult(update_urls, since)

Bases: object

Container for subscription update results

Attributes: update_urls - A list of (old_url, new_url) tuples since - A timestamp value for use in future requests

mygpoclient.feeds module

class mygpoclient.feeds.FeedServiceResponse(feeds, last_modified, feed_urls)

Bases: list

Encapsulates the relevant data of a mygpo-feedservice response

get_feed(url)

Returns the parsed feed for the given URL

get_feeds()

Returns the parsed feeds in order of the initial request

class mygpoclient.feeds.FeedserviceClient(username=None, password=None, base_url='http://mygpo-feedservice.appspot.com')

Bases: mygpoclient.json.JsonClient

A special-cased JsonClient for mygpo-feedservice

build_url(**kwargs)

Parameter such as strip_html, scale_logo, etc are pased as kwargs

static format_header_date(datetime_obj)

Formats the given datetime object for use in HTTP headers

parse_feeds(feed_urls, last_modified=None, strip_html=False, use_cache=True, inline_logo=False, scale_logo=None, logo_format=None)

Passes the given feed-urls to mygpo-feedservice to be parsed and returns the response

static parse_header_date(date_str)

Parses dates in RFC2822 format to datetime objects

mygpoclient.http module

exception mygpoclient.http.BadRequest

Bases: exceptions.Exception

class mygpoclient.http.HttpClient(username=None, password=None)

Bases: object

A comfortable HTTP client

This class hides the gory details of the underlying HTTP protocol from the rest of the code by providing a simple interface for doing requests and handling authentication.

GET(uri)

Convenience method for carrying out a GET request

POST(uri, data)

Convenience method for carrying out a POST request

PUT(uri, data)

Convenience method for carrying out a PUT request

class mygpoclient.http.HttpRequest(url, data=None, headers={}, origin_req_host=None, unverifiable=False)

Bases: urllib2.Request

Request object with customizable method

The default behaviour of Request is unchanged:

>>> request = HttpRequest('http://example.org/')
>>> request.get_method()
'GET'
>>> request = HttpRequest('http://example.org/', data='X')
>>> request.get_method()
'POST'

However, it’s possible to customize the method name:

>>> request = HttpRequest('http://example.org/', data='X')
>>> request.set_method('PUT')
>>> request.get_method()
'PUT'
get_method()
set_method(method)
exception mygpoclient.http.NotFound

Bases: exceptions.Exception

class mygpoclient.http.SimpleHttpPasswordManager(username, password)

Bases: urllib2.HTTPPasswordMgr

Simplified password manager for urllib2

This class always provides the username/password combination that is passed to it as constructor argument, independent of the realm or authuri that is used.

MAX_RETRIES = 3
find_user_password(realm, authuri)
exception mygpoclient.http.Unauthorized

Bases: exceptions.Exception

exception mygpoclient.http.UnknownResponse

Bases: exceptions.Exception

mygpoclient.json module

class mygpoclient.json.JsonClient(username=None, password=None)

Bases: mygpoclient.http.HttpClient

A HttpClient with built-in JSON support

This client will automatically marshal and unmarshal data for JSON-related web services so that code using this class will not need to care about (de-)serialization of data structures.

static decode(data)

Decodes a response string to a Python object

>>> JsonClient.decode(b'')
>>> JsonClient.decode(b'[1,2,3]')
[1, 2, 3]
>>> JsonClient.decode(b'42')
42
static encode(data)

Encodes a object into its JSON string repesentation

>>> JsonClient.encode(None) is None
True
>>> JsonClient.encode([1,2,3]) == b'[1, 2, 3]'
True
>>> JsonClient.encode(42) == b'42'
True
exception mygpoclient.json.JsonException

Bases: exceptions.Exception

mygpoclient.locator module

class mygpoclient.locator.Locator(username, root_url='http://gpodder.net', version=2)

Bases: object

URI Locator for API endpoints

This helper class abstracts the URIs for the gpodder.net webservice and provides a nice facility for generating API URIs and checking parameters.

SETTINGS_TYPES = ('account', 'device', 'podcast', 'episode')
SIMPLE_FORMATS = ('opml', 'json', 'txt')
add_remove_subscriptions_uri(device_id)

Get the Advanced API URI for uploading list diffs

>>> locator = Locator('bill')
>>> locator.add_remove_subscriptions_uri('n810')
'http://gpodder.net/api/2/subscriptions/bill/n810.json'
device_list_uri()

Get the Advanced API URI for retrieving the device list

>>> locator = Locator('jeff')
>>> locator.device_list_uri()
'http://gpodder.net/api/2/devices/jeff.json'
device_settings_uri(device_id)

Get the Advanced API URI for setting per-device settings uploads

>>> locator = Locator('mike')
>>> locator.device_settings_uri('ipod')
'http://gpodder.net/api/2/devices/mike/ipod.json'
download_episode_actions_uri(since=None, podcast=None, device_id=None)

Get the Advanced API URI for downloading episode actions

The parameter “since” is optional and should be a numeric value (otherwise a ValueError is raised).

Both “podcast” and “device_id” are optional and exclusive:

“podcast” should be a podcast URL “device_id” should be a device ID

>>> locator = Locator('steve')
>>> locator.download_episode_actions_uri()
'http://gpodder.net/api/2/episodes/steve.json'
>>> locator.download_episode_actions_uri(since=1337)
'http://gpodder.net/api/2/episodes/steve.json?since=1337'
>>> locator.download_episode_actions_uri(podcast='http://example.org/episodes.rss')
'http://gpodder.net/api/2/episodes/steve.json?podcast=http%3A//example.org/episodes.rss'
>>> locator.download_episode_actions_uri(since=2000, podcast='http://example.com/')
'http://gpodder.net/api/2/episodes/steve.json?since=2000&podcast=http%3A//example.com/'
>>> locator.download_episode_actions_uri(device_id='ipod')
'http://gpodder.net/api/2/episodes/steve.json?device=ipod'
>>> locator.download_episode_actions_uri(since=54321, device_id='ipod')
'http://gpodder.net/api/2/episodes/steve.json?since=54321&device=ipod'
episode_data_uri(podcast_url, episode_url)

Get the Advanced API URI for retrieving Episode Data

>>> locator = Locator(None)
>>> locator.episode_data_uri('http://podcast.com','http://podcast.com/foo')
'http://gpodder.net/api/2/data/episode.json?podcast=http%3A//podcast.com&url=http%3A//podcast.com/foo'
favorite_episodes_uri()

Get the Advanced API URI for listing favorite episodes

>>> locator = Locator('mike')
>>> locator.favorite_episodes_uri()
'http://gpodder.net/api/2/favorites/mike.json'
podcast_data_uri(podcast_url)

Get the Advanced API URI for retrieving Podcast Data

>>> locator = Locator(None)
>>> locator.podcast_data_uri('http://podcast.com')
'http://gpodder.net/api/2/data/podcast.json?url=http%3A//podcast.com'
podcasts_of_a_tag_uri(tag, count=50)

Get the Advanced API URI for retrieving the top Podcasts of a Tag

>>> locator = Locator(None)
>>> locator.podcasts_of_a_tag_uri('linux')
'http://gpodder.net/api/2/tag/linux/50.json'
>>> locator.podcasts_of_a_tag_uri('linux',70)
'http://gpodder.net/api/2/tag/linux/70.json'
root_uri()

Get the server’s root URI.

>>> locator = Locator(None)
>>> locator.root_uri()
'http://gpodder.net'
search_uri(query, format='opml')

Get the Simple API URI for podcast search

>>> locator = Locator(None)
>>> locator.search_uri('outlaws')
'http://gpodder.net/search.opml?q=outlaws'
>>> locator.search_uri(':something?', 'txt')
'http://gpodder.net/search.txt?q=%3Asomething%3F'
>>> locator.search_uri('software engineering', 'json')
'http://gpodder.net/search.json?q=software+engineering'
settings_uri(type, scope_param1, scope_param2)

Get the Advanced API URI for retrieving or saving Settings

Depending on the Type of setting scope_param2 or scope_param1 and scope_param2 are not necessary.

>>> locator = Locator('joe')
>>> locator.settings_uri('account',None,None)
'http://gpodder.net/api/2/settings/joe/account.json'
>>> locator.settings_uri('device','foodevice',None)
'http://gpodder.net/api/2/settings/joe/device.json?device=foodevice'
>>> locator.settings_uri('podcast','http://podcast.com',None)
'http://gpodder.net/api/2/settings/joe/podcast.json?podcast=http%3A//podcast.com'
>>> locator.settings_uri('episode','http://podcast.com','http://podcast.com/foo')
'http://gpodder.net/api/2/settings/joe/episode.json?podcast=http%3A//podcast.com&episode=http%3A//podcast.com/foo'
subscription_updates_uri(device_id, since=None)

Get the Advanced API URI for downloading list diffs

The parameter “since” is optional and should be a numeric value (otherwise a ValueError is raised).

>>> locator = Locator('jen')
>>> locator.subscription_updates_uri('n900')
'http://gpodder.net/api/2/subscriptions/jen/n900.json'
>>> locator.subscription_updates_uri('n900', 1234)
'http://gpodder.net/api/2/subscriptions/jen/n900.json?since=1234'
subscriptions_uri(device_id=None, format='opml')

Get the Simple API URI for a subscription list

>>> locator = Locator('john')
>>> locator.subscriptions_uri('n800')
'http://gpodder.net/subscriptions/john/n800.opml'
>>> locator.subscriptions_uri('ipod', 'txt')
'http://gpodder.net/subscriptions/john/ipod.txt'
suggestions_uri(count=10, format='opml')

Get the Simple API URI for user suggestions

>>> locator = Locator('john')
>>> locator.suggestions_uri()
'http://gpodder.net/suggestions/10.opml'
>>> locator.suggestions_uri(50)
'http://gpodder.net/suggestions/50.opml'
>>> locator.suggestions_uri(70, 'json')
'http://gpodder.net/suggestions/70.json'
toplist_uri(count=50, format='opml')

Get the Simple API URI for the toplist

>>> locator = Locator(None)
>>> locator.toplist_uri()
'http://gpodder.net/toplist/50.opml'
>>> locator.toplist_uri(70)
'http://gpodder.net/toplist/70.opml'
>>> locator.toplist_uri(10, 'json')
'http://gpodder.net/toplist/10.json'
toptags_uri(count=50)

Get the Advanced API URI for retrieving the top Tags

>>> locator = Locator(None)
>>> locator.toptags_uri()
'http://gpodder.net/api/2/tags/50.json'
>>> locator.toptags_uri(70)
'http://gpodder.net/api/2/tags/70.json'
upload_episode_actions_uri()

Get the Advanced API URI for uploading episode actions

>>> locator = Locator('thp')
>>> locator.upload_episode_actions_uri()
'http://gpodder.net/api/2/episodes/thp.json'

mygpoclient.public module

class mygpoclient.public.Episode(title, url, podcast_title, podcast_url, description, website, released, mygpo_link)

Bases: object

Container Class for Episodes

Attributes: title - url - podcast_title - podcast_url - description - website - released - mygpo_link -

REQUIRED_KEYS = ('title', 'url', 'podcast_title', 'podcast_url', 'description', 'website', 'released', 'mygpo_link')
classmethod from_dict(d)
class mygpoclient.public.PublicClient(root_url='http://gpodder.net', client_class=<class 'mygpoclient.json.JsonClient'>)

Bases: object

Client for the gpodder.net “anonymous” API

This is the API client implementation that provides a pythonic interface to the parts of the gpodder.net Simple API that don’t need user authentication.

FORMAT = 'json'
get_episode_data(podcast_uri, episode_uri)

Get Metadata for the specified Episode

Returns a Episode object.

The parameter “podcast_uri” specifies the URL of the Podcast, which this Episode belongs to

The parameter “episode_uri” specifies the URL of the Episode

get_podcast_data(podcast_uri)

Get Metadata for the specified Podcast

Returns a simple.Podcast object.

The parameter “podcast_uri” specifies the URL of the Podcast.

get_podcasts_of_a_tag(tag, count=50)

Get a list of most-subscribed podcasts of a Tag

Returns a list of simple.Podcast objects.

The parameter “tag” specifies the tag as a String

The parameter “count” is optional and describes the amount of podcasts that are returned. The default value is 50, the minimum value is 1 and the maximum value is 100.

get_toplist(count=50)

Get a list of most-subscribed podcasts

Returns a list of simple.Podcast objects.

The parameter “count” is optional and describes the amount of podcasts that are returned. The default value is 50, the minimum value is 1 and the maximum value is 100.

get_toptags(count=50)

Get a list of most-used tags

Returns a list of Tag objects.

The parameter “count” is optional and describes the amount of podcasts that are returned. The default value is 50, the minimum value is 1 and the maximum value is 100.

search_podcasts(query)

Search for podcasts on the webservice

Returns a list of simple.Podcast objects.

The parameter “query” specifies the search query as a string.

class mygpoclient.public.Tag(tag, usage)

Bases: object

Container class for a tag in the top tag list

Attributes: tag - The name of the tag usage - Usage of the tag

REQUIRED_KEYS = ('tag', 'usage')
classmethod from_dict(d)

mygpoclient.simple module

exception mygpoclient.simple.MissingCredentials

Bases: exceptions.Exception

Raised when instantiating a SimpleClient without credentials

class mygpoclient.simple.Podcast(url, title, description, website, subscribers, subscribers_last_week, mygpo_link, logo_url)

Bases: object

Container class for a podcast

Encapsulates the metadata for a podcast.

Attributes: url - The URL of the podcast feed title - The title of the podcast description - The description of the podcast

REQUIRED_FIELDS = ('url', 'title', 'description', 'website', 'subscribers', 'subscribers_last_week', 'mygpo_link', 'logo_url')
classmethod from_dict(d)
class mygpoclient.simple.SimpleClient(username, password, root_url='http://gpodder.net', client_class=<class 'mygpoclient.json.JsonClient'>)

Bases: object

Client for the gpodder.net Simple API

This is the API client implementation that provides a pythonic interface to the gpodder.net Simple API.

FORMAT = 'json'
get_subscriptions(*args, **kwargs)

Get a list of subscriptions for a device

Returns a list of URLs (one per subscription) for the given device_id that reflects the current list of subscriptions.

Raises http.NotFound if the device does not exist.

get_suggestions(*args, **kwargs)

Get podcast suggestions for the user

Returns a list of Podcast objects that are to be suggested to the user.

The parameter count is optional and if specified has to be a value between 1 and 100 (with 10 being the default), and determines how much search results are returned (at maximum).

locator

read-only access to the locator

put_subscriptions(*args, **kwargs)

Update a device’s subscription list

Sets the server-side subscription list for the device “device_id” to be equivalent to the URLs in the list of strings “urls”.

The device will be created if it does not yet exist.

Returns True if the update was successful, False otherwise.

mygpoclient.simple.needs_credentials(f)

apply to all methods that initiate requests that require credentials

mygpoclient.testing module

class mygpoclient.testing.FakeJsonClient

Bases: object

Fake implementation of a JsonClient used for testing

Set the response using response_value and check the list of requests this object got using the requests list.

GET(uri)
POST(uri, data)
PUT(uri, data)

mygpoclient.util module

mygpoclient.util.datetime_to_iso8601(dt)

Convert a datetime to a ISO8601-formatted string

>>> datetime_to_iso8601(datetime.datetime(2009, 12, 29, 19, 25, 33))
'2009-12-29T19:25:33'
mygpoclient.util.iso8601_to_datetime(s)

Convert a ISO8601-formatted string to datetime

>>> iso8601_to_datetime('2009-12-29T19:25:33')
datetime.datetime(2009, 12, 29, 19, 25, 33)
>>> iso8601_to_datetime('2009-12-29T19:25:33.1')
datetime.datetime(2009, 12, 29, 19, 25, 33, 100000)
>>> iso8601_to_datetime('2009-12-29T19:25:33Z')
datetime.datetime(2009, 12, 29, 19, 25, 33)
>>> iso8601_to_datetime('xXxXxXxXxxxxXxxxXxx')
>>>
mygpoclient.util.join(*args)

Join separate URL parts to a full URL

mygpoclient.util.position_to_seconds(s)

Convert a position string to its amount of seconds

>>> position_to_seconds('00:00:01')
1
>>> position_to_seconds('00:01:00')
60
>>> position_to_seconds('01:00:00')
3600
>>> position_to_seconds('02:59:59')
10799
>>> position_to_seconds('100:00:00')
360000
mygpoclient.util.seconds_to_position(seconds)

Convert the amount of seconds to a position string

>>> seconds_to_position(1)
'00:00:01'
>>> seconds_to_position(60)
'00:01:00'
>>> seconds_to_position(60*60)
'01:00:00'
>>> seconds_to_position(59 + 60*59 + 60*60*2)
'02:59:59'
>>> seconds_to_position(60*60*100)
'100:00:00'

Module contents

gpodder.net API Client Library

This is mygpoclient, the gpodder.net API Client Library for Python.

mygpoclient.require_version(minimum_required)

Require a minimum version of the library

Returns True if the minimum library version constraint is satisfied, False otherwise. Use this to check for newer API methods and changes in the public API as described in NEWS.

>>> require_version('1.0')
True
>>> require_version('1.2')
True
>>> require_version(__version__)
True
>>> require_version('99.99')
False