Permalink
Browse files

Merge branch 'develop' for release 0.3.0.

  • Loading branch information...
2 parents e92ddbf + dea2cab commit 0e7a3642499554edc8265fdf1ba6c5ee567daa78 @jbeluch committed Feb 21, 2013
View
@@ -9,3 +9,4 @@ XBMC_Swift.egg-info/
docs/_build/
TODO
XBMC_Swift.egg-info/
+xbmcswift2.egg-info/
View
@@ -12,3 +12,5 @@ Patches and Suggestions
- Tristan Fischer (sphere@dersphere.de)
- beenje
- takoi
+- cancan101
+- ulion
View
@@ -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
=====
View
@@ -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
View
@@ -31,9 +31,18 @@ Request
:inherited-members:
+Actions
+-------
+
+.. automodule:: xbmcswift2.actions
+ :members:
+
+
Extended API
------------
+.. module:: xbmcswift2
+
Module
``````
View
@@ -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
-------
View
@@ -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
------------------------------------------------------------
View
@@ -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
View
@@ -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.
Oops, something went wrong.

0 comments on commit 0e7a364

Please sign in to comment.