Import Upstream version 1.1.1+bzr982

8 files changed, 863 insertions, 0 deletions

diff --git a/doc/source/_ext/signals.py b/doc/source/_ext/signals.py
new file mode 100644
index 0000000..0e7cbee
--- /dev/null
+++ b/doc/source/_ext/signals.py
@@ -0,0 +1,20 @@
+"""Adds a new directive signal for GObject signals"""
+
+import re
+
+from sphinx import addnodes
+
+signal_re = re.compile(r"([a-zA-Z-]+)\s->(.*)")
+
+def parse_signal(env, sig, signode):
+    match = signal_re.match(sig)
+    if not match:
+        signode += addnodes.desc_name(sig, sig)
+        return sig
+    name, args = match.groups()
+    signode += addnodes.desc_name(name, name)
+    signode += addnodes.desc_returns(args.strip(), args.strip())
+    return name
+
+def setup(app):
+    app.add_description_unit("signal", "sig", "pair: %s; signal", parse_signal)
diff --git a/doc/source/aptdaemon.client.rst b/doc/source/aptdaemon.client.rst
new file mode 100644
index 0000000..5cd04eb
--- /dev/null
+++ b/doc/source/aptdaemon.client.rst
@@ -0,0 +1,134 @@
+:mod:`aptdaemon.client` --- The client module
+=============================================
+
+Introduction
+------------
+
+Aptdaemon comes with a client module which provides a smoother interface on top
+of the D-Bus interface. It provides GObjects of the daemon and each transaction.
+
+
+.. _life_cycle:
+
+Life cycle of a transaction based action
+----------------------------------------
+
+At first you initialize an AptClient instance.
+
+    >>> from aptdaemon import client
+    >>>
+    >>> apt_client = client.AptClient()
+
+Secondly you call the whished action, e.g. updating the package cache. It will
+give you a new transaction instance.
+
+    >>> transaction = apt_client.update()
+
+The transaction has not been started yet. So you can make some further 
+adjustements to it, e.g. setting a different language:
+
+    >>> transaction.set_locale("de_DE")
+
+... or setup the monitoring of the transaction:
+
+    >>> transaction.connect("finished", on_transaction_finished)
+
+You can then put the transaction on the queue by calling its :meth:`run()`
+method:
+
+    >>> transaction.run()
+
+If you don't need the underlying transcation instance of an action, you can
+alternatively set the wait argument to True. The AptClient method will return
+after the transaction is done:
+
+    >>> apt_client.update_cache(wait=True)
+
+This can also be used with asynchronous programming, see below.
+
+
+Asynchronous programming
+------------------------
+
+In the above examples simple synchronous calls have been made to the D-Bus. 
+Until these calls return your whole application is blocked/frozen.
+In the case of password prompts this can be quite long. So aptdaemon supports
+the following asynchronous styles:
+
+D-Bus style callbacks
+^^^^^^^^^^^^^^^^^^^^^
+
+Since the client module is basically a wrapper around D-Bus calls, it provides
+a pair of reply_handler and error_handler for each method. You are perhaps
+already familiar with those if you have written a Python D-Bus client before:
+
+    >>> def run(trans):
+    ...     trans.run(reply_handler=trans_has_started, error_handler=on_error)
+    ...
+    >>> def trans_has_started():
+    ...     pass
+    ...
+    >>> def on_error(error):
+    ...     raise error
+    ...
+    >>> client = AptClient()
+    >>> client.update(reply_handler=run, error_handler=on_error)
+
+
+Deferred callbacks
+^^^^^^^^^^^^^^^^^^
+
+Aptdaemon uses a simplified version of Twisted deferreds internally, called
+python-defer. But you can also make use of them in your application.
+
+The inline_callbacks decorator of python-defer allows to write asynchronous
+code in a synchronous way:
+
+    >>> @defer.inline_callbacks
+    ... def update_cache():
+    ...     apt_client = client.AptClient()
+    ...     try:
+    ...         transaction = yield apt_client.update()
+    ...     except errors.NotAuthorizedError:
+    ...         print "You are not allowed to update the cache!"
+    ...         return
+    ...     yield transaction.set_locale("de_DE")
+    ...     yield transaction.run()
+    ...     print "Transaction has started"
+
+
+.. _chaining:
+
+Chaining Transactions
+---------------------
+
+It is possible to chain transactions. This allows to add a simple
+dependency relation, e.g. you want to add a new repository, update
+the cache and finally install a new package.
+
+        >>> client = aptdaemon.client.AptClient()
+        >>> trans1 = client.add_repository("deb", [...])
+        >>> trans2 = client.update_cache()
+        >>> trans3 = client.install_packages(["new-package"])
+        >>> trans2.run_after(trans1)
+        >>> trans3.run_after(trans2)
+        >>> trans1.run()
+
+If a transaction in a chain fails all other ones which follow will
+fail too with the :data:`enums.EXIT_PREVIOUS_FAILED` exit state.
+
+Class Reference
+---------------
+
+.. autoclass:: aptdaemon.client.AptClient
+    :members:
+
+.. autoclass:: aptdaemon.client.AptTransaction
+    :members:
+
+Function Reference
+------------------
+
+.. autofunction:: aptdaemon.client.get_transaction
+
+.. autofunction:: aptdaemon.client.get_aptdaemon
diff --git a/doc/source/aptdaemon.enums.rst b/doc/source/aptdaemon.enums.rst
new file mode 100644
index 0000000..5644820
--- /dev/null
+++ b/doc/source/aptdaemon.enums.rst
@@ -0,0 +1,5 @@
+:mod:`aptdaemon.enums` --- The enums module
+===========================================
+
+.. automodule:: aptdaemon.enums
+    :members:
diff --git a/doc/source/aptdaemon.gtk3widgets.rst b/doc/source/aptdaemon.gtk3widgets.rst
new file mode 100644
index 0000000..d54955a
--- /dev/null
+++ b/doc/source/aptdaemon.gtk3widgets.rst
@@ -0,0 +1,5 @@
+:mod:`aptdaemon.gtk3widgets` --- The gtk3widgets module
+=====================================================
+
+.. automodule:: aptdaemon.gtk3widgets
+    :members:
diff --git a/doc/source/conf.py b/doc/source/conf.py
new file mode 100644
index 0000000..37b4882
--- /dev/null
+++ b/doc/source/conf.py
@@ -0,0 +1,199 @@
+# -*- coding: utf-8 -*-
+#
+# aptdaemon documentation build configuration file, created by
+# sphinx-quickstart on Thu Aug 26 06:52:32 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+sys.path.insert(0, os.path.abspath('../../'))
+sys.path.insert(0, os.path.abspath('_ext/'))
+
+# -- General configuration -----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.coverage', 'sphinx.ext.ifconfig', 'signals']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'aptdaemon'
+copyright = u'2010, Sebastian Heinlein'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '0.4'
+# The full version, including alpha/beta/rc tags.
+release = '0.4.0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of documents that shouldn't be included in the build.
+#unused_docs = []
+
+# List of directories, relative to source directory, that shouldn't be searched
+# for source files.
+exclude_trees = []
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  Major themes that come with
+# Sphinx are currently 'default' and 'sphinxdoc'.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_use_modindex = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = ''
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'aptdaemondoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'aptdaemon.tex', u'aptdaemon Documentation',
+   u'Sebastian Heinlein', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_use_modindex = True
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
diff --git a/doc/source/dbus.rst b/doc/source/dbus.rst
new file mode 100644
index 0000000..7d4f71a
--- /dev/null
+++ b/doc/source/dbus.rst
@@ -0,0 +1,410 @@
+The D-Bus API of the aptdaemon
+==============================
+
+Aptdaemon provides two D-Bus interfaces on the system bus.
+
+org.debian.apt --- The aptdaemon interface
+------------------------------------------
+
+This is the main interface which allows you to perform package managing tasks. 
+It is proivded by the aptdaemon object at ``/org/debian/apt``. 
+
+There are two kind of tasks: ones which are performed immediately and ones 
+which are queued up in transaction and performed in a sequence.
+
+Non-transaction based methods
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. automethod:: aptdaemon.core.AptDaemon.GetTrustedVendorKeys() -> array(string)
+
+.. automethod:: aptdaemon.core.AptDaemon.Quit()
+
+
+Transaction based methos
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Instead of performing the task immediately, a new transaction will be created
+and the method will return the D-Bus path of it. Afterwards you can simulate
+the transaction or put it on the queue.
+
+:ref:`life_cycle` and :ref:`chaining` are described in the Python client
+documentation with code examples.
+
+.. automethod:: aptdaemon.core.AptDaemon.UpdateCache() -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.UpdateCachePartially(sources_list : string) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.AddRepository(src_type : string, uri : string, dist : string, comps : array(string), comment : string, sourcesfile : string) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.EnableDistroComponent(component : string) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.InstallFile(path : string, force : boolean) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.InstallPackages(package_names : array(string)) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.RemovePackages(package_names : array(string)) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.UpgradePackages(package_names : array(string)) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.CommitPackages(install : array(string), reinstall : array(string), remove : array(string), purge : array(string), upgrade : array(string), downgrade : array(string)) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.UpgradeSystem(safe_mode : boolean) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.FixIncompleteInstall() -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.FixBrokenDepends() -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.AddVendorKeyFromKeyserver(keyid : string, keyserver : string) -> string
+
+.. automethod:: aptdaemon.core.AptDaemon.AddVendorKeyFromFile(path : string) -> string
+
+
+Signals
+^^^^^^^
+
+The following singal can be emitted on the org.debian.apt interface.
+
+.. automethod:: aptdaemon.core.AptDaemon.ActiveTransactionsChanged(current : string, queued : array(string))
+
+Properties
+^^^^^^^^^^
+
+The daemon interface provides a set of properties which can be accessed and modified through :meth:`Set()`, :meth:`Get()` and :meth:`GetAll()` methods of the ``org.freedesktop.DBus.Properties`` interface.
+See the `D-Bus specification <http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_ for more details.
+
+The following properties are available:
+
+.. attribute:: AutoCleanInterval : i
+
+    The interval in days in which the cache of downloaded packages should
+    should be cleaned. A value of 0 disables this feature.
+
+    *writable*
+
+
+.. attribute:: AutoDownload : b
+
+    If available upgrades should be already downloaded in the background.
+    The upgrades won't get installed automatically.
+
+    *writable*
+
+.. attribute:: AutoUpdateInterval : i
+   
+    The interval in days in which the software repositories should be checked
+    for updates. A value of 0 disables the automatic check.
+
+    *writable*
+
+.. attribute:: PopConParticipation : b
+
+    If statistics about installed software and how often it is used should be
+    sent to the distribution anonymously. This helps to determine which
+    software should be shipped on the first install CDROMs and to make software
+    recommendations.
+
+    *writable*
+
+.. attribute:: UnattendedUpgrade : i
+
+    The interval in days in which updates should be installed
+    automatically. A value of 0 disables this feature.
+
+    *writable*
+
+.. attribute:: RebootRequired : b
+
+   Set if a reboot is required in order to complete the update.
+
+    *readonly*
+
+
+org.debian.apt.transaction --- The transaction interface
+--------------------------------------------------------
+
+This is the main interface of a transaction object. It allows to control and
+monitor the transaction. Transactions are created by using the org.debian.apt
+interface of aptdaemon.
+
+The path of a transaction object consists of ``/org/debian/apt/transaction/`` and an unique identifier.
+
+Methods
+^^^^^^^
+
+.. automethod:: aptdaemon.core.Transaction.Run()
+
+.. automethod:: aptdaemon.core.Transaction.RunAfter(tid : string)
+
+.. automethod:: aptdaemon.core.Transaction.Cancel()
+
+.. automethod:: aptdaemon.core.Transaction.Simulate()
+
+.. automethod:: aptdaemon.core.Transaction.ProvideMedium(medium : string)
+
+.. automethod:: aptdaemon.core.Transaction.ResolveConfigFileConflict(config : string, answer : string)
+
+Signals
+^^^^^^^
+
+.. automethod:: aptdaemon.core.Transaction.Finished() -> string
+
+.. automethod:: aptdaemon.core.Transaction.PropertyChanged() -> string, variant
+
+Properties
+^^^^^^^^^^
+
+The transaction interface provides a set of properties which can be accessed and modified through :meth:`Set()`, :meth:`Get()` and :meth:`GetAll()` methods of the ``org.freedesktop.DBus.Properties`` interface.
+See the `D-Bus specification <http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-properties>`_ for more details.
+
+For the documentation of the available string enumerations, see :mod:`aptdaemon.enums`.
+
+The following properties are available:
+
+
+.. attribute:: AllowUnauthenticated : b
+
+    If it is allowed to install not authenticated packages by the transaction.
+    Defaults to False.
+
+    *writable*
+
+.. attribute:: Cancellable : b
+
+    If the transaction can be cancelled at the moment.
+
+    *read-only*
+
+.. attribute:: ConfigFileConflict : (ss)
+
+    If the transaction waits for the resolution of a configuration file
+    conflict, this property contains an array of the path to the old and
+    the path to the new configuration file. See
+    :meth:`ResolveConfigFileConflict()`.
+
+    *read-only*
+ 
+.. attribute:: DebconfSocket : s
+
+    The path to the socket which should be used to proxy debconf communication
+    to the user.
+
+    *writable*
+
+.. attribute:: Dependencies : (asasasasasasas)
+
+    Array of package groups which will be modified as dependencies:
+
+    * array of the packages to install
+    * array of the packages to re-install
+    * array of the packages to remove
+    * array of the packages to purge
+    * array of the packages to upgrade
+    * array of the packages to downgrade
+    * array of the packages to not upgrade (keep)
+
+    The packages are specified by their name and a version number
+    separated by an "=", e.g. "xterm=261-1".
+    The dependencies are calculated after :meth:`Simulate()` or :meth:`Run()`
+    was called.
+
+    *read-only*
+
+.. attribute:: Download : x
+
+    The required download size in Bytes.
+
+    The property is available after :meth:`Simulate()` or :meth:`Run()` has
+    been called.
+
+    *read-only*
+
+.. attribute:: Error : (ss)
+
+    If the transaction failed this property contains an array of the error
+    code, e.g. ``error-no-lock`` and a detailed error message.
+
+    *read-only*
+
+.. attribute:: ExitState : s
+
+    If the transaction is completed it contains the exit status enum of
+    the transaction, e.g. ``exit-failed``. If the transaction has not yet
+    been completed it is ``exit-unfinished``.
+
+    *read-only*
+
+.. attribute:: HttpProxy : s
+
+    The URL of an http proxy which should be used for downloads by
+    the transaction, e.g. ``http://proxy:8080``.
+
+    *writable*
+
+.. attribute:: Locale : s
+
+    The locale which is used to translate messages, e.g. ``de_DE@UTF-8``.
+
+    *writable*
+
+.. attribute:: MetaData : a{sv}
+
+    The meta data dictionary allows client applications to store additional
+    data persistently in the transaction object. The key has to be a string
+    and be prefixed by an underscore separated identifier of the client 
+    application, e.g. Software Center uses ``sc_app`` to store the application
+    corresponding to the transaction.
+
+    If a dict is written to the property it will be merged with the existing
+    one. It is not allowed to override already existing keys.
+
+    *writable*
+
+.. attribute:: Progress : i
+   
+    The progress in percent of the transaction.
+
+    *read-only*
+
+.. attribute:: Packages : (asasasasasas)
+
+    Array of package groups which have been specified by the user intially
+    to be modified:
+
+    * array of the packages to install
+    * array of the packages to re-install
+    * array of the packages to remove
+    * array of the packages to purge
+    * array of the packages to upgrade
+    * array of the packages to downgrade
+
+    The packages are specified by their name and an optional version number
+    separated by an "=", e.g. "xterm=261-1". Furthermore if specified the
+    target release of the package will be separated by a "/", e.g.
+    "xterm/experimental".
+
+    *read-only*
+
+.. attribute:: Paused : b
+
+    If the transaction is paused, e.g. it is waiting for a medium or the
+    resolution of a configuration file conflict.
+
+    *read-only*
+
+.. attribute:: ProgressDetails : (iixxdx)
+
+    A list with detailed progress information:
+
+    * number of already processed items
+    * number of total items
+    * number of already downloaded bytes
+    * number of total bytes which have to be downloaded
+    * number of bytes downloaded per second
+    * remaining time in seconds
+
+    *read-only*
+
+.. attribute:: ProgressDownload : (sssxxs)
+
+    The last progress information update of a currently running download.
+    A list of ..
+
+    * URL of the download
+    * status enum of the download, e.g. ``download-fetching``.
+    * short description of the download
+    * number of already downloaded bytes
+    * number of total bytes which have to be downloaded
+    * Status message
+
+    *read-only*
+
+.. attribute:: RemoveObsoletedDepends : b
+
+    If in the case of a removal obsolete dependencies which have been installed
+    automatically before should be removed, too.
+    *writable*
+
+.. attribute:: RequiredMedium : (ss)
+
+    If the transaction waits for a medium to be inserted this property contains
+    an array of the medium name and the path to the drive in which
+    it should be inserted.
+    *read-only*
+
+.. attribute:: Role : s
+
+    The enum representing the type of action performed by the transaction e.g.
+    ``role-install-packages``.
+    *read-only*
+
+.. attribute:: Space : x
+
+    The required disk space in Bytes. If disk spaces is freed the value will
+    be negative.
+
+    The property is available after :meth:`Simulate()` or :meth:`Run()` has
+    been called.
+
+    *read-only*
+
+.. attribute:: Status : s
+  
+    The status enum of the transaction, e.g. ``status-loading-cache``.
+
+    *read-only*
+
+.. attribute:: StatusDetails : s
+ 
+    A human readable string with additional download information.
+
+    *read-only*
+
+.. attribute:: Terminal : s
+
+    The path to the slave end of the controlling terminal which should be
+    used to controll the underlying :command:`dpkg` call.
+
+    *writable*
+
+.. attribute:: TerminalAttached : b
+
+    If the controlling terminal can be used to control the underlying
+    :command:`dpkg` call.
+
+    *read-only*
+
+.. attribute:: Unauthenticated : as
+
+    List of packages which are going to be installed but are not from an
+    authenticated repository.
+
+    *read-only*
+
+
+.. _policykit:
+
+PolicyKit privileges
+--------------------
+
+Most actions require the user to authenticate. The PolicyKit
+framework is used by aptdaemon for the authentication process.
+This allows to run aptdaemon as root and the client application as normal user.
+
+For non-transaction based actions the authentication will happen immediately. 
+For transaction based actions the privilege will be checked after :meth:`Run()`
+has been called. If the privilege has not yet been granted the user will
+be requested to authenticate interactively. 
+This allows the user to simulate a transaction before having to
+authenticate.
+
+Aptdaemon supports so called high level privileges which allow to perform
+a specified set of actions in a row without having to authenticate for each
+one separately. This only works if the client application authenticates for 
+the high level privilge before running the transactions and the authentication
+is cached.
+
+There are two high level privileges ``install-packages-from-new-repo`` and
+``install-purchased-software``. Both allow to add a repository, install the
+key of vendor from a keyserver, update the cache and to install packages.
+
+.. literalinclude:: ../examples/chained.py
diff --git a/doc/source/index.rst b/doc/source/index.rst
new file mode 100644
index 0000000..2b5976e
--- /dev/null
+++ b/doc/source/index.rst
@@ -0,0 +1,22 @@
+Aptdaemon documentation
+=======================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   aptdaemon.client
+   aptdaemon.enums
+   aptdaemon.gtk3widgets
+
+   dbus
+   plugins
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/doc/source/plugins.rst b/doc/source/plugins.rst
new file mode 100644
index 0000000..d3b35ef
--- /dev/null
+++ b/doc/source/plugins.rst
@@ -0,0 +1,68 @@
+Plugins
+=======
+
+Aptdaemon provides a plugin mechanism by making use of setuptools' entry points.
+The group name is ``aptdaemon.plugins``. 
+
+Cache modifiers
+---------------
+
+Currently there are two types of plugins available which allow you to modify 
+the marked changes of a transaction. Each plugin can be a function which 
+accepts the resolver (apt.cache.ProblemResolver) and the cache (apt.cache.Cache)
+as arguments:
+
+ * *modify_cache_before*
+   The plugged-in function is called after the intentional changes of the
+   transaction have been marked, but before the dependencies have been resolved.
+
+ * *modify_cache_after*
+   The plugged-in function is called after the dependency resolution of the
+   transaction. The resolver will be called again afterwards.
+ 
+A short overview of the steps required to process a transaction:
+
+ 1. Mark intentional changes (e.g. the to be installed packages of a
+    InstallPackages transaction)
+ 2. Call all modify_cache_before plugins
+ 3. Run the dependency resolver
+ 4. Call all modify_cache_after_plugins and re-run the resolver
+ 5. Commit changes
+
+
+External helpers
+----------------
+
+There is also the *get_license_key* plugin which allows to retrieve the license
+key content and path to store. License keys are required by propriatary
+software. The plugged-in function gets called with uid of the user who started
+the transaction, the package name, a JSON OAuth tocken and the name of a
+server to query.
+
+Example
+-------
+
+Here is an example which would install language packages :file:`./plugins/aptd.py`:
+
+>>> def install_language_packs(resolver, cache):
+>>>     """Marks the required language packs for installation."""
+>>>     #... do the magic here ...
+>>>     language_pack.mark_install(False, True)
+>>>     # Only protect your changes if they are mantadory. If they cannot be
+>>>     # be installed the transaction will fail.
+>>>     resolver.clear(language_pack)
+>>>     resolver.protect(language_pack)
+
+Finally you would have to register your function as entry point in :file:`setup.py`:
+
+>>> setup(
+>>> ...
+>>> entry_points="""[aptdaemon.plugins]
+>>> modify_cache_after=plugins.aptd:install_language_packs
+>>> """,
+>>> ...
+>>> )
+
+.. note::
+    Keep in mind that you can only register one entry point per name/plugin per
+    distribution.