From d8c0ca6ff164f79910b315c9525fa77417084edf Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Thu, 23 Jul 2009 21:42:17 +0200 Subject: doc/source: Big documentation reorganisation. Due to the new C++ API and because I wanted to include some tutorials, the documentation is now seperated into 4 sections: library => Documentation of modules. tutorials => Tutorials for using python-apt and contributing whatsnew => Release notes c++ => Documentation,Tutorials for the C++ API This commit also includes a new overview page, like the Python documentation. --- doc/source/apt/cache.rst | 78 -- doc/source/apt/cdrom.rst | 7 - doc/source/apt/debfile.rst | 39 - doc/source/apt/index.rst | 56 - doc/source/apt/package.rst | 111 -- doc/source/apt/progress.gtk2.rst | 29 - doc/source/apt/progress.rst | 37 - doc/source/apt_inst.rst | 122 -- doc/source/apt_pkg.rst | 1780 ------------------------ doc/source/aptsources/distinfo.rst | 10 - doc/source/aptsources/distro.rst | 10 - doc/source/aptsources/index.rst | 10 - doc/source/aptsources/sourceslist.rst | 10 - doc/source/conf.py | 31 +- doc/source/contents.rst | 20 + doc/source/contributing.rst | 308 ----- doc/source/examples/apt-cdrom.py | 70 + doc/source/index.rst | 41 - doc/source/library/apt.cache.rst | 78 ++ doc/source/library/apt.cdrom.rst | 7 + doc/source/library/apt.debfile.rst | 39 + doc/source/library/apt.package.rst | 111 ++ doc/source/library/apt.progress.gtk2.rst | 29 + doc/source/library/apt.progress.qt4.rst | 3 + doc/source/library/apt.progress.text.rst | 21 + doc/source/library/apt_inst.rst | 122 ++ doc/source/library/apt_pkg.rst | 1795 +++++++++++++++++++++++++ doc/source/library/aptsources.distinfo.rst | 11 + doc/source/library/aptsources.distro.rst | 11 + doc/source/library/aptsources.sourceslist.rst | 11 + doc/source/library/index.rst | 36 + doc/source/templates/indexcontent.html | 50 + doc/source/templates/layout.html | 10 + doc/source/tutorials/apt-cdrom.rst | 156 +++ doc/source/tutorials/contributing.rst | 312 +++++ doc/source/tutorials/index.rst | 8 + doc/source/whatsnew/0.8.0.rst | 4 +- 37 files changed, 2923 insertions(+), 2660 deletions(-) delete mode 100644 doc/source/apt/cache.rst delete mode 100644 doc/source/apt/cdrom.rst delete mode 100644 doc/source/apt/debfile.rst delete mode 100644 doc/source/apt/index.rst delete mode 100644 doc/source/apt/package.rst delete mode 100644 doc/source/apt/progress.gtk2.rst delete mode 100644 doc/source/apt/progress.rst delete mode 100644 doc/source/apt_inst.rst delete mode 100644 doc/source/apt_pkg.rst delete mode 100644 doc/source/aptsources/distinfo.rst delete mode 100644 doc/source/aptsources/distro.rst delete mode 100644 doc/source/aptsources/index.rst delete mode 100644 doc/source/aptsources/sourceslist.rst create mode 100644 doc/source/contents.rst delete mode 100644 doc/source/contributing.rst create mode 100644 doc/source/examples/apt-cdrom.py delete mode 100644 doc/source/index.rst create mode 100644 doc/source/library/apt.cache.rst create mode 100644 doc/source/library/apt.cdrom.rst create mode 100644 doc/source/library/apt.debfile.rst create mode 100644 doc/source/library/apt.package.rst create mode 100644 doc/source/library/apt.progress.gtk2.rst create mode 100644 doc/source/library/apt.progress.qt4.rst create mode 100644 doc/source/library/apt.progress.text.rst create mode 100644 doc/source/library/apt_inst.rst create mode 100644 doc/source/library/apt_pkg.rst create mode 100644 doc/source/library/aptsources.distinfo.rst create mode 100644 doc/source/library/aptsources.distro.rst create mode 100644 doc/source/library/aptsources.sourceslist.rst create mode 100644 doc/source/library/index.rst create mode 100644 doc/source/templates/indexcontent.html create mode 100644 doc/source/templates/layout.html create mode 100644 doc/source/tutorials/apt-cdrom.rst create mode 100644 doc/source/tutorials/contributing.rst create mode 100644 doc/source/tutorials/index.rst (limited to 'doc') diff --git a/doc/source/apt/cache.rst b/doc/source/apt/cache.rst deleted file mode 100644 index ddb2dc64..00000000 --- a/doc/source/apt/cache.rst +++ /dev/null @@ -1,78 +0,0 @@ -:mod:`apt.cache` --- The Cache class -===================================== -.. automodule:: apt.cache - -The Cache class ---------------- - -.. autoclass:: Cache - :members: - :undoc-members: - - .. describe:: cache[pkgname] - - Return a :class:`Package()` for the package with the name *pkgname*. - -Example -^^^^^^^ - -The following example shows how to load the cache, update it, and upgrade -all the packages on the system:: - - import apt - import apt.progress - - # First of all, open the cache - cache = apt.Cache() - # Now, lets update the package list - cache.update() - # We need to re-open the cache because it needs to read the package list - cache.open(None) - # Now we can do the same as 'apt-get upgrade' does - cache.upgrade() - # or we can play 'apt-get dist-upgrade' - cache.upgrade(True) - # Q: Why does nothing happen? - # A: You forgot to call commit()! - cache.commit(apt.progress.TextFetchProgress(), - apt.progress.InstallProgress()) - - - -Working with Filters --------------------- -.. autoclass:: Filter - :members: - :inherited-members: - :undoc-members: - -.. autoclass:: MarkedChangesFilter - :members: - :inherited-members: - :undoc-members: - -.. autoclass:: FilteredCache - :members: - :inherited-members: - :undoc-members: - - -Example -^^^^^^^ - -This is an example for a filtered cache, which only allows access to the -packages whose state has been changed, eg. packages marked for installation:: - - >>> from apt.cache import FilteredCache, Cache, MarkedChangesFilter - >>> cache = apt.Cache() - >>> changed = apt.FilteredCache(cache) - >>> changed.set_filter(MarkedChangesFilter()) - >>> print len(changed) == len(cache.get_changes()) # Both need to have same length - True - - -Exceptions ----------- -.. autoexception:: FetchCancelledException -.. autoexception:: FetchFailedException -.. autoexception:: LockFailedException diff --git a/doc/source/apt/cdrom.rst b/doc/source/apt/cdrom.rst deleted file mode 100644 index 56381f14..00000000 --- a/doc/source/apt/cdrom.rst +++ /dev/null @@ -1,7 +0,0 @@ -:mod:`apt.cdrom` - Functionality like in apt-cdrom -==================================================== -.. automodule:: apt.cdrom - :members: - - - diff --git a/doc/source/apt/debfile.rst b/doc/source/apt/debfile.rst deleted file mode 100644 index 7133b5a8..00000000 --- a/doc/source/apt/debfile.rst +++ /dev/null @@ -1,39 +0,0 @@ -:mod:`apt.debfile` --- Classes related to debian package files -============================================================== -The :mod:`apt.debfile` provides classes to work with locally available -debian packages, or source packages. - -.. module:: apt.debfile - -Binary packages ----------------- -.. autoclass:: DebPackage - :members: - :inherited-members: - :undoc-members: - - The :class:`DebPackage` class is a class for working with '.deb' files, - also known as Debian packages. - - It provides methods and attributes to get a list of the files in the - package, to install the package and much more. - - If you specify *cache* it has to point to an :class:`apt.cache.Cache()` - object. - - .. versionchanged:: 0.7.9 - Introduce all new methods (everything except for :meth:`open()` and - :attr:`filelist`) - - -Source packages ----------------- -.. autoclass:: DscSrcPackage - :members: - :inherited-members: - :undoc-members: - - Provide functionality to work with locally available source packages, - especially with their '.dsc' file. - - .. versionadded:: 0.7.9 diff --git a/doc/source/apt/index.rst b/doc/source/apt/index.rst deleted file mode 100644 index 9cd6ef45..00000000 --- a/doc/source/apt/index.rst +++ /dev/null @@ -1,56 +0,0 @@ -:mod:`apt` --- Highlevel apt package -===================================== -The highlevel apt package provides a lot of functionality, all -with an easy-to-use interface. - -.. warning:: - The API of this package is not considered stable. Evenmore, it is considered - to change the naming conventions in future to lowercase_with_underscores. - - In case this happens, the API will still be kept compatible, with the old - functions provided as deprecated ones. - -.. automodule:: apt - - - -.. toctree:: - :maxdepth: 2 - :glob: - - * - - -Classes exported in apt ------------------------- -These classes are defined in the submodules, but are also exported directly -in the package. - -.. class:: Cache - - Please see :class:`apt.cache.Cache` for documentation. - -.. class:: Cdrom - - Please see :class:`apt.cdrom.Cdrom` for documentation. - -.. class:: CdromProgress - - Please see :class:`apt.progress.CdromProgress` for documentation. - -.. class:: FetchProgress - - Please see :class:`apt.progress.FetchProgress` for documentation. - -.. class:: InstallProgress - - Please see :class:`apt.progress.InstallProgress` for documentation. - -.. class:: OpProgress - - Please see :class:`apt.progress.OpProgress` for documentation. - -.. class:: Package - - Please see :class:`apt.package.Package` for documentation. - diff --git a/doc/source/apt/package.rst b/doc/source/apt/package.rst deleted file mode 100644 index 4b143b8a..00000000 --- a/doc/source/apt/package.rst +++ /dev/null @@ -1,111 +0,0 @@ -:mod:`apt.package` --- Classes for package handling -==================================================== - - -.. automodule:: apt.package - - -The Package class ------------------ -.. autoclass:: Package - :members: - - .. note:: - - Several methods have been deprecated in version 0.7.9 of python-apt, - please see the :class:`Version` class for the new alternatives. - -The Version class ------------------ -.. autoclass:: Version - :members: - - -Dependency Information ----------------------- -.. class:: BaseDependency - - The :class:`BaseDependency` class defines various attributes for accessing - the parts of a dependency. The attributes are as follows: - - .. attribute:: name - - The name of the dependency - - .. attribute:: relation - - The relation (>>,>=,==,<<,<=,) - - .. attribute:: version - - The version or None. - - .. attribute:: pre_depend - - Boolean value whether this is a pre-dependency. - -.. class:: Dependency - - The dependency class represents a Or-Group of dependencies. It provides - an attribute to access the :class:`BaseDependency` object for the available - choices. - - .. attribute:: or_dependencies - - A list of :class:`BaseDependency` objects which could satisfy the - requirement of the Or-Group. - - -Origin Information -------------------- -.. class:: Origin - - The :class:`Origin` class provides access to the origin of the package. - It allows you to check the component, archive, the hostname, and even if - this package can be trusted. - - .. attribute:: archive - - The archive (eg. unstable) - - .. attribute:: component - - The component (eg. main) - - .. attribute:: label - - The Label, as set in the Release file - - .. attribute:: origin - - The Origin, as set in the Release file - - .. attribute:: site - - The hostname of the site. - - .. attribute:: trusted - - Boolean value whether this is trustworthy. An origin can be trusted, if - it provides a GPG-signed Release file and the GPG-key used is in the - keyring used by apt (see apt-key). - -Examples ---------- -.. code-block:: python - - import apt - - cache = apt.Cache() - pkg = cache['python-apt'] # Access the Package object for python-apt - print 'python-apt is trusted:', pkg.candidate.origins[0].trusted - - # Mark python-apt for install - pkg.mark_install() - - print 'python-apt is marked for install:', pkg.marked_install - - print 'python-apt is (summary):', pkg.candidate.summary - - # Now, really install it - cache.commit() diff --git a/doc/source/apt/progress.gtk2.rst b/doc/source/apt/progress.gtk2.rst deleted file mode 100644 index a83ab111..00000000 --- a/doc/source/apt/progress.gtk2.rst +++ /dev/null @@ -1,29 +0,0 @@ -:mod:`apt.progress.gtk2` --- GTK widgets -======================================== -.. automodule:: apt.progress.gtk2 - - -GObject progress classes -------------------------- - -.. autoclass:: GDpkgInstallProgress - :members: - -.. autoclass:: GFetchProgress - :members: - -.. autoclass:: GInstallProgress - :members: - -.. autoclass:: GOpProgress - :members: - -GTK+ Class ----------- -.. autoclass:: GtkAptProgress - :members: - - -Example -------- -.. literalinclude:: ../examples/apt-gtk.py diff --git a/doc/source/apt/progress.rst b/doc/source/apt/progress.rst deleted file mode 100644 index 8989aa27..00000000 --- a/doc/source/apt/progress.rst +++ /dev/null @@ -1,37 +0,0 @@ -:mod:`apt.progress` --- Classes for progress reporting -====================================================== -.. automodule:: apt.progress - -.. warning:: - - This class is currently under re-organisation. Therefore, the API may - change soon. The old names will still be kept until it is safe to remove - them. - - - -Classes without output ----------------------- -.. autoclass:: FetchProgress - :members: -.. autoclass:: OpProgress - :members: -.. autoclass:: CdromProgress - :members: -.. autoclass:: DumbInstallProgress - :members: - -Implementing classes for text output ------------------------------------- -.. autoclass:: TextFetchProgress - :members: -.. autoclass:: OpTextProgress - :members: -.. autoclass:: InstallProgress - :members: -.. autoclass:: DpkgInstallProgress - :members: - - - - diff --git a/doc/source/apt_inst.rst b/doc/source/apt_inst.rst deleted file mode 100644 index cd371e36..00000000 --- a/doc/source/apt_inst.rst +++ /dev/null @@ -1,122 +0,0 @@ -:mod:`apt_inst` - Working with local Debian packages -==================================================== -.. module:: apt_inst - -The :mod:`apt_inst` extension provides access to functions for working with -locally available Debian packages (.deb files) and tar files. - - -Checking packages ------------------- -.. function:: arCheckMember(file, membername) - - Check if the member specified by the parameter *membername* exists in - the AR file referenced by the parameter *file*, which may be a - :class:`file()` object, a file descriptor, or anything implementing a - :meth:`fileno` method. - - .. versionchanged:: 0.8.0 - Added support for file descriptors and objects implementing a :meth:`fileno` method. - - -Listing contents ------------------ -.. function:: debExtract(file, func, chunk) - - Call the function referenced by *func* for each member of the tar file - *chunk* which is contained in the AR file referenced by the parameter - *file*, which may be a :class:`file()` object, a file descriptor, or - anything implementing a :meth:`fileno` method. - - An example would be:: - - debExtract(open("package.deb"), my_callback, "data.tar.gz") - - See :ref:`emulating-dpkg-contents` for a more detailed example. - - .. versionchanged:: 0.8.0 - Added support for file descriptors and objects implementing a :meth:`fileno` method. - -.. function:: tarExtract(file,func,comp) - - Call the function *func* for each member of the tar file *file*. - - The parameter *comp* is a string determining the compressor used. Possible - options are "lzma", "bzip2" and "gzip". - - The parameter *file* may be a :class:`file()` object, a file descriptor, or - anything implementing a :meth:`fileno` method. - - .. versionchanged:: 0.8.0 - Added support for file descriptors and objects implementing a :meth:`fileno` method. - - -Callback -^^^^^^^^^ -Both of these functions expect a callback with the signature -``(what, name, link, mode, uid, gid, size, mtime, major, minor)``. - -The parameter *what* describes the type of the member. It can be 'FILE', -'DIR', or 'HARDLINK'. - -The parameter *name* refers to the name of the member. In case of links, -*link* refers to the target of the link. - - -Extracting contents -------------------- - -.. function:: debExtractArchive(file, rootdir) - - Extract the archive referenced by the :class:`file` object *file* - into the directory specified by *rootdir*. - - The parameter *file* may be a :class:`file()` object, a file descriptor, or - anything implementing a :meth:`fileno` method. - - See :ref:`emulating-dpkg-extract` for an example. - - .. warning:: - - If the directory given by *rootdir* does not exist, the package is - extracted into the current directory. - - .. versionchanged:: 0.8.0 - Added support for file descriptors and objects implementing a :meth:`fileno` method. - -.. function:: debExtractControl(file[, member='control']) - - Return the indicated file as a string from the control tar. The default - is 'control'. - - The parameter *file* may be a :class:`file()` object, a file descriptor, or - anything implementing a :meth:`fileno` method. - - If you want to print the control file of a given package, you could do - something like:: - - print debExtractControl(open("package.deb")) - - .. versionchanged:: 0.8.0 - Added support for file descriptors and objects implementing a :meth:`fileno` method. - - -.. _emulating-dpkg-extract: - -Example: Emulating :program:`dpkg` :option:`--extract` -------------------------------------------------------- -Here is a code snippet which emulates dpkg -x. It can be run as -:program:`tool` :option:`pkg.deb` :option:`outdir`. - -.. literalinclude:: examples/dpkg-extract.py - - -.. _emulating-dpkg-contents: - -Example: Emulating :program:`dpkg` :option:`--contents` -------------------------------------------------------- -.. literalinclude:: examples/dpkg-contents.py - -Example: Emulating :program:`dpkg` :option:`--info` ----------------------------------------------------- -.. literalinclude:: examples/dpkg-info.py diff --git a/doc/source/apt_pkg.rst b/doc/source/apt_pkg.rst deleted file mode 100644 index 9a14266e..00000000 --- a/doc/source/apt_pkg.rst +++ /dev/null @@ -1,1780 +0,0 @@ -:mod:`apt_pkg` --- The low-level bindings for apt-pkg -===================================================== -.. module:: apt_pkg - -The apt_pkg extensions provides a more low-level way to work with apt. It can -do everything apt can, and is written in C++. It has been in python-apt since -the beginning. - - -Module Initialization ---------------------- - -Initialization is needed for most functions, but not for all of them. Some can -be called without having run init*(), but will not return the expected value. - -.. function:: init_config - - Initialize the configuration of apt. This is needed for most operations. - -.. function:: init_system - - Initialize the system. - -.. function:: init - - Deprecated function. Use init_config() and init_system() instead. - -Working with the cache ----------------------- -.. class:: Cache([progress]) - - Return a :class:`Cache()` object. The optional parameter *progress* - specifies an instance of :class:`apt.progress.OpProgress()` which will - display the open progress. - - .. describe:: cache[pkgname] - - Return the :class:`Package()` object for the package name given by - *pkgname*. - - .. method:: close() - - Close the package cache. - - .. method:: open([progress]) - - Open the package cache again. The parameter *progress* may be set to - an :class:`apt.progress.OpProgress()` object or `None`. - - .. method:: update(progress, list) - - Update the package cache. - - The parameter *progress* points to an :class:`apt.progress.FetchProgress()` - object. The parameter *list* refers to a :class:`SourceList()` object. - - .. attribute:: depends_count - - The total number of dependencies. - - .. attribute:: package_count - - The total number of packages available in the cache. - - .. attribute:: provides_count - - The number of provided packages. - - .. attribute:: ver_file_count - - .. todo:: Seems to be some mixture of versions and pkgFile. - - .. attribute:: version_count - - The total number of package versions available in the cache. - - .. attribute:: package_file_count - - The total number of Packages files available (the Packages files - listing the packages). This is the same as the length of the list in - the attribute :attr:`file_list`. - - .. attribute:: file_list - - A list of :class:`PackageFile` objects. - -.. class:: DepCache(cache) - - Return a :class:`DepCache` object. The parameter *cache* specifies an - instance of :class:`Cache`. - - The DepCache object contains various methods to manipulate the cache, - to install packages, to remove them, and much more. - - .. method:: commit(fprogress, iprogress) - - Apply all the changes made. - - The parameter *fprogress* has to be set to an instance of - apt.progress.FetchProgress or one of its subclasses. - - The parameter *iprogress* has to be set to an instance of - apt.progress.InstallProgress or one of its subclasses. - - .. method:: fix_broken() - - Try to fix all broken packages in the cache. - - .. method:: get_candidate_ver(pkg) - - Return the candidate version of the package, ie. the version that - would be installed normally. - - The parameter *pkg* refers to an :class:`Package` object, - available using the :class:`pkgCache`. - - This method returns a :class:`Version` object. - - .. method:: set_candidate_ver(pkg, version) - - The opposite of :meth:`pkgDepCache.get_candidate_ver`. Set the candidate - version of the :class:`Package` *pkg* to the :class:`Version` - *version*. - - - .. method:: upgrade([dist_upgrade=False]) - - Perform an upgrade. More detailed, this marks all the upgradable - packages for upgrade. You still need to call - :meth:`pkgDepCache.commit` for the changes to apply. - - To perform a dist-upgrade, the optional parameter *dist_upgrade* has - to be set to True. - - .. method:: fix_broken() - - Fix broken packages. - - .. method:: read_pin_file() - - Read the policy, eg. /etc/apt/preferences. - - .. method:: minimize_upgrade() - - Go over the entire set of packages and try to keep each package marked - for upgrade. If a conflict is generated then the package is restored. - - .. todo:: - Explain better.. - - .. method:: mark_keep(pkg) - - Mark the :class:`Package` *pkg* for keep. - - .. method:: mark_delete(pkg[, purge]) - - Mark the :class:`Package` *pkg* for delete. If *purge* is True, - the configuration files will be removed as well. - - .. method:: mark_install(pkg[, auto_inst=True[, from_user=True]]) - - Mark the :class:`Package` *pkg* for install. - - If *auto_inst* is ``True``, the dependencies of the package will be - installed as well. This is the default. - - If *from_user* is ``True``, the package will be marked as manually - installed. This is the default. - - .. method:: set_reinstall(pkg) - - Set if the :class:`Package` *pkg* should be reinstalled. - - .. method:: is_upgradable(pkg) - - Return ``1`` if the package is upgradable. - - The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. - - .. method:: is_now_broken(pkg) - - Return `1` if the package is broken now (including changes made, but - not committed). - - .. method:: is_inst_broken(pkg) - - Return ``1`` if the package is broken on the current install. This - takes changes which have not been committed not into effect. - - .. method:: is_garbage(pkg) - - Return ``1`` if the package is garbage, ie. if it is automatically - installed and no longer referenced by other packages. - - .. method:: is_auto_installed(pkg) - - Return ``1`` if the package is automatically installed (eg. as the - dependency of another package). - - .. method:: marked_install(pkg) - - Return ``1`` if the package is marked for install. - - .. method:: marked_upgrade(pkg) - - Return ``1`` if the package is marked for upgrade. - - .. method:: marked_delete(pkg) - - Return ``1`` if the package is marked for delete. - - .. method:: marked_keep(pkg) - - Return ``1`` if the package is marked for keep. - - .. method:: marked_reinstall(pkg) - - Return ``1`` if the package should be installed. - - .. method:: marked_downgrade(pkg) - - Return ``1`` if the package should be downgraded. - - .. attribute:: keep_count - - Integer, number of packages marked as keep - - .. attribute:: inst_count - - Integer, number of packages marked for installation. - - .. attribute:: del_count - - Number of packages which should be removed. - - .. attribute:: broken_count - - Number of packages which are broken. - - .. attribute:: usr_size - - The size required for the changes on the filesystem. If you install - packages, this is positive, if you remove them its negative. - - .. attribute:: deb_size - - The size of the packages which are needed for the changes to be - applied. - - -.. class:: PackageManager(depcache) - - Return a new :class:`PackageManager` object. The parameter *depcache* - specifies a :class:`DepCache` object. - - :class:`PackageManager` objects provide several methods and attributes, - which will be listed here: - - .. method:: get_archives(fetcher, list, records) - - Add all the selected packages to the :class:`Acquire()` object - *fetcher*. - - The parameter *list* refers to a :class:`SourceList()` object. - - The parameter *records* refers to a :class:`PackageRecords()` object. - - .. method:: do_install() - - Install the packages. - - .. method:: fix_missing - - Fix the installation if a package could not be downloaded. - - .. attribute:: result_completed - - A constant for checking whether the the result is 'completed'. - - Compare it against the return value of :meth:`PackageManager.get_archives` - or :meth:`PackageManager.do_install`. - - .. attribute:: result_failed - - A constant for checking whether the the result is 'failed'. - - Compare it against the return value of :meth:`PackageManager.get_archives` - or :meth:`PackageManager.do_install`. - - .. attribute:: result_incomplete - - A constant for checking whether the the result is 'incomplete'. - - Compare it against the return value of :meth:`PackageManager.get_archives` - or :meth:`PackageManager.do_install`. - -Improve performance with :class:`ActionGroup` -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. class:: ActionGroup(depcache) - - Create a new :class:`ActionGroup()` object for the :class:`DepCache` object - given by the parameter *depcache*. - - :class:`ActionGroup()` objects make operations on the cache faster by - delaying certain cleanup operations until the action group is released. - - ActionGroup is also a context manager and therefore supports the - :keyword:`with` statement. But because it becomes active as soon as it - is created, you should not create an ActionGroup() object before entering - the with statement. - - If you want to use ActionGroup as a with statement (which is recommended - because it makes it easier to see when an actiongroup is active), always - use the following form:: - - with apt_pkg.ActionGroup(depcache): - ... - - For code which has to run on Python versions prior to 2.5, you can also - use the traditional way:: - - actiongroup = apt_pkg.ActionGroup(depcache) - ... - actiongroup.release() - - :class:`ActionGroup` provides the following method: - - .. method:: release() - - Release the ActionGroup. This will reactive the collection of package - garbage. - -Resolving Dependencies -^^^^^^^^^^^^^^^^^^^^^^ - -.. class:: ProblemResolver(depcache) - - Return a new :class:`ProblemResolver` object. The parameter *depcache* - specifies a :class:`pDepCache` object. - - The problem resolver helps when there are problems in the package - selection. An example is a package which conflicts with another, already - installed package. - - .. method:: protect(pkg) - - Protect the :class:`Package()` object given by the parameter *pkg*. - - .. todo:: - - Really document it. - - .. method:: install_protect() - - Protect all installed packages from being removed. - - .. method:: remove(pkg) - - Remove the :class:`Package()` object given by the parameter *pkg*. - - .. todo:: - - Really document it. - - .. method:: clear(pkg) - - Reset the :class:`Package()` *pkg* to the default state. - - .. todo:: - - Really document it. - - .. method:: resolve() - - Try to resolve problems by installing and removing packages. - - .. method:: resolve_by_keep() - - Try to resolve problems only by using keep. - - -:class:`PackageFile` --------------------- -.. class:: PackageFile - - A :class:`PackageFile` represents a Packages file, eg. - /var/lib/dpkg/status. - - .. attribute:: architecture - - The architecture of the package file. - - .. attribute:: archive - - The archive (eg. unstable) - - .. attribute:: component - - The component (eg. main) - - .. attribute:: filename - - The name of the file. - - .. attribute:: id - - The ID of the package. This is an integer which can be used to store - further information about the file [eg. as dictionary key]. - - .. attribute:: index_type - - The sort of the index file. In normal cases, this is - 'Debian Package Index'. - - .. attribute:: label - - The Label, as set in the Release file - - .. attribute:: not_automatic - - Whether packages from this list will be updated automatically. The - default for eg. example is 0 (aka false). - - .. attribute:: not_source - - Whether the file has no source from which it can be updated. In such a - case, the value is 1; else 0. /var/lib/dpkg/status is 0 for example. - - Example:: - - for pkgfile in cache.file_list: - if pkgfile.not_source: - print 'The file %s has no source.' % pkgfile.filename - - .. attribute:: origin - - The Origin, as set in the Release file - - .. attribute:: site - - The hostname of the site. - - .. attribute:: size - - The size of the file. - - .. attribute:: version - - The version, as set in the release file (eg. "4.0" for "Etch") - - -Example -^^^^^^^ -.. literalinclude:: examples/cache-pkgfile.py - - -:class:`Package` ----------------- - -.. class:: Package - - The pkgCache::Package objects are an interface to package specific - features. - - - Attributes: - - .. attribute:: current_ver - - The version currently installed, or None. This returns a - :class:`Version` object. - - .. attribute:: id - - The ID of the package. This can be used to store information about - the package. The ID is an int value. - - .. attribute:: name - - This is the name of the package. - - .. attribute:: provides_list - - A list of packages providing this package. More detailed, this is a - list of tuples (str:pkgname, ????, :class:`Version`). - - If you want to check for check for virtual packages, the expression - ``pkg.provides_list and not pkg._version_list`` helps you. It detects if - the package is provided by something else and is not available as a - real package. - - .. attribute:: rev_depends_list - - An iterator of :class:`Dependency` objects for dependencies on this - package. - - .. attribute:: section - - The section of the package, as specified in the record. The list of - possible sections is defined in the Policy. - - .. attribute:: version_list - - A list of :class:`Version` objects for all versions available in the - cache. - - **States**: - - .. attribute:: selected_state - - The state we want it to be, ie. if you mark a package for installation, - this is :attr:`apt_pkg.SELSTATE_INSTALL`. - - See :ref:`SelStates` for a list of available states. - - .. attribute:: inst_state - - The state the currently installed version is in. This is normally - :attr:`apt_pkg.INSTSTATE_OK`, unless the installation failed. - - See :ref:`InstStates` for a list of available states. - - .. attribute:: cur_state - - The current state of the package (not installed, unpacked, installed, - etc). See :ref:`CurStates` for a list of available states. - - **Flags**: - - .. attribute:: auto - - Whether the package was installed automatically as a dependency of - another package. (or marked otherwise as automatically installed) - - .. attribute:: essential - - Whether the package is essential. - - .. attribute:: important - - Whether the package is important. - -Example: -^^^^^^^^^ -.. literalinclude:: examples/cache-packages.py - - - -:class:`Version` ----------------- -.. class:: Version - - The version object contains all information related to a specific package - version. - - .. attribute:: ver_str - - The version, as a string. - - .. attribute:: section - - The usual sections (eg. admin, net, etc.). Prefixed with the component - name for packages not in main (eg. non-free/admin). - - .. attribute:: arch - - The architecture of the package, eg. amd64 or all. - - .. attribute:: file_list - - A list of (:class:`PackageFile`, int: index) tuples for all Package - files containing this version of the package. - - .. attribute:: depends_list_str - - A dictionary of dependencies. The key specifies the type of the - dependency ('Depends', 'Recommends', etc.). - - - The value is a list, containing items which refer to the or-groups of - dependencies. Each of these or-groups is itself a list, containing - tuples like ('pkgname', 'version', 'relation') for each or-choice. - - An example return value for a package with a 'Depends: python (>= 2.4)' - would be:: - - {'Depends': [ - [ - ('python', '2.4', '>=') - ] - ] - } - - The same for a dependency on A (>= 1) | B (>= 2):: - - {'Depends': [ - [ - ('A', '1', '>='), - ('B', '2', '>='), - ] - ] - } - - .. attribute:: depends_list - - This is basically the same as :attr:`Version.DependsListStr`, - but instead of the ('pkgname', 'version', 'relation') tuples, - it returns :class:`Dependency` objects, which can assist you with - useful functions. - - .. attribute:: parent_pkg - - The :class:`Package` object this version belongs to. - - .. attribute:: provides_list - - This returns a list of all packages provided by this version. Like - :attr:`Package.provides_list`, it returns a list of tuples - of the form ('virtualpkgname', ???, :class:`Version`), where as the - last item is the same as the object itself. - - .. attribute:: size - - The size of the .deb file, in bytes. - - .. attribute:: installed_size - - The size of the package (in kilobytes), when unpacked on the disk. - - .. attribute:: hash - - An integer hash value. - - .. attribute:: id - - An integer id. - - .. attribute:: priority - - The integer representation of the priority. This can be used to speed - up comparisons a lot, compared to :attr:`Version.priority_str`. - - The values are defined in the :mod:`apt_pkg` extension, see - :ref:`Priorities` for more information. - - .. attribute:: priority_str - - Return the priority of the package version, as a string, eg. - "optional". - - .. attribute:: downloadable - - Whether this package can be downloaded from a remote site. - - .. attribute:: translated_description - - Return a :class:`Description` object. - - -:class:`Dependency` -------------------- -.. class:: Dependency - - Represent a dependency from one package to another one. - - .. method:: all_targets - - A list of :class:`Version` objects which satisfy the dependency, - and do not conflict with already installed ones. - - From my experience, if you use this method to select the target - version, it is the best to select the last item unless any of the - other candidates is already installed. This leads to results being - very close to the normal package installation. - - .. method:: smart_target_pkg - - Return a :class:`Version` object of a package which satisfies the - dependency and does not conflict with installed packages - (the 'natural target'). - - .. attribute:: target_ver - - The target version of the dependency, as string. Empty string if the - dependency is not versioned. - - .. attribute:: target_pkg - - The :class:`Package` object of the target package. - - .. attribute:: parent_ver - - The :class:`Version` object of the parent version, ie. the package - which declares the dependency. - - .. attribute:: parent_pkg - - The :class:`Package` object of the package which declares the - dependency. This is the same as using ParentVer.ParentPkg. - - .. attribute:: comp_type - - The type of comparison (>=, ==, >>, <=), as string. - - .. attribute:: dep_type - - The type of the dependency, as string, eg. "Depends". - - .. attribute:: id - - The ID of the package, as integer. - -Example: Find all missing dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -With the help of Dependency.AllTargets(), you can easily find all packages with -broken dependencies: - -.. literalinclude:: examples/missing-deps.py - - -:class:`Description` --------------------- -.. class:: Description - - Represent the description of the package. - - .. attribute:: language_code - - The language code of the description - - .. attribute:: md5 - - The md5 hashsum of the description - - .. attribute:: file_list - - A list of tuples (:class:`PackageFile`, int: index). - - - -:class:`MetaIndex` ------------------- - -.. todo:: - - Complete them - -.. class:: MetaIndex - - .. attribute:: uri - .. attribute:: dist - .. attribute:: is_trusted - .. attribute:: index_files - - -:class:`PackageIndexFile` -------------------------- - -.. class:: PackageIndexFile - - .. method:: archive_uri(path) - - Return the full url to path in the archive. - - .. attribute:: label - - Return the Label. - - .. attribute:: exists - - Return whether the file exists. - - .. attribute:: has_packages - - Return whether the file has packages. - - .. attribute:: size - - Size of the file - - .. attribute:: is_trusted - - Whether we can trust the file. - - -Records --------- - -.. class:: PackageRecords(cache) - - Create a new :class:`PackageRecords` object, for the packages in the cache - specified by the parameter *cache*. - - Provide access to the packages records. This provides very useful - attributes for fast (convient) access to some fields of the record. - - .. method:: lookup(verfile_iter) - - Change the actual package to the package given by the verfile_iter. - - The parameter *verfile_iter* refers to a tuple consisting - of (:class:`PackageFile()`, int: index), as returned by various - attributes, including :attr:`Version.file_list`. - - Example (shortened):: - - cand = depcache.GetCandidateVer(cache['python-apt']) - records.Lookup(cand.FileList[0]) - # Now you can access the record - print records.SourcePkg # == python-apt - - .. attribute:: filename - - Return the field 'Filename' of the record. This is the path to the - package, relative to the base path of the archive. - - .. attribute:: md5_hash - - Return the MD5 hashsum of the package This refers to the field - 'MD5Sum' in the raw record. - - .. attribute:: sha1_hash - - Return the SHA1 hashsum of the package. This refers to the field 'SHA1' - in the raw record. - - .. attribute:: sha256_hash - - Return the SHA256 hashsum of the package. This refers to the field - 'SHA256' in the raw record. - - .. versionadded:: 0.7.9 - - .. attribute:: source_pkg - - Return the source package. - - .. attribute:: source_ver - - Return the source version. - - .. attribute:: maintainer - - Return the maintainer of the package. - - .. attribute:: short_desc - - Return the short description. This is the summary on the first line of - the 'Description' field. - - .. attribute:: long_desc - - Return the long description. These are lines 2-END from the - 'Description' field. - - .. attribute:: name - - Return the name of the package. This is the 'Package' field. - - .. attribute:: homepage - - Return the Homepage. This is the 'Homepage' field. - - .. attribute:: record - - Return the whole record as a string. If you want to access fields of - the record not available as an attribute, you can use - :class:`apt_pkg.TagSection` to parse the record and access the field - name. - - Example:: - - section = apt_pkg.TagSection(records.record) - print section['SHA256'] # Use records.sha256_hash instead - - -.. class:: SourceRecords - - This represents the entries in the Sources files, ie. the dsc files of - the source packages. - - .. note:: - - If the Lookup failed, because no package could be found, no error is - raised. Instead, the attributes listed below are simply not existing - anymore (same applies when no Lookup has been made, or when it has - been restarted). - - .. method:: lookup(pkgname) - - Lookup the record for the package named *pkgname*. To access all - available records, you need to call it multiple times. - - Imagine a package P with two versions X, Y. The first ``lookup(P)`` - would set the record to version X and the second ``lookup(P)`` to - version Y. - - .. method:: restart() - - Restart the lookup. - - Imagine a package P with two versions X, Y. The first ``Lookup(P)`` - would set the record to version X and the second ``Lookup(P)`` to - version Y. - - If you now call ``restart()``, the internal position will be cleared. - Now you can call ``lookup(P)`` again to move to X. - - .. attribute:: package - - The name of the source package. - - .. attribute:: version - - A string describing the version of the source package. - - .. attribute:: maintainer - - A string describing the name of the maintainer. - - .. attribute:: section - - A string describing the section. - - .. attribute:: record - - The whole record, as a string. You can use :func:`apt_pkg.ParseSection` - if you need to parse it. - - You need to parse the record if you want to access fields not available - via the attributes, eg. 'Standards-Version' - - .. attribute:: binaries - - Return a list of strings describing the package names of the binaries - created by the source package. This matches the 'Binary' field in the - raw record. - - .. attribute:: index - - The index in the Sources files. - - .. attribute:: files - - The list of files. This returns a list of tuples with the contents - ``(str: md5, int: size, str: path, str:type)``. - - .. attribute:: build_depends - - Return a dictionary representing the build-time dependencies of the - package. The format is the same as for :attr:`Version.depends_list_str` - and possible keys being ``"Build-Depends"``, ``"Build-Depends-Indep"``, - ``"Build-Conflicts"`` or ``"Build-Conflicts-Indep"``. - - .. attribute:: BuildDepends - - Return the list of Build dependencies, as - ``(str: package, str: version, int: op, int: type)``. This is a - completely deprecated format - - .. table:: Values of *op* - - ===== ============================================= - Value Meaning - ===== ============================================= - 0x00 No Operation (no versioned build dependency) - 0x10 | (or) - this will be added to the other values - 0x01 <= (less than or equal) - 0x02 >= (greater than or equal) - 0x03 << (less than) - 0x04 >> (greater than) - 0x05 = (equal) - 0x06 != (not equal) - ===== ============================================= - - .. table:: Values of *type* - - ===== =================== - Value Meaning - ===== =================== - 0 Build-Depends - 1 Build-Depends-Indep - 2 Build-Conflicts - 3 Build-Conflicts-Indep - ===== =================== - - **Example**: In the following content, we will imagine a - build-dependency:: - - Build-Depends: A (>= 1) | B (>= 1), C - - This results in:: - - [('A', '1', 18, 0), # 18 = (16 | 2) = (0x10 | 0x2) - ('B', '1', 2, 0), - ('C', '', 0, 0)] - - This is **not** the same as returned by - :func:`apt_pkg.ParseSrcDepends`. - - - -The Acquire interface ----------------------- -The Acquire Interface is responsible for all sorts of downloading in apt. All -packages, index files, etc. downloading is done using the Acquire functionality. - -The :mod:`apt_pkg` module provides a subset of this functionality which allows -you to implement file downloading in your applications. Together with the -:class:`PackageManager` class you can also fetch all the packages marked for -installation. - - -.. class:: Acquire([progress]) - - Return an :class:`Acquire` object. The parameter *progress* refers to - an :class:`apt.progress.FetchProgress()` object. - - Acquire objects maintaing a list of items which will be fetched or have - been fetched already during the lifetime of this object. To add new items - to this list, you can create new :class:`AcquireFile` objects which allow - you to add single files. - - Acquire items have multiple methods: - - .. method:: run() - - Fetch all the items which have been added by :class:`AcquireFile`. - - .. method:: shutdown() - - Shut the fetcher down. - - .. attribute:: total_needed - - The total amount of bytes needed (including those of files which are - already present) - - .. attribute:: fetch_needed - - The total amount of bytes which need to be fetched. - - .. attribute:: partial_present - - Whether some files have been acquired already. (???) - -.. class:: AcquireItem - - The :class:`AcquireItem()` objects represent the items of a - :class:`Acquire` object. :class:`AcquireItem()` objects can not be created - by the user, they are solely available through the :attr:`Acquire.items` - list of an :class:`Acquire` object. - - .. attribute:: id - - The ID of the item. - - .. attribute:: complete - - Is the item completely acquired? - - .. attribute:: local - - Is the item a local file? - - .. attribute:: is_trusted - - Can the file be trusted? - - .. attribute:: file_size - - The size of the file, in bytes. - - .. attribute:: error_text - - The error message. For example, when a file does not exist on a http - server, this will contain a 404 error message. - - .. attribute:: dest_file - - The location the file is saved as. - - .. attribute:: desc_uri - - The source location. - - **Status**: - - .. attribute:: status - - Integer, representing the status of the item. - - .. attribute:: stat_idle - - Constant for comparing :attr:`AcquireItem.status`. - - .. attribute:: stat_fetching - - Constant for comparing :attr:`AcquireItem.status` - - .. attribute:: stat_done - - Constant for comparing :attr:`AcquireItem.status` - - .. attribute:: stat_error - - Constant for comparing :attr:`AcquireItem.status` - - .. attribute:: stat_auth_error - - Constant for comparing :attr:`AcquireItem.status` - - -.. class:: AcquireFile(owner, uri[, md5, size, descr, short_descr, destdir, destfile]) - - Create a new :class:`AcquireFile()` object and register it with *acquire*, - so it will be fetched. AcquireFile objects provide no methods or attributes - and are completely useless at the moment. - - The parameter *owner* refers to an :class:`Acquire()` object as returned - by :func:`GetAcquire`. The file will be added to the Acquire queue - automatically. - - The parameter *uri* refers to the location of the file, any protocol - of apt is supported. - - The parameter *md5* refers to the md5sum of the file. This can be used - for checking the file. - - The parameter *size* can be used to specify the size of the package, - which can then be used to calculate the progress and validate the download. - - The parameter *descr* is a descripition of the download. It may be - used to describe the item in the progress class. *short_descr* is the - short form of it. - - You can use *destdir* to manipulate the directory where the file will - be saved in. Instead of *destdir*, you can also specify the full path to - the file using the parameter *destfile*. You can not combine both. - - -Hashes ------- -The apt_pkg module also provides several hash functions. If you develop -applications with python-apt it is often easier to use these functions instead -of the ones provides in Python's :mod:`hashlib` module. - -.. class:: Hashes(object) - - Calculate all supported hashes of the object. *object* may either be a - string, in which cases the hashes of the string are calculated, or a - :class:`file()` object or file descriptor, in which case the hashes of - its contents is calculated. The calculated hashes are then available via - attributes: - - .. attribute:: md5 - - The MD5 hash of the data, as string. - - .. attribute:: sha1 - - The SHA1 hash of the data, as string. - - .. attribute:: sha256 - - The SHA256 hash of the data, as string. - -.. function:: md5sum(object) - - Return the md5sum of the object. *object* may either be a string, in - which case the md5sum of the string is returned, or a :class:`file()` - object (or a file descriptor), in which case the md5sum of its contents is - returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -.. function:: sha1sum(object) - - Return the sha1sum of the object. *object* may either be a string, in - which case the sha1sum of the string is returned, or a :class:`file()` - object (or a file descriptor), in which case the sha1sum of its contents - is returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -.. function:: sha256sum(object) - - Return the sha256sum of the object. *object* may either be a string, in - which case the sha256sum of the string is returned, or a :class:`file()` - object (or a file descriptor), in which case the sha256sum of its contents - is returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -Debian control files --------------------- -Debian control files are files containing multiple stanzas of :RFC:`822`-style -header sections. They are widely used in the Debian community, and can represent -many kinds of information. One example for such a file is the -:file:`/var/lib/dpkg/status` file which contains a list of the currently -installed packages. - -The :mod:`apt_pkg` module provides two classes to read those files and parts -thereof and provides a function :func:`RewriteSection` which takes a -:class:`TagSection()` object and sorting information and outputs a sorted -section as a string. - -.. class:: TagFile(file) - - An object which represents a typical debian control file. Can be used for - Packages, Sources, control, Release, etc. - - An example for working with a TagFile could look like:: - - tagf = apt_pkg.TagFile(open('/var/lib/dpkg/status')) - tagf.step() - print tagf.section['Package'] - - .. method:: step - - Step forward to the next section. This simply returns ``1`` if OK, and - ``0`` if there is no section - - .. method:: offset - - Return the current offset (in bytes) from the beginning of the file. - - .. method:: jump(offset) - - Jump back/forward to *offset*. Use ``jump(0)`` to jump to the - beginning of the file again. - - .. attribute:: section - - This is the current :class:`TagSection()` instance. - -.. class:: TagSection(text) - - Represent a single section of a debian control file. - - .. describe:: section[key] - - Return the value of the field at *key*. If *key* is not available, - raise :exc:`KeyError`. - - .. describe:: key in section - - Return ``True`` if *section* has a key *key*, else ``False``. - - .. versionadded:: 0.8.0 - - .. method:: bytes - - The number of bytes in the section. - - .. method:: find(key, default='') - - Return the value of the field at the key *key* if available, - else return *default*. - - .. method:: find_flag(key) - - Find a yes/no value for the key *key*. An example for such a - field is 'Essential'. - - .. method:: get(key, default='') - - Return the value of the field at the key *key* if available, else - return *default*. - - .. method:: has_key(key) - - Check whether the field with named by *key* exists. - - .. deprecated:: 0.8.0 - - .. method:: keys() - - Return a list of keys in the section. - -.. autofunction:: rewrite_section(section, order, rewrite_list) - -.. data:: REWRITE_PACKAGE_ORDER - - The order in which the information for binary packages should be rewritten, - i.e. the order in which the fields should appear. - -.. data:: REWRITE_SOURCE_ORDER - - The order in which the information for source packages should be rewritten, - i.e. the order in which the fields should appear. - -Dependencies ------------- -.. function:: check_dep(pkgver, op, depver) - - Check that the dependency requirements consisting of op and depver can be - satisfied by the version pkgver. - - Example:: - - >>> bool(apt_pkg.check_dep("1.0", ">=", "1")) - True - -.. function:: parse_depends(depends) - - Parse the string *depends* which contains dependency information as - specified in Debian Policy, Section 7.1. - - Returns a list. The members of this list are lists themselves and contain - one or more tuples in the format ``(package,version,operation)`` for every - 'or'-option given, e.g.:: - - >>> apt_pkg.parse_depends("PkgA (>= VerA) | PkgB (>= VerB)") - [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] - - - .. note:: - - The behavior of this function is different than the behavior of the - old function :func:`ParseDepends()`, because the third field - ``operation`` uses `>` instead of `>>` and `<` instead of `<<` which - is specified in control files. - - -.. function:: parse_src_depends(depends) - - Parse the string *depends* which contains dependency information as - specified in Debian Policy, Section 7.1. - - Returns a list. The members of this list are lists themselves and contain - one or more tuples in the format ``(package,version,operation)`` for every - 'or'-option given, e.g.:: - - >>> apt_pkg.parse_depends("PkgA (>= VerA) | PkgB (>= VerB)") - [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] - - - Furthemore, this function also supports to limit the architectures, as - used in e.g. Build-Depends:: - - >>> apt_pkg.parse_src_depends("a (>= 01) [i386 amd64]") - [[('a', '01', '>=')]] - - .. note:: - - The behavior of this function is different than the behavior of the - old function :func:`ParseDepends()`, because the third field - ``operation`` uses `>` instead of `>>` and `<` instead of `<<` which - is specified in control files. - - -Configuration -------------- - -.. class:: Configuration() - - Configuration() objects store the configuration of apt, mostly created from - the contents of :file:`/etc/apt.conf` and the files in - :file:`/etc/apt.conf.d`. - - .. describe:: key in conf - - Return ``True`` if *conf* has a key *key*, else ``False``. - - .. versionadded:: 0.8.0 - - .. describe:: conf[key] - - Return the value of the option given key *key*. If it does not - exist, raise :exc:`KeyError`. - - .. describe:: conf[key] = value - - Set the option at *key* to *value*. - - .. method:: find(key[, default='']) - - Return the value for the given key *key*. This is the same as - :meth:`Configuration.get`. - - If *key* does not exist, return *default*. - - .. method:: find_file(key[, default='']) - - Return the filename hold by the configuration at *key*. This formats the - filename correctly and supports the Dir:: stuff in the configuration. - - If *key* does not exist, return *default*. - - .. method:: find_dir(key[, default='/']) - - Return the absolute path to the directory specified in *key*. A - trailing slash is appended. - - If *key* does not exist, return *default*. - - .. method:: find_i(key[, default=0]) - - Return the integer value stored at *key*. - - If *key* does not exist, return *default*. - - .. method:: find_b(key[, default=0]) - - Return the boolean value stored at *key*. This returns an integer, but - it should be treated like True/False. - - If *key* does not exist, return *default*. - - .. method:: set(key, value) - - Set the value of *key* to *value*. - - .. method:: exists(key) - - Check whether the key *key* exists in the configuration. - - .. method:: subtree(key) - - Return a sub tree starting at *key*. The resulting object can be used - like this one. - - .. method:: list([key]) - - List all items at *key*. Normally, return the keys at the top level, - eg. APT, Dir, etc. - - Use *key* to specify a key of which the childs will be returned. - - .. method:: value_list([key]) - - Same as :meth:`Configuration.list`, but this time for the values. - - .. method:: my_tag() - - Return the tag name of the current tree. Normally this is an empty - string, but for subtrees it is the key of the subtree. - - .. method:: clear(key) - - Clear the configuration. Remove all values and keys at *key*. - - .. method:: keys([key]) - - Return all the keys, recursive. If *key* is specified, ... (FIXME) - - .. method:: has_key(key) - - Return whether the configuration contains the key *key*. - - .. deprecated:: 0.8.0 - - .. method:: get(key[, default='']) - - This behaves just like :meth:`dict.get` and :meth:`Configuration.find`, - it returns the value of key or if it does not exist, *default*. - -.. class:: ConfigurationPtr - - Behaves like a :class:`Configuration()` objects, but uses a pointer to the - underlying C++ object. This is used for the default configuration in the - :data:`Config` attribute of the module. - -.. class:: ConfigurationSub - - Behaves like a :class:`Configuration()` objects, but provides access to - a subsection of another Configuration-like object. This type of object is - returned by the :meth:`Configuration.subtree()` method. - -.. data:: config - - A :class:`ConfigurationPtr()` object with the default configuration. This - object is initialized by calling :func:`init_config`. - - -Modifying -^^^^^^^^^ - - -.. function:: read_config_file(configuration, filename) - - Read the configuration file specified by the parameter *filename* and add - the settings therein to the :class:`Configuration()` object specified by - the parameter *configuration* - -.. function:: read_config_dir(configuration, dirname) - - Read configuration files in the directory specified by the parameter - *dirname* and add the settings therein to the :class:`Configuration()` - object specified by the parameter *configuration*. - -.. function:: read_config_file_isc(configuration, filename) - - Read the configuration file specified by the parameter *filename* and add - the settings therein to the :class:`Configuration()` object specified by - the parameter *configuration* - -.. function:: parse_commandline(configuration, options, argv) - - This function is like getopt except it manipulates a configuration space. - output is a list of non-option arguments (filenames, etc). *options* is a - list of tuples of the form ``(‘c’,”long-opt or None”, - ”Configuration::Variable”,”optional type”)``. - - Where ``type`` may be one of HasArg, IntLevel, Boolean, InvBoolean, - ConfigFile, or ArbItem. The default is Boolean. - -Locking --------- - -.. function:: get_lock(filename) - - Create an empty file at the path specified by the parameter *filename* and - lock it. - - While the file is locked by a process, calling this function in another - process returns ``-1``. - - When the lock is not required anymore, the file descriptor should be closed - using :func:`os.close`. - -.. function:: pkg_system_lock() - - Lock the global pkgsystem. - -.. function:: pkg_system_un_lock() - - Unlock the global pkgsystem. - -Other classes --------------- -.. class:: Cdrom() - - Return a Cdrom object with the following methods: - - .. method:: ident(progress) - - Identify the cdrom. The parameter *progress* refers to an - :class:`apt.progress.CdromProgress()` object. - - .. method:: add(progress) - - Add the cdrom to the sources.list file. The parameter *progress* - refers to an :class:`apt.progress.CdromProgress()` object. - -.. class:: SourceList - - This is for :file:`/etc/apt/sources.list`. - - .. method:: find_index(pkgfile) - - Return a :class:`PackageIndexFile` object for the :class:`PackageFile` - *pkgfile*. - - .. method:: read_main_list - - Read the main list. - - .. method:: get_indexes(acq[, all]) - - Add the index files to the :class:`Acquire()` object *acq*. If *all* is - given and ``True``, all files are fetched. - -String functions ----------------- -.. function:: base64_encode(string) - - Encode the given string using base64, e.g:: - - >>> apt_pkg.base64_encode(u"A") - 'QQ==' - - -.. function:: check_domain_list(host, list) - - See if Host is in a ',' seperated list, e.g.:: - - apt_pkg.check_domain_list("alioth.debian.org","debian.net,debian.org") - -.. function:: dequote_string(string) - - Dequote the string specified by the parameter *string*, e.g.:: - - >>> apt_pkg.dequote_string("%61%70%74%20is%20cool") - 'apt is cool' - -.. function:: quote_string(string, repl) - - For every character listed in the string *repl*, replace all occurences in - the string *string* with the correct HTTP encoded value: - - >>> apt_pkg.quote_string("apt is cool","apt") - '%61%70%74%20is%20cool' - -.. function:: size_to_str(size) - - Return a string presenting the human-readable version of the integer - *size*. When calculating the units (k,M,G,etc.) the size is divided by the - factor 1000. - - Example:: - - >>> apt_pkg.size_to_str(10000) - '10.0k' - -.. function:: string_to_bool(input) - - Parse the string *input* and return one of **-1**, **0**, **1**. - - .. table:: Return values - - ===== ============================================= - Value Meaning - ===== ============================================= - -1 The string *input* is not recognized. - 0 The string *input* evaluates to **False**. - +1 The string *input* evaluates to **True**. - ===== ============================================= - - Example:: - - >>> apt_pkg.string_to_bool("yes") - 1 - >>> apt_pkg.string_to_bool("no") - 0 - >>> apt_pkg.string_to_bool("not-recognized") - -1 - -.. function:: str_to_time(rfc_time) - - Convert the :rfc:`1123` conforming string *rfc_time* to the unix time, and - return the integer. This is the opposite of :func:`TimeRFC1123`. - - Example:: - - >> apt_pkg.str_to_time('Thu, 01 Jan 1970 00:00:00 GMT') - 0 - -.. function:: time_rfc1123(seconds) - - Format the unix time specified by the integer *seconds*, according to the - requirements of :rfc:`1123`. - - Example:: - - >>> apt_pkg.time_rfc1123(0) - 'Thu, 01 Jan 1970 00:00:00 GMT' - - -.. function:: time_to_str(seconds) - - Format a given duration in a human-readable manner. The parameter *seconds* - refers to a number of seconds, given as an integer. The return value is a - string with a unit like 's' for seconds. - - Example:: - - >>> apt_pkg.time_to_str(3601) - '1h0min1s' - -.. function:: upstream_version(version) - - Return the string *version*, eliminating everything following the last - '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``. - -.. function:: uri_to_filename(uri) - - Take a string *uri* as parameter and return a filename which can be used to - store the file, based on the URI. - - Example:: - - >>> apt_pkg.uri_to_filename('http://debian.org/index.html') - 'debian.org_index.html' - - -.. function:: version_compare(a, b) - - Compare two versions, *a* and *b*, and return an integer value which has - the same characteristic as the built-in :func:`cmp` function. - - .. table:: Return values - - ===== ============================================= - Value Meaning - ===== ============================================= - > 0 The version *a* is greater than version *b*. - = 0 Both versions are equal. - < 0 The version *a* is less than version *b*. - ===== ============================================= - - - - -Module Constants ----------------- -.. _CurStates: - -Package States -^^^^^^^^^^^^^^^ -.. data:: CURSTATE_CONFIG_FILES -.. data:: CURSTATE_HALF_CONFIGURED -.. data:: CURSTATE_HALF_INSTALLED -.. data:: CURSTATE_INSTALLED -.. data:: CURSTATE_NOT_INSTALLED -.. data:: CURSTATE_UNPACKED - - - - -Dependency types -^^^^^^^^^^^^^^^^ -.. data:: DEP_CONFLICTS -.. data:: DEP_DEPENDS -.. data:: DEP_OBSOLETES -.. data:: DEP_PRE_DEPENDS -.. data:: DEP_RECOMMENDS -.. data:: DEP_REPLACES -.. data:: DEP_SUGGESTS - -.. _InstStates: - -Installed states -^^^^^^^^^^^^^^^^ -.. data:: INSTSTATE_HOLD -.. data:: INSTSTATE_HOLD_REINSTREQ -.. data:: INSTSTATE_OK -.. data:: INSTSTATE_REINSTREQ - -.. _Priorities: - -Priorities -^^^^^^^^^^^ -.. data:: PRI_EXTRA -.. data:: PRI_IMPORTANT -.. data:: PRI_OPTIONAL -.. data:: PRI_REQUIRED -.. data:: PRI_STANDARD - - -.. _SelStates: - -Select states -^^^^^^^^^^^^^ -.. data:: SELSTATE_DE_INSTALL -.. data:: SELSTATE_HOLD -.. data:: SELSTATE_INSTALL -.. data:: SELSTATE_PURGE -.. data:: SELSTATE_UNKNOWN - - -Build information -^^^^^^^^^^^^^^^^^ -.. data:: DATE - - The date on which this extension has been compiled. - -.. data:: LIB_VERSION - - The version of the apt_pkg library. This is **not** the version of apt, - nor the version of python-apt. - -.. data:: TIME - - The time this extension has been built. - -.. data:: VERSION - - The version of apt (not of python-apt). - -.. data:: _COMPAT_0_7 - - A more or less internal variable defining whether this build provides an - API which is compatible to the one of python-apt 0.7. This is used in the - apt and aptsources packages to decide whether compatibility should be - enabled or not. diff --git a/doc/source/aptsources/distinfo.rst b/doc/source/aptsources/distinfo.rst deleted file mode 100644 index 96f9445d..00000000 --- a/doc/source/aptsources/distinfo.rst +++ /dev/null @@ -1,10 +0,0 @@ -:mod:`aptsources.distinfo` --- provide meta information for distro repositories -=============================================================================== - -.. automodule:: aptsources.distinfo - :members: - :undoc-members: - - .. note:: - - This part of the documentation is created automatically. diff --git a/doc/source/aptsources/distro.rst b/doc/source/aptsources/distro.rst deleted file mode 100644 index 06ca0fda..00000000 --- a/doc/source/aptsources/distro.rst +++ /dev/null @@ -1,10 +0,0 @@ -:mod:`aptsources.distro` --- Distribution abstraction of the sources.list -=============================================================================== - -.. automodule:: aptsources.distro - :members: - :undoc-members: - - .. note:: - - This part of the documentation is created automatically. diff --git a/doc/source/aptsources/index.rst b/doc/source/aptsources/index.rst deleted file mode 100644 index 898fbf74..00000000 --- a/doc/source/aptsources/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -:mod:`aptsources` --- Working with sources.list -===================================================== -.. automodule:: aptsources - -.. toctree:: - :maxdepth: 2 - :glob: - - * - diff --git a/doc/source/aptsources/sourceslist.rst b/doc/source/aptsources/sourceslist.rst deleted file mode 100644 index 509db3ce..00000000 --- a/doc/source/aptsources/sourceslist.rst +++ /dev/null @@ -1,10 +0,0 @@ -:mod:`aptsources.sourceslist` --- Provide an abstraction of the sources.list -============================================================================ - -.. automodule:: aptsources.sourceslist - :members: - :undoc-members: - - .. note:: - - This part of the documentation is created automatically. diff --git a/doc/source/conf.py b/doc/source/conf.py index 86e6868c..0a9d5ed5 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -54,7 +54,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', intersphinx_mapping = {'http://docs.python.org/': None} # Add any paths that contain templates here, relative to this directory. -templates_path = ['.templates'] +templates_path = ['templates'] # The suffix of source filenames. source_suffix = '.rst' @@ -63,7 +63,7 @@ source_suffix = '.rst' #source_encoding = 'utf-8' # The master toctree document. -master_doc = 'index' +#master_doc = 'contents' # General information about the project. project = u'python-apt' @@ -77,12 +77,21 @@ copyright = u'2009, Julian Andres Klode ' try: release=os.environ['DEBVER'] except KeyError: - from debian_bundle.changelog import Changelog - changes = Changelog(open('../../debian/changelog')) - # The full version, including alpha/beta/rc tags. - release = changes.full_version - -version = '.'.join(release.split('.')[:3]) + from subprocess import Popen, PIPE + p1 = Popen(["dpkg-parsechangelog", "-l../../debian/changelog"], + stdout=PIPE) + p2 = Popen(["sed", "-n", 's/^Version: //p'], stdin=p1.stdout, stdout=PIPE) + release = p2.communicate()[0] + +# Handle the alpha release scheme. +if int(release.split("~")[0].split(".")[2]) >= 90: + version_s = release.split("~")[0].split(".")[:3] + version_s[1] = str(int(version_s[1]) + 1) + version_s[2] = "0" + version = '.'.join(version_s) + del version_s +else: + version = '.'.join(release.split("~")[0].split('.')[:3]) # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -150,7 +159,7 @@ 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' +html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. @@ -161,7 +170,7 @@ html_static_path = ['.static'] # Additional templates that should be rendered to pages, maps page names to # template names. -#html_additional_pages = {} +html_additional_pages = {"index": "indexcontent.html"} # If false, no module index is generated. #html_use_modindex = True @@ -199,7 +208,7 @@ htmlhelp_basename = 'python-aptdoc' # Grouping the document tree into LaTeX files. List of tuples # (source index, target name, title, author, document class [howto/manual]). latex_documents = [ - ('index', 'python-apt.tex', ur'python-apt Documentation', + ('contents', 'python-apt.tex', ur'python-apt Documentation', ur'Julian Andres Klode ', 'manual'), ] diff --git a/doc/source/contents.rst b/doc/source/contents.rst new file mode 100644 index 00000000..3c9fb511 --- /dev/null +++ b/doc/source/contents.rst @@ -0,0 +1,20 @@ +Python APT Documentation contents +====================================== + +Contents: + +.. toctree:: + + whatsnew/index + library/index + tutorials/index + c++/index + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 7c6b6e6d..00000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,308 +0,0 @@ -Contributing to python-apt -========================== -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/examples/apt-cdrom.py b/doc/source/examples/apt-cdrom.py new file mode 100644 index 00000000..a20b0f12 --- /dev/null +++ b/doc/source/examples/apt-cdrom.py @@ -0,0 +1,70 @@ +#!/usr/bin/python +import sys + +import apt_pkg +import apt + + +def show_help(): + print ("apt %s compiled on %s %s" % (apt_pkg.VERSION, + apt_pkg.DATE, apt_pkg.TIME)) + if apt_pkg.config.find_b("version"): + return 0 + + # Copied from apt-cdrom + print ("Usage: apt-cdrom [options] command\n" + "\n" + "apt-cdrom is a tool to add CDROM's to APT's source list. The\n" + "CDROM mount point and device information is taken from apt.conf\n" + "and /etc/fstab.\n" + "\n" + "Commands:\n" + " add - Add a CDROM\n" + " ident - Report the identity of a CDROM\n" + "\n" + "Options:\n" + " -h This help text\n" + " -d CD-ROM mount point\n" + " -r Rename a recognized CD-ROM\n" + " -m No mounting\n" + " -f Fast mode, don't check package files\n" + " -a Thorough scan mode\n" + " -c=? Read this configuration file\n" + " -o=? Set an arbitrary configuration option, eg -o dir::cache=/tmp\n" + "See fstab(5)") + return 0 + + +def main(args): + 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) + + if apt_pkg.config.find_b("help") or apt_pkg.config.find_b("version"): + return show_help() + + progress = apt.progress.text.CdromProgress() + cdrom = apt_pkg.Cdrom() + + if not arguments: + return show_help() + 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]) + return 1 + +if __name__ == '__main__': + sys.exit(main(sys.argv)) diff --git a/doc/source/index.rst b/doc/source/index.rst deleted file mode 100644 index 2e05061a..00000000 --- a/doc/source/index.rst +++ /dev/null @@ -1,41 +0,0 @@ -Welcome to python-apt's documentation! -====================================== - -This is the official documentation for version |version| of the Python bindings -for Debian's famous APT package management. - -This documentation has been created by Sphinx, using reStructuredText files -written by Julian Andres Klode , and in case of the apt -package, from the documentation shipped in the modules. - - -Contents: - -.. toctree:: - :hidden: - - whatsnew/index - -.. toctree:: - :maxdepth: 2 - - whatsnew/0.8.0 - apt/index - apt_pkg - apt_inst - aptsources/index - contributing - - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - - -TODO -====== -.. todolist:: diff --git a/doc/source/library/apt.cache.rst b/doc/source/library/apt.cache.rst new file mode 100644 index 00000000..ddb2dc64 --- /dev/null +++ b/doc/source/library/apt.cache.rst @@ -0,0 +1,78 @@ +:mod:`apt.cache` --- The Cache class +===================================== +.. automodule:: apt.cache + +The Cache class +--------------- + +.. autoclass:: Cache + :members: + :undoc-members: + + .. describe:: cache[pkgname] + + Return a :class:`Package()` for the package with the name *pkgname*. + +Example +^^^^^^^ + +The following example shows how to load the cache, update it, and upgrade +all the packages on the system:: + + import apt + import apt.progress + + # First of all, open the cache + cache = apt.Cache() + # Now, lets update the package list + cache.update() + # We need to re-open the cache because it needs to read the package list + cache.open(None) + # Now we can do the same as 'apt-get upgrade' does + cache.upgrade() + # or we can play 'apt-get dist-upgrade' + cache.upgrade(True) + # Q: Why does nothing happen? + # A: You forgot to call commit()! + cache.commit(apt.progress.TextFetchProgress(), + apt.progress.InstallProgress()) + + + +Working with Filters +-------------------- +.. autoclass:: Filter + :members: + :inherited-members: + :undoc-members: + +.. autoclass:: MarkedChangesFilter + :members: + :inherited-members: + :undoc-members: + +.. autoclass:: FilteredCache + :members: + :inherited-members: + :undoc-members: + + +Example +^^^^^^^ + +This is an example for a filtered cache, which only allows access to the +packages whose state has been changed, eg. packages marked for installation:: + + >>> from apt.cache import FilteredCache, Cache, MarkedChangesFilter + >>> cache = apt.Cache() + >>> changed = apt.FilteredCache(cache) + >>> changed.set_filter(MarkedChangesFilter()) + >>> print len(changed) == len(cache.get_changes()) # Both need to have same length + True + + +Exceptions +---------- +.. autoexception:: FetchCancelledException +.. autoexception:: FetchFailedException +.. autoexception:: LockFailedException diff --git a/doc/source/library/apt.cdrom.rst b/doc/source/library/apt.cdrom.rst new file mode 100644 index 00000000..56381f14 --- /dev/null +++ b/doc/source/library/apt.cdrom.rst @@ -0,0 +1,7 @@ +:mod:`apt.cdrom` - Functionality like in apt-cdrom +==================================================== +.. automodule:: apt.cdrom + :members: + + + diff --git a/doc/source/library/apt.debfile.rst b/doc/source/library/apt.debfile.rst new file mode 100644 index 00000000..7133b5a8 --- /dev/null +++ b/doc/source/library/apt.debfile.rst @@ -0,0 +1,39 @@ +:mod:`apt.debfile` --- Classes related to debian package files +============================================================== +The :mod:`apt.debfile` provides classes to work with locally available +debian packages, or source packages. + +.. module:: apt.debfile + +Binary packages +---------------- +.. autoclass:: DebPackage + :members: + :inherited-members: + :undoc-members: + + The :class:`DebPackage` class is a class for working with '.deb' files, + also known as Debian packages. + + It provides methods and attributes to get a list of the files in the + package, to install the package and much more. + + If you specify *cache* it has to point to an :class:`apt.cache.Cache()` + object. + + .. versionchanged:: 0.7.9 + Introduce all new methods (everything except for :meth:`open()` and + :attr:`filelist`) + + +Source packages +---------------- +.. autoclass:: DscSrcPackage + :members: + :inherited-members: + :undoc-members: + + Provide functionality to work with locally available source packages, + especially with their '.dsc' file. + + .. versionadded:: 0.7.9 diff --git a/doc/source/library/apt.package.rst b/doc/source/library/apt.package.rst new file mode 100644 index 00000000..4b143b8a --- /dev/null +++ b/doc/source/library/apt.package.rst @@ -0,0 +1,111 @@ +:mod:`apt.package` --- Classes for package handling +==================================================== + + +.. automodule:: apt.package + + +The Package class +----------------- +.. autoclass:: Package + :members: + + .. note:: + + Several methods have been deprecated in version 0.7.9 of python-apt, + please see the :class:`Version` class for the new alternatives. + +The Version class +----------------- +.. autoclass:: Version + :members: + + +Dependency Information +---------------------- +.. class:: BaseDependency + + The :class:`BaseDependency` class defines various attributes for accessing + the parts of a dependency. The attributes are as follows: + + .. attribute:: name + + The name of the dependency + + .. attribute:: relation + + The relation (>>,>=,==,<<,<=,) + + .. attribute:: version + + The version or None. + + .. attribute:: pre_depend + + Boolean value whether this is a pre-dependency. + +.. class:: Dependency + + The dependency class represents a Or-Group of dependencies. It provides + an attribute to access the :class:`BaseDependency` object for the available + choices. + + .. attribute:: or_dependencies + + A list of :class:`BaseDependency` objects which could satisfy the + requirement of the Or-Group. + + +Origin Information +------------------- +.. class:: Origin + + The :class:`Origin` class provides access to the origin of the package. + It allows you to check the component, archive, the hostname, and even if + this package can be trusted. + + .. attribute:: archive + + The archive (eg. unstable) + + .. attribute:: component + + The component (eg. main) + + .. attribute:: label + + The Label, as set in the Release file + + .. attribute:: origin + + The Origin, as set in the Release file + + .. attribute:: site + + The hostname of the site. + + .. attribute:: trusted + + Boolean value whether this is trustworthy. An origin can be trusted, if + it provides a GPG-signed Release file and the GPG-key used is in the + keyring used by apt (see apt-key). + +Examples +--------- +.. code-block:: python + + import apt + + cache = apt.Cache() + pkg = cache['python-apt'] # Access the Package object for python-apt + print 'python-apt is trusted:', pkg.candidate.origins[0].trusted + + # Mark python-apt for install + pkg.mark_install() + + print 'python-apt is marked for install:', pkg.marked_install + + print 'python-apt is (summary):', pkg.candidate.summary + + # Now, really install it + cache.commit() diff --git a/doc/source/library/apt.progress.gtk2.rst b/doc/source/library/apt.progress.gtk2.rst new file mode 100644 index 00000000..b16c903c --- /dev/null +++ b/doc/source/library/apt.progress.gtk2.rst @@ -0,0 +1,29 @@ +:mod:`apt.progress.gtk2` --- Progress reporting for GTK+ interfaces +=================================================================== +.. automodule:: apt.progress.gtk2 + + +GObject progress classes +------------------------- + +.. autoclass:: GDpkgInstallProgress + :members: + +.. autoclass:: GFetchProgress + :members: + +.. autoclass:: GInstallProgress + :members: + +.. autoclass:: GOpProgress + :members: + +GTK+ Class +---------- +.. autoclass:: GtkAptProgress + :members: + + +Example +------- +.. literalinclude:: ../examples/apt-gtk.py diff --git a/doc/source/library/apt.progress.qt4.rst b/doc/source/library/apt.progress.qt4.rst new file mode 100644 index 00000000..cd06a4e6 --- /dev/null +++ b/doc/source/library/apt.progress.qt4.rst @@ -0,0 +1,3 @@ +:mod:`apt.progress.qt4` --- Progress reporting for Qt4 interfaces +================================================================= +Not written yet. diff --git a/doc/source/library/apt.progress.text.rst b/doc/source/library/apt.progress.text.rst new file mode 100644 index 00000000..4e051e31 --- /dev/null +++ b/doc/source/library/apt.progress.text.rst @@ -0,0 +1,21 @@ +:mod:`apt.progress.text` --- Progress reporting for text interfaces +=================================================================== +.. automodule:: apt.progress.text + + +Acquire Progress Reporting +-------------------------- +.. autoclass:: AcquireProgress + :members: + + +CD-ROM Progress Reporting +-------------------------- +.. autoclass:: CdromProgress + :members: + +Operation Progress Reporting +----------------------------- +.. autoclass:: OpProgress + :members: + diff --git a/doc/source/library/apt_inst.rst b/doc/source/library/apt_inst.rst new file mode 100644 index 00000000..eef3db9f --- /dev/null +++ b/doc/source/library/apt_inst.rst @@ -0,0 +1,122 @@ +:mod:`apt_inst` - Working with local Debian packages +==================================================== +.. module:: apt_inst + +The :mod:`apt_inst` extension provides access to functions for working with +locally available Debian packages (.deb files) and tar files. + + +Checking packages +------------------ +.. function:: arCheckMember(file, membername) + + Check if the member specified by the parameter *membername* exists in + the AR file referenced by the parameter *file*, which may be a + :class:`file()` object, a file descriptor, or anything implementing a + :meth:`fileno` method. + + .. versionchanged:: 0.8.0 + Added support for file descriptors and objects implementing a :meth:`fileno` method. + + +Listing contents +----------------- +.. function:: debExtract(file, func, chunk) + + Call the function referenced by *func* for each member of the tar file + *chunk* which is contained in the AR file referenced by the parameter + *file*, which may be a :class:`file()` object, a file descriptor, or + anything implementing a :meth:`fileno` method. + + An example would be:: + + debExtract(open("package.deb"), my_callback, "data.tar.gz") + + See :ref:`emulating-dpkg-contents` for a more detailed example. + + .. versionchanged:: 0.8.0 + Added support for file descriptors and objects implementing a :meth:`fileno` method. + +.. function:: tarExtract(file,func,comp) + + Call the function *func* for each member of the tar file *file*. + + The parameter *comp* is a string determining the compressor used. Possible + options are "lzma", "bzip2" and "gzip". + + The parameter *file* may be a :class:`file()` object, a file descriptor, or + anything implementing a :meth:`fileno` method. + + .. versionchanged:: 0.8.0 + Added support for file descriptors and objects implementing a :meth:`fileno` method. + + +Callback +^^^^^^^^^ +Both of these functions expect a callback with the signature +``(what, name, link, mode, uid, gid, size, mtime, major, minor)``. + +The parameter *what* describes the type of the member. It can be 'FILE', +'DIR', or 'HARDLINK'. + +The parameter *name* refers to the name of the member. In case of links, +*link* refers to the target of the link. + + +Extracting contents +------------------- + +.. function:: debExtractArchive(file, rootdir) + + Extract the archive referenced by the :class:`file` object *file* + into the directory specified by *rootdir*. + + The parameter *file* may be a :class:`file()` object, a file descriptor, or + anything implementing a :meth:`fileno` method. + + See :ref:`emulating-dpkg-extract` for an example. + + .. warning:: + + If the directory given by *rootdir* does not exist, the package is + extracted into the current directory. + + .. versionchanged:: 0.8.0 + Added support for file descriptors and objects implementing a :meth:`fileno` method. + +.. function:: debExtractControl(file[, member='control']) + + Return the indicated file as a string from the control tar. The default + is 'control'. + + The parameter *file* may be a :class:`file()` object, a file descriptor, or + anything implementing a :meth:`fileno` method. + + If you want to print the control file of a given package, you could do + something like:: + + print debExtractControl(open("package.deb")) + + .. versionchanged:: 0.8.0 + Added support for file descriptors and objects implementing a :meth:`fileno` method. + + +.. _emulating-dpkg-extract: + +Example: Emulating :program:`dpkg` :option:`--extract` +------------------------------------------------------- +Here is a code snippet which emulates dpkg -x. It can be run as +:program:`tool` :option:`pkg.deb` :option:`outdir`. + +.. literalinclude:: ../examples/dpkg-extract.py + + +.. _emulating-dpkg-contents: + +Example: Emulating :program:`dpkg` :option:`--contents` +------------------------------------------------------- +.. literalinclude:: ../examples/dpkg-contents.py + +Example: Emulating :program:`dpkg` :option:`--info` +---------------------------------------------------- +.. literalinclude:: ../examples/dpkg-info.py diff --git a/doc/source/library/apt_pkg.rst b/doc/source/library/apt_pkg.rst new file mode 100644 index 00000000..6fccc207 --- /dev/null +++ b/doc/source/library/apt_pkg.rst @@ -0,0 +1,1795 @@ +:mod:`apt_pkg` --- The low-level bindings for apt-pkg +===================================================== +.. module:: apt_pkg + +The apt_pkg extensions provides a more low-level way to work with apt. It can +do everything apt can, and is written in C++. It has been in python-apt since +the beginning. + + +Module Initialization +--------------------- + +Initialization is needed for most functions, but not for all of them. Some can +be called without having run init*(), but will not return the expected value. + +.. function:: init_config + + Initialize the configuration of apt. This is needed for most operations. + +.. function:: init_system + + Initialize the system. + +.. function:: init + + Deprecated function. Use init_config() and init_system() instead. + +Working with the cache +---------------------- +.. class:: Cache([progress]) + + Return a :class:`Cache()` object. The optional parameter *progress* + specifies an instance of :class:`apt.progress.OpProgress()` which will + display the open progress. + + .. describe:: cache[pkgname] + + Return the :class:`Package()` object for the package name given by + *pkgname*. + + .. method:: close() + + Close the package cache. + + .. method:: open([progress]) + + Open the package cache again. The parameter *progress* may be set to + an :class:`apt.progress.OpProgress()` object or `None`. + + .. method:: update(progress, list) + + Update the package cache. + + The parameter *progress* points to an :class:`apt.progress.FetchProgress()` + object. The parameter *list* refers to a :class:`SourceList()` object. + + .. attribute:: depends_count + + The total number of dependencies. + + .. attribute:: package_count + + The total number of packages available in the cache. + + .. attribute:: provides_count + + The number of provided packages. + + .. attribute:: ver_file_count + + .. todo:: Seems to be some mixture of versions and pkgFile. + + .. attribute:: version_count + + The total number of package versions available in the cache. + + .. attribute:: package_file_count + + The total number of Packages files available (the Packages files + listing the packages). This is the same as the length of the list in + the attribute :attr:`file_list`. + + .. attribute:: file_list + + A list of :class:`PackageFile` objects. + +.. class:: DepCache(cache) + + Return a :class:`DepCache` object. The parameter *cache* specifies an + instance of :class:`Cache`. + + The DepCache object contains various methods to manipulate the cache, + to install packages, to remove them, and much more. + + .. method:: commit(fprogress, iprogress) + + Apply all the changes made. + + The parameter *fprogress* has to be set to an instance of + apt.progress.FetchProgress or one of its subclasses. + + The parameter *iprogress* has to be set to an instance of + apt.progress.InstallProgress or one of its subclasses. + + .. method:: fix_broken() + + Try to fix all broken packages in the cache. + + .. method:: get_candidate_ver(pkg) + + Return the candidate version of the package, ie. the version that + would be installed normally. + + The parameter *pkg* refers to an :class:`Package` object, + available using the :class:`pkgCache`. + + This method returns a :class:`Version` object. + + .. method:: set_candidate_ver(pkg, version) + + The opposite of :meth:`pkgDepCache.get_candidate_ver`. Set the candidate + version of the :class:`Package` *pkg* to the :class:`Version` + *version*. + + + .. method:: upgrade([dist_upgrade=False]) + + Perform an upgrade. More detailed, this marks all the upgradable + packages for upgrade. You still need to call + :meth:`pkgDepCache.commit` for the changes to apply. + + To perform a dist-upgrade, the optional parameter *dist_upgrade* has + to be set to True. + + .. method:: fix_broken() + + Fix broken packages. + + .. method:: read_pin_file() + + Read the policy, eg. /etc/apt/preferences. + + .. method:: minimize_upgrade() + + Go over the entire set of packages and try to keep each package marked + for upgrade. If a conflict is generated then the package is restored. + + .. todo:: + Explain better.. + + .. method:: mark_keep(pkg) + + Mark the :class:`Package` *pkg* for keep. + + .. method:: mark_delete(pkg[, purge]) + + Mark the :class:`Package` *pkg* for delete. If *purge* is True, + the configuration files will be removed as well. + + .. method:: mark_install(pkg[, auto_inst=True[, from_user=True]]) + + Mark the :class:`Package` *pkg* for install. + + If *auto_inst* is ``True``, the dependencies of the package will be + installed as well. This is the default. + + If *from_user* is ``True``, the package will be marked as manually + installed. This is the default. + + .. method:: set_reinstall(pkg) + + Set if the :class:`Package` *pkg* should be reinstalled. + + .. method:: is_upgradable(pkg) + + Return ``1`` if the package is upgradable. + + The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. + + .. method:: is_now_broken(pkg) + + Return `1` if the package is broken now (including changes made, but + not committed). + + .. method:: is_inst_broken(pkg) + + Return ``1`` if the package is broken on the current install. This + takes changes which have not been committed not into effect. + + .. method:: is_garbage(pkg) + + Return ``1`` if the package is garbage, ie. if it is automatically + installed and no longer referenced by other packages. + + .. method:: is_auto_installed(pkg) + + Return ``1`` if the package is automatically installed (eg. as the + dependency of another package). + + .. method:: marked_install(pkg) + + Return ``1`` if the package is marked for install. + + .. method:: marked_upgrade(pkg) + + Return ``1`` if the package is marked for upgrade. + + .. method:: marked_delete(pkg) + + Return ``1`` if the package is marked for delete. + + .. method:: marked_keep(pkg) + + Return ``1`` if the package is marked for keep. + + .. method:: marked_reinstall(pkg) + + Return ``1`` if the package should be installed. + + .. method:: marked_downgrade(pkg) + + Return ``1`` if the package should be downgraded. + + .. attribute:: keep_count + + Integer, number of packages marked as keep + + .. attribute:: inst_count + + Integer, number of packages marked for installation. + + .. attribute:: del_count + + Number of packages which should be removed. + + .. attribute:: broken_count + + Number of packages which are broken. + + .. attribute:: usr_size + + The size required for the changes on the filesystem. If you install + packages, this is positive, if you remove them its negative. + + .. attribute:: deb_size + + The size of the packages which are needed for the changes to be + applied. + + +.. class:: PackageManager(depcache) + + Return a new :class:`PackageManager` object. The parameter *depcache* + specifies a :class:`DepCache` object. + + :class:`PackageManager` objects provide several methods and attributes, + which will be listed here: + + .. method:: get_archives(fetcher, list, records) + + Add all the selected packages to the :class:`Acquire()` object + *fetcher*. + + The parameter *list* refers to a :class:`SourceList()` object. + + The parameter *records* refers to a :class:`PackageRecords()` object. + + .. method:: do_install() + + Install the packages. + + .. method:: fix_missing + + Fix the installation if a package could not be downloaded. + + .. attribute:: result_completed + + A constant for checking whether the the result is 'completed'. + + Compare it against the return value of :meth:`PackageManager.get_archives` + or :meth:`PackageManager.do_install`. + + .. attribute:: result_failed + + A constant for checking whether the the result is 'failed'. + + Compare it against the return value of :meth:`PackageManager.get_archives` + or :meth:`PackageManager.do_install`. + + .. attribute:: result_incomplete + + A constant for checking whether the the result is 'incomplete'. + + Compare it against the return value of :meth:`PackageManager.get_archives` + or :meth:`PackageManager.do_install`. + +Improve performance with :class:`ActionGroup` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: ActionGroup(depcache) + + Create a new :class:`ActionGroup()` object for the :class:`DepCache` object + given by the parameter *depcache*. + + :class:`ActionGroup()` objects make operations on the cache faster by + delaying certain cleanup operations until the action group is released. + + ActionGroup is also a context manager and therefore supports the + :keyword:`with` statement. But because it becomes active as soon as it + is created, you should not create an ActionGroup() object before entering + the with statement. + + If you want to use ActionGroup as a with statement (which is recommended + because it makes it easier to see when an actiongroup is active), always + use the following form:: + + with apt_pkg.ActionGroup(depcache): + ... + + For code which has to run on Python versions prior to 2.5, you can also + use the traditional way:: + + actiongroup = apt_pkg.ActionGroup(depcache) + ... + actiongroup.release() + + :class:`ActionGroup` provides the following method: + + .. method:: release() + + Release the ActionGroup. This will reactive the collection of package + garbage. + +Resolving Dependencies +^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: ProblemResolver(depcache) + + Return a new :class:`ProblemResolver` object. The parameter *depcache* + specifies a :class:`pDepCache` object. + + The problem resolver helps when there are problems in the package + selection. An example is a package which conflicts with another, already + installed package. + + .. method:: protect(pkg) + + Protect the :class:`Package()` object given by the parameter *pkg*. + + .. todo:: + + Really document it. + + .. method:: install_protect() + + Protect all installed packages from being removed. + + .. method:: remove(pkg) + + Remove the :class:`Package()` object given by the parameter *pkg*. + + .. todo:: + + Really document it. + + .. method:: clear(pkg) + + Reset the :class:`Package()` *pkg* to the default state. + + .. todo:: + + Really document it. + + .. method:: resolve() + + Try to resolve problems by installing and removing packages. + + .. method:: resolve_by_keep() + + Try to resolve problems only by using keep. + + +:class:`PackageFile` +-------------------- +.. class:: PackageFile + + A :class:`PackageFile` represents a Packages file, eg. + /var/lib/dpkg/status. + + .. attribute:: architecture + + The architecture of the package file. + + .. attribute:: archive + + The archive (eg. unstable) + + .. attribute:: component + + The component (eg. main) + + .. attribute:: filename + + The name of the file. + + .. attribute:: id + + The ID of the package. This is an integer which can be used to store + further information about the file [eg. as dictionary key]. + + .. attribute:: index_type + + The sort of the index file. In normal cases, this is + 'Debian Package Index'. + + .. attribute:: label + + The Label, as set in the Release file + + .. attribute:: not_automatic + + Whether packages from this list will be updated automatically. The + default for eg. example is 0 (aka false). + + .. attribute:: not_source + + Whether the file has no source from which it can be updated. In such a + case, the value is 1; else 0. /var/lib/dpkg/status is 0 for example. + + Example:: + + for pkgfile in cache.file_list: + if pkgfile.not_source: + print 'The file %s has no source.' % pkgfile.filename + + .. attribute:: origin + + The Origin, as set in the Release file + + .. attribute:: site + + The hostname of the site. + + .. attribute:: size + + The size of the file. + + .. attribute:: version + + The version, as set in the release file (eg. "4.0" for "Etch") + + +Example +^^^^^^^ +.. literalinclude:: ../examples/cache-pkgfile.py + + +:class:`Package` +---------------- + +.. class:: Package + + The pkgCache::Package objects are an interface to package specific + features. + + + Attributes: + + .. attribute:: current_ver + + The version currently installed, or None. This returns a + :class:`Version` object. + + .. attribute:: id + + The ID of the package. This can be used to store information about + the package. The ID is an int value. + + .. attribute:: name + + This is the name of the package. + + .. attribute:: provides_list + + A list of packages providing this package. More detailed, this is a + list of tuples (str:pkgname, ????, :class:`Version`). + + If you want to check for check for virtual packages, the expression + ``pkg.provides_list and not pkg._version_list`` helps you. It detects if + the package is provided by something else and is not available as a + real package. + + .. attribute:: rev_depends_list + + An iterator of :class:`Dependency` objects for dependencies on this + package. + + .. attribute:: section + + The section of the package, as specified in the record. The list of + possible sections is defined in the Policy. + + .. attribute:: version_list + + A list of :class:`Version` objects for all versions available in the + cache. + + **States**: + + .. attribute:: selected_state + + The state we want it to be, ie. if you mark a package for installation, + this is :attr:`apt_pkg.SELSTATE_INSTALL`. + + See :ref:`SelStates` for a list of available states. + + .. attribute:: inst_state + + The state the currently installed version is in. This is normally + :attr:`apt_pkg.INSTSTATE_OK`, unless the installation failed. + + See :ref:`InstStates` for a list of available states. + + .. attribute:: cur_state + + The current state of the package (not installed, unpacked, installed, + etc). See :ref:`CurStates` for a list of available states. + + **Flags**: + + .. attribute:: auto + + Whether the package was installed automatically as a dependency of + another package. (or marked otherwise as automatically installed) + + .. attribute:: essential + + Whether the package is essential. + + .. attribute:: important + + Whether the package is important. + +Example: +^^^^^^^^^ +.. literalinclude:: ../examples/cache-packages.py + + + +:class:`Version` +---------------- +.. class:: Version + + The version object contains all information related to a specific package + version. + + .. attribute:: ver_str + + The version, as a string. + + .. attribute:: section + + The usual sections (eg. admin, net, etc.). Prefixed with the component + name for packages not in main (eg. non-free/admin). + + .. attribute:: arch + + The architecture of the package, eg. amd64 or all. + + .. attribute:: file_list + + A list of (:class:`PackageFile`, int: index) tuples for all Package + files containing this version of the package. + + .. attribute:: depends_list_str + + A dictionary of dependencies. The key specifies the type of the + dependency ('Depends', 'Recommends', etc.). + + + The value is a list, containing items which refer to the or-groups of + dependencies. Each of these or-groups is itself a list, containing + tuples like ('pkgname', 'version', 'relation') for each or-choice. + + An example return value for a package with a 'Depends: python (>= 2.4)' + would be:: + + {'Depends': [ + [ + ('python', '2.4', '>=') + ] + ] + } + + The same for a dependency on A (>= 1) | B (>= 2):: + + {'Depends': [ + [ + ('A', '1', '>='), + ('B', '2', '>='), + ] + ] + } + + .. attribute:: depends_list + + This is basically the same as :attr:`Version.DependsListStr`, + but instead of the ('pkgname', 'version', 'relation') tuples, + it returns :class:`Dependency` objects, which can assist you with + useful functions. + + .. attribute:: parent_pkg + + The :class:`Package` object this version belongs to. + + .. attribute:: provides_list + + This returns a list of all packages provided by this version. Like + :attr:`Package.provides_list`, it returns a list of tuples + of the form ('virtualpkgname', ???, :class:`Version`), where as the + last item is the same as the object itself. + + .. attribute:: size + + The size of the .deb file, in bytes. + + .. attribute:: installed_size + + The size of the package (in kilobytes), when unpacked on the disk. + + .. attribute:: hash + + An integer hash value. + + .. attribute:: id + + An integer id. + + .. attribute:: priority + + The integer representation of the priority. This can be used to speed + up comparisons a lot, compared to :attr:`Version.priority_str`. + + The values are defined in the :mod:`apt_pkg` extension, see + :ref:`Priorities` for more information. + + .. attribute:: priority_str + + Return the priority of the package version, as a string, eg. + "optional". + + .. attribute:: downloadable + + Whether this package can be downloaded from a remote site. + + .. attribute:: translated_description + + Return a :class:`Description` object. + + +:class:`Dependency` +------------------- +.. class:: Dependency + + Represent a dependency from one package to another one. + + .. method:: all_targets + + A list of :class:`Version` objects which satisfy the dependency, + and do not conflict with already installed ones. + + From my experience, if you use this method to select the target + version, it is the best to select the last item unless any of the + other candidates is already installed. This leads to results being + very close to the normal package installation. + + .. method:: smart_target_pkg + + Return a :class:`Version` object of a package which satisfies the + dependency and does not conflict with installed packages + (the 'natural target'). + + .. attribute:: target_ver + + The target version of the dependency, as string. Empty string if the + dependency is not versioned. + + .. attribute:: target_pkg + + The :class:`Package` object of the target package. + + .. attribute:: parent_ver + + The :class:`Version` object of the parent version, ie. the package + which declares the dependency. + + .. attribute:: parent_pkg + + The :class:`Package` object of the package which declares the + dependency. This is the same as using ParentVer.ParentPkg. + + .. attribute:: comp_type + + The type of comparison (>=, ==, >>, <=), as string. + + .. attribute:: dep_type + + The type of the dependency, as string, eg. "Depends". + + .. attribute:: id + + The ID of the package, as integer. + +Example: Find all missing dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +With the help of Dependency.AllTargets(), you can easily find all packages with +broken dependencies: + +.. literalinclude:: ../examples/missing-deps.py + + +:class:`Description` +-------------------- +.. class:: Description + + Represent the description of the package. + + .. attribute:: language_code + + The language code of the description + + .. attribute:: md5 + + The md5 hashsum of the description + + .. attribute:: file_list + + A list of tuples (:class:`PackageFile`, int: index). + + + +:class:`MetaIndex` +------------------ + +.. todo:: + + Complete them + +.. class:: MetaIndex + + .. attribute:: uri + .. attribute:: dist + .. attribute:: is_trusted + .. attribute:: index_files + + +:class:`PackageIndexFile` +------------------------- + +.. class:: PackageIndexFile + + .. method:: archive_uri(path) + + Return the full url to path in the archive. + + .. attribute:: label + + Return the Label. + + .. attribute:: exists + + Return whether the file exists. + + .. attribute:: has_packages + + Return whether the file has packages. + + .. attribute:: size + + Size of the file + + .. attribute:: is_trusted + + Whether we can trust the file. + + +Records +-------- + +.. class:: PackageRecords(cache) + + Create a new :class:`PackageRecords` object, for the packages in the cache + specified by the parameter *cache*. + + Provide access to the packages records. This provides very useful + attributes for fast (convient) access to some fields of the record. + + .. method:: lookup(verfile_iter) + + Change the actual package to the package given by the verfile_iter. + + The parameter *verfile_iter* refers to a tuple consisting + of (:class:`PackageFile()`, int: index), as returned by various + attributes, including :attr:`Version.file_list`. + + Example (shortened):: + + cand = depcache.GetCandidateVer(cache['python-apt']) + records.Lookup(cand.FileList[0]) + # Now you can access the record + print records.SourcePkg # == python-apt + + .. attribute:: filename + + Return the field 'Filename' of the record. This is the path to the + package, relative to the base path of the archive. + + .. attribute:: md5_hash + + Return the MD5 hashsum of the package This refers to the field + 'MD5Sum' in the raw record. + + .. attribute:: sha1_hash + + Return the SHA1 hashsum of the package. This refers to the field 'SHA1' + in the raw record. + + .. attribute:: sha256_hash + + Return the SHA256 hashsum of the package. This refers to the field + 'SHA256' in the raw record. + + .. versionadded:: 0.7.9 + + .. attribute:: source_pkg + + Return the source package. + + .. attribute:: source_ver + + Return the source version. + + .. attribute:: maintainer + + Return the maintainer of the package. + + .. attribute:: short_desc + + Return the short description. This is the summary on the first line of + the 'Description' field. + + .. attribute:: long_desc + + Return the long description. These are lines 2-END from the + 'Description' field. + + .. attribute:: name + + Return the name of the package. This is the 'Package' field. + + .. attribute:: homepage + + Return the Homepage. This is the 'Homepage' field. + + .. attribute:: record + + Return the whole record as a string. If you want to access fields of + the record not available as an attribute, you can use + :class:`apt_pkg.TagSection` to parse the record and access the field + name. + + Example:: + + section = apt_pkg.TagSection(records.record) + print section['SHA256'] # Use records.sha256_hash instead + + +.. class:: SourceRecords + + This represents the entries in the Sources files, ie. the dsc files of + the source packages. + + .. note:: + + If the Lookup failed, because no package could be found, no error is + raised. Instead, the attributes listed below are simply not existing + anymore (same applies when no Lookup has been made, or when it has + been restarted). + + .. method:: lookup(pkgname) + + Lookup the record for the package named *pkgname*. To access all + available records, you need to call it multiple times. + + Imagine a package P with two versions X, Y. The first ``lookup(P)`` + would set the record to version X and the second ``lookup(P)`` to + version Y. + + .. method:: restart() + + Restart the lookup. + + Imagine a package P with two versions X, Y. The first ``Lookup(P)`` + would set the record to version X and the second ``Lookup(P)`` to + version Y. + + If you now call ``restart()``, the internal position will be cleared. + Now you can call ``lookup(P)`` again to move to X. + + .. attribute:: package + + The name of the source package. + + .. attribute:: version + + A string describing the version of the source package. + + .. attribute:: maintainer + + A string describing the name of the maintainer. + + .. attribute:: section + + A string describing the section. + + .. attribute:: record + + The whole record, as a string. You can use :func:`apt_pkg.ParseSection` + if you need to parse it. + + You need to parse the record if you want to access fields not available + via the attributes, eg. 'Standards-Version' + + .. attribute:: binaries + + Return a list of strings describing the package names of the binaries + created by the source package. This matches the 'Binary' field in the + raw record. + + .. attribute:: index + + The index in the Sources files. + + .. attribute:: files + + The list of files. This returns a list of tuples with the contents + ``(str: md5, int: size, str: path, str:type)``. + + .. attribute:: build_depends + + Return a dictionary representing the build-time dependencies of the + package. The format is the same as for :attr:`Version.depends_list_str` + and possible keys being ``"Build-Depends"``, ``"Build-Depends-Indep"``, + ``"Build-Conflicts"`` or ``"Build-Conflicts-Indep"``. + + .. attribute:: BuildDepends + + Return the list of Build dependencies, as + ``(str: package, str: version, int: op, int: type)``. This is a + completely deprecated format + + .. table:: Values of *op* + + ===== ============================================= + Value Meaning + ===== ============================================= + 0x00 No Operation (no versioned build dependency) + 0x10 | (or) - this will be added to the other values + 0x01 <= (less than or equal) + 0x02 >= (greater than or equal) + 0x03 << (less than) + 0x04 >> (greater than) + 0x05 = (equal) + 0x06 != (not equal) + ===== ============================================= + + .. table:: Values of *type* + + ===== =================== + Value Meaning + ===== =================== + 0 Build-Depends + 1 Build-Depends-Indep + 2 Build-Conflicts + 3 Build-Conflicts-Indep + ===== =================== + + **Example**: In the following content, we will imagine a + build-dependency:: + + Build-Depends: A (>= 1) | B (>= 1), C + + This results in:: + + [('A', '1', 18, 0), # 18 = (16 | 2) = (0x10 | 0x2) + ('B', '1', 2, 0), + ('C', '', 0, 0)] + + This is **not** the same as returned by + :func:`apt_pkg.ParseSrcDepends`. + + + +The Acquire interface +---------------------- +The Acquire Interface is responsible for all sorts of downloading in apt. All +packages, index files, etc. downloading is done using the Acquire functionality. + +The :mod:`apt_pkg` module provides a subset of this functionality which allows +you to implement file downloading in your applications. Together with the +:class:`PackageManager` class you can also fetch all the packages marked for +installation. + + +.. class:: Acquire([progress]) + + Return an :class:`Acquire` object. The parameter *progress* refers to + an :class:`apt.progress.FetchProgress()` object. + + Acquire objects maintaing a list of items which will be fetched or have + been fetched already during the lifetime of this object. To add new items + to this list, you can create new :class:`AcquireFile` objects which allow + you to add single files. + + Acquire items have multiple methods: + + .. method:: run() + + Fetch all the items which have been added by :class:`AcquireFile`. + + .. method:: shutdown() + + Shut the fetcher down. + + .. attribute:: total_needed + + The total amount of bytes needed (including those of files which are + already present) + + .. attribute:: fetch_needed + + The total amount of bytes which need to be fetched. + + .. attribute:: partial_present + + Whether some files have been acquired already. (???) + +.. class:: AcquireItem + + The :class:`AcquireItem()` objects represent the items of a + :class:`Acquire` object. :class:`AcquireItem()` objects can not be created + by the user, they are solely available through the :attr:`Acquire.items` + list of an :class:`Acquire` object. + + .. attribute:: id + + The ID of the item. + + .. attribute:: complete + + Is the item completely acquired? + + .. attribute:: local + + Is the item a local file? + + .. attribute:: is_trusted + + Can the file be trusted? + + .. attribute:: file_size + + The size of the file, in bytes. + + .. attribute:: error_text + + The error message. For example, when a file does not exist on a http + server, this will contain a 404 error message. + + .. attribute:: dest_file + + The location the file is saved as. + + .. attribute:: desc_uri + + The source location. + + **Status**: + + .. attribute:: status + + Integer, representing the status of the item. + + .. attribute:: stat_idle + + Constant for comparing :attr:`AcquireItem.status`. + + .. attribute:: stat_fetching + + Constant for comparing :attr:`AcquireItem.status` + + .. attribute:: stat_done + + Constant for comparing :attr:`AcquireItem.status` + + .. attribute:: stat_error + + Constant for comparing :attr:`AcquireItem.status` + + .. attribute:: stat_auth_error + + Constant for comparing :attr:`AcquireItem.status` + + +.. class:: AcquireFile(owner, uri[, md5, size, descr, short_descr, destdir, destfile]) + + Create a new :class:`AcquireFile()` object and register it with *acquire*, + so it will be fetched. AcquireFile objects provide no methods or attributes + and are completely useless at the moment. + + The parameter *owner* refers to an :class:`Acquire()` object as returned + by :func:`GetAcquire`. The file will be added to the Acquire queue + automatically. + + The parameter *uri* refers to the location of the file, any protocol + of apt is supported. + + The parameter *md5* refers to the md5sum of the file. This can be used + for checking the file. + + The parameter *size* can be used to specify the size of the package, + which can then be used to calculate the progress and validate the download. + + The parameter *descr* is a descripition of the download. It may be + used to describe the item in the progress class. *short_descr* is the + short form of it. + + You can use *destdir* to manipulate the directory where the file will + be saved in. Instead of *destdir*, you can also specify the full path to + the file using the parameter *destfile*. You can not combine both. + + +Hashes +------ +The apt_pkg module also provides several hash functions. If you develop +applications with python-apt it is often easier to use these functions instead +of the ones provides in Python's :mod:`hashlib` module. + +.. class:: Hashes(object) + + Calculate all supported hashes of the object. *object* may either be a + string, in which cases the hashes of the string are calculated, or a + :class:`file()` object or file descriptor, in which case the hashes of + its contents is calculated. The calculated hashes are then available via + attributes: + + .. attribute:: md5 + + The MD5 hash of the data, as string. + + .. attribute:: sha1 + + The SHA1 hash of the data, as string. + + .. attribute:: sha256 + + The SHA256 hash of the data, as string. + +.. function:: md5sum(object) + + Return the md5sum of the object. *object* may either be a string, in + which case the md5sum of the string is returned, or a :class:`file()` + object (or a file descriptor), in which case the md5sum of its contents is + returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +.. function:: sha1sum(object) + + Return the sha1sum of the object. *object* may either be a string, in + which case the sha1sum of the string is returned, or a :class:`file()` + object (or a file descriptor), in which case the sha1sum of its contents + is returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +.. function:: sha256sum(object) + + Return the sha256sum of the object. *object* may either be a string, in + which case the sha256sum of the string is returned, or a :class:`file()` + object (or a file descriptor), in which case the sha256sum of its contents + is returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +Debian control files +-------------------- +Debian control files are files containing multiple stanzas of :RFC:`822`-style +header sections. They are widely used in the Debian community, and can represent +many kinds of information. One example for such a file is the +:file:`/var/lib/dpkg/status` file which contains a list of the currently +installed packages. + +The :mod:`apt_pkg` module provides two classes to read those files and parts +thereof and provides a function :func:`RewriteSection` which takes a +:class:`TagSection()` object and sorting information and outputs a sorted +section as a string. + +.. class:: TagFile(file) + + An object which represents a typical debian control file. Can be used for + Packages, Sources, control, Release, etc. + + An example for working with a TagFile could look like:: + + tagf = apt_pkg.TagFile(open('/var/lib/dpkg/status')) + tagf.step() + print tagf.section['Package'] + + .. method:: step + + Step forward to the next section. This simply returns ``1`` if OK, and + ``0`` if there is no section + + .. method:: offset + + Return the current offset (in bytes) from the beginning of the file. + + .. method:: jump(offset) + + Jump back/forward to *offset*. Use ``jump(0)`` to jump to the + beginning of the file again. + + .. attribute:: section + + This is the current :class:`TagSection()` instance. + +.. class:: TagSection(text) + + Represent a single section of a debian control file. + + .. describe:: section[key] + + Return the value of the field at *key*. If *key* is not available, + raise :exc:`KeyError`. + + .. describe:: key in section + + Return ``True`` if *section* has a key *key*, else ``False``. + + .. versionadded:: 0.8.0 + + .. method:: bytes + + The number of bytes in the section. + + .. method:: find(key, default='') + + Return the value of the field at the key *key* if available, + else return *default*. + + .. method:: find_flag(key) + + Find a yes/no value for the key *key*. An example for such a + field is 'Essential'. + + .. method:: get(key, default='') + + Return the value of the field at the key *key* if available, else + return *default*. + + .. method:: has_key(key) + + Check whether the field with named by *key* exists. + + .. deprecated:: 0.8.0 + + .. method:: keys() + + Return a list of keys in the section. + +.. function:: rewrite_section(section: TagSection, order: list, rewrite_list: list) -> str + + Rewrite the section given by *section* using *rewrite_list*, and order the + fields according to *order*. + + The parameter *order* is a :class:`list` object containing the names of the + fields in the order they should appear in the rewritten section. + :data:`apt_pkg.REWRITE_PACKAGE_ORDER` and + :data:`apt_pkg.REWRITE_SOURCE_ORDER` are two predefined lists for rewriting + package and source sections, respectively. + + The parameter *rewrite_list* is a list of tuples of the form + ``(tag, newvalue[, renamed_to])``, whereas *tag* describes the field which + should be changed, *newvalue* the value which should be inserted or + ``None`` to delete the field, and the optional *renamed_to* can be used + to rename the field. + +.. data:: REWRITE_PACKAGE_ORDER + + The order in which the information for binary packages should be rewritten, + i.e. the order in which the fields should appear. + +.. data:: REWRITE_SOURCE_ORDER + + The order in which the information for source packages should be rewritten, + i.e. the order in which the fields should appear. + +Dependencies +------------ +.. function:: check_dep(pkgver, op, depver) + + Check that the dependency requirements consisting of op and depver can be + satisfied by the version pkgver. + + Example:: + + >>> bool(apt_pkg.check_dep("1.0", ">=", "1")) + True + +.. function:: parse_depends(depends) + + Parse the string *depends* which contains dependency information as + specified in Debian Policy, Section 7.1. + + Returns a list. The members of this list are lists themselves and contain + one or more tuples in the format ``(package,version,operation)`` for every + 'or'-option given, e.g.:: + + >>> apt_pkg.parse_depends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + + + .. note:: + + The behavior of this function is different than the behavior of the + old function :func:`ParseDepends()`, because the third field + ``operation`` uses `>` instead of `>>` and `<` instead of `<<` which + is specified in control files. + + +.. function:: parse_src_depends(depends) + + Parse the string *depends* which contains dependency information as + specified in Debian Policy, Section 7.1. + + Returns a list. The members of this list are lists themselves and contain + one or more tuples in the format ``(package,version,operation)`` for every + 'or'-option given, e.g.:: + + >>> apt_pkg.parse_depends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + + + Furthemore, this function also supports to limit the architectures, as + used in e.g. Build-Depends:: + + >>> apt_pkg.parse_src_depends("a (>= 01) [i386 amd64]") + [[('a', '01', '>=')]] + + .. note:: + + The behavior of this function is different than the behavior of the + old function :func:`ParseDepends()`, because the third field + ``operation`` uses `>` instead of `>>` and `<` instead of `<<` which + is specified in control files. + + +Configuration +------------- + +.. class:: Configuration() + + Configuration() objects store the configuration of apt, mostly created from + the contents of :file:`/etc/apt.conf` and the files in + :file:`/etc/apt.conf.d`. + + .. describe:: key in conf + + Return ``True`` if *conf* has a key *key*, else ``False``. + + .. versionadded:: 0.8.0 + + .. describe:: conf[key] + + Return the value of the option given key *key*. If it does not + exist, raise :exc:`KeyError`. + + .. describe:: conf[key] = value + + Set the option at *key* to *value*. + + .. method:: find(key[, default='']) + + Return the value for the given key *key*. This is the same as + :meth:`Configuration.get`. + + If *key* does not exist, return *default*. + + .. method:: find_file(key[, default='']) + + Return the filename hold by the configuration at *key*. This formats the + filename correctly and supports the Dir:: stuff in the configuration. + + If *key* does not exist, return *default*. + + .. method:: find_dir(key[, default='/']) + + Return the absolute path to the directory specified in *key*. A + trailing slash is appended. + + If *key* does not exist, return *default*. + + .. method:: find_i(key[, default=0]) + + Return the integer value stored at *key*. + + If *key* does not exist, return *default*. + + .. method:: find_b(key[, default=0]) + + Return the boolean value stored at *key*. This returns an integer, but + it should be treated like True/False. + + If *key* does not exist, return *default*. + + .. method:: set(key, value) + + Set the value of *key* to *value*. + + .. method:: exists(key) + + Check whether the key *key* exists in the configuration. + + .. method:: subtree(key) + + Return a sub tree starting at *key*. The resulting object can be used + like this one. + + .. method:: list([key]) + + List all items at *key*. Normally, return the keys at the top level, + eg. APT, Dir, etc. + + Use *key* to specify a key of which the childs will be returned. + + .. method:: value_list([key]) + + Same as :meth:`Configuration.list`, but this time for the values. + + .. method:: my_tag() + + Return the tag name of the current tree. Normally this is an empty + string, but for subtrees it is the key of the subtree. + + .. method:: clear(key) + + Clear the configuration. Remove all values and keys at *key*. + + .. method:: keys([key]) + + Return all the keys, recursive. If *key* is specified, ... (FIXME) + + .. method:: has_key(key) + + Return whether the configuration contains the key *key*. + + .. deprecated:: 0.8.0 + + .. method:: get(key[, default='']) + + This behaves just like :meth:`dict.get` and :meth:`Configuration.find`, + it returns the value of key or if it does not exist, *default*. + +.. class:: ConfigurationPtr + + Behaves like a :class:`Configuration()` objects, but uses a pointer to the + underlying C++ object. This is used for the default configuration in the + :data:`Config` attribute of the module. + +.. class:: ConfigurationSub + + Behaves like a :class:`Configuration()` objects, but provides access to + a subsection of another Configuration-like object. This type of object is + returned by the :meth:`Configuration.subtree()` method. + +.. data:: config + + A :class:`ConfigurationPtr()` object with the default configuration. This + object is initialized by calling :func:`init_config`. + + +Modifying +^^^^^^^^^ + + +.. function:: read_config_file(configuration, filename) + + Read the configuration file specified by the parameter *filename* and add + the settings therein to the :class:`Configuration()` object specified by + the parameter *configuration* + +.. function:: read_config_dir(configuration, dirname) + + Read configuration files in the directory specified by the parameter + *dirname* and add the settings therein to the :class:`Configuration()` + object specified by the parameter *configuration*. + +.. function:: read_config_file_isc(configuration, filename) + + Read the configuration file specified by the parameter *filename* and add + the settings therein to the :class:`Configuration()` object specified by + the parameter *configuration* + +.. function:: parse_commandline(configuration, options, argv) + + This function is like getopt except it manipulates a configuration space. + output is a list of non-option arguments (filenames, etc). *options* is a + list of tuples of the form ``(‘c’,”long-opt or None”, + ”Configuration::Variable”,”optional type”)``. + + Where ``type`` may be one of HasArg, IntLevel, Boolean, InvBoolean, + ConfigFile, or ArbItem. The default is Boolean. + +Locking +-------- + +.. function:: get_lock(filename) + + Create an empty file at the path specified by the parameter *filename* and + lock it. + + While the file is locked by a process, calling this function in another + process returns ``-1``. + + When the lock is not required anymore, the file descriptor should be closed + using :func:`os.close`. + +.. function:: pkg_system_lock() + + Lock the global pkgsystem. + +.. function:: pkg_system_un_lock() + + Unlock the global pkgsystem. + +Other classes +-------------- +.. class:: Cdrom() + + Return a Cdrom object with the following methods: + + .. method:: ident(progress) + + Identify the cdrom. The parameter *progress* refers to an + :class:`apt.progress.CdromProgress()` object. + + .. method:: add(progress) + + Add the cdrom to the sources.list file. The parameter *progress* + refers to an :class:`apt.progress.CdromProgress()` object. + +.. class:: SourceList + + This is for :file:`/etc/apt/sources.list`. + + .. method:: find_index(pkgfile) + + Return a :class:`PackageIndexFile` object for the :class:`PackageFile` + *pkgfile*. + + .. method:: read_main_list + + Read the main list. + + .. method:: get_indexes(acq[, all]) + + Add the index files to the :class:`Acquire()` object *acq*. If *all* is + given and ``True``, all files are fetched. + +String functions +---------------- +.. function:: base64_encode(string) + + Encode the given string using base64, e.g:: + + >>> apt_pkg.base64_encode(u"A") + 'QQ==' + + +.. function:: check_domain_list(host, list) + + See if Host is in a ',' seperated list, e.g.:: + + apt_pkg.check_domain_list("alioth.debian.org","debian.net,debian.org") + +.. function:: dequote_string(string) + + Dequote the string specified by the parameter *string*, e.g.:: + + >>> apt_pkg.dequote_string("%61%70%74%20is%20cool") + 'apt is cool' + +.. function:: quote_string(string, repl) + + For every character listed in the string *repl*, replace all occurences in + the string *string* with the correct HTTP encoded value: + + >>> apt_pkg.quote_string("apt is cool","apt") + '%61%70%74%20is%20cool' + +.. function:: size_to_str(size) + + Return a string presenting the human-readable version of the integer + *size*. When calculating the units (k,M,G,etc.) the size is divided by the + factor 1000. + + Example:: + + >>> apt_pkg.size_to_str(10000) + '10.0k' + +.. function:: string_to_bool(input) + + Parse the string *input* and return one of **-1**, **0**, **1**. + + .. table:: Return values + + ===== ============================================= + Value Meaning + ===== ============================================= + -1 The string *input* is not recognized. + 0 The string *input* evaluates to **False**. + +1 The string *input* evaluates to **True**. + ===== ============================================= + + Example:: + + >>> apt_pkg.string_to_bool("yes") + 1 + >>> apt_pkg.string_to_bool("no") + 0 + >>> apt_pkg.string_to_bool("not-recognized") + -1 + +.. function:: str_to_time(rfc_time) + + Convert the :rfc:`1123` conforming string *rfc_time* to the unix time, and + return the integer. This is the opposite of :func:`TimeRFC1123`. + + Example:: + + >> apt_pkg.str_to_time('Thu, 01 Jan 1970 00:00:00 GMT') + 0 + +.. function:: time_rfc1123(seconds) + + Format the unix time specified by the integer *seconds*, according to the + requirements of :rfc:`1123`. + + Example:: + + >>> apt_pkg.time_rfc1123(0) + 'Thu, 01 Jan 1970 00:00:00 GMT' + + +.. function:: time_to_str(seconds) + + Format a given duration in a human-readable manner. The parameter *seconds* + refers to a number of seconds, given as an integer. The return value is a + string with a unit like 's' for seconds. + + Example:: + + >>> apt_pkg.time_to_str(3601) + '1h0min1s' + +.. function:: upstream_version(version) + + Return the string *version*, eliminating everything following the last + '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``. + +.. function:: uri_to_filename(uri) + + Take a string *uri* as parameter and return a filename which can be used to + store the file, based on the URI. + + Example:: + + >>> apt_pkg.uri_to_filename('http://debian.org/index.html') + 'debian.org_index.html' + + +.. function:: version_compare(a, b) + + Compare two versions, *a* and *b*, and return an integer value which has + the same characteristic as the built-in :func:`cmp` function. + + .. table:: Return values + + ===== ============================================= + Value Meaning + ===== ============================================= + > 0 The version *a* is greater than version *b*. + = 0 Both versions are equal. + < 0 The version *a* is less than version *b*. + ===== ============================================= + + + + +Module Constants +---------------- +.. _CurStates: + +Package States +^^^^^^^^^^^^^^^ +.. data:: CURSTATE_CONFIG_FILES +.. data:: CURSTATE_HALF_CONFIGURED +.. data:: CURSTATE_HALF_INSTALLED +.. data:: CURSTATE_INSTALLED +.. data:: CURSTATE_NOT_INSTALLED +.. data:: CURSTATE_UNPACKED + + + + +Dependency types +^^^^^^^^^^^^^^^^ +.. data:: DEP_CONFLICTS +.. data:: DEP_DEPENDS +.. data:: DEP_OBSOLETES +.. data:: DEP_PRE_DEPENDS +.. data:: DEP_RECOMMENDS +.. data:: DEP_REPLACES +.. data:: DEP_SUGGESTS + +.. _InstStates: + +Installed states +^^^^^^^^^^^^^^^^ +.. data:: INSTSTATE_HOLD +.. data:: INSTSTATE_HOLD_REINSTREQ +.. data:: INSTSTATE_OK +.. data:: INSTSTATE_REINSTREQ + +.. _Priorities: + +Priorities +^^^^^^^^^^^ +.. data:: PRI_EXTRA +.. data:: PRI_IMPORTANT +.. data:: PRI_OPTIONAL +.. data:: PRI_REQUIRED +.. data:: PRI_STANDARD + + +.. _SelStates: + +Select states +^^^^^^^^^^^^^ +.. data:: SELSTATE_DE_INSTALL +.. data:: SELSTATE_HOLD +.. data:: SELSTATE_INSTALL +.. data:: SELSTATE_PURGE +.. data:: SELSTATE_UNKNOWN + + +Build information +^^^^^^^^^^^^^^^^^ +.. data:: DATE + + The date on which this extension has been compiled. + +.. data:: LIB_VERSION + + The version of the apt_pkg library. This is **not** the version of apt, + nor the version of python-apt. + +.. data:: TIME + + The time this extension has been built. + +.. data:: VERSION + + The version of apt (not of python-apt). + +.. data:: _COMPAT_0_7 + + A more or less internal variable defining whether this build provides an + API which is compatible to the one of python-apt 0.7. This is used in the + apt and aptsources packages to decide whether compatibility should be + enabled or not. diff --git a/doc/source/library/aptsources.distinfo.rst b/doc/source/library/aptsources.distinfo.rst new file mode 100644 index 00000000..033ef483 --- /dev/null +++ b/doc/source/library/aptsources.distinfo.rst @@ -0,0 +1,11 @@ +:mod:`aptsources.distinfo` --- provide meta information for distro repositories +=============================================================================== +.. note:: + + This part of the documentation is created automatically. + + +.. automodule:: aptsources.distinfo + :members: + :undoc-members: + diff --git a/doc/source/library/aptsources.distro.rst b/doc/source/library/aptsources.distro.rst new file mode 100644 index 00000000..6ebe438c --- /dev/null +++ b/doc/source/library/aptsources.distro.rst @@ -0,0 +1,11 @@ +:mod:`aptsources.distro` --- Distribution abstraction of the sources.list +=============================================================================== +.. note:: + + This part of the documentation is created automatically. + + +.. automodule:: aptsources.distro + :members: + :undoc-members: + diff --git a/doc/source/library/aptsources.sourceslist.rst b/doc/source/library/aptsources.sourceslist.rst new file mode 100644 index 00000000..79b8dd01 --- /dev/null +++ b/doc/source/library/aptsources.sourceslist.rst @@ -0,0 +1,11 @@ +:mod:`aptsources.sourceslist` --- Provide an abstraction of the sources.list +============================================================================ +.. note:: + + This part of the documentation is created automatically. + + +.. automodule:: aptsources.sourceslist + :members: + :undoc-members: + diff --git a/doc/source/library/index.rst b/doc/source/library/index.rst new file mode 100644 index 00000000..dfbd8eec --- /dev/null +++ b/doc/source/library/index.rst @@ -0,0 +1,36 @@ +Python APT Library +================== +Python APT's library provides access to almost every functionality supported +by the underlying apt-pkg and apt-inst libraries. This means that it is +possible to rewrite frontend programs like apt-cdrom in Python, and this is +relatively easy, as can be seen in e.g. :doc:`../tutorials/apt-cdrom`. + +When going through the library, the first two modules are :mod:`apt_pkg` and +:mod:`apt_inst`. These modules are more or less straight bindings to the +apt-pkg and apt-inst libraries and the base for the rest of python-apt. + +Going forward, the :mod:`apt` package appears. This package is using +:mod:`apt_pkg` and :mod`apt_inst` to provide easy to use ways to manipulate +the cache, fetch packages, or install new packages. It also provides useful +progress classes, for text and GTK+ interfaces. The last package is +:mod:`aptsources`. The aptsources package provides classes and functions to +read files like :file:`/etc/apt/sources.list` and to modify them. + +.. toctree:: + :maxdepth: 1 + + apt_pkg + apt_inst + + apt.cache + apt.cdrom + apt.debfile + apt.package + apt.progress.text + apt.progress.gtk2 + apt.progress.qt4 + + aptsources.distinfo + aptsources.distro + aptsources.sourceslist + diff --git a/doc/source/templates/indexcontent.html b/doc/source/templates/indexcontent.html new file mode 100644 index 00000000..e5f11cc1 --- /dev/null +++ b/doc/source/templates/indexcontent.html @@ -0,0 +1,50 @@ +{% extends "defindex.html" %} +{% block body %} +

{{ docstitle|e }}

+

+ Welcome! This is + {% block description %}the documentation for {{ project|e }} + {{ release|e }}{% if last_updated %}, last updated {{ last_updated|e }}{% endif %}{% endblock %}. +

+ +

+ This documentation has been created using Sphinx and reStructuredText files + written by Julian Andres Klode <jak@debian.org>. +

+ + + + +

Parts of the documentation:

+ + +
+

What's new in Python {{ version }}?
+ or all "What's new" documents

+

Library Reference
+ keep this under your pillow

+

Tutorials
+ examples and more...

+ 		+

Embedding
+ tutorial for C++ programmers

+

C++ API
+ reference for C++ programmers

+
+ +

Indices and tables:

+ + +
+

Global Module Index
+ quick access to all modules

+

General Index
+ all functions, classes, terms

+ 		+

Search page
+ search this documentation

+

Complete Table of Contents
+ lists all sections and subsections

+
+ +{% endblock %} diff --git a/doc/source/templates/layout.html b/doc/source/templates/layout.html new file mode 100644 index 00000000..60298719 --- /dev/null +++ b/doc/source/templates/layout.html @@ -0,0 +1,10 @@ +{% extends "!layout.html" %} +{% block rootrellink %} +
    • +
  • {{ shorttitle }}{{ reldelim1 }}
    • +{% endblock %} +{% block extrahead %} + +{{ super() }} +{% endblock %} diff --git a/doc/source/tutorials/apt-cdrom.rst b/doc/source/tutorials/apt-cdrom.rst new file mode 100644 index 00000000..c66d49f7 --- /dev/null +++ b/doc/source/tutorials/apt-cdrom.rst @@ -0,0 +1,156 @@ +Writing your own apt-cdrom +========================== +:Author: Julian Andres Klode +: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() + +Advcaned 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/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 +: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: + + * diff --git a/doc/source/whatsnew/0.8.0.rst b/doc/source/whatsnew/0.8.0.rst index 244da388..8a2b52e8 100644 --- a/doc/source/whatsnew/0.8.0.rst +++ b/doc/source/whatsnew/0.8.0.rst @@ -78,11 +78,13 @@ Yet another context manager is available for locking the package system:: with apt_pkg.SystemLock(): # do your stuff here + pass -There is also one for file based locking: +There is also one for file based locking:: with apt_pkg.FileLock(filename): # do your stuff here + pass Unification of dependency handling -- cgit v1.2.3