Merge branch 'develop' for release 0.3.0.

.gitignore

@@ -9,3 +9,4 @@ XBMC_Swift.egg-info/
 docs/_build/
 TODO
 XBMC_Swift.egg-info/
+xbmcswift2.egg-info/

AUTHORS

@@ -12,3 +12,5 @@ Patches and Suggestions
 - Tristan Fischer (sphere@dersphere.de)
 - beenje
 - takoi
+- cancan101
+- ulion

CHANGES

@@ -1,7 +1,34 @@
 0.3
 ===
 
-Unreleased.
+- Allow ints to be passed to plugin.url_for() and str() them.
+- plugin.set_resolved_url() now takes an item dict instead of a URL. (The URL
+  is still allowed for backwards compatibility but is decprecated).
+- Ability to replace the context menu items by setting 'replace_context_menu'
+  to True in an item dict.
+- pluign.get_setting() now requires an extra paramter, *converter*, which
+  converts the item from XML to a python type specified by converter.
+- Major bug fix to accomodate handles > 0 in XBMC Frodo.
+- Auto-call plugin.finish(succeeded=False) if a view returns None.
+- XBMC now decides the default player when using plugin.play_video().
+- Storages now call sync() when clear() is called.
+- Added plugin.clear_function_cache() which clears the storage behind the
+  @cached and @cached_route decorators.
+- Add ability to set stream info for list items. Also, devs can now add
+  stream_info to item dicts.
+- Added the actions module. Contains actions.background() and
+  actions.update_view() which are convenience wrappers for RunPlugin() and
+  Container.Update().
+- Allow passing of functions to url_for.
+- 'properties' key in an item dict should now be a dictionary. A list of tuples
+  is still allowed for backwards compatibility.
+- Addon user is now prompted and storage automatically cleared if it becomes
+  corrupted.
+- Added subtitles support. A 'subtitles' parameter was added to
+  plugin.set_resolved_url().
+- xbmcswift2 URLs and routing code is now indifferent to a trailing slash.
+- Bug fixes. See https://github.com/jbeluch/xbmcswift2/issues?milestone=3.
+
 
 0.2.2
 =====

README.md

@@ -60,8 +60,13 @@ Bugs, patches and suggestions are all welcome. I'm working on adding tests and
 getting better coverage. Please ensure that your patches include tests as well
 as updates to the documentation. Thanks!
 
-## Contact
+## Support
+
+\#xbmcswift on freenode
 
 https://github.com/jbeluch/xbmcswift2
 
+Subscribe to the mailing list to be notified of new releases or to get help.
+Send an email to xbmcswift@librelist.com to subscribe.
+
 web@jonathanbeluch.com

docs/api.rst

@@ -31,9 +31,18 @@ Request
     :inherited-members:
 
 
+Actions
+-------
+
+.. automodule:: xbmcswift2.actions
+    :members:
+
+
 Extended API
 ------------
 
+.. module:: xbmcswift2 
+
 Module
 ``````
 

docs/caching.rst

@@ -1,14 +1,19 @@
 .. _caching:
 
 
-Caching
-=======
+Caching and Storage
+===================
 
-xbmcswift2 offers lots of caching options to help improve the user experience
-for your addon. xbmcswift2 offers a storage mechanism that allows you to store
-arbitrary python objects to use across requests. The storage options also allow
-for an optionan lifetime to be specified for each object.
+xbmcswift2 offers a few options for caching and storage to help improve the
+user experience of your addon. swift offers a simple storage mechanism that
+allows you to store arbitraty python objects to use between requests.
 
+.. warning::
+
+    The current implementation of xbmcswift2's storage is very basic and is not
+    thread safe. If your addon does background calls via the context menu and
+    manipulates storages in these backgound threads, you might run into some
+    issues.
 
 Storing Arbitraty Python Objects
 --------------------------------
@@ -61,7 +66,7 @@ time the addon is run. So we can use the caching decorator with a TTL argument.
 
 .. sourcecode:: python
 
-    @plugin.cache(TTL=60*24)
+    @plugin.cached(TTL=60*24)
     def get_api_data();
         # make remote request
         data = get_remote_data()
@@ -90,6 +95,10 @@ for this decorator; it defaults to 24 hours.
              cache the view. See the below section 'Caveats' for more
              information.
 
+.. warning:: It is currently only possible to attach a single cached_route to a
+             view. If you have multiple routes on a given view, try refactoring
+             some logic out to a new function that can be cached, instead of
+             using the cached_route decorator.
 Caveats
 -------
 

docs/commandline.rst

@@ -1,32 +1,41 @@
 .. _commandline:
 
 
-Running Addons on the Command Line
-==================================
+Running xbmcswift2 on the Command Line
+======================================
 
 
-Options
--------
+Commands
+--------
 
-To see the command line help, simply execute ``xbmcswift2 run -h``.::
+When running xbmcswift2 from the command line, there are two commands
+available, *create* and *run*. *create* is a script that will create the basic
+scaffolding and necessary files for an XBMC addon and personalize it by asking
+you a few questions. *run* enables you to debug your addon on the command line.
 
-    $ xbmcswift2 run -h
-    Usage: xbmcswift2 run [once|interactive|crawl] [url]
+To see the command line help, simply execute ``xbmcswift2 -h``. Both of the
+commands are explained further below.
 
-    Options:
-      -h, --help     show this help message and exit
-      -q, --quiet    set logging level to quiet
-      -v, --verbose  set logging level to verbose
 
+create
+~~~~~~
 
-There are three different run modes available, once_ (default),
-interactive_, and crawl_.
+To create a new addon, change your current working directory to a location
+where you want your addon folder to be created. Then execute ``xbmcswift2
+create``. After answering a few questions, you should have the basic addon
+structure in place.
 
-There is also a second positional argument which is optional, ``url``. By
-default, xbmcswift2 will run the root URL,
+run
+~~~
+
+When running an addon on the command line, there are three different run modes
+available, once_, interactive_, and crawl_. 
+
+There is also a second positional argument, ``url``, which is optional. By
+default, xbmcswift2 will run the root URL of your addon (a path of '/'), e.g.
 ``plugin://plugin.video.academicearth/``. This is the same default URL that
-XBMC uses when you first enter an addon. You can gather runnable URLs from the
-output of xbmcswift2.
+XBMC uses when you first enter an addon. You can gather URLs from the output of
+xbmcswift2.
 
 The options ``-q`` and ``-v`` decrease and increase the logging level.
 
@@ -35,44 +44,58 @@ The options ``-q`` and ``-v`` decrease and increase the logging level.
     To enable running on the command line, xbmcswift2 attempts to mock a
     portion of the XBMC python bindings. Certain functions behave properly like
     looking up strings. However, if a function has not been implemented,
-    xbmcswift2 lets the function call pass silently to avoid Exceptions and
-    allow the plugin to run in a limited fashion. This is why you'll very often
-    see WARNING log messages when running on the command line.
+    xbmcswift2 lets the function call pass silently to avoid exceptions and
+    allow the plugin to run in a limited fashion. This is why you'll often see
+    WARNING log messages when running on the command line.
 
-    This is also why you should import the xbmc python modules from xbmcswift2::
+    If you plan on using the command line to develop your addons, you should
+    always import the xbmc modules from xbmcswift2::
 
         from xbcmswift2 import xbmcgui
 
-    xbmcswift2 will correctly import the proper XBMC modules in the correct
-    environments so you don't have to worry about it.
-
-
+    xbmcswift2 will correctly import the proper module based on the
+    environment. When running in XBMC, it will import the actual modules, and
+    when running on the command line it will import mocked modules without
+    error.
 
 
 once
-~~~~
+____
 
 Executes the addon once then quits. Useful for testing when used
 with the optional ``url`` argument.::
 
-    $ xbmcswift2 run once 2>/dev/null
+    $ xbmcswift2 run once # you can omit the once argument as it is the default
+
     ------------------------------------------------------------
      #  Label    Path
     ------------------------------------------------------------
     [0] Subjects (plugin://plugin.video.academicearth/subjects/)
     ------------------------------------------------------------
 
 
+    $ xbmcswift2 run once plugin://plugin.video.academicearth/subjects/
+    ----------------------------------------------------------------------------------------------------------------------------------------------------------
+     #   Label                    Path
+    ----------------------------------------------------------------------------------------------------------------------------------------------------------
+     [ 0] ACT                      (plugin://plugin.video.academicearth/subjects/http%3A%2F%2Fwww.academicearth.org%2Fsubjects%2Fact/)
+     [ 1] Accounting               (plugin://plugin.video.academicearth/subjects/http%3A%2F%2Fwww.academicearth.org%2Fsubjects%2Faccounting/)
+     [ 2] Algebra                  (plugin://plugin.video.academicearth/subjects/http%3A%2F%2Fwww.academicearth.org%2Fsubjects%2Falgebra/)
+     [ 3] Anthropology             (plugin://plugin.video.academicearth/subjects/http%3A%2F%2Fwww.academicearth.org%2Fsubjects%2Fanthropology/)
+     [ 4] Applied CompSci          (plugin://plugin.video.academicearth/subjects/http%3A%2F%2Fwww.academicearth.org%2Fsubjects%2Fapplied-computer-science/)
+     ...
+
+
 interactive
-~~~~~~~~~~~
+___________
 
 Allows the user to step through their addon using an interactive session. This
 is meant to mimic the basic XBMC interface of clicking on a listitem, which
 then brings up a new directory listing. After each listing is displayed the
 user will be prompted for a listitem to select.  There will always be a ``..``
 option to return to the previous directory (except for the initial URL).::
 
-    (xbmc-academic-earth)jon@lenovo ~/Code/xbmc-academic-earth (master) $ xbmcswift2 run interactive 2>/dev/null
+    $ xbmcswift2 run interactive
     ------------------------------------------------------------
      #  Label    Path
     ------------------------------------------------------------
@@ -100,12 +123,12 @@ option to return to the previous directory (except for the initial URL).::
 
 
 crawl
-~~~~~
+_____
 
 Used to crawl every available path in your addon. In between each request the
 user will be prompted to hit Enter to continue.::
 
-    Choose an item or "q" to quit: (xbmc-academic-earth)jon@lenovo ~/Code/xbmc-academic-earth (master) $ xbmcswift2 run crawl 2>/dev/null
+    $ xbmcswift2 run crawl 2>/dev/null
     ------------------------------------------------------------
      #  Label    Path
     ------------------------------------------------------------

docs/index.rst

@@ -1,25 +1,20 @@
-.. XBMC Swift documentation master file, created by
-   sphinx-quickstart on Sat Jan 21 15:24:10 2012.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
-Welcome to XBMC Swift's documentation!
+Welcome to xbmcswift2's documentation!
 ======================================
 
-Welcome to the documentation for xbmcswift2. This documentation is divided into
-several parts. If you are new, you should start with the :ref:`installation`
-and then move on to :ref:`quickstart`. If you would prefer a more detailed
-walkthrough, try the :ref:`tutorial`.
+Welcome to the documentation for xbmcswift2. xbmcswift2 is a small framework to
+ease development of XBMC addons. Whether you are an experienced addon
+developer, or just coding your first addon, you'll find benefits to using xbmcswift2.
+
+This documentation is divided into several parts. If you are new, you should
+start with the :ref:`installation` and then move on to :ref:`quickstart`. If
+you would prefer a more detailed walkthrough, try the :ref:`tutorial`.
 
 To get a deeper understanding of xbmcswift2, check out :ref:`routing`,
 :ref:`caching` and the complete :ref:`api` reference. For specific code
 samples, check out :ref:`patterns`. If you are upgrading from xbmcswift, check
 out the :ref:`upgrading` page.
 
-xbmcswift2 doesn't rely on any external dependencies to get started. However,
-when writing plugins I like to use http://BeautifulSoup.org. Also, when it
-comes to advanced testing of plugins, I like to use http://nosetests.org.
-
 For a list of XBMC addons which use xbmcswift2, see :ref:`poweredby`.
 
 
@@ -32,6 +27,7 @@ Basic Info
     installation
     quickstart
     tutorial
+    item
     commandline
 
 Advanced User Guide

docs/installation.rst

@@ -9,23 +9,28 @@ Installation
     command line as well as in XBMC. This means that we will have to install
     xbmcswift2 twice, once for the command line and once as an XBMC addon.
 
+    The XBMC version of xbmcswift2 is a specially packaged version of the main
+    release. It excludes some CLI code and tests. It also contains XBMC
+    required files like addon.xml.
 
 The easiest way to get the most recent version of xbmcswift2 for XBMC is to
 install an addon that requires xbmcswift2. You can find a list of such addons
-on the :ref:`poweredby` page. The other options is download the correct version
-from https://github.com/jbeluch/xbmcswift2-xbmc-dist/tags and unpack it into
-your addons folder.  
+on the :ref:`poweredby` page. The other options is download the current XBMC
+distribution from https://github.com/jbeluch/xbmcswift2-xbmc-dist/tags and
+unpack it into your addons folder.  
 
 Now, on to installing xbmcswift2 for use on the command line.
 
 virtualenv
 ----------
 
 Virtualenv is an awesome tool that enables clean installation and removal of
-python libraries into a "virtual environment". Using a virtual environment
+python libraries into a sequestered environment. Using a virtual environment
 means that when you install a library, it doesn't pollute your system-wide
 python installation. This makes it possible to install different versions of a
-library in different environments and they will never conflict.
+library in different environments and they will never conflict. It's a good
+habit to get into when doing python development. So, first we're going to
+install virtualenv.
 
 If you already have pip installed, you can simply::
 
@@ -36,7 +41,7 @@ or if you only have easy_install::
     $ sudo easy_install virtualenv
 
 I also like to use some helpful virtualenv scripts, so install
-virtualenv-wrapper::
+virtualenv-wrapper as well::
 
     $ sudo pip install virtualenv-wrapper
 
@@ -47,16 +52,20 @@ Now we can create our virtualenv::
 
     $ mkvirtualenv xbmcswift2
 
-When this completes, your prompt should now be preceded by `(xbmcswift2)`.
-Now we install xbmcswift2::
+When this completes, your prompt should now be prefixed by `(xbmcswift2)`. The
+new prompt signals that we are now working within our virtualenv. Any libraries
+that we install via pip will only be available in this environment. Now we'll
+install xbmcswift2::
 
     $ pip install xbmcswift2
 
 Everything should be good to go. When you would like to work on your project
-again, simply::
+in the future, issue the following command to start your virtual env::
 
     $ workon xbmcswift2
 
 and to deactive the virtualenv::
 
     $ deactivate
+
+You should check out the :ref:`commandline` page next.