Updated to the 0.7.9x series (FFe LP: #531518)

[ Julian Andres Klode ]
* python/generic.cc:
  - Fix a memory leak when using old attribute names.
* debian/control:
  - Change priority to standard, keep -doc and -dev on optional.
[ Michael Vogt ]
* apt/cache.py:
  - make cache open silent by default (use apt.progress.base.OpProgress)
* tests/data/aptsources_ports/sources.list:
  - fix ports test-data
* debian/control
  - build against XS-Python-Versions: 2.6, 3.1
* tests/test_apt_cache.py:
  - add simple test for basic cache/dependency iteration
* apt/__init__.py:
  - only show deprecation warnings if PYTHON_APT_DEPRECATION_WARNINGS
    is set in the environment. While we do want to have the new API its
    not feasible to port all apps in the lucid timeframe. Once lucid
    is released we turn the warnings on by default again

* Revert 0.7.93.3 and just set APT::Architecture to i386 for
  test_aptsources; fixes FTBFS on powerpc.
* Pass --exclude=migrate-0.8.py to dh_pycentral; in order to not depend
  on python2.6; but recommend python2.6.
* Use dh_link instead of ln for python-apt-doc (Closes: #573523).
* Pass --link-doc=python-apt to dh_installdocs.
* Install examples to python-apt-doc instead of python-apt.
* tests/test_all.py: Write information header to stderr, not stdout.
* Build documentation only when needed (when building python-apt-doc).
* Move documentation into python-apt-doc (Closes: #572617)
* Build documentation only once on the default Python version.
* python/acquire-item.cc:
  - Add AcquireItem.partialsize member.
* python/apt_pkgmodule.cc:
  - Treat '>>' and '>', '<<' and '<' as identical in check_dep (LP: #535667).
* python/generic.cc:
  - Map UntranslatedDepType to dep_type_untranslated.
* python/tag.cc:
  - Hack the TagFile iterator to not use shared storage (Closes: #572596):
    Scan once, duplicate the section data, and scan again.
* apt/package.py:
  - Create a string class BaseDependency.__dstr which makes '>' equal to
    '>>' and '<' equal to '<<' (compatibility).
  - Use the binary package version in Version.fetch_source() if the
    source version is not specified (i.e. in the normal case).
  - Always return unicode strings in Package.get_changelog (Closes: #572998).
* apt/progress/text.py:
  - Drop InstallProgress, it's useless to keep this alias around.
* apt/progress/old.py:
  - Let the new method call the old one; e.g. status_update() now calls
    self.statusUpdate(). This improves compatibility for sub classes.
* Merge with Ubuntu:
  - util/get_ubuntu_mirrors_from_lp.py:
    + rewritten to use +archivemirrors-rss and feedburner
  - pre-build.sh: update ubuntu mirrors on bzr-buildpackage (and also do this
    for Debian mirrors)
  - add break for packagekit-backend-apt (<= 0.4.8-0ubuntu4)
* tests:
  - test_deps: Add tests for apt_pkg.CheckDep, apt_pkg.check_dep,
    apt_pkg.parse_depends and apt_pkg.parse_src_depends.
* tests/data/aptsources/sources.list.testDistribution:
  - change one mirror which is not on the mirror list anymore.
* utils/get_debian_mirrors.py:
  - Parse Mirrors.masterlist instead of the HTML web page.
* utils/get_ubuntu_mirrors_from_lp.py:
  - Sort the mirror list of each country.
  - Use generic MirrorsFile key instead of per-architecture ones in
    order to fix FTBFS on !amd64 !i386 (Closes: #571752)
[ Julian Andres Klode ]
* Fix some places where the old API was still used:
  - apt/utils.py: Completely ported, previous one was old-API from Ubuntu.
  - apt/cache.py: Use the new progress classes instead of the old ones.
  - apt/package.py: Various smaller issues fixed, probably caused by merge.
* utils/migrate-0.8.py:
  - Improve C++ parsing and add apt.progress.old to the modules, reduces
    false positives.
  - Ship the list of deprecated things in the apt_pkg and apt_inst modules
    inside the script itself, so we don't have to parse the source code
    anymore.
* python:
  - Handle deprecated attributes and methods in the tp_gettattro slot, this
    allows us to easily warn if a deprecated function is used.
* python/tagfile.cc:
  - Implement the iterator protocol in TagFile.
* python/cache.cc:
  - Implement Cache.__len__() and Cache.__contains__() (Closes: #571443).
* data/templates/Debian.info.in:
  - Replace the MatchURI with one that really matches something.
* aptsources/distro.py:
  - Call lsb_release with -idrc instead of --all.
* tests:
  - Fix aptsources tests to use local data files if available.
  - test_all.py: Use local modules instead of system ones if possible.
* data/templates/*.in: Switch MirrorsFile to relative filenames.
  - setup.py: Copy the mirror lists to the build directory
  - aptsources/distinfo.py: Support relative filenames for MirrorsFile.
* debian/rules:
  - Run tests during build time.
* debian/python-apt.install:
  - Install utils/migrate-0.8.py to /usr/share/python-apt/.

[ Michael Vogt ]
* apt/cache.py:
  - call install_progress.startUpdate()/finishUpdate() to keep
    compatibility with older code
* apt/progress/base.py:
  - restore "self.statusfd, self.writefd" type, provide additional
    self.status_stream and self.write_stream file like objects
* python/progress.cc:
  - try to call compatibility functions first, then new functions
[ Julian Andres Klode ]
* Fix reference counting for old progress classes (Closes: #566370).
* apt/cache.py:
  - Fix Cache.update() to not raise errors on successful updates.
* python/progress.cc:
  - Fix some threading issues (add some missing PyCbObj_BEGIN_ALLOW_THREADS)
* python/acquire-item.cc:
  - Support items without an owner set.
* python/tarfile.cc:
  - When extracting, only allocate a new buffer if the old one was too small.
  - Do not segfault if TarFile.go() is called without a member name.
  - Clone all pkgDirStream::Item's so apt_pkg.TarMember object can be used
    outside of the callback function passed to go().
  - If only one member is requested, extract just that one.
* Drop the segfault prevention measures from the Acquire code, as they fail
  to work. A replacement will be added once destruction callbacks are added
  in APT.
* Merge the CppOwnedPyObject C++ class into CppPyObject.
* Remove inline functions from the C++ API, export them instead.
* Localization
  - de.po: Update against new template
* python/arfile.cc:
  - Handle the case where ararchive_new returns NULL in debfile_new.
* apt/progress/base.py:
  - select.error objects do not have an errno attribute (Closes: #568005)
* doc/client-example.cc: Update against the new API.
* Fix typos of separated in multiple files (reported by lintian).
* debian/control:
  - Make python-apt-dev depend on ${misc:Depends} and recommend python-dev.
  - Set Standards-Version to 3.8.4.
[ Michael Vogt ]
[ Julian Andres Klode ]
* Merge debian-sid and debian-experimental.
* Add a tutorial on how to do things which are possible with apt-get,
  like apt-get --print-uris update (cf. #551164).
* Build for Python 2.5, 2.6 and 3.1; 2.6 and 3.1 hit unstable on Jan 16.
  - Use DH_PYCENTRAL=nomove for now because include-links seems broken
* Merge lp:~forest-bond/python-apt/cache-is-virtual-package-catch-key-error
  - Return False in Cache.is_virtual_package if the package does not exist.
* Make all class-level constants have uppercase names.
* Rewrite apt.progress.gtk2 documentation by hand and drop python-gtk2
  build-time dependency.
* aptsources:
  - Make all classes subclasses of object.
  - distro.py: Support Python 3, decode lsb_release results using utf-8.
* apt/progress/base.py:
  - Fix some parsing of dpkg status fd.
* apt/progress/text.py:
  - Replace one print statement with a .write() call.
* Rename apt_pkg.PackageIndexFile to apt_pkg.IndexFile.
[ Colin Watson ]
* apt/progress/__init__.py:
  - Fix InstallProgress.updateInterface() to cope with read() returning 0
    on non-blocking file descriptors (LP: #491027).

* New features:
  - Provide a C++ API in the package python-apt-dev (Closes: #334923).
  - Add apt_pkg.HashString and apt_pkg.IndexRecords (Closes: #456141).
  - Add apt_pkg.Policy class (Closes: #382725).
  - Add apt_pkg.Hashes class.
  - Allow types providing __new__() to be subclassed.
  - Add apt_pkg.DepCache.mark_auto() and apt.Package.mark_auto() methods to
    mark a package as automatically installed.
  - Make AcquireFile a subclass of AcquireItem, thus inheriting attributes.
  - New progress handling in apt.progress.base and apt.progress.text. Still
    missing Qt4 progress handlers.
  - Classes in apt_inst (Closes: #536096)
    + You can now use apt_inst.DebFile.data to access the data.tar.* member
      regardless of its compression (LP: #44493)
* Unification of dependency handling:
  - apt_pkg.parse_[src_]depends() now use CompType instead of CompTypeDeb
    (i.e. < instead of <<) to match the interface of Version.depends_list_str
  - apt_pkg.SourceRecords.build_depends matches exactly the interface of
    Version.depends_list_str just with different keys (e.g. Build-Depends).
    + Closes: #468123 - there is no need anymore for binding CompType or
      CompTypeDeb, because we don't return integer values for CompType
      anymore.
* Bugfixes:
  - Delete pointers correctly, fixing memory leaks (LP: #370149).
  - Drop open() and close() in apt_pkg.Cache as they cause segfaults.
  - Raise ValueError in AcquireItem if the Acquire process is shut down
    instead of segfaulting.
* Other stuff:
  - Merge releases 0.7.10.4 - 0.7.12.1 from unstable.
  - Merge Configuration,ConfigurationPtr,ConfigurationSub into one type.
  - Simplify the whole build process by using a single setup.py.
  - The documentation has been restructured and enhanced with tutorials.
  - Only recommend lsb-release instead of depending on it. Default to
    Debian unstable if lsb_release is not available.
[ Julian Andres Klode ]
* Rename where needed according to PEP 8 conventions (Closes: #481061)
* Where possible, derive apt.package.Record from collections.Mapping.
* ActionGroups can be used as a context manager for the 'with' statement.
* utils/migrate-0.8.py: Helper to check Python code for deprecated functions,
  attributes,etc. Has to be run from the python-apt source tree, but can be
  used for all Python code using python-apt.
* debian/control: Only recommend libjs-jquery (Closes: #527543).
[ Stefano Zacchiroli ]
* debian/python-apt.doc-base: register the documentation with the
  doc-base system (Closes: #525134)
[ Sebastian Heinlein ]
* apt/package.py: Add Package.get_version() which returns a Version instance
  for the given version string or None (Closes: #523998)
* Introduce support for Python 3 (Closes: #523645)
* Support the 'in' operator (e.g. "k in d") in Configuration{,Ptr,Sub}
  objects (e.g. apt_pkg.Config) and in TagSections (apt_pkg.ParseSection())
* Replace support for file objects with a more generic support for any object
  providing a fileno() method and for file descriptors (integers).
* Add support for the Breaks fields
* Only create Package objects when they are requested, do not keep them in
  a dict. Saves 10MB for 25,000 packages on my machine.
* apt/package.py: Allow to set the candidate of a package (Closes: #523997)
  - Support assignments to the 'candidate' property of Package objects.
  - Initial patch by Sebastian Heinlein
[ Michael Vogt ]
* data/templates/Ubuntu.info.in:
  - make armel point to ports.ubuntu.com (LP: #531876)
[ Emmet Hikory ]
* data/templates/Ubuntu.info.in:
  - refactor to use ports by default for gutsy and newer releases
  - Set appropriate exceptions to defaults for warty-lucid
* Drop build dependency on python2.4.
* apt/utils.py:
  - add some misc utils like get_release_filename_for_pkg()
[ Michael Vogt ]
* apt/cache.py: 
  - improved docstring for the cache
  - add "enhances" property
* data/templates/Ubuntu.info.in:
  - add lucid
* python/cache.cc:
  - add UntranslatedDepType attribute to DependencyType
  - add DepTypeEnum that returns a value from 
    {DepDepends, DepPreDepends, ...}
* python/apt_pkgmodule.cc:
  - add DepDpkgBreaks, DepEnhances constants
* doc/source/apt_pkg/{cache.rst, index.rst}:
  - update documentation as well
* Fix FTBFS with python-debian (>= 0.1.13) on Python 2.4 by not using it to
  get a version number in setup.py (Closes: #523473)
* apt/package.py:
  - (Package.candidateRecord): Fix missing 'd' in 'record'
  - (DeprecatedProperty.__get__): Only warn when used on objects, this
    makes it easier to use e.g. pydoc,sphinx,pychecker.
* Merged python-apt consolidation branch by Sebastian
  Heinlein (many thanks)
* apt/cache.py:
  - new method "isVirtualPackage()"
  - new method "getProvidingPackages()"
  - new method "getRequiredDownload()"
  - new method "additionalRequiredSpace()"
* apt/debfile.py:
  - move a lot of the gdebi code into this file, this
    provides interfaces for querrying and installing
    .deb files and .dsc files
* apt/package.py:
  - better description parsing
  - new method "installedFiles()"
  - new method "getChangelog()"
* apt/gtk/widgets.py:
  - new gobject GOpProgress
  - new gobject GFetchProgress
  - new gobject GInstallProgress
  - new gobject GDpkgInstallProgress
  - new widget GtkAptProgress
* doc/examples/gui-inst.py:
  - updated to use the new widgets
* debian/control:
  - add suggests for python-gtk2 and python-vte
* setup.py:
  - build html/ help of the apt and aptsources modules
    into /usr/share/doc/python-apt/html
* apt/__init__.py:
  - remove the future warning
* Non-maintainer upload.
* data/templates/Debian.info.in: Set the BaseURI to security.debian.org for
  lenny/updates, etch/updates and sarge/updates. (Closes: #503237)
* data/templates/Debian.info.in:
  - add 'lenny' template info (closes: #476364)
* aptsources/distinfo.py:
  - fix template matching for arch specific code (LP: #244093)

4 files changed, 521 insertions, 0 deletions

diff --git a/doc/source/tutorials/apt-cdrom.rst b/doc/source/tutorials/apt-cdrom.rst
new file mode 100644
index 00000000..0561e082
--- /dev/null
+++ b/doc/source/tutorials/apt-cdrom.rst
@@ -0,0 +1,156 @@
+Writing your own apt-cdrom
+==========================
+:Author: Julian Andres Klode <jak@debian.org>
+:Release: |release|
+:Date: |today|
+
+This article explains how to utilise python-apt to build your own clone of the
+:command:`apt-cdrom` command. To do this, we will take a look at the
+:mod:`apt.cdrom` and :mod:`apt.progress.text` modules, and we will learn how
+to use apt_pkg.parse_commandline to parse commandline arguments. The code shown
+here works on Python 2 and Python 3.
+
+Basics
+------
+The first step in building your own :command:`apt-cdrom` clone is to import the
+:mod:`apt` package, which will import :mod:`apt.cdrom` and
+:mod:`apt.progress.text`::
+
+    import apt
+
+Now we have to create a new :class:`apt.cdrom.Cdrom` object and pass to it an
+:class:`apt.progress.text.CdromProgress` object, which is responsible for
+displaying the progress and asking questions::
+
+    cdrom = apt.Cdrom(apt.progress.text.CdromProgress())
+
+Now we have to choose the action, depending on the given options on the
+command line. For now, we simply use the value of ``sys.argv[1]``::
+
+    import sys
+    if sys.argv[1] == 'add':
+        cdrom.add()
+    elif sys.argv[1] == 'ident':
+        cdrom.ident()
+
+Now we have a basic :command:`apt-cdrom` clone which can add and identify
+CD-ROMs::
+
+    import sys
+
+    import apt
+
+    cdrom = apt.Cdrom(apt.progress.text.CdromProgress())
+    if sys.argv[1] == 'add':
+        cdrom.add()
+    elif sys.argv[1] == 'ident':
+        cdrom.ident()
+
+Advanced example with command-line parsing
+-------------------------------------------
+Our example clearly misses a way to parse the commandline in a correct
+manner. Luckily, :mod:`apt_pkg` provides us with a function to do this:
+:func:`apt_pkg.parse_commandline`. To use it, we add ``import apt_pkg`` right
+after import apt::
+
+    import sys
+
+    import apt_pkg
+    import apt
+
+
+:func:`apt_pkg.parse_commandline` is similar to :mod:`getopt` functions, it
+takes a list of recognized options and the arguments and returns all unknown
+arguments. If it encounters an unknown argument which starts with a leading
+'-', the function raises an error indicating that the option is unknown. The
+major difference is that this function manipulates the apt configuration space.
+
+The function takes 3 arguments. The first argument is an
+:class:`apt_pkg.Configuration` object. The second argument is a list of tuples
+of the form ``(shortopt, longopt, config, type)``, whereas *shortopt* is a
+character indicating the short option name, *longopt* a string indicating the
+corresponding long option (e.g. ``"--help"``), *config* the name of the
+configuration item which should be set and *type* the type of the argument.
+
+For apt-cdrom, we can use the following statement::
+
+    arguments = apt_pkg.parse_commandline(apt_pkg.config,
+                    [('h', "help", "help"),
+                     ('v', "version", "version"),
+                     ('d', "cdrom", "Acquire::cdrom::mount", "HasArg"),
+                     ('r', "rename", "APT::CDROM::Rename"),
+                     ('m', "no-mount", "APT::CDROM::NoMount"),
+                     ('f', "fast", "APT::CDROM::Fast"),
+                     ('n', "just-print", "APT::CDROM::NoAct"),
+                     ('n', "recon", "APT::CDROM::NoAct"),
+                     ('n', "no-act", "APT::CDROM::NoAct"),
+                     ('a', "thorough", "APT::CDROM::Thorough"),
+                     ('c', "config-file", "", "ConfigFile"),
+                     ('o', "option", "", "ArbItem")], args)
+
+
+This allows us to support all options supported by apt-cdrom. The first option
+is --help. As you can see, it omits the fourth field of the tuple; which means
+it is a boolean argument. Afterwards you could use
+``apt_pkg.config.find_b("help")`` to see whether ``--help`` was specified. In
+``('d',"cdrom","Acquire::cdrom::mount","HasArg")`` the fourth field is
+``"HasArg"``. This means that the option has an argument, in this case the
+location of the mount pint. ``('c',"config-file","","ConfigFile")`` shows how
+to include configuration files. This option takes a parameter which points to
+a configuration file which will be added to the configuration space.
+('o',"option","","ArbItem") is yet another type of option, which allows users
+to set configuration options on the commandline.
+
+Now we have to check whether help or version is specified, and print a message
+and exit afterwards. To do this, we use :meth:`apt_pkg.Configuration.find_b`
+which returns ``True`` if the configuration option exists and evaluates to
+``True``::
+
+    if apt_pkg.config.find_b("help"):
+        print("This should be a help message")
+        sys.exit(0)
+    elif apt_pkg.config.find_b("version"):
+        print("Version blah.")
+        sys.exit(0)
+
+
+Now we are ready to create our progress object and our cdrom object. Instead
+of using :class:`apt.Cdrom` like in the first example, we will use
+:class:`apt_pkg.Cdrom` which provides a very similar interface. We could also
+use :class:`apt.Cdrom`, but `apt.Cdrom` provides options like *nomount* which
+conflict with our commandline parsing::
+
+    progress = apt.progress.text.CdromProgress()
+    cdrom = apt_pkg.Cdrom()
+
+
+Now we have to do the action requested by the user on the commandline. To see
+which option was requested, we check the list ``arguments`` which was returned
+by ``apt_pkg.parse_commandline`` above, and afterwards call ``cdrom.add`` or
+``cdrom.ident``::
+
+    if apt_pkg.config.find_b("help"):
+        print("This should be a help message")
+        sys.exit(0)
+    elif apt_pkg.config.find_b("version"):
+        print("Version blah.")
+        sys.exit(0)
+
+    if not arguments:
+        sys.stderr.write('E: No operation specified\n')
+        sys.exit(1)
+    elif arguments[0] == 'add':
+        cdrom.add(progress)
+    elif arguments[0] == 'ident':
+        cdrom.ident(progress)
+    else:
+        sys.stderr.write('E: Invalid operation %s\n' % arguments[0])
+        sys.exit(1)
+
+
+After putting all our actions into a main() function, we get a completely
+working apt-cdrom clone, which just misses useful ``--help`` and ``--version``
+options. If we add a function show_help(), we get an even more complete
+apt-cdrom clone:
+
+.. literalinclude:: ../examples/apt-cdrom.py
diff --git a/doc/source/tutorials/apt-get.rst b/doc/source/tutorials/apt-get.rst
new file mode 100644
index 00000000..575f0c46
--- /dev/null
+++ b/doc/source/tutorials/apt-get.rst
@@ -0,0 +1,45 @@
+Doing stuff :command:`apt-get` does
+===================================
+:Author: Julian Andres Klode <jak@debian.org>
+:Release: |release|
+:Date: |today|
+
+The following article will show how you can use python-apt to do actions done
+by the :command:`apt-get` command.
+
+
+Printing the URIs of all index files
+------------------------------------
+We all now that we can print the URIs of all our index files by running a
+simple ``apt-get -s --print-uris update``. We can do the same. Responsible for
+the source entries is the class :class:`apt_pkg.SourceList`, which can be
+combined with an :class:`apt_pkg.Acquire` object using :meth:`get_indexes`.
+
+First of all, we have to create the objects::
+
+    acquire = apt_pkg.Acquire()
+    slist = apt_pkg.SourceList()
+
+Now we have to parse /etc/apt/sources.list and its friends, by using
+:meth:`apt_pkg.SourceList.read_main_list`::
+    slist.read_main_list()
+
+Now the **slist** object knows about the location of the indexes. We now have
+to load those indexes into the *acquire* object by calling
+:meth:`apt_pkg.SourceList.get_indexes`::
+
+    slist.get_indexes(acquire, True)
+
+The first argument is the acquire object into which we will load these indexes,
+and the second argument means that we want to fetch all indexes. Now the only
+thing left to do is iterating over the list of items and printing out their
+URIs. Luckily, there is :attr:`apt_pkg.Acquire.items` which allows us to
+iterate over the items::
+
+    for item in acquire.items:
+        print item.desc_uri
+
+In the end a program could look like this:
+
+.. literalinclude:: ../examples/update-print-uris.py
+
diff --git a/doc/source/tutorials/contributing.rst b/doc/source/tutorials/contributing.rst
new file mode 100644
index 00000000..f68d626e
--- /dev/null
+++ b/doc/source/tutorials/contributing.rst
@@ -0,0 +1,312 @@
+Contributing to python-apt
+==========================
+:Author: Julian Andres Klode <jak@debian.org>
+:Release: |release|
+:Date: |today|
+
+Let's say you need a new feature, you can develop it, and you want to get it
+included in python-apt. Then be sure to follow the following guidelines.
+
+Available branches
+-------------------
+First of all, let's talk a bit about the bzr branches of python-apt. In the
+following parts, we will assume that you use bzr to create your changes and
+submit them.
+
+**mvo:** http://people.ubuntu.com/~mvo/bzr/python-apt/mvo
+    This is Michael Vogt's branch. Most of the development of apt happens here,
+    as he is the lead maintainer of python-apt.
+
+    This branch is also available from Launchpads super mirror, via
+    ``lp:python-apt``. Checkouts from Launchpad are generally faster and can
+    use the bzr protocoll.
+
+    VCS-Browser: https://code.launchpad.net/~mvo/python-apt/python-apt--mvo
+
+**debian-sid:** http://bzr.debian.org/apt/python-apt/debian-sid
+    This is the official Debian branch of python-apt. All code which will be
+    uploaded to Debian is here. It is not as up-to-date as the mvo branch,
+    because this branch often gets updated just right before the release
+    happens.
+
+    VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-sid/changes
+
+**debian-experimental:** http://bzr.debian.org/apt/python-apt/debian-experimental
+
+    This is another official Debian branch of python-apt, for releases
+    targetted at Debian experimental. This branch may contain unstable code
+    and may thus not work correctly.
+
+    VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-experimental/changes
+
+**jak:** http://bzr.debian.org/users/jak/python-apt/jak
+    This is Julian Andres Klode's (the documentation author's) branch. This
+    is the place where cleanup and documentation updates happen. It is based
+    off debian-sid or mvo.
+
+    VCS-Browser: http://bzr.debian.org/loggerhead/users/jak/python-apt/jak/changes
+
+**ubuntu:** ``lp:~ubuntu-core-dev/python-apt/ubuntu``
+    This is the official Ubuntu development branch. The same notes apply as
+    for the debian-sid branch above.
+
+    VCS-Browser: https://code.launchpad.net/~ubuntu-core-dev/python-apt/ubuntu
+
+
+.. highlightlang:: c
+
+C++ Coding style
+----------------
+This document gives coding conventions for the C++ code comprising
+the C++ extensions of Python APT.  Please see the companion
+informational PEP describing style guidelines for Python code (:PEP:`8`).
+
+Note, rules are there to be broken.  Two good reasons to break a
+particular rule:
+
+    (1) When applying the rule would make the code less readable, even
+        for someone who is used to reading code that follows the rules.
+
+    (2) To be consistent with surrounding code that also breaks it
+        (maybe for historic reasons) -- although this is also an
+        opportunity to clean up someone else's mess (in true XP style).
+
+This part of the document is derived from :PEP:`7` which was written by
+Guido van Rossum.
+
+
+C++ dialect
+^^^^^^^^^^^
+
+- Use ISO standard C++ (the 1998 version of the standard).
+
+- All function declarations and definitions must use full
+  prototypes (i.e. specify the types of all arguments).
+
+- Use C++ style // one-line comments where useful.
+
+- No compiler warnings with ``gcc -std=c++98 -Wall -Wno-write-strings``. There
+  should also be no errors with ``-pedantic`` added.
+
+
+Code lay-out
+^^^^^^^^^^^^
+
+- Use 3-space indents, in files that already use them. In new source files,
+  that were created after this rule was introduced, use 4-space indents.
+
+  At some point, the whole codebase may be converted to use only
+  4-space indents.
+
+- No line should be longer than 79 characters.  If this and the
+  previous rule together don't give you enough room to code, your
+  code is too complicated -- consider using subroutines.
+
+- No line should end in whitespace.  If you think you need
+  significant trailing whitespace, think again -- somebody's
+  editor might delete it as a matter of routine.
+
+- Function definition style: function name in column 2, outermost
+  curly braces in column 1, blank line after local variable
+  declarations::
+
+    static int extra_ivars(PyTypeObject *type, PyTypeObject *base)
+    {
+        int t_size = PyType_BASICSIZE(type);
+        int b_size = PyType_BASICSIZE(base);
+
+        assert(t_size >= b_size); /* type smaller than base! */
+        ...
+        return 1;
+    }
+
+- Code structure: one space between keywords like 'if', 'for' and
+  the following left paren; no spaces inside the paren; braces as
+  shown::
+
+    if (mro != NULL) {
+        ...
+    }
+    else {
+        ...
+    }
+
+- The return statement should *not* get redundant parentheses::
+
+    return Py_None; /* correct */
+    return(Py_None); /* incorrect */
+
+- Function and macro call style: ``foo(a, b, c)`` -- no space before
+  the open paren, no spaces inside the parens, no spaces before
+  commas, one space after each comma.
+
+- Always put spaces around assignment, Boolean and comparison
+  operators.  In expressions using a lot of operators, add spaces
+  around the outermost (lowest-priority) operators.
+
+- Breaking long lines: if you can, break after commas in the
+  outermost argument list.  Always indent continuation lines
+  appropriately, e.g.::
+
+    PyErr_Format(PyExc_TypeError,
+            "cannot create '%.100s' instances",
+            type->tp_name);
+
+- When you break a long expression at a binary operator, the
+  operator goes at the end of the previous line, e.g.::
+
+    if (type->tp_dictoffset != 0 && base->tp_dictoffset == 0 &&
+        type->tp_dictoffset == b_size &&
+        (size_t)t_size == b_size + sizeof(PyObject *))
+        return 0; /* "Forgive" adding a __dict__ only */
+
+- Put blank lines around functions, structure definitions, and
+  major sections inside functions.
+
+- Comments go before the code they describe.
+
+- All functions and global variables should be declared static
+  unless they are to be part of a published interface
+
+
+Naming conventions
+^^^^^^^^^^^^^^^^^^
+
+- Use a ``Py`` prefix for public functions; never for static
+  functions.  The ``Py_`` prefix is reserved for global service
+  routines like ``Py_FatalError``; specific groups of routines
+  (e.g. specific object type APIs) use a longer prefix,
+  e.g. ``PyString_`` for string functions.
+
+- Public functions and variables use MixedCase with underscores,
+  like this: ``PyObject_GetAttr``, ``Py_BuildValue``, ``PyExc_TypeError``.
+
+- Internal functions and variables use lowercase with underscores, like
+  this: ``hashes_get_sha1.``
+
+- Occasionally an "internal" function has to be visible to the
+  loader; we use the _Py prefix for this, e.g.: ``_PyObject_Dump``.
+
+- Macros should have a MixedCase prefix and then use upper case,
+  for example: ``PyString_AS_STRING``, ``Py_PRINT_RAW``.
+
+
+Documentation Strings
+^^^^^^^^^^^^^^^^^^^^^
+- The first line of each function docstring should be a "signature
+  line" that gives a brief synopsis of the arguments and return
+  value.  For example::
+
+    PyDoc_STRVAR(myfunction__doc__,
+    "myfunction(name: str, value) -> bool\n\n"
+    "Determine whether name and value make a valid pair.");
+
+  The signature line should be formatted using the format for function
+  annotations described in :PEP:`3107`, whereas the annotations shall reflect
+  the name of the type (e.g. ``str``). The leading ``def`` and the trailing
+  ``:`` as used for function definitions must not be included.
+
+  Always include a blank line between the signature line and the
+  text of the description.
+
+  If the return value for the function is always ``None`` (because
+  there is no meaningful return value), do not include the
+  indication of the return type.
+
+- When writing multi-line docstrings, be sure to always use
+  string literal concatenation::
+
+    PyDoc_STRVAR(myfunction__doc__,
+    "myfunction(name, value) -> bool\n\n"
+    "Determine whether name and value make a valid pair.");
+
+
+Python Coding Style
+-------------------
+The coding style for all code written in python is :PEP:`8`. Exceptions from
+this rule are the documentation, where code is sometimes formatted differently
+to explain aspects, and functions provided for 0.7 compatibility purposes.
+
+When writing code, use tools like pylint, pyflakes, pychecker and pep8.py from
+http://svn.browsershots.org/trunk/devtools/pep8/ to verify that your code is
+OK. Fix all the problems which seem reasonable, and mention the unfixed issues
+when asking for merge.
+
+In order to make the automatic generation of Python 3 code using 2to possible,
+code written in Python may not utilize any functionality unsupported by 2to3 or
+deprecated as of Python 2.6.
+
+Submitting your patch
+---------------------
+First of all, the patch you create should be based against the most current
+branch of python-apt (debian-sid or debian-experimental). If it is a bugfix,
+you should probably use debian-sid. If you choose the wrong branch, we will
+ask you to rebase your patches against the correct one.
+
+Once you have made your change, check that it:
+
+    * conforms to :PEP:`8` (checked with pep8.py). It should, at least not
+      introduce new errors. (and never have whitespace at end of line)
+    * produces no new errors in pychecker, pyflakes and pylint (unless you
+      can't fix them, but please tell so when requesting the merge, so it can
+      be fixed before hitting one of the main branches).
+    * does not change the behaviour of existing code in a non-compatible way.
+
+If your change follows all points of the checklist, you can commit it to your
+repository. (You could commit it first, and check later, and then commit the
+fixes, but commits should be logical and it makes no sense to have to commits
+for one logical unit).
+
+Once you have made all your changes,  you can run ``bzr send -o patch-name``
+to create a so called *merge-directive*, which contains your changes and
+allows us to preserve the history of your changes. (But please replace patch-name
+with something useful).
+
+Now report a bug against the python-apt package, attach the merge directive
+you created in the previous step, and tag it with 'patch'. It might also be
+a good idea to prefix the bug report with '[PATCH]'.
+
+If your patch introduces new functions, parameters, etc. , but does not update
+the content of this documentation, please CC. jak@debian.org, and add a short
+notice to the bug report. Also see `Documentation updates`
+
+Once your patch got merged, you can *pull* the branch into which it has been
+merged into your local one. If you have made changes since you submitted your
+patch, you may need to *merge* the branch instead.
+
+.. note::
+
+    If you plan to work on python-apt for a longer time, it may be a good
+    idea to publish your branch somewhere. Alioth (http://alioth.debian.org)
+    and Launchpad (https://launchpad.net) provide bzr hosting. You can also
+    use any webspace with ftp or sftp connection (for the upload). Then you do
+    not need to send *merge directives*, but you can point to your branch
+    instead.
+
+
+Documentation updates
+---------------------
+If you want to update the documentation, please follow the procedure as written
+above. You can send your content in plain text, but reStructuredText is the
+preferred format. I (Julian Andres Klode) will review your patch and include
+it.
+
+.. highlightlang:: sh
+
+Example patch session
+----------------------
+In the following example, we edit a file, create a merge directive (an enhanced
+patch), and report a wishlist bug with this patch against the python-apt
+package::
+
+    user@pc:~$ bzr clone http://bzr.debian.org/apt/python-apt/debian-sid/
+    user@pc:~$ cd debian-sid
+    user@pc:~/debian-sid$ editor FILES
+    user@pc:~/debian-sid$ pep8.py FILES # PEP 8 check, see above.
+    user@pc:~/debian-sid$ pylint -e FILES # Check with pylint
+    user@pc:~/debian-sid$ pyflakes FILES  # Check with pyflakes
+    user@pc:~/debian-sid$ pychecker FILES # Check with pychecker
+    user@pc:~/debian-sid$ bzr commit
+    user@pc:~/debian-sid$ bzr send -o my-patch
+    user@pc:~/debian-sid$ reportbug --severity=wishlist --tag=patch --attach=my-patch python-apt
+    user@pc:~/debian-sid$ # Add --list-cc=jak@debian.org if you change docs.
diff --git a/doc/source/tutorials/index.rst b/doc/source/tutorials/index.rst
new file mode 100644
index 00000000..06d31c6b
--- /dev/null
+++ b/doc/source/tutorials/index.rst
@@ -0,0 +1,8 @@
+Tutorials
+=========
+
+.. toctree::
+    :maxdepth: 1
+    :glob:
+
+    *