Skip to content
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
622 lines (483 sloc) 20.5 KB
# -*- coding: utf-8 -*-
# gPodder - A media aggregator and podcast client
# Copyright (c) 2005-2009 Thomas Perl and the gPodder Team
# gPodder is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3 of the License, or
# (at your option) any later version.
# gPodder is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <>.
Loads and executes user extensions
Extensions are Python scripts in "$GPODDER_HOME/Extensions". Each script must
define a class named "gPodderExtension", otherwise it will be ignored.
The extensions class defines several callbacks that will be called by gPodder
at certain points. See the methods defined below for a list of callbacks and
their parameters.
For an example extension see share/gpodder/examples/
import functools
import glob
import imp
import inspect
import json
import logging
import os
import re
import shlex
import subprocess
import sys
from datetime import datetime
import gpodder
from gpodder import util
_ = gpodder.gettext
logger = logging.getLogger(__name__)
'desktop-integration': _('Desktop Integration'),
'interface': _('Interface'),
'post-download': _('Post download'),
def call_extensions(func):
"""Decorator to create handler functions in ExtensionManager
Calls the specified function in all user extensions that define it.
method_name = func.__name__
def handler(self, *args, **kwargs):
result = None
for container in self.containers:
if not container.enabled or container.module is None:
callback = getattr(container.module, method_name, None)
if callback is None:
# If the results are lists, concatenate them to show all
# possible items that are generated by all extension together
cb_res = callback(*args, **kwargs)
if isinstance(result, list) and isinstance(cb_res, list):
elif cb_res is not None:
result = cb_res
except Exception as exception:
logger.error('Error in %s in %s: %s', container.filename,
method_name, exception, exc_info=True)
func(self, *args, **kwargs)
return result
return handler
class ExtensionMetadata(object):
# Default fallback metadata in case metadata fields are missing
'description': _('No description for this extension.'),
'doc': None,
'payment': None,
'title': 1,
'description': 2,
'category': 3,
'authors': 4,
'only_for': 5,
'mandatory_in': 6,
'disable_in': 7,
def __init__(self, container, metadata):
if 'title' not in metadata:
metadata['title'] =
category = metadata.get('category', 'other')
metadata['category'] = CATEGORY_DICT.get(category, DEFAULT_CATEGORY)
def __getattr__(self, name):
return self.DEFAULTS[name]
except KeyError as e:
raise AttributeError(name, e)
def get_sorted(self):
def kf(x):
return self.SORTKEYS.get(x[0], 99)
return sorted([(k, v) for k, v in list(self.__dict__.items())], key=kf)
def check_ui(self, target, default):
"""Checks metadata information like
__only_for__ = 'gtk'
__mandatory_in__ = 'gtk'
__disable_in__ = 'gtk'
The metadata fields in an extension can be a string with
comma-separated values for UIs. This will be checked against
boolean variables in the "gpodder.ui" object.
Example metadata field in an extension:
__only_for__ = 'gtk'
__only_for__ = 'unity'
In this case, this function will return the value of the default
if any of the following expressions will evaluate to True:
New, unknown UIs are silently ignored and will evaluate to False.
if not hasattr(self, target):
return default
uis = [_f for _f in [x.strip() for x in getattr(self, target).split(',')] if _f]
return any(getattr(gpodder.ui, ui.lower(), False) for ui in uis)
def available_for_current_ui(self):
return self.check_ui('only_for', True)
def mandatory_in_current_ui(self):
return self.check_ui('mandatory_in', False)
def disable_in_current_ui(self):
return self.check_ui('disable_in', False)
class MissingDependency(Exception):
def __init__(self, message, dependency, cause=None):
Exception.__init__(self, message)
self.dependency = dependency
self.cause = cause
class MissingModule(MissingDependency): pass
class MissingCommand(MissingDependency): pass
class ExtensionContainer(object):
"""An extension container wraps one extension module"""
def __init__(self, manager, name, config, filename=None, module=None):
self.manager = manager = name
self.config = config
self.filename = filename
self.module = module
self.enabled = False
self.error = None
self.default_config = None
self.parameters = None
self.metadata = ExtensionMetadata(self, self._load_metadata(filename))
def require_command(self, command):
"""Checks if the given command is installed on the system
Returns the complete path of the command
@param command: String with the command name
result = util.find_command(command)
if result is None:
msg = _('Command not found: %(command)s') % {'command': command}
raise MissingCommand(msg, command)
return result
def require_any_command(self, command_list):
"""Checks if any of the given commands is installed on the system
Returns the complete path of first found command in the list
@param command: List with the commands name
for command in command_list:
result = util.find_command(command)
if result is not None:
return result
msg = _('Need at least one of the following commands: %(list_of_commands)s') % \
{'list_of_commands': ', '.join(command_list)}
raise MissingCommand(msg, ', '.join(command_list))
def _load_metadata(self, filename):
if not filename or not os.path.exists(filename):
return {}
encoding = util.guess_encoding(filename)
extension_py = open(filename, "r", encoding=encoding).read()
metadata = dict(re.findall("__([a-z_]+)__ = '([^']+)'", extension_py))
# Support for using gpodder.gettext() as _ to localize text
localized_metadata = dict(re.findall("__([a-z_]+)__ = _\('([^']+)'\)",
for key in localized_metadata:
metadata[key] = gpodder.gettext(localized_metadata[key])
return metadata
def set_enabled(self, enabled):
if enabled and not self.enabled:
self.error = None
self.enabled = True
if hasattr(self.module, 'on_load'):
except Exception as exception:
logger.error('Cannot load %s from %s: %s',,
self.filename, exception, exc_info=True)
if isinstance(exception, ImportError):
# Wrap ImportError in MissingCommand for user-friendly
# message (might be displayed in the GUI)
module =
msg = _('Python module not found: %(module)s') % {
'module': module
exception = MissingCommand(msg, module, exception)
self.error = exception
self.enabled = False
elif not enabled and self.enabled:
if hasattr(self.module, 'on_unload'):
except Exception as exception:
logger.error('Failed to on_unload %s: %s',,
exception, exc_info=True)
self.enabled = False
def load_extension(self):
"""Load and initialize the gPodder extension module"""
if self.module is not None:'Module already loaded.')
if not self.metadata.available_for_current_ui:'Not loading "%s" (only_for = "%s")',, self.metadata.only_for)
basename, extension = os.path.splitext(os.path.basename(self.filename))
fp = open(self.filename, 'r')
module_file = imp.load_module(basename, fp, self.filename,
(extension, 'r', imp.PY_SOURCE))
# Remove the .pyc file if it was created during import
util.delete_file(self.filename + 'c')
self.default_config = getattr(module_file, 'DefaultConfig', {})
if self.default_config:
'extensions': { self.default_config,
self.config = getattr(self.manager.core.config.extensions,
self.module = module_file.gPodderExtension(self)'Module loaded: %s', self.filename)
class ExtensionManager(object):
"""Loads extensions and manages self-registering plugins"""
def __init__(self, core):
self.core = core
self.filenames = os.environ.get('GPODDER_EXTENSIONS', '').split()
self.containers = []
enabled_extensions = core.config.extensions.enabled
if os.environ.get('GPODDER_DISABLE_EXTENSIONS', '') != '':'Disabling all extensions (from environment)')
for name, filename in self._find_extensions():
logger.debug('Found extension "%s" in %s', name, filename)
config = getattr(core.config.extensions, name)
container = ExtensionContainer(self, name, config, filename)
if (name in enabled_extensions or
if (name in enabled_extensions and
def shutdown(self):
for container in self.containers:
def _config_value_changed(self, name, old_value, new_value):
if name != 'extensions.enabled':
for container in self.containers:
new_enabled = ( in new_value)
if new_enabled == container.enabled:
if not new_enabled and container.metadata.mandatory_in_current_ui:
# forced extensions are never listed in extensions.enabled
continue'Extension "%s" is now %s',,
'enabled' if new_enabled else 'disabled')
if new_enabled and not container.enabled:
logger.warn('Could not enable extension: %s',
self.core.config.extensions.enabled = [x
for x in self.core.config.extensions.enabled
if x !=]
def _find_extensions(self):
extensions = {}
if not self.filenames:
builtins = os.path.join(gpodder.prefix, 'share', 'gpodder',
'extensions', '*.py')
user_extensions = os.path.join(gpodder.home, 'Extensions', '*.py')
self.filenames = glob.glob(builtins) + glob.glob(user_extensions)
# Let user extensions override built-in extensions of the same name
for filename in self.filenames:
if not filename or not os.path.exists(filename):'Skipping non-existing file: %s', filename)
name, _ = os.path.splitext(os.path.basename(filename))
extensions[name] = filename
return sorted(extensions.items())
def get_extensions(self):
"""Get a list of all loaded extensions and their enabled flag"""
return [c for c in self.containers
if c.metadata.available_for_current_ui and
not c.metadata.mandatory_in_current_ui and
not c.metadata.disable_in_current_ui]
# Define all known handler functions here, decorate them with the
# "call_extension" decorator to forward all calls to extension scripts that have
# the same function defined in them. If the handler functions here contain
# any code, it will be called after all the extensions have been called.
def on_ui_initialized(self, model, update_podcast_callback,
"""Called when the user interface is initialized.
@param model: A gpodder.model.Model instance
@param update_podcast_callback: Function to update a podcast feed
@param download_episode_callback: Function to download an episode
def on_podcast_subscribe(self, podcast):
"""Called when the user subscribes to a new podcast feed.
@param podcast: A gpodder.model.PodcastChannel instance
def on_podcast_updated(self, podcast):
"""Called when a podcast feed was updated
This extension will be called even if there were no new episodes.
@param podcast: A gpodder.model.PodcastChannel instance
def on_podcast_update_failed(self, podcast, exception):
"""Called when a podcast update failed.
@param podcast: A gpodder.model.PodcastChannel instance
@param exception: The reason.
def on_podcast_save(self, podcast):
"""Called when a podcast is saved to the database
This extensions will be called when the user edits the metadata of
the podcast or when the feed was updated.
@param podcast: A gpodder.model.PodcastChannel instance
def on_podcast_delete(self, podcast):
"""Called when a podcast is deleted from the database
@param podcast: A gpodder.model.PodcastChannel instance
def on_episode_playback(self, episode):
"""Called when an episode is played back
This function will be called when the user clicks on "Play" or
"Open" in the GUI to open an episode with the media player.
@param episode: A gpodder.model.PodcastEpisode instance
def on_episode_save(self, episode):
"""Called when an episode is saved to the database
This extension will be called when a new episode is added to the
database or when the state of an existing episode is changed.
@param episode: A gpodder.model.PodcastEpisode instance
def on_episode_downloaded(self, episode):
"""Called when an episode has been downloaded
You can retrieve the filename via episode.local_filename(False)
@param episode: A gpodder.model.PodcastEpisode instance
def on_all_episodes_downloaded(self):
"""Called when all episodes has been downloaded
def on_episode_synced(self, device, episode):
"""Called when an episode has been synced to device
You can retrieve the filename via episode.local_filename(False)
For MP3PlayerDevice:
You can retrieve the filename on device via
You can retrieve the folder name on device via
@param device: A gpodder.sync.Device instance
@param episode: A gpodder.model.PodcastEpisode instance
def on_create_menu(self):
"""Called when the Extras menu is created
You can add additional Extras menu entries here. You have to return a
list of tuples, where the first item is a label and the second item is a
callable that will get no parameter.
Example return value:
[('Sync to Smartphone', lambda : ...)]
def on_episodes_context_menu(self, episodes):
"""Called when the episode list context menu is opened
You can add additional context menu entries here. You have to
return a list of tuples, where the first item is a label and
the second item is a callable that will get the episode as its
first and only parameter.
Example return value:
[('Mark as new', lambda episodes: ...)]
@param episodes: A list of gpodder.model.PodcastEpisode instances
def on_channel_context_menu(self, channel):
"""Called when the channel list context menu is opened
You can add additional context menu entries here. You have to return a
list of tuples, where the first item is a label and the second item is a
callable that will get the channel as its first and only parameter.
Example return value:
[('Update channel', lambda channel: ...)]
@param channel: A gpodder.model.PodcastChannel instance
def on_episode_delete(self, episode, filename):
"""Called just before the episode's disk file is about to be
def on_episode_removed_from_podcast(self, episode):
"""Called just before the episode is about to be removed from
the podcast channel, e.g., when the episode has not been
downloaded and it disappears from the feed.
@param podcast: A gpodder.model.PodcastChannel instance
def on_notification_show(self, title, message):
"""Called when a notification should be shown
@param title: title of the notification
@param message: message of the notification
def on_download_progress(self, progress):
"""Called when the overall download progress changes
@param progress: The current progress value (0..1)
def on_ui_object_available(self, name, ui_object):
"""Called when an UI-specific object becomes available
XXX: Experimental. This hook might go away without notice (and be
replaced with something better). Only use for in-tree extensions.
@param name: The name/ID of the object
@param ui_object: The object itself
def on_application_started(self):
"""Called when the application started.
This is for extensions doing stuff at startup that they don't
want to do if they have just been enabled.
e.g. minimize at startup should not minimize the application when
enabled but only on following startups.
It is called after on_ui_object_available and on_ui_initialized.
You can’t perform that action at this time.