Merge ~sylvain-pineau/plainbox/+git/packaging:fix-transition into plainbox:master

[Sylvain Pineau]

fix transition to checkbox-ng

Unmerged commits

25fa201... by Sylvain Pineau on 2018-04-24

Make plainbox a transitional package

https://wiki.debian.org/PackageTransition

cdd25c1... by Sylvain Pineau on 2018-01-15

Update silence logging failure patch

See https://bugs.launchpad.net/plainbox/+bug/1262898

4cf370b... by Sylvain Pineau on 2018-01-12

Update unvendorize patch (-funcsigs)

b2de646... by PMR <pmr@pmr-lander> on 2017-11-17

Merge #333833 from ~kissiel/plainbox/+git/packaging:add-pycrypto-dep

227148e... by Maciej Kisielewski on 2017-11-16

add python3-crypto dependency

Signed-off-by: Maciej Kisielewski <email address hidden>

90bce32... by Sylvain Pineau on 2017-11-16

change version to 0.38.0-1
"new upstream version"

c2d46ce... by Zygmunt Krynicki on 2015-10-08

Revert the documentation theme back to default

 PlainBox uses a customized sphinx theme that includes additional
 HTML to integrate with online comment service. This should not be
 a part of the offline documentation package.
Origin: upstream
Forwarded: not-needed
Last-Update: 2015-07-21

Patch-Name: documentation-theme

648f8eb... by Zygmunt Krynicki on 2015-10-08

Silence setup failure of the logging subsystem

 The logging subsystem has a feature that displays two lines of warnings
 if the per-user log file cannot be created. This leads to spurious
 errors when plainbox is invoked from a build environment. Before a
 better solution is found this warning is disabled as all of the
 subsequent, relevant, logging messages are display either way.
Bug-Ubuntu: https://bugs.launchpad.net/checkbox/+bug/1262898
Forwarded: yes
Last-Update: 2014-03-18

Patch-Name: silence-logging-failure

e112ce0... by Zygmunt Krynicki on 2015-10-08

Remove vendorized modules

 This patch replaces plainbox.vendor.{mock,funcsigs} with equivalent
 imports from the standard python3.3 library. Upstream will stop
 shipping those vendorized modules when support for python3.2 is no
 longer required.
Upstream: not-needed
Last-Update: 2014-03-18

Patch-Name: unvendorize

0b21cff... by Sylvain Pineau on 2017-11-16

record new upstream branch created by importing plainbox_0.38.0.orig.tar.gz

diff --git a/MANIFEST.in b/MANIFEST.in
index 0eed38a..8a92fdb 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -35,6 +35,12 @@ include plainbox/impl/providers/stubbox/po/*.pot
 include plainbox/impl/providers/stubbox/po/POTFILES.in
 include plainbox/impl/providers/stubbox/units/jobs/*.pxu
 include plainbox/impl/providers/stubbox/units/testplans/*.pxu
+<<<<<<< MANIFEST.in
+=======
+include plainbox/impl/providers/stubbox/whitelists/*.whitelist
+
+include plainbox/vendor/argparse/py*-argparse.py
+>>>>>>> MANIFEST.in
 
 include plainbox/qml_shell/qml_shell.qml
 
@@ -45,4 +51,8 @@ recursive-exclude daily-package-testing *
 recursive-include contrib *.policy
 recursive-include docs *.rst *.py *.html *.conf
 recursive-include plainbox/data *.rng
+<<<<<<< MANIFEST.in
 recursive-include plainbox/test-data *.json *.html *.tar.xz
+=======
+recursive-include plainbox/test-data *.json *.xml *.html
+>>>>>>> MANIFEST.in
diff --git a/PKG-INFO b/PKG-INFO
new file mode 100644
index 0000000..fafbf3f
--- /dev/null
+++ b/PKG-INFO
@@ -0,0 +1,62 @@
+Metadata-Version: 1.1
+Name: plainbox
+Version: 0.38.0
+Summary: Toolkit for software and hardware integration testing
+Home-page: https://launchpad.net/plainbox/
+Author: Zygmunt Krynicki
+Author-email: [e-mail]
+License: GPLv3
+Description: PlainBox
+        ========
+        
+        PlainBox is a toolkit consisting of python3 library, development tools,
+        documentation and examples. It is targeted at developers working on testing or
+        certification applications and authors creating tests for such applications.
+        
+        PlainBox can be used to both create simple and comprehensive test tools as well
+        as to develop and execute test jobs and test scenarios. It was created as a
+        refined and rewritten core of the CheckBox project. It has a well tested and
+        documented core, small but active development community and a collection of
+        associated projects that use it as a lower-level engine/back-end library.
+        
+        PlainBox has a novel approach to discovering (and probing) hardware and
+        software that is extensible and not hardwired into the system. It allows test
+        developers to express association between a particular test and the hardware,
+        software and configuration constraints that must be met for the test to execute
+        meaningfully. This feature, along with pluggable test definitions, makes
+        PlainBox flexible and applicable to many diverse testing situations, ranging
+        from mobile phones, traditional desktop computers, servers and up to testing
+        "cloud" installations.
+        
+        External Documentation Links
+        ============================
+        
+        * `Using PlainBox <http://plainbox.readthedocs.org/en/latest/usage.html>`_
+        * `Hacking on PlainBox <http://plainbox.readthedocs.org/en/latest/dev/index.html>`_
+        * `Testing PlainBox <http://plainbox.readthedocs.org/en/latest/dev/intro.html#running-plainbox-tests>`_
+        
+        Known Issues
+        ============
+        
+        https://bugs.launchpad.net/plainbox
+        
+Platform: POSIX
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Environment :: Console :: Curses
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: Manufacturing
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Natural Language :: English
+Classifier: Natural Language :: Polish
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.2
+Classifier: Programming Language :: Python :: 3.3
+Classifier: Programming Language :: Python :: 3.4
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: System :: Benchmark
+Classifier: Topic :: Utilities
diff --git a/debian/.git-dpm b/debian/.git-dpm
new file mode 100644
index 0000000..6322bd6
--- /dev/null
+++ b/debian/.git-dpm
@@ -0,0 +1,8 @@
+# see git-dpm(1) from git-dpm package
+c2d46ce5be7fb38b74c536e85865128af008d864
+c2d46ce5be7fb38b74c536e85865128af008d864
+8d70019e76acb28b201b59f0e0d578e15973723b
+8d70019e76acb28b201b59f0e0d578e15973723b
+plainbox_0.38.0.orig.tar.gz
+93dbb907b96d266b3a0e0c761cc975f10e2ae669
+1491112
diff --git a/debian/changelog b/debian/changelog
new file mode 100644
index 0000000..ab529e2
--- /dev/null
+++ b/debian/changelog
@@ -0,0 +1,257 @@
+plainbox (0.38.0-1) UNRELEASED; urgency=medium
+
+  [ Pierre Equoy ]
+  * Open for development (remove this message before releasing)
+  * "new upstream version"
+  * "new upstream version"
+
+  [ Sylvain Pineau ]
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+
+  [ Pierre Equoy ]
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+
+  [ Sylvain Pineau ]
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+  * "new upstream version"
+
+ -- Sylvain Pineau <[e-mail]>  Thu, 16 Nov 2017 11:39:52 +0100
+
+plainbox (0.31-1) UNRELEASED; urgency=medium
+
+  [ Ondřej Nový ]
+  * Fixed homepage (https)
+  * Fixed VCS URL (https)
+
+  [ Sylvain Pineau ]
+  * new upstream version
+
+ -- Sylvain Pineau <[e-mail]>  Tue, 04 Oct 2016 13:53:56 +0200
+
+plainbox (0.25-1) unstable; urgency=medium
+
+  * New upstream release
+  * List of fixed bugs: https://launchpad.net/plainbox/+milestone/0.25
+
+ -- Sylvain Pineau <[e-mail]>  Tue, 05 Jan 2016 17:26:37 +0100
+
+plainbox (0.24-1) unstable; urgency=medium
+
+  * New upstream release with multiple fixes and new features.
+  * One important feature is the introduction of the SessionAssistant class.
+    It allows Plainbox to simplify common testing scenarios.
+    The assistant acts as a middle-man between the session manager and the
+    application.
+    It handles all currently known stages of the testing work-flow.
+  * Add a dependency on python3 guacamole, padme, requests and tk.
+  * Plainbox now supports a new way to express estimated durations that is much
+    easier for humans to read and write.
+  * Plainbox now supports an *after* job ordering constraint. This constraint
+    is very similar to the existing *depends* constraint, except that the
+    outcome of the referenced job is not important. In practical terms, even if
+    one job runs and fails, another job that runs *after* it, will run.
+  * Plainbox now allows more than one resource object to be used in a resource
+    expression (e.g. the manifest resource with something else).
+  * Plainbox ignores trailing garbage after EOF while reading IOLog zip.
+    See https://bugs.python.org/issue24301.
+
+ -- Sylvain Pineau <[e-mail]>  Fri, 04 Dec 2015 15:44:14 +0100
+
+plainbox (0.22.2-2.1) unstable; urgency=medium
+
+  * Non-maintainer upload.
+  * Fix "FTBFS: dh_clean: rm: cannot remove 'plainbox.egg-info': d/clean did
+    miss the final '/*' to be recognized as directory. (Closes: #805677)
+  * Also clean a mo file to allow build twice in a row
+
+ -- Tobias Frost <[e-mail]>  Sun, 22 Nov 2015 13:07:43 +0100
+
+plainbox (0.22.2-2) unstable; urgency=medium
+
+  * debian/patches: add a pile of patches that bring in cherry-picked or
+    brand-new fixes for issues uncovered by python 3.5.
+
+ -- Zygmunt Krynicki <[e-mail]>  Wed, 02 Sep 2015 16:21:41 +0200
+
+plainbox (0.22.2-1) unstable; urgency=medium
+
+  * New upstream maintenance release
+  * Use a temporary HOME to work around LP: #1478906
+  * Build i18n catalogs for the exporters and categories providers.
+  * Move myself to Uploaders and set the [e-mail]
+    mailing list as the Maintainer. 
+  * Remove duplicate dependency on python3-xlsxwriter (via suggests and
+    depends) from python3-plainbox.
+  * Remove XS-Testsuite: autopkgtest as recommend by lintian.
+  * De-duplicate licenses in debian/copyright
+  * Correct filename patterns for pyglibc/glibc files.
+
+ -- Zygmunt Krynicki <[e-mail]>  Tue, 28 Jul 2015 12:23:17 +0200
+
+plainbox (0.22-1) unstable; urgency=medium
+
+  * New upstream release (sorry for skipping 0.21) with multiple fixes and new
+    features.
+  * One important feature is the introduction of exporter units that allow
+    test developers to put any customized report directly into the test
+    provider package. This allows us to remove all association with Ubuntu or
+    Canonical from the core plainbox package and make it more universal for
+    Debian and other distributions.
+  * debian/control: Drop dependency on python3-lxml (and the associated
+    security issues). Upstream moved away from lxml and has adopted Jinja2 as
+    a more flexible system for creating arbitrary text-based reports. 
+  * debian/control: Make the dependency on python3-xlsxwriter explicit as it
+    is now more directly tested and not so much optional.
+  * debian/patches/documentation-theme: refresh patch 
+  * debian/patches/fix-packaging-metadata-units: add a combined patch that
+    addresses three Debian-affecting bugs that prevent providers from
+    generating some of their dependencies.
+
+ -- Zygmunt Krynicki <[e-mail]>  Tue, 21 Jul 2015 12:22:03 +0200
+
+plainbox (0.20-1) unstable; urgency=medium
+
+  * Use the new pypi redirector
+  * Correct debian/copyright paths
+  * Correct debian/copyright license names
+  * Update Standards-Version to 3.9.6 (no change required) 
+  * New upstream release
+  * Add debian/copyright entry for sphinxarg
+  * Remove stubbox so that it's not packaged / installed 
+  * Break checkbox-ng << 0.18 so that upgrades work (packages are bound by
+    unstable API and this is the matching release) 
+  * Ship plainbox-qml-shell manual page along with python3-plainbox package
+  * Tweak how i18n catalogs are built not to corrupt the tree 
+  * Build i18n catalog for the 'categories' provider 
+  * Update generic copyright to -2015
+  * Remove textland-specific copyright (it's now the same as the rest of
+    plainbox), GPL-3 (not 3+) 
+  * Add license specific to vendorized python-morris
+  * Add license specific to vendorized python-glibc 
+  * Wrap-and-sort everything
+
+ -- Zygmunt Krynicki <[e-mail]>  Wed, 04 Mar 2015 18:49:06 +0100
+
+plainbox (0.5.4-1) unstable; urgency=medium
+
+  * New upstream release
+  * List of fixed bugs:
+    https://launchpad.net/plainbox/+milestone/0.5.4
+
+ -- Zygmunt Krynicki <[e-mail]>  Thu, 10 Apr 2014 22:31:50 +0200
+
+plainbox (0.5.3-2) unstable; urgency=medium
+
+  * debian/python3-plainbox.preinst: remove
+    /usr/lib/python3/dist-packages/{data,testdata} on upgrades (if they are
+    not symbolic links). This fixes upgrades from the previous version.
+
+ -- Zygmunt Krynicki <[e-mail]>  Tue, 08 Apr 2014 00:11:37 +0200
+
+plainbox (0.5.3-1) unstable; urgency=medium
+
+  * New upstream release
+  * debian/control: make python3-plainbox, plainbox, plainbox-secure-policy
+    and plainbox-insecure-policy all depend on one version on themselves.
+    LP: #1298284
+  * debian/control: break python3-checkbox-ng << 0.3
+  * debian/control: drop build and runtime dependency on python3-requests
+  * debian/copyright: add entry for new file (_shlex.py)
+  * debian/copyright: move python license to dedicated license section (reused
+    by three modules) per example 2 on http://dep.debian.net/deps/dep5/
+  * debian/rules: regenerate translation templates 
+  * debian/rules: move plainbox/data and plainbox/test-data to
+    /usr/share/python3-plainbox/ and use symlinks to keep original directories
+    available. 
+  * List of fixed bugs:
+    https://launchpad.net/checkbox/+milestone/plainbox-0.5.2
+    https://launchpad.net/plainbox/+milestone/0.5.3
+
+ -- Zygmunt Krynicki <[e-mail]>  Tue, 01 Apr 2014 01:36:20 +0200
+
+plainbox (0.5.1-1) unstable; urgency=medium
+
+  * New upstream release
+  * debian/control: drop X-Python3-Version << 3.5 
+  * debian/patches/disable-development-option: dropped, applied upstream
+  * debian/copyright: associate vendorized copies of argparse with appropriate
+    copyright section
+
+ -- Zygmunt Krynicki <[e-mail]>  Wed, 19 Mar 2014 00:08:12 +0100
+
+plainbox (0.5~b2-1) unstable; urgency=medium
+
+  * New upstream release.
+  * debian/control: build-depend on python3-distutils-extra for translations
+  * debian/control: add support for python3.4
+  * debian/control: drop build dependency on help2man, the new release has
+    native manual pages
+  * debian/rules: build, install and clean up after translations
+  * debian/clean: clean *.egg-info and *.pot files since those get
+    regenerated
+  * debian/source/options: ignore changes to .po files since intltools-update
+    keeps bumping the timestamp embedded in them
+  * debian/copyright: add license section for plainbox/impl/_argparse.py
+  * debian/copyright: add new copyright entries for textland
+  * debian/patches: refresh and reorder without any semantic changes
+  * debian/patches: add patch to revert documentation theme to defaults
+  * debian/watch: add mangling for alpha releases
+  * debian/python3-plainbox.manpages, debian/plainbox.manpages: use manual
+    pages build with sphinx
+
+ -- Zygmunt Krynicki <[e-mail]>  Thu, 13 Mar 2014 09:45:06 +0100
+
+plainbox (0.4-4) unstable; urgency=medium
+
+  * Team upload.
+  * Autopkgtest improvements: enable verbose output, use $ADTTMP and stop
+    redirecting output to /dev/null.
+  * Export NO_PNG_PKG_MANGLE=1 in debian/rules to disable PNG stripping
+    when pkgbinarymangler is installed (it breaks the testsuite).
+
+ -- Dmitry Shachnev <[e-mail]>  Wed, 22 Jan 2014 18:08:40 +0400
+
+plainbox (0.4-3) unstable; urgency=medium
+
+  * debian/tests/unit-tests: actually fail the test suite if unit tests fail.
+    Thanks to Michael Terry for the fix. LP:#1265853
+
+ -- Zygmunt Krynicki <[e-mail]>  Fri, 03 Jan 2014 16:55:54 +0100
+
+plainbox (0.4-2) unstable; urgency=medium
+
+  * debian/tests/control: Fix autopackage tests not to install all (including
+    conflicting) packages blindly LP:#1264985
+
+ -- Zygmunt Krynicki <[e-mail]>  Thu, 02 Jan 2014 10:33:29 +0100
+
+plainbox (0.4-1) unstable; urgency=medium
+
+  * New upstream release
+  * plainbox-insecure-policy.install, plainbox-secure-policy.install: adjust
+    packaging to install the same policykit .policy files under their new
+    names
+  * debian/copyright: update all Canonical-owned code to GPL-3 (not GPL-3+)
+  * debian/control: mark python3.4 as unsupported as python3-lxml does not
+    support python3.4 yet
+
+ -- Zygmunt Krynicki <[e-mail]>  Tue, 24 Dec 2013 14:27:09 +0100
+
+plainbox (0.4~b2-1) unstable; urgency=low
+
+  * Initial release (Closes: #730568)
+
+ -- Zygmunt Krynicki <[e-mail]>  Thu, 28 Nov 2013 23:38:28 +0000
diff --git a/debian/clean b/debian/clean
new file mode 100644
index 0000000..8f5ba15
--- /dev/null
+++ b/debian/clean
@@ -0,0 +1,5 @@
+plainbox.egg-info/*
+plainbox/impl/providers/stubbox/po/stubbox.pot
+po/plainbox.pot
+plainbox/vendor/sphinxarg/LICENSE
+plainbox/impl/providers/manifest/build/mo/pl/LC_MESSAGES/plainbox-provider-manifest.mo
diff --git a/debian/compat b/debian/compat
new file mode 100644
index 0000000..ec63514
--- /dev/null
+++ b/debian/compat
@@ -0,0 +1 @@
+9
diff --git a/debian/control b/debian/control
new file mode 100644
index 0000000..7f675ae
--- /dev/null
+++ b/debian/control
@@ -0,0 +1,106 @@
+Source: plainbox
+Section: utils
+Priority: optional
+Maintainer: Checkbox Developers <[e-mail]>
+Uploaders: Sylvain Pineau <[e-mail]>,
+           Zygmunt Krynicki <[e-mail]>,
+           Debian Python Modules Team <[e-mail]>
+Build-Depends: debhelper (>= 9),
+               dh-python,
+               python3-all,
+               python3-crypto,
+               python3-distutils-extra,
+               python3-docutils,
+               python3-guacamole,
+               python3-jinja2,
+               python3-padme,
+               python3-pkg-resources,
+               python3-requests,
+               python3-requests-oauthlib,
+               python3-setuptools,
+               python3-sphinx,
+               python3-tk,
+               python3-xlsxwriter
+Standards-Version: 3.9.6
+X-Python3-Version: >= 3.2
+Vcs-Git: https://anonscm.debian.org/git/python-modules/packages/plainbox.git
+Vcs-Browser: https://anonscm.debian.org/cgit/python-modules/packages/plainbox.git
+Homepage: https://launchpad.net/plainbox
+
+Package: plainbox
+Architecture: all
+Depends: checkbox-ng (>=1)
+Description: toolkit for software and hardware integration testing
+ PlainBox is a toolkit consisting of python3 library, development tools,
+ documentation and examples. It is targeted at developers working on testing or
+ certification applications and authors creating tests for such applications.
+ .
+ PlainBox can be used to both create simple and comprehensive test tools as
+ well as to develop and execute test jobs and test scenarios. It was created as
+ a refined and rewritten core of the Checkbox project. It has a well tested and
+ documented core, small but active development community and a collection of
+ associated projects that use it as a lower-level engine/back-end library.
+ .
+ PlainBox has a novel approach to discovering (and probing) hardware and
+ software that is extensible and not hardwired into the system. It allows test
+ developers to express association between a particular test and the hardware,
+ software and configuration constraints that must be met for the test to
+ execute meaningfully. This feature, along with pluggable test definitions,
+ makes plainbox flexible and applicable to many diverse testing situations,
+ ranging from mobile phones, traditional desktop computers, servers and up to
+ testing "cloud" installations.
+ .
+ This package contains the plainbox executable
+
+Package: python3-plainbox
+Architecture: all
+Section: python
+Depends: python3-checkbox-ng (>=1)
+Description: toolkit for software and hardware testing (python3 module)
+ PlainBox is a toolkit consisting of python3 library, development tools,
+ documentation and examples. It is targeted at developers working on testing or
+ certification applications and authors creating tests for such applications.
+ .
+ PlainBox can be used to both create simple and comprehensive test tools as
+ well as to develop and execute test jobs and test scenarios. It was created as
+ a refined and rewritten core of the Checkbox project. It has a well tested and
+ documented core, small but active development community and a collection of
+ associated projects that use it as a lower-level engine/back-end library.
+ .
+ PlainBox has a novel approach to discovering (and probing) hardware and
+ software that is extensible and not hardwired into the system. It allows test
+ developers to express association between a particular test and the hardware,
+ software and configuration constraints that must be met for the test to
+ execute meaningfully. This feature, along with pluggable test definitions,
+ makes plainbox flexible and applicable to many diverse testing situations,
+ ranging from mobile phones, traditional desktop computers, servers and up to
+ testing "cloud" installations.
+ .
+ This package contains the plainbox python3 library.
+
+Package: python3-plainbox-doc
+Architecture: all
+Section: doc
+Priority: extra
+Depends: ${misc:Depends}, ${sphinxdoc:Depends}
+Description: toolkit for software and hardware testing (documentation)
+ PlainBox is a toolkit consisting of python3 library, development tools,
+ documentation and examples. It is targeted at developers working on testing or
+ certification applications and authors creating tests for such applications.
+ .
+ PlainBox can be used to both create simple and comprehensive test tools as
+ well as to develop and execute test jobs and test scenarios. It was created as
+ a refined and rewritten core of the Checkbox project. It has a well tested and
+ documented core, small but active development community and a collection of
+ associated projects that use it as a lower-level engine/back-end library.
+ .
+ PlainBox has a novel approach to discovering (and probing) hardware and
+ software that is extensible and not hardwired into the system. It allows test
+ developers to express association between a particular test and the hardware,
+ software and configuration constraints that must be met for the test to
+ execute meaningfully. This feature, along with pluggable test definitions,
+ makes plainbox flexible and applicable to many diverse testing situations,
+ ranging from mobile phones, traditional desktop computers, servers and up to
+ testing "cloud" installations.
+ .
+ This package contains the documentation for the plainbox python3 library
diff --git a/debian/copyright b/debian/copyright
new file mode 100644
index 0000000..5784a09
--- /dev/null
+++ b/debian/copyright
@@ -0,0 +1,207 @@
+Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: plainbox
+Source: https://launchpad.net/checkbox
+
+Files: *
+Copyright: Copyright 2012-2015 Canonical Ltd.
+License: GPL-3
+ 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.
+ .
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ .
+ On Debian-based systems the full text of the GPL, version 3, can be found at
+ /usr/share/common-licenses/GPL-3.
+
+Files: plainbox/vendor/extcmd/*
+Copyright:
+ Copyright (c) 2010-2012 Linaro Limited
+ Copyright (c) 2013 Canonical Ltd.
+License: GPL-3+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+ .
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+ .
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ .
+ On Debian-based systems the full text of the GPL, version 3, can be found at
+ /usr/share/common-licenses/GPL-3.
+
+Files: plainbox/vendor/funcsigs/*
+Copyright:
+ Copyright 2013 Aaron Iles
+ Copyright 2001-2013 Python Software Foundation;
+License: Apache-2.0
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+ .
+  http://www.apache.org/licenses/LICENSE-2.0
+ .
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ .
+ On Debian-based systems the full text of the Apache, version 2.0, can be found
+ at /usr/share/common-licenses/Apache-2.0.
+
+Files: plainbox/vendor/mock.py
+Copyright: Copyright (C) 2007-2012 Michael Foord & the mock team
+License: BSD-3-clause
+ Redistribution and use in source and binary forms, with or without
+ modification, are permitted provided that the following conditions are
+ met:
+ .
+ .
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+ .
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+ .
+    * Neither the name of Michael Foord nor the name of Voidspace
+      may be used to endorse or promote products derived from this
+      software without specific prior written permission.
+ .
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+ A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+ THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+Files: plainbox/vendor/argparse/*.py
+Copyright: Steven J. Bethard <[e-mail]>.
+License: Python
+
+Files: plainbox/vendor/sphinxarg/*
+Copyright: Copyright (c) 2013 Alex Rudakov
+License: MIT
+ The MIT License (MIT)
+ .
+ Permission is hereby granted, free of charge, to any person obtaining a copy of
+ this software and associated documentation files (the "Software"), to deal in
+ the Software without restriction, including without limitation the rights to
+ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+ the Software, and to permit persons to whom the Software is furnished to do so,
+ subject to the following conditions:
+ .
+ The above copyright notice and this permission notice shall be included in all
+ copies or substantial portions of the Software.
+ .
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+ FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+ COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Files: plainbox/vendor/morris/*
+Copyright: Copyright (c) 2012-15 Canonical Ltd.
+License: LGPL-3+
+
+Files: plainbox/vendor/glibc.py
+Copyright: Copyright (c) 2014 Canonical Ltd.
+License: LGPL-3+
+
+Files: plainbox/vendor/pyglibc/*
+Copyright: Copyright (c) 2014 Canonical Ltd.
+License: LGPL-3+
+
+Files: plainbox/impl/_argparse.py
+Copyright: Steven J. Bethard <[e-mail]>.
+License: Python
+
+Files: plainbox/impl/_shlex.py
+Copyright:
+ Module and documentation by Eric S. Raymond, 21 Dec 1998
+ Input stacking and error message cleanup added by ESR, March 2000
+ push_source() and pop_source() made explicit by ESR, January 2001.
+ Posix compliance, split(), string arguments, and
+ iterator interface by Gustavo Niemeyer, April 2003.
+License: Python
+
+License: Python
+ PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2
+ --------------------------------------------
+ .
+ 1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"),
+    and the Individual or Organization ("Licensee") accessing and otherwise
+    using this software ("Python") in source or binary form and its associated
+    documentation.
+ .
+ 2. Subject to the terms and conditions of this License Agreement, PSF hereby
+    grants Licensee a nonexclusive, royalty-free, world-wide license to
+    reproduce, analyze, test, perform and/or display publicly, prepare
+    derivative works, distribute, and otherwise use Python alone or in any
+    derivative version, provided, however, that PSF's License Agreement and
+    PSF's notice of copyright, i.e., "Copyright (c) 2001, 2002, 2003, 2004,
+    2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014 Python Software
+    Foundation; All Rights Reserved" are retained in Python alone or in any
+    derivative version prepared by Licensee.
+ .
+ 3. In the event Licensee prepares a derivative work that is based on or
+    incorporates Python or any part thereof, and wants to make the derivative
+    work available to others as provided herein, then Licensee hereby agrees
+    to include in any such work a brief summary of the changes made to Python.
+ .
+ 4. PSF is making Python available to Licensee on an "AS IS" basis.  PSF MAKES
+    NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.  BY WAY OF EXAMPLE,
+    BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY REPRESENTATION OR
+    WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT
+    THE USE OF PYTHON WILL NOT INFRINGE ANY THIRD PARTY RIGHTS.
+ .
+ 5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON FOR ANY
+    INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS A RESULT OF
+    MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON, OR ANY DERIVATIVE
+    THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
+ .
+ 6. This License Agreement will automatically terminate upon a material breach
+    of its terms and conditions.
+ .
+ 7. Nothing in this License Agreement shall be deemed to create any
+    relationship of agency, partnership, or joint venture between PSF and
+    Licensee.  This License Agreement does not grant permission to use PSF
+    trademarks or trade name in a trademark sense to endorse or promote
+    products or services of Licensee, or any third party.
+ .
+ 8. By copying, installing or otherwise using Python, Licensee agrees to be
+    bound by the terms and conditions of this License Agreement.
+
+License: LGPL-3+
+ This file is part of Morris.
+ .
+ Morris is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Lesser General Public License as published by
+ the Free Software Foundation, either version 3 of the License.
+ .
+ Morris is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Lesser General Public License for more details.
+ .
+ You should have received a copy of the GNU Lesser General Public License
+ along with Morris.  If not, see <http://www.gnu.org/licenses/>.
diff --git a/debian/patches/documentation-theme b/debian/patches/documentation-theme
new file mode 100644
index 0000000..d0306e7
--- /dev/null
+++ b/debian/patches/documentation-theme
@@ -0,0 +1,42 @@
+From c2d46ce5be7fb38b74c536e85865128af008d864 Mon Sep 17 00:00:00 2001
+From: Zygmunt Krynicki <[e-mail]>
+Date: Thu, 8 Oct 2015 10:13:55 -0700
+Subject: Revert the documentation theme back to default
+
+ PlainBox uses a customized sphinx theme that includes additional
+ HTML to integrate with online comment service. This should not be
+ a part of the offline documentation package.
+Origin: upstream
+Forwarded: not-needed
+Last-Update: 2015-07-21
+
+Patch-Name: documentation-theme
+---
+ docs/conf.py | 10 +---------
+ 1 file changed, 1 insertion(+), 9 deletions(-)
+
+diff --git a/docs/conf.py b/docs/conf.py
+index 07bd76e..ab2ab04 100644
+--- a/docs/conf.py
++++ b/docs/conf.py
+@@ -124,19 +124,11 @@ pygments_style = 'sphinx'
+ # Use our custom theme. For now it only adds Disqus.com support but we may
+ # customize it further later on. The theme is called 'plainbox' and has one
+ # option which controls if disqus is active or not.
+-html_theme = 'plainbox'
++html_theme = 'default'
+ 
+ # Theme options are theme-specific and customize the look and feel of a theme
+ # further.  For a list of options available for each theme, see the
+ # documentation.
+-#
+-# Due to the way disqus works, it's only going to work on
+-# plainbox.readthedocs.org so only use it if building for readthedocs.
+-
+-html_theme_options = {
+-    'show_disqus': 'true' if os.environ.get(
+-        "READTHEDOCS", None) == 'True' else ''
+-}
+ 
+ # Add any paths that contain custom themes here, relative to this directory.
+ html_theme_path = ['_theme']
diff --git a/debian/patches/series b/debian/patches/series
new file mode 100644
index 0000000..5313c71
--- /dev/null
+++ b/debian/patches/series
@@ -0,0 +1,3 @@
+unvendorize
+silence-logging-failure
+documentation-theme
diff --git a/debian/patches/silence-logging-failure b/debian/patches/silence-logging-failure
new file mode 100644
index 0000000..c61779b
--- /dev/null
+++ b/debian/patches/silence-logging-failure
@@ -0,0 +1,37 @@
+From 648f8eb6ebd6465b85608915bb7ae1b021f5e809 Mon Sep 17 00:00:00 2001
+From: Zygmunt Krynicki <[e-mail]>
+Date: Thu, 8 Oct 2015 10:13:54 -0700
+Subject: Silence setup failure of the logging subsystem
+
+ The logging subsystem has a feature that displays two lines of warnings
+ if the per-user log file cannot be created. This leads to spurious
+ errors when plainbox is invoked from a build environment. Before a
+ better solution is found this warning is disabled as all of the
+ subsequent, relevant, logging messages are display either way.
+Bug-Ubuntu: https://bugs.launchpad.net/checkbox/+bug/1262898
+Forwarded: yes
+Last-Update: 2014-03-18
+
+Patch-Name: silence-logging-failure
+---
+ plainbox/impl/logging.py | 5 -----
+ 1 file changed, 5 deletions(-)
+
+diff --git a/plainbox/impl/logging.py b/plainbox/impl/logging.py
+index 85fe7dd..6e66da0 100644
+--- a/plainbox/impl/logging.py
++++ b/plainbox/impl/logging.py
+@@ -95,12 +95,6 @@ class LoggingHelper:
+             try:
+                 os.makedirs(self.log_dir, exist_ok=True)
+             except OSError as error:
+-                if not config_dict.get(
+-                        'silence_eperm_on_logdir_warning', False):
+-                    logger.warning(
+-                        _("Unable to create log directory: %s"), self.log_dir)
+-                    logger.warning(_("Reason: %s. All logs will go to "
+-                                    "console instead."), error)
+                 config_dict = self.DEFAULT_CONSOLE_ONLY_CONFIG
+         # Apply the selected configuration. This overrides anything currently
+         # defined for all of the logging subsystem in this python runtime
+
diff --git a/debian/patches/unvendorize b/debian/patches/unvendorize
new file mode 100644
index 0000000..fce9d34
--- /dev/null
+++ b/debian/patches/unvendorize
@@ -0,0 +1,2434 @@
+From e112ce0246c305cba81c457e8aa3a7c40e87ab13 Mon Sep 17 00:00:00 2001
+From: Zygmunt Krynicki <[e-mail]>
+Date: Thu, 8 Oct 2015 10:13:53 -0700
+Subject: Remove vendorized modules
+
+ This patch replaces plainbox.vendor.mock with equivalent imports from the
+ standard python3.3 library. Upstream will stop shipping those vendorized
+ modules when support for python3.2 is no longer required.
+Upstream: not-needed
+Last-Update: 2018-01-12
+
+Patch-Name: unvendorize
+---
+ plainbox/vendor/__init__.py |    5 +
+ plainbox/vendor/mock.py     | 2398 +------------------------------------------
+ 2 files changed, 34 insertions(+), 2369 deletions(-)
+
+diff --git a/plainbox/vendor/__init__.py b/plainbox/vendor/__init__.py
+index d4ed746..188c398 100644
+--- a/plainbox/vendor/__init__.py
++++ b/plainbox/vendor/__init__.py
+@@ -25,4 +25,9 @@ This module contains external packages that were vendorized (shipped with a
+ tree of another project) to simplify dependency management. There is no problem
+ with expressing those dependencies at pypi level but it would be annoying to
+ have to first package and introduce them to Ubuntu.
++
++.. note::
++    The ``plainbox.vendor`` package is modified by Debian not to ship a copy of
++    the ``unittest.mock`` and updated ``inspect`` modules that are already
++    available in python3.3
+ """
+diff --git a/plainbox/vendor/mock.py b/plainbox/vendor/mock.py
+index ca77df6..9916e39 100644
+--- a/plainbox/vendor/mock.py
++++ b/plainbox/vendor/mock.py
+@@ -1,2369 +1,29 @@
+-# mock.py
+-# Test tools for mocking and patching.
+-# Copyright (C) 2007-2012 Michael Foord & the mock team
+-# E-mail: fuzzyman AT voidspace DOT org DOT uk
+-
+-# mock 1.0
+-# http://www.voidspace.org.uk/python/mock/
+-
+-# Released subject to the BSD License
+-# Please see http://www.voidspace.org.uk/python/license.shtml
+-
+-# Scripts maintained at http://www.voidspace.org.uk/python/index.shtml
+-# Comments, suggestions and bug reports welcome.
+-
+-
+-__all__ = (
+-    'Mock',
+-    'MagicMock',
+-    'patch',
+-    'sentinel',
+-    'DEFAULT',
+-    'ANY',
+-    'call',
+-    'create_autospec',
+-    'FILTER_DIR',
+-    'NonCallableMock',
+-    'NonCallableMagicMock',
+-    'mock_open',
+-    'PropertyMock',
+-)
+-
+-
+-__version__ = '1.0.1'
+-
+-
+-import pprint
+-import sys
+-
+-try:
+-    import inspect
+-except ImportError:
+-    # for alternative platforms that
+-    # may not have inspect
+-    inspect = None
+-
+-try:
+-    from functools import wraps as original_wraps
+-except ImportError:
+-    # Python 2.4 compatibility
+-    def wraps(original):
+-        def inner(f):
+-            f.__name__ = original.__name__
+-            f.__doc__ = original.__doc__
+-            f.__module__ = original.__module__
+-            f.__wrapped__ = original
+-            return f
+-        return inner
+-else:
+-    if sys.version_info[:2] >= (3, 3):
+-        wraps = original_wraps
+-    else:
+-        def wraps(func):
+-            def inner(f):
+-                f = original_wraps(func)(f)
+-                f.__wrapped__ = func
+-                return f
+-            return inner
+-
+-try:
+-    unicode
+-except NameError:
+-    # Python 3
+-    basestring = unicode = str
+-
+-try:
+-    long
+-except NameError:
+-    # Python 3
+-    long = int
+-
+-try:
+-    BaseException
+-except NameError:
+-    # Python 2.4 compatibility
+-    BaseException = Exception
+-
+-try:
+-    next
+-except NameError:
+-    def next(obj):
+-        return obj.next()
+-
+-
+-BaseExceptions = (BaseException,)
+-if 'java' in sys.platform:
+-    # jython
+-    import java
+-    BaseExceptions = (BaseException, java.lang.Throwable)
+-
+-try:
+-    _isidentifier = str.isidentifier
+-except AttributeError:
+-    # Python 2.X
+-    import keyword
+-    import re
+-    regex = re.compile(r'^[a-z_][a-z0-9_]*$', re.I)
+-    def _isidentifier(string):
+-        if string in keyword.kwlist:
+-            return False
+-        return regex.match(string)
+-
+-
+-inPy3k = sys.version_info[0] == 3
+-
+-# Needed to work around Python 3 bug where use of "super" interferes with
+-# defining __class__ as a descriptor
+-_super = super
+-
+-self = 'im_self'
+-builtin = '__builtin__'
+-if inPy3k:
+-    self = '__self__'
+-    builtin = 'builtins'
+-
+-FILTER_DIR = True
+-
+-
+-def _is_instance_mock(obj):
+-    # can't use isinstance on Mock objects because they override __class__
+-    # The base class for all mocks is NonCallableMock
+-    return issubclass(type(obj), NonCallableMock)
+-
+-
+-def _is_exception(obj):
+-    return (
+-        isinstance(obj, BaseExceptions) or
+-        isinstance(obj, ClassTypes) and issubclass(obj, BaseExceptions)
+-    )
+-
+-
+-class _slotted(object):
+-    __slots__ = ['a']
+-
+-
+-DescriptorTypes = (
+-    type(_slotted.a),
+-    property,
+-)
+-
+-
+-def _getsignature(func, skipfirst, instance=False):
+-    if inspect is None:
+-        raise ImportError('inspect module not available')
+-
+-    if isinstance(func, ClassTypes) and not instance:
+-        try:
+-            func = func.__init__
+-        except AttributeError:
+-            return
+-        skipfirst = True
+-    elif not isinstance(func, FunctionTypes):
+-        # for classes where instance is True we end up here too
+-        try:
+-            func = func.__call__
+-        except AttributeError:
+-            return
+-
+-    if inPy3k:
+-        try:
+-            argspec = inspect.getfullargspec(func)
+-        except TypeError:
+-            # C function / method, possibly inherited object().__init__
+-            return
+-        regargs, varargs, varkw, defaults, kwonly, kwonlydef, ann = argspec
+-    else:
+-        try:
+-            regargs, varargs, varkwargs, defaults = inspect.getargspec(func)
+-        except TypeError:
+-            # C function / method, possibly inherited object().__init__
+-            return
+-
+-    # instance methods and classmethods need to lose the self argument
+-    if getattr(func, self, None) is not None:
+-        regargs = regargs[1:]
+-    if skipfirst:
+-        # this condition and the above one are never both True - why?
+-        regargs = regargs[1:]
+-
+-    if inPy3k:
+-        signature = inspect.formatargspec(
+-            regargs, varargs, varkw, defaults,
+-            kwonly, kwonlydef, ann, formatvalue=lambda value: "")
+-    else:
+-        signature = inspect.formatargspec(
+-            regargs, varargs, varkwargs, defaults,
+-            formatvalue=lambda value: "")
+-    return signature[1:-1], func
+-
+-
+-def _check_signature(func, mock, skipfirst, instance=False):
+-    if not _callable(func):
+-        return
+-
+-    result = _getsignature(func, skipfirst, instance)
+-    if result is None:
+-        return
+-    signature, func = result
+-
+-    # can't use self because "self" is common as an argument name
+-    # unfortunately even not in the first place
+-    src = "lambda _mock_self, %s: None" % signature
+-    checksig = eval(src, {})
+-    _copy_func_details(func, checksig)
+-    type(mock)._mock_check_sig = checksig
+-
+-
+-def _copy_func_details(func, funcopy):
+-    funcopy.__name__ = func.__name__
+-    funcopy.__doc__ = func.__doc__
+-    #funcopy.__dict__.update(func.__dict__)
+-    funcopy.__module__ = func.__module__
+-    if not inPy3k:
+-        funcopy.func_defaults = func.func_defaults
+-        return
+-    funcopy.__defaults__ = func.__defaults__
+-    funcopy.__kwdefaults__ = func.__kwdefaults__
+-
+-
+-def _callable(obj):
+-    if isinstance(obj, ClassTypes):
+-        return True
+-    if getattr(obj, '__call__', None) is not None:
+-        return True
+-    return False
+-
+-
+-def _is_list(obj):
+-    # checks for list or tuples
+-    # XXXX badly named!
+-    return type(obj) in (list, tuple)
+-
+-
+-def _instance_callable(obj):
+-    """Given an object, return True if the object is callable.
+-    For classes, return True if instances would be callable."""
+-    if not isinstance(obj, ClassTypes):
+-        # already an instance
+-        return getattr(obj, '__call__', None) is not None
+-
+-    klass = obj
+-    # uses __bases__ instead of __mro__ so that we work with old style classes
+-    if klass.__dict__.get('__call__') is not None:
+-        return True
+-
+-    for base in klass.__bases__:
+-        if _instance_callable(base):
+-            return True
+-    return False
+-
+-
+-def _set_signature(mock, original, instance=False):
+-    # creates a function with signature (*args, **kwargs) that delegates to a
+-    # mock. It still does signature checking by calling a lambda with the same
+-    # signature as the original.
+-    if not _callable(original):
+-        return
+-
+-    skipfirst = isinstance(original, ClassTypes)
+-    result = _getsignature(original, skipfirst, instance)
+-    if result is None:
+-        # was a C function (e.g. object().__init__ ) that can't be mocked
+-        return
+-
+-    signature, func = result
+-
+-    src = "lambda %s: None" % signature
+-    checksig = eval(src, {})
+-    _copy_func_details(func, checksig)
+-
+-    name = original.__name__
+-    if not _isidentifier(name):
+-        name = 'funcopy'
+-    context = {'_checksig_': checksig, 'mock': mock}
+-    src = """def %s(*args, **kwargs):
+-    _checksig_(*args, **kwargs)
+-    return mock(*args, **kwargs)""" % name
+-    exec (src, context)
+-    funcopy = context[name]
+-    _setup_func(funcopy, mock)
+-    return funcopy
+-
+-
+-def _setup_func(funcopy, mock):
+-    funcopy.mock = mock
+-
+-    # can't use isinstance with mocks
+-    if not _is_instance_mock(mock):
+-        return
+-
+-    def assert_called_with(*args, **kwargs):
+-        return mock.assert_called_with(*args, **kwargs)
+-    def assert_called_once_with(*args, **kwargs):
+-        return mock.assert_called_once_with(*args, **kwargs)
+-    def assert_has_calls(*args, **kwargs):
+-        return mock.assert_has_calls(*args, **kwargs)
+-    def assert_any_call(*args, **kwargs):
+-        return mock.assert_any_call(*args, **kwargs)
+-    def reset_mock():
+-        funcopy.method_calls = _CallList()
+-        funcopy.mock_calls = _CallList()
+-        mock.reset_mock()
+-        ret = funcopy.return_value
+-        if _is_instance_mock(ret) and not ret is mock:
+-            ret.reset_mock()
+-
+-    funcopy.called = False
+-    funcopy.call_count = 0
+-    funcopy.call_args = None
+-    funcopy.call_args_list = _CallList()
+-    funcopy.method_calls = _CallList()
+-    funcopy.mock_calls = _CallList()
+-
+-    funcopy.return_value = mock.return_value
+-    funcopy.side_effect = mock.side_effect
+-    funcopy._mock_children = mock._mock_children
+-
+-    funcopy.assert_called_with = assert_called_with
+-    funcopy.assert_called_once_with = assert_called_once_with
+-    funcopy.assert_has_calls = assert_has_calls
+-    funcopy.assert_any_call = assert_any_call
+-    funcopy.reset_mock = reset_mock
+-
+-    mock._mock_delegate = funcopy
+-
+-
+-def _is_magic(name):
+-    return '__%s__' % name[2:-2] == name
+-
+-
+-class _SentinelObject(object):
+-    "A unique, named, sentinel object."
+-    def __init__(self, name):
+-        self.name = name
+-
+-    def __repr__(self):
+-        return 'sentinel.%s' % self.name
+-
+-
+-class _Sentinel(object):
+-    """Access attributes to return a named object, usable as a sentinel."""
+-    def __init__(self):
+-        self._sentinels = {}
+-
+-    def __getattr__(self, name):
+-        if name == '__bases__':
+-            # Without this help(mock) raises an exception
+-            raise AttributeError
+-        return self._sentinels.setdefault(name, _SentinelObject(name))
+-
+-
+-sentinel = _Sentinel()
+-
+-DEFAULT = sentinel.DEFAULT
+-_missing = sentinel.MISSING
+-_deleted = sentinel.DELETED
+-
+-
+-class OldStyleClass:
+-    pass
+-ClassType = type(OldStyleClass)
+-
+-
+-def _copy(value):
+-    if type(value) in (dict, list, tuple, set):
+-        return type(value)(value)
+-    return value
+-
+-
+-ClassTypes = (type,)
+-if not inPy3k:
+-    ClassTypes = (type, ClassType)
+-
+-_allowed_names = set(
+-    [
+-        'return_value', '_mock_return_value', 'side_effect',
+-        '_mock_side_effect', '_mock_parent', '_mock_new_parent',
+-        '_mock_name', '_mock_new_name'
+-    ]
+-)
+-
+-
+-def _delegating_property(name):
+-    _allowed_names.add(name)
+-    _the_name = '_mock_' + name
+-    def _get(self, name=name, _the_name=_the_name):
+-        sig = self._mock_delegate
+-        if sig is None:
+-            return getattr(self, _the_name)
+-        return getattr(sig, name)
+-    def _set(self, value, name=name, _the_name=_the_name):
+-        sig = self._mock_delegate
+-        if sig is None:
+-            self.__dict__[_the_name] = value
+-        else:
+-            setattr(sig, name, value)
+-
+-    return property(_get, _set)
+-
+-
+-
+-class _CallList(list):
+-
+-    def __contains__(self, value):
+-        if not isinstance(value, list):
+-            return list.__contains__(self, value)
+-        len_value = len(value)
+-        len_self = len(self)
+-        if len_value > len_self:
+-            return False
+-
+-        for i in range(0, len_self - len_value + 1):
+-            sub_list = self[i:i+len_value]
+-            if sub_list == value:
+-                return True
+-        return False
+-
+-    def __repr__(self):
+-        return pprint.pformat(list(self))
+-
+-
+-def _check_and_set_parent(parent, value, name, new_name):
+-    if not _is_instance_mock(value):
+-        return False
+-    if ((value._mock_name or value._mock_new_name) or
+-        (value._mock_parent is not None) or
+-        (value._mock_new_parent is not None)):
+-        return False
+-
+-    _parent = parent
+-    while _parent is not None:
+-        # setting a mock (value) as a child or return value of itself
+-        # should not modify the mock
+-        if _parent is value:
+-            return False
+-        _parent = _parent._mock_new_parent
+-
+-    if new_name:
+-        value._mock_new_parent = parent
+-        value._mock_new_name = new_name
+-    if name:
+-        value._mock_parent = parent
+-        value._mock_name = name
+-    return True
+-
+-
+-
+-class Base(object):
+-    _mock_return_value = DEFAULT
+-    _mock_side_effect = None
+-    def __init__(self, *args, **kwargs):
+-        pass
+-
+-
+-
+-class NonCallableMock(Base):
+-    """A non-callable version of `Mock`"""
+-
+-    def __new__(cls, *args, **kw):
+-        # every instance has its own class
+-        # so we can create magic methods on the
+-        # class without stomping on other mocks
+-        new = type(cls.__name__, (cls,), {'__doc__': cls.__doc__})
+-        instance = object.__new__(new)
+-        return instance
+-
+-
+-    def __init__(
+-            self, spec=None, wraps=None, name=None, spec_set=None,
+-            parent=None, _spec_state=None, _new_name='', _new_parent=None,
+-            **kwargs
+-        ):
+-        if _new_parent is None:
+-            _new_parent = parent
+-
+-        __dict__ = self.__dict__
+-        __dict__['_mock_parent'] = parent
+-        __dict__['_mock_name'] = name
+-        __dict__['_mock_new_name'] = _new_name
+-        __dict__['_mock_new_parent'] = _new_parent
+-
+-        if spec_set is not None:
+-            spec = spec_set
+-            spec_set = True
+-
+-        self._mock_add_spec(spec, spec_set)
+-
+-        __dict__['_mock_children'] = {}
+-        __dict__['_mock_wraps'] = wraps
+-        __dict__['_mock_delegate'] = None
+-
+-        __dict__['_mock_called'] = False
+-        __dict__['_mock_call_args'] = None
+-        __dict__['_mock_call_count'] = 0
+-        __dict__['_mock_call_args_list'] = _CallList()
+-        __dict__['_mock_mock_calls'] = _CallList()
+-
+-        __dict__['method_calls'] = _CallList()
+-
+-        if kwargs:
+-            self.configure_mock(**kwargs)
+-
+-        _super(NonCallableMock, self).__init__(
+-            spec, wraps, name, spec_set, parent,
+-            _spec_state
+-        )
+-
+-
+-    def attach_mock(self, mock, attribute):
+-        """
+-        Attach a mock as an attribute of this one, replacing its name and
+-        parent. Calls to the attached mock will be recorded in the
+-        `method_calls` and `mock_calls` attributes of this one."""
+-        mock._mock_parent = None
+-        mock._mock_new_parent = None
+-        mock._mock_name = ''
+-        mock._mock_new_name = None
+-
+-        setattr(self, attribute, mock)
+-
+-
+-    def mock_add_spec(self, spec, spec_set=False):
+-        """Add a spec to a mock. `spec` can either be an object or a
+-        list of strings. Only attributes on the `spec` can be fetched as
+-        attributes from the mock.
+-
+-        If `spec_set` is True then only attributes on the spec can be set."""
+-        self._mock_add_spec(spec, spec_set)
+-
+-
+-    def _mock_add_spec(self, spec, spec_set):
+-        _spec_class = None
+-
+-        if spec is not None and not _is_list(spec):
+-            if isinstance(spec, ClassTypes):
+-                _spec_class = spec
+-            else:
+-                _spec_class = _get_class(spec)
+-
+-            spec = dir(spec)
+-
+-        __dict__ = self.__dict__
+-        __dict__['_spec_class'] = _spec_class
+-        __dict__['_spec_set'] = spec_set
+-        __dict__['_mock_methods'] = spec
+-
+-
+-    def __get_return_value(self):
+-        ret = self._mock_return_value
+-        if self._mock_delegate is not None:
+-            ret = self._mock_delegate.return_value
+-
+-        if ret is DEFAULT:
+-            ret = self._get_child_mock(
+-                _new_parent=self, _new_name='()'
+-            )
+-            self.return_value = ret
+-        return ret
+-
+-
+-    def __set_return_value(self, value):
+-        if self._mock_delegate is not None:
+-            self._mock_delegate.return_value = value
+-        else:
+-            self._mock_return_value = value
+-            _check_and_set_parent(self, value, None, '()')
+-
+-    __return_value_doc = "The value to be returned when the mock is called."
+-    return_value = property(__get_return_value, __set_return_value,
+-                            __return_value_doc)
+-
+-
+-    @property
+-    def __class__(self):
+-        if self._spec_class is None:
+-            return type(self)
+-        return self._spec_class
+-
+-    called = _delegating_property('called')
+-    call_count = _delegating_property('call_count')
+-    call_args = _delegating_property('call_args')
+-    call_args_list = _delegating_property('call_args_list')
+-    mock_calls = _delegating_property('mock_calls')
+-
+-
+-    def __get_side_effect(self):
+-        sig = self._mock_delegate
+-        if sig is None:
+-            return self._mock_side_effect
+-        return sig.side_effect
+-
+-    def __set_side_effect(self, value):
+-        value = _try_iter(value)
+-        sig = self._mock_delegate
+-        if sig is None:
+-            self._mock_side_effect = value
+-        else:
+-            sig.side_effect = value
+-
+-    side_effect = property(__get_side_effect, __set_side_effect)
+-
+-
+-    def reset_mock(self):
+-        "Restore the mock object to its initial state."
+-        self.called = False
+-        self.call_args = None
+-        self.call_count = 0
+-        self.mock_calls = _CallList()
+-        self.call_args_list = _CallList()
+-        self.method_calls = _CallList()
+-
+-        for child in self._mock_children.values():
+-            if isinstance(child, _SpecState):
+-                continue
+-            child.reset_mock()
+-
+-        ret = self._mock_return_value
+-        if _is_instance_mock(ret) and ret is not self:
+-            ret.reset_mock()
+-
+-
+-    def configure_mock(self, **kwargs):
+-        """Set attributes on the mock through keyword arguments.
+-
+-        Attributes plus return values and side effects can be set on child
+-        mocks using standard dot notation and unpacking a dictionary in the
+-        method call:
+-
+-        >>> attrs = {'method.return_value': 3, 'other.side_effect': KeyError}
+-        >>> mock.configure_mock(**attrs)"""
+-        for arg, val in sorted(kwargs.items(),
+-                               # we sort on the number of dots so that
+-                               # attributes are set before we set attributes on
+-                               # attributes
+-                               key=lambda entry: entry[0].count('.')):
+-            args = arg.split('.')
+-            final = args.pop()
+-            obj = self
+-            for entry in args:
+-                obj = getattr(obj, entry)
+-            setattr(obj, final, val)
+-
+-
+-    def __getattr__(self, name):
+-        if name == '_mock_methods':
+-            raise AttributeError(name)
+-        elif self._mock_methods is not None:
+-            if name not in self._mock_methods or name in _all_magics:
+-                raise AttributeError("Mock object has no attribute %r" % name)
+-        elif _is_magic(name):
+-            raise AttributeError(name)
+-        if name.startswith(('assert', 'assret')):
+-            raise AttributeError(name)
+-
+-        result = self._mock_children.get(name)
+-        if result is _deleted:
+-            raise AttributeError(name)
+-        elif result is None:
+-            wraps = None
+-            if self._mock_wraps is not None:
+-                # XXXX should we get the attribute without triggering code
+-                # execution?
+-                wraps = getattr(self._mock_wraps, name)
+-
+-            result = self._get_child_mock(
+-                parent=self, name=name, wraps=wraps, _new_name=name,
+-                _new_parent=self
+-            )
+-            self._mock_children[name]  = result
+-
+-        elif isinstance(result, _SpecState):
+-            result = create_autospec(
+-                result.spec, result.spec_set, result.instance,
+-                result.parent, result.name
+-            )
+-            self._mock_children[name]  = result
+-
+-        return result
+-
+-
+-    def __repr__(self):
+-        _name_list = [self._mock_new_name]
+-        _parent = self._mock_new_parent
+-        last = self
+-
+-        dot = '.'
+-        if _name_list == ['()']:
+-            dot = ''
+-        seen = set()
+-        while _parent is not None:
+-            last = _parent
+-
+-            _name_list.append(_parent._mock_new_name + dot)
+-            dot = '.'
+-            if _parent._mock_new_name == '()':
+-                dot = ''
+-
+-            _parent = _parent._mock_new_parent
+-
+-            # use ids here so as not to call __hash__ on the mocks
+-            if id(_parent) in seen:
+-                break
+-            seen.add(id(_parent))
+-
+-        _name_list = list(reversed(_name_list))
+-        _first = last._mock_name or 'mock'
+-        if len(_name_list) > 1:
+-            if _name_list[1] not in ('()', '().'):
+-                _first += '.'
+-        _name_list[0] = _first
+-        name = ''.join(_name_list)
+-
+-        name_string = ''
+-        if name not in ('mock', 'mock.'):
+-            name_string = ' name=%r' % name
+-
+-        spec_string = ''
+-        if self._spec_class is not None:
+-            spec_string = ' spec=%r'
+-            if self._spec_set:
+-                spec_string = ' spec_set=%r'
+-            spec_string = spec_string % self._spec_class.__name__
+-        return "<%s%s%s id='%s'>" % (
+-            type(self).__name__,
+-            name_string,
+-            spec_string,
+-            id(self)
+-        )
+-
+-
+-    def __dir__(self):
+-        """Filter the output of `dir(mock)` to only useful members.
+-        XXXX
+-        """
+-        extras = self._mock_methods or []
+-        from_type = dir(type(self))
+-        from_dict = list(self.__dict__)
+-
+-        if FILTER_DIR:
+-            from_type = [e for e in from_type if not e.startswith('_')]
+-            from_dict = [e for e in from_dict if not e.startswith('_') or
+-                         _is_magic(e)]
+-        return sorted(set(extras + from_type + from_dict +
+-                          list(self._mock_children)))
+-
+-
+-    def __setattr__(self, name, value):
+-        if name in _allowed_names:
+-            # property setters go through here
+-            return object.__setattr__(self, name, value)
+-        elif (self._spec_set and self._mock_methods is not None and
+-            name not in self._mock_methods and
+-            name not in self.__dict__):
+-            raise AttributeError("Mock object has no attribute '%s'" % name)
+-        elif name in _unsupported_magics:
+-            msg = 'Attempting to set unsupported magic method %r.' % name
+-            raise AttributeError(msg)
+-        elif name in _all_magics:
+-            if self._mock_methods is not None and name not in self._mock_methods:
+-                raise AttributeError("Mock object has no attribute '%s'" % name)
+-
+-            if not _is_instance_mock(value):
+-                setattr(type(self), name, _get_method(name, value))
+-                original = value
+-                value = lambda *args, **kw: original(self, *args, **kw)
+-            else:
+-                # only set _new_name and not name so that mock_calls is tracked
+-                # but not method calls
+-                _check_and_set_parent(self, value, None, name)
+-                setattr(type(self), name, value)
+-                self._mock_children[name] = value
+-        elif name == '__class__':
+-            self._spec_class = value
+-            return
+-        else:
+-            if _check_and_set_parent(self, value, name, name):
+-                self._mock_children[name] = value
+-        return object.__setattr__(self, name, value)
+-
+-
+-    def __delattr__(self, name):
+-        if name in _all_magics and name in type(self).__dict__:
+-            delattr(type(self), name)
+-            if name not in self.__dict__:
+-                # for magic methods that are still MagicProxy objects and
+-                # not set on the instance itself
+-                return
+-
+-        if name in self.__dict__:
+-            object.__delattr__(self, name)
+-
+-        obj = self._mock_children.get(name, _missing)
+-        if obj is _deleted:
+-            raise AttributeError(name)
+-        if obj is not _missing:
+-            del self._mock_children[name]
+-        self._mock_children[name] = _deleted
+-
+-
+-
+-    def _format_mock_call_signature(self, args, kwargs):
+-        name = self._mock_name or 'mock'
+-        return _format_call_signature(name, args, kwargs)
+-
+-
+-    def _format_mock_failure_message(self, args, kwargs):
+-        message = 'Expected call: %s\nActual call: %s'
+-        expected_string = self._format_mock_call_signature(args, kwargs)
+-        call_args = self.call_args
+-        if len(call_args) == 3:
+-            call_args = call_args[1:]
+-        actual_string = self._format_mock_call_signature(*call_args)
+-        return message % (expected_string, actual_string)
+-
+-
+-    def assert_called_with(_mock_self, *args, **kwargs):
+-        """assert that the mock was called with the specified arguments.
+-
+-        Raises an AssertionError if the args and keyword args passed in are
+-        different to the last call to the mock."""
+-        self = _mock_self
+-        if self.call_args is None:
+-            expected = self._format_mock_call_signature(args, kwargs)
+-            raise AssertionError('Expected call: %s\nNot called' % (expected,))
+-
+-        if self.call_args != (args, kwargs):
+-            msg = self._format_mock_failure_message(args, kwargs)
+-            raise AssertionError(msg)
+-
+-
+-    def assert_called_once_with(_mock_self, *args, **kwargs):
+-        """assert that the mock was called exactly once and with the specified
+-        arguments."""
+-        self = _mock_self
+-        if not self.call_count == 1:
+-            msg = ("Expected to be called once. Called %s times." %
+-                   self.call_count)
+-            raise AssertionError(msg)
+-        return self.assert_called_with(*args, **kwargs)
+-
+-
+-    def assert_has_calls(self, calls, any_order=False):
+-        """assert the mock has been called with the specified calls.
+-        The `mock_calls` list is checked for the calls.
+-
+-        If `any_order` is False (the default) then the calls must be
+-        sequential. There can be extra calls before or after the
+-        specified calls.
+-
+-        If `any_order` is True then the calls can be in any order, but
+-        they must all appear in `mock_calls`."""
+-        if not any_order:
+-            if calls not in self.mock_calls:
+-                raise AssertionError(
+-                    'Calls not found.\nExpected: %r\n'
+-                    'Actual: %r' % (calls, self.mock_calls)
+-                )
+-            return
+-
+-        all_calls = list(self.mock_calls)
+-
+-        not_found = []
+-        for kall in calls:
+-            try:
+-                all_calls.remove(kall)
+-            except ValueError:
+-                not_found.append(kall)
+-        if not_found:
+-            raise AssertionError(
+-                '%r not all found in call list' % (tuple(not_found),)
+-            )
+-
+-
+-    def assert_any_call(self, *args, **kwargs):
+-        """assert the mock has been called with the specified arguments.
+-
+-        The assert passes if the mock has *ever* been called, unlike
+-        `assert_called_with` and `assert_called_once_with` that only pass if
+-        the call is the most recent one."""
+-        kall = call(*args, **kwargs)
+-        if kall not in self.call_args_list:
+-            expected_string = self._format_mock_call_signature(args, kwargs)
+-            raise AssertionError(
+-                '%s call not found' % expected_string
+-            )
+-
+-
+-    def _get_child_mock(self, **kw):
+-        """Create the child mocks for attributes and return value.
+-        By default child mocks will be the same type as the parent.
+-        Subclasses of Mock may want to override this to customize the way
+-        child mocks are made.
+-
+-        For non-callable mocks the callable variant will be used (rather than
+-        any custom subclass)."""
+-        _type = type(self)
+-        if not issubclass(_type, CallableMixin):
+-            if issubclass(_type, NonCallableMagicMock):
+-                klass = MagicMock
+-            elif issubclass(_type, NonCallableMock) :
+-                klass = Mock
+-        else:
+-            klass = _type.__mro__[1]
+-        return klass(**kw)
+-
+-
+-
+-def _try_iter(obj):
+-    if obj is None:
+-        return obj
+-    if _is_exception(obj):
+-        return obj
+-    if _callable(obj):
+-        return obj
+-    try:
+-        return iter(obj)
+-    except TypeError:
+-        # XXXX backwards compatibility
+-        # but this will blow up on first call - so maybe we should fail early?
+-        return obj
+-
+-
+-
+-class CallableMixin(Base):
+-
+-    def __init__(self, spec=None, side_effect=None, return_value=DEFAULT,
+-                 wraps=None, name=None, spec_set=None, parent=None,
+-                 _spec_state=None, _new_name='', _new_parent=None, **kwargs):
+-        self.__dict__['_mock_return_value'] = return_value
+-
+-        _super(CallableMixin, self).__init__(
+-            spec, wraps, name, spec_set, parent,
+-            _spec_state, _new_name, _new_parent, **kwargs
+-        )
+-
+-        self.side_effect = side_effect
+-
+-
+-    def _mock_check_sig(self, *args, **kwargs):
+-        # stub method that can be replaced with one with a specific signature
+-        pass
+-
+-
+-    def __call__(_mock_self, *args, **kwargs):
+-        # can't use self in-case a function / method we are mocking uses self
+-        # in the signature
+-        _mock_self._mock_check_sig(*args, **kwargs)
+-        return _mock_self._mock_call(*args, **kwargs)
+-
+-
+-    def _mock_call(_mock_self, *args, **kwargs):
+-        self = _mock_self
+-        self.called = True
+-        self.call_count += 1
+-        self.call_args = _Call((args, kwargs), two=True)
+-        self.call_args_list.append(_Call((args, kwargs), two=True))
+-
+-        _new_name = self._mock_new_name
+-        _new_parent = self._mock_new_parent
+-        self.mock_calls.append(_Call(('', args, kwargs)))
+-
+-        seen = set()
+-        skip_next_dot = _new_name == '()'
+-        do_method_calls = self._mock_parent is not None
+-        name = self._mock_name
+-        while _new_parent is not None:
+-            this_mock_call = _Call((_new_name, args, kwargs))
+-            if _new_parent._mock_new_name:
+-                dot = '.'
+-                if skip_next_dot:
+-                    dot = ''
+-
+-                skip_next_dot = False
+-                if _new_parent._mock_new_name == '()':
+-                    skip_next_dot = True
+-
+-                _new_name = _new_parent._mock_new_name + dot + _new_name
+-
+-            if do_method_calls:
+-                if _new_name == name:
+-                    this_method_call = this_mock_call
+-                else:
+-                    this_method_call = _Call((name, args, kwargs))
+-                _new_parent.method_calls.append(this_method_call)
+-
+-                do_method_calls = _new_parent._mock_parent is not None
+-                if do_method_calls:
+-                    name = _new_parent._mock_name + '.' + name
+-
+-            _new_parent.mock_calls.append(this_mock_call)
+-            _new_parent = _new_parent._mock_new_parent
+-
+-            # use ids here so as not to call __hash__ on the mocks
+-            _new_parent_id = id(_new_parent)
+-            if _new_parent_id in seen:
+-                break
+-            seen.add(_new_parent_id)
+-
+-        ret_val = DEFAULT
+-        effect = self.side_effect
+-        if effect is not None:
+-            if _is_exception(effect):
+-                raise effect
+-
+-            if not _callable(effect):
+-                result = next(effect)
+-                if _is_exception(result):
+-                    raise result
+-                return result
+-
+-            ret_val = effect(*args, **kwargs)
+-            if ret_val is DEFAULT:
+-                ret_val = self.return_value
+-
+-        if (self._mock_wraps is not None and
+-             self._mock_return_value is DEFAULT):
+-            return self._mock_wraps(*args, **kwargs)
+-        if ret_val is DEFAULT:
+-            ret_val = self.return_value
+-        return ret_val
+-
+-
+-
+-class Mock(CallableMixin, NonCallableMock):
+-    """
+-    Create a new `Mock` object. `Mock` takes several optional arguments
+-    that specify the behaviour of the Mock object:
+-
+-    * `spec`: This can be either a list of strings or an existing object (a
+-      class or instance) that acts as the specification for the mock object. If
+-      you pass in an object then a list of strings is formed by calling dir on
+-      the object (excluding unsupported magic attributes and methods). Accessing
+-      any attribute not in this list will raise an `AttributeError`.
+-
+-      If `spec` is an object (rather than a list of strings) then
+-      `mock.__class__` returns the class of the spec object. This allows mocks
+-      to pass `isinstance` tests.
+-
+-    * `spec_set`: A stricter variant of `spec`. If used, attempting to *set*
+-      or get an attribute on the mock that isn't on the object passed as
+-      `spec_set` will raise an `AttributeError`.
+-
+-    * `side_effect`: A function to be called whenever the Mock is called. See
+-      the `side_effect` attribute. Useful for raising exceptions or
+-      dynamically changing return values. The function is called with the same
+-      arguments as the mock, and unless it returns `DEFAULT`, the return
+-      value of this function is used as the return value.
+-
+-      Alternatively `side_effect` can be an exception class or instance. In
+-      this case the exception will be raised when the mock is called.
+-
+-      If `side_effect` is an iterable then each call to the mock will return
+-      the next value from the iterable. If any of the members of the iterable
+-      are exceptions they will be raised instead of returned.
+-
+-    * `return_value`: The value returned when the mock is called. By default
+-      this is a new Mock (created on first access). See the
+-      `return_value` attribute.
+-
+-    * `wraps`: Item for the mock object to wrap. If `wraps` is not None then
+-      calling the Mock will pass the call through to the wrapped object
+-      (returning the real result). Attribute access on the mock will return a
+-      Mock object that wraps the corresponding attribute of the wrapped object
+-      (so attempting to access an attribute that doesn't exist will raise an
+-      `AttributeError`).
+-
+-      If the mock has an explicit `return_value` set then calls are not passed
+-      to the wrapped object and the `return_value` is returned instead.
+-
+-    * `name`: If the mock has a name then it will be used in the repr of the
+-      mock. This can be useful for debugging. The name is propagated to child
+-      mocks.
+-
+-    Mocks can also be called with arbitrary keyword arguments. These will be
+-    used to set attributes on the mock after it is created.
+-    """
+-
+-
+-
+-def _dot_lookup(thing, comp, import_path):
+-    try:
+-        return getattr(thing, comp)
+-    except AttributeError:
+-        __import__(import_path)
+-        return getattr(thing, comp)
+-
+-
+-def _importer(target):
+-    components = target.split('.')
+-    import_path = components.pop(0)
+-    thing = __import__(import_path)
+-
+-    for comp in components:
+-        import_path += ".%s" % comp
+-        thing = _dot_lookup(thing, comp, import_path)
+-    return thing
+-
+-
+-def _is_started(patcher):
+-    # XXXX horrible
+-    return hasattr(patcher, 'is_local')
+-
+-
+-class _patch(object):
+-
+-    attribute_name = None
+-    _active_patches = set()
+-
+-    def __init__(
+-            self, getter, attribute, new, spec, create,
+-            spec_set, autospec, new_callable, kwargs
+-        ):
+-        if new_callable is not None:
+-            if new is not DEFAULT:
+-                raise ValueError(
+-                    "Cannot use 'new' and 'new_callable' together"
+-                )
+-            if autospec is not None:
+-                raise ValueError(
+-                    "Cannot use 'autospec' and 'new_callable' together"
+-                )
+-
+-        self.getter = getter
+-        self.attribute = attribute
+-        self.new = new
+-        self.new_callable = new_callable
+-        self.spec = spec
+-        self.create = create
+-        self.has_local = False
+-        self.spec_set = spec_set
+-        self.autospec = autospec
+-        self.kwargs = kwargs
+-        self.additional_patchers = []
+-
+-
+-    def copy(self):
+-        patcher = _patch(
+-            self.getter, self.attribute, self.new, self.spec,
+-            self.create, self.spec_set,
+-            self.autospec, self.new_callable, self.kwargs
+-        )
+-        patcher.attribute_name = self.attribute_name
+-        patcher.additional_patchers = [
+-            p.copy() for p in self.additional_patchers
+-        ]
+-        return patcher
+-
+-
+-    def __call__(self, func):
+-        if isinstance(func, ClassTypes):
+-            return self.decorate_class(func)
+-        return self.decorate_callable(func)
+-
+-
+-    def decorate_class(self, klass):
+-        for attr in dir(klass):
+-            if not attr.startswith(patch.TEST_PREFIX):
+-                continue
+-
+-            attr_value = getattr(klass, attr)
+-            if not hasattr(attr_value, "__call__"):
+-                continue
+-
+-            patcher = self.copy()
+-            setattr(klass, attr, patcher(attr_value))
+-        return klass
+-
+-
+-    def decorate_callable(self, func):
+-        if hasattr(func, 'patchings'):
+-            func.patchings.append(self)
+-            return func
+-
+-        @wraps(func)
+-        def patched(*args, **keywargs):
+-            # don't use a with here (backwards compatability with Python 2.4)
+-            extra_args = []
+-            entered_patchers = []
+-
+-            # can't use try...except...finally because of Python 2.4
+-            # compatibility
+-            exc_info = tuple()
+-            try:
+-                try:
+-                    for patching in patched.patchings:
+-                        arg = patching.__enter__()
+-                        entered_patchers.append(patching)
+-                        if patching.attribute_name is not None:
+-                            keywargs.update(arg)
+-                        elif patching.new is DEFAULT:
+-                            extra_args.append(arg)
+-
+-                    args += tuple(extra_args)
+-                    return func(*args, **keywargs)
+-                except:
+-                    if (patching not in entered_patchers and
+-                        _is_started(patching)):
+-                        # the patcher may have been started, but an exception
+-                        # raised whilst entering one of its additional_patchers
+-                        entered_patchers.append(patching)
+-                    # Pass the exception to __exit__
+-                    exc_info = sys.exc_info()
+-                    # re-raise the exception
+-                    raise
+-            finally:
+-                for patching in reversed(entered_patchers):
+-                    patching.__exit__(*exc_info)
+-
+-        patched.patchings = [self]
+-        if hasattr(func, 'func_code'):
+-            # not in Python 3
+-            patched.compat_co_firstlineno = getattr(
+-                func, "compat_co_firstlineno",
+-                func.func_code.co_firstlineno
+-            )
+-        return patched
+-
+-
+-    def get_original(self):
+-        target = self.getter()
+-        name = self.attribute
+-
+-        original = DEFAULT
+-        local = False
+-
+-        try:
+-            original = target.__dict__[name]
+-        except (AttributeError, KeyError):
+-            original = getattr(target, name, DEFAULT)
+-        else:
+-            local = True
+-
+-        if not self.create and original is DEFAULT:
+-            raise AttributeError(
+-                "%s does not have the attribute %r" % (target, name)
+-            )
+-        return original, local
+-
+-
+-    def __enter__(self):
+-        """Perform the patch."""
+-        new, spec, spec_set = self.new, self.spec, self.spec_set
+-        autospec, kwargs = self.autospec, self.kwargs
+-        new_callable = self.new_callable
+-        self.target = self.getter()
+-
+-        # normalise False to None
+-        if spec is False:
+-            spec = None
+-        if spec_set is False:
+-            spec_set = None
+-        if autospec is False:
+-            autospec = None
+-
+-        if spec is not None and autospec is not None:
+-            raise TypeError("Can't specify spec and autospec")
+-        if ((spec is not None or autospec is not None) and
+-            spec_set not in (True, None)):
+-            raise TypeError("Can't provide explicit spec_set *and* spec or autospec")
+-
+-        original, local = self.get_original()
+-
+-        if new is DEFAULT and autospec is None:
+-            inherit = False
+-            if spec is True:
+-                # set spec to the object we are replacing
+-                spec = original
+-                if spec_set is True:
+-                    spec_set = original
+-                    spec = None
+-            elif spec is not None:
+-                if spec_set is True:
+-                    spec_set = spec
+-                    spec = None
+-            elif spec_set is True:
+-                spec_set = original
+-
+-            if spec is not None or spec_set is not None:
+-                if original is DEFAULT:
+-                    raise TypeError("Can't use 'spec' with create=True")
+-                if isinstance(original, ClassTypes):
+-                    # If we're patching out a class and there is a spec
+-                    inherit = True
+-
+-            Klass = MagicMock
+-            _kwargs = {}
+-            if new_callable is not None:
+-                Klass = new_callable
+-            elif spec is not None or spec_set is not None:
+-                this_spec = spec
+-                if spec_set is not None:
+-                    this_spec = spec_set
+-                if _is_list(this_spec):
+-                    not_callable = '__call__' not in this_spec
+-                else:
+-                    not_callable = not _callable(this_spec)
+-                if not_callable:
+-                    Klass = NonCallableMagicMock
+-
+-            if spec is not None:
+-                _kwargs['spec'] = spec
+-            if spec_set is not None:
+-                _kwargs['spec_set'] = spec_set
+-
+-            # add a name to mocks
+-            if (isinstance(Klass, type) and
+-                issubclass(Klass, NonCallableMock) and self.attribute):
+-                _kwargs['name'] = self.attribute
+-
+-            _kwargs.update(kwargs)
+-            new = Klass(**_kwargs)
+-
+-            if inherit and _is_instance_mock(new):
+-                # we can only tell if the instance should be callable if the
+-                # spec is not a list
+-                this_spec = spec
+-                if spec_set is not None:
+-                    this_spec = spec_set
+-                if (not _is_list(this_spec) and not
+-                    _instance_callable(this_spec)):
+-                    Klass = NonCallableMagicMock
+-
+-                _kwargs.pop('name')
+-                new.return_value = Klass(_new_parent=new, _new_name='()',
+-                                         **_kwargs)
+-        elif autospec is not None:
+-            # spec is ignored, new *must* be default, spec_set is treated
+-            # as a boolean. Should we check spec is not None and that spec_set
+-            # is a bool?
+-            if new is not DEFAULT:
+-                raise TypeError(
+-                    "autospec creates the mock for you. Can't specify "
+-                    "autospec and new."
+-                )
+-            if original is DEFAULT:
+-                raise TypeError("Can't use 'autospec' with create=True")
+-            spec_set = bool(spec_set)
+-            if autospec is True:
+-                autospec = original
+-
+-            new = create_autospec(autospec, spec_set=spec_set,
+-                                  _name=self.attribute, **kwargs)
+-        elif kwargs:
+-            # can't set keyword args when we aren't creating the mock
+-            # XXXX If new is a Mock we could call new.configure_mock(**kwargs)
+-            raise TypeError("Can't pass kwargs to a mock we aren't creating")
+-
+-        new_attr = new
+-
+-        self.temp_original = original
+-        self.is_local = local
+-        setattr(self.target, self.attribute, new_attr)
+-        if self.attribute_name is not None:
+-            extra_args = {}
+-            if self.new is DEFAULT:
+-                extra_args[self.attribute_name] =  new
+-            for patching in self.additional_patchers:
+-                arg = patching.__enter__()
+-                if patching.new is DEFAULT:
+-                    extra_args.update(arg)
+-            return extra_args
+-
+-        return new
+-
+-
+-    def __exit__(self, *exc_info):
+-        """Undo the patch."""
+-        if not _is_started(self):
+-            raise RuntimeError('stop called on unstarted patcher')
+-
+-        if self.is_local and self.temp_original is not DEFAULT:
+-            setattr(self.target, self.attribute, self.temp_original)
+-        else:
+-            delattr(self.target, self.attribute)
+-            if not self.create and not hasattr(self.target, self.attribute):
+-                # needed for proxy objects like django settings
+-                setattr(self.target, self.attribute, self.temp_original)
+-
+-        del self.temp_original
+-        del self.is_local
+-        del self.target
+-        for patcher in reversed(self.additional_patchers):
+-            if _is_started(patcher):
+-                patcher.__exit__(*exc_info)
+-
+-
+-    def start(self):
+-        """Activate a patch, returning any created mock."""
+-        result = self.__enter__()
+-        self._active_patches.add(self)
+-        return result
+-
+-
+-    def stop(self):
+-        """Stop an active patch."""
+-        self._active_patches.discard(self)
+-        return self.__exit__()
+-
+-
+-
+-def _get_target(target):
+-    try:
+-        target, attribute = target.rsplit('.', 1)
+-    except (TypeError, ValueError):
+-        raise TypeError("Need a valid target to patch. You supplied: %r" %
+-                        (target,))
+-    getter = lambda: _importer(target)
+-    return getter, attribute
+-
+-
+-def _patch_object(
+-        target, attribute, new=DEFAULT, spec=None,
+-        create=False, spec_set=None, autospec=None,
+-        new_callable=None, **kwargs
+-    ):
+-    """
+-    patch.object(target, attribute, new=DEFAULT, spec=None, create=False,
+-                 spec_set=None, autospec=None, new_callable=None, **kwargs)
+-
+-    patch the named member (`attribute`) on an object (`target`) with a mock
+-    object.
+-
+-    `patch.object` can be used as a decorator, class decorator or a context
+-    manager. Arguments `new`, `spec`, `create`, `spec_set`,
+-    `autospec` and `new_callable` have the same meaning as for `patch`. Like
+-    `patch`, `patch.object` takes arbitrary keyword arguments for configuring
+-    the mock object it creates.
+-
+-    When used as a class decorator `patch.object` honours `patch.TEST_PREFIX`
+-    for choosing which methods to wrap.
+-    """
+-    getter = lambda: target
+-    return _patch(
+-        getter, attribute, new, spec, create,
+-        spec_set, autospec, new_callable, kwargs
+-    )
+-
+-
+-def _patch_multiple(target, spec=None, create=False, spec_set=None,
+-                    autospec=None, new_callable=None, **kwargs):
+-    """Perform multiple patches in a single call. It takes the object to be
+-    patched (either as an object or a string to fetch the object by importing)
+-    and keyword arguments for the patches::
+-
+-        with patch.multiple(settings, FIRST_PATCH='one', SECOND_PATCH='two'):
+-            ...
+-
+-    Use `DEFAULT` as the value if you want `patch.multiple` to create
+-    mocks for you. In this case the created mocks are passed into a decorated
+-    function by keyword, and a dictionary is returned when `patch.multiple` is
+-    used as a context manager.
+-
+-    `patch.multiple` can be used as a decorator, class decorator or a context
+-    manager. The arguments `spec`, `spec_set`, `create`,
+-    `autospec` and `new_callable` have the same meaning as for `patch`. These
+-    arguments will be applied to *all* patches done by `patch.multiple`.
+-
+-    When used as a class decorator `patch.multiple` honours `patch.TEST_PREFIX`
+-    for choosing which methods to wrap.
+-    """
+-    if type(target) in (unicode, str):
+-        getter = lambda: _importer(target)
+-    else:
+-        getter = lambda: target
+-
+-    if not kwargs:
+-        raise ValueError(
+-            'Must supply at least one keyword argument with patch.multiple'
+-        )
+-    # need to wrap in a list for python 3, where items is a view
+-    items = list(kwargs.items())
+-    attribute, new = items[0]
+-    patcher = _patch(
+-        getter, attribute, new, spec, create, spec_set,
+-        autospec, new_callable, {}
+-    )
+-    patcher.attribute_name = attribute
+-    for attribute, new in items[1:]:
+-        this_patcher = _patch(
+-            getter, attribute, new, spec, create, spec_set,
+-            autospec, new_callable, {}
+-        )
+-        this_patcher.attribute_name = attribute
+-        patcher.additional_patchers.append(this_patcher)
+-    return patcher
+-
+-
+-def patch(
+-        target, new=DEFAULT, spec=None, create=False,
+-        spec_set=None, autospec=None, new_callable=None, **kwargs
+-    ):
+-    """
+-    `patch` acts as a function decorator, class decorator or a context
+-    manager. Inside the body of the function or with statement, the `target`
+-    is patched with a `new` object. When the function/with statement exits
+-    the patch is undone.
+-
+-    If `new` is omitted, then the target is replaced with a
+-    `MagicMock`. If `patch` is used as a decorator and `new` is
+-    omitted, the created mock is passed in as an extra argument to the
+-    decorated function. If `patch` is used as a context manager the created
+-    mock is returned by the context manager.
+-
+-    `target` should be a string in the form `'package.module.ClassName'`. The
+-    `target` is imported and the specified object replaced with the `new`
+-    object, so the `target` must be importable from the environment you are
+-    calling `patch` from. The target is imported when the decorated function
+-    is executed, not at decoration time.
+-
+-    The `spec` and `spec_set` keyword arguments are passed to the `MagicMock`
+-    if patch is creating one for you.
+-
+-    In addition you can pass `spec=True` or `spec_set=True`, which causes
+-    patch to pass in the object being mocked as the spec/spec_set object.
+-
+-    `new_callable` allows you to specify a different class, or callable object,
+-    that will be called to create the `new` object. By default `MagicMock` is
+-    used.
+-
+-    A more powerful form of `spec` is `autospec`. If you set `autospec=True`
+-    then the mock with be created with a spec from the object being replaced.
+-    All attributes of the mock will also have the spec of the corresponding
+-    attribute of the object being replaced. Methods and functions being
+-    mocked will have their arguments checked and will raise a `TypeError` if
+-    they are called with the wrong signature. For mocks replacing a class,
+-    their return value (the 'instance') will have the same spec as the class.
+-
+-    Instead of `autospec=True` you can pass `autospec=some_object` to use an
+-    arbitrary object as the spec instead of the one being replaced.
+-
+-    By default `patch` will fail to replace attributes that don't exist. If
+-    you pass in `create=True`, and the attribute doesn't exist, patch will
+-    create the attribute for you when the patched function is called, and
+-    delete it again afterwards. This is useful for writing tests against
+-    attributes that your production code creates at runtime. It is off by by
+-    default because it can be dangerous. With it switched on you can write
+-    passing tests against APIs that don't actually exist!
+-
+-    Patch can be used as a `TestCase` class decorator. It works by
+-    decorating each test method in the class. This reduces the boilerplate
+-    code when your test methods share a common patchings set. `patch` finds
+-    tests by looking for method names that start with `patch.TEST_PREFIX`.
+-    By default this is `test`, which matches the way `unittest` finds tests.
+-    You can specify an alternative prefix by setting `patch.TEST_PREFIX`.
+-
+-    Patch can be used as a context manager, with the with statement. Here the
+-    patching applies to the indented block after the with statement. If you
+-    use "as" then the patched object will be bound to the name after the
+-    "as"; very useful if `patch` is creating a mock object for you.
+-
+-    `patch` takes arbitrary keyword arguments. These will be passed to
+-    the `Mock` (or `new_callable`) on construction.
+-
+-    `patch.dict(...)`, `patch.multiple(...)` and `patch.object(...)` are
+-    available for alternate use-cases.
+-    """
+-    getter, attribute = _get_target(target)
+-    return _patch(
+-        getter, attribute, new, spec, create,
+-        spec_set, autospec, new_callable, kwargs
+-    )
+-
+-
+-class _patch_dict(object):
+-    """
+-    Patch a dictionary, or dictionary like object, and restore the dictionary
+-    to its original state after the test.
+-
+-    `in_dict` can be a dictionary or a mapping like container. If it is a
+-    mapping then it must at least support getting, setting and deleting items
+-    plus iterating over keys.
+-
+-    `in_dict` can also be a string specifying the name of the dictionary, which
+-    will then be fetched by importing it.
+-
+-    `values` can be a dictionary of values to set in the dictionary. `values`
+-    can also be an iterable of `(key, value)` pairs.
+-
+-    If `clear` is True then the dictionary will be cleared before the new
+-    values are set.
+-
+-    `patch.dict` can also be called with arbitrary keyword arguments to set
+-    values in the dictionary::
+-
+-        with patch.dict('sys.modules', mymodule=Mock(), other_module=Mock()):
+-            ...
+-
+-    `patch.dict` can be used as a context manager, decorator or class
+-    decorator. When used as a class decorator `patch.dict` honours
+-    `patch.TEST_PREFIX` for choosing which methods to wrap.
+-    """
+-
+-    def __init__(self, in_dict, values=(), clear=False, **kwargs):
+-        if isinstance(in_dict, basestring):
+-            in_dict = _importer(in_dict)
+-        self.in_dict = in_dict
+-        # support any argument supported by dict(...) constructor
+-        self.values = dict(values)
+-        self.values.update(kwargs)
+-        self.clear = clear
+-        self._original = None
+-
+-
+-    def __call__(self, f):
+-        if isinstance(f, ClassTypes):
+-            return self.decorate_class(f)
+-        @wraps(f)
+-        def _inner(*args, **kw):
+-            self._patch_dict()
+-            try:
+-                return f(*args, **kw)
+-            finally:
+-                self._unpatch_dict()
+-
+-        return _inner
+-
+-
+-    def decorate_class(self, klass):
+-        for attr in dir(klass):
+-            attr_value = getattr(klass, attr)
+-            if (attr.startswith(patch.TEST_PREFIX) and
+-                 hasattr(attr_value, "__call__")):
+-                decorator = _patch_dict(self.in_dict, self.values, self.clear)
+-                decorated = decorator(attr_value)
+-                setattr(klass, attr, decorated)
+-        return klass
+-
+-
+-    def __enter__(self):
+-        """Patch the dict."""
+-        self._patch_dict()
+-
+-
+-    def _patch_dict(self):
+-        values = self.values
+-        in_dict = self.in_dict
+-        clear = self.clear
+-
+-        try:
+-            original = in_dict.copy()
+-        except AttributeError:
+-            # dict like object with no copy method
+-            # must support iteration over keys
+-            original = {}
+-            for key in in_dict:
+-                original[key] = in_dict[key]
+-        self._original = original
+-
+-        if clear:
+-            _clear_dict(in_dict)
+-
+-        try:
+-            in_dict.update(values)
+-        except AttributeError:
+-            # dict like object with no update method
+-            for key in values:
+-                in_dict[key] = values[key]
+-
+-
+-    def _unpatch_dict(self):
+-        in_dict = self.in_dict
+-        original = self._original
+-
+-        _clear_dict(in_dict)
+-
+-        try:
+-            in_dict.update(original)
+-        except AttributeError:
+-            for key in original:
+-                in_dict[key] = original[key]
+-
+-
+-    def __exit__(self, *args):
+-        """Unpatch the dict."""
+-        self._unpatch_dict()
+-        return False
+-
+-    start = __enter__
+-    stop = __exit__
+-
+-
+-def _clear_dict(in_dict):
+-    try:
+-        in_dict.clear()
+-    except AttributeError:
+-        keys = list(in_dict)
+-        for key in keys:
+-            del in_dict[key]
+-
+-
+-def _patch_stopall():
+-    """Stop all active patches."""
+-    for patch in list(_patch._active_patches):
+-        patch.stop()
+-
+-
+-patch.object = _patch_object
+-patch.dict = _patch_dict
+-patch.multiple = _patch_multiple
+-patch.stopall = _patch_stopall
+-patch.TEST_PREFIX = 'test'
+-
+-magic_methods = (
+-    "lt le gt ge eq ne "
+-    "getitem setitem delitem "
+-    "len contains iter "
+-    "hash str sizeof "
+-    "enter exit "
+-    "divmod neg pos abs invert "
+-    "complex int float index "
+-    "trunc floor ceil "
+-)
+-
+-numerics = "add sub mul div floordiv mod lshift rshift and xor or pow "
+-inplace = ' '.join('i%s' % n for n in numerics.split())
+-right = ' '.join('r%s' % n for n in numerics.split())
+-extra = ''
+-if inPy3k:
+-    extra = 'bool next '
+-else:
+-    extra = 'unicode long nonzero oct hex truediv rtruediv '
+-
+-# not including __prepare__, __instancecheck__, __subclasscheck__
+-# (as they are metaclass methods)
+-# __del__ is not supported at all as it causes problems if it exists
+-
+-_non_defaults = set('__%s__' % method for method in [
+-    'cmp', 'getslice', 'setslice', 'coerce', 'subclasses',
+-    'format', 'get', 'set', 'delete', 'reversed',
+-    'missing', 'reduce', 'reduce_ex', 'getinitargs',
+-    'getnewargs', 'getstate', 'setstate', 'getformat',
+-    'setformat', 'repr', 'dir'
+-])
+-
+-
+-def _get_method(name, func):
+-    "Turns a callable object (like a mock) into a real function"
+-    def method(self, *args, **kw):
+-        return func(self, *args, **kw)
+-    method.__name__ = name
+-    return method
+-
+-
+-_magics = set(
+-    '__%s__' % method for method in
+-    ' '.join([magic_methods, numerics, inplace, right, extra]).split()
+-)
+-
+-_all_magics = _magics | _non_defaults
+-
+-_unsupported_magics = set([
+-    '__getattr__', '__setattr__',
+-    '__init__', '__new__', '__prepare__'
+-    '__instancecheck__', '__subclasscheck__',
+-    '__del__'
+-])
+-
+-_calculate_return_value = {
+-    '__hash__': lambda self: object.__hash__(self),
+-    '__str__': lambda self: object.__str__(self),
+-    '__sizeof__': lambda self: object.__sizeof__(self),
+-    '__unicode__': lambda self: unicode(object.__str__(self)),
+-}
+-
+-_return_values = {
+-    '__lt__': NotImplemented,
+-    '__gt__': NotImplemented,
+-    '__le__': NotImplemented,
+-    '__ge__': NotImplemented,
+-    '__int__': 1,
+-    '__contains__': False,
+-    '__len__': 0,
+-    '__exit__': False,
+-    '__complex__': 1j,
+-    '__float__': 1.0,
+-    '__bool__': True,
+-    '__nonzero__': True,
+-    '__oct__': '1',
+-    '__hex__': '0x1',
+-    '__long__': long(1),
+-    '__index__': 1,
+-}
+-
+-
+-def _get_eq(self):
+-    def __eq__(other):
+-        ret_val = self.__eq__._mock_return_value
+-        if ret_val is not DEFAULT:
+-            return ret_val
+-        return self is other
+-    return __eq__
+-
+-def _get_ne(self):
+-    def __ne__(other):
+-        if self.__ne__._mock_return_value is not DEFAULT:
+-            return DEFAULT
+-        return self is not other
+-    return __ne__
+-
+-def _get_iter(self):
+-    def __iter__():
+-        ret_val = self.__iter__._mock_return_value
+-        if ret_val is DEFAULT:
+-            return iter([])
+-        # if ret_val was already an iterator, then calling iter on it should
+-        # return the iterator unchanged
+-        return iter(ret_val)
+-    return __iter__
+-
+-_side_effect_methods = {
+-    '__eq__': _get_eq,
+-    '__ne__': _get_ne,
+-    '__iter__': _get_iter,
+-}
+-
+-
+-
+-def _set_return_value(mock, method, name):
+-    fixed = _return_values.get(name, DEFAULT)
+-    if fixed is not DEFAULT:
+-        method.return_value = fixed
+-        return
+-
+-    return_calulator = _calculate_return_value.get(name)
+-    if return_calulator is not None:
+-        try:
+-            return_value = return_calulator(mock)
+-        except AttributeError:
+-            # XXXX why do we return AttributeError here?
+-            #      set it as a side_effect instead?
+-            return_value = AttributeError(name)
+-        method.return_value = return_value
+-        return
+-
+-    side_effector = _side_effect_methods.get(name)
+-    if side_effector is not None:
+-        method.side_effect = side_effector(mock)
+-
+-
+-
+-class MagicMixin(object):
+-    def __init__(self, *args, **kw):
+-        _super(MagicMixin, self).__init__(*args, **kw)
+-        self._mock_set_magics()
+-
+-
+-    def _mock_set_magics(self):
+-        these_magics = _magics
+-
+-        if self._mock_methods is not None:
+-            these_magics = _magics.intersection(self._mock_methods)
+-
+-            remove_magics = set()
+-            remove_magics = _magics - these_magics
+-
+-            for entry in remove_magics:
+-                if entry in type(self).__dict__:
+-                    # remove unneeded magic methods
+-                    delattr(self, entry)
+-
+-        # don't overwrite existing attributes if called a second time
+-        these_magics = these_magics - set(type(self).__dict__)
+-
+-        _type = type(self)
+-        for entry in these_magics:
+-            setattr(_type, entry, MagicProxy(entry, self))
+-
+-
+-
+-class NonCallableMagicMock(MagicMixin, NonCallableMock):
+-    """A version of `MagicMock` that isn't callable."""
+-    def mock_add_spec(self, spec, spec_set=False):
+-        """Add a spec to a mock. `spec` can either be an object or a
+-        list of strings. Only attributes on the `spec` can be fetched as
+-        attributes from the mock.
+-
+-        If `spec_set` is True then only attributes on the spec can be set."""
+-        self._mock_add_spec(spec, spec_set)
+-        self._mock_set_magics()
+-
+-
+-
+-class MagicMock(MagicMixin, Mock):
+-    """
+-    MagicMock is a subclass of Mock with default implementations
+-    of most of the magic methods. You can use MagicMock without having to
+-    configure the magic methods yourself.
+-
+-    If you use the `spec` or `spec_set` arguments then *only* magic
+-    methods that exist in the spec will be created.
+-
+-    Attributes and the return value of a `MagicMock` will also be `MagicMocks`.
+-    """
+-    def mock_add_spec(self, spec, spec_set=False):
+-        """Add a spec to a mock. `spec` can either be an object or a
+-        list of strings. Only attributes on the `spec` can be fetched as
+-        attributes from the mock.
+-
+-        If `spec_set` is True then only attributes on the spec can be set."""
+-        self._mock_add_spec(spec, spec_set)
+-        self._mock_set_magics()
+-
+-
+-
+-class MagicProxy(object):
+-    def __init__(self, name, parent):
+-        self.name = name
+-        self.parent = parent
+-
+-    def __call__(self, *args, **kwargs):
+-        m = self.create_mock()
+-        return m(*args, **kwargs)
+-
+-    def create_mock(self):
+-        entry = self.name
+-        parent = self.parent
+-        m = parent._get_child_mock(name=entry, _new_name=entry,
+-                                   _new_parent=parent)
+-        setattr(parent, entry, m)
+-        _set_return_value(parent, m, entry)
+-        return m
+-
+-    def __get__(self, obj, _type=None):
+-        return self.create_mock()
+-
+-
+-
+-class _ANY(object):
+-    "A helper object that compares equal to everything."
+-
+-    def __eq__(self, other):
+-        return True
+-
+-    def __ne__(self, other):
+-        return False
+-
+-    def __repr__(self):
+-        return '<ANY>'
+-
+-ANY = _ANY()
+-
+-
+-
+-def _format_call_signature(name, args, kwargs):
+-    message = '%s(%%s)' % name
+-    formatted_args = ''
+-    args_string = ', '.join([repr(arg) for arg in args])
+-    kwargs_string = ', '.join([
+-        '%s=%r' % (key, value) for key, value in kwargs.items()
+-    ])
+-    if args_string:
+-        formatted_args = args_string
+-    if kwargs_string:
+-        if formatted_args:
+-            formatted_args += ', '
+-        formatted_args += kwargs_string
+-
+-    return message % formatted_args
+-
+-
+-
+-class _Call(tuple):
+-    """
+-    A tuple for holding the results of a call to a mock, either in the form
+-    `(args, kwargs)` or `(name, args, kwargs)`.
+-
+-    If args or kwargs are empty then a call tuple will compare equal to
+-    a tuple without those values. This makes comparisons less verbose::
+-
+-        _Call(('name', (), {})) == ('name',)
+-        _Call(('name', (1,), {})) == ('name', (1,))
+-        _Call(((), {'a': 'b'})) == ({'a': 'b'},)
+-
+-    The `_Call` object provides a useful shortcut for comparing with call::
+-
+-        _Call(((1, 2), {'a': 3})) == call(1, 2, a=3)
+-        _Call(('foo', (1, 2), {'a': 3})) == call.foo(1, 2, a=3)
+-
+-    If the _Call has no name then it will match any name.
+-    """
+-    def __new__(cls, value=(), name=None, parent=None, two=False,
+-                from_kall=True):
+-        name = ''
+-        args = ()
+-        kwargs = {}
+-        _len = len(value)
+-        if _len == 3:
+-            name, args, kwargs = value
+-        elif _len == 2:
+-            first, second = value
+-            if isinstance(first, basestring):
+-                name = first
+-                if isinstance(second, tuple):
+-                    args = second
+-                else:
+-                    kwargs = second
+-            else:
+-                args, kwargs = first, second
+-        elif _len == 1:
+-            value, = value
+-            if isinstance(value, basestring):
+-                name = value
+-            elif isinstance(value, tuple):
+-                args = value
+-            else:
+-                kwargs = value
+-
+-        if two:
+-            return tuple.__new__(cls, (args, kwargs))
+-
+-        return tuple.__new__(cls, (name, args, kwargs))
+-
+-
+-    def __init__(self, value=(), name=None, parent=None, two=False,
+-                 from_kall=True):
+-        self.name = name
+-        self.parent = parent
+-        self.from_kall = from_kall
+-
+-
+-    def __eq__(self, other):
+-        if other is ANY:
+-            return True
+-        try:
+-            len_other = len(other)
+-        except TypeError:
+-            return False
+-
+-        self_name = ''
+-        if len(self) == 2:
+-            self_args, self_kwargs = self
+-        else:
+-            self_name, self_args, self_kwargs = self
+-
+-        other_name = ''
+-        if len_other == 0:
+-            other_args, other_kwargs = (), {}
+-        elif len_other == 3:
+-            other_name, other_args, other_kwargs = other
+-        elif len_other == 1:
+-            value, = other
+-            if isinstance(value, tuple):
+-                other_args = value
+-                other_kwargs = {}
+-            elif isinstance(value, basestring):
+-                other_name = value
+-                other_args, other_kwargs = (), {}
+-            else:
+-                other_args = ()
+-                other_kwargs = value
+-        else:
+-            # len 2
+-            # could be (name, args) or (name, kwargs) or (args, kwargs)
+-            first, second = other
+-            if isinstance(first, basestring):
+-                other_name = first
+-                if isinstance(second, tuple):
+-                    other_args, other_kwargs = second, {}
+-                else:
+-                    other_args, other_kwargs = (), second
+-            else:
+-                other_args, other_kwargs = first, second
+-
+-        if self_name and other_name != self_name:
+-            return False
+-
+-        # this order is important for ANY to work!
+-        return (other_args, other_kwargs) == (self_args, self_kwargs)
+-
+-
+-    def __ne__(self, other):
+-        return not self.__eq__(other)
+-
+-
+-    def __call__(self, *args, **kwargs):
+-        if self.name is None:
+-            return _Call(('', args, kwargs), name='()')
+-
+-        name = self.name + '()'
+-        return _Call((self.name, args, kwargs), name=name, parent=self)
+-
+-
+-    def __getattr__(self, attr):
+-        if self.name is None:
+-            return _Call(name=attr, from_kall=False)
+-        name = '%s.%s' % (self.name, attr)
+-        return _Call(name=name, parent=self, from_kall=False)
+-
+-
+-    def __repr__(self):
+-        if not self.from_kall:
+-            name = self.name or 'call'
+-            if name.startswith('()'):
+-                name = 'call%s' % name
+-            return name
+-
+-        if len(self) == 2:
+-            name = 'call'
+-            args, kwargs = self
+-        else:
+-            name, args, kwargs = self
+-            if not name:
+-                name = 'call'
+-            elif not name.startswith('()'):
+-                name = 'call.%s' % name
+-            else:
+-                name = 'call%s' % name
+-        return _format_call_signature(name, args, kwargs)
+-
+-
+-    def call_list(self):
+-        """For a call object that represents multiple calls, `call_list`
+-        returns a list of all the intermediate calls as well as the
+-        final call."""
+-        vals = []
+-        thing = self
+-        while thing is not None:
+-            if thing.from_kall:
+-                vals.append(thing)
+-            thing = thing.parent
+-        return _CallList(reversed(vals))
+-
+-
+-call = _Call(from_kall=False)
+-
+-
+-
+-def create_autospec(spec, spec_set=False, instance=False, _parent=None,
+-                    _name=None, **kwargs):
+-    """Create a mock object using another object as a spec. Attributes on the
+-    mock will use the corresponding attribute on the `spec` object as their
+-    spec.
+-
+-    Functions or methods being mocked will have their arguments checked
+-    to check that they are called with the correct signature.
+-
+-    If `spec_set` is True then attempting to set attributes that don't exist
+-    on the spec object will raise an `AttributeError`.
+-
+-    If a class is used as a spec then the return value of the mock (the
+-    instance of the class) will have the same spec. You can use a class as the
+-    spec for an instance object by passing `instance=True`. The returned mock
+-    will only be callable if instances of the mock are callable.
+-
+-    `create_autospec` also takes arbitrary keyword arguments that are passed to
+-    the constructor of the created mock."""
+-    if _is_list(spec):
+-        # can't pass a list instance to the mock constructor as it will be
+-        # interpreted as a list of strings
+-        spec = type(spec)
+-
+-    is_type = isinstance(spec, ClassTypes)
+-
+-    _kwargs = {'spec': spec}
+-    if spec_set:
+-        _kwargs = {'spec_set': spec}
+-    elif spec is None:
+-        # None we mock with a normal mock without a spec
+-        _kwargs = {}
+-
+-    _kwargs.update(kwargs)
+-
+-    Klass = MagicMock
+-    if type(spec) in DescriptorTypes:
+-        # descriptors don't have a spec
+-        # because we don't know what type they return
+-        _kwargs = {}
+-    elif not _callable(spec):
+-        Klass = NonCallableMagicMock
+-    elif is_type and instance and not _instance_callable(spec):
+-        Klass = NonCallableMagicMock
+-
+-    _new_name = _name
+-    if _parent is None:
+-        # for a top level object no _new_name should be set
+-        _new_name = ''
+-
+-    mock = Klass(parent=_parent, _new_parent=_parent, _new_name=_new_name,
+-                 name=_name, **_kwargs)
+-
+-    if isinstance(spec, FunctionTypes):
+-        # should only happen at the top level because we don't
+-        # recurse for functions
+-        mock = _set_signature(mock, spec)
+-    else:
+-        _check_signature(spec, mock, is_type, instance)
+-
+-    if _parent is not None and not instance:
+-        _parent._mock_children[_name] = mock
+-
+-    if is_type and not instance and 'return_value' not in kwargs:
+-        mock.return_value = create_autospec(spec, spec_set, instance=True,
+-                                            _name='()', _parent=mock)
+-
+-    for entry in dir(spec):
+-        if _is_magic(entry):
+-            # MagicMock already does the useful magic methods for us
+-            continue
+-
+-        if isinstance(spec, FunctionTypes) and entry in FunctionAttributes:
+-            # allow a mock to actually be a function
+-            continue
+-
+-        # XXXX do we need a better way of getting attributes without
+-        # triggering code execution (?) Probably not - we need the actual
+-        # object to mock it so we would rather trigger a property than mock
+-        # the property descriptor. Likewise we want to mock out dynamically
+-        # provided attributes.
+-        # XXXX what about attributes that raise exceptions other than
+-        # AttributeError on being fetched?
+-        # we could be resilient against it, or catch and propagate the
+-        # exception when the attribute is fetched from the mock
+-        try:
+-            original = getattr(spec, entry)
+-        except AttributeError:
+-            continue
+-
+-        kwargs = {'spec': original}
+-        if spec_set:
+-            kwargs = {'spec_set': original}
+-
+-        if not isinstance(original, FunctionTypes):
+-            new = _SpecState(original, spec_set, mock, entry, instance)
+-            mock._mock_children[entry] = new
+-        else:
+-            parent = mock
+-            if isinstance(spec, FunctionTypes):
+-                parent = mock.mock
+-
+-            new = MagicMock(parent=parent, name=entry, _new_name=entry,
+-                            _new_parent=parent, **kwargs)
+-            mock._mock_children[entry] = new
+-            skipfirst = _must_skip(spec, entry, is_type)
+-            _check_signature(original, new, skipfirst=skipfirst)
+-
+-        # so functions created with _set_signature become instance attributes,
+-        # *plus* their underlying mock exists in _mock_children of the parent
+-        # mock. Adding to _mock_children may be unnecessary where we are also
+-        # setting as an instance attribute?
+-        if isinstance(new, FunctionTypes):
+-            setattr(mock, entry, new)
+-
+-    return mock
+-
+-
+-def _must_skip(spec, entry, is_type):
+-    if not isinstance(spec, ClassTypes):
+-        if entry in getattr(spec, '__dict__', {}):
+-            # instance attribute - shouldn't skip
+-            return False
+-        spec = spec.__class__
+-    if not hasattr(spec, '__mro__'):
+-        # old style class: can't have descriptors anyway
+-        return is_type
+-
+-    for klass in spec.__mro__:
+-        result = klass.__dict__.get(entry, DEFAULT)
+-        if result is DEFAULT:
+-            continue
+-        if isinstance(result, (staticmethod, classmethod)):
+-            return False
+-        return is_type
+-
+-    # shouldn't get here unless function is a dynamically provided attribute
+-    # XXXX untested behaviour
+-    return is_type
+-
+-
+-def _get_class(obj):
+-    try:
+-        return obj.__class__
+-    except AttributeError:
+-        # in Python 2, _sre.SRE_Pattern objects have no __class__
+-        return type(obj)
+-
+-
+-class _SpecState(object):
+-
+-    def __init__(self, spec, spec_set=False, parent=None,
+-                 name=None, ids=None, instance=False):
+-        self.spec = spec
+-        self.ids = ids
+-        self.spec_set = spec_set
+-        self.parent = parent
+-        self.instance = instance
+-        self.name = name
+-
+-
+-FunctionTypes = (
+-    # python function
+-    type(create_autospec),
+-    # instance method
+-    type(ANY.__eq__),
+-    # unbound method
+-    type(_ANY.__eq__),
+-)
+-
+-FunctionAttributes = set([
+-    'func_closure',
+-    'func_code',
+-    'func_defaults',
+-    'func_dict',
+-    'func_doc',
+-    'func_globals',
+-    'func_name',
+-])
+-
+-
+-file_spec = None
+-
+-
+-def mock_open(mock=None, read_data=''):
+-    """
+-    A helper function to create a mock to replace the use of `open`. It works
+-    for `open` called directly or used as a context manager.
+-
+-    The `mock` argument is the mock object to configure. If `None` (the
+-    default) then a `MagicMock` will be created for you, with the API limited
+-    to methods or attributes available on standard file handles.
+-
+-    `read_data` is a string for the `read` method of the file handle to return.
+-    This is an empty string by default.
+-    """
+-    global file_spec
+-    if file_spec is None:
+-        # set on first use
+-        if inPy3k:
+-            import _io
+-            file_spec = list(set(dir(_io.TextIOWrapper)).union(set(dir(_io.BytesIO))))
+-        else:
+-            file_spec = file
+-
+-    if mock is None:
+-        mock = MagicMock(name='open', spec=open)
+-
+-    handle = MagicMock(spec=file_spec)
+-    handle.write.return_value = None
+-    handle.__enter__.return_value = handle
+-    handle.read.return_value = read_data
+-
+-    mock.return_value = handle
+-    return mock
+-
+-
+-class PropertyMock(Mock):
+-    """
+-    A mock intended to be used as a property, or other descriptor, on a class.
+-    `PropertyMock` provides `__get__` and `__set__` methods so you can specify
+-    a return value when it is fetched.
+-
+-    Fetching a `PropertyMock` instance from an object calls the mock, with
+-    no args. Setting it calls the mock with the value being set.
+-    """
+-    def _get_child_mock(self, **kwargs):
+-        return MagicMock(**kwargs)
+-
+-    def __get__(self, obj, obj_type):
+-        return self()
+-    def __set__(self, obj, val):
+-        self(val)
++# This file is part of Checkbox.
++#
++# Copyright 2013 Canonical Ltd.
++# Written by:
++#   Zygmunt Krynicki <[e-mail]>
++#
++# Checkbox is free software: you can redistribute it and/or modify
++# it under the terms of the GNU General Public License as published by
++# the Free Software Foundation, either version 3 of the License, or
++# (at your option) any later version.
++#
++# Checkbox is distributed in the hope that it will be useful,
++# but WITHOUT ANY WARRANTY; without even the implied warranty of
++# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
++# GNU General Public License for more details.
++#
++# You should have received a copy of the GNU General Public License
++# along with Checkbox.  If not, see <http://www.gnu.org/licenses/>.
++
++"""
++:mod:`plainbox.vendor.mock` -- vendorized mock module
++=====================================================
++
++This file has been patched-away by the Debian package as compared to the
++upstream version, not to ship a copy of a the 'mock' module that is now
++integrated into the upstream python3.3 release.
++"""
++
++from unittest.mock import *
diff --git a/debian/plainbox.manpages b/debian/plainbox.manpages
new file mode 100644
index 0000000..5c9ed39
--- /dev/null
+++ b/debian/plainbox.manpages
@@ -0,0 +1,32 @@
+build/sphinx/man/CHECKBOX_DATA.7
+build/sphinx/man/CHECKBOX_SHARE.7
+build/sphinx/man/PLAINBOX_PROVIDER_DATA.7
+build/sphinx/man/PLAINBOX_SESSION_SHARE.7
+build/sphinx/man/manage.py.1
+build/sphinx/man/plainbox-category-units.7
+build/sphinx/man/plainbox-check-config.1
+build/sphinx/man/plainbox-dev-analyze.1
+build/sphinx/man/plainbox-dev-crash.1
+build/sphinx/man/plainbox-dev-list.1
+build/sphinx/man/plainbox-dev-logtest.1
+build/sphinx/man/plainbox-dev-parse.1
+build/sphinx/man/plainbox-dev-script.1
+build/sphinx/man/plainbox-dev-special.1
+build/sphinx/man/plainbox-dev.1
+build/sphinx/man/plainbox-device.1
+build/sphinx/man/plainbox-file-units.7
+build/sphinx/man/plainbox-job-units.7
+build/sphinx/man/plainbox-run.1
+build/sphinx/man/plainbox-self-test.1
+build/sphinx/man/plainbox-session-archive.1
+build/sphinx/man/plainbox-session-export.1
+build/sphinx/man/plainbox-session-list.1
+build/sphinx/man/plainbox-session-remove.1
+build/sphinx/man/plainbox-session-show.1
+build/sphinx/man/plainbox-session-structure.7
+build/sphinx/man/plainbox-session.1
+build/sphinx/man/plainbox-startprovider.1
+build/sphinx/man/plainbox-template-units.7
+build/sphinx/man/plainbox-test-plan-units.7
+build/sphinx/man/plainbox.1
+build/sphinx/man/plainbox.conf.5
diff --git a/debian/python3-plainbox-doc.doc-base b/debian/python3-plainbox-doc.doc-base
new file mode 100644
index 0000000..2be3de8
--- /dev/null
+++ b/debian/python3-plainbox-doc.doc-base
@@ -0,0 +1,9 @@
+Document: plainbox
+Title: Plainbox Manual
+Author: Canonical Ltd.
+Abstract: This manual describes what Plainbox is, and how it can be used.
+Section: Programming/Python
+
+Format: HTML
+Index: /usr/share/doc/python3-plainbox-doc/html/index.html
+Files: /usr/share/doc/python3-plainbox-doc/html/*.html
\ No newline at end of file
diff --git a/debian/python3-plainbox-doc.docs b/debian/python3-plainbox-doc.docs
new file mode 100644
index 0000000..6f7511e
--- /dev/null
+++ b/debian/python3-plainbox-doc.docs
@@ -0,0 +1 @@
+build/sphinx/html
diff --git a/debian/python3-plainbox.install b/debian/python3-plainbox.install
new file mode 100644
index 0000000..a829b2d
--- /dev/null
+++ b/debian/python3-plainbox.install
@@ -0,0 +1,2 @@
+build/mo/* usr/share/locale
+plainbox/impl/providers/stubbox/build/mo/* usr/share/locale
diff --git a/debian/python3-plainbox.links b/debian/python3-plainbox.links
new file mode 100644
index 0000000..9297a04
--- /dev/null
+++ b/debian/python3-plainbox.links
@@ -0,0 +1,2 @@
+usr/share/python3-plainbox/data /usr/lib/python3/dist-packages/plainbox/data
+usr/share/python3-plainbox/test-data /usr/lib/python3/dist-packages/plainbox/test-data
diff --git a/debian/python3-plainbox.manpages b/debian/python3-plainbox.manpages
new file mode 100644
index 0000000..a7372fb
--- /dev/null
+++ b/debian/python3-plainbox.manpages
@@ -0,0 +1,2 @@
+build/sphinx/man/plainbox-trusted-launcher-1.1
+build/sphinx/man/plainbox-qml-shell.1
diff --git a/debian/python3-plainbox.preinst b/debian/python3-plainbox.preinst
new file mode 100644
index 0000000..8e73be6
--- /dev/null
+++ b/debian/python3-plainbox.preinst
@@ -0,0 +1,44 @@
+#! /bin/sh
+# Pre-install script for ‘python3-plainbox’.
+#
+# Manpage: ‘dh_installdeb(1)’
+
+set -e
+
+# Summary of ways this script can be called:
+#   * <new-preinst> install
+#   * <new-preinst> install <old-version>
+#   * <new-preinst> upgrade <old-version>
+#   * <old-preinst> abort-upgrade <new-version>
+# For details, see the Debian Policy §6.5 in the ‘debian-policy’ package
+# or on the web at <URL:http://www.debian.org/doc/debian-policy/>.
+
+action="$1"
+
+case "$action" in
+    upgrade)
+        data_dir="/usr/lib/python3/dist-packages/plainbox/data"
+        if [ -d "$data_dir" ] && [ ! -L "$data_dir" ] ; then
+            # The ‘data’ location should be platform-independent.
+            # The new package will replace the directory with a symlink.
+            rm -rf "$data_dir"
+        fi
+        testdata_dir="/usr/lib/python3/dist-packages/plainbox/test-data"
+        if [ -d "$testdata_dir" ] && [ ! -L "$testdata_dir" ] ; then
+            # The ‘data’ location should be platform-independent.
+            # The new package will replace the directory with a symlink.
+            rm -rf "$testdata_dir"
+        fi
+        ;;
+
+    install|abort-upgrade)
+        ;;
+
+    *)
+        printf "preinst called with unknown action ‘%s’\n" "$action" >&2
+        exit 1
+        ;;
+
+esac
+
+#DEBHELPER#
diff --git a/debian/rules b/debian/rules
new file mode 100755
index 0000000..79ee81e
--- /dev/null
+++ b/debian/rules
@@ -0,0 +1,49 @@
+#!/usr/bin/make -f
+export PYBUILD_NAME=plainbox
+export LANG=
+export LANGUAGE=
+export NO_PNG_PKG_MANGLE=1
+
+%:
+	dh $@ --with=python3,sphinxdoc --buildsystem=pybuild
+
+override_dh_auto_build:
+	dh_auto_build --buildsystem=pybuild
+	# Build sphinx html documentation and man pages 
+	# Use TEMP_HOME to work around https://bugs.launchpad.net/plainbox/+bug/1478906
+	TEMP_HOME=`mktemp -d`; HOME=$$TEMP_HOME python3 setup.py build_sphinx -b html; rm -rf $$TEMP_HOME;
+	TEMP_HOME=`mktemp -d`; HOME=$$TEMP_HOME python3 setup.py build_sphinx -b man; rm -rf $$TEMP_HOME;
+	# Build plainbox translations
+	python3 setup.py build_i18n --merge-po
+	# Build translations for the bundled provider
+	PYTHONPATH=. ./plainbox/impl/providers/stubbox/manage.py i18n --dont-update-pot --dont-merge-po
+	PYTHONPATH=. ./plainbox/impl/providers/categories/manage.py i18n --dont-update-pot --dont-merge-po
+	PYTHONPATH=. ./plainbox/impl/providers/manifest/manage.py i18n --dont-update-pot --dont-merge-po
+	PYTHONPATH=. ./plainbox/impl/providers/exporters/manage.py i18n --dont-update-pot --dont-merge-po
+
+# Override dh_install to ensure that /usr/bin/plainbox is in the plainbox
+# package and not in the python3-plainbox package. Also move the data and
+# test-data directories to usr/share and provide symlinks (via
+# python3-plainbox.links) for everything to work.
+override_dh_install:
+	dh_install
+	mkdir -p debian/plainbox/usr/bin
+	mkdir -p debian/python3-plainbox/usr/share/python3-plainbox/
+	mv debian/python3-plainbox/usr/bin/plainbox debian/plainbox/usr/bin/
+	cp -R plainbox/data debian/python3-plainbox/usr/share/python3-plainbox/
+	cp -R plainbox/test-data debian/python3-plainbox/usr/share/python3-plainbox/
+	rm -rf $(foreach version,$(shell py3versions -s), debian/python3-plainbox/usr/lib/$(version)/dist-packages/plainbox/data)
+	rm -rf $(foreach version,$(shell py3versions -s), debian/python3-plainbox/usr/lib/$(version)/dist-packages/plainbox/test-data)
+	rm -f debian/python3-plainbox/usr/bin/stubbox
+
+# Override dh_clean to remove provider build artefacts
+override_dh_clean:
+	dh_clean
+	rm -rf plainbox/impl/providers/stubbox/build
+	rm -rf plainbox/impl/providers/categories/build
+
+# Drop the empty python-3.4 directory
+# Taken from https://wiki.debian.org/Python/LibraryStyleGuide
+override_dh_python3:
+	dh_python3
+	rm -rf debian/python3-plainbox/usr/lib/python3.?
diff --git a/debian/source/format b/debian/source/format
new file mode 100644
index 0000000..163aaf8
--- /dev/null
+++ b/debian/source/format
@@ -0,0 +1 @@
+3.0 (quilt)
diff --git a/debian/source/options b/debian/source/options
new file mode 100644
index 0000000..cccadcc
--- /dev/null
+++ b/debian/source/options
@@ -0,0 +1 @@
+extend-diff-ignore = ".*\.po$"
diff --git a/debian/tests/control b/debian/tests/control
new file mode 100644
index 0000000..1079546
--- /dev/null
+++ b/debian/tests/control
@@ -0,0 +1,2 @@
+Tests: unit-tests
+Depends: plainbox
diff --git a/debian/tests/unit-tests b/debian/tests/unit-tests
new file mode 100755
index 0000000..615deb5
--- /dev/null
+++ b/debian/tests/unit-tests
@@ -0,0 +1,10 @@
+#!/bin/sh
+# autopkgtest check: run plainbox unit tests and ensure everything passes
+# (C) 2013 Canonical Ltd.
+# Author: Zygmunt Krynicki <[e-mail]> 
+
+set -e
+
+cd $ADTTMP
+plainbox self-test -u -v 2>&1
+echo "unit-tests: OK"
diff --git a/debian/watch b/debian/watch
new file mode 100644
index 0000000..bd41b5e
--- /dev/null
+++ b/debian/watch
@@ -0,0 +1,3 @@
+version=3
+opts=uversionmangle=s/(rc|a|b|c)/~$1/ \
+http://pypi.debian.net/plainbox/plainbox-(.+)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz)))
diff --git a/docs/author/index.rst b/docs/author/index.rst
index b22bb46..6106b08 100644
--- a/docs/author/index.rst
+++ b/docs/author/index.rst
@@ -8,8 +8,15 @@ core.
 
 .. toctree::
    intro.rst
+<<<<<<< docs/author/index.rst
    qml-job-tutorial.rst
    providers.rst
+=======
+   tutorial.rst
+   qml-job-tutorial.rst
+   providers.rst
+   whitelists.rst
+>>>>>>> docs/author/index.rst
    rfc822.rst
    faq.rst
 
diff --git a/docs/author/intro.rst b/docs/author/intro.rst
index 2dae15d..93e9365 100644
--- a/docs/author/intro.rst
+++ b/docs/author/intro.rst
@@ -49,7 +49,11 @@ Terminology
 In developing or using Plainbox, you'll run into several unfamiliar terms.
 Check the :doc:`../glossary` to learn what they mean. In fact, you should
 probably check it now. Pay particular attention to the terms *Checkbox*,
+<<<<<<< docs/author/intro.rst
 *Plainbox*, *job* and *provider*.
+=======
+*Plainbox*, *job*, *provider*, and *whitelist*.
+>>>>>>> docs/author/intro.rst
 
 Getting Started
 ---------------
@@ -73,7 +77,11 @@ tests. First up is a welcome screen:
        select tests.
 
 When you press the Enter key, ``checkbox-cli`` lets you select which
+<<<<<<< docs/author/intro.rst
 test plan to use:
+=======
+whitelist to use:
+>>>>>>> docs/author/intro.rst
 
 .. image:: cc2.png
  :height: 343
@@ -81,7 +89,11 @@ test plan to use:
  :scale: 100
  :alt: checkbox-cli enables you to select which test suite to run.
 
+<<<<<<< docs/author/intro.rst
 With a test plan selected, you can choose the individual tests to run:
+=======
+With a whitelist selected, you can choose the individual tests to run:
+>>>>>>> docs/author/intro.rst
 
 .. image:: cc3.png
  :height: 600
@@ -117,7 +129,11 @@ A provider is described in a configuration file (stored in
 ``/usr/share/plainbox-providers-1``). This file describes where to find all
 the files from the provider. This file is usually managed automatically
 (more on this later). A provider can ship jobs, binaries, data and
+<<<<<<< docs/author/intro.rst
 test plans.
+=======
+whitelists.
+>>>>>>> docs/author/intro.rst
 
 A **job** or **test** is the smallest unit or description that Plainbox
 knows about. It describes a single test (historically they're called
@@ -140,6 +156,13 @@ types include (but are not limited to):
  * ``shell`` -- An automated test that requires no user interaction; the
    test is passed or failed on the basis of the return value of the script
    or command.
+<<<<<<< docs/author/intro.rst
+=======
+ * ``local`` -- This type of job is similar to a ``shell`` test, but it
+   supports creating multiple tests from a single definition (say, to test
+   all the Ethernet ports on a computer). Jobs using the ``local`` plugin
+   are run when Plainbox is initialized.
+>>>>>>> docs/author/intro.rst
  * ``user-interact`` -- A test that asks the user to perform some action
    *before* the test is performed. The test then passes or fails
    automatically based on the output of the test. An example is
@@ -158,9 +181,176 @@ types include (but are not limited to):
    which probes the system to determine the maximum supported resolution
    and then asks the user to confirm that the resolution is correct.
 
+<<<<<<< docs/author/intro.rst
 Each provider has a ``bin`` directory and all binaries there are available
 in the path.
 
+=======
+A fairly complex example definition is::
+
+ plugin: local
+ _summary: Automated test to walk multiple network cards and test each one in sequence.
+ id: ethernet/multi_nic
+ requires:
+  device.category == 'NETWORK'
+ _description: Automated test to walk multiple network cards and test each one in sequence.
+ command:
+  cat <<'EOF' | run_templates -s 'udev_resource | filter_templates -w "category=NETWORK" | awk "/path: / { print \$2 }" | xargs -n 1 sh -c "for i in \``ls /sys\$0/net 2>/dev/null\``; do echo \$0 \$i; done"'
+  plugin: shell
+  id: ethernet/multi_nic_$2
+  requires:
+   package.name == 'ethtool'
+   package.name == 'nmap'
+   device.path == "$1"
+  user: root
+  environ: TEST_TARGET_FTP TEST_TARGET_IPERF TEST_USER TEST_PASS
+  command: network test -i $2 -t iperf --fail-threshold 80
+  estimated_duration: 330.0
+  description:
+   Testing for NIC $2
+  EOF
+
+Key points to note include:
+
+ * If a field name begins with an underscore, its value can be localized.
+ * The values of fields can appear on the same line as their field names,
+   as in ``plugin: local``; or they can appear on a subsequent line, which
+   is indented, as in the preceding example's ``requires: device.category
+   == 'NETWORK'``.
+ * The ``requires`` field can be used to specify dependencies; if the
+   specified condition is not met, the test does not run.
+ * The ``command`` field specifies the command that's used to run the test.
+   This can be a standard Linux command (or even a set of commands) or a
+   Checkbox test script. In this example's ``local`` test definition, the
+   first ``command`` line generates a list of network devices that is fed
+   to an embedded test, which is defined beginning with the second
+   ``plugin`` line immediately following the first ``command`` line.
+ * In this example, the line that reads ``EOF`` ends the
+   ``ethernet/ethtool_multi_nic_$2`` test's command; it's matched to the
+   ``EOF`` that's part of ``cat << 'EOF'`` near the start of that command.
+
+Each provider has a ``bin`` directory and all binaries there are available
+in the path.
+
+Whitelists
+``````````
+
+In the job files we have a "universe" of known jobs. We don't normally want
+to run them all; rather we want to select a subset depending on what we're
+testing, and maybe give the user a way to fine-tune that selection. Also,
+we need a way to determine the order in which they will run, beyond what
+dependencies may provide. This is where the whitelist comes in; think of it
+as a mask or selection filter from the universe of jobs. Whitelists support
+regular expressions, and Plainbox will attempt to run tests in the order
+shown in the whitelist. Again, providers ship whitelists in a specific
+directory, and you can use ``plainbox`` to run a specific whitelist with
+the ``-w`` option.
+
+You can also use ``plainbox`` to run a test with the ``-i`` syntax. This is
+good for quickly running a job and ensuring it works well.
+
+Let's look at ``checkbox-cli`` for a moment. This is a "launcher"; it
+specifies a set of configuration options for a specific testing purpose.
+This enables us to create mini-clients for each testing purpose, without
+changing the core utility (``checkbox-launcher``). For instance, let's look
+at the launcher for ``canonical-certification-server``, which appears in
+``./providers/plainbox-provider-certification-server/launcher/canonical-certification-server``
+in the Checkbox source tree::
+
+ #!/usr/bin/env checkbox-launcher
+ [welcome]
+ text = Welcome to System Certification!
+     This application will gather information from your system. Then you will be
+     asked manual tests to confirm that the system is working properly. Finally,
+     you will be asked for the Secure ID of the computer to submit the
+     information to the certification.canonical.com database.
+     To learn how to create or locate the Secure ID, please see here:
+     https://certification.canonical.com/
+
+ [suite]
+ # Whitelist(s) displayed in the suite selection screen
+ whitelist_filter = ^((network|storage|usb|virtualization)-only)|(server-(full|functional)-14.04)$
+ # Whitelist(s) pre-selected in the suite selection screen, default whitelist(s)
+ whitelist_selection = ^server-full-14.04$
+
+ [transport]
+ submit_to = certification
+
+ [config]
+ config_filename = canonical-certification.conf
+
+A launcher such as this sets up an environment that includes introductory
+text to be shown to users, a filter to determine what whitelists to present
+as options, information on where to (optionally) submit results, and a
+configuration filename. This allows each provider to ship a launcher or
+binary with which to launch its relevant tests.
+
+Developing Tests
+````````````````
+
+One way to deliver tests via Plainbox is to start your own provider. To
+learn how to do that, see the :ref:`tutorial`.
+
+In other cases you want to add tests to the main Checkbox repository (which
+is also what we recommend to keep tests centralized, unless they're so
+purpose-specific that this makes no sense).
+
+This is a bit easier because the provider in question already exists. So
+let's get started by branching a copy of ``lp:checkbox``. In brief, you
+should change to your software development directory and type ``bzr branch
+lp:checkbox my-branch`` to create a copy of the ``checkbox`` Launchpad
+project in the ``my-branch`` subdirectory. You can then edit the files in
+that subdirectory, upload the results to your own Launchpad account, and
+request a merge.
+
+To begin, consider the files and subdirectories in the main Checkbox
+development directory (``my-branch`` if you used the preceding ``bzr``
+command without change):
+
+ * ``checkbox-gui`` -- Checkbox GUI components, used in desktop/laptop
+   testing
+ * ``checkbox-ng`` -- The Plainbox-based version of Checkbox
+ * ``checkbox-support`` -- Support code for many providers
+ * ``checkbox-touch`` -- A Checkbox frontend optimized for touch/tablet
+   devices
+ * ``mk-venv`` -- A symbolic link to a script used to set up an environment
+   for testing Checkbox
+ * ``plainbox`` -- A Python3 library and development tools at the heart of
+   Plainbox
+ * ``plainbox-client`` -- Unfinished Python3 interface for Checkbox
+ * ``providers`` -- Provider definitions, including test scripts
+ * ``README.md`` -- A file describing the contents of the subdirectory in
+   greater detail
+ * ``setup.py`` -- A setup script
+ * ``support`` -- Support code that's not released
+ * ``tarmac-verify`` -- A support script
+ * ``test-in-lxc.sh`` -- A support script for testing in an LXC
+ * ``test-in-vagrant.sh`` -- A support script for testing with Vagrant
+ * ``test-with-coverage`` -- A link to a support script for testing with
+   coverage
+ * ``Vagrantfile`` -- A Vagrant configuration file
+
+Let's say I want to write a test to ensure that the ubuntu user exists in
+``/etc/passwd``. You need to remove any existing Checkbox provider
+packages, lest they interfere with your new or modified tests. The
+``setup.py`` script will set up a Plainbox development environment for you.
+
+We can write a simple job here, then add a requirement, perhaps a
+dependency, then a script in the directory. Note that scripts can be
+anything that's executable, we usually prefer either shell or Python but
+anything goes.
+
+Plainbox will supply two environment variables, ``PLAINBOX_PROVIDER_DATA``
+and ``SHARE``, we usually try to use them in the job description only, not
+in the scripts, to keep the scripts Plainbox-agnostic if possible.
+
+Once the test is running correctly, we can create a whitelist with a few
+tests and name it.
+
+Once we get everything running correctly we can prepare and propose a merge
+request using ``bzr`` as usual.
+
+>>>>>>> docs/author/intro.rst
 Other Questions
 ---------------
 
diff --git a/docs/author/provider-files.rst b/docs/author/provider-files.rst
index 34f21d4..d7ab8d1 100644
--- a/docs/author/provider-files.rst
+++ b/docs/author/provider-files.rst
@@ -53,6 +53,14 @@ jobs_dir
     Absolute pathname to a directory with :term:`job definitions <job>`
     as individual ``.txt`` files using the :doc:`job file format <jobs>`.
 
+<<<<<<< docs/author/provider-files.rst
+=======
+whitelists_dir
+    Absolute pathname to a directory with :term:`whitelists <whitelist>`
+    as individual ``.whitelist`` files using the
+    :doc:`whitelist format <whitelists>`.
+
+>>>>>>> docs/author/provider-files.rst
 bin_dir
     Absolute pathname to a directory with additional executables required by
     any of the job definitions.
@@ -75,6 +83,10 @@ location
         Variable          Default Value
     ================  =====================
     jobs_dir          $location/jobs
+<<<<<<< docs/author/provider-files.rst
+=======
+    whitelists_dir    $location/whitelists
+>>>>>>> docs/author/provider-files.rst
     bin_dir           $location/bin
     data_dir          $location/data
     locale_dir        $location/locale
diff --git a/docs/author/provider-namespaces.rst b/docs/author/provider-namespaces.rst
index e25036b..c5e73b7 100644
--- a/docs/author/provider-namespaces.rst
+++ b/docs/author/provider-namespaces.rst
@@ -120,7 +120,11 @@ The part of the provide name before the colon is used as the name-space. The
 colon is *not* a part of the name-space.
 
 The implicit name-space is used to construct non-partial job definition names
+<<<<<<< docs/author/provider-namespaces.rst
 as well as to implicitly prefix each pattern inside test plans. 
+=======
+as well as to implicitly prefix each pattern inside :term:`whitelists <whitelist>`. 
+>>>>>>> docs/author/provider-namespaces.rst
 
 Using Explicit Name-Spaces
 --------------------------
@@ -133,15 +137,25 @@ Explicit name-spaces need to be used in two situations:
    This is required as any partial ID may silently change the job it resolves
    to and we didn't want to introduce that ambiguity.
 
+<<<<<<< docs/author/provider-namespaces.rst
 2. When including a job from another name-space inside a test plan, e.g.::
 
         ~/com.example.some:provider$ cat units/test-plan.pxu
+=======
+2. When including a job from another name-space inside a whitelist, e.g.::
+
+        ~/com.example.some:provider$ cat whitelists/cross.whitelist
+>>>>>>> docs/author/provider-namespaces.rst
         job-a
         job-b
         com\.example\.other::job-a
         ~com.example.some:provider$
 
+<<<<<<< docs/author/provider-namespaces.rst
    Here the test plan names three jobs:
+=======
+   Here the whitelist names three jobs:
+>>>>>>> docs/author/provider-namespaces.rst
 
    * com.example.some::job-a
    * com.example.some::job-b
diff --git a/docs/author/provider-template.rst b/docs/author/provider-template.rst
index ae5bb76..302bf7d 100644
--- a/docs/author/provider-template.rst
+++ b/docs/author/provider-template.rst
@@ -23,14 +23,27 @@ The following files and directories are generated::
     ├── data
     │   ├── example.dat
     │   └── README.md
+<<<<<<< docs/author/provider-template.rst
+=======
+    ├── jobs
+    │   ├── examples-intermediate.txt
+    │   ├── examples-normal.txt
+    │   └── examples-trivial.txt
+>>>>>>> docs/author/provider-template.rst
     ├── manage.py
     ├── po
     │   └── POTFILES.in
     ├── README.md
+<<<<<<< docs/author/provider-template.rst
     └── units
         ├── examples-intermediate.txt
         ├── examples-normal.txt
         └── examples-trivial.txt
+=======
+    └── whitelists
+        ├── normal.whitelist
+        └── trivial.whitelist
+>>>>>>> docs/author/provider-template.rst
 
 Generated Content
 =================
@@ -56,8 +69,15 @@ README.md
     Plainbox parlance, is the smallest piece of executable test code. Each
     job has a name and a number of other attributes.
 
+<<<<<<< docs/author/provider-template.rst
     Jobs can be arranged in lists, test plans if you will. You can create as
     many test plans as you need, referring to arbitrary subsets of your jobs.
+=======
+    Jobs can be arranged in lists, test plans if you will that are known
+    as "whitelists". Those are defined in the ``whitelists/`` directory,
+    this time one per file. You can create as many whitelists as you need,
+    referring to arbitrary subsets of your jobs.
+>>>>>>> docs/author/provider-template.rst
 
     Then there are the ``bin/`` and ``data/`` directories. Those are
     entirely for custom content you may need. You can put arbitrary
@@ -335,7 +355,11 @@ jobs/examples-intermediate.txt
     estimated_duration: 30
 
 
+<<<<<<< docs/author/provider-template.rst
 po/POTFILES.in
+=======
+po/PORFILES.in
+>>>>>>> docs/author/provider-template.rst
 --------------
 
 ::
@@ -345,3 +369,23 @@ po/POTFILES.in
     [type: gettext/rfc822deb] jobs/examples-normal.txt
     [type: gettext/rfc822deb] jobs/examples-intermediate.txt
     manage.py
+<<<<<<< docs/author/provider-template.rst
+=======
+
+whitelists/trivial.whitelist
+----------------------------
+
+::
+
+    # select two trivial jobs by directly selecting their names
+    examples/trivial/always-pass
+    examples/trivial/always-fail
+
+whitelists/normal.whitelist
+---------------------------
+
+::
+
+    # use regular expression to select all normal jobs
+    examples/normal/.*
+>>>>>>> docs/author/provider-template.rst
diff --git a/docs/author/providers.rst b/docs/author/providers.rst
index cc1bb6c..40d4dc5 100644
--- a/docs/author/providers.rst
+++ b/docs/author/providers.rst
@@ -5,7 +5,11 @@ Providers
 Providers are a new feature introduced in Plainbox 0.5. They allow third party
 developers to produce and maintain private and public test collections.
 
+<<<<<<< docs/author/providers.rst
 All :term:`jobs <job>` and test plans are now loaded from a provider. This
+=======
+All :term:`jobs <job>` and :term:`whitelists <whitelist>` are now loaded from a provider. This
+>>>>>>> docs/author/providers.rst
 also affects the :term:`Checkbox` project that now produces a custom user
 interface and a number of providers for various purposes.
 
diff --git a/docs/author/tutorial.rst b/docs/author/tutorial.rst
new file mode 100644
index 0000000..892cb19
--- /dev/null
+++ b/docs/author/tutorial.rst
@@ -0,0 +1,177 @@
+.. _tutorial:
+
+========
+Tutorial
+========
+
+To best illustrate how providers work, we will walk through creating one
+step-by-step. At the end of this tutorial you will have a provider which adds
+a new :term:`whitelist`, several new jobs and the scripts and test data 
+supporting those jobs. Before starting this tutorial you will need to have a 
+running version of :term:`Plainbox` installed. You can either install it from 
+the  repositories of Debian or its derivatives by running ``apt-get install 
+plainbox``, or if you prefer to work with the source, see :doc:`Getting 
+started with development <../dev/intro>`. There is also a Launchpad PPA with
+the very latest development build for Ubuntu, which is `ppa:checkbox-dev/ppa`.
+
+#. To get started we create an initial template for our provider by running
+   ``plainbox startprovider com.example:myprovider``.
+
+#. This will create a directory called ``com.example:myprovider``.
+   Change to this directory and you will see that it contains::
+
+    /bin
+    /data
+    /integration-tests
+    /jobs
+    manage.py
+    README.md
+    /whitelists
+
+   The ``manage.py`` script is a helper script for developing the provider.
+   It provides a set of commands which assist in validating the correctness
+   of the provider and making it ready for distribution.
+
+#. Let’s create some jobs first by changing to the jobs directory. It currently
+   contains a file called category.txt which serves as an example of how
+   jobs should look. Let’s delete it and instead create a file called
+   ``myjobs.txt``. This can contain the following simple jobs::
+
+    plugin: shell
+    name: myjobs/shell_command
+    command: true
+    _description:
+     An example job that uses a command provided by the shell.
+
+    plugin: shell
+    name: myjobs/provider_command
+    command: mycommand
+    _description:
+      An example job that uses a test command provided by this provider.
+  
+   At this point we can check that everything looks okay by running the command
+   ``./manage.py info`` which displays some information about the provider. The
+   output should be something like::
+
+    [Provider MetaData]
+	name: com.example:myprovider
+	version: 1.0
+    [Job Definitions]
+	'myjobs/builtin_command', from jobs/myjobs.txt:1-5
+	'myjobs/provider_command', from jobs/myjobs.txt:7-11
+    [White Lists]    
+        'category', from whitelists/category.whitelist:1-1
+
+   This shows all three jobs from the job file we added - great!
+
+#. Next we need to change directory to ``bin`` to add the command used by the
+   job ``myjobs/this_provider_command``. We create a file there called 
+   ``mycommand`` which contains the following text::
+
+    #!/bin/sh
+    test `cat $CHECKBOX_SHARE/data/testfile` = 'expected'
+
+   This needs to be executable to be used in the job command so we need to run
+   ``chmod a+x mycommand`` to make it executable.
+
+   You'll notice the command uses a file in ``$CHECKBOX_SHARE/data`` - we'll
+   add this file to our provider next. 
+
+#. Because the command we’re using uses a file that we expect to be located in
+   ``$CHECKBOX_SHARE/data``, we need to add this file to our provider so that 
+   after the provider is installed this file is available in that location. 
+   First we need to change to the directory called ``data``, then as indicated 
+   by the contents of the script we wrote in the previous step, we need to 
+   create a file there called ``testfile`` with the contents::
+
+    expected
+
+   As simple as that!
+
+#. Lastly we need to add a :term:`whitelist` that utilizes the jobs we created
+   earlier. We need to change to the directory called ``whitelists``. As with
+   the ``jobs`` directory  there is already an example file there called 
+   ``category.whitelist``. We can delete that and add a file called 
+   ``mywhitelist.whitelist``. The contents should be::
+
+    myjobs/shell_command
+    myjobs/provider_command
+
+   The ``miscellanea/submission_resources`` and ``graphics/glxgears`` jobs
+   are from the default provider that is part of Plainbox.
+
+   We can check that everything is correct with the whitelist by running the 
+   ``./manage.py info`` command again. The output should be like::
+
+    [Provider MetaData]
+	name: com.example:myprovider
+	version: 1.0
+    [Job Definitions]
+	'myjobs/builtin_command', from jobs/myjobs.txt:1-5
+	'myjobs/provider_command', from jobs/myjobs.txt:7-11
+    [White Lists]
+	'mywhitelist', from whitelists/mywhitelist.whitelist:1-2 
+  
+   Our new :term:`whitelist` is listed there.
+
+#. Now we have a provider we need to test it to make sure everything is
+   correct. The first thing to do is to install the provider so that it
+   it visible to Plainbox. Run ``./manage.py develop`` then run 
+   ``plainbox dev list provider``. Your provider should be in the list
+   that is displayed.
+
+#. We should also make sure the whole provider works end-to-end by running
+   the :term:`whitelist` which it provides. Run the following command - 
+   ``plainbox run -w whitelists/mywhitelist.whitelist``.
+
+#. Assuming everything works okay, we can now package the provider for 
+   distribution. This involves creating a basic ``debian`` directory
+   containing all of the files needed for packaging your provider. Create
+   a directory called ``debian`` at the base of your provider, and then
+   create the following files within it.
+
+   ``compat``::
+
+    9
+
+   ``control``::
+
+    Source: plainbox-myprovider
+    Section: utils
+    Priority: optional
+    Maintainer: Brendan Donegan <[e-mail]>
+    Standards-Version: 3.9.3
+    X-Python3-Version: >= 3.2
+    Build-Depends: debhelper (>= 9.2),
+                   lsb-release,
+                   python3 (>= 3.2),
+                   python3-plainbox
+
+    Package: plainbox-myprovider
+    Architecture: all
+    Depends: plainbox-provider-checkbox
+    Description: My whitelist provider
+     A provider for Plainbox.
+
+   ``rules``::
+
+    #!/usr/bin/make -f
+    %:
+        dh "$@"
+
+    override_dh_auto_build:
+        $(CURDIR)/manage.py install
+
+   Note that the ``rules`` file must be executable. Make it so with 
+   ``chmod a+x rules``. Also, be careful with the indentation in the
+   file - all indents must be actual TAB characters, not four spaces
+   for example.
+
+   ``source/format``::
+
+    3.0 (native)
+
+   Finally we should create a ``changelog`` file. The easiest way to do this
+   is to run the command ``dch --create 'Initial release.'``. You'll need to
+   edit the field ``PACKAGE`` to the name of your provider and the field
+   ``VERSION`` to something like ``0.1``.
diff --git a/docs/author/whitelists.rst b/docs/author/whitelists.rst
new file mode 100644
index 0000000..7b5f162
--- /dev/null
+++ b/docs/author/whitelists.rst
@@ -0,0 +1,120 @@
+========================
+Checkbox Whitelist Files
+========================
+
+When creating a test suite for a particular purpose, it will be necessary to
+specify which tests to run and which order they should run in. For this purpose
+Checkbox provides the concept of Whitelists.
+
+Whitelist Format
+================
+
+A whitelist is a text file containing a line-seperated sequence of patterns, 
+each representing one or more 'jobs'. These patterns are in the Python regular 
+expression syntax. Comments may be included in the file by starting the line 
+with '#'.
+
+Minimal Whitelist File
+======================
+
+In order to be useful a whitelist file needs to include a particular subset of
+jobs which provide Checkbox with all of the information it needs to run tests 
+properly. These include jobs which attach hardware information and resource 
+jobs which provide other jobs with information of the environment they a
+re running in (available hardware, available packages etc). To make this easy 
+to do a single job exists whose purpose is to execute all of these other jobs::
+
+    miscellanea/submission-resources
+
+This should be included as the first job in any whitelist.
+
+Job Categories
+==============
+
+In order to allow Checkbox to display jobs by category in the UI it is 
+necessary to include a particular local job which itself generates jobs which 
+belong to that category. This job will normally look like ``__<category>__`` 
+where <category> is the name of the job file which contains the job. This is 
+indicated again by the prefix of the job (before the ``/`` in the job name). 
+As a quick example, the job ``graphics/glxgears`` is contained in 
+``graphics.txt``. Therefore we should include the ``__graphics__`` job so that 
+the ``graphics/glxgears`` job shows correctly under the category. The 
+``__graphics__`` job itself looks like::
+
+    name: __graphics__
+    plugin: local
+    _description: Graphics tests
+    command:
+      shopt -s extglob
+      cat $CHECKBOX_SHARE/jobs/graphics.txt?(.in)
+
+Checkbox will interpret this job as a request to display any job in 
+``graphics.txt`` (or its untranslated version ``graphics.txt.in``) under the 
+heading shown in the description of this job (in this case 'Graphics tests').
+
+Tutorial
+========
+
+To compound what we discussed before, below is a brief tutorial which walks 
+through assembling a basic whitelist file.
+
+1. First we need to create a file, let's name it tutorial.whitelist. 
+Whitelists don't have to end with the .whitelist suffix but this is the 
+convention used to help identify them.
+2. We start by adding the one job that is required for all whitelists, as 
+explained above in the section 'Minimal Whitelist File', so our whitelist file 
+looks like::
+
+    miscellanea/submission-resources
+
+3. Next we should choose some jobs that we want to run. This all depends on 
+your specific use-case of course, but I've selected a few jobs that will help 
+clearly illustrate more of the concepts involved in whitelists. These jobs will 
+give us a whitelist file that looks like::
+
+    miscellanea/submission-resources
+    cpu/clocktest
+    ethernet/multi_nic
+    ethernet/multi_nic_eth0
+    graphics/glxgears
+
+ If we run this whitelist now then all of these jobs will be executed and a 
+ valid test submission will be created, but we can still improve it in a couple 
+ of ways.
+
+4. The first way is by adding the necessary jobs to allow the Checkbox UI to 
+group the jobs into specific categories. To do this we need to add a job with 
+a name like ``__<category>__`` for each category. We have three categories in 
+our whitelist file - cpu, ethernet and graphics. The category of the job is 
+the prefix of the job name prior to the ``/``. So now our whitelist file looks 
+like::
+
+    miscellanea/submission-resources
+    __cpu__
+    __ethernet__
+    __graphics__
+    cpu/clocktest
+    ethernet/multi_nic
+    ethernet/multi_nic_eth0
+    graphics/glxgears
+
+  Now the Checkbox UI will group the jobs into these categories.
+
+5. Although it's not immediately apparent there is another problem with this 
+whitelist. The ``ethernet/multi_nic`` tests are only able to include one job 
+for the ethernet port 'eth0'. It would be better if we included all of the 
+jobs generated by 'ethernet/multi_nic', no matter how many ethernet ports are 
+present on the system under test. The best way to do this is to write the 
+pattern so that it matches all of the possible job names. We can take advantage 
+of the Python regular expression syntax and use the ``\d`` special character 
+to match any decimal number. After doing this the whitelist file will look 
+like this::
+
+    miscellanea/submission-resources
+    __cpu__
+    __ethernet__
+    __graphics__
+    cpu/clocktest
+    ethernet/multi_nic
+    ethernet/multi_nic_eth\d
+    graphics/glxgears
diff --git a/docs/conf.py b/docs/conf.py
index 07bd76e..4ff2437 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -124,11 +124,16 @@ pygments_style = 'sphinx'
 # Use our custom theme. For now it only adds Disqus.com support but we may
 # customize it further later on. The theme is called 'plainbox' and has one
 # option which controls if disqus is active or not.
+<<<<<<< docs/conf.py
 html_theme = 'plainbox'
+=======
+html_theme = 'default'
+>>>>>>> docs/conf.py
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
+<<<<<<< docs/conf.py
 #
 # Due to the way disqus works, it's only going to work on
 # plainbox.readthedocs.org so only use it if building for readthedocs.
@@ -137,6 +142,8 @@ html_theme_options = {
     'show_disqus': 'true' if os.environ.get(
         "READTHEDOCS", None) == 'True' else ''
 }
+=======
+>>>>>>> docs/conf.py
 
 # Add any paths that contain custom themes here, relative to this directory.
 html_theme_path = ['_theme']
diff --git a/docs/dev/old.rst b/docs/dev/old.rst
index 7921f68..9584888 100644
--- a/docs/dev/old.rst
+++ b/docs/dev/old.rst
@@ -144,6 +144,11 @@ dependencies) being added to the repository.
 Implementation issues
 ---------------------
 
+<<<<<<< docs/dev/old.rst
+=======
+There are two issues that are known at this time:
+
+>>>>>>> docs/dev/old.rst
 * There is too much checkbox-specific knowledge which really belongs
   elsewhere. We are working to remove that so that non-checkbox jobs
   can be introduced later. There is a branch in progress that entirely
@@ -153,6 +158,18 @@ Implementation issues
   that was previously internal (most notably a way to add new jobs and
   resources).
 
+<<<<<<< docs/dev/old.rst
+=======
+* The way jobs are currently selected is unfortunate because of local jobs
+  that can add new jobs to the system. This causes considerable complexity
+  at the application level where the application must check if each
+  executed job is a 'local' job and re-compute the desired_job_list. This
+  should be replaced by a matcher function that can be passed to
+  SessionState once so that desired_job_list is re-evaluated internally
+  whenever job_list changes.
+
+
+>>>>>>> docs/dev/old.rst
 :class:`~plainbox.impl.job.JobDefinition`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -200,6 +217,52 @@ plugin == "manual"
 This value is used for fully manual jobs. It has no special handling in the core
 apart from requiring a human-provided outcome (pass/fail classification) 
 
+<<<<<<< docs/dev/old.rst
+=======
+.. _local:
+
+plugin == "local"
+#################
+
+This value is used for special job generator jobs. The output of such jobs is
+interpreted as additional jobs and is identical in effect to loading such jobs
+from a job definition file. 
+
+There are two practical uses for such jobs:
+
+* Some local jobs are used to generate a number of jobs for each object.
+  This is needed where the tested machine may have a number of such objects
+  and each requires unique testing. A good example is a computer where all
+  network tests are explicitly "instantiated" for each network card
+  present.
+ 
+  This is a valid use case but is rather unfortunate for architecture of
+  Plainbox and there is a desire to replace it with equally-expressive
+  pattern jobs. The advantage is that unlike local jobs (which cannot be
+  "discovered" without enduring any potential side effects that may be
+  caused by the job script command) pattern jobs would allow the core to
+  determine the names of jobs that can be generated and, for example,
+  automatically determine that a pattern job needs to be executed as a
+  dependency of a phantom (yet undetermined) job with a given name.
+
+  The solution with "pattern" jobs may be executed in future phases of
+  Plainbox development. Currently there is no support for that at all.
+
+  Currently Plainbox cannot determine job dependencies across local jobs.
+  That is, unless a local job is explicitly requested (in the desired job
+  list) Plainbox will not be able to run a job that is generated by a local
+  job at all and will treat it as if that job never existed.
+
+* Some local jobs are used to create a form of informal "category".
+  Typically all such jobs have a leading and trailing double underscore,
+  for example '__audio__'. This is currently being used by Checkbox for
+  building a hierarchical tree of tests that the user may select.
+
+  Since this has the same flaws as described above (for pattern jobs) it
+  will likely be replaced by an explicit category field that can be
+  specified each job.
+
+>>>>>>> docs/dev/old.rst
 plugin == "resource"
 ####################
 
diff --git a/docs/dev/trusted-launcher.rst b/docs/dev/trusted-launcher.rst
index a0cc565..6e5a6ec 100644
--- a/docs/dev/trusted-launcher.rst
+++ b/docs/dev/trusted-launcher.rst
@@ -145,7 +145,11 @@ Usage
 .. code-block:: text
 
     plainbox-trusted-launcher-1 [-h] (--hash HASH | --warmup)
+<<<<<<< docs/dev/trusted-launcher.rst
                               [--via GENERATOR-JOB-HASH]
+=======
+                              [--via LOCAL-JOB-HASH]
+>>>>>>> docs/dev/trusted-launcher.rst
                               [NAME=VALUE [NAME=VALUE ...]]
 
     positional arguments:
@@ -156,7 +160,11 @@ Usage
       --hash HASH           job hash to match
       --warmup              Return immediately, only useful when used with
                             pkexec(1)
+<<<<<<< docs/dev/trusted-launcher.rst
       --via GENERATOR-JOB-HASH  Generator job hash to use to match the generated job
+=======
+      --via LOCAL-JOB-HASH  Local job hash to use to match the generated job
+>>>>>>> docs/dev/trusted-launcher.rst
 
 .. note::
 
@@ -185,11 +193,25 @@ thanks to the installed policy file the authentication will be kept.
 Special case of jobs using the Checkbox local plugin
 ----------------------------------------------------
 
+<<<<<<< docs/dev/trusted-launcher.rst
 For jobs generated from resources jobs (e.g.
 disk/read_performance.*) the trusted launcher is started with ``--via`` meaning
 that we have to first eval a generator job to find a hash match. Once a match is
+=======
+For jobs generated from :ref:`local <local>` jobs (e.g.
+disk/read_performance.*) the trusted launcher is started with ``--via`` meaning
+that we have to first eval a local job to find a hash match. Once a match is
+>>>>>>> docs/dev/trusted-launcher.rst
 found, the job command is executed.
 
 .. code-block:: bash
 
+<<<<<<< docs/dev/trusted-launcher.rst
     $ pkexec plainbox-trusted-launcher-1 --hash JOB-HASH --via GENERATOR-JOB-HASH
+=======
+    $ pkexec plainbox-trusted-launcher-1 --hash JOB-HASH --via LOCAL-JOB-HASH
+
+.. note::
+
+    it will obviously fail if any local job can ever generate another local job.
+>>>>>>> docs/dev/trusted-launcher.rst
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 212d9a2..8d22fef 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -46,11 +46,20 @@ Glossary
            necessary for end-user work. ``plainbox`` is usually installed
            explicitly if needed.
 
+<<<<<<< docs/glossary.rst
     test plan
 
         Test plans are text files used by Checkbox to select jobs for
         execution. They can include simple regular expressions to match and
         pick many similar jobs at once.
+=======
+    whitelist
+
+        Whitelists are text files used by Checkbox to select jobs for
+        execution.  They can include simple regular expressions to match and
+        pick many similar jobs at once. For more information see
+        :doc:`Checkbox Whitelist Files <author/whitelists>`
+>>>>>>> docs/glossary.rst
 
     job
 
@@ -62,7 +71,11 @@ Glossary
 
     provider
 
+<<<<<<< docs/glossary.rst
         A container for jobs, test plans, private executables and data.
+=======
+        A container for jobs, whitelists, private executables and data.
+>>>>>>> docs/glossary.rst
         Providers are the foundation of Plainbox as they *provide* all of the
         content. Providers can be created and managed by any entity, separately
         from the Checkbox project.
@@ -95,7 +108,11 @@ Glossary
     attachment
         
         Attachments are a special type of a Job that can creates an attachment
+<<<<<<< docs/glossary.rst
         record in the submission reports. They are commonly used to include
+=======
+        record in the submission.xml file. They are commonly used to include
+>>>>>>> docs/glossary.rst
         basic system information files and output of certain commands which can
         aid in system certification.
 
diff --git a/docs/manpages/plainbox-dev-analyze.rst b/docs/manpages/plainbox-dev-analyze.rst
index 23fc999..6bcc0c1 100644
--- a/docs/manpages/plainbox-dev-analyze.rst
+++ b/docs/manpages/plainbox-dev-analyze.rst
@@ -15,6 +15,16 @@ plainbox-dev-analyze (1)
     and the command prints nothing at all) to inspect certain aspects of the
     hypothetical session
 
+<<<<<<< docs/manpages/plainbox-dev-analyze.rst
+=======
+    The only exception to the rule above is the ``--run-local`` option. With that
+    option all local jobs and their dependencies *are* started. This is
+    technically required to correctly emulate the behavior of ``plainbox run``
+    that does so unconditionally. Still, local jobs can cause harm so don't run
+    untrusted code this way (the author of this man page recalls one local job
+    that ran ``sudo reboot`` to measure bootchart data)
+
+>>>>>>> docs/manpages/plainbox-dev-analyze.rst
     Report Types
     ============
 
@@ -67,11 +77,19 @@ plainbox-dev-analyze (1)
     always includes additional jobs (such as resource jobs and other
     dependencies)
 
+<<<<<<< docs/manpages/plainbox-dev-analyze.rst
     The run list is of great importance. Most of the time the test operator
     will see tests in precisely this order. The only exception is that some
     test applications choose to pre-run generator jobs (resources). Still, if
     your job ordering is wrong in any way, inspecting the run list is the best
     way to debug the problem.
+=======
+    The run list is of great importance. Most of the time the test operator will
+    see tests in precisely this order. The only exception is that some test
+    applications choose to pre-run local jobs. Still, if your job ordering is
+    wrong in any way, inspecting the run list is the best way to debug the
+    problem.
+>>>>>>> docs/manpages/plainbox-dev-analyze.rst
 
 See Also
 ========
diff --git a/docs/manpages/plainbox-exporter-units.rst b/docs/manpages/plainbox-exporter-units.rst
index df7172c..2b0791b 100644
--- a/docs/manpages/plainbox-exporter-units.rst
+++ b/docs/manpages/plainbox-exporter-units.rst
@@ -120,4 +120,40 @@ The provider shipping such unit can be as follow::
         └── exporters.pxu
 
 Note that exporters.pxu is not strictly needed to store the exporter units, but
+<<<<<<< docs/manpages/plainbox-exporter-units.rst
 keeping them in a dedicated file is a good practice.
+=======
+keeping them in a dedidated file is a good practice.
+
+How to use exporter units?
+--------------------------
+
+In order to call an exporter unit from provider foo, you just need to add the
+unit id to the cli or the gui launcher in the exporter section:
+
+Example of a gui launcher:
+
+    #!/usr/bin/checkbox-gui
+
+    [welcome]
+    title = "Foo"
+    text = "bar"
+
+    [exporter]
+    HTML = "com.foo.bar::my_html"
+
+Example of a cli launcher:
+
+    #!/usr/bin/env checkbox-launcher
+    [welcome]
+    text = Foo
+
+    [suite]
+    whitelist_filter = ^.*$
+    whitelist_selection = ^default$
+
+    [exporter]
+    com.foo.bar::my_html
+    com.foo.bar::my_json
+    com.foo.baz::my_html
+>>>>>>> docs/manpages/plainbox-exporter-units.rst
diff --git a/docs/manpages/plainbox-file-units.rst b/docs/manpages/plainbox-file-units.rst
index 3c5ddbd..d8da24e 100644
--- a/docs/manpages/plainbox-file-units.rst
+++ b/docs/manpages/plainbox-file-units.rst
@@ -36,6 +36,12 @@ There are two fields that are used by the file unit:
     'unit-source':
         The file is a source of unit definitions. Currently this is the only
         actually implemented value.
+<<<<<<< docs/manpages/plainbox-file-units.rst
+=======
+
+    'legacy-whitelist':
+        This file is a legacy whitelist.
+>>>>>>> docs/manpages/plainbox-file-units.rst
     
     'script':
         This file is an architecture independent executable.
@@ -57,4 +63,8 @@ There are two fields that are used by the file unit:
         This file contains copyright and licensing information.
 
     'docs':
+<<<<<<< docs/manpages/plainbox-file-units.rst
+        This file contains documentation.
+=======
         This file contains documentation.
+>>>>>>> docs/manpages/plainbox-file-units.rst
diff --git a/docs/manpages/plainbox-job-units.rst b/docs/manpages/plainbox-job-units.rst
index 08e8fd1..d33c2d8 100644
--- a/docs/manpages/plainbox-job-units.rst
+++ b/docs/manpages/plainbox-job-units.rst
@@ -56,6 +56,12 @@ Following fields may be used by the job unit:
         test's outcome. This is essentially a manual job with a command.
      :attachment: jobs whose command output will be attached to the
          test report or submission.
+<<<<<<< docs/manpages/plainbox-job-units.rst
+=======
+     :local: a job whose command output needs to be in Checkbox job
+         format. Jobs output by a local job will be added to the set of
+         available jobs to be run.
+>>>>>>> docs/manpages/plainbox-job-units.rst
      :resource: A job whose command output results in a set of rfc822
           records, containing key/value pairs, and that can be used in other
           jobs' ``requires`` expressions.
diff --git a/docs/manpages/plainbox-run.rst b/docs/manpages/plainbox-run.rst
index 3363aa8..b3a6432 100644
--- a/docs/manpages/plainbox-run.rst
+++ b/docs/manpages/plainbox-run.rst
@@ -74,6 +74,47 @@ plainbox-run (1)
 
         plainbox run -i '.*::foo' -i '.*::bar'
 
+<<<<<<< docs/manpages/plainbox-run.rst
+=======
+    Selecting jobs with whitelists
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    The second mechanism is the ``--whitelist WHITELIST`` command-line option.
+    WhiteLists (or test plans, which is somewhat easier to relate to).
+    Whitelists are simple text files composed of a list of regular expressions,
+    identical to those that may be passed with the ``-i`` option.
+
+    Unlike the ``-i`` option though, there are two kinds of whitelists.
+    Standalone whitelists are not associated with any Plainbox Provider.  Such
+    whitelists can be distributed entirely separately from any other component
+    and thus have no association with any namespace.
+
+    Therefore, be fully qualified, each pattern must include both the namespace
+    and the partial identifier components. For example, this is a valid, fully
+    quallified whitelist::
+
+        com.canonical.plainbox::stub/.*
+
+    It will unambiguously select some of the jobs from the special, internal
+    StubBox provider that is built into Plainbox. It can be saved under any
+    filename and stored in any directory and it will always select the same set
+    of jobs.
+
+    In contrast, whitelists that are associated with a particular provider, by
+    being stored in the per-provider ``whitelists/`` directory, carry an
+    implicit namespace. Such whitelists are typically written without
+    mentioning the namespace component.
+
+    For example, the same "stub/.*" pattern can be abbreviated to::
+
+        stub/.*
+
+    Typically this syntax is used in all whitelists specific to a particular
+    provider unless the provider maintainer explicitly wants to include a job
+    from another namespace (for example, one of the well-known Checkbox job
+    definitions).
+
+>>>>>>> docs/manpages/plainbox-run.rst
     GENERATED JOBS
     ==============
 
@@ -87,7 +128,32 @@ plainbox-run (1)
     storage devices) and then duplicate each of the store specific tests so
     that all devices are tested separately.
 
+<<<<<<< docs/manpages/plainbox-run.rst
     One limitation is that jobs cannot override existing definitions.
+=======
+    At this time jobs can be generated only from jobs using the plugin type
+    `local`. Jobs of this kind are expected to print fully conforming job
+    definitions on stdout. Generated jobs cause a few complexities and one
+    limitation that is currently enforced is that generated jobs cannot
+    generate additional jobs if any of the affected jobs need to run as another
+    user.
+
+    Another limitation is that jobs cannot override existing definitions.
+
+    Creating Parent-Child Association
+    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+    A relatively niche and legacy feature of generated jobs is to print a
+    verbatim copy of existing job definitions from a ``local`` job definition
+    named afer a generic testing theme or category. For example the Checkbox
+    job definition ``__wireless__`` prints, with the help of ``cat`` (1), all
+    of the job definitions defined in the file ``wireless.txt``.
+
+    This behavior is special-cased not to cause redefinition errors. Instead,
+    existing definitions gain the ``via`` attribute that links them to the
+    generator job. This feature is used by derivative application such as
+    Checkbox. Plainbox is not using it at this time.
+>>>>>>> docs/manpages/plainbox-run.rst
 
     RESUMING
     ========
@@ -132,10 +198,17 @@ plainbox-run (1)
 
     Some formats are more useful than others in that they are capable of
     transferring more of the internal state. Depending on your application you
+<<<<<<< docs/manpages/plainbox-run.rst
     may wish to choose the most generic format (tar.xz) and process it further
     with additional tools, choose the most basic format (text) just to get a
     simple summary of the results or lastly choose one of the two specialized
     formats (xlsx and html) that are specific to the Checkbox workflow.
+=======
+    may wish to choose the most generic format (json) and process it further
+    with additional tools, choose the most basic format (text) just to get a
+    simple summary of the results or lastly choose one of the two specialized
+    formats (xml and html) that are specific to the Checkbox workflow.
+>>>>>>> docs/manpages/plainbox-run.rst
 
     Out of the box the following exporters are supported:
 
@@ -171,7 +244,11 @@ plainbox-run (1)
     xlsx
     ----
 
+<<<<<<< docs/manpages/plainbox-run.rst
     This exporter creates a standalone .xlsx (OOXML format for Microsoft Excel)
+=======
+    This exporter creates a standalone .xlsx (XML format for Microsoft Excel)
+>>>>>>> docs/manpages/plainbox-run.rst
     file that contains a human-readable test report. It is quit similar to the
     HTML report but it is easier to edit. It is useful for communicating with
     other humans and since it is entirely standalone and off-line it can be
@@ -179,6 +256,20 @@ plainbox-run (1)
 
     It depends on python3-xlsxwriter package
 
+<<<<<<< docs/manpages/plainbox-run.rst
+=======
+    hexr
+    ----
+
+    This exporter creates a rather confusingly named XML document only
+    applicable for internal Canonical Hardware Certification Team workflow.
+
+    It is not a generic XML representation of test results and instead it
+    carries quite a few legacy constructs that are only retained for
+    compatibility with other internal tools. If you want generic processing
+    look for JSON instead.
+
+>>>>>>> docs/manpages/plainbox-run.rst
     Selecting Exporter Options
     ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -243,24 +334,51 @@ plainbox-run (1)
         Exported data will include comments added by the test operator to each
         job result that has them.
 
+<<<<<<< docs/manpages/plainbox-run.rst
     with-job-hash:
         Exported data will include the ``hash`` attribute alongside each job
         result. The hash attribute is the checksum of the job definition's
         data.
+=======
+    with-job-via:
+        Exported data will include the ``via`` attribute alongside each job
+        result. The via attribute contains the checksum of the job definition
+        that generated a particular job definition. This is useful for tracking
+        jobs generated by jobs with the plugin type `local`.
+
+    with-job-hash:
+        Exported data will include the ``hash`` attribute alongside each job
+        result. The hash attribute is the checksum of the job definition's
+        data. It can be useful alongside with `with-job-via`.
+>>>>>>> docs/manpages/plainbox-run.rst
 
     machine-json:
         The generated JSON document will be minimal (devoid of any optional
         whitespace). This option is best to be used if the result is not
         intended to be read by humans as it saves some space.
 
+<<<<<<< docs/manpages/plainbox-run.rst
     text
+=======
+    rfc822
+>>>>>>> docs/manpages/plainbox-run.rst
     ------
 
     All of the options have the same meaning as for the `json` exporter:
     `with-io-log`, `squash-io-log`, `flatten-io-log`, `with-run-list`,
     `with-job-list`, `with-resource-map`, `with-job-defs`, `with-attachments`,
+<<<<<<< docs/manpages/plainbox-run.rst
     `with-comments`, `with-job-hash`.  The only exception is the `machine-json`
     option which doesn't exist for this exporter.
+=======
+    `with-comments`, `with-job-via`, `with-job-hash`.  The only exception is
+    the `machine-json` option which doesn't exist for this exporter.
+
+    text
+    ----
+
+    Same as with rfc822.
+>>>>>>> docs/manpages/plainbox-run.rst
 
     xlsx
     ----
@@ -280,6 +398,18 @@ plainbox-run (1)
     with-text-attachments:
         Exported spreadsheet will include text attachments on a separate sheet
 
+<<<<<<< docs/manpages/plainbox-run.rst
+=======
+    xml
+    ---
+
+    client-name:
+        This option allows clients to override the name of the application
+        generating the XML document. By default that name is `plainbox`.  To
+        use this option pass ``--output-options client-name=other-name``
+        command-line option.
+
+>>>>>>> docs/manpages/plainbox-run.rst
     TRANSPORTING RESULTS
     ====================
 
@@ -298,12 +428,32 @@ plainbox-run (1)
 
     Plainbox comes equipped with the following transports:
 
+<<<<<<< docs/manpages/plainbox-run.rst
     certification
     ^^^^^^^^^^^^^
 
     This transport can send the results exported using the ``tar`` exporter to
     the Canonical Certification Website (https://certification.canonical.com).
 
+=======
+    launchpad
+    ^^^^^^^^^
+
+    This transport can send the results exported using ``xml`` exporter to the
+    Launchpad Hardware Database. This is a little-known feature offered by the
+    https://launchpad.net/ website.
+
+    certification
+    ^^^^^^^^^^^^^
+
+    This transport can send the results exported using the ``xml`` exporter to
+    the Canonical Certification Website (https://certification.canonical.com).
+
+    This transport is of little use to anyone but the Canonical Hardware
+    Certification Team that also maintains Plainbox and Checkbox but it is
+    mentioned here for completeness.
+
+>>>>>>> docs/manpages/plainbox-run.rst
 See Also
 ========
 
diff --git a/docs/manpages/plainbox-test-plan-units.rst b/docs/manpages/plainbox-test-plan-units.rst
index 6857100..b04b135 100644
--- a/docs/manpages/plainbox-test-plan-units.rst
+++ b/docs/manpages/plainbox-test-plan-units.rst
@@ -99,10 +99,18 @@ copy such constructs when working on a new test plan from scratch
        common and most test plans used by Checkbox actually look like that.
 
      - You can use regular expressions to select many tests at the same time.
+<<<<<<< docs/manpages/plainbox-test-plan-units.rst
        This is the only way to select generated jobs (created by template
        units). Please remember that the dot character has a special meaning so
        unless you actually want to match *any character* escape the dot with
        the backslash character (\\).
+=======
+       This is the only way to select generated jobs (created either by
+       template units or by job definitions using the legacy 'local' plugin
+       type). Please remember that the dot character has a special meaning
+       so unless you actually want to match *any character* escape the dot
+       with the backslash character (\\).
+>>>>>>> docs/manpages/plainbox-test-plan-units.rst
 
     Regardless of if you use patterns or literal job identifiers you can use
     their fully qualified name (the one that includes the namespace they reside
@@ -148,7 +156,11 @@ copy such constructs when working on a new test plan from scratch
 
     Note that each entry in the bootstrap_include section must be a valid job
     identifier and cannot be a regular expression pattern.
+<<<<<<< docs/manpages/plainbox-test-plan-units.rst
     Also note that only resource jobs are allowed in this section.
+=======
+    Also note that only local and resource jobs are allowed in this section.
+>>>>>>> docs/manpages/plainbox-test-plan-units.rst
 
 ``exclude``:
     A multi-line list of job identifiers or patterns matching such identifiers
diff --git a/docs/manpages/plainbox-trusted-launcher-1.rst b/docs/manpages/plainbox-trusted-launcher-1.rst
index 77cdfeb..e609736 100644
--- a/docs/manpages/plainbox-trusted-launcher-1.rst
+++ b/docs/manpages/plainbox-trusted-launcher-1.rst
@@ -77,8 +77,18 @@ The following environment variables *DO NOT* affect ``plainbox-trusted-launcher-
 Bugs
 ====
 
+<<<<<<< docs/manpages/plainbox-trusted-launcher-1.rst
 The launcher is somewhat inefficient, in that it has to re-run all of the
 dependencies of the generator job over and over. Ideally those would be cached,
+=======
+Currently it is impossible to use ``plainbox-trusted-launcher-1`` with a
+``local`` job needs to run as root, that generates another ``local`` job that
+needs to run as root, to generate any additional jobs that also need to run as
+root. In other words, only one-level job generation is supported.
+
+The launcher is somewhat inefficient, in that it has to re-run all of the
+dependencies of the ``local`` job over and over. Ideally those would be cached,
+>>>>>>> docs/manpages/plainbox-trusted-launcher-1.rst
 per-session, but that would significantly increase the complexity of the code
 running as root.
 
diff --git a/docs/usage.rst b/docs/usage.rst
index e2f2f0a..6f698b5 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -47,12 +47,31 @@ To list all known jobs run:
 
     plainbox dev special --list-jobs
 
+<<<<<<< docs/usage.rst
+=======
+Running a white list
+^^^^^^^^^^^^^^^^^^^^
+
+To run a :term:`whitelist` pass the ``--whitelist`` or ``-w`` option.
+
+For example, to run the default white list run:
+
+.. code-block:: bash
+
+    $ plainbox run -w /path/to/some/file.whitelist
+
+>>>>>>> docs/usage.rst
 Saving test results
 ^^^^^^^^^^^^^^^^^^^
 
 Anything that Plainbox captures and stores during test execution can be
+<<<<<<< docs/usage.rst
 exported to a file using the exporter system. The three most commonly used
 exporters are tar.xz, html and xlsx.
+=======
+exported to a file using the exporter system. The two most commonly used
+exporters are JSON (versatile and general) and XML (for internal Canonical use).
+>>>>>>> docs/usage.rst
 
 JSON Exporter
 -------------
@@ -61,7 +80,11 @@ To generate a JSON file with all of the internally available data (for storage,
 processing or other automation) you will need to pass three additional
 arguments to ``plainbox run``:
 
+<<<<<<< docs/usage.rst
 #. ``--output-format=com.canonical.com.canonical.plainbox::json``
+=======
+#. ``--output-format=com.canonical.plainbox::json``
+>>>>>>> docs/usage.rst
 #. ``--output-options=OPTION1,OPTION2`` where *OPTIONx* are option names.
 #. ``--output-file=NAME`` where *NAME* is a file name.
 
@@ -70,7 +93,27 @@ exporter options can be specified, separated with commas.
 
 .. code-block:: bash
 
+<<<<<<< docs/usage.rst
     $ plainbox run -i com.canonical.certification::foo --output-format=com.canonical.plainbox::json --output-file=results.json
+=======
+    $ plainbox run --whitelist=/path/to/some/file.whitelist --output-format=com.canonical.plainbox::json --output-file=results.json
+
+XML Exporter
+------------
+
+To generate an XML file that can be sent to the :term:`certification website`
+you need to pass two additional arguments to ``plainbox run``:
+
+#. ``--output-format=com.canonical.plainbox::hexr``
+#. ``--output-file=NAME`` where *NAME* is a file name
+
+For example, to get the default certification tests ready to be submitted
+run this command:
+
+.. code-block:: bash
+
+    $ plainbox run --whitelist=/path/to/some/file.whitelist --output-format=com.canonical.plainbox::hexr --output-file=submission.xml
+>>>>>>> docs/usage.rst
 
 Other Exporters
 ---------------
diff --git a/plainbox.egg-info/PKG-INFO b/plainbox.egg-info/PKG-INFO
new file mode 100644
index 0000000..fafbf3f
--- /dev/null
+++ b/plainbox.egg-info/PKG-INFO
@@ -0,0 +1,62 @@
+Metadata-Version: 1.1
+Name: plainbox
+Version: 0.38.0
+Summary: Toolkit for software and hardware integration testing
+Home-page: https://launchpad.net/plainbox/
+Author: Zygmunt Krynicki
+Author-email: [e-mail]
+License: GPLv3
+Description: PlainBox
+        ========
+        
+        PlainBox is a toolkit consisting of python3 library, development tools,
+        documentation and examples. It is targeted at developers working on testing or
+        certification applications and authors creating tests for such applications.
+        
+        PlainBox can be used to both create simple and comprehensive test tools as well
+        as to develop and execute test jobs and test scenarios. It was created as a
+        refined and rewritten core of the CheckBox project. It has a well tested and
+        documented core, small but active development community and a collection of
+        associated projects that use it as a lower-level engine/back-end library.
+        
+        PlainBox has a novel approach to discovering (and probing) hardware and
+        software that is extensible and not hardwired into the system. It allows test
+        developers to express association between a particular test and the hardware,
+        software and configuration constraints that must be met for the test to execute
+        meaningfully. This feature, along with pluggable test definitions, makes
+        PlainBox flexible and applicable to many diverse testing situations, ranging
+        from mobile phones, traditional desktop computers, servers and up to testing
+        "cloud" installations.
+        
+        External Documentation Links
+        ============================
+        
+        * `Using PlainBox <http://plainbox.readthedocs.org/en/latest/usage.html>`_
+        * `Hacking on PlainBox <http://plainbox.readthedocs.org/en/latest/dev/index.html>`_