Plugin routing
Library for building and parsing URLs in Kodi plugins.
Example
import routing
from xbmcgui import ListItem
from xbmcplugin import addDirectoryItem, endOfDirectory
plugin = routing.Plugin()
@plugin.route('/')
def index():
addDirectoryItem(plugin.handle, plugin.url_for(show_category, "one"), ListItem("Category One"), True)
addDirectoryItem(plugin.handle, plugin.url_for(show_category, "two"), ListItem("Category Two"), True)
addDirectoryItem(plugin.handle, plugin.url_for(show_directory, "/dir/one"), ListItem("Directory One"), True)
addDirectoryItem(plugin.handle, plugin.url_for(show_directory, "/dir/two"), ListItem("Directory Two"), True)
endOfDirectory(plugin.handle)
@plugin.route('/category/<category_id>')
def show_category(category_id):
addDirectoryItem(plugin.handle, "", ListItem("Hello category %s!" % category_id))
endOfDirectory(plugin.handle)
@plugin.route('/directory/<path:dir>')
def show_directory(dir):
addDirectoryItem(plugin.handle, "", ListItem("List directory %s!" % dir))
endOfDirectory(plugin.handle)
if __name__ == '__main__':
plugin.run()Creating rules
The route() decorator binds a function to an URL pattern. The pattern is a
path expression consisting of static parts and variable parts of an URL.
Variables are enclosed in angle brackets as <variable_name> and will be passed
to the function as keyword arguments.
For example:
@plugin.route('/hello/<what>')
def hello(what):
# will be called for all incoming URLs like "/hello/world", "/hello/123" etc.
# 'what' will contain "world", "123" etc. depending on the URL.
passIn case your variable contains slashes (i.e. is a path or URL) and you want
to match this, you can use the path identifier in the patern.
@plugin.route('/url/<path:url>')
def parse_url(url):
# will be called for all incoming URLs like "/url/https://foo.bar/baz" etc.
# 'url' can be any string with slashes.
passRoutes can also be registered manually with the add_route method.
Building URLs
url_for() can be used to build URLs for registered functions. It takes a
reference to a function and a number of arguments that corresponds to variables
in the URL rule.
For example:
plugin.url_for(hello, what="world")will read the rule for hello, fill in the variable parts and return a final URL:
plugin://my.addon.id/hello/world
which can be passed to xbmcplugin.addDirectoryItem(). All variable parts must
be passed to url_for either as ordered arguments or keyword arguments.
Keywords that does not occur in the function/pattern will be added as query string in the returned URL.
Alternatively, URLs can be created directly from a path with url_for_path. For
example url_for_path('/foo/bar') will return plugin://my.addon.id/foo/bar.
Unlike url_for this method will not check that the path is valid.
Query string
The query string part of the URL is parsed with urlparse.parse_qs and is
accessible via the plugin.args attribute. The dictionary keys corresponds to
query variables and values to lists of query values.
Example:
@plugin.route('/')
def index():
url = plugin.url_for(search, query="hello world")
addDirectoryItem(plugin.handle, url, ListItem("Search"))
# ...
@plugin.route('/search')
def search():
query = plugin.args['query'][0]
addDirectoryItem(plugin.handle, "", ListItem("You searched for '%s'" % query))
# ...Creating a dependency in your addon
To get kodi to install this dependency you will have to add a command to your addons.xml.
<requires>
<import addon="xbmc.python" version="2.25.0" />
<import addon="script.module.routing" version="0.2.0"/>
</requires>