Merge lp:~barry/lazr.config/lp1096512 into lp:lazr.config

[Barry Warsaw]

Another port to Python 3. This one is just like the ports for lazr.smtptest and lazr.delegates. In fact, this depends on the branch for LP: #1096513 which Gavin has approved, but I haven't yet landed and released.

To test this, you'll need to create a virtualenv and install the branch for LP: #1096513 into it. Then you should be able to run the nosetests.

Just like the other two packages, I might have some post-porting fixups for the Sphinx documentation, but I'll clean all that up once this branch lands and I'm ready to do a PyPI release.

(Side note: not all of usage.rst could be retained due to printable repr differences between Python 2 and 3. Where necessary, such tests are moved to unittests, but coverage is still 99%-100% depending on the Python version used.)

[Curtis Hovey (sinzui)]

Thank you for this update. I think this is fine to land, but I think there are changes in behaviour that deserve documentation:
   1. decode('ascii', 'strict'): appear to mean that someone upgrading might see more unicode errors raised.
   2. sorted category names: is nice to have, but different from the past.

review: Approve (code)

[Barry Warsaw (barry)]

On Jan 10, 2013, at 07:17 PM, Curtis Hovey wrote:

> 1. decode('ascii', 'strict'): appear to mean that someone upgrading might
> see more unicode errors raised.

Interestingly, the documentation says that only ASCII is acceptable but the
use of 'ignore' didn't enforce that, at least AFAICT.

> 2. sorted category names: is nice to have, but different from the past.

True. I thought about sorting in the test instead (you have to sort one place
or the other for doctest reproducibility). I mildly preferred to guarantee it
in the API.

Thanks for the review. I'll make sure the NEWS file and the release
announcement properly document these issues.

=== renamed file 'README.txt' => 'README.rst'
=== removed directory '_bootstrap'
=== removed file '_bootstrap/COPYRIGHT.txt'
--- _bootstrap/COPYRIGHT.txt	2009-03-24 17:31:47 +0000
+++ _bootstrap/COPYRIGHT.txt	1970-01-01 00:00:00 +0000
@@ -1,9 +0,0 @@
-Copyright (c) 2004-2009 Zope Corporation and Contributors.
-All Rights Reserved.
-
-This software is subject to the provisions of the Zope Public License,
-Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
-THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
-WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
-FOR A PARTICULAR PURPOSE.
 
=== removed file '_bootstrap/LICENSE.txt'
--- _bootstrap/LICENSE.txt	2009-03-24 17:31:47 +0000
+++ _bootstrap/LICENSE.txt	1970-01-01 00:00:00 +0000
@@ -1,54 +0,0 @@
-Zope Public License (ZPL) Version 2.1
--------------------------------------
-
-A copyright notice accompanies this license document that
-identifies the copyright holders.
-
-This license has been certified as open source. It has also
-been designated as GPL compatible by the Free Software
-Foundation (FSF).
-
-Redistribution and use in source and binary forms, with or
-without modification, are permitted provided that the
-following conditions are met:
-
-1. Redistributions in source code must retain the
-   accompanying copyright notice, this list of conditions,
-   and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the accompanying
-   copyright notice, this list of conditions, and the
-   following disclaimer in the documentation and/or other
-   materials provided with the distribution.
-
-3. Names of the copyright holders must not be used to
-   endorse or promote products derived from this software
-   without prior written permission from the copyright
-   holders.
-
-4. The right to distribute this software or to use it for
-   any purpose does not give you the right to use
-   Servicemarks (sm) or Trademarks (tm) of the copyright
-   holders. Use of them is covered by separate agreement
-   with the copyright holders.
-
-5. If any files are modified, you must cause the modified
-   files to carry prominent notices stating that you changed
-   the files and the date of any change.
-
-Disclaimer
-
-  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS''
-  AND ANY EXPRESSED 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 HOLDERS 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.
 \ No newline at end of file
 
=== removed file '_bootstrap/bootstrap.py'
--- _bootstrap/bootstrap.py	2009-03-24 17:31:47 +0000
+++ _bootstrap/bootstrap.py	1970-01-01 00:00:00 +0000
@@ -1,77 +0,0 @@
-##############################################################################
-#
-# Copyright (c) 2006 Zope Corporation and Contributors.
-# All Rights Reserved.
-#
-# This software is subject to the provisions of the Zope Public License,
-# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
-# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
-# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
-# FOR A PARTICULAR PURPOSE.
-#
-##############################################################################
-"""Bootstrap a buildout-based project
-
-Simply run this script in a directory containing a buildout.cfg.
-The script accepts buildout command-line options, so you can
-use the -c option to specify an alternate configuration file.
-
-$Id$
-"""
-
-import os, shutil, sys, tempfile, urllib2
-
-tmpeggs = tempfile.mkdtemp()
-
-is_jython = sys.platform.startswith('java')
-
-try:
-    import pkg_resources
-except ImportError:
-    ez = {}
-    exec urllib2.urlopen('http://peak.telecommunity.com/dist/ez_setup.py'
-                         ).read() in ez
-    ez['use_setuptools'](to_dir=tmpeggs, download_delay=0)
-
-    import pkg_resources
-
-if sys.platform == 'win32':
-    def quote(c):
-        if ' ' in c:
-            return '"%s"' % c # work around spawn lamosity on windows
-        else:
-            return c
-else:
-    def quote (c):
-        return c
-
-cmd = 'from setuptools.command.easy_install import main; main()'
-ws  = pkg_resources.working_set
-
-if is_jython:
-    import subprocess
-    
-    assert subprocess.Popen([sys.executable] + ['-c', quote(cmd), '-mqNxd', 
-           quote(tmpeggs), 'zc.buildout'], 
-           env=dict(os.environ,
-               PYTHONPATH=
-               ws.find(pkg_resources.Requirement.parse('setuptools')).location
-               ),
-           ).wait() == 0
-
-else:
-    assert os.spawnle(
-        os.P_WAIT, sys.executable, quote (sys.executable),
-        '-c', quote (cmd), '-mqNxd', quote (tmpeggs), 'zc.buildout',
-        dict(os.environ,
-            PYTHONPATH=
-            ws.find(pkg_resources.Requirement.parse('setuptools')).location
-            ),
-        ) == 0
-
-ws.add_entry(tmpeggs)
-ws.require('zc.buildout')
-import zc.buildout.buildout
-zc.buildout.buildout.main(sys.argv[1:] + ['bootstrap'])
-shutil.rmtree(tmpeggs)
 
=== removed symlink 'bootstrap.py'
=== target was u'_bootstrap/bootstrap.py'
=== removed file 'buildout.cfg'
--- buildout.cfg	2009-03-24 17:36:13 +0000
+++ buildout.cfg	1970-01-01 00:00:00 +0000
@@ -1,31 +0,0 @@
-[buildout]
-parts =
-    interpreter
-    test
-    docs
-    tags
-unzip = true
-
-develop = .
-
-[test]
-recipe = zc.recipe.testrunner
-eggs = lazr.config
-defaults = '--tests-pattern ^tests --exit-with-status --suite-name additional_tests'.split()
-
-[docs]
-recipe = z3c.recipe.sphinxdoc
-eggs = lazr.config [docs]
-index-doc = README
-default.css =
-layout.html =
-
-[interpreter]
-recipe = zc.recipe.egg
-interpreter=py
-eggs = lazr.config
-       docutils
-
-[tags]
-recipe = z3c.recipe.tag:tags
-eggs = lazr.config
 
=== added file 'distribute_setup.py'
--- distribute_setup.py	1970-01-01 00:00:00 +0000
+++ distribute_setup.py	2013-01-10 15:47:20 +0000
@@ -0,0 +1,546 @@
+#!python
+"""Bootstrap distribute installation
+
+If you want to use setuptools in your package's setup.py, just include this
+file in the same directory with it, and add this to the top of your setup.py::
+
+    from distribute_setup import use_setuptools
+    use_setuptools()
+
+If you want to require a specific version of setuptools, set a download
+mirror, or use an alternate download directory, you can do so by supplying
+the appropriate options to ``use_setuptools()``.
+
+This file can also be run as a script to install or upgrade setuptools.
+"""
+import os
+import shutil
+import sys
+import time
+import fnmatch
+import tempfile
+import tarfile
+import optparse
+
+from distutils import log
+
+try:
+    from site import USER_SITE
+except ImportError:
+    USER_SITE = None
+
+try:
+    import subprocess
+
+    def _python_cmd(*args):
+        args = (sys.executable,) + args
+        return subprocess.call(args) == 0
+
+except ImportError:
+    # will be used for python 2.3
+    def _python_cmd(*args):
+        args = (sys.executable,) + args
+        # quoting arguments if windows
+        if sys.platform == 'win32':
+            def quote(arg):
+                if ' ' in arg:
+                    return '"%s"' % arg
+                return arg
+            args = [quote(arg) for arg in args]
+        return os.spawnl(os.P_WAIT, sys.executable, *args) == 0
+
+DEFAULT_VERSION = "0.6.34"
+DEFAULT_URL = "http://pypi.python.org/packages/source/d/distribute/"
+SETUPTOOLS_FAKED_VERSION = "0.6c11"
+
+SETUPTOOLS_PKG_INFO = """\
+Metadata-Version: 1.0
+Name: setuptools
+Version: %s
+Summary: xxxx
+Home-page: xxx
+Author: xxx
+Author-email: xxx
+License: xxx
+Description: xxx
+""" % SETUPTOOLS_FAKED_VERSION
+
+
+def _install(tarball, install_args=()):
+    # extracting the tarball
+    tmpdir = tempfile.mkdtemp()
+    log.warn('Extracting in %s', tmpdir)
+    old_wd = os.getcwd()
+    try:
+        os.chdir(tmpdir)
+        tar = tarfile.open(tarball)
+        _extractall(tar)
+        tar.close()
+
+        # going in the directory
+        subdir = os.path.join(tmpdir, os.listdir(tmpdir)[0])
+        os.chdir(subdir)
+        log.warn('Now working in %s', subdir)
+
+        # installing
+        log.warn('Installing Distribute')
+        if not _python_cmd('setup.py', 'install', *install_args):
+            log.warn('Something went wrong during the installation.')
+            log.warn('See the error message above.')
+            # exitcode will be 2
+            return 2
+    finally:
+        os.chdir(old_wd)
+        shutil.rmtree(tmpdir)
+
+
+def _build_egg(egg, tarball, to_dir):
+    # extracting the tarball
+    tmpdir = tempfile.mkdtemp()
+    log.warn('Extracting in %s', tmpdir)
+    old_wd = os.getcwd()
+    try:
+        os.chdir(tmpdir)
+        tar = tarfile.open(tarball)
+        _extractall(tar)
+        tar.close()
+
+        # going in the directory
+        subdir = os.path.join(tmpdir, os.listdir(tmpdir)[0])
+        os.chdir(subdir)
+        log.warn('Now working in %s', subdir)
+
+        # building an egg
+        log.warn('Building a Distribute egg in %s', to_dir)
+        _python_cmd('setup.py', '-q', 'bdist_egg', '--dist-dir', to_dir)
+
+    finally:
+        os.chdir(old_wd)
+        shutil.rmtree(tmpdir)
+    # returning the result
+    log.warn(egg)
+    if not os.path.exists(egg):
+        raise IOError('Could not build the egg.')
+
+
+def _do_download(version, download_base, to_dir, download_delay):
+    egg = os.path.join(to_dir, 'distribute-%s-py%d.%d.egg'
+                       % (version, sys.version_info[0], sys.version_info[1]))
+    if not os.path.exists(egg):
+        tarball = download_setuptools(version, download_base,
+                                      to_dir, download_delay)
+        _build_egg(egg, tarball, to_dir)
+    sys.path.insert(0, egg)
+    import setuptools
+    setuptools.bootstrap_install_from = egg
+
+
+def use_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
+                   to_dir=os.curdir, download_delay=15, no_fake=True):
+    # making sure we use the absolute path
+    to_dir = os.path.abspath(to_dir)
+    was_imported = 'pkg_resources' in sys.modules or \
+        'setuptools' in sys.modules
+    try:
+        try:
+            import pkg_resources
+            if not hasattr(pkg_resources, '_distribute'):
+                if not no_fake:
+                    _fake_setuptools()
+                raise ImportError
+        except ImportError:
+            return _do_download(version, download_base, to_dir, download_delay)
+        try:
+            pkg_resources.require("distribute>=" + version)
+            return
+        except pkg_resources.VersionConflict:
+            e = sys.exc_info()[1]
+            if was_imported:
+                sys.stderr.write(
+                "The required version of distribute (>=%s) is not available,\n"
+                "and can't be installed while this script is running. Please\n"
+                "install a more recent version first, using\n"
+                "'easy_install -U distribute'."
+                "\n\n(Currently using %r)\n" % (version, e.args[0]))
+                sys.exit(2)
+            else:
+                del pkg_resources, sys.modules['pkg_resources']    # reload ok
+                return _do_download(version, download_base, to_dir,
+                                    download_delay)
+        except pkg_resources.DistributionNotFound:
+            return _do_download(version, download_base, to_dir,
+                                download_delay)
+    finally:
+        if not no_fake:
+            _create_fake_setuptools_pkg_info(to_dir)
+
+
+def download_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
+                        to_dir=os.curdir, delay=15):
+    """Download distribute from a specified location and return its filename
+
+    `version` should be a valid distribute version number that is available
+    as an egg for download under the `download_base` URL (which should end
+    with a '/'). `to_dir` is the directory where the egg will be downloaded.
+    `delay` is the number of seconds to pause before an actual download
+    attempt.
+    """
+    # making sure we use the absolute path
+    to_dir = os.path.abspath(to_dir)
+    try:
+        from urllib.request import urlopen
+    except ImportError:
+        from urllib2 import urlopen
+    tgz_name = "distribute-%s.tar.gz" % version
+    url = download_base + tgz_name
+    saveto = os.path.join(to_dir, tgz_name)
+    src = dst = None
+    if not os.path.exists(saveto):  # Avoid repeated downloads
+        try:
+            log.warn("Downloading %s", url)
+            src = urlopen(url)
+            # Read/write all in one block, so we don't create a corrupt file
+            # if the download is interrupted.
+            data = src.read()
+            dst = open(saveto, "wb")
+            dst.write(data)
+        finally:
+            if src:
+                src.close()
+            if dst:
+                dst.close()
+    return os.path.realpath(saveto)
+
+
+def _no_sandbox(function):
+    def __no_sandbox(*args, **kw):
+        try:
+            from setuptools.sandbox import DirectorySandbox
+            if not hasattr(DirectorySandbox, '_old'):
+                def violation(*args):
+                    pass
+                DirectorySandbox._old = DirectorySandbox._violation
+                DirectorySandbox._violation = violation
+                patched = True
+            else:
+                patched = False
+        except ImportError:
+            patched = False
+
+        try:
+            return function(*args, **kw)
+        finally:
+            if patched:
+                DirectorySandbox._violation = DirectorySandbox._old
+                del DirectorySandbox._old
+
+    return __no_sandbox
+
+
+def _patch_file(path, content):
+    """Will backup the file then patch it"""
+    f = open(path)
+    existing_content = f.read()
+    f.close()
+    if existing_content == content:
+        # already patched
+        log.warn('Already patched.')
+        return False
+    log.warn('Patching...')
+    _rename_path(path)
+    f = open(path, 'w')
+    try:
+        f.write(content)
+    finally:
+        f.close()
+    return True
+
+_patch_file = _no_sandbox(_patch_file)
+
+
+def _same_content(path, content):
+    f = open(path)
+    existing_content = f.read()
+    f.close()
+    return existing_content == content
+
+
+def _rename_path(path):
+    new_name = path + '.OLD.%s' % time.time()
+    log.warn('Renaming %s to %s', path, new_name)
+    os.rename(path, new_name)
+    return new_name
+
+
+def _remove_flat_installation(placeholder):
+    if not os.path.isdir(placeholder):
+        log.warn('Unkown installation at %s', placeholder)
+        return False
+    found = False
+    for file in os.listdir(placeholder):
+        if fnmatch.fnmatch(file, 'setuptools*.egg-info'):
+            found = True
+            break
+    if not found:
+        log.warn('Could not locate setuptools*.egg-info')
+        return
+
+    log.warn('Moving elements out of the way...')
+    pkg_info = os.path.join(placeholder, file)
+    if os.path.isdir(pkg_info):
+        patched = _patch_egg_dir(pkg_info)
+    else:
+        patched = _patch_file(pkg_info, SETUPTOOLS_PKG_INFO)
+
+    if not patched:
+        log.warn('%s already patched.', pkg_info)
+        return False
+    # now let's move the files out of the way
+    for element in ('setuptools', 'pkg_resources.py', 'site.py'):
+        element = os.path.join(placeholder, element)
+        if os.path.exists(element):
+            _rename_path(element)
+        else:
+            log.warn('Could not find the %s element of the '
+                     'Setuptools distribution', element)
+    return True
+
+_remove_flat_installation = _no_sandbox(_remove_flat_installation)
+
+
+def _after_install(dist):
+    log.warn('After install bootstrap.')
+    placeholder = dist.get_command_obj('install').install_purelib
+    _create_fake_setuptools_pkg_info(placeholder)
+
+
+def _create_fake_setuptools_pkg_info(placeholder):
+    if not placeholder or not os.path.exists(placeholder):
+        log.warn('Could not find the install location')
+        return
+    pyver = '%s.%s' % (sys.version_info[0], sys.version_info[1])
+    setuptools_file = 'setuptools-%s-py%s.egg-info' % \
+            (SETUPTOOLS_FAKED_VERSION, pyver)
+    pkg_info = os.path.join(placeholder, setuptools_file)
+    if os.path.exists(pkg_info):
+        log.warn('%s already exists', pkg_info)
+        return
+
+    log.warn('Creating %s', pkg_info)
+    try:
+        f = open(pkg_info, 'w')
+    except EnvironmentError:
+        log.warn("Don't have permissions to write %s, skipping", pkg_info)
+        return
+    try:
+        f.write(SETUPTOOLS_PKG_INFO)
+    finally:
+        f.close()
+
+    pth_file = os.path.join(placeholder, 'setuptools.pth')
+    log.warn('Creating %s', pth_file)
+    f = open(pth_file, 'w')
+    try:
+        f.write(os.path.join(os.curdir, setuptools_file))
+    finally:
+        f.close()
+
+_create_fake_setuptools_pkg_info = _no_sandbox(
+    _create_fake_setuptools_pkg_info
+)
+
+
+def _patch_egg_dir(path):
+    # let's check if it's already patched
+    pkg_info = os.path.join(path, 'EGG-INFO', 'PKG-INFO')
+    if os.path.exists(pkg_info):
+        if _same_content(pkg_info, SETUPTOOLS_PKG_INFO):
+            log.warn('%s already patched.', pkg_info)
+            return False
+    _rename_path(path)
+    os.mkdir(path)
+    os.mkdir(os.path.join(path, 'EGG-INFO'))
+    pkg_info = os.path.join(path, 'EGG-INFO', 'PKG-INFO')
+    f = open(pkg_info, 'w')
+    try:
+        f.write(SETUPTOOLS_PKG_INFO)
+    finally:
+        f.close()
+    return True
+
+_patch_egg_dir = _no_sandbox(_patch_egg_dir)
+
+
+def _before_install():
+    log.warn('Before install bootstrap.')
+    _fake_setuptools()
+
+
+def _under_prefix(location):
+    if 'install' not in sys.argv:
+        return True
+    args = sys.argv[sys.argv.index('install') + 1:]
+    for index, arg in enumerate(args):
+        for option in ('--root', '--prefix'):
+            if arg.startswith('%s=' % option):
+                top_dir = arg.split('root=')[-1]
+                return location.startswith(top_dir)
+            elif arg == option:
+                if len(args) > index:
+                    top_dir = args[index + 1]
+                    return location.startswith(top_dir)
+        if arg == '--user' and USER_SITE is not None:
+            return location.startswith(USER_SITE)
+    return True
+
+
+def _fake_setuptools():
+    log.warn('Scanning installed packages')
+    try:
+        import pkg_resources
+    except ImportError:
+        # we're cool
+        log.warn('Setuptools or Distribute does not seem to be installed.')
+        return
+    ws = pkg_resources.working_set
+    try:
+        setuptools_dist = ws.find(
+            pkg_resources.Requirement.parse('setuptools', replacement=False)
+            )
+    except TypeError:
+        # old distribute API
+        setuptools_dist = ws.find(
+            pkg_resources.Requirement.parse('setuptools')
+        )
+
+    if setuptools_dist is None:
+        log.warn('No setuptools distribution found')
+        return
+    # detecting if it was already faked
+    setuptools_location = setuptools_dist.location
+    log.warn('Setuptools installation detected at %s', setuptools_location)
+
+    # if --root or --preix was provided, and if
+    # setuptools is not located in them, we don't patch it
+    if not _under_prefix(setuptools_location):
+        log.warn('Not patching, --root or --prefix is installing Distribute'
+                 ' in another location')
+        return
+
+    # let's see if its an egg
+    if not setuptools_location.endswith('.egg'):
+        log.warn('Non-egg installation')
+        res = _remove_flat_installation(setuptools_location)
+        if not res:
+            return
+    else:
+        log.warn('Egg installation')
+        pkg_info = os.path.join(setuptools_location, 'EGG-INFO', 'PKG-INFO')
+        if (os.path.exists(pkg_info) and
+            _same_content(pkg_info, SETUPTOOLS_PKG_INFO)):
+            log.warn('Already patched.')
+            return
+        log.warn('Patching...')
+        # let's create a fake egg replacing setuptools one
+        res = _patch_egg_dir(setuptools_location)
+        if not res:
+            return
+    log.warn('Patching complete.')
+    _relaunch()
+
+
+def _relaunch():
+    log.warn('Relaunching...')
+    # we have to relaunch the process
+    # pip marker to avoid a relaunch bug
+    _cmd1 = ['-c', 'install', '--single-version-externally-managed']
+    _cmd2 = ['-c', 'install', '--record']
+    if sys.argv[:3] == _cmd1 or sys.argv[:3] == _cmd2:
+        sys.argv[0] = 'setup.py'
+    args = [sys.executable] + sys.argv
+    sys.exit(subprocess.call(args))
+
+
+def _extractall(self, path=".", members=None):
+    """Extract all members from the archive to the current working
+       directory and set owner, modification time and permissions on
+       directories afterwards. `path' specifies a different directory
+       to extract to. `members' is optional and must be a subset of the
+       list returned by getmembers().
+    """
+    import copy
+    import operator
+    from tarfile import ExtractError
+    directories = []
+
+    if members is None:
+        members = self
+
+    for tarinfo in members:
+        if tarinfo.isdir():
+            # Extract directories with a safe mode.
+            directories.append(tarinfo)
+            tarinfo = copy.copy(tarinfo)
+            tarinfo.mode = 448  # decimal for oct 0700
+        self.extract(tarinfo, path)
+
+    # Reverse sort directories.
+    if sys.version_info < (2, 4):
+        def sorter(dir1, dir2):
+            return cmp(dir1.name, dir2.name)
+        directories.sort(sorter)
+        directories.reverse()
+    else:
+        directories.sort(key=operator.attrgetter('name'), reverse=True)
+
+    # Set correct owner, mtime and filemode on directories.
+    for tarinfo in directories:
+        dirpath = os.path.join(path, tarinfo.name)
+        try:
+            self.chown(tarinfo, dirpath)
+            self.utime(tarinfo, dirpath)
+            self.chmod(tarinfo, dirpath)
+        except ExtractError:
+            e = sys.exc_info()[1]
+            if self.errorlevel > 1:
+                raise
+            else:
+                self._dbg(1, "tarfile: %s" % e)
+
+
+def _build_install_args(options):
+    """
+    Build the arguments to 'python setup.py install' on the distribute package
+    """
+    install_args = []
+    if options.user_install:
+        if sys.version_info < (2, 6):
+            log.warn("--user requires Python 2.6 or later")
+            raise SystemExit(1)
+        install_args.append('--user')
+    return install_args
+
+def _parse_args():
+    """
+    Parse the command line for options
+    """
+    parser = optparse.OptionParser()
+    parser.add_option(
+        '--user', dest='user_install', action='store_true', default=False,
+        help='install in user site package (requires Python 2.6 or later)')
+    parser.add_option(
+        '--download-base', dest='download_base', metavar="URL",
+        default=DEFAULT_URL,
+        help='alternative URL from where to download the distribute package')
+    options, args = parser.parse_args()
+    # positional arguments are ignored
+    return options
+
+def main(version=DEFAULT_VERSION):
+    """Install or upgrade setuptools and EasyInstall"""
+    options = _parse_args()
+    tarball = download_setuptools(download_base=options.download_base)
+    return _install(tarball, _build_install_args(options))
+
+if __name__ == '__main__':
+    sys.exit(main())
 
=== removed file 'ez_setup.py'
--- ez_setup.py	2009-03-24 17:31:47 +0000
+++ ez_setup.py	1970-01-01 00:00:00 +0000
@@ -1,241 +0,0 @@
-#!python
-"""Bootstrap setuptools installation
-
-If you want to use setuptools in your package's setup.py, just include this
-file in the same directory with it, and add this to the top of your setup.py::
-
-    from ez_setup import use_setuptools
-    use_setuptools()
-
-If you want to require a specific version of setuptools, set a download
-mirror, or use an alternate download directory, you can do so by supplying
-the appropriate options to ``use_setuptools()``.
-
-This file can also be run as a script to install or upgrade setuptools.
-"""
-import sys
-DEFAULT_VERSION = "0.6c8"
-DEFAULT_URL     = "http://pypi.python.org/packages/%s/s/setuptools/" % sys.version[:3]
-
-md5_data = {
-    'setuptools-0.6b1-py2.3.egg': '8822caf901250d848b996b7f25c6e6ca',
-    'setuptools-0.6b1-py2.4.egg': 'b79a8a403e4502fbb85ee3f1941735cb',
-    'setuptools-0.6b2-py2.3.egg': '5657759d8a6d8fc44070a9d07272d99b',
-    'setuptools-0.6b2-py2.4.egg': '4996a8d169d2be661fa32a6e52e4f82a',
-    'setuptools-0.6b3-py2.3.egg': 'bb31c0fc7399a63579975cad9f5a0618',
-    'setuptools-0.6b3-py2.4.egg': '38a8c6b3d6ecd22247f179f7da669fac',
-    'setuptools-0.6b4-py2.3.egg': '62045a24ed4e1ebc77fe039aa4e6f7e5',
-    'setuptools-0.6b4-py2.4.egg': '4cb2a185d228dacffb2d17f103b3b1c4',
-    'setuptools-0.6c1-py2.3.egg': 'b3f2b5539d65cb7f74ad79127f1a908c',
-    'setuptools-0.6c1-py2.4.egg': 'b45adeda0667d2d2ffe14009364f2a4b',
-    'setuptools-0.6c2-py2.3.egg': 'f0064bf6aa2b7d0f3ba0b43f20817c27',
-    'setuptools-0.6c2-py2.4.egg': '616192eec35f47e8ea16cd6a122b7277',
-    'setuptools-0.6c3-py2.3.egg': 'f181fa125dfe85a259c9cd6f1d7b78fa',
-    'setuptools-0.6c3-py2.4.egg': 'e0ed74682c998bfb73bf803a50e7b71e',
-    'setuptools-0.6c3-py2.5.egg': 'abef16fdd61955514841c7c6bd98965e',
-    'setuptools-0.6c4-py2.3.egg': 'b0b9131acab32022bfac7f44c5d7971f',
-    'setuptools-0.6c4-py2.4.egg': '2a1f9656d4fbf3c97bf946c0a124e6e2',
-    'setuptools-0.6c4-py2.5.egg': '8f5a052e32cdb9c72bcf4b5526f28afc',
-    'setuptools-0.6c5-py2.3.egg': 'ee9fd80965da04f2f3e6b3576e9d8167',
-    'setuptools-0.6c5-py2.4.egg': 'afe2adf1c01701ee841761f5bcd8aa64',
-    'setuptools-0.6c5-py2.5.egg': 'a8d3f61494ccaa8714dfed37bccd3d5d',
-    'setuptools-0.6c6-py2.3.egg': '35686b78116a668847237b69d549ec20',
-    'setuptools-0.6c6-py2.4.egg': '3c56af57be3225019260a644430065ab',
-    'setuptools-0.6c6-py2.5.egg': 'b2f8a7520709a5b34f80946de5f02f53',
-    'setuptools-0.6c7-py2.3.egg': '209fdf9adc3a615e5115b725658e13e2',
-    'setuptools-0.6c7-py2.4.egg': '5a8f954807d46a0fb67cf1f26c55a82e',
-    'setuptools-0.6c7-py2.5.egg': '45d2ad28f9750e7434111fde831e8372',
-    'setuptools-0.6c8-py2.3.egg': '50759d29b349db8cfd807ba8303f1902',
-    'setuptools-0.6c8-py2.4.egg': 'cba38d74f7d483c06e9daa6070cce6de',
-    'setuptools-0.6c8-py2.5.egg': '1721747ee329dc150590a58b3e1ac95b',
-}
-
-import sys, os
-
-def _validate_md5(egg_name, data):
-    if egg_name in md5_data:
-        from md5 import md5
-        digest = md5(data).hexdigest()
-        if digest != md5_data[egg_name]:
-            print >>sys.stderr, (
-                "md5 validation of %s failed!  (Possible download problem?)"
-                % egg_name
-            )
-            sys.exit(2)
-    return data
-
-
-def use_setuptools(
-    version=DEFAULT_VERSION, download_base=DEFAULT_URL, to_dir=os.curdir,
-    download_delay=15, min_version=None
-):
-    """Automatically find/download setuptools and make it available on sys.path
-
-    `version` should be a valid setuptools version number that is available
-    as an egg for download under the `download_base` URL (which should end with
-    a '/').  `to_dir` is the directory where setuptools will be downloaded, if
-    it is not already available.  If `download_delay` is specified, it should
-    be the number of seconds that will be paused before initiating a download,
-    should one be required.  If an older version of setuptools is installed,
-    this routine will print a message to ``sys.stderr`` and raise SystemExit in
-    an attempt to abort the calling script.
-    """
-    # Work around a hack in the ez_setup.py file from simplejson==1.7.3.
-    if min_version:
-        version = min_version
-
-    was_imported = 'pkg_resources' in sys.modules or 'setuptools' in sys.modules
-    def do_download():
-        egg = download_setuptools(version, download_base, to_dir, download_delay)
-        sys.path.insert(0, egg)
-        import setuptools; setuptools.bootstrap_install_from = egg
-    try:
-        import pkg_resources
-    except ImportError:
-        return do_download()       
-    try:
-        pkg_resources.require("setuptools>="+version); return
-    except pkg_resources.VersionConflict, e:
-        if was_imported:
-            print >>sys.stderr, (
-            "The required version of setuptools (>=%s) is not available, and\n"
-            "can't be installed while this script is running. Please install\n"
-            " a more recent version first, using 'easy_install -U setuptools'."
-            "\n\n(Currently using %r)"
-            ) % (version, e.args[0])
-            sys.exit(2)
-        else:
-            del pkg_resources, sys.modules['pkg_resources']    # reload ok
-            return do_download()
-    except pkg_resources.DistributionNotFound:
-        return do_download()
-
-def download_setuptools(
-    version=DEFAULT_VERSION, download_base=DEFAULT_URL, to_dir=os.curdir,
-    delay = 15
-):
-    """Download setuptools from a specified location and return its filename
-
-    `version` should be a valid setuptools version number that is available
-    as an egg for download under the `download_base` URL (which should end
-    with a '/'). `to_dir` is the directory where the egg will be downloaded.
-    `delay` is the number of seconds to pause before an actual download attempt.
-    """
-    import urllib2, shutil
-    egg_name = "setuptools-%s-py%s.egg" % (version,sys.version[:3])
-    url = download_base + egg_name
-    saveto = os.path.join(to_dir, egg_name)
-    src = dst = None
-    if not os.path.exists(saveto):  # Avoid repeated downloads
-        try:
-            from distutils import log
-            if delay:
-                log.warn("""
----------------------------------------------------------------------------
-This script requires setuptools version %s to run (even to display
-help).  I will attempt to download it for you (from
-%s), but
-you may need to enable firewall access for this script first.
-I will start the download in %d seconds.
-
-(Note: if this machine does not have network access, please obtain the file
-
-   %s
-
-and place it in this directory before rerunning this script.)
----------------------------------------------------------------------------""",
-                    version, download_base, delay, url
-                ); from time import sleep; sleep(delay)
-            log.warn("Downloading %s", url)
-            src = urllib2.urlopen(url)
-            # Read/write all in one block, so we don't create a corrupt file
-            # if the download is interrupted.
-            data = _validate_md5(egg_name, src.read())
-            dst = open(saveto,"wb"); dst.write(data)
-        finally:
-            if src: src.close()
-            if dst: dst.close()
-    return os.path.realpath(saveto)
-
-def main(argv, version=DEFAULT_VERSION):
-    """Install or upgrade setuptools and EasyInstall"""
-    try:
-        import setuptools
-    except ImportError:
-        egg = None
-        try:
-            egg = download_setuptools(version, delay=0)
-            sys.path.insert(0,egg)
-            from setuptools.command.easy_install import main
-            return main(list(argv)+[egg])   # we're done here
-        finally:
-            if egg and os.path.exists(egg):
-                os.unlink(egg)
-    else:
-        if setuptools.__version__ == '0.0.1':
-            print >>sys.stderr, (
-            "You have an obsolete version of setuptools installed.  Please\n"
-            "remove it from your system entirely before rerunning this script."
-            )
-            sys.exit(2)
-
-    req = "setuptools>="+version
-    import pkg_resources
-    try:
-        pkg_resources.require(req)
-    except pkg_resources.VersionConflict:
-        try:
-            from setuptools.command.easy_install import main
-        except ImportError:
-            from easy_install import main
-        main(list(argv)+[download_setuptools(delay=0)])
-        sys.exit(0) # try to force an exit
-    else:
-        if argv:
-            from setuptools.command.easy_install import main
-            main(argv)
-        else:
-            print "Setuptools version",version,"or greater has been installed."
-            print '(Run "ez_setup.py -U setuptools" to reinstall or upgrade.)'
-
-def update_md5(filenames):
-    """Update our built-in md5 registry"""
-
-    import re
-    from md5 import md5
-
-    for name in filenames:
-        base = os.path.basename(name)
-        f = open(name,'rb')
-        md5_data[base] = md5(f.read()).hexdigest()
-        f.close()
-
-    data = ["    %r: %r,\n" % it for it in md5_data.items()]
-    data.sort()
-    repl = "".join(data)
-
-    import inspect
-    srcfile = inspect.getsourcefile(sys.modules[__name__])
-    f = open(srcfile, 'rb'); src = f.read(); f.close()
-
-    match = re.search("\nmd5_data = {\n([^}]+)}", src)
-    if not match:
-        print >>sys.stderr, "Internal error!"
-        sys.exit(2)
-
-    src = src[:match.start(1)] + repl + src[match.end(1):]
-    f = open(srcfile,'w')
-    f.write(src)
-    f.close()
-
-
-if __name__=='__main__':
-    if len(sys.argv)>2 and sys.argv[1]=='--md5update':
-        update_md5(sys.argv[2:])
-    else:
-        main(sys.argv[1:])
-
-
-
-
-
 
=== renamed directory 'src/lazr' => 'lazr'
=== modified file 'lazr/__init__.py'
--- src/lazr/__init__.py	2009-03-24 17:31:47 +0000
+++ lazr/__init__.py	2013-01-10 15:47:20 +0000
@@ -1,4 +1,4 @@
-# Copyright 2008-2009 Canonical Ltd.  All rights reserved.
+# Copyright 2008-2013 Canonical Ltd.  All rights reserved.
 #
 # This file is part of lazr.config.
 #
@@ -14,10 +14,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with lazr.config.  If not, see <http://www.gnu.org/licenses/>.
 
-# this is a namespace package
-try:
-    import pkg_resources
-    pkg_resources.declare_namespace(__name__)
-except ImportError:
-    import pkgutil
-    __path__ = pkgutil.extend_path(__path__, __name__)
+# This is a namespace package, however under >= Python 3.3, let it be a true
+# namespace package (i.e. this cruft isn't necessary).
+import sys
+
+if sys.hexversion < 0x30300f0:
+    try:
+        import pkg_resources
+        pkg_resources.declare_namespace(__name__)
+    except ImportError:
+        import pkgutil
+        __path__ = pkgutil.extend_path(__path__, __name__)
 
=== modified file 'lazr/config/__init__.py'
--- src/lazr/config/__init__.py	2009-08-25 13:46:10 +0000
+++ lazr/config/__init__.py	2013-01-10 15:47:20 +0000
@@ -17,7 +17,8 @@
 """A configuration file system."""
 
 import pkg_resources
-__version__ = pkg_resources.resource_string("lazr.config", "version.txt").strip()
+__version__ = pkg_resources.resource_string(
+    "lazr.config", "version.txt").strip()
 
 # Re-export in such a way that __version__ can still be imported if
 # dependencies are not yet available.
 
=== modified file 'lazr/config/_config.py'
--- src/lazr/config/_config.py	2009-03-24 17:31:47 +0000
+++ lazr/config/_config.py	2013-01-10 15:47:20 +0000
@@ -1,4 +1,4 @@
-# Copyright 2008-2009 Canonical Ltd.  All rights reserved.
+# Copyright 2008-2013 Canonical Ltd.  All rights reserved.
 #
 # This file is part of lazr.config.
 #
@@ -16,8 +16,9 @@
 
 """Implementation classes for config."""
 
+from __future__ import absolute_import, print_function, unicode_literals
+
 __metaclass__ = type
-
 __all__ = [
     'Config',
     'ConfigData',
@@ -34,7 +35,6 @@
     ]
 
 
-import StringIO
 import datetime
 import grp
 import logging
@@ -42,35 +42,39 @@
 import pwd
 import re
 
-from ConfigParser import NoSectionError, RawConfigParser
 from os.path import abspath, basename, dirname
 from textwrap import dedent
 
-from zope.interface import implements
+try:
+    from io import StringIO
+    from configparser import NoSectionError, RawConfigParser
+except ImportError:
+    # Python 2.
+    from StringIO import StringIO
+    from ConfigParser import NoSectionError, RawConfigParser
+
+
+from zope.interface import implementer
 
 from lazr.config.interfaces import (
     ConfigErrors, ICategory, IConfigData, IConfigLoader, IConfigSchema,
     InvalidSectionNameError, ISection, ISectionSchema, IStackableConfig,
     NoCategoryError, NoConfigError, RedefinedSectionError, UnknownKeyError,
     UnknownSectionError)
-from lazr.delegates import delegates
+from lazr.delegates import delegate_to
 
 _missing = object()
 
 
 def read_content(filename):
     """Return the content of a file at filename as a string."""
-    source_file = open(filename, 'r')
-    try:
-        raw_data = source_file.read()
-    finally:
-        source_file.close()
-    return raw_data
-
-
+    with open(filename, 'rt') as fp:
+        return fp.read()
+
+
+@implementer(ISectionSchema)
 class SectionSchema:
     """See `ISectionSchema`."""
-    implements(ISectionSchema)
 
     def __init__(self, name, options, is_optional=False, is_master=False):
         """Create an `ISectionSchema` from the name and options.
@@ -89,7 +93,8 @@
 
     def __iter__(self):
         """See `ISectionSchema`"""
-        return self._options.iterkeys()
+        for key in self._options.keys():
+            yield key
 
     def __contains__(self, name):
         """See `ISectionSchema`"""
@@ -113,12 +118,11 @@
                               self.optional, self.master)
 
 
+@delegate_to(ISectionSchema, context='schema')
+@implementer(ISection)
 class Section:
     """See `ISection`."""
 
-    implements(ISection)
-    delegates(ISectionSchema, context='schema')
-
     def __init__(self, schema, _options=None):
         """Create an `ISection` from schema.
 
@@ -223,9 +227,9 @@
         return self._convert(value)
 
 
+@implementer(IConfigSchema, IConfigLoader)
 class ConfigSchema:
     """See `IConfigSchema`."""
-    implements(IConfigSchema, IConfigLoader)
 
     _section_factory = Section
 
@@ -267,7 +271,7 @@
         """
         raw_schema = read_content(filename)
         # Verify that the string is ascii.
-        raw_schema.encode('ascii', 'ignore')
+        raw_schema.encode('ascii', 'strict')
         # Verify that no sections are redefined.
         section_names = []
         for section_name in re.findall(r'^\s*\[[^\]]+\]', raw_schema, re.M):
@@ -275,7 +279,7 @@
                 raise RedefinedSectionError(section_name)
             else:
                 section_names.append(section_name)
-        return StringIO.StringIO(raw_schema)
+        return StringIO(raw_schema)
 
     def _setSectionSchemasAndCategoryNames(self, parser):
         """Set the SectionSchemas and category_names from the config."""
@@ -301,7 +305,7 @@
                 section_name, options, is_optional, is_master)
             if category_name is not None:
                 category_names.add(category_name)
-        self._category_names = list(category_names)
+        self._category_names = sorted(category_names)
 
     _section_name_pattern = re.compile(r'\w[\w.-]+\w')
 
@@ -355,7 +359,8 @@
 
     def __iter__(self):
         """See `IConfigSchema`."""
-        return self._section_schemas.itervalues()
+        for value in self._section_schemas.values():
+            yield value
 
     def __contains__(self, name):
         """See `IConfigSchema`."""
@@ -423,9 +428,9 @@
     _section_factory = ImplicitTypeSection
 
 
+@implementer(IConfigData)
 class ConfigData:
     """See `IConfigData`."""
-    implements(IConfigData)
 
     def __init__(self, filename, sections, extends=None, errors=None):
         """Set the configuration data."""
@@ -456,7 +461,8 @@
 
     def __iter__(self):
         """See `IConfigData`."""
-        return self._sections.itervalues()
+        for value in self._sections.values():
+            yield value
 
     def __contains__(self, name):
         """See `IConfigData`."""
@@ -484,12 +490,12 @@
         return sections
 
 
+@delegate_to(IConfigData, context='data')
+@implementer(IStackableConfig)
 class Config:
     """See `IStackableConfig`."""
     # LAZR config classes may access ConfigData private data.
     # pylint: disable-msg=W0212
-    implements(IStackableConfig)
-    delegates(IConfigData, context='data')
 
     def __init__(self, schema):
         """Set the schema and configuration."""
@@ -567,7 +573,7 @@
             confs = []
         encoding_errors = self._verifyEncoding(conf_data)
         parser = RawConfigParser()
-        parser.readfp(StringIO.StringIO(conf_data), conf_filename)
+        parser.readfp(StringIO(conf_data), conf_filename)
         confs.append((conf_filename, parser, encoding_errors))
         if parser.has_option('meta', 'extends'):
             base_path = dirname(conf_filename)
@@ -660,8 +666,11 @@
         """
         errors = []
         try:
-            config_data.encode('ascii', 'ignore')
-        except UnicodeDecodeError, error:
+            if isinstance(config_data, bytes):
+                config_data.decode('ascii', 'strict')
+            else:
+                config_data.encode('ascii', 'strict')
+        except UnicodeError as error:
             errors.append(error)
         return errors
 
@@ -706,9 +715,9 @@
         raise NoConfigError('No config with name: %s.' % conf_name)
 
 
+@implementer(ICategory)
 class Category:
     """See `ICategory`."""
-    implements(ICategory)
 
     def __init__(self, name, sections):
         """Initialize the Category its name and a list of sections."""
@@ -786,12 +795,8 @@
     return user, group
 
 
-def _sort_order(a, b):
-    """Sort timedelta suffixes from greatest to least."""
-    if len(a) == 0:
-        return -1
-    if len(b) == 0:
-        return 1
+def _sortkey(item):
+    """Return a value that sorted(..., key=_sortkey) can use."""
     order = dict(
         w=0,    # weeks
         d=1,    # days
@@ -799,20 +804,14 @@
         m=3,    # minutes
         s=4,    # seconds
         )
-    suffix_a = order.get(a[-1])
-    suffix_b = order.get(b[-1])
-    if suffix_a is None or suffix_b is None:
-        raise ValueError
-    return cmp(suffix_a, suffix_b)
-
+    return order.get(item[-1])
 
 def as_timedelta(value):
     """Convert a value string to the equivalent timedeta."""
     # Technically, the regex will match multiple decimal points in the
     # left-hand side, but that's okay because the float/int conversion below
     # will properly complain if there's more than one dot.
-    components = sorted(re.findall(r'([\d.]+[smhdw])', value),
-                        cmp=_sort_order)
+    components = sorted(re.findall(r'([\d.]+[smhdw])', value), key=_sortkey)
     # Complain if the components are out of order.
     if ''.join(components) != value:
         raise ValueError
 
=== added directory 'lazr/config/docs'
=== renamed file 'src/lazr/config/CHANGES.txt' => 'lazr/config/docs/NEWS.rst'
--- src/lazr/config/CHANGES.txt	2009-03-24 17:31:47 +0000
+++ lazr/config/docs/NEWS.rst	2013-01-10 15:47:20 +0000
@@ -2,6 +2,23 @@
 Changes
 =======
 
+
+2.0 (2013-01-06)
+================
+- Ported to Python 3.
+
+
+1.1.3 (2009-08-25)
+==================
+
+- Fixed a build problem.
+
+1.1.2 (2009-08-25)
+==================
+
+- Got rid of a sys.path hack.
+
+
 1.1.1 (2009-03-24)
 ==================
 
 
=== added file 'lazr/config/docs/__init__.py'
=== added file 'lazr/config/docs/fixture.py'
--- lazr/config/docs/fixture.py	1970-01-01 00:00:00 +0000
+++ lazr/config/docs/fixture.py	2013-01-10 15:47:20 +0000
@@ -0,0 +1,34 @@
+# Copyright 2009-2013 Canonical Ltd.  All rights reserved.
+#
+# This file is part of lazr.smtptest
+#
+# lazr.smtptest 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, version 3 of the License.
+#
+# lazr.smtptest 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 lazr.smtptest.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Doctest fixtures for running under nose."""
+
+from __future__ import absolute_import, print_function, unicode_literals
+
+__metaclass__ = type
+__all__ = [
+    'globs',
+    ]
+
+
+def globs(globs):
+    """Set up globals for doctests."""
+    # Enable future statements to make Python 2 act more like Python 3.
+    globs['absolute_import'] = absolute_import
+    globs['print_function'] = print_function
+    globs['unicode_literals'] = unicode_literals
+    # Provide a convenient way to clean things up at the end of the test.
+    return globs
 
=== renamed file 'src/lazr/config/README.txt' => 'lazr/config/docs/usage.rst'
--- src/lazr/config/README.txt	2009-03-24 17:36:13 +0000
+++ lazr/config/docs/usage.rst	2013-01-10 15:47:20 +0000
@@ -1,60 +1,40 @@
-..
-    This file is part of lazr.config.
-
-    lazr.config 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, version 3 of the License.
-
-    lazr.config 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 lazr.config.  If not, see <http://www.gnu.org/licenses/>.
-
+===========
 LAZR config
-***********
+===========
 
 The LAZR config system is typically used to manage process configuration.
-Process configuration is for saying how things change when we run
-systems on different machines, or under different circumstances.
-
-This system uses ini-like file format of section, keys, and values.
-The config file supports inheritance to minimize duplication of
-information across files. The format supports schema validation.
-
-
-============
+Process configuration is for saying how things change when we run systems on
+different machines, or under different circumstances.
+
+This system uses ini-like file format of section, keys, and values.  The
+config file supports inheritance to minimize duplication of information across
+files. The format supports schema validation.
+
+
 ConfigSchema
 ============
 
-A schema is loaded by instantiating the ConfigSchema class with
-the path to a configuration file. The schema is explicitly derived from
-the information in the configuration file.
-
-    >>> from os import path
-    >>> from zope.interface.verify import verifyObject
-    >>> from lazr.config import ConfigSchema
-    >>> from lazr.config.interfaces import IConfigSchema
-
-    >>> import lazr.config
-    >>> testfiles_dir = path.normpath(path.join(
-    ...     path.dirname(lazr.config.__file__), 'tests', 'testdata'))
-    >>> base_conf = path.join(testfiles_dir, 'base.conf')
-
-The config file contains sections enclosed in square brackets ([]).
-The section name may be divided into major and minor categories using a
-dot (.). Beneath each section is a list of key-value pairs, separated
-by a colon (:). Multiple sections with the same major category may have
-their keys defined in another section that appends the '.template'
-suffix to the category name. A section with '.optional' suffix is not
-required. Lines that start with a hash (#) are comments.
-
-    >>> schema_file = open(base_conf, 'r')
-    >>> raw_schema = schema_file.read()
-    >>> schema_file.close()
-    >>> print raw_schema
+A schema is loaded by instantiating the ConfigSchema class with the path to a
+configuration file. The schema is explicitly derived from the information in
+the configuration file.
+
+    >>> from pkg_resources import resource_string
+    >>> raw_schema = resource_string('lazr.config.tests.testdata', 'base.conf')
+
+The config file contains sections enclosed in square brackets
+(e.g. ``[section]``).  The section name may be divided into major and minor
+categories using a dot (``.``).  Beneath each section is a list of key-value
+pairs, separated by a colon (``:``).
+
+Multiple sections with the same major category may have their keys defined in
+another section that appends the ``.template`` suffix to the category name.
+
+A section with ``.optional`` suffix is not required.  Lines that start with a
+hash (``#``) are comments.
+
+    >>> from pkg_resources import resource_string
+    >>> raw_schema = resource_string('lazr.config.tests.testdata', 'base.conf')
+    >>> print(raw_schema.decode('utf-8'))
     # This section defines required keys and default values.
     [section_1]
     key1: foo
@@ -86,36 +66,46 @@
     key2: multiline value 1
        multiline value 2
 
+To create the schema, provide a file name.
+
+    >>> from lazr.config import ConfigSchema
+    >>> from lazr.config.interfaces import IConfigSchema
+    >>> from pkg_resources import resource_filename
+    >>> from zope.interface.verify import verifyObject
+    >>> base_conf = resource_filename(
+    ...     'lazr.config.tests.testdata', 'base.conf')
     >>> schema = ConfigSchema(base_conf)
     >>> verifyObject(IConfigSchema, schema)
     True
 
-    >>> schema.name
-    'base.conf'
-    >>> schema.filename
-    '...lazr/config/tests/testdata/base.conf'
+The schema has a name and a file name.
+
+    >>> print(schema.name)
+    base.conf
+    >>> print('file:', schema.filename)
+    file: ...lazr/config/tests/testdata/base.conf
 
 If you provide an optional file-like object as a second argument to the
 constructor, that is used instead of opening the named file implicitly.
 
-    >>> file_object = open(base_conf)
-    >>> other_schema = ConfigSchema('/does/not/exist.conf', file_object)
+    >>> with open(base_conf, 'r') as file_object:
+    ...     other_schema = ConfigSchema('/does/not/exist.conf', file_object)
     >>> verifyObject(IConfigSchema, other_schema)
     True
 
-    >>> print other_schema.name
+For such schemas, the file name is taken from the first argument.
+
+    >>> print(other_schema.name)
     exist.conf
-    >>> print other_schema.filename
+    >>> print(other_schema.filename)
     /does/not/exist.conf
 
-    >>> file_object.close()
-
 A schema is made up of multiple SchemaSections. They can be iterated
 over in a loop as needed.
 
     >>> from operator import attrgetter
     >>> for section_schema in sorted(schema, key=attrgetter('name')):
-    ...     print section_schema.name
+    ...     print(section_schema.name)
     section-2.app-b
     section-5
     section_1
@@ -124,7 +114,7 @@
     section_33
 
     >>> for section_schema in sorted(other_schema, key=attrgetter('name')):
-    ...     print section_schema.name
+    ...     print(section_schema.name)
     section-2.app-b
     section-5
     section_1
@@ -140,78 +130,69 @@
     >>> 'section-4' in schema
     False
 
-A SectionSchema can be retrieved from the schema using the []
-operator
+A SectionSchema can be retrieved from the schema using the ``[]`` operator.
 
     >>> section_schema_1 = schema['section_1']
-    >>> section_schema_1.name
-    'section_1'
-
-A SectionNotFound error is raised if the name does not match any of the
-SectionSchemas.
-
-    >>> section_schema_app_a = schema['section_3.app_a']
-    >>> schema['section-4']
-    Traceback (most recent call last):
-      ...
-    NoSectionError: ...
-
-Processes often require resources like databases or vhosts that have a
-common category of keys. The list of all category names can be retrieved
-via the categories attribute.
-
-    >>> schema.category_names
-    ['section_3', 'section-2']
+    >>> print(section_schema_1.name)
+    section_1
+
+Processes often require resources like databases or virtual hosts that have a
+common category of keys.  The list of all category names can be retrieved via
+the categories attribute.
+
+    >>> for name in schema.category_names:
+    ...     print(name)
+    section-2
+    section_3
 
 The list of SchemaSections that share common category can be retrieved
-using getByCategory().
+using ``getByCategory()``.
 
     >>> all_section_3 = schema.getByCategory('section_3')
     >>> for section_schema in sorted(all_section_3, key=attrgetter('name')):
-    ...     print section_schema.name
+    ...     print(section_schema.name)
     section_3.app_a
     section_3.app_b
 
-An error is raised when accessing a category does not exist.
-
-    >>> schema.getByCategory('non-section')
-    Traceback (most recent call last):
-      ...
-    NoCategoryError: ...
-
-You can pass a default argument to getByCategory() to avoid the exception.
+You can pass a default argument to ``getByCategory()`` to avoid the exception.
 
     >>> missing = object()
     >>> schema.getByCategory('non-section', missing) is missing
     True
 
 
-=============
 SchemaSection
 =============
 
-A SchemaSection behaves similar to a dictionary. It has keys and
-values. Each SchemaSection has a name.
+A SchemaSection behaves similar to a dictionary.  It has keys and values.
 
     >>> from lazr.config.interfaces import ISectionSchema
     >>> section_schema_1 = schema['section_1']
     >>> verifyObject(ISectionSchema, section_schema_1)
     True
 
-    >>> section_schema_1.name
-    'section_1'
-
-A SchemaSection can return a 2-tuple of its category name and specific
-name parts. The category name will be None if the SchemaSection's name
-does not contain a category.
-
-    >>> schema['section_3.app_b'].category_and_section_names
-    ('section_3', 'app_b')
-
-    >>> section_schema_1.category_and_section_names
-    (None, 'section_1')
-
-Optional sections have the optional attribute set to True:
+Each SchemaSection has a name.
+
+    >>> print(section_schema_1.name)
+    section_1
+
+A SchemaSection can return a 2-tuple of its category name and specific name
+parts.
+
+    >>> for name in schema['section_3.app_b'].category_and_section_names:
+    ...     print(name)
+    section_3
+    app_b
+
+The category name will be ``None`` if the SchemaSection's name does not
+contain a category.
+
+    >>> for name in section_schema_1.category_and_section_names:
+    ...     print(name)
+    None
+    section_1
+
+Optional sections have the optional attribute set to ``True``:
 
     >>> section_schema_1.optional
     False
@@ -225,11 +206,11 @@
     >>> 'nonkey' in section_schema_1
     False
 
-A key can be accessed directly using as a subscript of the SchemaSection.
-The value is always a string.
+A key can be accessed directly using as a subscript of the SchemaSection.  The
+value is always a string.
 
-    >>> section_schema_1['key3']
-    'Launchpad&nbsp;rocks'
+    >>> print(section_schema_1['key3'])
+    Launchpad&nbsp;rocks
     >>> section_schema_1['key5']
     ''
 
@@ -240,29 +221,29 @@
       ...
     KeyError: ...
 
-In the conf file, '[section_1]' is a default section that defines keys
-and values. The values specified in the section schema will be used as
-default values if not overriden in the configuration. In the case of
-key5, the key had no explicit value, so the value is an empty string.
+In the conf file, ``[section_1]`` is a default section that defines keys and
+values.  The values specified in the section schema will be used as default
+values if not overridden in the configuration.  In the case of *key5*, the key
+had no explicit value, so the value is an empty string.
 
     >>> for key in sorted(section_schema_1):
-    ...     print key, ':', section_schema_1[key]
+    ...     print(key, ':', section_schema_1[key])
     key1 : foo
     key2 : bar and baz
     key3 : Launchpad&nbsp;rocks
     key4 : F&#028c;k yeah!
     key5 :
 
-In the conf file '[section_3.template]' defines a common set of keys and
-default values for '[section_3.app_a]' and '[section_3.app_b]'. When a
-section defines different keys and default values s from the template,
-the new data overlays the template data. This is the case for section
-'[section_3.app_b]'.
+In the conf file ``[section_3.template]`` defines a common set of keys and
+default values for ``[section_3.app_a]`` and ``[section_3.app_b]``.  When a
+section defines different keys and default values from the template, the new
+data overlays the template data.  This is the case for section
+``[section_3.app_b]``.
 
     >>> for section_schema in sorted(all_section_3, key=attrgetter('name')):
-    ...     print section_schema.name
+    ...     print(section_schema.name)
     ...     for key in sorted(section_schema):
-    ...         print key, ':', section_schema[key]
+    ...         print(key, ':', section_schema[key])
     section_3.app_a
     key1 : 17
     key2 : 3.1415
@@ -272,93 +253,45 @@
     key3 : unique
 
 
-=======================
 ConfigSchema validation
 =======================
 
-ConfigSchema will raise an error if the schema file cannot be opened.
-
-    >>> ConfigSchema("no-such-file")
-    Traceback (most recent call last):
-      ...
-    IOError: [Errno 2] No such file or directory: ...
-
-The schema parser is self-validating. It will check that the character
-encoding is ascii. It will check that the data is not ambiguous or
-self-contradicting.
-
-Schema files that contain non-ASCII characters raise a
-UnicodeDecodeError.
-
-    >>> ConfigSchema(path.join(testfiles_dir, 'bad-nonascii.conf'))
-    Traceback (most recent call last):
-      ...
-    UnicodeDecodeError: ...
-
-Keys without sections raise MissingSectionHeaderError.
-
-    >>> ConfigSchema(path.join(testfiles_dir, 'bad-sectionless.conf'))
-    Traceback (most recent call last):
-      ...
-    MissingSectionHeaderError: File contains no section headers. ...
-
-Redefining a section in a config file will raise a RedefinedSectionError.
-
-    >>> ConfigSchema(path.join(testfiles_dir, 'bad-redefined-section.conf'))
-    Traceback (most recent call last):
-      ...
-    RedefinedSectionError: ...
-
-# XXX sinzui 2007-12-13:
-# ConfigSchema should raise RedefinedKeyError when a section redefines
-# a key.
-
-Defining a section that belongs to many categories will raise
-a InvalidSectionNameError.
-
-    >>> ConfigSchema(path.join(testfiles_dir, 'bad-invalid-name.conf'))
-    Traceback (most recent call last):
-      ...
-    InvalidSectionNameError: [category.other_category.name.optional] ...
-
-As does using non word characters other than a dot or dash in the
-section name.
-
-    >>> ConfigSchema(path.join(testfiles_dir, 'bad-invalid-name-chars.conf'))
-    Traceback (most recent call last):
-      ...
-    InvalidSectionNameError: [$category.name_part.optional] ...
-
-
-=============
+The schema parser is self-validating.  It checks that the character encoding
+is ASCII, and that the data is not ambiguous or self-contradicting.  Keys must
+exist inside sections and section names may not be defined twice.  Sections
+may belong to only one category, and only letters, numbers, dots and dashes
+may be present in section names.
+
+.. For multilingual Python support reasons, we don't include testable examples
+   here.  See ``test_config.py`` and ``lazr/config/interfaces.py`` for details.
+
+
 IConfigLoader
 =============
 
-ConfigSchema implements the two methods in the IConfigLoader interface.
-A Config is created by a schema using either the load() or loadFile()
+ConfigSchema implements the two methods in the IConfigLoader interface.  A
+Config is created by a schema using either the ``load()`` or ``loadFile()``
 methods to return a Config instance.
 
     >>> from lazr.config.interfaces import IConfigLoader
     >>> verifyObject(IConfigLoader, schema)
     True
 
-The load() method accepts a filename.
+The ``load()`` method accepts a filename.
 
-    >>> local_conf = path.join(testfiles_dir,  'local.conf')
+    >>> local_conf = resource_filename(
+    ...     'lazr.config.tests.testdata', 'local.conf')
     >>> config = schema.load(local_conf)
 
-Passing a filename to a non-existent file will raise an IOError.
-
-    >>> schema.load("fnord.conf")
-    Traceback (most recent call last):
-      ...
-    IOError: [Errno 2] No such file or directory: 'fnord.conf'
-
-The loadFile method accepts a file-like object and an optional filename
-keyword arg. The filename arg must be passed if the file-like object
-does not have a name attribute.
-
-    >>> import StringIO
+The ``loadFile()`` method accepts a file-like object and an optional filename
+keyword argument.  The filename argument must be passed if the file-like
+object does not have a ``name`` attribute.
+
+    >>> try:
+    ...     from io import StringIO
+    ... except ImportError:
+    ...     # Python 2
+    ...     from StringIO import StringIO
     >>> bad_data = ("""
     ...     [meta]
     ...     metakey: unsupported
@@ -369,30 +302,24 @@
     ...     key1: bad character in caf\xc3)
     ...     [section_3.template]
     ...     key1: schema suffixes are not permitted""")
-    >>> schema.loadFile(StringIO.StringIO(bad_data))
-    Traceback (most recent call last):
-      ...
-    AttributeError: StringIO instance has no attribute 'name'
-
     >>> bad_config = schema.loadFile(
-    ...     StringIO.StringIO(bad_data), 'bad conf')
-
-The bad_config example will be used for validation tests.
-
-
-======
+    ...     StringIO(bad_data), 'bad conf')
+
+.. The bad_config example will be used for validation tests.
+
+
 Config
 ======
 
-The config represents the local configuration of the process on a
-system. It is validated with a schema. It extends the schema, or other
-conf files to define the specific differences from the extended files
-that are required to run the local processes.
+The config represents the local configuration of the process on a system.  It
+is validated with a schema.  It extends the schema, or other conf files, to
+define the specific differences from the extended files that are required to
+run the local processes.
 
-The object returned by load() provides both the IConfigData and
-IStackableConfig interfaces. IConfigData is for read-only access to the
-configuration data. A process configuration is made up of a stack of
-different IConfigData. The IStackableConfig interface provides the
+The object returned by ``load()`` provides both the ``IConfigData`` and
+``IStackableConfig`` interfaces.  ``IConfigData`` is for read-only access to
+the configuration data.  A process configuration is made up of a stack of
+different ``IConfigData``.  The ``IStackableConfig`` interface provides the
 methods used to manipulate that stack of configuration overlays.
 
     >>> from lazr.config.interfaces import IConfigData, IStackableConfig
@@ -401,15 +328,14 @@
     >>> verifyObject(IStackableConfig, config)
     True
 
-Like the schema file, the conf file is made up of sections with keys.
-The sections may belong to a category. Unlike the schema file, it does
-not have template or optional sections. The [meta] has the extends
-key that declares that this conf extends shared.conf.
+Like the schema file, the conf file is made up of sections with keys.  The
+sections may belong to a category.  Unlike the schema file, it does not have
+template or optional sections.  The ``[meta]`` section has the extends key
+that declares that this conf extends ``shared.conf``.
 
-    >>> local_file = open(local_conf, 'r')
-    >>> raw_conf = local_file.read()
-    >>> local_file.close()
-    >>> print raw_conf
+    >>> with open(local_conf, 'rt') as local_file:
+    ...     raw_conf = local_file.read()
+    >>> print(raw_conf)
     [meta]
     extends: shared.conf
     # Localize a key for section_1.
@@ -418,66 +344,71 @@
     # Accept the default values for the optional section-5.
     [section-5]
 
-The .master section allows admins to define configurations for an arbitrary
-number of processes.  If the schema defines .master sections, then the conf
-file can contain sections that extend the .master section.  These are like
-categories with templates except that the section names extending .master need
-not be named in the schema file.
+The ``.master`` section allows admins to define configurations for an
+arbitrary number of processes.  If the schema defines ``.master`` sections,
+then the conf file can contain sections that extend the ``.master`` section.
+These are like categories with templates except that the section names
+extending ``.master`` need not be named in the schema file.
 
-    >>> master_schema_conf = path.join(testfiles_dir,  'master.conf')
-    >>> master_local_conf = path.join(testfiles_dir,  'master-local.conf')
+    >>> master_schema_conf = resource_filename(
+    ...     'lazr.config.tests.testdata', 'master.conf')
+    >>> master_local_conf = resource_filename(
+    ...     'lazr.config.tests.testdata', 'master-local.conf')
     >>> master_schema = ConfigSchema(master_schema_conf)
     >>> sections = master_schema.getByCategory('thing')
-    >>> sorted(section.name for section in sections)
-    ['thing.master']
+    >>> for name in sorted(section.name for section in sections):
+    ...     print(name)
+    thing.master
     >>> master_conf = master_schema.load(master_local_conf)
     >>> sections = master_conf.getByCategory('thing')
-    >>> sorted(section.name for section in sections)
-    ['thing.one', 'thing.two']
-    >>> sorted(section.foo for section in sections)
-    ['1', '2']
-    >>> print master_conf.thing.one.name
-    thing.one
-
-The shared.conf file derives the keys and default values from the
-schema. This config was loaded before local.conf because its sections
-and values are required to be in place before local.conf applies its
-changes.
-
-    >>> shared_conf = path.join(testfiles_dir,  'shared.conf')
-    >>> shared_file = open(shared_conf, 'r')
-    >>> raw_conf = shared_file.read()
-    >>> shared_file.close()
-    >>> print raw_conf
+    >>> for name in sorted(section.name for section in sections):
+    ...     print(name)
+    thing.one
+    thing.two
+    >>> for name in sorted(section.foo for section in sections):
+    ...     print(name)
+    1
+    2
+    >>> print(master_conf.thing.one.name)
+    thing.one
+
+The ``shared.conf`` file derives the keys and default values from the schema.
+This config was loaded before ``local.conf`` because its sections and values
+are required to be in place before ``local.conf`` applies its changes.
+
+    >>> shared_config = resource_filename(
+    ...     'lazr.config.tests.testdata', 'shared.conf')
+    >>> with open(shared_config, 'rt') as shared_file:
+    ...     raw_conf = shared_file.read()
+    >>> print(raw_conf)
     # The schema is defined by base.conf.
     # Localize a key for section_1.
     [section_1]
     key2: sharing is fun
     key5: shared value
 
-The config that was loaded has name and filename attributes to identify
-the configuration.
+The config that was loaded has ``name`` and ``filename`` attributes to
+identify the configuration.
 
-    >>> config.name
-    'local.conf'
-    >>> config.filename
-    '...lazr/config/tests/testdata/local.conf'
+    >>> print(config.name)
+    local.conf
+    >>> print('file:', config.filename)
+    file: ...lazr/config/tests/testdata/local.conf
 
 The config can access the schema via the schema property.
 
-    >>> config.schema.name
-    'base.conf'
+    >>> print(config.schema.name)
+    base.conf
     >>> config.schema is schema
     True
 
-A config is made up of multiple Sections like the schema. They can be
-iterated over in a loop as needed. This config inherited several
-sections defined in schema. Note that the meta section is not present
-because it pertains to the config system, not to the processes being
-configured.
+A config is made up of multiple Sections like the schema.  They can be
+iterated over in a loop as needed.  This config inherited several sections
+defined in schema.  Note that the meta section is not present because it
+pertains to the config system, not to the processes being configured.
 
     >>> for section in sorted(config, key=attrgetter('name')):
-    ...     print section.name
+    ...     print(section.name)
     section-2.app-b
     section-5
     section_1
@@ -491,11 +422,11 @@
     >>> 'bad-section' in config
     False
 
-Optional SchemaSections are not inherited by the config. A config file
-must declare all optional sections. Including the section heading is
-enough to inherit the section and its keys. The config file may localize
-the keys by declaring them too. The local.conf file includes
-'section-5', but not 'section_3.app_a'
+Optional SchemaSections are not inherited by the config.  A config file must
+declare all optional sections.  Including the section heading is enough to
+inherit the section and its keys.  The config file may localize the keys by
+declaring them too.  The ``local.conf`` file includes ``section-5``, but not
+``section_3.app_a``.
 
 
     >>> 'section_3.app_a' in config
@@ -504,7 +435,6 @@
     True
     >>> config.schema['section_3.app_a'].optional
     True
-
     >>> 'section-5' in config
     True
     >>> 'section-5' in config.schema
@@ -512,81 +442,65 @@
     >>> config.schema['section-5'].optional
     True
 
-A Section can be accessed using subscript notation. Accessing a section
-that does not exist will raise a NoSectionError.
+A Section can be accessed using subscript notation.  Accessing a section that
+does not exist will raise a NoSectionError.  NoSectionError is raised for a
+undeclared optional sections too.
 
     >>> section_1 = config['section_1']
     >>> section_1.name in config
     True
 
-    >>> config['section-4']
-    Traceback (most recent call last):
-      ...
-    NoSectionError: ...
-
-NoSectionError is raised for a undeclared optional sections too.
-
-    >>> config['section_3.app_a']
-    Traceback (most recent call last):
-      ...
-    NoSectionError: ...
-
-Config supports category access like Schema does. The list of
-categories are returned by the category_names property.
-
-    >>> sorted(config.category_names)
-    ['section-2', 'section_3']
+Config supports category access like Schema does.  The list of categories are
+returned by the ``category_names`` property.
+
+    >>> for name in sorted(config.category_names):
+    ...     print(name)
+    section-2
+    section_3
 
 All the sections that belong to a category can be retrieved using the
-getByCategory() method.
+``getByCategory()`` method.
 
     >>> for section in config.getByCategory('section_3'):
-    ...     print section_schema.name
+    ...     print(section_schema.name)
     section_3.app_b
 
 Passing a non-existent category_name to the method will raise a
-NoCategoryError.
-
-    >>> config.getByCategory('non-section')
-    Traceback (most recent call last):
-      ...
-    NoCategoryError: ...
-
-As with schemas, you can pass a default argument to getByCategory() to avoid
-the exception.
+NoCategoryError.  As with schemas, you can pass a default argument to
+``getByCategory()`` to avoid the exception.
 
     >>> missing = object()
     >>> config.getByCategory('non-section', missing) is missing
     True
 
 
-=======
 Section
 =======
 
-A Section behaves similar to a dictionary. It has keys and values.
-It supports some specialize access methods and properties for working
-with the values. Each Section has a name. Continuing with section_1
-from above....
+A Section behaves similar to a dictionary.  It has keys and values.  It
+supports some specialize access methods and properties for working with the
+values.  Each Section has a name.
 
     >>> from lazr.config.interfaces import ISection
     >>> verifyObject(ISection, section_1)
     True
-
-    >>> section_1.name
-    'section_1'
-
-Like SectionSchemas, sections can return a 2-tuple of their category
-name and specific name parts. The category name will be None if the
-section's name does not contain a category.
-
-    >>> config['section_3.app_b'].category_and_section_names
-    ('section_3', 'app_b')
-
-    >>> section_1.category_and_section_names
-    (None, 'section_1')
-
-The Section's type is the same type as the ConfigSchema.section_factory.
+    >>> print(section_1.name)
+    section_1
+
+Like SectionSchemas, sections can return a 2-tuple of their category name and
+specific name parts.  The category name will be ``None`` if the section's name
+does not contain a category.
+
+    >>> for name in config['section_3.app_b'].category_and_section_names:
+    ...     print(name)
+    section_3
+    app_b
+    >>> for name in section_1.category_and_section_names:
+    ...     print(name)
+    None
+    section_1
+
+The Section's type is the same type as the ``ConfigSchema.section_factory``.
 
     >>> section_1
     <lazr.config...Section object at ...>
@@ -603,10 +517,10 @@
 A key can be accessed directly using as a subscript of the Section.
 The value is always a string.
 
-    >>> section_1['key3']
-    'Launchpad&nbsp;rocks'
-    >>> section_1['key5']
-    'local value'
+    >>> print(section_1['key3'])
+    Launchpad&nbsp;rocks
+    >>> print(section_1['key5'])
+    local value
 
 An error is raised if a non-existent key is accessed via a subscript.
 
@@ -615,37 +529,36 @@
       ...
     KeyError: ...
 
-The Section keys can be iterated. The section has all the keys from the
-SectionSchema. The values came form the schema's default values, then
-the values from shared.conf were applied, and lastly, the values from
-local.conf were applied. The schema provided the values of key1, key3,
-and key4, shared.conf provided the value of key2. local.conf provided
-key5. While shared.conf provided a key5, local.conf takes precedence.
+The Section keys can be iterated over.  The section has all the keys from the
+SectionSchema.  The values came form the schema's default values, then the
+values from ``shared.conf`` were applied, and lastly, the values from
+``local.conf`` were applied.  The schema provided the values of ``key1``,
+``key3``, and ``key4``. ``shared.conf`` provided the value of ``key2``
+. ``local.conf`` provided ``key5``.  While ``shared.conf`` provided a
+``key5``, ``local.conf`` takes precedence.
 
     >>> for key in sorted(section_1):
-    ...     print key, ':', section_1[key]
+    ...     print(key, ':', section_1[key])
     key1 : foo
     key2 : sharing is fun
     key3 : Launchpad&nbsp;rocks
     key4 : F&#028c;k yeah!
     key5 : local value
-
     >>> section_1.schema['key5']
     ''
 
-The schema provided mandatory sections and default values to the
-config. So while the config file did not declare all the sections, they
-are present. In the case of section_3.app_b, its keys were defined in a
-template section.
+The schema provided mandatory sections and default values to the config.  So
+while the config file did not declare all the sections, they are present.  In
+the case of ``section_3.app_b``, its keys were defined in a template section.
 
     >>> for key in sorted(config['section_3.app_b']):
-    ...     print key, ':', config['section_3.app_b'][key]
+    ...     print(key, ':', config['section_3.app_b'][key])
     key1 : 17
     key2 : changed
     key3 : unique
 
-Sections attributes cannot be directly set to shadow config options. An
-AttributeError is raised when a callsite attempts to mutate the config.
+Sections attributes cannot be directly set to shadow config options.  An
+``AttributeError`` is raised when an attempt is made to mutate the config.
 
     >>> config['section_3.app_b'].key1 = 'fail'
     Traceback (most recent call last):
@@ -660,96 +573,73 @@
     AttributeError: Config options cannot be set directly.
 
 
-==================
 Validating configs
 ==================
 
-Config provides the validate() method to verify that the config is valid
-according to the schema. The method returns True if the config is valid.
+Config provides the ``validate()`` method to verify that the config is valid
+according to the schema.  The method returns ``True`` if the config is valid.
 
     >>> config.validate()
     True
 
-When the config is not valid, a ConfigErrors is raised. The
-exception has an errors property that contains a list of all the
-errors in the config.
-
-    >>> from lazr.config.interfaces import ConfigErrors
-
-    >>> try:
-    ...     bad_config.validate()
-    ... except ConfigErrors, validation_error:
-    ...     print validation_error
-    ...     for error in validation_error.errors:
-    ...         print  "%s: %s" % (error.__class__.__name__, error)
-    ConfigErrors: bad conf is not valid.
-    UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in ... range(128)
-    UnknownKeyError: section_1 does not have a keyn key.
-    UnknownKeyError: The meta section does not have a metakey key.
-    UnknownSectionError: base.conf does not have a unknown-section section.
-
-
-===============
+When the config is not valid, a ConfigErrors is raised.  The exception has an
+``errors`` property that contains a list of all the errors in the config.
+
+
 Config overlays
 ===============
 
-A conf file may contains a meta section that is used by the config
-system. The config data can access the config it extended using the
-extends property. The object is just the config data; it does not
-have any config methods.
+A conf file may contain a meta section that is used by the config system.  The
+config data can access the config it extended using the ``extends`` property.
+The object is just the config data; it does not have any config methods.
 
-    >>> config.extends.name
-    'shared.conf'
+    >>> print(config.extends.name)
+    shared.conf
 
     >>> verifyObject(IConfigData, config.extends)
     True
-    >>> verifyObject(IStackableConfig, config.extends)
-    Traceback (most recent call last):
-     ...
-    DoesNotImplement: ...
 
-As Config supports inheritance through the extends key, each conf file
-produces instance of ConfigData, called an overlay. ConfigData
-represents the state of a config. The overlays property is a stack of
-ConfigData as it was constructed from the schema's config to the last
-config file that was loaded.
+As Config supports inheritance through the ``extends`` key, each conf file
+produces instance of ConfigData, called an *overlay*.  ConfigData represents
+the state of a config.  The ``overlays`` property is a stack of ConfigData as
+it was constructed from the schema's config to the last config file that was
+loaded.
 
     >>> for config_data in config.overlays:
-    ...     print config_data.name
+    ...     print(config_data.name)
     local.conf
     shared.conf
     base.conf
-
     >>> verifyObject(IConfigData, config.overlays[-1])
     True
 
-Conf files can use the extends key to specify that it extends a schema
-without incurring a processing penalty by loading the schema twice in a
-row. The schema can never be the second item in the overlays stack.
+Conf files can use the ``extends`` key to specify that it extends a schema
+without incurring a processing penalty by loading the schema twice in a row.
+The schema can never be the second item in the overlays stack.
 
     >>> single_config = schema.load(schema.filename)
     >>> for config_data in single_config.overlays:
-    ...     print config_data.name
+    ...     print(config_data.name)
     base.conf
-
-    >>> single_config.push(schema.filename, raw_schema)
+    >>> single_config.push(schema.filename, raw_schema.decode('utf-8'))
     >>> for config_data in single_config.overlays:
-    ...     print config_data.name
+    ...     print(config_data.name)
     base.conf
 
 
 push()
 ======
 
-Raw config data can be merged with the config to create a new overlay
-for testing. The push() method accepts a string of config data. The
-data must conform to the schema. The 'section_1' sections's keys are
-updated when the unparsed data is pushed onto the config. Note that
-indented unparsed data is passed to push() in thie example; push()
-does not require tests to dedent the test data.
+Raw config data can be merged with the config to create a new overlay for
+testing.  The ``push()`` method accepts a string of config data.  The data
+must conform to the schema.  The ``section_1`` sections's keys are updated
+when the unparsed data is pushed onto the config.  Note that indented,
+unparsed data is passed to ``push()`` in this example; ``push()`` does not
+require tests to dedent the test data.
+::
 
     >>> for key in sorted(config['section_1']):
-    ...     print key, ':', config['section_1'][key]
+    ...     print(key, ':', config['section_1'][key])
     key1 : foo
     key2 : sharing is fun
     key3 : Launchpad&nbsp;rocks
@@ -763,16 +653,17 @@
     >>> config.push('test config', test_data)
 
     >>> for key in sorted(config['section_1']):
-    ...     print key, ':', config['section_1'][key]
+    ...     print(key, ':', config['section_1'][key])
     key1 : test1
     key2 : sharing is fun
     key3 : Launchpad&nbsp;rocks
     key4 : F&#028c;k yeah!
     key5 :
 
-Besides updating section keys, optional sections can be enabled too.
-The 'section_3.app_a' section is enabled with the default keys from the
-schema in this example.
+Besides updating section keys, optional sections can be enabled too.  The
+``section_3.app_a`` section is enabled with the default keys from the schema
+in this example.
+::
 
     >>> config.schema['section_3.app_a'].optional
     True
@@ -785,41 +676,41 @@
     >>> 'section_3.app_a' in config
     True
     >>> for key in sorted(config['section_3.app_a']):
-    ...     print key, ':', config['section_3.app_a'][key]
+    ...     print(key, ':', config['section_3.app_a'][key])
     key1 : 17
     key2 : 3.1415
 
     >>> for key in sorted(config.schema['section_3.app_a']):
-    ...     print key, ':', config.schema['section_3.app_a'][key]
+    ...     print(key, ':', config.schema['section_3.app_a'][key])
     key1 : 17
     key2 : 3.1415
 
-The config's name and overlays are updated by push().
+The config's name and overlays are updated by ``push()``.
 
-    >>> config.name
-    'test app_a'
-    >>> config.filename
-    'test app_a'
+    >>> print(config.name)
+    test app_a
+    >>> print(config.filename)
+    test app_a
     >>> for config_data in config.overlays:
-    ...     print config_data.name
+    ...     print(config_data.name)
     test app_a
     test config
     local.conf
     shared.conf
     base.conf
 
-The 'test app_a' did not declare an extends key in a meta section. Its
-extends property is None, even though it implicitly extends 'test
-config'. The extends property only provides access to configs that are
-explicitly extended.
-
-    >>> config.extends.name
-    'test config'
-
-The config's sections are updated with 'section_3.app_a' too.
+The ``test app_a`` config did not declare an ``extends`` key in a ``meta``
+section.  Its ``extends`` property is ``None``, even though it implicitly
+extends ``test config``.  The ``extends`` property only provides access to
+configs that are explicitly extended.
+
+    >>> print(config.extends.name)
+    test config
+
+The config's sections are updated with ``section_3.app_a`` too.
 
     >>> for section in sorted(config, key=attrgetter('name')):
-    ...     print section.name
+    ...     print(section.name)
     section-2.app-b
     section-5
     section_1
@@ -827,17 +718,18 @@
     section_3.app_b
     section_33
 
-A config file may state that it extends its schema (to clearly connect
-the config to the schema). The schema can also be pushed to reset the
-values in the config to the schema's default values.
+A config file may state that it extends its schema (to clearly connect the
+config to the schema).  The schema can also be pushed to reset the values in
+the config to the schema's default values.
 
-    >>> extender_conf_name = path.join(testfiles_dir, 'extender.conf')
+    >>> extender_conf_name = resource_filename(
+    ...     'lazr.config.tests.testdata', 'extender.conf')
     >>> extender_conf_data = ("""
     ...     [meta]
     ...     extends: base.conf""")
     >>> config.push(extender_conf_name, extender_conf_data)
     >>> for config_data in config.overlays:
-    ...     print config_data.name
+    ...     print(config_data.name)
     extender.conf
     base.conf
     test app_a
@@ -846,22 +738,23 @@
     shared.conf
     base.conf
 
-The 'section_1' section was restored to the schema's default values.
+The ``section_1`` section was restored to the schema's default values.
 
     >>> for key in sorted(config['section_1']):
-    ...     print key, ':', config['section_1'][key]
+    ...     print(key, ':', config['section_1'][key])
     key1 : foo
     key2 : bar and baz
     key3 : Launchpad&nbsp;rocks
     key4 : F&#028c;k yeah!
     key5 :
 
-push() can also be used to extend master sections.
+``push()`` can also be used to extend master sections.
+::
 
     >>> sections = sorted(master_conf.getByCategory('bar'),
     ...                   key=attrgetter('name'))
     >>> for section in sections:
-    ...     print section.name, section.baz
+    ...     print(section.name, section.baz)
     bar.master badger
     bar.soup cougar
 
@@ -872,7 +765,7 @@
     >>> sections = sorted(master_conf.getByCategory('bar'),
     ...                   key=attrgetter('name'))
     >>> for section in sections:
-    ...     print section.name, section.baz
+    ...     print(section.name, section.baz)
     bar.soup cougar
     bar.two dolphin
 
@@ -883,67 +776,70 @@
     >>> sections = sorted(master_conf.getByCategory('bar'),
     ...                   key=attrgetter('name'))
     >>> for section in sections:
-    ...     print section.name, section.baz
+    ...     print(section.name, section.baz)
     bar.soup cougar
     bar.three emu
     bar.two dolphin
 
-push() works with master sections too.
+``push()`` works with master sections too.
+::
 
-    >>> schema_file = StringIO.StringIO("""\
+    >>> schema_file = StringIO("""\
     ... [thing.master]
     ... foo: 0
     ... bar: 0
     ... """)
     >>> push_schema = ConfigSchema('schema.cfg', schema_file)
 
-    >>> config_file = StringIO.StringIO("""\
+    >>> config_file = StringIO("""\
     ... [thing.one]
     ... foo: 1
     ... """)
     >>> push_config = push_schema.loadFile(config_file, 'config.cfg')
-    >>> print push_config.thing.one.foo
+    >>> print(push_config.thing.one.foo)
     1
-    >>> print push_config.thing.one.bar
+    >>> print(push_config.thing.one.bar)
     0
 
     >>> push_config.push('test.cfg', """\
     ... [thing.one]
     ... bar: 2
     ... """)
-    >>> print push_config.thing.one.foo
+    >>> print(push_config.thing.one.foo)
     1
-    >>> print push_config.thing.one.bar
+    >>> print(push_config.thing.one.bar)
     2
 
 
 pop()
 =====
 
-ConfigData can be removed from the stack of overlays using the pop()
-method. The methods returns the list of ConfigData that was removed--a
+ConfigData can be removed from the stack of overlays using the ``pop()``
+method.  The methods returns the list of ConfigData that was removed -- a
 slice from the specified ConfigData to the top of the stack.
+::
 
     >>> overlays = config.pop('test config')
     >>> for config_data in overlays:
-    ...     config_data.name
-    'extender.conf'
-    'base.conf'
-    'test app_a'
-    'test config'
+    ...     print(config_data.name)
+    extender.conf
+    base.conf
+    test app_a
+    test config
 
     >>> for config_data in config.overlays:
-    ...     print config_data.name
+    ...     print(config_data.name)
     local.conf
     shared.conf
     base.conf
 
-The config's state was restored to the ConfigData that is top of the
-overlay stack. Section 'section_3.app_a' was removed completely. The
-keys ('key1' and 'key5') for 'section_1' were restored.
+The config's state was restored to the ConfigData that is on top of the
+overlay stack.  Section ``section_3.app_a`` was removed completely.  The keys
+(``key1`` and ``key5``) for ``section_1`` were restored.
+::
 
     >>> for section in sorted(config, key=attrgetter('name')):
-    ...     print section.name
+    ...     print(section.name)
     section-2.app-b
     section-5
     section_1
@@ -951,46 +847,32 @@
     section_33
 
     >>> for key in sorted(config['section_1']):
-    ...     print key, ':', config['section_1'][key]
+    ...     print(key, ':', config['section_1'][key])
     key1 : foo
     key2 : sharing is fun
     key3 : Launchpad&nbsp;rocks
     key4 : F&#028c;k yeah!
     key5 : local value
 
-Call the pop() method with an unknown conf_name raises an error
-
-    >>> overlays = config.pop('bad-name')
-    Traceback (most recent call last):
-      ...
-    NoConfigError: No config with name: bad-name.
-
-A Config must have at least one ConfigData in the overlays stack so that
-it has data. The bottom ConfigData in the overlays was made from the
-schema's required sections. It cannot be removed by the pop() method.
-
-    >>> overlays = config.pop('base.conf')
-    Traceback (most recent call last):
-      ...
-    NoConfigError: Cannot pop the schema's default config.
+A Config must have at least one ConfigData in the overlays stack so that it
+has data.  The bottom ConfigData in the overlays was made from the schema's
+required sections.  It cannot be removed by the ``pop()`` method.
 
 If all but the bottom ConfigData is popped from overlays, the extends
 property returns None.
 
     >>> overlays = config.pop('shared.conf')
-    >>> print config.extends
+    >>> print(config.extends)
     None
 
 
-===============================
 Attribute access to config data
 ===============================
 
-Config provides attribute-based access to its members. So long as the
-section, category, and key names conform to Python identifier naming
-rules, they can be accessed as attributes. The Python code will not
-compile, or will cause a runtime error if the object being accessed has
-a bad name.
+Config provides attribute-based access to its members.  So long as the
+section, category, and key names conform to Python identifier naming rules,
+they can be accessed as attributes.  The Python code will not compile, or will
+cause a runtime error if the object being accessed has a bad name.
 
 Sections appear to be attributes of the config.
 
@@ -998,15 +880,15 @@
     >>> config.section_1 is config['section_1']
     True
 
-Accessing an unknown section, or a section whose name is not a valid
-Python identifier will raise an AttributeError.
+Accessing an unknown section, or a section whose name is not a valid Python
+identifier will raise an AttributeError.
 
     >>> config.section-5
     Traceback (most recent call last):
       ...
     AttributeError: No section or category named section.
 
-Categories may be accessed as attributes too. The ICategory interface
+Categories may be accessed as attributes too.  The ICategory interface
 provides access to its sections as members.
 
     >>> from lazr.config.interfaces import ICategory
@@ -1016,8 +898,8 @@
     >>> config_category.app_b is config['section_3.app_b']
     True
 
-Like a config, a category will raise an AttributeError if it does not
-have a section that matches the identifier name.
+Like a config, a category will raise an AttributeError if it does not have a
+section that matches the identifier name.
 
     >>> config_category.no_such_section
     Traceback (most recent call last):
@@ -1026,10 +908,10 @@
 
 Section keys can be accessed directly as members.
 
-    >>> config.section_1.key2
-    'sharing is fun'
-    >>> config.section_3.app_b.key2
-    'changed'
+    >>> print(config.section_1.key2)
+    sharing is fun
+    >>> print(config.section_3.app_b.key2)
+    changed
 
 Accessing a non-existent section key as an attribute will raise an
 AttributeError.
@@ -1040,27 +922,25 @@
     AttributeError: No section key named non_key.
 
 
-====================
 Implicit data typing
 ====================
 
-The ImplicitTypeSchema can create configs that support implicit
-datatypes. The value of a Section key is automatically converted from
-str to the type the value appears to be. Implicit typing does not add
-any validation support; it adds type casting conveniences for the
-developer.
+The ImplicitTypeSchema can create configs that support implicit datatypes.
+The value of a Section key is automatically converted from ``str`` to the type
+the value appears to be.  Implicit typing does not add any validation support;
+it adds type casting conveniences for the developer.
 
-An ImplicitTypeSchema can be used to parse the same schema and conf
-files that Schema uses.
+An ImplicitTypeSchema can be used to parse the same schema and conf files that
+Schema uses.
 
     >>> from lazr.config import ImplicitTypeSchema
-
     >>> implicit_schema = ImplicitTypeSchema(base_conf)
     >>> verifyObject(IConfigSchema, implicit_schema)
     True
 
 The config loaded by ImplicitTypeSchema is the same class with the same
 sections as is made by Schema.
+::
 
     >>> implicit_config = implicit_schema.load(local_conf)
     >>> implicit_config
@@ -1082,8 +962,9 @@
     >>> implicit_config['section_3.app_b']
     <lazr.config...ImplicitTypeSection object at ...>
 
-ImplicitTypeSection, in contrast to Section, converts values that
-appear to be integer or boolean into ints and bools.
+ImplicitTypeSection, in contrast to Section, converts values that appear to be
+integer or boolean into ints and bools.
+::
 
     >>> config['section_3.app_b']['key1']
     '17'
@@ -1103,11 +984,11 @@
     >>> implicit_config['section-2.app-b'].key1
     True
 
-ImplicitTypeSection uses a private method that employs heuristic rules
-to convert strings into simple types. It may return a str, bool, or int.
-When the argument is the word 'true' or 'false' (in any case), a bool is
-returned. Values like 'yes', 'no', '0', and '1' are not converted to
-bool.
+ImplicitTypeSection uses a private method that employs heuristic rules to
+convert strings into simple types.  It may return a str, bool, or int.  When
+the argument is the word 'true' or 'false' (in any case), a bool is returned.
+Values like 'yes', 'no', '0', and '1' are not converted to bool.
+::
 
     >>> convert = implicit_config['section_1']._convert
 
@@ -1118,31 +999,33 @@
     >>> convert('tRue')
     True
 
-    >>> convert('yes')
-    'yes'
+    >>> print(convert('yes'))
+    yes
     >>> convert('1')
     1
-    >>> convert('True or False')
-    'True or False'
-
-When the argument is the word 'none', None is returned. The token in the
-config means the key has no value.
-
-    >>> print convert('none')
-    None
-    >>> print convert('None')
-    None
-    >>> print convert('nonE')
-    None
-
-    >>> convert('none today')
-    'none today'
-    >>> convert('nonevident')
-    'nonevident'
-
-When the argument is an unbroken sequence of numbers, an int is
-returned. The number may have a leading positive or negative. Octal and
-hex notation is not supported.
+    >>> print(convert('True or False'))
+    True or False
+
+When the argument is the word ``none``, ``None`` is returned.  The token in
+the config means the key has no value.
+::
+
+    >>> print(convert('none'))
+    None
+    >>> print(convert('None'))
+    None
+    >>> print(convert('nonE'))
+    None
+
+    >>> print(convert('none today'))
+    none today
+    >>> print(convert('nonevident'))
+    nonevident
+
+When the argument is an unbroken sequence of numbers, an int is returned.  The
+number may have a leading positive or negative.  Octal and hex notation is not
+supported.
+::
 
     >>> convert('0')
     0
@@ -1155,37 +1038,28 @@
     >>> convert('0100')
     100
 
-    >>> convert('2001-01-01')
-    '2001-01-01'
-    >>> convert('1000*60*5')
-    '1000*60*5'
-    >>> convert('1000 * 60 * 5')
-    '1000 * 60 * 5'
-    >>> convert('1,024')
-    '1,024'
-    >>> convert('0.5')
-    '0.5'
-    >>> convert('0x100')
-    '0x100'
+    >>> print(convert('2001-01-01'))
+    2001-01-01
+    >>> print(convert('1000*60*5'))
+    1000*60*5
+    >>> print(convert('1000 * 60 * 5'))
+    1000 * 60 * 5
+    >>> print(convert('1,024'))
+    1,024
+    >>> print(convert('0.5'))
+    0.5
+    >>> print(convert('0x100'))
+    0x100
 
 Multiline values are always strings, with white space (and line breaks)
-removed from the beginning/end.
-
-    >>> convert("""multiline value 1
-    ...     multiline value 2""")
-    'multiline value 1\n    multiline value 2'
-
-    >>> convert("""
-    ...     multiline value 1
-    ...     multiline value 2
-    ...     """)
-    'multiline value 1\n    multiline value 2'
-
-    >>> implicit_config['section_33'].key2
-    'multiline value 1\nmultiline value 2'
-
-
-=======================
+removed from the beginning and end.
+
+    >>> print(convert("""multiline value 1
+    ...     multiline value 2"""))
+    multiline value 1
+    multiline value 2
+
+
 Type conversion helpers
 =======================
 
@@ -1195,10 +1069,10 @@
 
 
 Booleans
-========
+--------
 
-There is a helper for turning various strings into the boolean values True and
-False.
+There is a helper for turning various strings into the boolean values ``True``
+and ``False``.
 
     >>> from lazr.config import as_boolean
 
@@ -1206,8 +1080,8 @@
 enable.
 
     >>> for value in ('true', 'yes', 'on', 'enable', 'enabled', '1'):
-    ...     print value, '->', as_boolean(value)
-    ...     print value.upper(), '->', as_boolean(value.upper())
+    ...     print(value, '->', as_boolean(value))
+    ...     print(value.upper(), '->', as_boolean(value.upper()))
     true -> True
     TRUE -> True
     yes -> True
@@ -1225,8 +1099,8 @@
 disable.
 
     >>> for value in ('false', 'no', 'off', 'disable', 'disabled', '0'):
-    ...     print value, '->', as_boolean(value)
-    ...     print value.upper(), '->', as_boolean(value.upper())
+    ...     print(value, '->', as_boolean(value))
+    ...     print(value.upper(), '->', as_boolean(value.upper()))
     false -> False
     FALSE -> False
     no -> False
@@ -1249,46 +1123,53 @@
 
 
 Host and port
-=============
+-------------
 
-There is a helper for converting from a host:port string to a 2-tuple of
-(host, port).
+There is a helper for converting from a ``host:port`` string to a 2-tuple of
+``(host, port)``.
 
     >>> from lazr.config import as_host_port
-    >>> as_host_port('host:25')
-    ('host', 25)
+    >>> host, port = as_host_port('host:25')
+    >>> print(host, port)
+    host 25
 
 The port string is optional, in which case, port 25 is the default (for
 historical reasons).
 
-    >>> as_host_port('host')
-    ('host', 25)
+    >>> host, port = as_host_port('host')
+    >>> print(host, port)
+    host 25
 
 The default port can be overridden.
 
-    >>> as_host_port('host', default_port=22)
-    ('host', 22)
+    >>> host, port = as_host_port('host', default_port=22)
+    >>> print(host, port)
+    host 22
 
 The default port is ignored if it is given in the value.
 
-    >>> as_host_port('host:80', default_port=22)
-    ('host', 80)
+    >>> host, port = as_host_port('host:80', default_port=22)
+    >>> print(host, port)
+    host 80
 
 The host name is also optional, as denoted by a leading colon.  When omitted,
 localhost is used.
 
-    >>> as_host_port(':80')
-    ('localhost', 80)
+    >>> host, port = as_host_port(':80')
+    >>> print(host, port)
+    localhost 80
 
 The default host name can be overridden though.
 
-    >>> as_host_port(':80', default_host='myhost')
-    ('myhost', 80)
+    >>> host, port = as_host_port(':80', default_host='myhost')
+    >>> print(host, port)
+    myhost 80
 
 The default host name is ignored if the value string contains it.
 
-    >>> as_host_port('yourhost:80', default_host='myhost')
-    ('yourhost', 80)
+    >>> host, port = as_host_port('yourhost:80', default_host='myhost')
+    >>> print(host, port)
+    yourhost 80
 
 A ValueError occurs if the port number in the configuration value string is
 not an integer.
@@ -1300,10 +1181,10 @@
 
 
 User and group
-==============
+--------------
 
-A helper is provided for turning a chown(1)-style user:group specification
-into a 2-tuple of the user name and group name.
+A helper is provided for turning a ``chown(1)``-style ``user:group``
+specification into a 2-tuple of the user name and group name.
 
     >>> from lazr.config import as_username_groupname
 
@@ -1317,14 +1198,16 @@
 
 When both are given, the strings are returned unchanged or validated.
 
-    >>> as_username_groupname('person:group')
-    ('person', 'group')
+    >>> user, group = as_username_groupname('person:group')
+    >>> print(user, group)
+    person group
 
 Numeric values can be given, but they are not converted into their symbolic
 names.
 
-    >>> as_username_groupname('25:26')
-    ('25', '26')
+    >>> uid, gid = as_username_groupname('25:26')
+    >>> print(uid, gid)
+    25 26
 
 By default the current user and group names are returned.
 
@@ -1337,10 +1220,10 @@
 
 
 Time intervals
-==============
+--------------
 
-One such converter accepts a range of 'time interval specifications', and
-returns a Python timedelta.
+This converter accepts a range of *time interval specifications*, and returns
+a Python timedelta_.
 
     >>> from lazr.config import as_timedelta
 
@@ -1349,22 +1232,22 @@
     >>> as_timedelta('45s')
     datetime.timedelta(0, 45)
 
-The function also accepts suffixes 'm' for minutes...
+The function also accepts suffixes ``m`` for minutes...
 
     >>> as_timedelta('3m')
     datetime.timedelta(0, 180)
 
-...'h' for hours...
+...``h`` for hours...
 
     >>> as_timedelta('2h')
     datetime.timedelta(0, 7200)
 
-...and 'd' for days...
+...and ``d`` for days...
 
     >>> as_timedelta('4d')
     datetime.timedelta(4)
 
-...and 'w' for weeks.
+...and ``w`` for weeks.
 
     >>> as_timedelta('4w')
     datetime.timedelta(28)
@@ -1381,7 +1264,7 @@
     >>> as_timedelta('4w2d9h3s')
     datetime.timedelta(30, 32403)
 
-But doesn't accept 'weird' or duplicate combinations.
+But doesn't accept "weird" or duplicate combinations.
 
     >>> as_timedelta('3s2s')
     Traceback (most recent call last):
@@ -1414,10 +1297,10 @@
 
 
 Log levels
-==========
+----------
 
 It's convenient to be able to use symbolic log level names when using
-lazr.config to configure the Python logger.
+``lazr.config`` to configure the Python logger.
 
     >>> from lazr.config import as_log_level
 
@@ -1425,8 +1308,8 @@
 
     >>> for value in ('critical', 'error', 'warning', 'info',
     ...               'debug', 'notset'):
-    ...     print value, '->', as_log_level(value)
-    ...     print value.upper(), '->', as_log_level(value.upper())
+    ...     print(value, '->', as_log_level(value))
+    ...     print(value.upper(), '->', as_log_level(value.upper()))
     critical -> 50
     CRITICAL -> 50
     error -> 40
@@ -1447,7 +1330,7 @@
     ...
     AttributeError: 'module' object has no attribute 'CHEESE'
 
-===============
+
 Other Documents
 ===============
 
@@ -1456,3 +1339,5 @@
 
    *
    docs/*
+
+.. _timedelta: http://docs.python.org/3/library/datetime.html#timedelta-objects
 
=== added file 'lazr/config/docs/usage_fixture.py'
--- lazr/config/docs/usage_fixture.py	1970-01-01 00:00:00 +0000
+++ lazr/config/docs/usage_fixture.py	2013-01-10 15:47:20 +0000
@@ -0,0 +1,27 @@
+# Copyright 2009-2013 Canonical Ltd.  All rights reserved.
+#
+# This file is part of lazr.smtptest
+#
+# lazr.smtptest 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, version 3 of the License.
+#
+# lazr.smtptest 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 lazr.smtptest.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Doctest fixtures for running under nose."""
+
+from __future__ import absolute_import, print_function, unicode_literals
+
+__metaclass__ = type
+__all__ = [
+    'globs',
+    ]
+
+
+from lazr.config.docs.fixture import globs
 
=== modified file 'lazr/config/interfaces.py'
--- src/lazr/config/interfaces.py	2009-03-24 17:31:47 +0000
+++ lazr/config/interfaces.py	2013-01-10 15:47:20 +0000
@@ -1,4 +1,4 @@
-# Copyright 2007-2009 Canonical Ltd.  All rights reserved.
+# Copyright 2007-2013 Canonical Ltd.  All rights reserved.
 #
 # This file is part of lazr.config
 #
@@ -17,8 +17,9 @@
 # pylint: disable-msg=E0211,E0213,W0231
 """Interfaces for process configuration.."""
 
+from __future__ import absolute_import, print_function, unicode_literals
+
 __metaclass__ = type
-
 __all__ = [
     'ConfigErrors',
     'ConfigSchemaError',
@@ -37,12 +38,8 @@
     'UnknownKeyError',
     'UnknownSectionError']
 
-from warnings import filterwarnings
 from zope.interface import Interface, Attribute
 
-# Ignore Python 2.6 deprecation warnings.
-filterwarnings('ignore', category=DeprecationWarning, module=r'lazr\.config')
-
 
 class ConfigSchemaError(Exception):
     """A base class of all `IConfigSchema` errors."""
 
=== modified file 'lazr/config/tests/__init__.py'
--- src/lazr/config/tests/__init__.py	2009-03-24 17:31:47 +0000
+++ lazr/config/tests/__init__.py	2013-01-10 15:47:20 +0000
@@ -1,17 +0,0 @@
-# Copyright 2007-2009 Canonical Ltd.  All rights reserved.
-#
-# This file is part of lazr.config
-#
-# lazr.config 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, version 3 of the License.
-#
-# lazr.config 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 lazr.config.  If not, see <http://www.gnu.org/licenses/>.
-
-"""Test package for lazr.config."""
 
=== added file 'lazr/config/tests/test_config.py'
--- lazr/config/tests/test_config.py	1970-01-01 00:00:00 +0000
+++ lazr/config/tests/test_config.py	2013-01-10 15:47:20 +0000
@@ -0,0 +1,205 @@
+# Copyright 2008-2013 Canonical Ltd.  All rights reserved.
+#
+# This file is part of lazr.config.
+#
+# lazr.config 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, version 3 of the License.
+#
+# lazr.config 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 lazr.config.  If not, see <http://www.gnu.org/licenses/>.
+
+"""Tests of lazr.config."""
+
+from __future__ import absolute_import, print_function, unicode_literals
+
+__metaclass__ = type
+__all__ = [
+    'TestConfig',
+    ]
+
+
+import unittest
+import pkg_resources
+try:
+    from configparser import MissingSectionHeaderError, NoSectionError
+except ImportError:
+    # Python 2
+    from ConfigParser import MissingSectionHeaderError, NoSectionError
+try:
+    from io import StringIO
+except ImportError:
+    # Python 2
+    from StringIO import StringIO
+
+from operator import attrgetter
+from zope.interface.exceptions import DoesNotImplement
+from zope.interface.verify import verifyObject
+
+from lazr.config import ConfigSchema, ImplicitTypeSchema
+from lazr.config.interfaces import (
+    ConfigErrors, IStackableConfig, InvalidSectionNameError, NoCategoryError,
+    NoConfigError, RedefinedSectionError, UnknownKeyError,
+    UnknownSectionError)
+
+
+class TestConfig(unittest.TestCase):
+    def setUp(self):
+        # Python 2.6 does not have assertMultilineEqual
+        self.meq = getattr(self, 'assertMultiLineEqual', self.assertEqual)
+
+    def _testfile(self, conf_file):
+        return pkg_resources.resource_filename(
+            'lazr.config.tests.testdata', conf_file)
+
+    def test_missing_category(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        self.assertRaises(NoCategoryError, schema.getByCategory, 'non-section')
+
+    def test_missing_file(self):
+        self.assertRaises(IOError, ConfigSchema, '/does/not/exist')
+
+    def test_must_be_ascii(self):
+        self.assertRaises(UnicodeError,
+                          ConfigSchema, self._testfile('bad-nonascii.conf'))
+
+    def test_missing_schema_section(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        self.assertRaises(NoSectionError, schema.__getitem__, 'section-4')
+
+    def test_missing_header_section(self):
+        self.assertRaises(MissingSectionHeaderError,
+                          ConfigSchema, self._testfile('bad-sectionless.conf'))
+
+    def test_redefined_section(self):
+        self.assertRaises(RedefinedSectionError,
+                          ConfigSchema,
+                          self._testfile('bad-redefined-section.conf'))
+        # XXX sinzui 2007-12-13:
+        # ConfigSchema should raise RedefinedKeyError when a section redefines
+        # a key.
+
+    def test_invalid_section_name(self):
+        self.assertRaises(InvalidSectionNameError,
+                          ConfigSchema,
+                          self._testfile('bad-invalid-name.conf'))
+
+    def test_invalid_characters(self):
+        self.assertRaises(InvalidSectionNameError,
+                          ConfigSchema,
+                          self._testfile('bad-invalid-name-chars.conf'))
+
+    def test_load_missing_file(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        self.assertRaises(IOError, schema.load, '/no/such/file.conf')
+
+    def test_no_name_argument(self):
+        config = """
+[meta]
+metakey: unsupported
+[unknown-section]
+key1 = value1
+[section_1]
+keyn: unknown key
+key1: bad character in caf\xc3)
+[section_3.template]
+key1: schema suffixes are not permitted
+"""
+        schema = ConfigSchema(self._testfile('base.conf'))
+        self.assertRaises(AttributeError, schema.loadFile, StringIO(config))
+
+    def test_missing_section(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        self.assertRaises(NoSectionError, config.__getitem__, 'section-4')
+
+    def test_undeclared_optional_section(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        self.assertRaises(NoSectionError,
+                          config.__getitem__, 'section_3.app_a')
+
+    def test_nonexistent_category_name(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        self.assertRaises(NoCategoryError,
+                          config.getByCategory, 'non-section')
+
+    def test_all_config_errors(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        config = schema.loadFile(StringIO("""
+[meta]
+metakey: unsupported
+[unknown-section]
+key1 = value1
+[section_1]
+keyn: unknown key
+key1: bad character in caf\xc3)
+[section_3.template]
+key1: schema suffixes are not permitted
+"""), 'bad config')
+        try:
+            config.validate()
+        except ConfigErrors as errors:
+            sorted_errors = sorted(
+                errors.errors, key=attrgetter('__class__.__name__'))
+            self.assertEqual(str(errors),
+                             'ConfigErrors: bad config is not valid.')
+        else:
+            self.fail('ConfigErrors expected')
+        self.assertEqual(len(sorted_errors), 4)
+        self.assertEqual([error.__class__ for error in sorted_errors],
+                         [UnicodeEncodeError, UnknownKeyError,
+                          UnknownKeyError, UnknownSectionError])
+
+    def test_not_stackable(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        self.assertRaises(DoesNotImplement,
+                          verifyObject, IStackableConfig, config.extends)
+
+    def test_bad_pop(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        config.push('one', '')
+        config.push('two', '')
+        self.assertRaises(NoConfigError, config.pop, 'bad-name')
+
+    def test_cannot_pop_bottom(self):
+        schema = ConfigSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        config.pop('local.conf')
+        self.assertRaises(NoConfigError, config.pop, 'base.conf')
+
+    def test_multiline_preserves_indentation(self):
+        schema = ImplicitTypeSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        convert = config['section_1']._convert
+        orig = """\
+multiline value 1
+    multiline value 2"""
+        new = convert(orig)
+        self.meq(new, orig)
+
+    def test_multiline_strips_leading_and_trailing_whitespace(self):
+        schema = ImplicitTypeSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        convert = config['section_1']._convert
+        orig = """
+    multiline value 1
+    multiline value 2
+    """
+        new = convert(orig)
+        self.meq(new, orig.strip())
+
+    def test_multiline_key(self):
+        schema = ImplicitTypeSchema(self._testfile('base.conf'))
+        config = schema.load(self._testfile('local.conf'))
+        self.meq(config['section_33'].key2, """\
+multiline value 1
+multiline value 2""")
 
=== added file 'lazr/config/tests/testdata/__init__.py'
=== modified file 'lazr/config/version.txt'
--- src/lazr/config/version.txt	2009-08-25 18:56:38 +0000
+++ lazr/config/version.txt	2013-01-10 15:47:20 +0000
@@ -1,1 +1,1 @@
-1.1.3
+2.0
 
=== added file 'setup.cfg'
--- setup.cfg	1970-01-01 00:00:00 +0000
+++ setup.cfg	2013-01-10 15:47:20 +0000
@@ -0,0 +1,9 @@
+[nosetests]
+verbosity=3
+with-coverage=1
+with-doctest=1
+doctest-extension=.rst
+doctest-options=+ELLIPSIS,+NORMALIZE_WHITESPACE,+REPORT_NDIFF
+doctest-fixtures=_fixture
+cover-package=lazr.config
+pdb=1
 
=== modified file 'setup.py'
--- setup.py	2009-08-25 13:58:54 +0000
+++ setup.py	2013-01-10 15:47:20 +0000
@@ -1,6 +1,4 @@
-#!/usr/bin/env python
-
-# Copyright 2008-2009 Canonical Ltd.  All rights reserved.
+# Copyright 2008-2013 Canonical Ltd.  All rights reserved.
 #
 # This file is part of lazr.config.
 #
@@ -16,10 +14,9 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with lazr.config.  If not, see <http://www.gnu.org/licenses/>.
 
-import ez_setup
-ez_setup.use_setuptools()
+import distribute_setup
+distribute_setup.use_setuptools()
 
-import sys
 from setuptools import setup, find_packages
 
 # generic helpers primarily for the long_description
@@ -37,22 +34,21 @@
 # end generic helpers
 
 
-__version__ = open("src/lazr/config/version.txt").read().strip()
+__version__ = open("lazr/config/version.txt").read().strip()
 
 setup(
     name='lazr.config',
     version=__version__,
     namespace_packages=['lazr'],
-    packages=find_packages('src'),
-    package_dir={'':'src'},
+    packages=find_packages(),
     include_package_data=True,
     zip_safe=False,
     maintainer='LAZR Developers',
     maintainer_email='[e-mail]',
-    description=open('README.txt').readline().strip(),
+    description=open('README.rst').readline().strip(),
     long_description=generate(
-        'src/lazr/config/README.txt',
-        'src/lazr/config/CHANGES.txt'),
+        'lazr/config/README.rst',
+        'lazr/config/CHANGES.rst'),
     license='LGPL v3',
     install_requires=[
         'setuptools',
@@ -60,16 +56,16 @@
         'lazr.delegates',
         ],
     url='https://launchpad.net/lazr.config',
-    download_url= 'https://launchpad.net/lazr.config/+download',
+    download_url='https://launchpad.net/lazr.config/+download',
     classifiers=[
         "Development Status :: 5 - Production/Stable",
         "Intended Audience :: Developers",
         "License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)",
         "Operating System :: OS Independent",
-        "Programming Language :: Python"],
-    extras_require=dict(
-        docs=['Sphinx',
-              'z3c.recipe.sphinxdoc']
-    ),
+        'Programming Language :: Python',
+        'Programming Language :: Python :: 2.6',
+        'Programming Language :: Python :: 2.7',
+        'Programming Language :: Python :: 3',
+        ],
     test_suite='lazr.config.tests',
     )
 
=== removed directory 'src'
=== removed file 'src/lazr/config/NEWS.txt'
--- src/lazr/config/NEWS.txt	2009-08-25 18:56:38 +0000
+++ src/lazr/config/NEWS.txt	1970-01-01 00:00:00 +0000
@@ -1,15 +0,0 @@
-1.1.3 (2009-08-25)
-==================
-
-Fixed a build problem.
-
-1.1.2 (2009-08-25)
-==================
-
-Got rid of a sys.path hack.
-
-
-1.1.1
-=====
-
-Initial release
 
=== removed file 'src/lazr/config/tests/test_docs.py'
--- src/lazr/config/tests/test_docs.py	2009-03-24 17:31:47 +0000
+++ src/lazr/config/tests/test_docs.py	1970-01-01 00:00:00 +0000
@@ -1,51 +0,0 @@
-# Copyright 2009 Canonical Ltd.  All rights reserved.
-#
-# This file is part of lazr.config
-#
-# lazr.config 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, version 3 of the License.
-#
-# lazr.config 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 lazr.config.  If not, see <http://www.gnu.org/licenses/>.
-"Test harness for doctests."
-
-# pylint: disable-msg=E0611,W0142
-
-__metaclass__ = type
-__all__ = [
-    'additional_tests',
-    ]
-
-import atexit
-import doctest
-import os
-from pkg_resources import (
-    resource_filename, resource_exists, resource_listdir, cleanup_resources)
-import unittest
-
-DOCTEST_FLAGS = (
-    doctest.ELLIPSIS |
-    doctest.NORMALIZE_WHITESPACE |
-    doctest.REPORT_NDIFF)
-
-
-def additional_tests():
-    "Run the doc tests (README.txt and docs/*, if any exist)"
-    doctest_files = [
-        os.path.abspath(resource_filename('lazr.config', 'README.txt'))]
-    if resource_exists('lazr.config', 'docs'):
-        for name in resource_listdir('lazr.config', 'docs'):
-            if name.endswith('.txt'):
-                doctest_files.append(
-                    os.path.abspath(
-                        resource_filename('lazr.config', 'docs/%s' % name)))
-    kwargs = dict(module_relative=False, optionflags=DOCTEST_FLAGS)
-    atexit.register(cleanup_resources)
-    return unittest.TestSuite((
-        doctest.DocFileSuite(*doctest_files, **kwargs)))