trukstosie faili

kodiswift/__init__.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift
+----------
+
+A micro framework to enable rapid development of Kodi plugins.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+from types import ModuleType
+
+try:
+    import xbmc
+    import xbmcgui
+    import xbmcplugin
+    import xbmcaddon
+    import xbmcvfs
+
+    CLI_MODE = False
+except ImportError:
+    CLI_MODE = True
+    import sys
+    from kodiswift.logger import log
+
+    # Mock the Kodi modules
+    from kodiswift.mockxbmc import xbmc, xbmcgui, xbmcplugin, xbmcaddon, xbmcvfs
+
+    class _Module(ModuleType):
+        """A wrapper class for a module used to override __getattr__.
+        This class will behave normally for any existing module attributes.
+        For any attributes which do not exist in the wrapped module, a mock
+        function will be returned. This function will also return itself
+        enabling multiple mock function calls.
+        """
+
+        def __init__(self, wrapped=None):
+            self.wrapped = wrapped
+            if wrapped:
+                self.__dict__.update(wrapped.__dict__)
+
+        def __getattr__(self, name):
+            """Returns any existing attr for the wrapped module or returns a
+            mock function for anything else. Never raises an AttributeError.
+            """
+            try:
+                return getattr(self.wrapped, name)
+            except AttributeError:
+                # noinspection PyUnusedLocal
+                # pylint disable=unused-argument
+                def func(*args, **kwargs):
+                    """A mock function which returns itself, enabling chainable
+                    function calls.
+                    """
+                    log.warning('The %s method has not been implemented on '
+                                'the CLI. Your code might not work properly '
+                                'when calling it.', name)
+                    return self
+
+                return func
+
+    xbmc = _Module(xbmc)
+    xbmcgui = _Module(xbmcgui)
+    xbmcplugin = _Module(xbmcplugin)
+    xbmcaddon = _Module(xbmcaddon)
+    xbmcvfs = _Module(xbmcvfs)
+    for m in (xbmc, xbmcgui, xbmcplugin, xbmcaddon, xbmcvfs):
+        name = reversed(m.__name__.rsplit('.', 1)).next()
+        sys.modules[name] = m
+
+from kodiswift.storage import TimedStorage
+from kodiswift.request import Request
+from kodiswift.common import (kodi_url, clean_dict, pickle_dict, unpickle_args,
+                              unpickle_dict, download_page)
+from kodiswift.constants import SortMethod
+from kodiswift.listitem import ListItem
+from kodiswift.logger import setup_log
+from kodiswift.module import Module
+from kodiswift.urls import AmbiguousUrlException, NotFoundException, UrlRule
+from kodiswift.xbmcmixin import XBMCMixin
+from kodiswift.plugin import Plugin

kodiswift/actions.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.actions
+------------------
+
+This module contains wrapper functions for Kodi built-in functions.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+
+__all__ = ['background', 'update_view']
+
+
+def background(url):
+    """This action will run an addon in the background for the provided URL.
+
+    See 'RunPlugin()' at
+    http://kodi.wiki/view/List_of_built-in_functions
+
+    Args:
+        url (str): Full path must be specified.
+            Does not work for folder plugins.
+
+    Returns:
+        str: String of the builtin command
+    """
+    return 'RunPlugin(%s)' % url
+
+
+def update_view(url):
+    """This action will update the current container view with provided url.
+
+    See 'Container.Update()' at
+    http://kodi.wiki/view/List_of_built-in_functions
+    """
+    return 'Container.Update(%s)' % url

kodiswift/cli/__init__.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""
+    kodiswift.cli
+    ----------------
+
+    This package contains modules that are used only when running kodiswift in
+    CLI mode. Nothing from this package should be called from addon code.
+
+    :copyright: (c) 2012 by Jonathan Beluch
+    :license: GPLv3, see LICENSE for more details.
+"""
+
+
+def Option(*args, **kwargs):
+    """Returns a tuple of args, kwargs passed to the function. Useful for
+    recording arguments for future function calls.
+    """
+    return args, kwargs

kodiswift/cli/app.py

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.cli.app
+----------------
+
+This package contains the code which runs plugins from the command line.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import logging
+import os
+import sys
+from xml.etree import ElementTree as Et
+
+from kodiswift import Plugin, ListItem, logger
+from kodiswift.cli import Option
+from kodiswift.cli.console import (display_listitems, continue_or_quit,
+                                   get_user_choice)
+from kodiswift.common import Modes
+
+__all__ = ['get_addon_module_name', 'crawl', 'RunCommand', 'PluginManager',
+           'setup_options', 'patch_sysargv', 'patch_plugin', 'once',
+           'interactive']
+
+
+class RunCommand(object):
+    """A CLI command to run a plugin."""
+
+    command = 'run'
+    usage = '%prog run [once|interactive|crawl] [url]'
+    option_list = (
+        Option('-q', '--quiet', action='store_true',
+               help='set logging level to quiet'),
+        Option('-v', '--verbose', action='store_true',
+               help='set logging level to verbose'),
+    )
+
+    @staticmethod
+    def run(opts, args):
+        """The run method for the 'run' command. Executes a plugin from the
+        command line.
+        """
+        setup_options(opts)
+
+        mode = Modes.ONCE
+        if len(args) > 0 and hasattr(Modes, args[0].upper()):
+            _mode = args.pop(0).upper()
+            mode = getattr(Modes, _mode)
+
+        url = None
+        if len(args) > 0:
+            # A url was specified
+            url = args.pop(0)
+
+        plugin_mgr = PluginManager.load_plugin_from_addon_xml(mode, url)
+        plugin_mgr.run()
+
+
+def setup_options(opts):
+    """Takes any actions necessary based on command line options"""
+    if opts.quiet:
+        logger.log.setLevel(logging.WARNING)
+        logger.GLOBAL_LOG_LEVEL = logging.WARNING
+
+    if opts.verbose:
+        logger.log.setLevel(logging.DEBUG)
+        logger.GLOBAL_LOG_LEVEL = logging.DEBUG
+
+
+def get_addon_module_name(addon_xml_filename):
+    """Attempts to extract a module name for the given addon's addon.xml file.
+    Looks for the 'xbmc.python.pluginsource' extension node and returns the
+    addon's filename without the .py suffix.
+    """
+    try:
+        xml = Et.parse(addon_xml_filename).getroot()
+    except IOError:
+        sys.exit('Cannot find an addon.xml file in the current working '
+                 'directory. Please run this command from the root directory '
+                 'of an addon.')
+
+    try:
+        plugin_source = (ext for ext in xml.findall('extension') if
+                         ext.get('point') == 'xbmc.python.pluginsource').next()
+    except StopIteration:
+        sys.exit('ERROR, no pluginsource in addonxml')
+
+    return plugin_source.get('library').split('.')[0]
+
+
+class PluginManager(object):
+    """A class to handle running a plugin in CLI mode. Handles setup state
+    before calling plugin.run().
+    """
+
+    @classmethod
+    def load_plugin_from_addon_xml(cls, mode, url):
+        """Attempts to import a plugin's source code and find an instance of
+        :class:`~kodiswift.Plugin`. Returns an instance of PluginManager if
+        successful.
+        """
+        cwd = os.getcwd()
+        sys.path.insert(0, cwd)
+        module_name = get_addon_module_name(os.path.join(cwd, 'addon.xml'))
+        addon = __import__(module_name)
+
+        # Find the first instance of kodiswift.Plugin
+        try:
+            plugin = (attr_value for attr_value in vars(addon).values()
+                      if isinstance(attr_value, Plugin)).next()
+        except StopIteration:
+            sys.exit('Could not find a Plugin instance in %s.py' % module_name)
+
+        return cls(plugin, mode, url)
+
+    def __init__(self, plugin, mode, url):
+        self.plugin = plugin
+        self.mode = mode
+        self.url = url
+
+    def run(self):
+        """This method runs the the plugin in the appropriate mode parsed from
+        the command line options.
+        """
+        handle = 0
+        handlers = {
+            Modes.ONCE: once,
+            Modes.CRAWL: crawl,
+            Modes.INTERACTIVE: interactive,
+        }
+        handler = handlers[self.mode]
+        patch_sysargv(self.url or 'plugin://%s/' % self.plugin.id, handle)
+        return handler(self.plugin)
+
+
+def patch_sysargv(*args):
+    """Patches sys.argv with the provided args"""
+    sys.argv = args[:]
+
+
+def patch_plugin(plugin, path, handle=None):
+    """Patches a few attributes of a plugin instance to enable a new call to
+    plugin.run()
+    """
+    if handle is None:
+        handle = plugin.request.handle
+    patch_sysargv(path, handle)
+    plugin._end_of_directory = False
+
+
+def once(plugin, parent_stack=None):
+    """A run mode for the CLI that runs the plugin once and exits."""
+    plugin.clear_added_items()
+    items = plugin.run()
+
+    # if update_listing=True, we need to remove the last url from the parent
+    # stack
+    if parent_stack and plugin._update_listing:
+        del parent_stack[-1]
+
+    # if we have parent items, include the most recent in the display
+    if parent_stack:
+        items.insert(0, parent_stack[-1])
+
+    display_listitems(items, plugin.request.url)
+    return items
+
+
+def interactive(plugin):
+    """A run mode for the CLI that runs the plugin in a loop based on user
+    input.
+    """
+    items = [item for item in once(plugin) if not item.get_played()]
+    parent_stack = []  # Keep track of parents so we can have a '..' option
+
+    selected_item = get_user_choice(items)
+    while selected_item is not None:
+        if parent_stack and selected_item == parent_stack[-1]:
+            # User selected the parent item, remove from list
+            parent_stack.pop()
+        else:
+            # User selected non parent item, add current url to parent stack
+            parent_stack.append(ListItem.from_dict(label='..',
+                                                   path=plugin.request.url))
+        patch_plugin(plugin, selected_item.get_path())
+
+        items = [item for item in once(plugin, parent_stack=parent_stack)
+                 if not item.get_played()]
+        selected_item = get_user_choice(items)
+
+
+def crawl(plugin):
+    """Performs a breadth-first crawl of all possible routes from the
+    starting path. Will only visit a URL once, even if it is referenced
+    multiple times in a plugin. Requires user interaction in between each
+    fetch.
+    """
+    # TODO: use OrderedSet?
+    paths_visited = set()
+    paths_to_visit = set(item.get_path() for item in once(plugin))
+
+    while paths_to_visit and continue_or_quit():
+        path = paths_to_visit.pop()
+        paths_visited.add(path)
+
+        # Run the new listitem
+        patch_plugin(plugin, path)
+        new_paths = set(item.get_path() for item in once(plugin))
+
+        # Filter new items by checking against urls_visited and
+        # urls_tovisit
+        paths_to_visit.update(path for path in new_paths
+                              if path not in paths_visited)

kodiswift/cli/cli.py

@@ -0,0 +1,78 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.cli.cli
+------------------
+
+The main entry point for the kodiswift console script. CLI commands can be
+registered in this module.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import sys
+from optparse import OptionParser
+
+from kodiswift.cli.app import RunCommand
+from kodiswift.cli.create import CreateCommand
+
+# TODO: Make an ABC for Command
+COMMANDS = {
+    RunCommand.command: RunCommand,
+    CreateCommand.command: CreateCommand,
+}
+
+
+# TODO: Make this usage dynamic based on COMMANDS dict
+USAGE = """%prog <command>
+
+Commands:
+    create
+        Create a new plugin project.
+
+    run
+        Run an kodiswift plugin from the command line.
+
+Help:
+    To see options for a command, run `kodiswift <command> -h`
+"""
+
+
+def main():
+    """The entry point for the console script kodiswift.
+
+    The 'xbcmswift2' script is command bassed, so the second argument is always
+    the command to execute. Each command has its own parser options and usages.
+    If no command is provided or the -h flag is used without any other
+    commands, the general help message is shown.
+    """
+    parser = OptionParser()
+    if len(sys.argv) == 1:
+        parser.set_usage(USAGE)
+        parser.error('At least one command is required.')
+
+    # spy sys.argv[1] in order to use correct opts/args
+    command = sys.argv[1]
+
+    if command == '-h':
+        parser.set_usage(USAGE)
+        opts, args = parser.parse_args()
+
+    if command not in COMMANDS.keys():
+        parser.error('Invalid command')
+
+    # We have a proper command, set the usage and options list according to the
+    # specific command
+    manager = COMMANDS[command]
+    if hasattr(manager, 'option_list'):
+        for args, kwargs in manager.option_list:
+            parser.add_option(*args, **kwargs)
+    if hasattr(manager, 'usage'):
+        parser.set_usage(manager.usage)
+
+    opts, args = parser.parse_args()
+
+    # Since we are calling a specific comamnd's manager, we no longer need the
+    # actual command in sys.argv so we slice from position 1
+    manager.run(opts, args[1:])

kodiswift/cli/console.py

@@ -0,0 +1,101 @@
+# -*- coding: utf-8 -*-
+"""
+    kodiswift.cli.console
+    ----------------------
+
+    This module contains code to handle CLI interaction.
+
+    :copyright: (c) 2012 by Jonathan Beluch
+    :license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import print_function, absolute_import
+
+
+def get_max_len(items):
+    """Returns the max of the lengths for the provided items"""
+    try:
+        return max(len(item) for item in items)
+    except ValueError:
+        return 0
+
+
+def display_listitems(items, url):
+    """Displays a list of items along with the index to enable a user
+    to select an item.
+
+    Args:
+        items (list[kodiswift.ListItem]):
+        url (str):
+    """
+    if len(items) == 2 and items[0].label == '..' and items[1].played:
+        display_video(items)
+    else:
+        label_width = get_max_len(item.label for item in items)
+        num_width = len(str(len(items)))
+        output = []
+        for i, item in enumerate(items):
+            output.append('[%s] %s (%s)' % (
+                str(i).rjust(num_width),
+                item.label.ljust(label_width),
+                item.path))
+
+        line_width = get_max_len(output)
+        output.append('-' * line_width)
+
+        header = [
+            '',
+            '=' * line_width,
+            'Current URL: %s' % url,
+            '-' * line_width,
+            '%s %s Path' % ('#'.center(num_width + 2),
+                            'Label'.ljust(label_width)),
+            '-' * line_width,
+        ]
+        print('\n'.join(header + output))
+
+
+def display_video(items):
+    """Prints a message for a playing video and displays the parent
+    listitem.
+    """
+    parent_item, played_item = items
+
+    title_line = 'Playing Media %s (%s)' % (played_item.label, played_item.path.encode("utf8"))
+    parent_line = '[0] %s (%s)' % (parent_item.label, parent_item.path)
+    line_width = get_max_len([title_line, parent_line])
+
+    output = [
+        '-' * line_width,
+        title_line,
+        '-' * line_width,
+        parent_line.encode("utf8") if isinstance(parent_line, unicode) else parent_line ,
+    ]
+    print('\n'.join(output))
+
+
+def get_user_choice(items):
+    """Returns the selected item from provided items or None if 'q' was
+    entered for quit.
+    """
+    choice = raw_input('Choose an item or "q" to quit: ')
+    while choice != 'q':
+        try:
+            item = items[int(choice)]
+            print()  # Blank line for readability between interactive views
+            return item
+        except ValueError:
+            # Passed something that couldn't be converted with int()
+            choice = raw_input('You entered a non-integer. Choice must be an'
+                               ' integer or "q": ')
+        except IndexError:
+            # Passed an integer that was out of range of the list of urls
+            choice = raw_input('You entered an invalid integer. Choice must '
+                               'be from above url list or "q": ')
+    return None
+
+
+def continue_or_quit():
+    """Prints an exit message and returns False if the user wants to
+    quit.
+    """
+    return raw_input('Enter to continue or "q" to quit') != 'q'

kodiswift/cli/create.py

@@ -0,0 +1,192 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.cli.create
+---------------------
+
+This module contains the code to initialize a new Kodi addon project.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import print_function, absolute_import
+
+import os
+import readline
+import string
+from getpass import getpass
+from optparse import OptionParser
+from os import getcwd
+from shutil import copytree, ignore_patterns
+from xml.sax import saxutils
+
+
+class CreateCommand(object):
+    """A CLI command to initialize a new Kodi addon project."""
+    command = 'create'
+    usage = '%prog create'
+
+    # noinspection PyUnusedLocal
+    @staticmethod
+    def run(opts, args):
+        """Required run function for the 'create' CLI command."""
+        create_new_project()
+
+
+# Path to skeleton file templates dir
+SKEL = os.path.join(os.path.dirname(__file__), 'data')
+
+
+def error_msg(msg):
+    """A decorator that sets the error_message attribute of the decorated
+    function to the provided value.
+    """
+    def decorator(func):
+        """Sets the error_message attribute on the provided function"""
+        func.error_message = msg
+        return func
+    return decorator
+
+
+def parse_cli():
+    """Currently only one positional arg, create."""
+    parser = OptionParser()
+    return parser.parse_args()
+
+
+@error_msg('** Value must be non-blank.')
+def validate_nonblank(value):
+    """A callable that retunrs the value passed"""
+    return value
+
+
+@error_msg('** Value must contain only letters or underscores.')
+def validate_pluginid(value):
+    """Returns True if the provided value is a valid plugin id"""
+    valid = string.ascii_letters + string.digits + '.' + '_'
+    return all(c in valid for c in value)
+
+
+@error_msg('** The provided path must be an existing folder.')
+def validate_isfolder(value):
+    """Returns true if the provided path is an existing directory"""
+    return os.path.isdir(value)
+
+
+def get_valid_value(prompt, validator, default=None):
+    """Displays the provided prompt and gets input from the user. This behavior
+    loops indefinitely until the provided validator returns True for the user
+    input. If a default value is provided, it will be used only if the user
+    hits Enter and does not provide a value.
+
+    If the validator callable has an error_message attribute, it will be
+    displayed for an invalid value, otherwise a generic message is used.
+    """
+    ans = get_value(prompt, default)
+    while not validator(ans):
+        try:
+            print(validator.error_message)
+        except AttributeError:
+            print('Invalid value.')
+        ans = get_value(prompt, default)
+
+    return ans
+
+
+def get_value(prompt, default=None, hidden=False):
+    """Displays the provided prompt and returns the input from the user. If the
+    user hits Enter and there is a default value provided, the default is
+    returned.
+    """
+    _prompt = '%s : ' % prompt
+    if default:
+        _prompt = '%s [%s]: ' % (prompt, default)
+
+    if hidden:
+        ans = getpass(_prompt)
+    else:
+        ans = raw_input(_prompt)
+
+    # If user hit Enter and there is a default value
+    if not ans and default:
+        ans = default
+    return ans
+
+
+def update_file(filename, items):
+    """Edits the given file in place, replacing any instances of {key} with the
+    appropriate value from the provided items dict. If the given filename ends
+    with ".xml" values will be quoted and escaped for XML.
+    """
+    # TODO: Implement something in the templates to denote whether the value
+    # being replaced is an XML attribute or a value. Perhaps move to dyanmic
+    # XML tree building rather than string replacement.
+    should_escape = filename.endswith('addon.xml')
+
+    with open(filename, 'r') as inp:
+        text = inp.read()
+
+    for key, val in items.items():
+        if should_escape:
+            val = saxutils.quoteattr(val)
+        text = text.replace('{%s}' % key, val)
+    output = text
+
+    with open(filename, 'w') as out:
+        out.write(output)
+
+
+def create_new_project():
+    """Creates a new Kodi Plugin directory based on user input"""
+    readline.parse_and_bind('tab: complete')
+
+    print("""
+    kodiswift - A micro-framework for creating Kodi plugins.
+    xbmc@jonathanbeluch.com
+    --
+""")
+    print('I\'m going to ask you a few questions to get this project started.')
+
+    opts = {}
+
+    # Plugin Name
+    opts['plugin_name'] = get_valid_value(
+        'What is your plugin name?',
+        validate_nonblank
+    )
+
+    # Plugin ID
+    opts['plugin_id'] = get_valid_value(
+        'Enter your plugin id.',
+        validate_pluginid,
+        'plugin.video.%s' % (opts['plugin_name'].lower().replace(' ', ''))
+    )
+
+    # Parent Directory
+    opts['parent_dir'] = get_valid_value(
+        'Enter parent folder (where to create project)',
+        validate_isfolder,
+        getcwd()
+    )
+
+    # Parent Directory
+    opts['plugin_dir'] = os.path.join(opts['parent_dir'], opts['plugin_id'])
+    assert not os.path.isdir(opts['plugin_dir']), \
+        'A folder named %s already exists in %s.' % (opts['plugin_id'],
+                                                     opts['parent_dir'])
+
+    # Provider
+    opts['provider_name'] = get_valid_value(
+        'Enter provider name',
+        validate_nonblank,
+    )
+
+    # Create the project folder by copying over skel
+    copytree(SKEL, opts['plugin_dir'], ignore=ignore_patterns('*.pyc'))
+
+    # Walk through all the new files and fill in with out options
+    for root, _, files in os.walk(opts['plugin_dir']):
+        for filename in files:
+            update_file(os.path.join(root, filename), opts)
+
+    print('Projects successfully created in %s.' % opts['plugin_dir'])
+    print('Done.')

kodiswift/cli/data/addon.py

@@ -0,0 +1,19 @@
+# -*- coding: utf-8 -*-
+from kodiswift import Plugin
+
+
+plugin = Plugin()
+
+
+@plugin.route('/')
+def index():
+    item = {
+        'label': 'Hello Kodi!',
+        'path': 'http://example.com/video.mp4',
+        'is_playable': True
+    }
+    return [item]
+
+
+if __name__ == '__main__':
+    plugin.run()

kodiswift/cli/data/addon.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<addon id={plugin_id} name={plugin_name} version="0.0.1" provider-name={provider_name}>
+  <requires>
+    <import addon="xbmc.python" version="2.24.0" />
+    <import addon="script.module.kodiswift" version="0.0.1" />
+  </requires>
+  <extension point="xbmc.python.pluginsource" library="addon.py">
+    <provides>video</provides>
+  </extension>
+  <extension point="xbmc.addon.metadata">
+    <platform>all</platform>
+    <language>en</language>
+    <summary lang="en">Summary for {plugin_name}</summary>
+    <description lang="en">Description for {plugin_name}</description>
+    <disclaimer lang="en">Disclaimer for {plugin_name}</disclaimer>
+  </extension>
+</addon>

kodiswift/cli/data/resources/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

kodiswift/cli/data/resources/language/English/strings.po

@@ -0,0 +1,26 @@
+# Kodi Media Center language file
+# Addon Name: {plugin_name}
+# Addon id: {plugin_id}
+# Addon Provider: {provider_name}
+msgid ""
+msgstr ""
+"Project-Id-Version: Kodi Addons\n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: \n"
+"Language-Team: \n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=UTF-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Language: en\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+
+# strings 30000 thru 30999 reserved for plugins and plugin settings
+# strings 31000 thru 31999 reserved for skins
+# strings 32000 thru 32999 reserved for scripts
+# strings 33000 thru 33999 reserved for common strings used in add-ons
+
+msgctxt "#33000"
+msgid "Hello Kodi"
+msgstr ""

kodiswift/cli/data/resources/lib/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

kodiswift/common.py

@@ -0,0 +1,147 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.common
+-----------------
+
+This module contains some common helpful functions.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import urllib
+
+try:
+    import cPickle as pickle
+except ImportError:
+    import pickle
+
+__all__ = ['clean_dict', 'kodi_url', 'unpickle_args', 'pickle_dict',
+           'unpickle_dict', 'download_page', 'Modes']
+
+
+class Modes(object):
+    ONCE = 'ONCE'
+    CRAWL = 'CRAWL'
+    INTERACTIVE = 'INTERACTIVE'
+
+
+def kodi_url(url, **options):
+    """Appends key/val pairs to the end of a URL. Useful for passing arbitrary
+    HTTP headers to Kodi to be used when fetching a media resource, e.g.
+    cookies.
+
+    Args:
+        url (str):
+        **options (dict):
+
+    Returns:
+        str:
+    """
+    options = urllib.urlencode(options)
+    if options:
+        return url + '|' + options
+    return url
+
+
+def clean_dict(data):
+    """Remove keys with a value of None
+
+    Args:
+        data (dict):
+
+    Returns:
+        dict:
+    """
+    return dict((k, v) for k, v in data.items() if v is not None)
+
+
+def pickle_dict(items):
+    """Convert `items` values into pickled values.
+
+    Args:
+        items (dict): A dictionary
+
+    Returns:
+        dict: Values which aren't instances of basestring are pickled. Also,
+            a new key '_pickled' contains a comma separated list of keys
+            corresponding to the pickled values.
+    """
+    ret = {}
+    pickled_keys = []
+    for k, v in items.items():
+        if isinstance(v, basestring):
+            ret[k] = v
+        else:
+            pickled_keys.append(k)
+            ret[k] = pickle.dumps(v)
+    if pickled_keys:
+        ret['_pickled'] = ','.join(pickled_keys)
+    return ret
+
+
+def unpickle_args(items):
+    """Takes a dict and un-pickles values whose keys are found in a '_pickled'
+    key.
+
+    >>> unpickle_args({'_pickled': ['foo'], 'foo': ['I3%0A.']})
+    {'foo': 3}
+
+    Args:
+        items (dict): A pickled dictionary.
+
+    Returns:
+        dict: Dict with values un-pickled.
+    """
+    # Technically there can be more than one _pickled value. At this point
+    # we'll just use the first one
+    pickled = items.pop('_pickled', None)
+    if pickled is None:
+        return items
+
+    pickled_keys = pickled[0].split(',')
+    ret = {}
+    for k, v in items.items():
+        if k in pickled_keys:
+            ret[k] = [pickle.loads(val) for val in v]
+        else:
+            ret[k] = v
+    return ret
+
+
+def unpickle_dict(items):
+    """un-pickles a dictionary that was pickled with `pickle_dict`.
+
+    Args:
+        items (dict): A pickled dictionary.
+
+    Returns:
+        dict: An un-pickled dictionary.
+    """
+    pickled_keys = items.pop('_pickled', '').split(',')
+    ret = {}
+    for k, v in items.items():
+        if k in pickled_keys:
+            ret[k] = pickle.loads(v)
+        else:
+            ret[k] = v
+    return ret
+
+
+def download_page(url, data=None):
+    """Returns the response for the given url. The optional data argument is
+    passed directly to urlopen.
+
+    Args:
+        url (str): The URL to read.
+        data (Optional[any]): If given, a POST request will be made with
+            :param:`data` as the POST body.
+
+    Returns:
+        str: The results of requesting the URL.
+    """
+    conn = urllib.urlopen(url, data)
+    resp = conn.read()
+    conn.close()
+    return resp

kodiswift/constants.py

@@ -0,0 +1,76 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.constants
+--------------------
+
+This module contains some helpful constants which ease interaction
+with Kodi.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+from kodiswift import xbmcplugin
+
+__all__ = ['SortMethod']
+
+
+class SortMethod(object):
+    """Static class to hold all of the available sort methods. The prefix
+    of 'SORT_METHOD_' is stripped.
+
+    e.g. SORT_METHOD_TITLE becomes SortMethod.TITLE
+    """
+    ALBUM = xbmcplugin.SORT_METHOD_ALBUM
+    ALBUM_IGNORE_THE = xbmcplugin.SORT_METHOD_ALBUM_IGNORE_THE
+    ARTIST = xbmcplugin.SORT_METHOD_ARTIST
+    ARTIST_IGNORE_THE = xbmcplugin.SORT_METHOD_ARTIST_IGNORE_THE
+    BITRATE = xbmcplugin.SORT_METHOD_BITRATE
+    CHANNEL = xbmcplugin.SORT_METHOD_CHANNEL
+    COUNTRY = xbmcplugin.SORT_METHOD_COUNTRY
+    DATE = xbmcplugin.SORT_METHOD_DATE
+    DATEADDED = xbmcplugin.SORT_METHOD_DATEADDED
+    DATE_TAKEN = xbmcplugin.SORT_METHOD_DATE_TAKEN
+    DRIVE_TYPE = xbmcplugin.SORT_METHOD_DRIVE_TYPE
+    DURATION = xbmcplugin.SORT_METHOD_DURATION
+    EPISODE = xbmcplugin.SORT_METHOD_EPISODE
+    FILE = xbmcplugin.SORT_METHOD_FILE
+    FULLPATH = xbmcplugin.SORT_METHOD_FULLPATH
+    GENRE = xbmcplugin.SORT_METHOD_GENRE
+    LABEL = xbmcplugin.SORT_METHOD_LABEL
+    LABEL_IGNORE_FOLDERS = xbmcplugin.SORT_METHOD_LABEL_IGNORE_FOLDERS
+    LABEL_IGNORE_THE = xbmcplugin.SORT_METHOD_LABEL_IGNORE_THE
+    LASTPLAYED = xbmcplugin.SORT_METHOD_LASTPLAYED
+    LISTENERS = xbmcplugin.SORT_METHOD_LISTENERS
+    MPAA_RATING = xbmcplugin.SORT_METHOD_MPAA_RATING
+    NONE = xbmcplugin.SORT_METHOD_NONE
+    PLAYCOUNT = xbmcplugin.SORT_METHOD_PLAYCOUNT
+    PLAYLIST_ORDER = xbmcplugin.SORT_METHOD_PLAYLIST_ORDER
+    PRODUCTIONCODE = xbmcplugin.SORT_METHOD_PRODUCTIONCODE
+    PROGRAM_COUNT = xbmcplugin.SORT_METHOD_PROGRAM_COUNT
+    SIZE = xbmcplugin.SORT_METHOD_SIZE
+    SONG_RATING = xbmcplugin.SORT_METHOD_SONG_RATING
+    STUDIO = xbmcplugin.SORT_METHOD_STUDIO
+    STUDIO_IGNORE_THE = xbmcplugin.SORT_METHOD_STUDIO_IGNORE_THE
+    TITLE = xbmcplugin.SORT_METHOD_TITLE
+    TITLE_IGNORE_THE = xbmcplugin.SORT_METHOD_TITLE_IGNORE_THE
+    TRACKNUM = xbmcplugin.SORT_METHOD_TRACKNUM
+    UNSORTED = xbmcplugin.SORT_METHOD_UNSORTED
+    VIDEO_RATING = xbmcplugin.SORT_METHOD_VIDEO_RATING
+    VIDEO_RUNTIME = xbmcplugin.SORT_METHOD_VIDEO_RUNTIME
+    VIDEO_SORT_TITLE = xbmcplugin.SORT_METHOD_VIDEO_SORT_TITLE
+    VIDEO_SORT_TITLE_IGNORE_THE = xbmcplugin.SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE
+    VIDEO_TITLE = xbmcplugin.SORT_METHOD_VIDEO_TITLE
+    VIDEO_USER_RATING = xbmcplugin.SORT_METHOD_VIDEO_USER_RATING
+    VIDEO_YEAR = xbmcplugin.SORT_METHOD_VIDEO_YEAR
+
+    @classmethod
+    def from_string(cls, sort_method):
+        """Returns the sort method specified. sort_method is case insensitive.
+        Will raise an AttributeError if the provided sort_method does not
+        exist.
+
+        >>> SortMethod.from_string('title')
+        """
+        return getattr(cls, sort_method.upper())

kodiswift/listitem.py

@@ -0,0 +1,339 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.listitem
+------------------
+
+This module contains the ListItem class, which acts as a wrapper
+for xbmcgui.ListItem.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import warnings
+
+from kodiswift import xbmcgui
+
+__all__ = ['ListItem']
+
+
+class ListItem(object):
+    """A wrapper for the xbmcgui.ListItem class. The class keeps track
+    of any set properties that xbmcgui doesn't expose getters for.
+    """
+
+    def __init__(self, label=None, label2=None, icon=None, thumbnail=None,
+                 path=None):
+        """Defaults are an emtpy string since xbmcgui.ListItem will not
+        accept None.
+        """
+        self._listitem = xbmcgui.ListItem(label=label, label2=label2, path=path)
+
+        # The docs have the thumbnail property set as thumb
+        # http://mirrors.kodi.tv/docs/python-docs/16.x-jarvis/xbmcgui.html#ListItem-setArt
+        self._art = {'icon': icon, 'thumb': thumbnail}
+        self._icon = icon
+        self._path = path
+        self._thumbnail = thumbnail
+        self._context_menu_items = []
+        self._played = False
+        self._playable = False
+        self.is_folder = True
+
+    def get_context_menu_items(self):
+        """Returns the list of currently set context_menu items."""
+        return self._context_menu_items
+
+    def add_context_menu_items(self, items, replace_items=False):
+        """Adds context menu items. If replace_items is True all
+        previous context menu items will be removed.
+        """
+        for label, action in items:
+            assert isinstance(label, basestring)
+            assert isinstance(action, basestring)
+        if replace_items:
+            self._context_menu_items = []
+        self._context_menu_items.extend(items)
+        self._listitem.addContextMenuItems(items, replace_items)
+
+    @property
+    def label(self):
+        """
+        Returns:
+            str:
+        """
+        return self._listitem.getLabel()
+
+    @label.setter
+    def label(self, value):
+        """
+        Args:
+            value (str):
+        """
+        self._listitem.setLabel(value)
+
+    def get_label(self):
+        warnings.warn('get_label is deprecated, use label property',
+                      DeprecationWarning)
+        return self.label
+
+    def set_label(self, value):
+        warnings.warn('set_label is deprecated, use label property',
+                      DeprecationWarning)
+        return self._listitem.setLabel(value)
+
+    @property
+    def label2(self):
+        return self._listitem.getLabel2()
+
+    @label2.setter
+    def label2(self, value):
+        self._listitem.setLabel2(value)
+
+    def get_label2(self):
+        warnings.warn('get_label2 is deprecated, use label2 property',
+                      DeprecationWarning)
+        return self.label2
+
+    def set_label2(self, value):
+        warnings.warn('set_label2 is deprecated, use label2 property',
+                      DeprecationWarning)
+        return self._listitem.setLabel2(value)
+
+    @property
+    def selected(self):
+        return self._listitem.isSelected()
+
+    @selected.setter
+    def selected(self, value):
+        self._listitem.select(value)
+
+    def is_selected(self):
+        warnings.warn('is_selected is deprecated, use selected property',
+                      DeprecationWarning)
+        return self._listitem.isSelected()
+
+    def select(self, selected_status=True):
+        warnings.warn('select is deprecated, use selected property',
+                      DeprecationWarning)
+        return self._listitem.select(selected_status)
+
+    @property
+    def icon(self):
+        return self._art.get('icon')
+
+    @icon.setter
+    def icon(self, value):
+        self._art['icon'] = value
+        self._listitem.setArt(self._art)
+
+    def get_icon(self):
+        warnings.warn('get_icon is deprecated, use icon property',
+                      DeprecationWarning)
+        return self.icon
+
+    def set_icon(self, icon):
+        warnings.warn('set_icon is deprecated, use icon property',
+                      DeprecationWarning)
+        self.icon = icon
+        return self.icon
+
+    @property
+    def thumbnail(self):
+        return self._art.get('thumb')
+
+    @thumbnail.setter
+    def thumbnail(self, value):
+        self._art['thumb'] = value
+        self._listitem.setArt(self._art)
+
+    def get_thumbnail(self):
+        warnings.warn('get_thumbnail is deprecated, use thumbnail property',
+                      DeprecationWarning)
+        return self.thumbnail
+
+    def set_thumbnail(self, thumbnail):
+        warnings.warn('set_thumbnail is deprecated, use thumbnail property',
+                      DeprecationWarning)
+        self.thumbnail = thumbnail
+        return self.thumbnail
+
+    @property
+    def poster(self):
+        return self._art.get('poster')
+
+    @poster.setter
+    def poster(self, value):
+        self._art['poster'] = value
+        self._listitem.setArt(self._art)
+
+    @property
+    def path(self):
+        return self._path
+
+    @path.setter
+    def path(self, value):
+        self._path = value
+        self._listitem.setPath(value)
+
+    def get_path(self):
+        warnings.warn('get_path is deprecated, use path property',
+                      DeprecationWarning)
+        return self._path
+
+    def set_path(self, path):
+        warnings.warn('set_path is deprecated, use path property',
+                      DeprecationWarning)
+        self._path = path
+        return self._listitem.setPath(path)
+
+    @property
+    def playable(self):
+        return self._playable
+
+    @playable.setter
+    def playable(self, value):
+        self._playable = value
+        is_playable = 'true' if self._playable else 'false'
+        self.set_property('isPlayable', is_playable)
+
+    def get_is_playable(self):
+        warnings.warn('get_is_playable is deprecated, use playable property',
+                      DeprecationWarning)
+        return self._playable
+
+    def set_is_playable(self, is_playable):
+        warnings.warn('set_is_playable is deprecated, use playable property',
+                      DeprecationWarning)
+        self._playable = is_playable
+        value = 'false'
+        if is_playable:
+            value = 'true'
+        self.set_property('isPlayable', value)
+
+    @property
+    def played(self):
+        return self._played
+
+    @played.setter
+    def played(self, value):
+        self._played = value
+
+    def set_played(self, was_played):
+        """Sets the played status of the listitem.
+
+        Used to differentiate between a resolved video versus a playable item.
+        Has no effect on Kodi, it is strictly used for kodiswift.
+        """
+        warnings.warn('set_played is deprecated, use played property',
+                      DeprecationWarning)
+        self._played = was_played
+
+    def get_played(self):
+        warnings.warn('get_played is deprecated, use played property',
+                      DeprecationWarning)
+        return self._played
+
+    @property
+    def art(self):
+        return self._art
+
+    @art.setter
+    def art(self, value):
+        self._art = value
+        self._listitem.setArt(value)
+
+    def set_art(self, value):
+        self._art = value
+        self._listitem.setArt(value)
+
+    def set_info(self, info_type, info_labels):
+        """Sets the listitem's info"""
+        return self._listitem.setInfo(info_type, info_labels)
+
+    def get_property(self, key):
+        """Returns the property associated with the given key"""
+        return self._listitem.getProperty(key)
+
+    def set_property(self, key, value):
+        """Sets a property for the given key and value"""
+        return self._listitem.setProperty(key, value)
+
+    def add_stream_info(self, stream_type, stream_values):
+        """Adds stream details"""
+        return self._listitem.addStreamInfo(stream_type, stream_values)
+
+    def as_tuple(self):
+        """Returns a tuple of list item properties:
+            (path, the wrapped xbmcgui.ListItem, is_folder)
+        """
+        return self.path, self._listitem, self.is_folder
+
+    def as_xbmc_listitem(self):
+        """Returns the wrapped xbmcgui.ListItem"""
+        return self._listitem
+
+    @classmethod
+    def from_dict(cls, label=None, label2=None, icon=None, thumbnail=None,
+                  path=None, selected=None, info=None, properties=None,
+                  context_menu=None, replace_context_menu=False,
+                  is_playable=None, info_type='video', stream_info=None,
+                  **kwargs):
+        """A ListItem constructor for setting a lot of properties not
+        available in the regular __init__ method. Useful to collect all
+        the properties in a dict and then use the **dct to call this
+        method.
+        """
+        # TODO(Sinap): Should this just use **kwargs? or should art be a dict?
+        listitem = cls(label, label2, path=path)
+        listitem.art = {
+            'icon': icon,
+            'thumb': thumbnail,
+            'poster': kwargs.get('poster'),
+            'banner': kwargs.get('banner'),
+            'fanart': kwargs.get('fanart'),
+            'landscape': kwargs.get('landscape'),
+        }
+
+        if selected is not None:
+            listitem.selected = selected
+
+        if info:
+            listitem.set_info(info_type, info)
+
+        if is_playable:
+            listitem.playable = True
+            listitem.is_folder = False # III
+
+        if properties:
+            # Need to support existing tuples, but prefer to have a dict for
+            # properties.
+            if hasattr(properties, 'items'):
+                properties = properties.items()
+            for key, val in properties:
+                listitem.set_property(key, val)
+
+        if stream_info:
+            for stream_type, stream_values in stream_info.items():
+                listitem.add_stream_info(stream_type, stream_values)
+
+        if context_menu:
+            listitem.add_context_menu_items(context_menu, replace_context_menu)
+
+        return listitem
+
+    def __eq__(self, other):
+        if not isinstance(other, ListItem):
+            raise NotImplementedError
+        self_props = (self.label, self.label2, self.art, self.path,
+                      self.playable, self.selected, self.played,)
+        other_props = (other.label, other.label2, other.art, other.path,
+                       other.playable, other.selected, other.played,)
+        return self_props == other_props
+
+    def __str__(self):
+        return ('%s (%s)' % (self.label, self.path)).encode('utf-8')
+
+    def __repr__(self):
+        return ("<ListItem '%s'>" % self.label).encode('utf-8')

kodiswift/logger.py

@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.log
+--------------
+
+This module contains the kodiswift logger as well as a convenience
+method for creating new loggers.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import logging
+
+from kodiswift import CLI_MODE
+
+__all__ = ['setup_log', 'GLOBAL_LOG_LEVEL', 'log']
+
+# TODO: Add logging to a file as well when on CLI with lowest threshold
+#       possible
+# fh = logging.FileHandler('log_filename.txt')
+# fh.setLevel(logging.DEBUG)
+# fh.setFormatter(formatter)
+# log.addHandler(fh)
+# TODO: Allow a global flag to set logging level when dealing with Kodi
+# TODO: Add -q and -v flags to CLI to quiet or enable more verbose logging
+
+
+class XBMCFilter(object):
+    """A logging filter that streams to STDOUT or to the xbmc log if
+    running inside Kodi.
+    """
+    python_to_xbmc = {
+        'DEBUG': 'LOGDEBUG',
+        'INFO': 'LOGNOTICE',
+        'WARNING': 'LOGWARNING',
+        'ERROR': 'LOGERROR',
+        'CRITICAL': 'LOGSEVERE',
+    }
+
+    xbmc_levels = {
+        'LOGDEBUG': 0,
+        'LOGINFO': 1,
+        'LOGNOTICE': 2,
+        'LOGWARNING': 3,
+        'LOGERROR': 4,
+        'LOGSEVERE': 5,
+        'LOGFATAL': 6,
+        'LOGNONE': 7,
+    }
+
+    def __init__(self, prefix):
+        self.prefix = prefix
+
+    def filter(self, record):
+        """Returns True for all records if running in the CLI, else returns
+        True.
+
+        When running inside Kodi it calls the xbmc.log() method and prevents
+        the message from being double printed to STDOUT.
+        """
+
+        # When running in Kodi, any logged statements will be double printed
+        # since we are calling xbmc.log() explicitly. Therefore we return False
+        # so every log message is filtered out and not printed again.
+        if CLI_MODE:
+            return True
+        else:
+            # Must not be imported until here because of import order issues
+            # when running in CLI
+            from kodiswift import xbmc
+            xbmc_level = XBMCFilter.xbmc_levels.get(
+                XBMCFilter.python_to_xbmc.get(record.levelname))
+            xbmc.log('%s%s' % (self.prefix, record.getMessage()), xbmc_level)
+            return False
+
+
+if CLI_MODE:
+    GLOBAL_LOG_LEVEL = logging.INFO
+else:
+    GLOBAL_LOG_LEVEL = logging.DEBUG
+
+
+def setup_log(name):
+    """Returns a logging instance for the provided name. The returned
+    object is an instance of logging.Logger. Logged messages will be
+    printed to stderr when running in the CLI, or forwarded to Kodi's
+    log when running in Kodi mode.
+    """
+    _log = logging.getLogger(name)
+    _log.setLevel(GLOBAL_LOG_LEVEL)
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter(
+        '%(asctime)s - %(levelname)s - [%(name)s] %(message)s')
+    handler.setFormatter(formatter)
+    _log.addHandler(handler)
+    _log.addFilter(XBMCFilter('[%s] ' % name))
+    return _log
+
+
+# The kodiswift log
+# Plugin writers should use plugin.log instead.
+log = setup_log('kodiswift')

kodiswift/mockxbmc/__init__.py

@@ -0,0 +1 @@
+# -*- coding: utf-8 -*-

kodiswift/mockxbmc/utils.py

@@ -0,0 +1,37 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import
+
+import os
+from xml.dom.minidom import parse
+
+import kodiswift.mockxbmc.polib as polib
+
+
+def load_addon_strings(addon, filename):
+    """This is not an official Kodi method, it is here to facilitate
+    mocking up the other methods when running outside of Kodi."""
+    def get_strings(fn):
+        if os.path.exists(filename):
+            po = polib.pofile(fn)
+            return {entry.msgctxt[1:]: entry.msgid for entry in po}
+        else:
+            fn = os.path.splitext(fn)[0] + '.xml'
+            xml = parse(fn)
+            strings = {tag.getAttribute('id'): tag.firstChild.data
+                       for tag in xml.getElementsByTagName('string')}
+            return strings
+    addon._strings = get_strings(filename)
+
+
+def get_addon_id(addon_xml):
+    """Parses an addon id from the given addon.xml filename."""
+    xml = parse(addon_xml)
+    addon_node = xml.getElementsByTagName('addon')[0]
+    return addon_node.getAttribute('id')
+
+
+def get_addon_name(addon_xml):
+    """Parses an addon name from the given addon.xml filename."""
+    xml = parse(addon_xml)
+    addon_node = xml.getElementsByTagName('addon')[0]
+    return addon_node.getAttribute('name')

kodiswift/mockxbmc/xbmc.py

@@ -0,0 +1,97 @@
+# -*- coding: utf-8 -*-
+from __future__ import print_function, absolute_import
+
+import errno
+import os
+import tempfile
+
+import kodiswift
+from kodiswift.cli.create import get_value
+
+TEMP_DIR = os.path.join(tempfile.gettempdir(), 'kodiswift_debug')
+kodiswift.log.info('Using temp directory %s', TEMP_DIR)
+
+
+def _create_dir(path):
+    """Creates necessary directories for the given path or does nothing
+    if the directories already exist.
+    """
+    try:
+        os.makedirs(path)
+    except OSError as exc:
+        if exc.errno == errno.EEXIST:
+            pass
+        else:
+            raise
+
+
+def log(msg, level=0):
+    levels = [
+        'LOGDEBUG',
+        'LOGINFO',
+        'LOGNOTICE',
+        'LOGWARNING',
+        'LOGERROR',
+        'LOGSEVERE',
+        'LOGFATAL',
+        'LOGNONE',
+    ]
+    print('%s - %s' % (levels[level], msg))
+
+
+# noinspection PyPep8Naming
+def translatePath(path):
+    """Creates folders in the OS's temp directory. Doesn't touch any
+    possible Kodi installation on the machine. Attempting to do as
+    little work as possible to enable this function to work seamlessly.
+    """
+    valid_dirs = ['xbmc', 'home', 'temp', 'masterprofile', 'profile',
+                  'subtitles', 'userdata', 'database', 'thumbnails',
+                  'recordings', 'screenshots', 'musicplaylists',
+                  'videoplaylists', 'cdrips', 'skin', ]
+
+    # TODO: Remove asserts
+    assert path.startswith('special://'), 'Not a valid special:// path.'
+    parts = path.split('/')[2:]
+    #assert len(parts) > 1, 'Need at least a single root directory'
+    assert parts[0] in valid_dirs, '%s is not a valid root dir.' % parts[0]
+
+    # We don't want to swallow any potential IOErrors here, so only makedir for
+    # the root dir, the user is responsible for making any further child dirs
+    _create_dir(os.path.join(TEMP_DIR, parts[0]))
+
+    return os.path.join(TEMP_DIR, *parts)
+
+
+# noinspection PyPep8Naming
+class Keyboard(object):
+    def __init__(self, default='', heading='', hidden=False):
+        self._heading = heading
+        self._default = default
+        self._hidden = hidden
+        self._confirmed = False
+        self._input = None
+
+    def setDefault(self, default):
+        self._default = default
+
+    def setHeading(self, heading):
+        self._heading = heading
+
+    def setHiddenInput(self, hidden):
+        self._hidden = hidden
+
+    def doModal(self):
+        self._confirmed = False
+        try:
+            self._input = get_value(
+                self._heading, self._default, hidden=self._hidden)
+            self._confirmed = True
+        except(KeyboardInterrupt, EOFError):
+            pass
+
+    def isConfirmed(self):
+        return self._confirmed
+
+    def getText(self):
+        return self._input

kodiswift/mockxbmc/xbmcaddon.py

@@ -0,0 +1,70 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import
+
+import os
+
+from kodiswift.logger import log
+from kodiswift.mockxbmc import utils
+
+__all__ = ['Addon']
+
+
+def _get_env_setting(name):
+    return os.getenv('KODISWIFT_%s' % name.upper())
+
+
+# noinspection PyPep8Naming
+class Addon(object):
+    def __init__(self, id=None):
+        # In CLI mode, kodiswift must be run from the root of the addon
+        # directory, so we can rely on getcwd() being correct.
+        addon_xml = os.path.join(os.getcwd(), 'addon.xml')
+        _id = None
+        if os.path.exists(addon_xml):
+            _id = utils.get_addon_id(addon_xml)
+        self._info = {
+            'id': id or _id,
+            'name': utils.get_addon_name(addon_xml),
+            'profile': 'special://profile/addon_data/%s/' % _id,
+            'path': 'special://home/addons/%s' % _id
+        }
+        self._strings = {}
+        self._settings = {}
+        strings_fn = os.path.join(
+            os.getcwd(), 'resources', 'language', 'English', 'strings.po')
+        utils.load_addon_strings(self, strings_fn)
+
+    def getAddonInfo(self, prop):
+        properties = ['author', 'changelog', 'description', 'disclaimer',
+                      'fanart', 'icon', 'id', 'name', 'path', 'profile',
+                      'stars', 'summary', 'type', 'version']
+        if prop not in properties:
+            raise ValueError('%s is not a valid property.' % prop)
+        return self._info.get(prop, 'Unavailable')
+
+    def getLocalizedString(self, str_id):
+        key = str(str_id)
+        if key not in self._strings:
+            raise KeyError('id not found in English/strings.po or '
+                           'strings.xml.')
+        return self._strings[key]
+
+    def getSetting(self, key):
+        log.warning('xbmcaddon.Plugin.getSetting() has not been implemented '
+                    'in CLI mode.')
+        try:
+            value = self._settings[key]
+        except KeyError:
+            # see if we have an env var
+            value = _get_env_setting(key)
+            if _get_env_setting(key) is None:
+                value = raw_input(
+                    '* Please enter a temporary value for %s: ' % key)
+            self._settings[key] = value
+        return value
+
+    def setSetting(self, key, value):
+        self._settings[key] = value
+
+    def openSettings(self):
+        pass

kodiswift/mockxbmc/xbmcgui.py

@@ -0,0 +1,67 @@
+# -*- coding: utf-8 -*-
+
+
+# noinspection PyPep8Naming,PyUnusedLocal
+class ListItem(object):
+    def __init__(self, label=None, label2=None, iconImage=None,
+                 thumbnailImage=None, path=None):
+        self.label = label
+        self.label2 = label2
+        self.iconImage = iconImage
+        self.thumbnailImage = thumbnailImage
+        self.path = path
+        self.properties = {}
+        self.stream_info = {}
+        self.art = {}
+        self.selected = False
+        self.context_menu_items = None
+        self.infolabels = {}
+
+    def addContextMenuItems(self, items, replaceItems=False):
+        self.context_menu_items = items
+
+    def getLabel(self):
+        return self.label
+
+    def getLabel2(self):
+        return self.label2
+
+    def getProperty(self, key):
+        return self.properties[key.lower()]
+
+    def isSelected(self):
+        return self.selected
+
+    def select(self, selected):
+        self.selected = selected
+
+    def setIconImage(self, icon):
+        self.iconImage = icon
+
+    def setInfo(self, info_type, infoLabels):
+        #assert info_type in ['video', 'music', 'pictures']
+        self.infolabels.update(infoLabels)
+
+    def setLabel(self, label):
+        self.label = label
+
+    def setLabel2(self, label2):
+        self.label2 = label2
+
+    def setPath(self, path):
+        self.path = path
+
+    def setProperty(self, key, value):
+        self.properties[key.lower()] = value
+
+    def addStreamInfo(self, stream_type, stream_values):
+        self.stream_info.update({stream_type: stream_values})
+
+    def setThumbnailImage(self, thumb):
+        self.thumbnailImage = thumb
+
+    def setArt(self, values):
+        self.art = values
+
+class WindowXMLDialog:
+    pass

kodiswift/mockxbmc/xbmcplugin.py

@@ -0,0 +1,88 @@
+# coding: utf-8
+"""
+Functions for Kodi plugins
+"""
+import sys
+
+SORT_METHOD_ALBUM = 13
+SORT_METHOD_ALBUM_IGNORE_THE = 14
+SORT_METHOD_ARTIST = 11
+SORT_METHOD_ARTIST_IGNORE_THE = 12
+SORT_METHOD_BITRATE = 40
+SORT_METHOD_CHANNEL = 38
+SORT_METHOD_COUNTRY = 16
+SORT_METHOD_DATE = 3
+SORT_METHOD_DATEADDED = 19
+SORT_METHOD_DATE_TAKEN = 41
+SORT_METHOD_DRIVE_TYPE = 6
+SORT_METHOD_DURATION = 8
+SORT_METHOD_EPISODE = 22
+SORT_METHOD_FILE = 5
+SORT_METHOD_FULLPATH = 32
+SORT_METHOD_GENRE = 15
+SORT_METHOD_LABEL = 1
+SORT_METHOD_LABEL_IGNORE_FOLDERS = 33
+SORT_METHOD_LABEL_IGNORE_THE = 2
+SORT_METHOD_LASTPLAYED = 34
+SORT_METHOD_LISTENERS = 36
+SORT_METHOD_MPAA_RATING = 28
+SORT_METHOD_NONE = 0
+SORT_METHOD_PLAYCOUNT = 35
+SORT_METHOD_PLAYLIST_ORDER = 21
+SORT_METHOD_PRODUCTIONCODE = 26
+SORT_METHOD_PROGRAM_COUNT = 20
+SORT_METHOD_SIZE = 4
+SORT_METHOD_SONG_RATING = 27
+SORT_METHOD_STUDIO = 30
+SORT_METHOD_STUDIO_IGNORE_THE = 31
+SORT_METHOD_TITLE = 9
+SORT_METHOD_TITLE_IGNORE_THE = 10
+SORT_METHOD_TRACKNUM = 7
+SORT_METHOD_UNSORTED = 37
+SORT_METHOD_VIDEO_RATING = 18
+SORT_METHOD_VIDEO_RUNTIME = 29
+SORT_METHOD_VIDEO_SORT_TITLE = 24
+SORT_METHOD_VIDEO_SORT_TITLE_IGNORE_THE = 25
+SORT_METHOD_VIDEO_TITLE = 23
+SORT_METHOD_VIDEO_YEAR = 17
+
+def player(url, title = "", suburl= "",headers={}):
+    from subprocess import call
+    if not url:
+        return
+    cmd1 = [r"c:\Program Files\VideoLAN\VLC\vlc.exe",url,
+           "--meta-title",title.decode("utf8").encode(sys.getfilesystemencoding()),
+           "--http-user-agent","Enigma2"
+    ]
+    # gst-launch-1.0 -v souphttpsrc ssl-strict=false proxy=127.0.0.1:8888 extra-headers="Origin:adadadasd"  location="http://bitdash-a.akamaihd.net/content/sintel/sintel.mpd" ! decodebin! autovideosink
+    cmd2 = [
+        r"C:\gstreamer\1.0\x86_64\bin\gst-launch-1.0","-v",
+        "playbin", 'uri="%s"'%url,
+        #"souphttpsrc", "ssl-strict=false",
+        #"proxy=127.0.0.1:8888",
+        #'location="%s"'%url,
+        #'!decodebin!autovideosink'
+    ]
+    cmd3 = ["ffplay.exe",url]
+    cmd = cmd1 if url.startswith("https") else cmd2
+    ret = call(cmd3)
+    #if ret:
+        #a = raw_input("*** Error, continue")
+    return
+
+def setResolvedUrl(handle, succeeded, listitem):
+    """Callback function to tell XBMC that the file plugin has been resolved to a url
+
+    :param handle: integer - handle the plugin was started with.
+    :param succeeded: bool - True=script completed successfully/False=Script did not.
+    :param listitem: ListItem - item the file plugin resolved to for playback.
+
+    Example::
+
+        xbmcplugin.setResolvedUrl(int(sys.argv[1]), True, listitem)
+
+    """
+    url = listitem.path
+    title = listitem.label
+    player(url,title)
+    pass

kodiswift/mockxbmc/xbmcvfs.py

@@ -0,0 +1,25 @@
+# -*- coding: utf-8 -*-
+
+import os
+
+
+def exists(target):
+    return os.path.exists(target)
+
+
+def rename(origin, target):
+    return os.rename(origin, target)
+
+
+def delete(target):
+    if os.path.isfile(target) and not os.path.isdir(target):
+        return os.unlink(target)
+    return False
+
+
+def mkdir(target):
+    os.mkdir(target)
+
+
+def listdir(target):
+    return os.listdir(target)

kodiswift/module.py

@@ -0,0 +1,155 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.module
+-----------------
+
+This module contains the Module Class.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+from kodiswift import setup_log
+from kodiswift.xbmcmixin import XBMCMixin
+
+__all__ = ['Module']
+
+
+class Module(XBMCMixin):
+    """Modules are basically mini plugins except they don't have any
+    functionality until they are registered with a Plugin.
+    """
+
+    def __init__(self, namespace):
+        # Get rid of package prefixes
+        self._namespace = namespace.split('.')[-1]
+        self._view_functions = {}
+        self._routes = []
+        self._register_funcs = []
+        self._plugin = None
+        self._url_prefix = None
+        self._log = setup_log(namespace)
+
+    @property
+    def plugin(self):
+        """Returns the plugin this module is registered to, or
+
+        Returns:
+            kodiswift.Plugin:
+
+        Raises:
+            RuntimeError: If not registered
+        """
+        if self._plugin is None:
+            raise RuntimeError('Module must be registered in order to call'
+                               'this method.')
+        return self._plugin
+
+    @plugin.setter
+    def plugin(self, value):
+        self._plugin = value
+
+    @property
+    def cache_path(self):
+        """Returns the module's cache_path."""
+        return self.plugin.storage_path
+
+    @property
+    def addon(self):
+        """Returns the module's addon"""
+        return self.plugin.addon
+
+    @property
+    def added_items(self):
+        """Returns this module's added_items"""
+        return self.plugin.added_items
+
+    @property
+    def handle(self):
+        """Returns this module's handle"""
+        return self.plugin.handle
+
+    @property
+    def request(self):
+        """Returns the current request"""
+        return self.plugin.request
+
+    @property
+    def log(self):
+        """Returns the registered plugin's log."""
+        return self._log
+
+    @property
+    def url_prefix(self):
+        """Sets or gets the url prefix of the module.
+
+        Raises an Exception if this module is not registered with a
+        Plugin.
+
+        Returns:
+            str:
+
+        Raises:
+            RuntimeError:
+        """
+        if self._url_prefix is None:
+            raise RuntimeError(
+                'Module must be registered in order to call this method.')
+        return self._url_prefix
+
+    @url_prefix.setter
+    def url_prefix(self, value):
+        self._url_prefix = value
+
+    @property
+    def register_funcs(self):
+        return self._register_funcs
+
+    def route(self, url_rule, name=None, options=None):
+        """A decorator to add a route to a view. name is used to
+        differentiate when there are multiple routes for a given view."""
+        def decorator(func):
+            """Adds a url rule for the provided function"""
+            view_name = name or func.__name__
+            self.add_url_rule(url_rule, func, name=view_name, options=options)
+            return func
+        return decorator
+
+    def url_for(self, endpoint, explicit=False, **items):
+        """Returns a valid Kodi plugin URL for the given endpoint name.
+        endpoint can be the literal name of a function, or it can
+        correspond to the name keyword arguments passed to the route
+        decorator.
+
+        Currently, view names must be unique across all plugins and
+        modules. There are not namespace prefixes for modules.
+        """
+        # TODO: Enable items to be passed with keywords of other var names
+        #       such as endpoing and explicit
+        # TODO: Figure out how to handle the case where a module wants to
+        #       call a parent plugin view.
+        if not explicit and not endpoint.startswith(self._namespace):
+            endpoint = '%s.%s' % (self._namespace, endpoint)
+        return self._plugin.url_for(endpoint, **items)
+
+    def add_url_rule(self, url_rule, view_func, name, options=None):
+        """This method adds a URL rule for routing purposes. The
+        provided name can be different from the view function name if
+        desired. The provided name is what is used in url_for to build
+        a URL.
+
+        The route decorator provides the same functionality.
+        """
+        name = '%s.%s' % (self._namespace, name)
+
+        def register_rule(plugin, url_prefix):
+            """Registers a url rule for the provided plugin and
+            url_prefix.
+            """
+            full_url_rule = url_prefix + url_rule
+            plugin.add_url_rule(full_url_rule, view_func, name, options)
+
+        # Delay actual registration of the url rule until this module is
+        # registered with a plugin
+        self._register_funcs.append(register_rule)

kodiswift/plugin.py

@@ -0,0 +1,357 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.plugin
+-----------------
+
+This module contains the Plugin class. This class handles all of the url
+routing and interaction with Kodi for a plugin.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import collections
+import inspect
+import os
+import sys
+
+import kodiswift
+from kodiswift import xbmc, xbmcaddon, Request
+from kodiswift.logger import log, setup_log
+from kodiswift.urls import UrlRule, NotFoundException, AmbiguousUrlException
+from kodiswift.xbmcmixin import XBMCMixin
+
+__all__ = ['Plugin']
+
+
+class Plugin(XBMCMixin):
+    """The Plugin objects encapsulates all the properties and methods necessary
+    for running an Kodi plugin. The plugin instance is a central place for
+    registering view functions and keeping track of plugin state.
+
+    Usually the plugin instance is created in the main plugin.py file for the
+    plugin. Typical creation looks like this::
+
+        >>> from kodiswift import Plugin
+        >>> plugin = Plugin('Hello Kodi')
+    """
+
+    def __init__(self, name=None, addon_id=None, plugin_file=None,
+                 info_type=None):
+        """
+        Args:
+            name (Optional[str]): The name of the plugin, e.g. 'Hello Kodi'.
+            addon_id (Optional[str): The Kodi addon ID for the plugin,
+                e.g. 'plugin.video.hellokodi'. This parameter is now optional
+                and is really only useful for testing purposes. If it is not
+                provided, the correct value will be parsed from the
+                addon.xml file.
+            plugin_file (Optional[str]): If provided, it should be the path
+                to the plugin.py file in the root of the addon directory.
+                This only has an effect when kodiswift is running on the
+                command line. Will default to the current working directory
+                since kodiswift requires execution in the root addon directory
+                anyway. The parameter still exists to ease testing.
+            info_type (Optional[str):
+        """
+        self._name = name
+        self._routes = []
+        self._view_functions = {}
+        self._addon = xbmcaddon.Addon(addon_id) if addon_id else xbmcaddon.Addon()
+
+        self._addon_id = addon_id or self._addon.getAddonInfo('id')
+        self._name = name or self._addon.getAddonInfo('name')
+
+        self._info_type = info_type
+        if not self._info_type:
+            types = {
+                'video': 'video',
+                'audio': 'music',
+                'image': 'pictures',
+            }
+            self._info_type = types.get(self._addon_id.split('.')[1], 'video')
+
+        # Keeps track of the added list items
+        self._current_items = []
+
+        # Gets initialized when self.run() is called
+        self._request = None
+
+        # A flag to keep track of a call to xbmcplugin.endOfDirectory()
+        self._end_of_directory = False
+
+        # Keep track of the update_listing flag passed to
+        # xbmcplugin.endOfDirectory()
+        self._update_listing = False
+
+        # The plugin's named logger
+        self._log = setup_log(self._addon_id)
+
+        # The path to the storage directory for the addon
+        self._storage_path = xbmc.translatePath(
+            'special://profile/addon_data/%s/.storage/' % self._addon_id)
+        if not os.path.isdir(self._storage_path):
+            os.makedirs(self._storage_path)
+
+        # If we are running in CLI, we need to load the strings.xml manually
+        # Since kodiswift currently relies on execution from an addon's root
+        # directly, we can rely on cwd for now...
+        if kodiswift.CLI_MODE:
+            from kodiswift.mockxbmc import utils
+            if plugin_file:
+                plugin_dir = os.path.dirname(plugin_file)
+            else:
+                plugin_dir = os.getcwd()
+            strings_fn = os.path.join(
+                plugin_dir, 'resources', 'language', 'English', 'strings.po')
+            utils.load_addon_strings(self._addon, strings_fn)
+            self.load_addon_settings()
+
+    @property
+    def info_type(self):
+        return self._info_type
+
+    @property
+    def log(self):
+        """The log instance for the plugin.
+
+        Returns an instance of the stdlib's ``logging.Logger``.
+        This log will print to STDOUT when running in CLI mode and will
+        forward messages to Kodi's log when running in Kodi.
+
+        Examples:
+            ``plugin.log.debug('Debug message')``
+            ``plugin.log.warning('Warning message')``
+            ``plugin.log.error('Error message')``
+
+        Returns:
+            logging.Logger:
+        """
+        return self._log
+
+    @property
+    def id(self):
+        """The id for the addon instance.
+        """
+        return self._addon_id
+
+    @property
+    def storage_path(self):
+        """A full path to the storage folder for this plugin's addon data.
+        """
+        return self._storage_path
+
+    @property
+    def addon(self):
+        """This addon's wrapped instance of xbmcaddon.Plugin.
+        """
+        return self._addon
+
+    @property
+    def added_items(self):
+        """The list of currently added items.
+
+        Even after repeated calls to :meth:`~kodiswift.Plugin.add_items`, this
+        property will contain the complete list of added items.
+        """
+        return self._current_items
+
+    @property
+    def handle(self):
+        """The current plugin's handle. Equal to ``plugin.request.handle``.
+        """
+        return self.request.handle
+
+    @property
+    def request(self):
+        """The current :class:`~kodiswift.Request`.
+
+        Raises:
+            Exception: if the request hasn't been initialized yet via
+                :meth:`~kodiswift.Plugin.run()`.
+
+        Returns:
+            kodiswift.Request:
+        """
+        if self._request is None:
+            raise Exception('It seems the current request has not been '
+                            'initialized yet. Please ensure that '
+                            '`plugin.run()` has been called before attempting '
+                            'to access the current request.')
+        return self._request
+
+    @property
+    def name(self):
+        """The addon's name.
+
+        Returns:
+            str:
+        """
+        return self._name
+
+    def clear_added_items(self):
+        self._current_items = []
+
+    def register_module(self, module, url_prefix):
+        """Registers a module with a plugin. Requires a url_prefix that will
+        then enable calls to url_for.
+
+        Args:
+            module (kodiswift.Module):
+            url_prefix (str): A url prefix to use for all module urls,
+                e.g. '/mymodule'
+        """
+        module.plugin = self
+        module.url_prefix = url_prefix
+        for func in module.register_funcs:
+            func(self, url_prefix)
+
+    def cached_route(self, url_rule, name=None, options=None, ttl=None):
+        """A decorator to add a route to a view and also apply caching. The
+        url_rule, name and options arguments are the same arguments for the
+        route function. The TTL argument if given will passed along to the
+        caching decorator.
+        """
+        route_decorator = self.route(url_rule, name=name, options=options)
+        if ttl:
+            cache_decorator = self.cached(ttl)
+        else:
+            cache_decorator = self.cached()
+
+        def new_decorator(func):
+            return route_decorator(cache_decorator(func))
+
+        return new_decorator
+
+    def route(self, url_rule=None, name=None, root=False, options=None):
+        """A decorator to add a route to a view. name is used to
+        differentiate when there are multiple routes for a given view."""
+
+        def decorator(f):
+            view_name = name or f.__name__
+            if root:
+                url = '/'
+            elif not url_rule:
+                url = '/' + view_name + '/'
+                args = inspect.getargspec(f)[0]
+                if args:
+                    url += '/'.join('%s/<%s>' % (p, p) for p in args)
+            else:
+                url = url_rule
+            self.add_url_rule(url, f, name=view_name, options=options)
+            return f
+
+        return decorator
+
+    def add_url_rule(self, url_rule, view_func, name, options=None):
+        """This method adds a URL rule for routing purposes. The
+        provided name can be different from the view function name if
+        desired. The provided name is what is used in url_for to build
+        a URL.
+
+        The route decorator provides the same functionality.
+        """
+        rule = UrlRule(url_rule, view_func, name, options)
+        if name in self._view_functions.keys():
+            # TODO: Raise exception for ambiguous views during registration
+            log.warning('Cannot add url rule "%s" with name "%s". There is '
+                        'already a view with that name', url_rule, name)
+            self._view_functions[name] = None
+        else:
+            log.debug('Adding url rule "%s" named "%s" pointing to function '
+                      '"%s"', url_rule, name, view_func.__name__)
+            self._view_functions[name] = rule
+        self._routes.append(rule)
+
+    def url_for(self, endpoint, **items):
+        """Returns a valid Kodi plugin URL for the given endpoint name.
+        endpoint can be the literal name of a function, or it can
+        correspond to the name keyword arguments passed to the route
+        decorator.
+
+        Raises AmbiguousUrlException if there is more than one possible
+        view for the given endpoint name.
+        """
+        try:
+            rule = self._view_functions[endpoint]
+        except KeyError:
+            try:
+                rule = (rule for rule in self._view_functions.values()
+                        if rule.view_func == endpoint).next()
+            except StopIteration:
+                raise NotFoundException(
+                    '%s does not match any known patterns.' % endpoint)
+
+        # rule can be None since values of None are allowed in the
+        # _view_functions dict. This signifies more than one view function is
+        # tied to the same name.
+        if not rule:
+            # TODO: Make this a regular exception
+            raise AmbiguousUrlException
+
+        path_qs = rule.make_path_qs(items)
+        return 'plugin://%s%s' % (self._addon_id, path_qs)
+
+    def redirect(self, url):
+        """Used when you need to redirect to another view, and you only
+        have the final plugin:// url."""
+        # TODO: Should we be overriding self.request with the new request?
+        new_request = self._parse_request(url=url, handle=self.request.handle)
+        log.debug('Redirecting %s to %s', self.request.path, new_request.path)
+        return self._dispatch(new_request.path)
+
+    def run(self):
+        """The main entry point for a plugin."""
+        self._request = self._parse_request()
+        log.debug('Handling incoming request for %s', self.request.path)
+        items = self._dispatch(self.request.path)
+
+        # Close any open storages which will persist them to disk
+        if hasattr(self, '_unsynced_storage'):
+            for storage in self._unsynced_storage.values():
+                log.debug('Saving a %s storage to disk at "%s"',
+                          storage.file_format, storage.file_path)
+                storage.close()
+
+        return items
+
+    def _dispatch(self, path):
+        for rule in self._routes:
+            try:
+                view_func, items = rule.match(path)
+            except NotFoundException:
+                continue
+            log.info('Request for "%s" matches rule for function "%s"',
+                     path, view_func.__name__)
+            resp = view_func(**items)
+
+            # Only call self.finish() for UI container listing calls to plugin
+            # (handle will be >= 0). Do not call self.finish() when called via
+            # RunPlugin() (handle will be -1).
+            if not self._end_of_directory and self.handle >= 0:
+                if isinstance(resp, dict):
+                    resp['items'] = self.finish(**resp)
+                elif isinstance(resp, collections.Iterable):
+                    resp = self.finish(items=resp)
+            return resp
+
+        raise NotFoundException('No matching view found for %s' % path)
+
+    @staticmethod
+    def _parse_request(url=None, handle=None):
+        """Handles setup of the plugin state, including request
+        arguments, handle, mode.
+
+        This method never needs to be called directly. For testing, see
+        plugin.test()
+        """
+        # To accommodate self.redirect, we need to be able to parse a full
+        # url as well
+        if url is None:
+            url = sys.argv[0]
+            if len(sys.argv) == 3:
+                url += sys.argv[2]
+        if handle is None:
+            handle = sys.argv[1]
+        return Request(url, handle)

kodiswift/request.py

@@ -0,0 +1,46 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.request
+------------------
+
+This module contains the Request class. This class represents an incoming
+request from Kodi.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import urlparse
+
+from kodiswift.common import unpickle_args
+
+__all__ = ['Request']
+
+
+class Request(object):
+
+    def __init__(self, url, handle):
+        """The request objects contains all the arguments passed to the plugin via
+        the command line.
+
+        Args:
+            url (str): The complete plugin URL being requested. Since Kodi
+                typically passes the URL query string in a separate argument
+                from the base URL, they must be joined into a single string
+                before being provided.
+            handle (Union[int, str]): The handle associated with the current
+                request.
+        """
+        self.url = url
+
+        #: The current request's handle, an integer.
+        self.handle = int(handle)
+
+        # urlparse doesn't like the 'plugin' scheme, so pass a protocol
+        # relative url, e.g. //plugin.video.helloxbmc/path
+        self.scheme, remainder = url.split(':', 1)
+        parts = urlparse.urlparse(remainder)
+        self.netloc, self.path, self.query_string = (
+            parts[1], parts[2], parts[4])
+        self.args = unpickle_args(urlparse.parse_qs(self.query_string))

kodiswift/storage.py

@@ -0,0 +1,163 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.storage
+-----------------
+
+This module contains persistent storage classes.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import collections
+import json
+import os
+import time
+import shutil
+from datetime import datetime
+
+try:
+    import cPickle as pickle
+except ImportError:
+    import pickle
+
+__all__ = ['Formats', 'PersistentStorage', 'TimedStorage', 'UnknownFormat']
+
+
+class UnknownFormat(Exception):
+    pass
+
+
+class Formats(object):
+    PICKLE = 'pickle'
+    JSON = 'json'
+
+
+class PersistentStorage(collections.MutableMapping):
+    def __init__(self, file_path, file_format=Formats.PICKLE):
+        """
+        Args:
+            file_path (str):
+            file_format (Optional[kodiswift.Formats]):
+        """
+        super(PersistentStorage, self).__init__()
+        self.file_path = file_path
+        self.file_format = file_format
+        self._store = {}
+        self._loaded = False
+
+    def __getitem__(self, key):
+        return self._store[key]
+
+    def __setitem__(self, key, value):
+        self._store[key] = value
+
+    def __delitem__(self, key):
+        del self._store[key]
+
+    def __iter__(self):
+        return iter(self._store)
+
+    def __len__(self):
+        return len(self._store)
+
+    def __enter__(self):
+        self.load()
+        self.sync()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.sync()
+
+    def __repr__(self):
+        return '%s(%r)' % (self.__class__.__name__, self._store)
+
+    def items(self):
+        return self._store.items()
+
+    def load(self):
+        """Load the file from disk.
+
+        Returns:
+            bool: True if successfully loaded, False if the file
+                doesn't exist.
+
+        Raises:
+            UnknownFormat: When the file exists but couldn't be loaded.
+        """
+
+        if not self._loaded and os.path.exists(self.file_path):
+            with open(self.file_path, 'rb') as f:
+                for loader in (pickle.load, json.load):
+                    try:
+                        f.seek(0)
+                        self._store = loader(f)
+                        self._loaded = True
+                        break
+                    except pickle.UnpicklingError:
+                        pass
+            # If the file exists and wasn't able to be loaded, raise an error.
+            if not self._loaded:
+                raise UnknownFormat('Failed to load file')
+        return self._loaded
+
+    def close(self):
+        self.sync()
+
+    def sync(self):
+        temp_file = self.file_path + '.tmp'
+        try:
+            with open(temp_file, 'wb') as f:
+                if self.file_format == Formats.PICKLE:
+                    pickle.dump(self._store, f, 2)
+                elif self.file_format == Formats.JSON:
+                    json.dump(self._store, f, separators=(',', ':'))
+                else:
+                    raise NotImplementedError(
+                        'Unknown file format ' + repr(self.file_format))
+        except Exception:
+            if os.path.exists(temp_file):
+                os.remove(temp_file)
+            raise
+        shutil.move(temp_file, self.file_path)
+
+
+class TimedStorage(PersistentStorage):
+    """A dict with the ability to persist to disk and TTL for items."""
+
+    def __init__(self, file_path, ttl=None, **kwargs):
+        """
+        Args:
+            file_path (str):
+            ttl (Optional[int]):
+        """
+        super(TimedStorage, self).__init__(file_path, **kwargs)
+        self.ttl = ttl
+
+    def __setitem__(self, key, value):
+        self._store[key] = (value, time.time())
+
+    def __getitem__(self, item):
+        val, timestamp = self._store[item]
+        ttl_diff = datetime.utcnow() - datetime.utcfromtimestamp(timestamp)
+        if self.ttl and ttl_diff > self.ttl:
+            del self._store[item]
+            raise KeyError
+        return val
+
+    def __repr__(self):
+        return '%s(%r)' % (self.__class__.__name__,
+                           dict((k, v[0]) for k, v in self._store.items()))
+
+    def items(self):
+        items = []
+        for k in self._store.keys():
+            try:
+                items.append((k, self[k]))
+            except KeyError:
+                pass
+        return items
+
+    def sync(self):
+        super(TimedStorage, self).sync()

kodiswift/urls.py

@@ -0,0 +1,212 @@
+# -*- coding: utf-8 -*-
+"""
+kodiswift.urls
+---------------
+
+This module contains URLRule class for dealing with url patterns.
+
+:copyright: (c) 2012 by Jonathan Beluch
+:license: GPLv3, see LICENSE for more details.
+"""
+from __future__ import absolute_import
+
+import re
+from urllib import urlencode, unquote_plus, quote_plus
+
+from kodiswift.common import pickle_dict, unpickle_dict
+
+__all__ = ['UrlRule', 'AmbiguousUrlException', 'NotFoundException']
+
+
+class AmbiguousUrlException(Exception):
+    pass
+
+
+class NotFoundException(Exception):
+    pass
+
+
+class UrlRule(object):
+    """A class the encapsulates a URL
+    """
+
+    def __init__(self, url_rule, view_func, name, options):
+        """Stores the various properties related to a routing URL rule.
+
+        It also provides a few methods to create URLs from the rule or to
+        match a given URL against a rule.
+
+        Args:
+            url_rule: The relative url pattern for the rule.
+                It may include <var_name> to denote where dynamic variables
+                should be matched.
+            view_func: The function that should be bound to this rule.
+                This should be an actual function object.
+            name: The name of the url rule. This is used in the reverse
+                process of creating urls for a given rule.
+            options: A dict containing any default values for the url rule.
+
+        Warnings:
+            view_func: The function signature should match any variable
+                names in the provided url_rule.
+        """
+        self._name = name
+        self._url_rule = url_rule
+        self._view_func = view_func
+        self._options = options or {}
+        self._keywords = re.findall(r'<(.+?)>', url_rule)
+
+        # change <> to {} for use with str.format()
+        self._url_format = self._url_rule.replace('<', '{').replace('>', '}')
+
+        # Make a regex pattern for matching incoming URLs
+        rule = self._url_rule
+        if rule != '/':
+            # Except for a path of '/', the trailing slash is optional.
+            rule = self._url_rule.rstrip('/') + '/?'
+        p = rule.replace('<', '(?P<').replace('>', '>[^/]+?)')
+
+        try:
+            self._regex = re.compile('^' + p + '$')
+        except re.error:
+            raise ValueError('There was a problem creating this URL rule. '
+                             'Ensure you do not have any unpaired angle '
+                             'brackets: "<" or ">"')
+
+    def __eq__(self, other):
+        if isinstance(other, UrlRule):
+            return (
+                (self._name, self._url_rule, self._view_func, self._options) ==
+                (other._name, other._url_rule, other._view_func, other._options)
+            )
+        else:
+            raise NotImplementedError
+
+    def __ne__(self, other):
+        return not self == other
+
+    def match(self, path):
+        """Attempts to match a url to the given path.
+
+        If successful, a tuple is returned. The first item is the matched
+        function and the second item is a dictionary containing items to be
+        passed to the function parsed from the provided path.
+
+        Args:
+            path (str): The URL path.
+
+        Raises:
+            NotFoundException: If the provided path does not match this
+                url rule.
+        """
+        m = self._regex.search(path)
+        if not m:
+            raise NotFoundException
+
+        # urlunencode the values
+        items = dict((key, unquote_plus(val))
+                     for key, val in m.groupdict().items())
+
+        # unpickle any items if present
+        items = unpickle_dict(items)
+
+        # We need to update our dictionary with default values provided in
+        # options if the keys don't already exist.
+        [items.setdefault(key, val) for key, val in self._options.items()]
+        return self._view_func, items
+
+    def _make_path(self, items):
+        """Returns a relative path for the given dictionary of items.
+
+        Uses this url rule's url pattern and replaces instances of <var_name>
+        with the appropriate value from the items dict.
+        """
+        for key, val in items.items():
+            if not isinstance(val, basestring):
+                raise TypeError('Value "%s" for key "%s" must be an instance'
+                                ' of basestring' % (val, key))
+            items[key] = quote_plus(val)
+
+        try:
+            path = self._url_format.format(**items)
+        except AttributeError:
+            # Old version of python
+            path = self._url_format
+            for key, val in items.items():
+                path = path.replace('{%s}' % key, val)
+        return path
+
+    def _make_qs(self, items):
+        """Returns a query string for the given dictionary of items. All keys
+        and values in the provided items will be urlencoded. If necessary, any
+        python objects will be pickled before being urlencoded.
+        """
+        return urlencode(pickle_dict(items))
+
+    def make_path_qs(self, items):
+        """Returns a relative path complete with query string for the given
+        dictionary of items.
+
+        Any items with keys matching this rule's url pattern will be inserted
+        into the path. Any remaining items will be appended as query string
+        parameters.
+
+        All items will be urlencoded. Any items which are not instances of
+        basestring, or int/long will be pickled before being urlencoded.
+
+        .. warning:: The pickling of items only works for key/value pairs which
+                     will be in the query string. This behavior should only be
+                     used for the simplest of python objects. It causes the
+                     URL to get very lengthy (and unreadable) and Kodi has a
+                     hard limit on URL length. See the caching section if you
+                     need to persist a large amount of data between requests.
+        """
+        # Convert any ints and longs to strings
+        for key, val in items.items():
+            if isinstance(val, (int, long)):
+                items[key] = str(val)
+
+        # First use our defaults passed when registering the rule
+        url_items = dict((key, val) for key, val in self._options.items()
+                         if key in self._keywords)
+
+        # Now update with any items explicitly passed to url_for
+        url_items.update((key, val) for key, val in items.items()
+                         if key in self._keywords)
+
+        # Create the path
+        path = self._make_path(url_items)
+
+        # Extra arguments get tacked on to the query string
+        qs_items = dict((key, val) for key, val in items.items()
+                        if key not in self._keywords)
+        qs = self._make_qs(qs_items)
+
+        if qs:
+            return '?'.join([path, qs])
+        return path
+
+    @property
+    def regex(self):
+        """The regex for matching paths against this url rule."""
+        return self._regex
+
+    @property
+    def view_func(self):
+        """The bound function"""
+        return self._view_func
+
+    @property
+    def url_format(self):
+        """The url pattern"""
+        return self._url_format
+
+    @property
+    def name(self):
+        """The name of this url rule."""
+        return self._name
+
+    @property
+    def keywords(self):
+        """The list of path keywords for this url rule."""
+        return self._keywords

kodiswift/xbmcmixin.py

@@ -0,0 +1,572 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import
+
+import os
+import warnings
+from datetime import timedelta
+from functools import wraps
+
+import kodiswift
+from kodiswift import xbmc, xbmcplugin, xbmcgui, CLI_MODE
+from kodiswift.constants import SortMethod
+from kodiswift.logger import log
+from kodiswift.storage import TimedStorage, UnknownFormat
+
+__all__ = ['XBMCMixin']
+
+# TODO(Sinap): Need to either break the single mixin into multiple or just use
+#              a parent class.
+
+
+# noinspection PyUnresolvedReferences,PyAttributeOutsideInit
+class XBMCMixin(object):
+    """A mixin to add Kodi helper methods. In order to use this mixin,
+    the child class must implement the following methods and
+    properties:
+
+        # Also, the child class is responsible for ensuring that this path
+        # exists.
+        self.storage_path
+
+        self.added_items
+
+        self.request
+
+        self.addon
+
+        _end_of_directory = False
+
+        _update_listing
+
+        self.handle
+
+    # optional
+    self.info_type: should be in ['video', 'music', 'pictures']
+    _memoized_storage = None
+    _unsynced_storage = None
+    # TODO: Ensure above is implemented
+    """
+
+    _function_cache_name = '.functions'
+
+    def cached(self, ttl=60 * 24):
+        """A decorator that will cache the output of the wrapped function.
+
+        The key used for the cache is the function name as well as the
+        `*args` and `**kwargs` passed to the function.
+
+        Args:
+            ttl: Time to live in minutes.
+
+        Notes:
+            ttl: For route caching, you should use
+                :meth:`kodiswift.Plugin.cached_route`.
+        """
+        def decorating_function(function):
+            storage = self.get_storage(
+                self._function_cache_name, file_format='pickle', ttl=ttl)
+            kwd_mark = 'f35c2d973e1bbbc61ca60fc6d7ae4eb3'
+
+            @wraps(function)
+            def wrapper(*args, **kwargs):
+                key = (function.__name__, kwd_mark) + args
+                if kwargs:
+                    key += (kwd_mark,) + tuple(sorted(kwargs.items()))
+
+                try:
+                    result = storage[key]
+                    log.debug('Storage hit for function "%s" with args "%s" '
+                              'and kwargs "%s"', function.__name__, args,
+                              kwargs)
+                except KeyError:
+                    log.debug('Storage miss for function "%s" with args "%s" '
+                              'and kwargs "%s"', function.__name__, args,
+                              kwargs)
+                    result = function(*args, **kwargs)
+                    storage[key] = result
+                    storage.sync()
+                return result
+
+            return wrapper
+
+        return decorating_function
+
+    def clear_function_cache(self):
+        """Clears the storage that caches results when using
+        :meth:`kodiswift.Plugin.cached_route` or
+        :meth:`kodiswift.Plugin.cached`.
+        """
+        self.get_storage(self._function_cache_name).clear()
+
+    def list_storage(self):
+        """Returns a list of existing stores.
+
+        The returned names can then be used to call get_storage().
+        """
+        # Filter out any storage used by kodiswift so caller doesn't corrupt
+        # them.
+        return [name for name in os.listdir(self.storage_path)
+                if not name.startswith('.')]
+
+    def get_storage(self, name='main', file_format='pickle', ttl=None):
+        """Returns a storage for the given name.
+
+        The returned storage is a fully functioning python dictionary and is
+        designed to be used that way. It is usually not necessary for the
+        caller to load or save the storage manually. If the storage does
+        not already exist, it will be created.
+
+        See Also:
+            :class:`kodiswift.TimedStorage` for more details.
+
+        Args:
+            name (str): The name  of the storage to retrieve.
+            file_format (str): Choices are 'pickle', 'csv', and 'json'.
+                Pickle is recommended as it supports python objects.
+
+                Notes: If a storage already exists for the given name, the
+                    file_format parameter is ignored. The format will be
+                    determined by the existing storage file.
+
+            ttl (int): The time to live for storage items specified in minutes
+                or None for no expiration. Since storage items aren't expired
+                until a storage is loaded form disk, it is possible to call
+                get_storage() with a different TTL than when the storage was
+                created. The currently specified TTL is always honored.
+
+        Returns:
+            kodiswift.storage.TimedStorage:
+        """
+        if not hasattr(self, '_unsynced_storage'):
+            self._unsynced_storage = {}
+        filename = os.path.join(self.storage_path, name)
+        try:
+            storage = self._unsynced_storage[filename]
+            log.debug('Loaded storage "%s" from memory', name)
+        except KeyError:
+            if ttl:
+                ttl = timedelta(minutes=ttl)
+            try:
+                storage = TimedStorage(filename, ttl, file_format=file_format)
+                storage.load()
+            except UnknownFormat:
+                # Thrown when the storage file is corrupted and can't be read.
+                # Prompt user to delete storage.
+                choices = ['Clear storage', 'Cancel']
+                ret = xbmcgui.Dialog().select(
+                    'A storage file is corrupted. It'
+                    ' is recommended to clear it.', choices)
+                if ret == 0:
+                    os.remove(filename)
+                    storage = TimedStorage(filename, ttl,
+                                           file_format=file_format)
+                else:
+                    raise Exception('Corrupted storage file at %s' % filename)
+
+            self._unsynced_storage[filename] = storage
+            log.debug('Loaded storage "%s" from disk', name)
+        return storage
+
+    def get_string(self, string_id):
+        """Returns the localized string from strings.po or strings.xml for the
+        given string_id.
+        """
+        string_id = int(string_id)
+        if not hasattr(self, '_strings'):
+            self._strings = {}
+        if string_id not in self._strings:
+            self._strings[string_id] = self.addon.getLocalizedString(string_id)
+        return self._strings[string_id]
+
+    def set_content(self, content):
+        """Sets the content type for the plugin."""
+        contents = ['files', 'songs', 'artists', 'albums', 'movies', 'tvshows',
+                    'episodes', 'musicvideos']
+        if content not in contents:
+            self.log.warning('Content type "%s" is not valid', content)
+        xbmcplugin.setContent(self.handle, content)
+
+    def get_setting(self, key, converter=None, choices=None):
+        """Returns the settings value for the provided key.
+
+        If converter is str, unicode, bool or int the settings value will be
+        returned converted to the provided type. If choices is an instance of
+        list or tuple its item at position of the settings value be returned.
+
+        Args:
+            key (str): The ID of the setting defined in settings.xml.
+            converter (Optional[str, unicode, bool, int]): How to convert the
+                setting value.
+                TODO(Sinap): Maybe this should just be a callable object?
+            choices (Optional[list,tuple]):
+
+        Notes:
+            converter: It is suggested to always use unicode for
+                text-settings because else xbmc returns utf-8 encoded strings.
+
+        Examples:
+            * ``plugin.get_setting('per_page', int)``
+            * ``plugin.get_setting('password', unicode)``
+            * ``plugin.get_setting('force_viewmode', bool)``
+            * ``plugin.get_setting('content', choices=('videos', 'movies'))``
+        """
+        # TODO: allow pickling of settings items?
+        # TODO: STUB THIS OUT ON CLI
+        value = self.addon.getSetting(key)
+        if converter is str:
+            return value
+        elif converter is unicode:
+            return value.decode('utf-8')
+        elif converter is bool:
+            return not(value.lower()=="false" or value=="0")
+        elif converter is int:
+            return int(value)
+        elif isinstance(choices, (list, tuple)):
+            return choices[int(value)]
+        elif converter is None:
+            log.warning('No converter provided, unicode should be used, '
+                        'but returning str value')
+            return value
+        else:
+            raise TypeError('Acceptable converters are str, unicode, bool and '
+                            'int. Acceptable choices are instances of list '
+                            ' or tuple.')
+
+    def set_setting(self, key, val):
+        # TODO: STUB THIS OUT ON CLI - setSetting takes id=x, value=x throws an error otherwise
+        return self.addon.setSetting(id=key, value=val)
+
+    def load_addon_settings(self):
+        """ Mock loading addon settings from user_data/settings.xml file.
+        If settings.xml does no exists, create using default values"""
+        if not CLI_MODE:
+            return
+        from xml.dom.minidom import parse
+        xml = parse(os.path.join("resources","language","English","strings.xml"))
+        self.addon._strings = dict((tag.getAttribute('id'), tag.firstChild.data) for tag in xml.getElementsByTagName('string'))
+        settings_file = os.path.join("addon_data","settings.xml")
+        if not os.path.exists(settings_file):
+            xml = parse(os.path.join("resources","settings.xml"))
+            self.addon._settings = dict((tag.getAttribute('id'), tag.attributes["default"].value)for tag in xml.getElementsByTagName('setting') if "id" in tag.attributes.keys())
+            if not os.path.exists("addon_data"):
+                os.mkdir("addon_data")
+            with open(settings_file,"w") as f:
+                f.write("<settings>\n")
+                for s in self.addon._settings:
+                    f.write('    <setting id="%s" value="%s" />\n'%(s,self.addon._settings[s]))
+                f.write("</settings>\n")
+        else:
+            xml = parse(settings_file)
+            self.addon._settings = dict((tag.getAttribute('id'), tag.attributes["value"].value) for tag in xml.getElementsByTagName('setting'))
+
+    def open_settings(self):
+        """Opens the settings dialog within Kodi"""
+        self.addon.openSettings()
+
+    @staticmethod
+    def add_to_playlist(items, playlist='video'):
+        """Adds the provided list of items to the specified playlist.
+        Available playlists include *video* and *music*.
+        """
+        playlists = {'music': 0, 'video': 1}
+        if playlist not in playlists:
+            raise ValueError('Playlist "%s" is invalid.' % playlist)
+
+        selected_playlist = xbmc.PlayList(playlists[playlist])
+        _items = []
+        for item in items:
+            if not hasattr(item, 'as_xbmc_listitem'):
+                if 'info_type' in item:
+                    log.warning('info_type key has no affect for playlist '
+                                'items as the info_type is inferred from the '
+                                'playlist type.')
+                # info_type has to be same as the playlist type
+                item['info_type'] = playlist
+                item = kodiswift.ListItem.from_dict(**item)
+            _items.append(item)
+            selected_playlist.add(item.get_path(), item.as_xbmc_listitem())
+        return _items
+
+    @staticmethod
+    def get_view_mode_id(view_mode):
+        warnings.warn('get_view_mode_id is deprecated.', DeprecationWarning)
+        return None
+
+    @staticmethod
+    def set_view_mode(view_mode_id):
+        """Calls Kodi's Container.SetViewMode. Requires an integer
+        view_mode_id"""
+        xbmc.executebuiltin('Container.SetViewMode(%d)' % view_mode_id)
+
+    def keyboard(self, default=None, heading=None, hidden=False):
+        """Displays the keyboard input window to the user. If the user does not
+        cancel the modal, the value entered by the user will be returned.
+
+        :param default: The placeholder text used to prepopulate the input
+                        field.
+        :param heading: The heading for the window. Defaults to the current
+                        addon's name. If you require a blank heading, pass an
+                        empty string.
+        :param hidden: Whether or not the input field should be masked with
+                       stars, e.g. a password field.
+        """
+        if heading is None:
+            heading = self.addon.getAddonInfo('name')
+        if default is None:
+            default = ''
+        keyboard = xbmc.Keyboard(default, heading, hidden)
+        keyboard.doModal()
+        if keyboard.isConfirmed():
+            return keyboard.getText()
+
+    def notify(self, msg='', title=None, delay=5000, image=''):
+        """Displays a temporary notification message to the user. If
+        title is not provided, the plugin name will be used. To have a
+        blank title, pass '' for the title argument. The delay argument
+        is in milliseconds.
+        """
+        if not image:
+            image = xbmcgui.NOTIFICATION_INFO
+        if not msg:
+            log.warning('Empty message for notification dialog')
+        if title is None:
+            title = self.addon.getAddonInfo('name')
+        if isinstance(msg,unicode):
+            msg = msg.encode("utf8")
+        if isinstance(title,unicode):
+            title = title.encode("utf8")
+        xbmcgui.Dialog().notification(title, msg, image, delay)
+        #xbmc.executebuiltin('Notification("%s", "%s", "%s", "%s")' % (msg, title, delay, image))
+
+    def set_resolved_url(self, item=None, subtitles=None):
+        """Takes a url or a listitem to be played. Used in conjunction with a
+        playable list item with a path that calls back into your addon.
+
+        :param item: A playable list item or url. Pass None to alert Kodi of a
+                     failure to resolve the item.
+
+                     .. warning:: When using set_resolved_url you should ensure
+                                  the initial playable item (which calls back
+                                  into your addon) doesn't have a trailing
+                                  slash in the URL. Otherwise it won't work
+                                  reliably with Kodi's PlayMedia().
+        :param subtitles: A URL to a remote subtitles file or a local filename
+                          for a subtitles file to be played along with the
+                          item.
+        """
+        if self._end_of_directory:
+            raise Exception('Current Kodi handle has been removed. Either '
+                            'set_resolved_url(), end_of_directory(), or '
+                            'finish() has already been called.')
+        self._end_of_directory = True
+
+        succeeded = True
+        if item is None:
+            # None item indicates the resolve url failed.
+            item = {}
+            succeeded = False
+
+        if isinstance(item, basestring):
+            # caller is passing a url instead of an item dict
+            item = {'path': item}
+
+        item = self._listitemify(item)
+        item.set_played(True)
+        xbmcplugin.setResolvedUrl(self.handle, succeeded,
+                                  item.as_xbmc_listitem())
+
+        # call to _add_subtitles must be after setResolvedUrl
+        if subtitles:
+            if isinstance(subtitles,list):
+                for subtitle in subtitles:
+                    self._add_subtitles(subtitle)
+            else:
+                self._add_subtitles(subtitles)
+
+        return [item]
+
+    def play_video(self, item, player=None):
+        if isinstance(item, dict):
+            item['info_type'] = 'video'
+
+        item = self._listitemify(item)
+        item.set_played(True)
+        if player:
+            _player = xbmc.Player(player)
+        else:
+            _player = xbmc.Player()
+        _player.play(item.get_path(), item.as_xbmc_listitem())
+        return [item]
+
+    def add_items(self, items):
+        """Adds ListItems to the Kodi interface.
+
+        Each item in the provided list should either be instances of
+        kodiswift.ListItem, or regular dictionaries that will be passed
+        to kodiswift.ListItem.from_dict.
+
+        Args:
+            items: An iterable of items where each item is either a
+                dictionary with keys/values suitable for passing to
+                :meth:`kodiswift.ListItem.from_dict` or an instance of
+                :class:`kodiswift.ListItem`.
+
+        Returns:
+            kodiswift.ListItem: The list of ListItems.
+        """
+        _items = [self._listitemify(item) for item in items]
+        tuples = [item.as_tuple() for item in _items if hasattr(item, 'as_tuple')]
+        xbmcplugin.addDirectoryItems(self.handle, tuples, len(tuples))
+
+        # We need to keep track internally of added items so we can return them
+        # all at the end for testing purposes
+        self.added_items.extend(_items)
+
+        # Possibly need an if statement if only for debug mode
+        return _items
+
+    def add_sort_method(self, sort_method, label2_mask=None):
+        """A wrapper for `xbmcplugin.addSortMethod()
+        <http://mirrors.xbmc.org/docs/python-docs/xbmcplugin.html#-addSortMethod>`_.
+        You can use ``dir(kodiswift.SortMethod)`` to list all available sort
+        methods.
+
+        Args:
+            sort_method: A valid sort method. You can provided the constant
+                from xbmcplugin, an attribute of SortMethod, or a string name.
+                For instance, the following method calls are all equivalent:
+                 * ``plugin.add_sort_method(xbmcplugin.SORT_METHOD_TITLE)``
+                 * ``plugin.add_sort_method(SortMethod.TITLE)``
+                 * ``plugin.add_sort_method('title')``
+            label2_mask: A mask pattern for label2. See the `Kodi
+                documentation <http://mirrors.xbmc.org/docs/python-docs/xbmcplugin.html#-addSortMethod>`_
+                for more information.
+        """
+        try:
+            # Assume it's a string and we need to get the actual int value
+            sort_method = SortMethod.from_string(sort_method)
+        except AttributeError:
+            # sort_method was already an int (or a bad value)
+            pass
+
+        if label2_mask:
+            xbmcplugin.addSortMethod(self.handle, sort_method, label2_mask)
+        else:
+            xbmcplugin.addSortMethod(self.handle, sort_method)
+
+    def end_of_directory(self, succeeded=True, update_listing=False,
+                         cache_to_disc=True):
+        """Wrapper for xbmcplugin.endOfDirectory. Records state in
+        self._end_of_directory.
+
+        Typically it is not necessary to call this method directly, as
+        calling :meth:`~kodiswift.Plugin.finish` will call this method.
+        """
+        self._update_listing = update_listing
+        if not self._end_of_directory:
+            self._end_of_directory = True
+            # Finalize the directory items
+            return xbmcplugin.endOfDirectory(self.handle, succeeded,
+                                             update_listing, cache_to_disc)
+        else:
+            raise Exception('Already called endOfDirectory.')
+
+    def finish(self, items=None, sort_methods=None, succeeded=True,
+               update_listing=False, cache_to_disc=True, view_mode=None):
+        """Adds the provided items to the Kodi interface.
+
+        Args:
+            items (List[Dict[str, str]]]): an iterable of items where each
+                item is either a dictionary with keys/values suitable for
+                passing to :meth:`kodiswift.ListItem.from_dict` or an
+                instance of :class:`kodiswift.ListItem`.
+
+            sort_methods (Union[List[str], str]): A list of valid Kodi
+                sort_methods. Each item in the list can either be a sort
+                method or a tuple of `sort_method, label2_mask`.
+                See :meth:`add_sort_method` for more detail concerning
+                valid sort_methods.
+
+            succeeded (bool):
+            update_listing (bool):
+            cache_to_disc (bool): Whether to tell Kodi to cache this folder
+                to disk.
+            view_mode (Union[str, int]): Can either be an integer
+                (or parsable integer string) corresponding to a view_mode or
+                the name of a type of view. Currently the only view type
+                supported is 'thumbnail'.
+
+        Returns:
+            List[kodiswift.listitem.ListItem]: A list of all ListItems added
+                to the Kodi interface.
+        """
+        # If we have any items, add them. Items are optional here.
+        if items:
+            self.add_items(items)
+        if sort_methods:
+            for sort_method in sort_methods:
+                if isinstance(sort_method, (list, tuple)):
+                    self.add_sort_method(*sort_method)
+                else:
+                    self.add_sort_method(sort_method)
+
+        # Attempt to set a view_mode if given
+        if view_mode is not None:
+            # First check if we were given an integer or parsable integer
+            try:
+                view_mode_id = int(view_mode)
+            except ValueError:
+                view_mode_id = None
+            if view_mode_id is not None:
+                self.set_view_mode(view_mode_id)
+
+        # Finalize the directory items
+        self.end_of_directory(succeeded, update_listing, cache_to_disc)
+
+        # Return the cached list of all the list items that were added
+        return self.added_items
+
+    def _listitemify(self, item):
+        """Creates an kodiswift.ListItem if the provided value for item is a
+        dict. If item is already a valid kodiswift.ListItem, the item is
+        returned unmodified.
+        """
+        info_type = self.info_type if hasattr(self, 'info_type') else 'video'
+
+        # Create ListItems for anything that is not already an instance of
+        # ListItem
+        if not hasattr(item, 'as_tuple') and hasattr(item, 'keys'):
+            if 'info_type' not in item:
+                item['info_type'] = info_type
+            item = kodiswift.ListItem.from_dict(**item)
+        return item
+
+    @staticmethod
+    def _add_subtitles(subtitles):
+        """Adds subtitles to playing video.
+
+        Warnings:
+            You must start playing a video before calling this method or it
+            will raise and Exception after 30 seconds.
+
+        Args:
+            subtitles (str): A URL to a remote subtitles file or a local
+                filename for a subtitles file.
+        """
+        # This method is named with an underscore to suggest that callers pass
+        # the subtitles argument to set_resolved_url instead of calling this
+        # method directly. This is to ensure a video is played before calling
+        # this method.
+        player = xbmc.Player()
+        monitor = xbmc.Monitor()
+        while not monitor.abortRequested():
+            if monitor.waitForAbort(30):
+                # Abort requested, so exit.
+                break
+            elif player.isPlaying():
+                # No abort requested after 30 seconds and a video is playing
+                # so add the subtitles and exit.
+                player.setSubtitles(subtitles)
+                break
+            else:
+                raise Exception('No video playing. Aborted after 30 seconds.')