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)¶
-
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
-
static
-
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'
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 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.
-
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¶
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