From 6a806f0570599e8f5e9438c9623d496df75571d4 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Fri, 9 Jan 2009 21:52:07 +0100 Subject: * Introduce the new documentation and add 0.7.9~exp2 to changelog. The new documentation is built using sphinx (>= 0.5) [other versions may work too, but let's be safe]. --- doc/source/apt/cache.rst | 70 ++++++++++ doc/source/apt/cdrom.rst | 7 + doc/source/apt/debfile.rst | 37 ++++++ doc/source/apt/gtk.widgets.rst | 29 +++++ doc/source/apt/index.rst | 58 +++++++++ doc/source/apt/package.rst | 101 ++++++++++++++ doc/source/apt/progress.rst | 37 ++++++ doc/source/apt_inst.rst | 100 ++++++++++++++ doc/source/apt_pkg/cache.rst | 95 ++++++++++++++ doc/source/apt_pkg/index.rst | 239 ++++++++++++++++++++++++++++++++++ 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/coding.rst | 149 +++++++++++++++++++++ doc/source/conf.py | 192 +++++++++++++++++++++++++++ doc/source/examples/apt-gtk.py | 29 +++++ doc/source/examples/dpkg-contents.py | 55 ++++++++ doc/source/examples/dpkg-extract.py | 25 ++++ doc/source/examples/dpkg-info.py | 20 +++ doc/source/index.rst | 38 ++++++ 21 files changed, 1321 insertions(+) create mode 100644 doc/source/apt/cache.rst create mode 100644 doc/source/apt/cdrom.rst create mode 100644 doc/source/apt/debfile.rst create mode 100644 doc/source/apt/gtk.widgets.rst create mode 100644 doc/source/apt/index.rst create mode 100644 doc/source/apt/package.rst create mode 100644 doc/source/apt/progress.rst create mode 100644 doc/source/apt_inst.rst create mode 100644 doc/source/apt_pkg/cache.rst create mode 100644 doc/source/apt_pkg/index.rst create mode 100644 doc/source/aptsources/distinfo.rst create mode 100644 doc/source/aptsources/distro.rst create mode 100644 doc/source/aptsources/index.rst create mode 100644 doc/source/aptsources/sourceslist.rst create mode 100644 doc/source/coding.rst create mode 100644 doc/source/conf.py create mode 100644 doc/source/examples/apt-gtk.py create mode 100644 doc/source/examples/dpkg-contents.py create mode 100644 doc/source/examples/dpkg-extract.py create mode 100644 doc/source/examples/dpkg-info.py create mode 100644 doc/source/index.rst (limited to 'doc/source') 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 ' + +# 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 +# " v 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/. +#html_copy_source = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a 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 ', '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 , 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` + + -- cgit v1.2.3 From 21ba650e32457ee67ac0f85b03c071969aa5934b Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Fri, 9 Jan 2009 21:52:32 +0100 Subject: * setup.py, doc/source/conf.py: Fix building by adding build/lib* to PYTHONPATH We now build the extension first, and then the documentation. Also add the text docs. --- debian/changelog | 6 ++++-- debian/python-apt.docs | 3 ++- debian/rules | 1 + doc/Makefile | 4 ++++ doc/source/conf.py | 7 +++++-- po/python-apt.pot | 2 +- setup.py | 14 ++++++++++---- 7 files changed, 27 insertions(+), 10 deletions(-) (limited to 'doc/source') diff --git a/debian/changelog b/debian/changelog index 1002bead..7d37e7be 100644 --- a/debian/changelog +++ b/debian/changelog @@ -13,7 +13,9 @@ python-apt (0.7.9~exp2) experimental; urgency=low - 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. + - debian/python-apt.docs: + + Change html/ to build/doc/html. + + Add build/doc/text for the text-only documentation * setup.py: - Only create build/data when building, not all the time - Remove build/mo and build/data on clean -a @@ -22,7 +24,7 @@ python-apt (0.7.9~exp2) experimental; urgency=low they are only needed for oldstable (sarge) - Build-Depend on python-sphinx (>= 0.5) - -- Julian Andres Klode Fri, 09 Jan 2009 17:20:41 +0100 + -- Julian Andres Klode Fri, 09 Jan 2009 18:11:30 +0100 python-apt (0.7.9~exp1) experimental; urgency=low diff --git a/debian/python-apt.docs b/debian/python-apt.docs index ff53abec..6ba083f5 100644 --- a/debian/python-apt.docs +++ b/debian/python-apt.docs @@ -1,4 +1,5 @@ README apt/README.apt data/templates/README.templates -doc/build/html/ +build/doc/html/ +build/doc/text/ diff --git a/debian/rules b/debian/rules index adaad2a8..90b48cda 100755 --- a/debian/rules +++ b/debian/rules @@ -13,6 +13,7 @@ include /usr/share/cdbs/1/class/python-distutils.mk PKG=python-apt DEBVER=$(shell dpkg-parsechangelog |sed -n -e '/^Version:/s/^Version: //p') +DEB_COMPRESS_EXCLUDE:=.html .js _static/* _sources/* _sources/*/* .inv DEB_BUILD_PROG:=debuild --preserve-envvar PATH --preserve-envvar CCACHE_DIR -us -uc $(DEB_BUILD_PROG_OPTS) build/python-apt-dbg:: diff --git a/doc/Makefile b/doc/Makefile index 39fe377f..327bba91 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -26,6 +26,10 @@ help: clean: -rm -rf build/* +text: + mkdir -p build/text build/doctrees + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) build/text + html: mkdir -p build/html build/doctrees $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html diff --git a/doc/source/conf.py b/doc/source/conf.py index 4cd444f1..907e2275 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -19,8 +19,11 @@ 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('../..')) +sys.path.insert(0, os.path.abspath('..')) +sys.path.insert(0, os.path.abspath('../..')) +if os.path.exists("../../build"): + for dirname in os.listdir('../../build'): + sys.path.insert(0, os.path.abspath('../../build/' + dirname)) # General configuration # --------------------- diff --git a/po/python-apt.pot b/po/python-apt.pot index 6ffef103..6af898db 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: 2009-01-09 17:23+0100\n" +"POT-Creation-Date: 2009-01-09 18:08+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" diff --git a/setup.py b/setup.py index 1ff7cb16..016db85a 100755 --- a/setup.py +++ b/setup.py @@ -10,7 +10,6 @@ import os.path import pydoc import shutil import string -import subprocess import sys @@ -39,10 +38,10 @@ if len(sys.argv) > 1 and sys.argv[1] == "build": 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": + for dirname in "build/doc", "doc/build", "build/data", "build/mo": if os.path.exists(dirname): print "Removing", dirname shutil.rmtree(dirname) @@ -65,3 +64,10 @@ setup(name="python-apt", license = 'GNU GPL', platforms = 'posix' ) + +if len(sys.argv) > 1 and sys.argv[1] == "build": + import sphinx + sphinx.main(["sphinx", "-b", "html", "-d", "build/doc/doctrees", + os.path.abspath("doc/source"), "build/doc/html"]) + sphinx.main(["sphinx", "-b", "text", "-d", "build/doc/doctrees", + os.path.abspath("doc/source"), "build/doc/text"]) -- cgit v1.2.3 From b2d15c42700f0c67af2c9364a29c72562f74ff2b Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Fri, 9 Jan 2009 21:52:54 +0100 Subject: * doc/source/coding.rst: Add the jak branch --- doc/source/coding.rst | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc/source') diff --git a/doc/source/coding.rst b/doc/source/coding.rst index 0a57bd74..61c037ec 100644 --- a/doc/source/coding.rst +++ b/doc/source/coding.rst @@ -27,6 +27,13 @@ submit them. happens. VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-sid/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 -- cgit v1.2.3 From 513093cd51f95a8d014cd5436d3fff8556e10ced Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sat, 10 Jan 2009 18:14:11 +0100 Subject: * doc/: Heavily improve documentation Complete the documentation of pkgCache, pkgDepCache, pkgCache::Package. Introduce new documentation for pkgCache::Version, pkgCache::Dependency, pkgCache::PackageFile, pkgcache::Description. There is also an example now which checks for missing dependencies. --- doc/source/apt/debfile.rst | 6 +- doc/source/apt_pkg/cache.rst | 532 +++++++++++++++++++++++++++++++++- doc/source/apt_pkg/index.rst | 24 +- doc/source/conf.py | 5 +- doc/source/examples/cache-packages.py | 22 ++ doc/source/examples/cache-pkgfile.py | 29 ++ doc/source/examples/missing-deps.py | 51 ++++ 7 files changed, 655 insertions(+), 14 deletions(-) create mode 100644 doc/source/examples/cache-packages.py create mode 100644 doc/source/examples/cache-pkgfile.py create mode 100644 doc/source/examples/missing-deps.py (limited to 'doc/source') diff --git a/doc/source/apt/debfile.rst b/doc/source/apt/debfile.rst index 70c39087..c0146df9 100644 --- a/doc/source/apt/debfile.rst +++ b/doc/source/apt/debfile.rst @@ -21,8 +21,10 @@ Binary packages 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. + .. versionchanged:: 0.7.9 + Introduce all new methods (everything except for :meth:`open()` and + :attr:`filelist`) + Source packages ---------------- diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index abb0fab2..81ee2a8e 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -1,5 +1,10 @@ -Low-Level Cache Handling -=========================== +Classes in apt_pkg +================== + +.. todo:: + + This should be split and cleaned up a bit. + .. class:: Acquire @@ -12,6 +17,9 @@ Low-Level Cache Handling Shut the fetcher down. + +The cache +--------- .. class:: pkgCache The :class:`pkgCache` class prov @@ -37,10 +45,121 @@ Low-Level Cache Handling .. method:: __getitem__(item) - Return an :class:`pkgCachePackage` object for the package with the given + Return an :class:`Package` object for the package with the given name. -.. class:: pkgCachePackage + .. attribute:: DependsCount + + The total number of dependencies. + + .. attribute:: PackageCount + + The total number of packages available in the cache. + + .. attribute:: ProvidesCount + + The number of provided packages. + + .. attribute:: VerFileCount + + .. todo:: Seems to be some mixture of versions and pkgFile. + + .. attribute:: VersionCount + + The total number of package versions available in the cache. + + .. attribute:: PackageFileCount + + 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:`FileList`. + + .. attribute:: FileList + + A list of :class:`PackageFile` objects. + + +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:: IndexType + + 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:: NotAutomatic + + Whether packages from this list will be updated automatically. The + default for eg. example is 0 (aka false). + + .. attribute:: NotSource + + 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: + + .. code-block:: python + + for pkgfile in cache.FileList: + if pkgfile.NotSource: + 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 + + +A Package +--------- + +.. class:: Package The pkgCache::Package objects are an interface to package specific features. @@ -48,23 +167,285 @@ Low-Level Cache Handling Attributes: + .. attribute:: CurrentVer + + 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:: ProvidesList + + 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.ProvidesList and not pkg.VersionList`` helps you. It detects if + the package is provided by something else and is not available as a + real package. + + .. attribute:: RevDependsList + + 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:: VersionList + + A list of :class:`Version` objects for all versions available in the + cache. + + **States**: + + .. attribute:: SelectedState + + The state we want it to be, ie. if you mark a package for installation, + this is :attr:`apt_pkg.SelStateInstall`. + + See :ref:`SelStates` for a list of available states. + + .. attribute:: InstState + + The state the currently installed version is in. This is normally + :attr:`apt_pkg.InstStateOK`, unless the installation failed. + + See :ref:`InstStates` for a list of available states. + + .. attribute:: CurState + + 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 + + + +Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` +--------------------------------------------------------------- +.. class:: Version + + The version object contains all information related to a specific package + version. + + .. attribute:: VerStr + + 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:: FileList + + A list of (:class:`PackageFile`, int: index) tuples for all Package + files containing this version of the package. + + .. attribute:: DependsListStr + + 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: + + .. code-block:: python + + {'Depends': [ + [ + ('python', '2.4', '>=') + ] + ] + } + + The same for a dependency on A (>= 1) | B (>= 2): + + .. code-block:: python + + {'Depends': [ + [ + ('A', '1', '>='), + ('B', '2', '>='), + ] + ] + } + + .. attribute:: DependsList + + 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:: ParentPkg + + The :class:`Package` object this version belongs to. + + .. attribute:: ProvidesList + + This returns a list of all packages provided by this version. Like + :attr:`Package.ProvidesList`, 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:: InstalledSize + + The size of the package (in kilobytes), when unpacked on the disk. + + .. attribute:: Hash + + An integer hash value. + .. attribute:: ID - The ID of the package. This can be used to store information about - the package. The ID is an int value. + 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.PriorityStr`. + + The values are defined in the :mod:`apt_pkg` extension, see + :ref:`Priorities` for more information. + + .. attribute:: PriorityStr + + 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:: TranslatedDescription + + Return a :class:`Description` object. + + +The Dependency class +-------------------- +.. class:: Dependency + + Represent a dependency from one package to another one. + + .. method:: AllTargets + + 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:: SmartTargetPkg + + Return a :class:`Version` object of a package which satisfies the + dependency and does not conflict with installed packages + (the 'natural target'). + + .. attribute:: TargetVer + + The target version of the dependency, as string. Empty string if the + dependency is not versioned. + .. attribute:: TargetPkg -Working with dependencies -------------------------- + The :class:`Package` object of the target package. + + .. attribute:: ParentVer + + The :class:`Version` object of the parent version, ie. the package + which declares the dependency. + + .. attribute:: ParentPkg + + The :class:`Package` object of the package which declares the + dependency. This is the same as using ParentVer.ParentPkg. + + .. attribute:: CompType + + The type of comparison (>=, ==, >>, <=), as string. + + .. attribute:: DepType + + 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 + + +The Description class +--------------------- +.. class:: Description + + Represent the description of the package. + + .. attribute:: LanguageCode + + The language code of the description + + .. attribute:: md5 + + The md5 hashsum of the description + + .. attribute:: FileList + + A list of tuples (:class:`PackageFile`, int: index). + + + +The pkgDepCache wrapper +----------------------- .. class:: pkgDepCache The pkgDepCache object contains various methods to manipulate the cache, @@ -89,7 +470,138 @@ Working with dependencies Return the candidate version of the package, ie. the version that would be installed normally. - The parameter ``pkg`` refers to an :class:`pkgCachePackage` object, + The parameter ``pkg`` refers to an :class:`Package` object, available using the :class:`pkgCache`. - This method returns a :class:`pkgCacheVersion` object. + This method returns a :class:`Version` object. + + .. method:: SetCandidateVer(pkg, version) + + The opposite of :meth:`pkgDepCache.GetCandidateVer`. Set the candidate + version of the :class:`Package` ``pkg`` to the :class:`Version` + ``version``. + + + .. method:: Upgrade([distUpgrade=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 ``distUpgrade`` has + to be set to True. + + .. method:: FixBroken() + + Fix broken packages. + + .. method:: ReadPinFile() + + Read the policy, eg. /etc/apt/preferences. + + .. method:: MinimizeUpgrade() + + 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:: MarkKeep(pkg) + + Mark the :class:`Package` ``pkg`` for keep. + + .. method:: MarkDelete(pkg[, purge]) + + Mark the :class:`Package` ``pkg`` for delete. If ``purge`` is True, + the configuration files will be removed as well. + + .. method:: MarkInstall(pkg[, autoInst=True[, fromUser=True]]) + + Mark the :class:`Package` ``pkg`` for install. + + If ``autoInst`` is True, the dependencies of the package will be + installed as well. This is the default. + + If ``fromUser`` is True, the package will be marked as manually + installed. This is the default. + + .. method:: SetReinstall(pkg) + + Set if the :class:`Package` ``pkg`` should be reinstalled. + + .. method:: IsUpgradable(pkg) + + Return `1` if the package is upgradable. + + The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. + + .. method:: IsNowBroken(pkg) + + Return `1` if the package is broken now (including changes made, but + not committed). + + .. method:: IsInstBroken(pkg) + + Return `1` if the package is broken on the current install. This takes + changes which have not been committed not into effect. + + .. method:: IsGarbage(pkg) + + Return `1` if the package is garbage, ie. if it is automatically + installed and no longer referenced by other packages. + + .. method:: IsAutoInstalled(pkg) + + Return `1` if the package is automatically installed (eg. as the + dependency of another package). + + .. method:: MarkedInstall(pkg) + + Return `1` if the package is marked for install. + + .. method:: MarkedUpgrade(pkg) + + Return `1` if the package is marked for upgrade. + + .. method:: MarkedDelete(pkg) + + Return `1` if the package is marked for delete. + + .. method:: MarkedKeep(pkg) + + Return `1` if the package is marked for keep. + + .. method:: MarkedReinstall(pkg) + + Return `1` if the package should be installed. + + .. method:: MarkedDowngrade(pkg) + + Return `1` if the package should be downgraded. + + .. attribute:: KeepCount + + Integer, number of packages marked as keep + + .. attribute:: InstCount + + Integer, number of packages marked for installation. + + .. attribute:: DelCount + + Number of packages which should be removed. + + .. attribute:: BrokenCount + + Number of packages which are broken. + + .. attribute:: UsrSize + + The size required for the changes on the filesystem. If you install + packages, this is positive, if you remove them its negative. + + .. attribute:: DebSize + + The size of the packages which are needed for the changes to be + applied. diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst index 5f23df31..1c5866a9 100644 --- a/doc/source/apt_pkg/index.rst +++ b/doc/source/apt_pkg/index.rst @@ -83,6 +83,20 @@ The Acquire interface Shut the fetcher down. + .. attribute:: Acquire.TotalNeeded + + The total amount of bytes needed (including those of files which are + already present) + + .. attribute:: Acquire.FetchNeeded + + The total amount of bytes which need to be fetched. + + .. attribute:: Acquire.PartialPresent + + Whether some files have been acquired already. (???) + + .. function:: GetPkgAcqFile(aquire, uri[, md5, size, descr, shortDescr, destDir, destFile]) The parameter ``acquire`` refers to an :class:`Acquire()` object as returned @@ -184,6 +198,8 @@ Data .. data:: RewriteSourceOrder +.. _CurStates: + Package States ^^^^^^^^^^^^^^^ .. data:: CurStateConfigFiles @@ -206,6 +222,8 @@ Dependency types .. data:: DepReplaces .. data:: DepSuggests +.. _InstStates: + Installed states ^^^^^^^^^^^^^^^^^ .. data:: InstStateHold @@ -213,6 +231,7 @@ Installed states .. data:: InstStateOk .. data:: InstStateReInstReq +.. _Priorities: Priorities ^^^^^^^^^^ @@ -222,7 +241,10 @@ Priorities .. data:: PriRequired .. data:: PriStandard -Dselect states + +.. _SelStates: + +Select states ^^^^^^^^^^^^^^ .. data:: SelStateDeInstall .. data:: SelStateHold diff --git a/doc/source/conf.py b/doc/source/conf.py index 907e2275..bb8056ad 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -30,7 +30,8 @@ if os.path.exists("../../build"): # 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'] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] intersphinx_mapping = {'http://docs.python.org/': None} # Add any paths that contain templates here, relative to this directory. @@ -193,3 +194,5 @@ latex_documents = [ # If false, no module index is generated. #latex_use_modindex = True + +todo_include_todos = True diff --git a/doc/source/examples/cache-packages.py b/doc/source/examples/cache-packages.py new file mode 100644 index 00000000..1abe7cf2 --- /dev/null +++ b/doc/source/examples/cache-packages.py @@ -0,0 +1,22 @@ +#!/usr/bin/python +"""Example for packages. Print all essential and important packages""" + +import apt_pkg + + +def main(): + """Main.""" + apt_pkg.InitConfig() + apt_pkg.InitSystem() + cache = apt_pkg.GetCache() + print "Essential packages:" + for pkg in cache.Packages: + if pkg.Essential: + print " ", pkg.Name + print "Important packages:" + for pkg in cache.Packages: + if pkg.Important: + print " ", pkg.Name + +if __name__ == "__main__": + main() diff --git a/doc/source/examples/cache-pkgfile.py b/doc/source/examples/cache-pkgfile.py new file mode 100644 index 00000000..f25975d3 --- /dev/null +++ b/doc/source/examples/cache-pkgfile.py @@ -0,0 +1,29 @@ +#!/usr/bin/python +import apt_pkg + + +def main(): + """Example for PackageFile()""" + apt_pkg.init() + cache = apt_pkg.GetCache() + for pkgfile in cache.FileList: + print 'Package-File:', pkgfile.FileName + print 'Index-Type:', pkgfile.IndexType # 'Debian Package Index' + if pkgfile.NotSource: + print 'Source: None' + else: + if pkgfile.Site: + # There is a source, and a site, print the site + print 'Source:', pkgfile.Site + else: + # It seems to be a local repository + print 'Source: Local package file' + if pkgfile.NotAutomatic: + # The system won't be updated automatically (eg. experimental) + print 'Automatic: No' + else: + print 'Automatic: Yes' + print + +if __name__ == '__main__': + main() diff --git a/doc/source/examples/missing-deps.py b/doc/source/examples/missing-deps.py new file mode 100644 index 00000000..0870eb98 --- /dev/null +++ b/doc/source/examples/missing-deps.py @@ -0,0 +1,51 @@ +#!/usr/bin/python +"""Check the archive for missing dependencies""" +import apt_pkg + + +def fmt_dep(dep): + """Format a Dependency object [of apt_pkg] as a string.""" + ret = dep.TargetPkg.Name + if dep.TargetVer: + ret += " (%s %s)" % (dep.CompType, dep.TargetVer) + return ret + +def check_version(pkgver): + """Check the version of the package""" + missing = [] + + for or_group in pkgver.DependsList.get("Pre-Depends", []) + \ + pkgver.DependsList.get("Depends", []): + if not any(dep.AllTargets() for dep in or_group): + # If none of the or-choices can be satisfied, add it to missing + missing.append(or_group) + + if missing: + print "Package:", pkgver.ParentPkg.Name + print "Version:", pkgver.VerStr + print "Missing:", + print ", ".join(" | ".join(fmt_dep(dep) for dep in or_group) + for or_group in missing) + print + + +def main(): + """The main function.""" + apt_pkg.InitConfig() + apt_pkg.InitSystem() + + cache = apt_pkg.GetCache() + + for pkg in sorted(cache.Packages, key=lambda pkg: pkg.Name): + # pkg is from a list of packages, sorted by name. + for version in pkg.VersionList: + # Check every version + for pfile, _ in version.FileList: + if (pfile.Origin == "Debian" and pfile.Component == "main" and + pfile.Archive == "unstable"): + # We only want packages from Debian unstable main. + check_version(version) + break + +if __name__ == "__main__": + main() -- cgit v1.2.3 From d388a868fc8671d71accec63d35165201dbfced2 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sat, 10 Jan 2009 21:07:54 +0100 Subject: * doc/source/apt_pkg/cache.rst: Add PkgAcqFile, AcquireItem, and Configuration Not documented: MetaIndex PackageIndexFile PkgManager PkgRecords PkgSourceList PkgSrcRecords ProblemResolver TagFile TagSection (9) --- doc/source/apt_pkg/cache.rst | 175 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) (limited to 'doc/source') diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 81ee2a8e..2f4fb2d6 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -17,6 +17,181 @@ Classes in apt_pkg Shut the fetcher down. +.. class:: PkgAcqFile + + This class provides no methods or attributes + +.. class:: AcquireItem + + .. attribute:: ID + + The ID of the item. + + .. attribute:: Complete + + Is the item completely acquired? + + .. attribute:: Local + + Is the item a local file? + + .. attribute:: IsTrusted + + Can the file be trusted? + + .. attribute:: FileSize + + The size of the file, in bytes. + + .. attribute:: ErrorText + + The error message. For example, when a file does not exist on a http + server, this will contain a 404 error message. + + .. attribute:: DestFile + + The location the file is saved as. + + .. attribute:: DescURI + + The source location. + + **Status**: + + .. attribute:: Status + + Integer, representing the status of the item. + + .. attribute:: StatIdle + + Constant for comparing :attr:`AcquireItem.Status`. + + .. attribute:: StatFetching + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatDone + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatError + + Constant for comparing :attr:`AcquireItem.Status` + + .. attribute:: StatAuthError + + Constant for comparing :attr:`AcquireItem.Status` + +ActionGroup --- brings eg. big speedup +-------------------------------------- + +.. class:: ActionGroup + + Normally, apt checkes the package cache after every modification for + packages which are automatically installed but on which no package depends + anymore (it collects the package garbage). + + Using ActionGroups you can turn this off and therefore make your code + much faster. + + Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg: + + .. code-block: python + + apt_pkg.GetPkgActionGroup(depcache) + + .. method:: release + + Release the ActionGroup. This will reactive the collection of package + garbage. + + +Configuration +-------------- + +.. class:: Configuration + + The Configuration objects store the configuration of apt. + + .. method:: Find(key[, default='']) + + Return the value for the given key. This is the same as + :meth:`Configuration.get`. + + If ``key`` does not exist, return ``default``. + + .. method:: FindFile(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:: FindDir(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:: FindI(key[, default=0]) + + Return the integer value stored at key. + + If ``key`` does not exist, return ``default``. + + .. method:: FindB(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 given 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:: ValueList([key]) + + Same as :meth:`Configuration.List`, but this time for the values. + + .. method:: MyTag() + + 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``. + + .. 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``. The cache --------- -- cgit v1.2.3 From cdc861975216d0a27bccc16aebdf1684a963727d Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 17:01:05 +0100 Subject: * doc/source/apt_pkg/cache.rst: Add the last classes There is no description for MetaIndex yet, but this will be added soon. --- doc/source/apt_pkg/cache.rst | 441 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 435 insertions(+), 6 deletions(-) (limited to 'doc/source') diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 2f4fb2d6..81fb0026 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -113,6 +113,15 @@ Configuration The Configuration objects store the configuration of apt. + .. 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. This is the same as @@ -193,12 +202,18 @@ Configuration This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`, it returns the value of key or if it does not exist, ``default``. + The cache --------- .. class:: pkgCache The :class:`pkgCache` class prov + .. describe:: cache[pkgname] + + Return the :class:`Package()` object for the package name given by + *pkgname*. + .. method:: Close() Close the package cache. @@ -218,11 +233,6 @@ The cache The parameter ``list`` refers to an object as returned by :func:`apt_pkg.GetPkgSourceList`. - .. method:: __getitem__(item) - - Return an :class:`Package` object for the package with the given - name. - .. attribute:: DependsCount The total number of dependencies. @@ -243,7 +253,7 @@ The cache The total number of package versions available in the cache. - .. attribute:: PackageFileCount + .. attribute:: PackageFileCount The total number of Packages files available (the Packages files listing the packages). This is the same as the length of the list in @@ -780,3 +790,422 @@ The pkgDepCache wrapper The size of the packages which are needed for the changes to be applied. + + +MetaIndex +--------- + +.. todo:: + + Complete them + +.. class:: MetaIndex + + .. attribute:: URI + .. attribute:: Dist + .. attribute:: IsTrusted + .. attribute:: IndexFiles + + +PackageIndexFile +---------------- + +.. class:: PackageIndexFile + + .. method:: ArchiveURI(path) + + Return the full url to path in the archive. + + .. attribute:: Label + + Return the Label. + + .. attribute:: Exists + + Return whether the file exists. + + .. attribute:: HasPackages + + Return whether the file has packages. + + .. attribute:: Size + + Size of the file + + .. attribute:: IsTrusted + + Whether we can trust the file. + + +PkgManager +---------- + +.. class:: PkgManager + + Class, as returned by :func:`apt_pkg.GetPackageManager`. + + .. method:: GetArchives(fetcher, list, records) + + Add all the selected packages to the :class:`Acquire()` object + ``fetcher``. + + The parameter ``list`` refers to a :class:`pkgSourceList()` object, as + returned by :func:`apt_pkg.GetPkgSourceList`. + + The parameter ``records`` refers to a :class:`pkgRecords()` object, as + returned by :func:`apt_pkg.GetPkgRecords`. + + .. method:: DoInstall() + + Install the packages. + + .. method:: FixMissing + + Fix the installation if a package could not be downloaded. + + .. attribute:: ResultCompleted + + A constant for checking whether the the result is 'completed'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + + .. attribute:: ResultFailed + + A constant for checking whether the the result is 'failed'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + + .. attribute:: ResultIncomplete + + A constant for checking whether the the result is 'incomplete'. + + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. + +pkgRecords +----------- + +.. class:: PkgRecords + + Provide access to the packages records. This provides very useful + attributes for fast (convient) access to some fields of the record. + + See :func:`apt_pkg.GetPkgRecords` for initialization. + + + .. 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.FileList`. + + Example (shortened): + + .. code-block:: python + + 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:: MD5Hash + + Return the MD5 hashsum of the package This refers to the field + 'MD5Sum' in the raw record. + + .. attribute:: SHA1Hash + + Return the SHA1 hashsum of the package. This refers to the field 'SHA1' + in the raw record. + + .. attribute:: SourcePkg + + Return the source package. + + .. attribute:: SourceVer + + Return the source version. + + .. attribute:: Maintainer + + Return the maintainer of the package. + + .. attribute:: ShortDesc + + Return the short description. This is the summary on the first line of + the 'Description' field. + + .. attribute:: LongDesc + + 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 + :func:`apt_pkg.ParseSection` to parse the record and access the field + name. + + Example: + + .. code-block:: python + + section = apt_pkg.ParseSection(records.Record) + print section['SHA256'] + +PkgSrcRecords +------------- + +.. class:: PkgSrcRecords + + 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:: BuildDepends + + Return the list of Build dependencies, as + ``str: package, str: version, int: op, int: type)``. + + .. table:: Values of ``op`` + + ===== ============================================= + Value Meaning + ===== ============================================= + 0x0 No Operation (no versioned build dependency) + 0x10 | (or) - this will be added to the other values + 0x1 <= (less than or equal) + 0x2 >= (greater than or equal) + 0x3 << (less than) + 0x4 >> (greater than) + 0x5 == (equal) + 0x6 != (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: + + .. code-block:: python + + [('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`. + + +:class:`PkgSourceList` + + .. todo:: + + Describe it. + + +:class:`ProblemResolver` --- Resolve problems + + 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:: InstallProtect() + + 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:: ResolveByKeep() + + Try to resolve problems only by using keep. + + +TagFile +------- + +.. class:: TagFile + + An object which represents a typical debian control file. Can be used for + Packages, Sources, control, Release, etc. + + Use :func:`apt_pkg.ParseTagFile` to parse a file. + + .. 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. + +TagSection +---------- + +.. class:: TagSection + + 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`. + + .. 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:: FindFlag(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 ``field`` if available, else return + ``default``. + + .. method:: has_key(key) + + Check whether the field with named by ``key`` exists. + + .. method:: keys() + + Return a list of keys in the section. -- cgit v1.2.3 From c8215a931b11db1b85b977920c720479de7bf902 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 17:36:10 +0100 Subject: doc/source/**.rst: rst Style changes. This changes our style to match the Python documentation. --- doc/source/apt/cache.rst | 16 +++-- doc/source/apt/debfile.rst | 2 +- doc/source/apt_inst.rst | 38 +++++----- doc/source/apt_pkg/cache.rst | 160 ++++++++++++++++++++----------------------- 4 files changed, 103 insertions(+), 113 deletions(-) (limited to 'doc/source') diff --git a/doc/source/apt/cache.rst b/doc/source/apt/cache.rst index f3ba7d52..d96cba97 100644 --- a/doc/source/apt/cache.rst +++ b/doc/source/apt/cache.rst @@ -7,14 +7,17 @@ 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. - -.. code-block:: python +all the packages on the system:: import apt import apt.progress @@ -40,12 +43,18 @@ 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 @@ -65,6 +74,5 @@ packages whose state has been changed, eg. packages marked for installation:: Exceptions ---------- .. autoexception:: FetchCancelledException - :members: .. autoexception:: FetchFailedException .. autoexception:: LockFailedException diff --git a/doc/source/apt/debfile.rst b/doc/source/apt/debfile.rst index c0146df9..7133b5a8 100644 --- a/doc/source/apt/debfile.rst +++ b/doc/source/apt/debfile.rst @@ -18,7 +18,7 @@ Binary 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()` + If you specify *cache* it has to point to an :class:`apt.cache.Cache()` object. .. versionchanged:: 0.7.9 diff --git a/doc/source/apt_inst.rst b/doc/source/apt_inst.rst index b405b9f4..97705f61 100644 --- a/doc/source/apt_inst.rst +++ b/doc/source/apt_inst.rst @@ -10,21 +10,19 @@ 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``. + 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``. + 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 + An example would be:: debExtract(open("package.deb"), my_callback, "data.tar.gz") @@ -32,9 +30,9 @@ Listing contents .. function:: tarExtract(file,func,comp) - Call the function ``func`` for each member of the tar file ``file``. + Call the function *func* for each member of the tar file *file*. - ``Comp`` is a string determining the compressor used. Possible options are + *Comp* is a string determining the compressor used. Possible options are "lzma", "bzip2" and "gzip". @@ -43,11 +41,11 @@ 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 *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. +The parameter *name* refers to the name of the member. In case of links, +*link* refers to the target of the link. Extracting contents @@ -55,14 +53,14 @@ Extracting contents .. function:: debExtractArchive(file, rootdir) - Extract the archive referenced by the :class:`file` object ``file`` - into the directory specified by ``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 + If the directory given by *rootdir* does not exist, the package is extracted into the current directory. .. function:: debExtractControl(file[, member='control']) @@ -70,9 +68,7 @@ Extracting contents 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 + something like:: print debExtractControl(open("package.deb")) @@ -84,7 +80,7 @@ Extracting contents Example: Emulating :program:`dpkg` :option:`--extract` ------------------------------------------------------- Here is a code snippet which emulates dpkg -x. It can be run as -``tool pkg.deb outdir``. +:program:`tool` :option:`pkg.deb` :option:`outdir`. .. literalinclude:: examples/dpkg-extract.py diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 81fb0026..65887dbf 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -94,9 +94,7 @@ ActionGroup --- brings eg. big speedup Using ActionGroups you can turn this off and therefore make your code much faster. - Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg: - - .. code-block: python + Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg:: apt_pkg.GetPkgActionGroup(depcache) @@ -115,66 +113,66 @@ Configuration .. describe:: conf[key] - Return the value of the option given key ``key``. If it does not + 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``. + Set the option at *key* to *value*. .. method:: Find(key[, default='']) - Return the value for the given key. This is the same as + Return the value for the given key *key*. This is the same as :meth:`Configuration.get`. - If ``key`` does not exist, return ``default``. + If *key* does not exist, return *default*. .. method:: FindFile(key[, default='']) - Return the filename hold by the configuration at key. This formats the + 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``. + If *key* does not exist, return *default*. .. method:: FindDir(key[, default='/']) - Return the absolute path to the directory specified in key. A trailing - slash is appended. + Return the absolute path to the directory specified in *key*. A + trailing slash is appended. - If ``key`` does not exist, return ``default``. + If *key* does not exist, return *default*. .. method:: FindI(key[, default=0]) - Return the integer value stored at key. + Return the integer value stored at *key*. - If ``key`` does not exist, return ``default``. + If *key* does not exist, return *default*. .. method:: FindB(key[, default=0]) - Return the boolean value stored at key. This returns an integer, but + 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``. + If *key* does not exist, return *default*. .. method:: Set(key, value) - Set the value of ``key`` to ``value``. + Set the value of *key* to *value*. .. method:: Exists(key) - Check whether the given key exists in the configuration. + 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 + 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, + 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. + Use *key* to specify a key of which the childs will be returned. .. method:: ValueList([key]) @@ -187,20 +185,20 @@ Configuration .. method:: Clear(key) - Clear the configuration. Remove all values and keys at ``key``. + Clear the configuration. Remove all values and keys at *key*. .. method:: keys([key]) - Return all the keys, recursive. If ``key`` is specified, ... (FIXME) + Return all the keys, recursive. If *key* is specified, ... (FIXME) .. method:: has_key(key) - Return whether the configuration contains the key ``key``. + Return whether the configuration contains the key *key*. .. 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``. + it returns the value of key or if it does not exist, *default*. The cache @@ -220,17 +218,17 @@ The cache .. method:: Open([progress]) - Open the package cache again. The parameter ``progress`` may be set to + 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()` + The parameter *progress* points to an :class:`apt.progress.FetchProgress()` object. - The parameter ``list`` refers to an object as returned by + The parameter *list* refers to an object as returned by :func:`apt_pkg.GetPkgSourceList`. .. attribute:: DependsCount @@ -311,9 +309,7 @@ PackageFile 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: - - .. code-block:: python + Example:: for pkgfile in cache.FileList: if pkgfile.NotSource: @@ -469,9 +465,7 @@ Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` tuples like ('pkgname', 'version', 'relation') for each or-choice. An example return value for a package with a 'Depends: python (>= 2.4)' - would be: - - .. code-block:: python + would be:: {'Depends': [ [ @@ -480,9 +474,7 @@ Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` ] } - The same for a dependency on A (>= 1) | B (>= 2): - - .. code-block:: python + The same for a dependency on A (>= 1) | B (>= 2):: {'Depends': [ [ @@ -640,10 +632,10 @@ The pkgDepCache wrapper Apply all the changes made. - The parameter ``fprogress`` has to be set to an instance of + 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 + The parameter *iprogress* has to be set to an instance of apt.progress.InstallProgress or one of its subclasses. .. method:: FixBroken() @@ -655,7 +647,7 @@ The pkgDepCache wrapper Return the candidate version of the package, ie. the version that would be installed normally. - The parameter ``pkg`` refers to an :class:`Package` object, + The parameter *pkg* refers to an :class:`Package` object, available using the :class:`pkgCache`. This method returns a :class:`Version` object. @@ -663,8 +655,8 @@ The pkgDepCache wrapper .. method:: SetCandidateVer(pkg, version) The opposite of :meth:`pkgDepCache.GetCandidateVer`. Set the candidate - version of the :class:`Package` ``pkg`` to the :class:`Version` - ``version``. + version of the :class:`Package` *pkg* to the :class:`Version` + *version*. .. method:: Upgrade([distUpgrade=False]) @@ -673,7 +665,7 @@ The pkgDepCache wrapper packages for upgrade. You still need to call :meth:`pkgDepCache.Commit` for the changes to apply. - To perform a dist-upgrade, the optional parameter ``distUpgrade`` has + To perform a dist-upgrade, the optional parameter *distUpgrade* has to be set to True. .. method:: FixBroken() @@ -694,30 +686,30 @@ The pkgDepCache wrapper .. method:: MarkKeep(pkg) - Mark the :class:`Package` ``pkg`` for keep. + Mark the :class:`Package` *pkg* for keep. .. method:: MarkDelete(pkg[, purge]) - Mark the :class:`Package` ``pkg`` for delete. If ``purge`` is True, + Mark the :class:`Package` *pkg* for delete. If *purge* is True, the configuration files will be removed as well. .. method:: MarkInstall(pkg[, autoInst=True[, fromUser=True]]) - Mark the :class:`Package` ``pkg`` for install. + Mark the :class:`Package` *pkg* for install. - If ``autoInst`` is True, the dependencies of the package will be + If *autoInst* is ``True``, the dependencies of the package will be installed as well. This is the default. - If ``fromUser`` is True, the package will be marked as manually + If *fromUser* is ``True``, the package will be marked as manually installed. This is the default. .. method:: SetReinstall(pkg) - Set if the :class:`Package` ``pkg`` should be reinstalled. + Set if the :class:`Package` *pkg* should be reinstalled. .. method:: IsUpgradable(pkg) - Return `1` if the package is upgradable. + Return ``1`` if the package is upgradable. The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. @@ -728,42 +720,42 @@ The pkgDepCache wrapper .. method:: IsInstBroken(pkg) - Return `1` if the package is broken on the current install. This takes - changes which have not been committed not into effect. + Return ``1`` if the package is broken on the current install. This + takes changes which have not been committed not into effect. .. method:: IsGarbage(pkg) - Return `1` if the package is garbage, ie. if it is automatically + Return ``1`` if the package is garbage, ie. if it is automatically installed and no longer referenced by other packages. .. method:: IsAutoInstalled(pkg) - Return `1` if the package is automatically installed (eg. as the + Return ``1`` if the package is automatically installed (eg. as the dependency of another package). .. method:: MarkedInstall(pkg) - Return `1` if the package is marked for install. + Return ``1`` if the package is marked for install. .. method:: MarkedUpgrade(pkg) - Return `1` if the package is marked for upgrade. + Return ``1`` if the package is marked for upgrade. .. method:: MarkedDelete(pkg) - Return `1` if the package is marked for delete. + Return ``1`` if the package is marked for delete. .. method:: MarkedKeep(pkg) - Return `1` if the package is marked for keep. + Return ``1`` if the package is marked for keep. .. method:: MarkedReinstall(pkg) - Return `1` if the package should be installed. + Return ``1`` if the package should be installed. .. method:: MarkedDowngrade(pkg) - Return `1` if the package should be downgraded. + Return ``1`` if the package should be downgraded. .. attribute:: KeepCount @@ -847,12 +839,12 @@ PkgManager .. method:: GetArchives(fetcher, list, records) Add all the selected packages to the :class:`Acquire()` object - ``fetcher``. + *fetcher*. - The parameter ``list`` refers to a :class:`pkgSourceList()` object, as + The parameter *list* refers to a :class:`pkgSourceList()` object, as returned by :func:`apt_pkg.GetPkgSourceList`. - The parameter ``records`` refers to a :class:`pkgRecords()` object, as + The parameter *records* refers to a :class:`pkgRecords()` object, as returned by :func:`apt_pkg.GetPkgRecords`. .. method:: DoInstall() @@ -899,13 +891,11 @@ pkgRecords Change the actual package to the package given by the verfile_iter. - The parameter ``verfile_iter`` refers to a tuple consisting + The parameter *verfile_iter* refers to a tuple consisting of (:class:`PackageFile()`, int: index), as returned by various attributes, including :attr:`Version.FileList`. - Example (shortened): - - .. code-block:: python + Example (shortened):: cand = depcache.GetCandidateVer(cache['python-apt']) records.Lookup(cand.FileList[0]) @@ -964,9 +954,7 @@ pkgRecords :func:`apt_pkg.ParseSection` to parse the record and access the field name. - Example: - - .. code-block:: python + Example:: section = apt_pkg.ParseSection(records.Record) print section['SHA256'] @@ -988,7 +976,7 @@ PkgSrcRecords .. method:: Lookup(pkgname) - Lookup the record for the package named ``pkgname``. To access all + 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)`` @@ -1050,7 +1038,7 @@ PkgSrcRecords Return the list of Build dependencies, as ``str: package, str: version, int: op, int: type)``. - .. table:: Values of ``op`` + .. table:: Values of *op* ===== ============================================= Value Meaning @@ -1065,7 +1053,7 @@ PkgSrcRecords 0x6 != (not equal) ===== ============================================= - .. table:: Values of ``type`` + .. table:: Values of *type* ===== =================== Value Meaning @@ -1081,9 +1069,7 @@ PkgSrcRecords Build-Depends: A (>= 1) | B (>= 1), C - This results in: - - .. code-block:: python + This results in:: [('A', '1', 18, 0), # 18 = 16 + 2 = 0x10 + 0x2 ('B', '1', 2, 0), @@ -1108,7 +1094,7 @@ PkgSrcRecords .. method:: Protect(pkg) - Protect the :class:`Package()` object given by the parameter ``pkg``. + Protect the :class:`Package()` object given by the parameter *pkg*. .. todo:: @@ -1120,7 +1106,7 @@ PkgSrcRecords .. method:: Remove(pkg) - Remove the :class:`Package()` object given by the parameter ``pkg``. + Remove the :class:`Package()` object given by the parameter *pkg*. .. todo:: @@ -1128,7 +1114,7 @@ PkgSrcRecords .. method:: Clear(pkg) - Reset the :class:`Package()` ``pkg`` to the default state. + Reset the :class:`Package()` *pkg* to the default state. .. todo:: @@ -1164,7 +1150,7 @@ TagFile .. method:: Jump(offset) - Jump back/forward to ``offset``. Use ``Jump(0)`` to jump to the + Jump back/forward to *offset*. Use ``Jump(0)`` to jump to the beginning of the file again. .. attribute:: Section @@ -1180,7 +1166,7 @@ TagSection .. describe:: section[key] - Return the value of the field at ``key``. If ``key`` is not available, + Return the value of the field at *key*. If *key* is not available, raise :exc:`KeyError`. .. method:: Bytes @@ -1189,22 +1175,22 @@ TagSection .. method:: Find(key, default='') - Return the value of the field at the key ``key`` if available, - else return ``default``. + Return the value of the field at the key *key* if available, + else return *default*. .. method:: FindFlag(key) - Find a yes/no value for the key ``key``. An example for such a + 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 ``field`` if available, else return - ``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. + Check whether the field with named by *key* exists. .. method:: keys() -- cgit v1.2.3 From 0998ee54b5b56d7ca91310d28f73028cfc0e036c Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 18:30:58 +0100 Subject: * doc/: Small updates, add PkgSourceList --- doc/source/apt_pkg/cache.rst | 99 +++++++++++++++++++++++++++----------------- doc/source/index.rst | 3 ++ 2 files changed, 64 insertions(+), 38 deletions(-) (limited to 'doc/source') diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 65887dbf..0a02c47c 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -5,7 +5,8 @@ Classes in apt_pkg This should be split and cleaned up a bit. - +:class:`Acquire` +---------------- .. class:: Acquire .. method:: Run() @@ -17,10 +18,15 @@ Classes in apt_pkg Shut the fetcher down. +:class:`PkgAcqFile` +------------------- .. class:: PkgAcqFile This class provides no methods or attributes +:class:`AcquireItem` +--------------------- + .. class:: AcquireItem .. attribute:: ID @@ -82,8 +88,8 @@ Classes in apt_pkg Constant for comparing :attr:`AcquireItem.Status` -ActionGroup --- brings eg. big speedup --------------------------------------- +:class:`ActionGroup` +-------------------- .. class:: ActionGroup @@ -104,8 +110,8 @@ ActionGroup --- brings eg. big speedup garbage. -Configuration --------------- +:class:`Configuration` +---------------------- .. class:: Configuration @@ -201,8 +207,8 @@ Configuration it returns the value of key or if it does not exist, *default*. -The cache ---------- +:class:`pkgCache` +----------------- .. class:: pkgCache The :class:`pkgCache` class prov @@ -262,8 +268,8 @@ The cache A list of :class:`PackageFile` objects. -PackageFile ------------- +:class:`PackageFile` +-------------------- .. class:: PackageFile A :class:`PackageFile` represents a Packages file, eg. @@ -337,8 +343,8 @@ Example .. literalinclude:: ../examples/cache-pkgfile.py -A Package ---------- +:class:`Package` +---------------- .. class:: Package @@ -429,8 +435,8 @@ Example: -Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` ---------------------------------------------------------------- +:class:`Version` +---------------- .. class:: Version The version object contains all information related to a specific package @@ -540,8 +546,8 @@ Version, as returned by eg. :meth:`pkgDepCache.GetCandidateVer` Return a :class:`Description` object. -The Dependency class --------------------- +:class:`Dependency` +------------------- .. class:: Dependency Represent a dependency from one package to another one. @@ -601,8 +607,8 @@ broken dependencies: .. literalinclude:: ../examples/missing-deps.py -The Description class ---------------------- +:class:`Description` +-------------------- .. class:: Description Represent the description of the package. @@ -621,8 +627,8 @@ The Description class -The pkgDepCache wrapper ------------------------ +:class:`pkgDepCache` +-------------------- .. class:: pkgDepCache The pkgDepCache object contains various methods to manipulate the cache, @@ -784,8 +790,8 @@ The pkgDepCache wrapper applied. -MetaIndex ---------- +:class:`MetaIndex` +------------------ .. todo:: @@ -799,8 +805,8 @@ MetaIndex .. attribute:: IndexFiles -PackageIndexFile ----------------- +:class:`PackageIndexFile` +------------------------- .. class:: PackageIndexFile @@ -829,8 +835,8 @@ PackageIndexFile Whether we can trust the file. -PkgManager ----------- +:class:`PkgManager` +------------------- .. class:: PkgManager @@ -841,7 +847,7 @@ PkgManager Add all the selected packages to the :class:`Acquire()` object *fetcher*. - The parameter *list* refers to a :class:`pkgSourceList()` object, as + The parameter *list* refers to a :class:`PkgSourceList()` object, as returned by :func:`apt_pkg.GetPkgSourceList`. The parameter *records* refers to a :class:`pkgRecords()` object, as @@ -876,8 +882,8 @@ PkgManager Compare it against the return value of :meth:`PkgManager.GetArchives` or :meth:`PkgManager.DoInstall`. -pkgRecords ------------ +:class:`pkgRecords` +-------------------- .. class:: PkgRecords @@ -959,8 +965,8 @@ pkgRecords section = apt_pkg.ParseSection(records.Record) print section['SHA256'] -PkgSrcRecords -------------- +:class:`PkgSrcRecords` +---------------------- .. class:: PkgSrcRecords @@ -1036,7 +1042,7 @@ PkgSrcRecords .. attribute:: BuildDepends Return the list of Build dependencies, as - ``str: package, str: version, int: op, int: type)``. + ``(str: package, str: version, int: op, int: type)``. .. table:: Values of *op* @@ -1080,13 +1086,30 @@ PkgSrcRecords :class:`PkgSourceList` +----------------------- + +.. class:: PkgSourceList + + This is for :file:`/etc/apt/sources.list`. - .. todo:: + .. method:: FindIndex(pkgfile) - Describe it. + Return a :class:`PackageIndexFile` object for the :class:`PackageFile` + *pkgfile*. + .. method:: ReadMainList -:class:`ProblemResolver` --- Resolve problems + Read the main list. + + .. method:: GetIndexes(acq[, all]) + + Add the index files to the :class:`Acquire()` object *acq*. If *all* is + given and ``True``, all files are fetched. + + +:class:`ProblemResolver` +------------------------ +.. class:: ProblemResolver The problem resolver helps when there are problems in the package selection. An example is a package which conflicts with another, already @@ -1129,8 +1152,8 @@ PkgSrcRecords Try to resolve problems only by using keep. -TagFile -------- +:class:`TagFile` +---------------- .. class:: TagFile @@ -1157,8 +1180,8 @@ TagFile This is the current :class:`TagSection()` instance. -TagSection ----------- +:class:`TagSection` +------------------- .. class:: TagSection diff --git a/doc/source/index.rst b/doc/source/index.rst index d7c425bd..23ea4cca 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -36,3 +36,6 @@ Indices and tables * :ref:`search` +TODO +====== +.. todolist:: -- cgit v1.2.3 From 2e980f4f190abb787f9aa9939a404875905d651c Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 20:02:29 +0100 Subject: * Add support for PkgRecords.SHA256Hash (Closes: #456113) --- debian/changelog | 3 ++- doc/source/apt_pkg/cache.rst | 5 +++++ python/pkgrecords.cc | 2 ++ 3 files changed, 9 insertions(+), 1 deletion(-) (limited to 'doc/source') diff --git a/debian/changelog b/debian/changelog index fbf665cd..49236999 100644 --- a/debian/changelog +++ b/debian/changelog @@ -30,8 +30,9 @@ python-apt (0.7.9~exp2) experimental; urgency=low * Merge Ben Finney's whitespace changes (Closes: #481563) * Merge Ben Finney's do not use has_key() (Closes: #481878) * Do not use deprecated form of raise statement (Closes: #494259) + * Add support for PkgRecords.SHA256Hash (Closes: #456113) - -- Julian Andres Klode Sun, 11 Jan 2009 19:55:11 +0100 + -- Julian Andres Klode Sun, 11 Jan 2009 20:01:59 +0100 python-apt (0.7.9~exp1) experimental; urgency=low diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 0a02c47c..6e924aeb 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -923,6 +923,11 @@ broken dependencies: Return the SHA1 hashsum of the package. This refers to the field 'SHA1' in the raw record. + .. attribute:: SHA256Hash + + Return the SHA256 hashsum of the package. This refers to the field + 'SHA256' in the raw record. + .. attribute:: SourcePkg Return the source package. diff --git a/python/pkgrecords.cc b/python/pkgrecords.cc index 18240ce0..5359ee6f 100644 --- a/python/pkgrecords.cc +++ b/python/pkgrecords.cc @@ -65,6 +65,8 @@ static PyObject *PkgRecordsAttr(PyObject *Self,char *Name) return CppPyString(Struct.Last->MD5Hash()); else if (strcmp("SHA1Hash",Name) == 0) return CppPyString(Struct.Last->SHA1Hash()); + else if (strcmp("SHA256Hash",Name) == 0) + return CppPyString(Struct.Last->SHA256Hash()); else if (strcmp("SourcePkg",Name) == 0) return CppPyString(Struct.Last->SourcePkg()); else if (strcmp("SourceVer",Name) == 0) -- cgit v1.2.3 From eb32fb89da3e3e1ff4a9668aaed6d533f04e9ee7 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Sun, 11 Jan 2009 20:48:40 +0100 Subject: * doc/source/apt_pkg/cache.rst: Mention the SHA256Hash is new in 0.7.9 --- doc/source/apt_pkg/cache.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc/source') diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg/cache.rst index 6e924aeb..af67d82f 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg/cache.rst @@ -928,6 +928,8 @@ broken dependencies: Return the SHA256 hashsum of the package. This refers to the field 'SHA256' in the raw record. + .. versionadded:: 0.7.9 + .. attribute:: SourcePkg Return the source package. -- cgit v1.2.3 From 2e4443bbd9872f5599c9a8eb93a65d6c34c83ca2 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Mon, 12 Jan 2009 17:01:34 +0100 Subject: Cleanup: Comparisons to True/False, ==/!= None, deprecated modules --- apt/cache.py | 16 +++++------ aptsources/distinfo.py | 16 +++++------ aptsources/distro.py | 13 +++++---- aptsources/sourceslist.py | 54 +++++++++++++++++-------------------- doc/examples/action.py | 4 +-- doc/examples/all_deps.py | 4 +-- doc/examples/build-deps.py | 3 +-- doc/examples/depcache.py | 4 +-- doc/examples/dependant-pkgs.py | 2 +- doc/examples/gui-inst.py | 9 +------ doc/examples/progress.py | 9 +++---- doc/examples/versiontest.py | 3 +-- doc/source/conf.py | 18 +++++++------ doc/source/examples/missing-deps.py | 1 + setup.py | 9 +++---- tests/depcache.py | 2 +- tests/pkgproblemresolver.py | 2 +- tests/test_aptsources_ports.py | 18 ++++++++----- tests/test_debextract.py | 19 ++++++++----- 19 files changed, 98 insertions(+), 108 deletions(-) (limited to 'doc/source') diff --git a/apt/cache.py b/apt/cache.py index f134ab0a..ff3149f5 100644 --- a/apt/cache.py +++ b/apt/cache.py @@ -76,12 +76,12 @@ class Cache(object): self._dict = {} # build the packages dict - if progress != None: + if progress is not None: progress.Op = "Building data structures" i=last=0 size=len(self._cache.Packages) for pkg in self._cache.Packages: - if progress != None and last+100 < i: + if progress is not None and last+100 < i: progress.update(i/float(size)*100) last=i # drop stuff with no versions (cruft) @@ -91,7 +91,7 @@ class Cache(object): self, pkg) i += 1 - if progress != None: + if progress is not None: progress.done() self._runCallbacks("cache_post_open") @@ -216,7 +216,7 @@ class Cache(object): return providers for pkg in self: v = self._depcache.GetCandidateVer(pkg._pkg) - if v == None: + if v is None: continue for p in v.ProvidesList: if virtual == p[0]: @@ -232,7 +232,7 @@ class Cache(object): raise LockFailedException("Failed to lock %s" % lockfile) try: - if fetchProgress == None: + if fetchProgress is None: fetchProgress = apt.progress.FetchProgress() return self._cache.Update(fetchProgress, self._list) finally: @@ -253,9 +253,9 @@ class Cache(object): # Current a failed download will just display "error" # which is less than optimal! - if fetchProgress == None: + if fetchProgress is None: fetchProgress = apt.progress.FetchProgress() - if installProgress == None: + if installProgress is None: installProgress = apt.progress.InstallProgress() pm = apt_pkg.GetPackageManager(self._depcache) @@ -327,7 +327,7 @@ class FilteredCache(object): """ def __init__(self, cache=None, progress=None): - if cache == None: + if cache is None: self.cache = Cache(progress) else: self.cache = cache diff --git a/aptsources/distinfo.py b/aptsources/distinfo.py index 3c499b52..59fa7e02 100644 --- a/aptsources/distinfo.py +++ b/aptsources/distinfo.py @@ -27,11 +27,9 @@ import os import gettext from os import getenv import ConfigParser -import string -import apt_pkg +import re -#from gettext import gettext as _ -import gettext +import apt_pkg def _(s): @@ -76,9 +74,9 @@ class Component: self.description_long = long_desc def get_description(self): - if self.description_long != None: + if self.description_long is not None: return self.description_long - elif self.description != None: + elif self.description is not None: return self.description else: return None @@ -221,8 +219,8 @@ class DistInfo: mirror_set = {} try: mirror_data = filter(match_mirror_line.match, - map(string.strip, open(value))) - except: + [x.strip() for x in open(value)]) + except Exception: print "WARNING: Failed to read mirror file" mirror_data = [] for line in mirror_data: @@ -256,7 +254,7 @@ class DistInfo: if not template: return # reuse some properties of the parent template - if template.match_uri == None and template.child: + if template.match_uri is None and template.child: for t in template.parents: if t.match_uri: template.match_uri = t.match_uri diff --git a/aptsources/distro.py b/aptsources/distro.py index a8f1d0fd..d8f191d6 100644 --- a/aptsources/distro.py +++ b/aptsources/distro.py @@ -21,7 +21,6 @@ # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 # USA -import string import gettext import re import os @@ -86,7 +85,7 @@ class Distribution: # template.components self.source_template = template break - if self.source_template == None: + if self.source_template is None: raise NoDistroTemplateException("Error: could not find a " "distribution template") @@ -259,14 +258,14 @@ class Distribution: """ Add distribution specific sources """ - if uri == None: + if uri is None: # FIXME: Add support for the server selector uri = self.default_server - if dist == None: + if dist is None: dist = self.codename - if comps == None: + if comps is None: comps = list(self.enabled_comps) - if type == None: + if type is None: type = self.binary_type new_source = self.sourceslist.add(type, uri, dist, comps, comment) # if source code is enabled add a deb-src line after the new @@ -379,7 +378,7 @@ class Distribution: change_server_of_source(source, uri, seen_binary) for source in self.child_sources: # Do not change the forces server of a child source - if source.template.base_uri == None or \ + if source.template.base_uri is None or \ source.template.base_uri != source.uri: change_server_of_source(source, uri, seen_binary) for source in self.source_code_sources: diff --git a/aptsources/sourceslist.py b/aptsources/sourceslist.py index a0346267..dc2a5d45 100644 --- a/aptsources/sourceslist.py +++ b/aptsources/sourceslist.py @@ -23,18 +23,16 @@ # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 # USA -import string import gettext -import re -import apt_pkg import glob -import shutil -import time import os.path +import re +import shutil import sys +import time -#from UpdateManager.Common.DistInfo import DistInfo -from distinfo import DistInfo +import apt_pkg +from aptsources.distinfo import DistInfo # some global helpers @@ -88,7 +86,7 @@ class SourceEntry: # (may empty) self.comment = "" # (optional) comment self.line = line # the original sources.list line - if file == None: + if file is None: file = apt_pkg.Config.FindDir( "Dir::Etc")+apt_pkg.Config.Find("Dir::Etc::sourcelist") self.file = file # the file that the entry is located in @@ -107,7 +105,7 @@ class SourceEntry: def mysplit(self, line): """ a split() implementation that understands the sources.list format better and takes [] into account (for e.g. cdroms) """ - line = string.strip(line) + line = line.strip() pieces = [] tmp = "" # we are inside a [..] block @@ -138,7 +136,7 @@ class SourceEntry: def parse(self, line): """ parse a given sources.list (textual) line and break it up into the field we have """ - line = string.strip(self.line) + line = self.line.strip() #print line # check if the source is enabled/disabled if line == "" or line == "#": # empty line @@ -146,7 +144,7 @@ class SourceEntry: return if line[0] == "#": self.disabled = True - pieces = string.split(line[1:]) + pieces = line[1:].strip() # if it looks not like a disabled deb line return if not pieces[0] in ("rpm", "rpm-src", "deb", "deb-src"): self.invalid = True @@ -165,18 +163,18 @@ class SourceEntry: self.invalid = True return # Type, deb or deb-src - self.type = string.strip(pieces[0]) + self.type = pieces[0].strip() # Sanity check if self.type not in ("deb", "deb-src", "rpm", "rpm-src"): self.invalid = True return # URI - self.uri = string.strip(pieces[1]) + self.uri = pieces[1].strip() if len(self.uri) < 1: self.invalid = True # distro and components (optional) # Directory or distro - self.dist = string.strip(pieces[2]) + self.dist = pieces[2].strip() if len(pieces) > 3: # List of components self.comps = pieces[3:] @@ -187,15 +185,11 @@ class SourceEntry: """ set a line to enabled or disabled """ self.disabled = not new_value # enable, remove all "#" from the start of the line - if new_value == True: - i=0 - self.line = string.lstrip(self.line) - while self.line[i] == "#": - i += 1 - self.line = self.line[i:] + if new_value: + self.line = self.line.lstrip().lstrip('#') else: # disabled, add a "#" - if string.strip(self.line)[0] != "#": + if self.line.strip()[0] != "#": self.line = "#" + self.line def __str__(self): @@ -251,7 +245,7 @@ class SourcesList: self.load(file) # check if the source item fits a predefined template for source in self.list: - if source.invalid == False: + if not source.invalid: self.matcher.match(source) def __iter__(self): @@ -272,7 +266,7 @@ class SourcesList: comps = orig_comps[:] # check if we have this source already in the sources.list for source in self.list: - if source.disabled == False and source.invalid == False and \ + if not source.disabled and not source.invalid and \ source.type == type and uri == source.uri and \ source.dist == dist: for new_comp in comps: @@ -285,14 +279,14 @@ class SourcesList: for source in self.list: # if there is a repo with the same (type, uri, dist) just add the # components - if source.disabled == False and source.invalid == False and \ + if not source.disabled and not source.invalid and \ source.type == type and uri == source.uri and \ source.dist == dist: comps = uniq(source.comps + comps) source.comps = comps return source # if there is a corresponding repo which is disabled, enable it - elif source.disabled == True and source.invalid == False and \ + elif source.disabled and not source.invalid and \ source.type == type and uri == source.uri and \ source.dist == dist and \ len(set(source.comps) & set(comps)) == len(comps): @@ -306,7 +300,7 @@ class SourcesList: line = "%s #%s\n" % (line, comment) line = line + "\n" new_entry = SourceEntry(line) - if file != None: + if file is not None: new_entry.file = file self.matcher.match(new_entry) self.list.insert(pos, new_entry) @@ -333,7 +327,7 @@ class SourcesList: """ make a backup of the current source files, if no backup extension is given, the current date/time is used (and returned) """ already_backuped = set() - if backup_ext == None: + if backup_ext is None: backup_ext = time.strftime("%y%m%d.%H%M") for source in self.list: if not source.file in already_backuped \ @@ -380,11 +374,11 @@ class SourcesList: used_child_templates = {} for source in sources_list: # try to avoid checking uninterressting sources - if source.template == None: + if source.template is None: continue # set up a dict with all used child templates and corresponding # source entries - if source.template.child == True: + if source.template.child: key = source.template if key not in used_child_templates: used_child_templates[key] = [] @@ -414,7 +408,7 @@ class SourceEntryMatcher: f = f[0:i] dist = DistInfo(f, base_dir=matcherPath) for template in dist.templates: - if template.match_uri != None: + if template.match_uri is not None: self.templates.append(template) return diff --git a/doc/examples/action.py b/doc/examples/action.py index 7153292c..9b9d7dd3 100644 --- a/doc/examples/action.py +++ b/doc/examples/action.py @@ -86,7 +86,7 @@ print "UsrSize: %s " % apt_pkg.SizeToStr(depcache.UsrSize) print "DebSize: %s " % apt_pkg.SizeToStr(depcache.DebSize) for pkg in cache.Packages: - if pkg.CurrentVer != None and not depcache.MarkedInstall(pkg) \ + if pkg.CurrentVer is not None and not depcache.MarkedInstall(pkg) \ and depcache.IsUpgradable(pkg): print "Upgrade didn't upgrade (kept): %s" % pkg.Name @@ -101,7 +101,7 @@ print "DebSize: %s " % apt_pkg.SizeToStr(depcache.DebSize) # overview about what would happen for pkg in cache.Packages: if depcache.MarkedInstall(pkg): - if pkg.CurrentVer != None: + if pkg.CurrentVer is not None: print "Marked upgrade: %s " % pkg.Name else: print "Marked install: %s" % pkg.Name diff --git a/doc/examples/all_deps.py b/doc/examples/all_deps.py index 0a2f3157..992e98d8 100644 --- a/doc/examples/all_deps.py +++ b/doc/examples/all_deps.py @@ -1,13 +1,13 @@ #!/usr/bin/env python - import sys + import apt def dependencies(cache, pkg, deps, key="Depends"): #print "pkg: %s (%s)" % (pkg.name, deps) candver = cache._depcache.GetCandidateVer(pkg._pkg) - if candver == None: + if candver is None: return deps dependslist = candver.DependsList if key in dependslist: diff --git a/doc/examples/build-deps.py b/doc/examples/build-deps.py index dc1a6f4e..aeb5667c 100755 --- a/doc/examples/build-deps.py +++ b/doc/examples/build-deps.py @@ -3,7 +3,6 @@ import apt_pkg import sys -import sets # only needed for python2.3, python2.4 supports this naively def get_source_pkg(pkg, records, depcache): @@ -37,7 +36,7 @@ try: except KeyError: print "No package %s found" % sys.argv[1] sys.exit(1) -all_build_depends = sets.Set() +all_build_depends = set() # get the build depdends for the package itself srcpkg_name = get_source_pkg(base, records, depcache) diff --git a/doc/examples/depcache.py b/doc/examples/depcache.py index ad884fe7..790cc9d6 100644 --- a/doc/examples/depcache.py +++ b/doc/examples/depcache.py @@ -84,7 +84,7 @@ print "UsrSize: %s " % apt_pkg.SizeToStr(depcache.UsrSize) print "DebSize: %s " % apt_pkg.SizeToStr(depcache.DebSize) for pkg in cache.Packages: - if pkg.CurrentVer != None and not depcache.MarkedInstall(pkg) \ + if pkg.CurrentVer is not None and not depcache.MarkedInstall(pkg) \ and depcache.IsUpgradable(pkg): print "Upgrade didn't upgrade (kept): %s" % pkg.Name @@ -100,7 +100,7 @@ print "DebSize: %s " % apt_pkg.SizeToStr(depcache.DebSize) # overview about what would happen for pkg in cache.Packages: if depcache.MarkedInstall(pkg): - if pkg.CurrentVer != None: + if pkg.CurrentVer is not None: print "Marked upgrade: %s " % pkg.Name else: print "Marked install: %s" % pkg.Name diff --git a/doc/examples/dependant-pkgs.py b/doc/examples/dependant-pkgs.py index bb10ce70..5fbbc76d 100755 --- a/doc/examples/dependant-pkgs.py +++ b/doc/examples/dependant-pkgs.py @@ -7,7 +7,7 @@ pkgs = set() cache = apt.Cache() for pkg in cache: candver = cache._depcache.GetCandidateVer(pkg._pkg) - if candver == None: + if candver is None: continue dependslist = candver.DependsList for dep in dependslist.keys(): diff --git a/doc/examples/gui-inst.py b/doc/examples/gui-inst.py index cb49db3e..8138d922 100755 --- a/doc/examples/gui-inst.py +++ b/doc/examples/gui-inst.py @@ -1,20 +1,13 @@ #!/usr/bin/python # example how to install in a custom terminal widget # see also gnome bug: #169201 - -import apt -import apt_pkg -import sys, os, fcntl -import copy -import string -import fcntl - import pygtk pygtk.require('2.0') import gtk import apt.gtk.widgets + if __name__ == "__main__": win = gtk.Window() diff --git a/doc/examples/progress.py b/doc/examples/progress.py index c56734b7..83847598 100644 --- a/doc/examples/progress.py +++ b/doc/examples/progress.py @@ -1,8 +1,7 @@ -import apt -from apt import SizeToStr import sys import time -import string + +import apt class TextProgress(apt.OpProgress): @@ -39,8 +38,8 @@ class TextFetchProgress(apt.FetchProgress): def pulse(self): print "Pulse: CPS: %s/s; Bytes: %s/%s; Item: %s/%s" % ( - SizeToStr(self.currentCPS), SizeToStr(self.currentBytes), - SizeToStr(self.totalBytes), self.currentItems, self.totalItems) + apt.SizeToStr(self.currentCPS), SizeToStr(self.currentBytes), + apt.SizeToStr(self.totalBytes), self.currentItems, self.totalItems) return True def mediaChange(self, medium, drive): diff --git a/doc/examples/versiontest.py b/doc/examples/versiontest.py index dd881f6b..fa13cc1c 100755 --- a/doc/examples/versiontest.py +++ b/doc/examples/versiontest.py @@ -4,7 +4,6 @@ import apt_pkg import sys import re -import string apt_pkg.InitConfig() apt_pkg.InitSystem() @@ -22,7 +21,7 @@ while(1): CurLine = CurLine + 1 if Line == "": break - Line = string.strip(Line) + Line = Line.strip() if len(Line) == 0 or Line[0] == '#': continue diff --git a/doc/source/conf.py b/doc/source/conf.py index bb8056ad..8f71e3e3 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -3,18 +3,20 @@ # 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. +# 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). +# 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 +import os +import sys # 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 @@ -28,8 +30,8 @@ if os.path.exists("../../build"): # 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. +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo'] intersphinx_mapping = {'http://docs.python.org/': None} @@ -76,7 +78,7 @@ release = '0.7.9~exp2' # for source files. exclude_trees = [] -# The reST default role (used for this markup: `text`) to use for all documents. +# The reST default role (used for this markup: `text`) for all documents. #default_role = None # If true, '()' will be appended to :func: etc. cross-reference text. @@ -172,7 +174,7 @@ htmlhelp_basename = 'python-aptdoc' #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]). +# (source index, target name, title, author, document class [howto/manual]). latex_documents = [ ('index', 'python-apt.tex', ur'python-apt Documentation', ur'Julian Andres Klode ', 'manual'), diff --git a/doc/source/examples/missing-deps.py b/doc/source/examples/missing-deps.py index 0870eb98..3ca16e45 100644 --- a/doc/source/examples/missing-deps.py +++ b/doc/source/examples/missing-deps.py @@ -10,6 +10,7 @@ def fmt_dep(dep): ret += " (%s %s)" % (dep.CompType, dep.TargetVer) return ret + def check_version(pkgver): """Check the version of the package""" missing = [] diff --git a/setup.py b/setup.py index c9f940a4..6a22734d 100755 --- a/setup.py +++ b/setup.py @@ -3,24 +3,21 @@ from distutils.core import setup, Extension from distutils.sysconfig import parse_makefile -from DistUtilsExtra.command import * +from DistUtilsExtra.command import build_extra, build_i18n import glob import os -import os.path -import pydoc import shutil -import string import sys # The apt_pkg module files = map(lambda source: "python/"+source, - string.split(parse_makefile("python/makefile")["APT_PKG_SRC"])) + parse_makefile("python/makefile")["APT_PKG_SRC"].split()) apt_pkg = Extension("apt_pkg", files, libraries=["apt-pkg"]) # The apt_inst module files = map(lambda source: "python/"+source, - string.split(parse_makefile("python/makefile")["APT_INST_SRC"])) + parse_makefile("python/makefile")["APT_INST_SRC"].split()) apt_inst = Extension("apt_inst", files, libraries=["apt-pkg", "apt-inst"]) # Replace the leading _ that is used in the templates for translation diff --git a/tests/depcache.py b/tests/depcache.py index b199c812..19aba680 100644 --- a/tests/depcache.py +++ b/tests/depcache.py @@ -22,7 +22,7 @@ def main(): x = pkg.Name # then get each version ver =depcache.GetCandidateVer(pkg) - if ver != None: + if ver is not None: depcache.MarkInstall(pkg) if depcache.InstCount == 0: if depcache.IsUpgradable(pkg): diff --git a/tests/pkgproblemresolver.py b/tests/pkgproblemresolver.py index 7d5ae682..a21d8d9d 100644 --- a/tests/pkgproblemresolver.py +++ b/tests/pkgproblemresolver.py @@ -22,7 +22,7 @@ def main(): x = pkg.Name # then get each version ver =depcache.GetCandidateVer(pkg) - if ver != None: + if ver is not None: depcache.MarkInstall(pkg) if depcache.BrokenCount > 0: fixer = apt_pkg.GetPkgProblemResolver(depcache) diff --git a/tests/test_aptsources_ports.py b/tests/test_aptsources_ports.py index 203721c7..09d6e9d9 100644 --- a/tests/test_aptsources_ports.py +++ b/tests/test_aptsources_ports.py @@ -1,28 +1,32 @@ #!/usr/bin/env python import unittest -import apt_pkg + import os import copy - import sys + sys.path.insert(0, "../") +import apt_pkg import aptsources import aptsources.sourceslist import aptsources.distro + class TestAptSources(unittest.TestCase): + def __init__(self, methodName): unittest.TestCase.__init__(self, methodName) apt_pkg.init() - apt_pkg.Config.Set("APT::Architecture","powerpc") - apt_pkg.Config.Set("Dir::Etc", os.path.join(os.getcwd(),"test-data-ports")) - apt_pkg.Config.Set("Dir::Etc::sourceparts","/xxx") + apt_pkg.Config.Set("APT::Architecture", "powerpc") + apt_pkg.Config.Set("Dir::Etc", os.path.abspath("test-data-ports")) + apt_pkg.Config.Set("Dir::Etc::sourceparts", "/xxx") def testMatcher(self): - apt_pkg.Config.Set("Dir::Etc::sourcelist","sources.list") + apt_pkg.Config.Set("Dir::Etc::sourcelist", "sources.list") sources = aptsources.sourceslist.SourcesList() - distro = aptsources.distro.get_distro("Ubuntu","hardy","desc","8.04") + distro = aptsources.distro.get_distro("Ubuntu", "hardy", "desc", + "8.04") distro.get_sources(sources) # test if all suits of the current distro were detected correctly dist_templates = set() diff --git a/tests/test_debextract.py b/tests/test_debextract.py index c080b26e..4ba498ae 100755 --- a/tests/test_debextract.py +++ b/tests/test_debextract.py @@ -1,13 +1,18 @@ #!/usr/bin/python +import sys import apt_inst -import sys -def Callback(What,Name,Link,Mode,UID,GID,Size,MTime,Major,Minor): + +def Callback(What, Name, Link, Mode, UID, GID, Size, MTime, Major, Minor): print "%s '%s','%s',%u,%u,%u,%u,%u,%u,%u" % ( - What,Name,Link,Mode,UID,GID,Size, MTime, Major, Minor) + What, Name, Link, Mode, UID, GID, Size, MTime, Major, Minor) + + +def main(): + member = "data.tar.lzma" + if len(sys.argv) > 2: + member = sys.argv[2] + apt_inst.debExtract(open(sys.argv[1]), Callback, member) -member = "data.tar.lzma" -if len(sys.argv) > 2: - member = sys.argv[2] -apt_inst.debExtract(open(sys.argv[1]), Callback, member) +main() -- cgit v1.2.3 From a6f8de9b03b83c4c733b04b85cc940f42757d353 Mon Sep 17 00:00:00 2001 From: Julian Andres Klode Date: Mon, 12 Jan 2009 17:56:14 +0100 Subject: doc/source/coding.rst: New python coding guidelines The exception for mixedCase names is now only granted for modules introduced prior to version 0.7.9 and changes thereto. Modules which are listed as deprecated in the documentation of Python 2.6 should be avoided. has_key() may only be used on TagSection objects. --- doc/source/coding.rst | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) (limited to 'doc/source') diff --git a/doc/source/coding.rst b/doc/source/coding.rst index 61c037ec..1357ce14 100644 --- a/doc/source/coding.rst +++ b/doc/source/coding.rst @@ -1,8 +1,7 @@ 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 - +included in python-apt. Then be sure to follow the following guidelines. Available branches ------------------- @@ -27,7 +26,7 @@ submit them. happens. VCS-Browser: http://bzr.debian.org/loggerhead/apt/python-apt/debian-sid/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 @@ -70,18 +69,28 @@ attributes, etc. Python Coding Style ------------------- -The coding style for the rest of the code is basically :PEP:`8`, with some exceptions: +The coding style for all code written in python is :PEP:`8`. For modules added +from version 0.7.9 on, there are no exceptions. + +Modules introduced prior to 0.7.9 use mixedCase names for methods, functions +and variables. These names will be replaced by names conforming to :PEP:`8` +in a future release of python-apt. -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`. +Therefore, try to reduce the introduction of the mixedName code to the absolute +minimum (sometimes you can also use shorter names). + +To prepare the port to Python 3.0, code should not use any functionality which +is deprecated as of Python 2.6. + +The has_key() functionality may be used only on TagSection objects; as they +provide no other way to do this. If someone is willing to adapt TagSection to +support ``key in mapping`` and ``iter(mapping)``, this would be great. .. 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.). - + fix all new **errors** they report (undefined names, etc.). Submitting your patch --------------------- @@ -124,7 +133,9 @@ patch, you may need to *merge* the branch instead. 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). + 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 @@ -154,3 +165,4 @@ package:: 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. -- cgit v1.2.3