Merge lp:~thomir-deactivatedaccount/autopilot/fix-pick-variant into lp:autopilot

[Thomi Richards]

_pick_variant now raises an exception when requested backend was not available.

When asking for a specific stack backend, we now either return the requested backend, or raise an exception. This had a number of knock-on changes, including:
 * A new exception in the autopilot module.
 * Changes to the documentation in the input, process, and display packages.
 * A few other documentation changes.

There are extra tests around the BackendException class.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:159
http://jenkins.qa.ubuntu.com/job/autopilot-ci/20/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-raring-amd64-ci/20
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-raring-armhf-ci/19

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/20/rebuild

review: Approve (continuous-integration)

[lp:~thomir-deactivatedaccount/autopilot/fix-pick-variant]

160. By Thomi Richards on 2013-04-16

fixed typo, and re-introduced the version string.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:160
http://jenkins.qa.ubuntu.com/job/autopilot-ci/21/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-raring-amd64-ci/21
    SUCCESS: http://jenkins.qa.ubuntu.com/job/autopilot-raring-armhf-ci/20

Click here to trigger a rebuild:
http://s-jenkins:8080/job/autopilot-ci/21/rebuild

review: Approve (continuous-integration)

[Christopher Lee (veebers)]

Looks good

review: Approve

=== modified file 'autopilot/__init__.py'
--- autopilot/__init__.py	2012-05-07 17:38:00 +0000
+++ autopilot/__init__.py	2013-04-16 05:01:27 +0000
@@ -6,7 +6,17 @@
 # under the terms of the GNU General Public License version 3, as published
 # by the Free Software Foundation.
 
-"""An automated test runner and driver for Unity"""
-
-
-version = "1.0"
+
+version = '1.3'
+
+
+class BackendException(RuntimeError):
+
+    """An error occured while trying to initialise an autopilot backend."""
+
+    def __init__(self, original_exception):
+        super(BackendException, self).__init__(
+            "Error while initialising backend. Original exception was: " \
+            + original_exception.message
+            )
+        self.original_exception = original_exception
 
=== modified file 'autopilot/display/__init__.py'
--- autopilot/display/__init__.py	2013-04-08 03:46:47 +0000
+++ autopilot/display/__init__.py	2013-04-16 05:01:27 +0000
@@ -90,13 +90,23 @@
     def create(preferred_variant=''):
         """Get an instance of the Display class.
 
-        If variant is specified, it should be a string that specifies a backend to
-        use. However, this hint can be ignored - autopilot will prefer to return a
-        variant other than the one requested, rather than fail to return anything at
-        all.
-
-        If autopilot cannot instantate any of the possible backends, a RuntimeError
-        will be raised.
+        :param preferred_variant: A string containing a hint as to which variant you
+            would like. If left blank, autopilot will pick a suitable
+            variant for you. Specifying a variant will guarantee that either that
+            variant is returned, or an exception is raised.
+
+            possible variants are:
+
+            * ``X11`` - Get display information from X11.
+            * ``UPA`` - Get display information from the ubuntu platform API.
+
+        :raises: RuntimeError if autopilot cannot instantate any of the possible
+            backends.
+        :raises: RuntimeError if the preferred_variant is specified and is not
+            one of the possible backends for this device class.
+        :raises: :class:`~autopilot.BackendException` if the preferred_variant is
+            set, but that variant could not be instantiated.
+
         """
         def get_x11_display():
             from autopilot.display._X11 import Display
 
=== modified file 'autopilot/input/__init__.py'
--- autopilot/input/__init__.py	2013-04-08 03:46:47 +0000
+++ autopilot/input/__init__.py	2013-04-16 05:01:27 +0000
@@ -17,9 +17,11 @@
 events (possibly UInput).
 
 Test authors should instantiate the appropriate class using the ``create`` method
-on each class. Tests can provide a hint to this method to suggest that a particular
-subsystem be used. However, autopilot will prefer to return a subsystem other than
-the one specified, if the requested subsystem is unavailable.
+on each class. Calling ``create()`` with  no arguments will get an instance of the
+specified class that suits the current platform. In this case, autopilot will
+do it's best to pick a suitable variant. Calling ``create`` with a variant name
+will result in that specific variant type being returned, or, if it cannot be created,
+an exception will be raised. The exception type varies from variant to variant.
 
 There are three basic input types available:
 
@@ -49,12 +51,23 @@
     def create(preferred_variant=''):
         """Get an instance of the :py:class:`Keyboard` class.
 
-        :param preferred_variant: A string containing a hint as to which variant you
-            would like. However, this hint can be ignored - autopilot will prefer to
-            return a keyboard variant other than the one requested, rather than fail
-            to return anything at all.
-        :raises: a RuntimeError will be raised if autopilot cannot instantate any of
-            the possible backends.
+        :param preferred_variant: A string containing a hint as to which variant
+            you would like. If left blank, autopilot will pick a suitable
+            variant for you. Specifying a variant will guarantee that either that
+            variant is returned, or an exception is raised.
+
+            possible variants are:
+
+            * ``X11`` - Generate keyboard events using the X11 client libraries.
+            * ``UInput`` - Use UInput kernel-level device driver.
+
+        :raises: RuntimeError if autopilot cannot instantate any of the possible
+            backends.
+        :raises: RuntimeError if the preferred_variant is specified and is not
+            one of the possible backends for this device class.
+        :raises: :class:`~autopilot.BackendException` if the preferred_variant is
+            set, but that variant could not be instantiated.
+
 
         """
         def get_x11_kb():
@@ -167,11 +180,20 @@
         """Get an instance of the :py:class:`Mouse` class.
 
         :param preferred_variant: A string containing a hint as to which variant you
-            would like. However, this hint can be ignored - autopilot will prefer to
-            return a mouse variant other than the one requested, rather than fail
-            to return anything at all.
-        :raises: a RuntimeError will be raised if autopilot cannot instantate any of
-            the possible backends.
+            would like. If left blank, autopilot will pick a suitable
+            variant for you. Specifying a variant will guarantee that either that
+            variant is returned, or an exception is raised.
+
+            possible variants are:
+
+            * ``X11`` - Generate mouse events using the X11 client libraries.
+
+        :raises: RuntimeError if autopilot cannot instantate any of the possible
+            backends.
+        :raises: RuntimeError if the preferred_variant is specified and is not
+            one of the possible backends for this device class.
+        :raises: :class:`~autopilot.BackendException` if the preferred_variant is
+            set, but that variant could not be instantiated.
 
         """
         def get_x11_mouse():
@@ -262,11 +284,21 @@
         """Get an instance of the :py:class:`Touch` class.
 
         :param preferred_variant: A string containing a hint as to which variant you
-            would like. However, this hint can be ignored - autopilot will prefer to
-            return a touch variant other than the one requested, rather than fail
-            to return anything at all.
-        :raises: a RuntimeError will be raised if autopilot cannot instantate any of
-            the possible backends.
+            would like. If left blank, autopilot will pick a suitable
+            variant for you. Specifying a variant will guarantee that either that
+            variant is returned, or an exception is raised.
+
+            possible variants are:
+
+            * ``UInput`` - Use UInput kernel-level device driver.
+
+        :raises: RuntimeError if autopilot cannot instantate any of the possible
+            backends.
+        :raises: RuntimeError if the preferred_variant is specified and is not
+            one of the possible backends for this device class.
+        :raises: :class:`~autopilot.BackendException` if the preferred_variant is
+            set, but that variant could not be instantiated.
+
 
         """
         def get_uinput_touch():
 
=== modified file 'autopilot/process/__init__.py'
--- autopilot/process/__init__.py	2013-04-15 03:39:09 +0000
+++ autopilot/process/__init__.py	2013-04-16 05:01:27 +0000
@@ -58,11 +58,21 @@
         """Get an instance of the :py:class:`ProcessManager` class.
 
         :param preferred_variant: A string containing a hint as to which variant you
-            would like. However, this hint can be ignored - autopilot will prefer to
-            return a keyboard variant other than the one requested, rather than fail
-            to return anything at all.
-        :raises: a RuntimeError will be raised if autopilot cannot instantate any of
-            the possible backends.
+            would like. If left blank, autopilot will pick a suitable
+            variant for you. Specifying a variant will guarantee that either that
+            variant is returned, or an exception is raised.
+
+            possible variants are:
+
+            * ``BAMF`` - Get process information using the BAMF Application Matching Framework.
+
+        :raises: RuntimeError if autopilot cannot instantate any of the possible
+            backends.
+        :raises: RuntimeError if the preferred_variant is specified and is not
+            one of the possible backends for this device class.
+        :raises: :class:`~autopilot.BackendException` if the preferred_variant is
+            set, but that variant could not be instantiated.
+
         """
         def get_bamf_pm():
             from autopilot.process._bamf import ProcessManager
 
=== added file 'autopilot/tests/test_custom_exceptions.py'
--- autopilot/tests/test_custom_exceptions.py	1970-01-01 00:00:00 +0000
+++ autopilot/tests/test_custom_exceptions.py	2013-04-16 05:01:27 +0000
@@ -0,0 +1,31 @@
+# -*- Mode: Python; coding: utf-8; indent-tabs-mode: nil; tab-width: 4 -*-
+# Copyright 2013 Canonical
+# Author: Thomi Richards
+#
+# This program is free software: you can redistribute it and/or modify it
+# under the terms of the GNU General Public License version 3, as published
+# by the Free Software Foundation.
+
+
+from testtools import TestCase
+from testtools.matchers import Equals, IsInstance
+
+from autopilot import BackendException
+
+class BackendExceptionTests(TestCase):
+
+    def test_must_wrap_exception(self):
+        """BackendException must be able to wrap another exception instance."""
+        err = BackendException(RuntimeError("Hello World"))
+        self.assertThat(err.original_exception, IsInstance(RuntimeError))
+        self.assertThat(err.original_exception.message, Equals("Hello World"))
+
+    def test_dunder_str(self):
+        err = BackendException(RuntimeError("Hello World"))
+        self.assertThat(str(err),
+            Equals("Error while initialising backend. Original exception was: Hello World"))
+
+    def test_dunder_repr(self):
+        err = BackendException(RuntimeError("Hello World"))
+        self.assertThat(repr(err),
+            Equals("BackendException('Error while initialising backend. Original exception was: Hello World',)"))
 
=== modified file 'autopilot/utilities.py'
--- autopilot/utilities.py	2013-04-08 01:05:45 +0000
+++ autopilot/utilities.py	2013-04-16 05:01:27 +0000
@@ -20,12 +20,17 @@
 import time
 from functools import wraps
 
+from autopilot import BackendException
+
 
 def _pick_variant(variants, preferred_variant):
     possible_backends = variants.keys()
     get_debug_logger().debug("Possible variants: %s", ','.join(possible_backends))
-    if preferred_variant in possible_backends:
-        possible_backends.sort(lambda a,b: -1 if a == preferred_variant else 0)
+    if preferred_variant:
+        if preferred_variant in possible_backends:
+            possible_backends.sort(lambda a,b: -1 if a == preferred_variant else 0)
+        else:
+            raise RuntimeError("Unknown backend '%s'" % (preferred_variant))
     failure_reasons = []
     for be in possible_backends:
         try:
@@ -33,6 +38,8 @@
         except Exception as e:
             get_debug_logger().warning("Can't create variant %s: %r", be, e)
             failure_reasons.append('%s: %r' % (be, e))
+            if preferred_variant != '':
+                raise BackendException(e)
     raise RuntimeError("Unable to instantiate any backends\n%s" % '\n'.join(failure_reasons))
 
 
 
=== modified file 'docs/_templates/indexcontent.html'
--- docs/_templates/indexcontent.html	2013-04-15 03:33:21 +0000
+++ docs/_templates/indexcontent.html	2013-04-16 05:01:27 +0000
@@ -12,7 +12,7 @@
       </td>
       <td width="50%">
         <p class="biglink">
-          <a class="biglink" href="{{ pathto("api/autopilot") }}">API Reference</a><br/>
+          <a class="biglink" href="{{ pathto("api/index") }}">API Reference</a><br/>
           <span class="linkdescr">API reference documentation for Autopilot.</span>
         </p>
       </td>
 
=== modified file 'docs/api/autopilot.rst'
--- docs/api/autopilot.rst	2013-04-14 21:56:27 +0000
+++ docs/api/autopilot.rst	2013-04-16 05:01:27 +0000
@@ -1,10 +1,8 @@
-:orphan:
-
-Autopilot API Documentation
-===========================
-
-.. toctree::
-   :maxdepth: 1
-   :glob:
-
-   *
+``autopilot`` - Global stuff
+++++++++++++++++++++++++++++
+
+
+.. automodule:: autopilot
+    :members:
+    :undoc-members:
+
 
=== modified file 'docs/api/display.rst'
--- docs/api/display.rst	2013-04-05 05:26:23 +0000
+++ docs/api/display.rst	2013-04-16 05:01:27 +0000
@@ -1,5 +1,5 @@
-``display`` - Get information about the current display(s)
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+``autopilot.display`` - Get information about the current display(s)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 .. automodule:: autopilot.display
 
=== modified file 'docs/api/emulators.rst'
--- docs/api/emulators.rst	2013-04-15 01:15:52 +0000
+++ docs/api/emulators.rst	2013-04-16 05:01:27 +0000
@@ -1,5 +1,5 @@
-``emulators`` - Backwards compatibility for autopilot v1.2
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+``autopilot.emulators`` - Backwards compatibility for autopilot v1.2
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 .. module autopilot.emulators
 
=== modified file 'docs/api/gestures.rst'
--- docs/api/gestures.rst	2013-04-05 04:57:25 +0000
+++ docs/api/gestures.rst	2013-04-16 05:01:27 +0000
@@ -1,5 +1,5 @@
-``gestures`` - Gestural and multi-touch support
-+++++++++++++++++++++++++++++++++++++++++++++++
+``autopilot.gestures`` - Gestural and multi-touch support
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 .. automodule:: autopilot.gestures
 
=== added file 'docs/api/index.rst'
--- docs/api/index.rst	1970-01-01 00:00:00 +0000
+++ docs/api/index.rst	2013-04-16 05:01:27 +0000
@@ -0,0 +1,10 @@
+:orphan:
+
+Autopilot API Documentation
+===========================
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *
 
=== modified file 'docs/api/input.rst'
--- docs/api/input.rst	2013-04-05 05:26:23 +0000
+++ docs/api/input.rst	2013-04-16 05:01:27 +0000
@@ -1,5 +1,5 @@
-``input`` - Generate keyboard, mouse, and touch input events
-++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+``autopilot.input`` - Generate keyboard, mouse, and touch input events
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 .. automodule:: autopilot.input
 
=== modified file 'docs/api/introspection.rst'
--- docs/api/introspection.rst	2013-04-15 01:00:21 +0000
+++ docs/api/introspection.rst	2013-04-16 05:01:27 +0000
@@ -1,5 +1,5 @@
-``introspection`` - Autopilot introspection internals
-+++++++++++++++++++++++++++++++++++++++++++++++++++++
+``autopilot.introspection`` - Autopilot introspection internals
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 .. automodule:: autopilot.introspection
 
=== modified file 'docs/api/matchers.rst'
--- docs/api/matchers.rst	2013-04-05 04:15:17 +0000
+++ docs/api/matchers.rst	2013-04-16 05:01:27 +0000
@@ -1,5 +1,5 @@
-``matchers`` - Custom matchers for test assertions
-++++++++++++++++++++++++++++++++++++++++++++++++++
+``autopilot.matchers`` - Custom matchers for test assertions
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 .. automodule:: autopilot.matchers
 
=== modified file 'docs/api/platform.rst'
--- docs/api/platform.rst	2013-04-05 04:15:17 +0000
+++ docs/api/platform.rst	2013-04-16 05:01:27 +0000
@@ -1,5 +1,5 @@
-``Platform`` - Functions for platform detection
-+++++++++++++++++++++++++++++++++++++++++++++++
+``autopilot.Platform`` - Functions for platform detection
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 .. automodule:: autopilot.platform
 
=== modified file 'docs/api/testcase.rst'
--- docs/api/testcase.rst	2013-04-05 04:15:17 +0000
+++ docs/api/testcase.rst	2013-04-16 05:01:27 +0000
@@ -1,5 +1,5 @@
-``testcase`` - Base class for all Autopilot Test Cases
-++++++++++++++++++++++++++++++++++++++++++++++++++++++
+``autopilot.testcase`` - Base class for all Autopilot Test Cases
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 
 .. automodule:: autopilot.testcase
 
=== modified file 'docs/conf.py'
--- docs/conf.py	2013-04-15 20:42:55 +0000
+++ docs/conf.py	2013-04-16 05:01:27 +0000
@@ -101,7 +101,7 @@
 pygments_style = 'sphinx'
 
 # A list of ignored prefixes for module index sorting.
-modindex_common_prefix = ['autopilot.']
+# modindex_common_prefix = ['']
 
 # nitpicky = True
 # -- Options for HTML output ---------------------------------------------------