Import Upstream version 1.1.1+bzr982

1 files changed, 410 insertions, 0 deletions

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