t0mm0.common.addon

class t0mm0.common.addon.Addon(addon_id, argv=None)

This class provides a lot of code that is used across many XBMC addons in the hope that it will simplify some of the common tasks an addon needs to perform.

Mostly this is achieved by providing a wrapper around commonly used parts of xbmc, xbmcaddon, xbmcgui and xbmcplugin.

You probably want to have exactly one instance of this class in your addon which you can call from anywhere in your code.

Example:

import sys
from t0mm0.common.addon import Addon
addon = Addon('my.plugin.id', argv=sys.argv)

Args:

addon_id (str): Your addon’s id (eg. ‘plugin.video.t0mm0.test’).

Kwargs:

argv (list): List of arguments passed to your addon if applicable (eg. sys.argv).

add_directory(queries, infolabels, img='', fanart='', total_items=0, is_folder=True)

Convenience method to add a directory to the display list or a playlist.

See add_item() for full infomation

add_item(queries, infolabels, img='', fanart='', resolved=False, total_items=0, playlist=False, item_type='video', is_folder=False)

Adds an item to the list of entries to be displayed in XBMC or to a playlist.

Use this method when you want users to be able to select this item to start playback of a media file. queries is a dict that will be sent back to the addon when this item is selected:

add_item({'host': 'youtube.com', 'media_id': 'ABC123XYZ'}, 
         {'title': 'A youtube vid'})

will add a link to:

plugin://your.plugin.id/?host=youtube.com&media_id=ABC123XYZ

See also

add_music_item(), add_video_item(), add_directory()

Args:

queries (dict): A set of keys/values to be sent to the addon when the user selects this item.

infolabels (dict): A dictionary of information about this media (see the XBMC Wiki InfoLabels entry).

Kwargs:

img (str): A URL to an image file to be used as an icon for this entry.

fanart (str): A URL to a fanart image for this entry.

resolved (str): If not empty, queries will be ignored and instead the added item will be the exact contentes of resolved.

total_items (int): Total number of items to be added in this list. If supplied it enables XBMC to show a progress bar as the list of items is being built.

playlist (playlist object): If False (default), the item will be added to the list of entries to be displayed in this directory. If a playlist object is passed (see get_playlist()) then the item will be added to the playlist instead

item_type (str): The type of item to add (eg. ‘music’, ‘video’ or ‘pictures’)

add_music_item(queries, infolabels, img='', fanart='', resolved=False, total_items=0, playlist=False)

Convenience method to add a music item to the directory list or a playlist.

See add_item() for full infomation

add_video_item(queries, infolabels, img='', fanart='', resolved=False, total_items=0, playlist=False)

Convenience method to add a video item to the directory list or a playlist.

See add_item() for full infomation

build_plugin_url(queries)

Returns a plugin:// URL which can be used to call the addon with the specified queries.

Example:

>>> addon.build_plugin_url({'name': 'test', 'type': 'basic'})
'plugin://your.plugin.id/?name=test&type=basic'

Args:

queries (dict): A dctionary of keys/values to be added to the plugin:// URL.

Retuns:

A string containing a fully formed plugin:// URL.

decode(data)

Regular expression to convert entities such as &#044 to the correct characters. It is called by unescape() and so it is not required to call it directly.

This method was found on the web

Args:

data (str): String to be cleaned.

Returns:

Cleaned string.

end_of_directory()

Tell XBMC that we have finished adding items to this directory.

get_author()

Returns the addon author as defined in addon.xml.

get_changelog()

Returns the addon changelog.

get_description()

Returns the addon description as defined in addon.xml.

get_disclaimer()

Returns the addon disclaimer as defined in addon.xml.

get_fanart()

Returns the full path to the addon fanart.

get_icon()

Returns the full path to the addon icon.

get_id()

Returns the addon id as defined in addon.xml.

get_music_playlist(new=False)

Convenience method to return a music xbmc.Playlist object.

See also

get_playlist()

Kwargs:

new (bool): If False (default), get the current music xbmc.Playlist object. If True then return a new blank music xbmc.Playlist.

Returns:

A xbmc.Playlist object.

get_name()

Returns the addon name as defined in addon.xml.

get_path()

Returns the full path to the addon directory.

get_playlist(pl_type, new=False)

Return a xbmc.Playlist object of the specified type.

The available playlist types are defined in the xbmc module and are currently as follows:

xbmc.PLAYLIST_MUSIC = 0
xbmc.PLAYLIST_VIDEO = 1

See also

get_music_playlist(), get_video_playlist()

Args:

pl_type (int): The type of playlist to get.

new (bool): If False (default), get the current xbmc.Playlist object of the type specified. If True then return a new blank xbmc.Playlist.

Returns:

A xbmc.Playlist object.

get_profile()

Returns the full path to the addon profile directory (useful for storing files needed by the addon such as cookies).

get_setting(setting)

Returns an addon setting. Settings must be defined in your addon’s resources/settings.xml file.

Args:

setting (str): Name of the setting to be retrieved.

Returns:

str containing the requested setting.

get_stars()

Returns the number of stars for this addon.

get_string(string_id)

Returns a localized string. Strings must be defined in your addon’s resources/language/[lang_name]/strings.xml file.

Args:

string_id (int): id of the translated string to retrieve.

Returns:

str containing the localized requested string.

get_summary()

Returns the addon summary as defined in addon.xml.

get_type()

Returns the addon summary as defined in addon.xml (eg. xbmc.python.pluginsource).

get_version()

Returns the addon version as defined in addon.xml.

get_video_playlist(new=False)

Convenience method to return a video xbmc.Playlist object.

See also

get_playlist()

Kwargs:

new (bool): If False (default), get the current video xbmc.Playlist object. If True then return a new blank video xbmc.Playlist.

Returns:

A xbmc.Playlist object.

load_data(filename)

Load the data that was saved with save_data() and returns the data structure.

Args:

filename (string): Name of the file you want to load data from. This file will be loaded from your addons profile directory.

Returns:

Data stucture on success False on failure

log(msg, level=2)

Writes a string to the XBMC log file. The addon name is inserted into the beginning of the message automatically to help you find relevent messages in the log file.

The available log levels are defined in the xbmc module and are currently as follows:

xbmc.LOGDEBUG = 0
xbmc.LOGERROR = 4
xbmc.LOGFATAL = 6
xbmc.LOGINFO = 1
xbmc.LOGNONE = 7
xbmc.LOGNOTICE = 2
xbmc.LOGSEVERE = 5
xbmc.LOGWARNING = 3

Args:

msg (str or unicode): The message to be written to the log file.

Kwargs:

level (int): The XBMC log level to write at.

log_debug(msg)

Convenience method to write to the XBMC log file at the xbmc.LOGDEBUG error level. Use this when you want to print out lots of detailed information that is only usefull for debugging. This will show up in the log only when debugging is enabled in the XBMC settings, and will be prefixed with ‘DEBUG:’.

log_error(msg)

Convenience method to write to the XBMC log file at the xbmc.LOGERROR error level. Use when something has gone wrong in your addon code. This will show up in the log prefixed with ‘ERROR:’ whether you have debugging switched on or not.

log_notice(msg)

Convenience method to write to the XBMC log file at the xbmc.LOGNOTICE error level. Use for general log messages. This will show up in the log prefixed with ‘NOTICE:’ whether you have debugging switched on or not.

parse_query(query, defaults={'mode': 'main'})

Parse a query string as used in a URL or passed to your addon by XBMC.

Example:

>>> addon.parse_query('name=test&type=basic')
{'mode': 'main', 'name': 'test', 'type': 'basic'} 

Args:

query (str): A query string.

Kwargs:

defaults (dict): A dictionary containing key/value pairs parsed from the query string. If a key is repeated in the query string its value will be a list containing all of that keys values.

resolve_url(stream_url)

Tell XBMC that you have resolved a URL (or not!).

This method should be called as follows:

1. The user selects a list item that has previously had isPlayable set (this is true for items added with add_item(), add_music_item() or add_music_item())
2. Your code resolves the item requested by the user to a media URL
3. Your addon calls this method with the resolved URL

Args:

stream_url (str or False): If a string, tell XBMC that the media URL ha been successfully resolved to stream_url. If False or an empty string tell XBMC the resolving failed and pop up an error messsage.

save_data(filename, data)

Saves the data structure using pickle. If the addon data path does not exist it will be automatically created. This save function has the same restrictions as the pickle module.

Args:

filename (string): name of the file you want to save data to. This file will be saved in your addon’s profile directory.

data (data object/string): you want to save.

Returns:

True on success False on failure

show_error_dialog(msg)

Convenience method to show an XBMC dialog box with a single OK button and also write the message to the log file at the ERROR log level.

The title of the dialog will be the addon’s name with the prefix ‘Error: ‘.

Warning

Don’t forget that msg must be a list of strings and not just a string even if you only want to display a single line!

Args:

msg (list of strings): The message to be displayed in the dialog. Only the first 3 list items will be displayed.

show_ok_dialog(msg, title=None, is_error=False)

Display an XBMC dialog with a message and a single ‘OK’ button. The message is also written to the XBMC log file at the appropriate log level.

Warning

Don’t forget that msg must be a list of strings and not just a string even if you only want to display a single line!

Example:

addon.show_ok_dialog(['My message'], 'My Addon')

Args:

msg (list of strings): The message to be displayed in the dialog. Only the first 3 list items will be displayed.

Kwargs:

title (str): String to be displayed as the title of the dialog box. Defaults to the addon name.

is_error (bool): If True, the log message will be written at the ERROR log level, otherwise NOTICE will be used.

show_settings()

Shows the settings dialog for this addon.

show_small_popup(title='', msg='', delay=5000, image='')

Displays a small popup box in the lower right corner. The default delay is 5 seconds.

Code inspired by anarchintosh and daledude’s Icefilms addon.

Example:

import os
logo = os.path.join(addon.get_path(), 'art','logo.jpg')
addon.show_small_popup('MyAddonName','Is now loaded enjoy', 5000, logo)

Kwargs:

title (str): title to be displayed at the top of the box

msg (str): Main message body

delay (int): delay in milliseconds until it disapears

image (str): Path to the image you want to display

unescape(text)

Decodes HTML entities in a string.

You can add more entities to the rep dictionary.

Args:

text (str): String to be cleaned.

Returns:

Cleaned string.

unescape_dict(d)

Calls unescape() on all values in a dictionary.

Args:

d (dict): A dictionary containing string values

Returns:

A dictionary with HTML entities removed from the values.