diff options
29 files changed, 1453 insertions, 52 deletions
diff --git a/debian/changelog b/debian/changelog index a80a9b64..1002bead 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,3 +1,29 @@ +python-apt (0.7.9~exp2) experimental; urgency=low + + * apt/*.py: + - Almost complete cleanup of the code + - Improved documentation + * apt/debfile.py: + - Drop get*() methods, as they are deprecated and were + never in a stable release + - Make DscSrcPackage working + * apt/gtk/widgets.py: + - Fix the code and document the signals + * Introduce new documentation build with Sphinx + - debian/rules: Build the documentation here + - setup.py: Remove pydoc building and add new docs. + - debian/examples: Include examples from documentation + - debian/python-apt.docs: Change html/ to doc/build/html. + * setup.py: + - Only create build/data when building, not all the time + - Remove build/mo and build/data on clean -a + * debian/control: + - Remove the Conflicts on python2.3-apt, python2.4-apt, as + they are only needed for oldstable (sarge) + - Build-Depend on python-sphinx (>= 0.5) + + -- Julian Andres Klode <jak@debian.org> Fri, 09 Jan 2009 17:20:41 +0100 + python-apt (0.7.9~exp1) experimental; urgency=low * Merged python-apt consolidation branch by Sebastian diff --git a/debian/control b/debian/control index b738231f..8a10091d 100644 --- a/debian/control +++ b/debian/control @@ -5,15 +5,13 @@ Maintainer: APT Development Team <deity@lists.debian.org> Uploaders: Matt Zimmerman <mdz@debian.org>, Michael Vogt <mvo@debian.org> Standards-Version: 3.7.2.2 XS-Python-Version: all -Build-Depends: debhelper (>= 5.0.37.1), libapt-pkg-dev (>= 0.7.10), apt-utils, python-all-dev, python-distutils-extra (>= 1.9.0), cdbs, python-central (>= 0.5), python-all-dbg +Build-Depends: debhelper (>= 5.0.37.1), libapt-pkg-dev (>= 0.7.10), apt-utils, python-all-dev, python-distutils-extra (>= 1.9.0), cdbs, python-central (>= 0.5), python-all-dbg, python-sphinx (>= 0.5) Vcs-Bzr: http://bzr.debian.org/apt/python-apt/debian-sid Package: python-apt Architecture: any Depends: ${python:Depends}, ${shlibs:Depends}, ${misc:Depends}, lsb-release Priority: optional -Replaces: python2.3-apt (<< 0.6.18), python2.4-apt (<< 0.6.18) -Conflicts: python2.3-apt (<< 0.6.18), python2.4-apt (<< 0.6.18) Provides: ${python:Provides} Suggests: python-apt-dbg, python-gtk2, python-vte XB-Python-Version: ${python:Versions} diff --git a/debian/examples b/debian/examples index 80a386c8..e4a93ea1 100644 --- a/debian/examples +++ b/debian/examples @@ -1 +1,2 @@ doc/examples/*.py +doc/source/examples/*.py diff --git a/debian/python-apt.docs b/debian/python-apt.docs index f3c87fdc..ff53abec 100644 --- a/debian/python-apt.docs +++ b/debian/python-apt.docs @@ -1,4 +1,4 @@ README apt/README.apt data/templates/README.templates -html/ +doc/build/html/ diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 00000000..39fe377f --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,75 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source + +.PHONY: help clean html web pickle htmlhelp latex changes linkcheck + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " changes to make an overview over all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + +clean: + -rm -rf build/* + +html: + mkdir -p build/html build/doctrees + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html + @echo + @echo "Build finished. The HTML pages are in build/html." + +pickle: + mkdir -p build/pickle build/doctrees + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +web: pickle + +json: + mkdir -p build/json build/doctrees + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) build/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + mkdir -p build/htmlhelp build/doctrees + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in build/htmlhelp." + +latex: + mkdir -p build/latex build/doctrees + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex + @echo + @echo "Build finished; the LaTeX files are in build/latex." + @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ + "run these through (pdf)latex." + +changes: + mkdir -p build/changes build/doctrees + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes + @echo + @echo "The overview file is in build/changes." + +linkcheck: + mkdir -p build/linkcheck build/doctrees + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in build/linkcheck/output.txt." diff --git a/doc/makefile b/doc/makefile deleted file mode 100644 index 7f9dff2b..00000000 --- a/doc/makefile +++ /dev/null @@ -1,13 +0,0 @@ -# -*- make -*- -BASE=.. -SUBDIR=doc - -# Bring in the default rules -include ../buildlib/defaults.mak - -# Examples -SOURCE = examples/config.py examples/configisc.py examples/tagfile.py \ - examples/versiontest.py examples/checkstate.py \ - examples/recommends.py -TO = $(DOC) -include $(COPY_H) diff --git a/doc/source/apt/cache.rst b/doc/source/apt/cache.rst new file mode 100644 index 00000000..f3ba7d52 --- /dev/null +++ b/doc/source/apt/cache.rst @@ -0,0 +1,70 @@ +:mod:`apt.cache` --- The Cache class +===================================== +.. automodule:: apt.cache + +The Cache class +--------------- + +.. autoclass:: Cache + :members: + +Example +^^^^^^^ + +The following example shows how to load the cache, update it, and upgrade +all the packages on the system. + +.. code-block:: python + + 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: + +.. autoclass:: MarkedChangesFilter + :members: + +.. autoclass:: FilteredCache + :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.setFilter(MarkedChangesFilter()) + >>> print len(changed) == len(cache.GetChanges()) # Both need to have same length + True + + +Exceptions +---------- +.. autoexception:: FetchCancelledException + :members: +.. autoexception:: FetchFailedException +.. autoexception:: LockFailedException diff --git a/doc/source/apt/cdrom.rst b/doc/source/apt/cdrom.rst new file mode 100644 index 00000000..56381f14 --- /dev/null +++ b/doc/source/apt/cdrom.rst @@ -0,0 +1,7 @@ +: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 new file mode 100644 index 00000000..70c39087 --- /dev/null +++ b/doc/source/apt/debfile.rst @@ -0,0 +1,37 @@ +: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. + + All methods except for :meth:`open()` and the attribute :attr:`filelist` have been + introduced in version 0.7.9. + +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/gtk.widgets.rst b/doc/source/apt/gtk.widgets.rst new file mode 100644 index 00000000..9fa84ead --- /dev/null +++ b/doc/source/apt/gtk.widgets.rst @@ -0,0 +1,29 @@ +:mod:`apt.gtk.widgets` --- GTK widgets +====================================== +.. automodule:: apt.gtk.widgets + + +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/index.rst b/doc/source/apt/index.rst new file mode 100644 index 00000000..5047a0fd --- /dev/null +++ b/doc/source/apt/index.rst @@ -0,0 +1,58 @@ +: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 + :members: + + + + +.. 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 new file mode 100644 index 00000000..1bd032ab --- /dev/null +++ b/doc/source/apt/package.rst @@ -0,0 +1,101 @@ +:mod:`apt.package` --- Classes for package handling +==================================================== + + +.. automodule:: apt.package + + +The Package class +----------------- +.. autoclass:: Package + :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:: preDepend + + 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.candidateOrigin.trusted + + # Mark python-apt for install + pkg.markInstall() + + print 'python-apt is marked for install:', pkg.markedInstall + + print 'python-apt is', pkg.summary #Python interface to libapt-pkg + + # Now, really install it + cache.commit() diff --git a/doc/source/apt/progress.rst b/doc/source/apt/progress.rst new file mode 100644 index 00000000..8989aa27 --- /dev/null +++ b/doc/source/apt/progress.rst @@ -0,0 +1,37 @@ +: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 new file mode 100644 index 00000000..b405b9f4 --- /dev/null +++ b/doc/source/apt_inst.rst @@ -0,0 +1,100 @@ +: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 :class:`file` object ``file``. + + +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 file object + ``file``. + + An example would be: + + .. code-block:: python + + debExtract(open("package.deb"), my_callback, "data.tar.gz") + + See :ref:`emulating-dpkg-contents` for a more detailed example. + +.. function:: tarExtract(file,func,comp) + + Call the function ``func`` for each member of the tar file ``file``. + + ``Comp`` is a string determining the compressor used. Possible options are + "lzma", "bzip2" and "gzip". + + +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``. + + 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. + +.. function:: debExtractControl(file[, member='control']) + + Return the indicated file from the control tar. The default is 'control'. + + If you want to print the control file of a given package, you could do + something like: + + .. code-block:: python + + print debExtractControl(open("package.deb")) + + :return: The contents of the file, as :class:`str`. + + +.. _emulating-dpkg-extract: + +Example: Emulating :program:`dpkg` :option:`--extract` +------------------------------------------------------- +Here is a code snippet which emulates dpkg -x. It can be run as +``tool pkg.deb 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/cache.rst b/doc/source/apt_pkg/cache.rst new file mode 100644 index 00000000..abb0fab2 --- /dev/null +++ b/doc/source/apt_pkg/cache.rst @@ -0,0 +1,95 @@ +Low-Level Cache Handling +=========================== + +.. class:: Acquire + + .. method:: Run() + + Fetch all the items which have been added by + :func:`apt_pkg.GetPkgAcqFile`. + + .. method:: Shutdown + + Shut the fetcher down. + +.. class:: pkgCache + + The :class:`pkgCache` class prov + + .. 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 an object as returned by + :func:`apt_pkg.GetPkgSourceList`. + + .. method:: __getitem__(item) + + Return an :class:`pkgCachePackage` object for the package with the given + name. + +.. class:: pkgCachePackage + + The pkgCache::Package objects are an interface to package specific + features. + + + Attributes: + + .. attribute:: Name + + This is the name of the package. + + .. attribute:: Section + + The section of the package, as specified in the record. The list of + possible sections is defined in the Policy. + + .. attribute:: ID + + The ID of the package. This can be used to store information about + the package. The ID is an int value. + + +Working with dependencies +------------------------- +.. class:: pkgDepCache + + The pkgDepCache 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:: FixBroken() + + Try to fix all broken packages in the cache. + + .. method:: GetCandidateVer(pkg) + + Return the candidate version of the package, ie. the version that + would be installed normally. + + The parameter ``pkg`` refers to an :class:`pkgCachePackage` object, + available using the :class:`pkgCache`. + + This method returns a :class:`pkgCacheVersion` object. diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst new file mode 100644 index 00000000..5f23df31 --- /dev/null +++ b/doc/source/apt_pkg/index.rst @@ -0,0 +1,239 @@ +: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. + + +.. toctree:: + :maxdepth: 2 + :glob: + + * + + +Module Initialization +--------------------- + + +.. function:: initConfig + + Initialize the configuration of apt. This is needed for most operations. + +.. function:: initSystem + + Initialize the system. + +.. function:: init + + Deprecated function. Use initConfig() and initSystem() instead. + +Object initialization +---------------------- +.. function:: GetCache([progress]) + + Return a :class:`pkgCache` object. The optional parameter ``progress`` + specifies an instance of :class:`apt.progress.OpProgress()` which will + display the open progress. + +.. function:: GetCdrom() + + Return a Cdrom object with the following methods: + + .. method:: Cdrom.Ident(progress) + + Identify the cdrom. The parameter ``progress`` refers to an + :class:`apt.progress.CdromProgress()` object. + + .. method:: Cdrom.Add(progress) + + Add the cdrom to the sources.list file. The parameter ``progress`` + refers to an :class:`apt.progress.CdromProgress()` object. + + + +.. function:: GetDepCache(cache) + + Return a :class:`pkgDepCache` object. The parameter ``cache`` specifies an + instance of :class:`pkgCache` (see :func:`GetCache()`). + + +.. function:: GetPkgSourceList() + + Return a :class:`pkgSourceList` object. + + +The Acquire interface +---------------------- +.. function:: GetAcquire([progress]) + + Return an :class:`Acquire` object. This is a class which allows you + to fetch files, or archive contents. The parameter ``progress`` refers to + an :class:`apt.progress.FetchProgress()` object. + + Acquire items have multiple methods: + + .. method:: Acquire.Run() + + Fetch all the items which have been added by :func:`GetPkgAcqFile`. + + .. method:: Acquire.Shutdown() + + Shut the fetcher down. + +.. function:: GetPkgAcqFile(aquire, uri[, md5, size, descr, shortDescr, destDir, destFile]) + + The parameter ``acquire`` 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. ``shortDescr`` is the + short form of it. + + You can use ``destDir`` to manipulate the directory where the file will + be saved in. Together with ``destFile`` you can specify the complete target + path. + + + +Hash functions +-------------- +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. + +.. 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, in which case the md5sum of its contents is returned. + +.. 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, in which case the sha1sum of its contents is returned. + +.. 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, in which case the sha256sum of its contents is returned. + +Other functions +---------------- + +.. note:: + + This documentation is created automatically and should be rewritten. + +.. autofunction:: Base64Encode +.. autofunction:: CheckDep +.. autofunction:: CheckDomainList +.. autofunction:: DeQuoteString +.. autofunction:: GetLock +.. autofunction:: GetPackageManager +.. autofunction:: GetPkgActionGroup +.. autofunction:: GetPkgProblemResolver +.. autofunction:: GetPkgRecords +.. autofunction:: GetPkgSrcRecords +.. autofunction:: newConfiguration +.. autofunction:: ParseCommandLine +.. autofunction:: ParseDepends +.. autofunction:: ParseSection +.. autofunction:: ParseSrcDepends +.. autofunction:: ParseTagFile +.. autofunction:: PkgSystemLock +.. autofunction:: PkgSystemUnLock +.. autofunction:: QuoteString +.. autofunction:: ReadConfigFile +.. autofunction:: ReadConfigFileISC +.. autofunction:: RewriteSection +.. autofunction:: SizeToStr +.. autofunction:: StringToBool +.. autofunction:: StrToTime +.. autofunction:: TimeRFC1123 +.. autofunction:: TimeToStr +.. autofunction:: UpstreamVersion +.. autofunction:: URItoFileName +.. autofunction:: VersionCompare + + +Data +----- + +.. data:: Config + + An :class:`Configuration()` object with the default configuration. Actually, + this is a bit different object, but it is compatible. + +.. data:: RewritePackageOrder + +.. data:: RewriteSourceOrder + + +Package States +^^^^^^^^^^^^^^^ +.. data:: CurStateConfigFiles +.. data:: CurStateHalfConfigured +.. data:: CurStateHalfInstalled +.. data:: CurStateInstalled +.. data:: CurStateNotInstalled +.. data:: CurStateUnPacked + + + + +Dependency types +^^^^^^^^^^^^^^^^ +.. data:: DepConflicts +.. data:: DepDepends +.. data:: DepObsoletes +.. data:: DepPreDepends +.. data:: DepRecommends +.. data:: DepReplaces +.. data:: DepSuggests + +Installed states +^^^^^^^^^^^^^^^^^ +.. data:: InstStateHold +.. data:: InstStateHoldReInstReq +.. data:: InstStateOk +.. data:: InstStateReInstReq + + +Priorities +^^^^^^^^^^ +.. data:: PriExtra +.. data:: PriImportant +.. data:: PriOptional +.. data:: PriRequired +.. data:: PriStandard + +Dselect states +^^^^^^^^^^^^^^ +.. data:: SelStateDeInstall +.. data:: SelStateHold +.. data:: SelStateInstall +.. data:: SelStatePurge +.. data:: SelStateUnknown + + +Build information +^^^^^^^^^^^^^^^^^ +.. data:: Date +.. data:: LibVersion +.. data:: Time +.. data:: Version diff --git a/doc/source/aptsources/distinfo.rst b/doc/source/aptsources/distinfo.rst new file mode 100644 index 00000000..96f9445d --- /dev/null +++ b/doc/source/aptsources/distinfo.rst @@ -0,0 +1,10 @@ +: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 new file mode 100644 index 00000000..06ca0fda --- /dev/null +++ b/doc/source/aptsources/distro.rst @@ -0,0 +1,10 @@ +: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 new file mode 100644 index 00000000..898fbf74 --- /dev/null +++ b/doc/source/aptsources/index.rst @@ -0,0 +1,10 @@ +: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 new file mode 100644 index 00000000..509db3ce --- /dev/null +++ b/doc/source/aptsources/sourceslist.rst @@ -0,0 +1,10 @@ +: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/coding.rst b/doc/source/coding.rst new file mode 100644 index 00000000..0a57bd74 --- /dev/null +++ b/doc/source/coding.rst @@ -0,0 +1,149 @@ +Coding for 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 + +**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 + + +C++ Coding style +---------------- +When you work on the C++ code in the python/ directory, you should follow some +basic rules. + +The indentation of the code is a bit non-standard. We currently use 3 spaces +indentation for the C++ code. + +When you create new functions, you should follow some naming conventions. All +C++ functions are named according to the ``CamelCase`` convention. + +The resulting Python functions should be ``CamelCase`` as well in apt_pkg, or +``mixedCase`` in apt_inst. The same applies for variables, parameters, +attributes, etc. + +.. note:: + + This coding style guidelines are incomplete. If you have any questions + send an email to deity@lists.debian.org. + +.. note:: + + The coding style may be changed completely during the port to Python 3.0. + But this will not happen very soon. + + +Python Coding Style +------------------- +The coding style for the rest of the code is basically :PEP:`8`, with some exceptions: + +The naming convention is mixedCase for functions, methods, attributes, and +variables. This is considered bad and will be changed in future versions to +lowercase_with_underscores, as stated in :PEP:`8`. + +.. note:: + + You can use the tool pep8.py from http://svn.browsershots.org/trunk/devtools/pep8/ + to validate your code. Please also run pylint, pychecker, and pyflakes and + fix all new errors they report (unresolved names, etc.). + + +Submitting your patch +--------------------- +First of all, the patch you create should be based against the debian-sid +branch of python-apt. + +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). + + +Documentation updates +--------------------- +If you want to update the documentation, please follow the procedure as written +above. But please CC: jak@debian.org in the bug report. + +You can send your content in plain text, but reStructuredText is the preferred +format. I (Julian Andres Klode) will review your patch and will forward them to +Michael Vogt, for inclusion in his branch. On release, this will be merged into +the debian-sid branch. + + +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 diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 00000000..4cd444f1 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,192 @@ +# -*- coding: utf-8 -*- +# +# python-apt documentation build configuration file, created by +# sphinx-quickstart on Wed Jan 7 17:04:36 2009. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# The contents of this file are pickled, so don't put values in the namespace +# that aren't pickleable (module imports are okay, they're removed automatically). +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If your extensions are in another directory, add it here. If the directory +# is relative to the documentation root, use os.path.abspath to make it +# absolute, like shown here. +sys.path.insert(0,os.path.abspath('..')) +sys.path.insert(0,os.path.abspath('../..')) + +# General configuration +# --------------------- + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx'] +intersphinx_mapping = {'http://docs.python.org/': None} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'python-apt' +copyright = u'2009, Julian Andres Klode <jak@debian.org>' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.7' +# The full version, including alpha/beta/rc tags. +release = '0.7.9~exp2' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of documents that shouldn't be included in the build. +#unused_docs = [] + +# List of directories, relative to source directory, that shouldn't be searched +# for source files. +exclude_trees = [] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# Options for HTML output +# ----------------------- + +# The style sheet to use for HTML and HTML Help pages. A file of that name +# must exist either in Sphinx' static/ path, or in one of the custom paths +# given in html_static_path. +html_style = 'default.css' + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['.static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_use_modindex = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, the reST sources are included in the HTML build as _sources/<name>. +#html_copy_source = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = '' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'python-aptdoc' + + +# Options for LaTeX output +# ------------------------ + +# The paper size ('letter' or 'a4'). +#latex_paper_size = 'letter' + +# The font size ('10pt', '11pt' or '12pt'). +#latex_font_size = '10pt' + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, document class [howto/manual]). +latex_documents = [ + ('index', 'python-apt.tex', ur'python-apt Documentation', + ur'Julian Andres Klode <jak@debian.org>', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# Additional stuff for the LaTeX preamble. +#latex_preamble = '' + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_use_modindex = True diff --git a/doc/source/examples/apt-gtk.py b/doc/source/examples/apt-gtk.py new file mode 100644 index 00000000..c3bb09d5 --- /dev/null +++ b/doc/source/examples/apt-gtk.py @@ -0,0 +1,29 @@ +#!/usr/bin/python +"""Example for gtk widgets""" +import pygtk +pygtk.require("2.0") +import gtk + +import apt.gtk.widgets + + +def main(): + """Main function.""" + win = gtk.Window() + win.connect("destroy", gtk.main_quit) + progress = apt.gtk.widgets.GtkAptProgress() + win.set_title("GtkAptProgress Demo") + win.add(progress) + progress.show() + win.show() + cache = apt.cache.Cache(progress.open) + if cache["xterm"].isInstalled: + cache["xterm"].markDelete() + else: + cache["xterm"].markInstall() + progress.show_terminal(expanded=True) + cache.commit(progress.fetch, progress.install) + gtk.main() + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/dpkg-contents.py b/doc/source/examples/dpkg-contents.py new file mode 100644 index 00000000..99d1596f --- /dev/null +++ b/doc/source/examples/dpkg-contents.py @@ -0,0 +1,55 @@ +#!/usr/bin/python +"""Emulate dpkg --contents""" + +import grp +import pwd +import stat +import sys +import time + +import apt_inst + + +def format_mode(what, mode): + """Return the symbolic mode""" + s_mode = dict(DIR="d", HARDLINK="h", FILE="-").get(what) + s_mode += ((mode & stat.S_IRUSR) and "r" or "-") + s_mode += ((mode & stat.S_IWUSR) and "w" or "-") + s_mode += ((mode & stat.S_IXUSR) and (mode & stat.S_ISUID and "s" or "x") + or (mode & stat.S_ISUID and "S" or "-")) + s_mode += ((mode & stat.S_IRGRP) and "r" or "-") + s_mode += ((mode & stat.S_IWGRP) and "w" or "-") + s_mode += ((mode & stat.S_IXGRP) and (mode & stat.S_ISGID and "s" or "x") + or (mode & stat.S_ISGID and "S" or "-")) + s_mode += ((mode & stat.S_IROTH) and "r" or "-") + s_mode += ((mode & stat.S_IWOTH) and "w" or "-") + s_mode += ((mode & stat.S_IXOTH) and "x" or "-") + return s_mode + + +def callback(what, name, link, mode, uid, gid, size, mtime, major, minor): + """callback for debExtract""" + s_mode = format_mode(what, mode) + s_owner = "%s/%s" % (pwd.getpwuid(uid)[0], grp.getgrgid(gid)[0]) + s_size = "%9d" % size + s_time = time.strftime("%Y-%m-%d %H:%M", time.localtime(mtime)) + s_name = name.startswith(".") and name or ("./" + name) + if link: + s_name += " link to %s" % link + print s_mode, s_owner, s_size, s_time, s_name + + +def main(): + """Main function""" + if len(sys.argv) < 2: + print >> sys.stderr, "need filename argumnet" + sys.exit(1) + + fobj = open(sys.argv[1]) + try: + apt_inst.debExtract(fobj, callback, "data.tar.gz") + finally: + fobj.close() + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/dpkg-extract.py b/doc/source/examples/dpkg-extract.py new file mode 100644 index 00000000..ced8652f --- /dev/null +++ b/doc/source/examples/dpkg-extract.py @@ -0,0 +1,25 @@ +#!/usr/bin/python +"""Emulate dpkg --extract package.deb outdir""" +import os +import sys + +import apt_inst + + +def main(): + """Main function.""" + if len(sys.argv) < 3: + print >> sys.stderr, "Usage:", __file__, "package.deb outdir" + sys.exit(1) + if not os.path.exists(sys.argv[2]): + print >> sys.stderr, "The directory %s does not exist" % sys.argv[2] + sys.exit(1) + + fobj = open(sys.argv[1]) + try: + apt_inst.debExtractArchive(fobj, sys.argv[2]) + finally: + fobj.close() + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/dpkg-info.py b/doc/source/examples/dpkg-info.py new file mode 100644 index 00000000..ff98d8b1 --- /dev/null +++ b/doc/source/examples/dpkg-info.py @@ -0,0 +1,20 @@ +#!/usr/bin/python +"""Emulate dpkg --info package.deb control-file""" +import sys + +from apt_inst import debExtractControl + + +def main(): + """Main function.""" + if len(sys.argv) < 3: + print >> sys.stderr, 'Usage: tool file.deb control-file' + sys.exit(0) + fobj = open(sys.argv[1]) + try: + print debExtractControl(fobj, sys.argv[2]) + finally: + fobj.close() + +if __name__ == '__main__': + main() diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 00000000..d7c425bd --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,38 @@ +Welcome to python-apt's documentation! +====================================== + +.. note:: + + This documentation can not be considered complete at the moment. But it + provides better documentation than the documentation available through + pydoc. + +.. note:: + + + This documentation has been created by Sphinx, using reStructuredText files + written by Julian Andres Klode <jak@debian.org>, and in case of the apt + package, from the documentation shipped in the modules. + + +Contents: + +.. toctree:: + :maxdepth: 2 + + apt/index + apt_pkg/index + apt_inst + aptsources/index + coding + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + + diff --git a/po/python-apt.pot b/po/python-apt.pot index 7a1002fb..6ffef103 100644 --- a/po/python-apt.pot +++ b/po/python-apt.pot @@ -8,7 +8,7 @@ msgid "" msgstr "" "Project-Id-Version: PACKAGE VERSION\n" "Report-Msgid-Bugs-To: \n" -"POT-Creation-Date: 2008-11-24 14:45+0100\n" +"POT-Creation-Date: 2009-01-09 17:23+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <LL@li.org>\n" @@ -336,25 +336,25 @@ msgstr "" msgid "Custom servers" msgstr "" -#: ../apt/gtk/widgets.py:173 +#: ../apt/gtk/widgets.py:243 #, python-format msgid "Downloading file %(current)li of %(total)li with %(speed)s/s" msgstr "" -#: ../apt/gtk/widgets.py:179 +#: ../apt/gtk/widgets.py:249 #, python-format msgid "Downloading file %(current)li of %(total)li" msgstr "" #. Setup some child widgets -#: ../apt/gtk/widgets.py:220 +#: ../apt/gtk/widgets.py:269 msgid "Details" msgstr "" -#: ../apt/gtk/widgets.py:310 +#: ../apt/gtk/widgets.py:351 msgid "Starting..." msgstr "" -#: ../apt/gtk/widgets.py:313 +#: ../apt/gtk/widgets.py:357 msgid "Complete" msgstr "" @@ -10,24 +10,9 @@ import os.path import pydoc import shutil import string +import subprocess import sys -def build_docs(dir="html", modules=["apt","aptsources"]): - htmldir = os.path.join(os.getcwd(), dir) - for d in modules: - for (dirpath, dirnames, filenames) in os.walk(d): - pydoc.writedoc(dirpath.replace("/",".")) - for file in filenames: - if not file.endswith(".py"): - continue - if file in ["__init__.py"]: - continue - pydoc.writedoc(dirpath.replace("/",".")+"."+file.split(".py")[0]) - if not os.path.exists(htmldir): - os.mkdir(htmldir) - for f in glob.glob("*.html"): - shutil.move(f, htmldir) - return True # The apt_pkg module files = map(lambda source: "python/"+source, @@ -41,23 +26,31 @@ apt_inst = Extension("apt_inst", files, libraries=["apt-pkg","apt-inst"]); # Replace the leading _ that is used in the templates for translation templates = [] -if not os.path.exists("build/data/templates/"): - os.makedirs("build/data/templates") -for template in glob.glob('data/templates/*.info.in'): - source = open(template, "r") - build = open(os.path.join("build", template[:-3]), "w") - lines = source.readlines() - for line in lines: - build.write(line.lstrip("_")) - source.close() - build.close() # build doc -if sys.argv[1] == "build": - build_docs() +if len(sys.argv) > 1 and sys.argv[1] == "build": + if not os.path.exists("build/data/templates/"): + os.makedirs("build/data/templates") + for template in glob.glob('data/templates/*.info.in'): + source = open(template, "r") + build = open(os.path.join("build", template[:-3]), "w") + lines = source.readlines() + for line in lines: + build.write(line.lstrip("_")) + source.close() + build.close() + if subprocess.call(["make", "-C", "doc", "html"]) : + raise SystemError +if len(sys.argv) > 1 and sys.argv[1] == "clean" and '-a' in sys.argv: + for dirname in "doc/build", "build/data", "build/mo": + if os.path.exists(dirname): + print "Removing", dirname + shutil.rmtree(dirname) + else: + print "Not removing", dirname, "because it does not exist" setup(name="python-apt", - version="0.6.17", + version="0.7.9", description="Python bindings for APT", author="APT Development Team", author_email="deity@lists.debian.org", |