diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/source/apt/index.rst | 2 | ||||
| -rw-r--r-- | doc/source/apt_pkg.rst (renamed from doc/source/apt_pkg/cache.rst) | 1333 | ||||
| -rw-r--r-- | doc/source/apt_pkg/index.rst | 530 | ||||
| -rw-r--r-- | doc/source/index.rst | 22 | ||||
| -rw-r--r-- | doc/source/whatsnew/0.8.0.rst | 33 | ||||
| -rw-r--r-- | doc/source/whatsnew/index.rst | 9 |
6 files changed, 968 insertions, 961 deletions
diff --git a/doc/source/apt/index.rst b/doc/source/apt/index.rst index 5047a0fd..9cd6ef45 100644 --- a/doc/source/apt/index.rst +++ b/doc/source/apt/index.rst @@ -11,8 +11,6 @@ with an easy-to-use interface. functions provided as deprecated ones. .. automodule:: apt - :members: - diff --git a/doc/source/apt_pkg/cache.rst b/doc/source/apt_pkg.rst index a58f1356..8c602f37 100644 --- a/doc/source/apt_pkg/cache.rst +++ b/doc/source/apt_pkg.rst @@ -1,279 +1,382 @@ -Classes in apt_pkg -================== +:mod:`apt_pkg` --- The low-level bindings for apt-pkg +===================================================== +.. module:: apt_pkg -.. todo:: +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. - This should be split and cleaned up a bit. -:class:`Acquire` ----------------- -.. class:: Acquire +Module Initialization +--------------------- - .. method:: Run() +Initialization is needed for most functions, but not for all of them. Some can +be called without having run init*(), but will not return the expected value. - Fetch all the items which have been added by - :func:`apt_pkg.GetPkgAcqFile`. +.. function:: initConfig - .. method:: Shutdown + Initialize the configuration of apt. This is needed for most operations. - Shut the fetcher down. +.. function:: initSystem -:class:`PkgAcqFile` -------------------- -.. class:: PkgAcqFile + Initialize the system. - This class provides no methods or attributes +.. function:: init -:class:`AcquireItem` ---------------------- + Deprecated function. Use initConfig() and initSystem() instead. -.. class:: AcquireItem +Working with the cache +---------------------- +.. class:: Cache([progress]) - .. attribute:: ID + Return a :class:`Cache()` object. The optional parameter *progress* + specifies an instance of :class:`apt.progress.OpProgress()` which will + display the open progress. - The ID of the item. + .. describe:: cache[pkgname] - .. attribute:: Complete + Return the :class:`Package()` object for the package name given by + *pkgname*. - Is the item completely acquired? + .. method:: Close() - .. attribute:: Local + Close the package cache. - Is the item a local file? + .. method:: Open([progress]) - .. attribute:: IsTrusted + Open the package cache again. The parameter *progress* may be set to + an :class:`apt.progress.OpProgress()` object or `None`. - Can the file be trusted? + .. method:: Update(progress, list) - .. attribute:: FileSize + Update the package cache. - The size of the file, in bytes. + The parameter *progress* points to an :class:`apt.progress.FetchProgress()` + object. The parameter *list* refers to a :class:`SourceList()` object. - .. attribute:: ErrorText + .. attribute:: DependsCount - The error message. For example, when a file does not exist on a http - server, this will contain a 404 error message. + The total number of dependencies. - .. attribute:: DestFile + .. attribute:: PackageCount - The location the file is saved as. + The total number of packages available in the cache. - .. attribute:: DescURI + .. attribute:: ProvidesCount - The source location. + The number of provided packages. - **Status**: + .. attribute:: VerFileCount - .. attribute:: Status + .. todo:: Seems to be some mixture of versions and pkgFile. - Integer, representing the status of the item. + .. attribute:: VersionCount - .. attribute:: StatIdle + The total number of package versions available in the cache. - Constant for comparing :attr:`AcquireItem.Status`. + .. attribute:: PackageFileCount - .. attribute:: StatFetching + 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`. - Constant for comparing :attr:`AcquireItem.Status` + .. attribute:: FileList - .. attribute:: StatDone + A list of :class:`PackageFile` objects. - Constant for comparing :attr:`AcquireItem.Status` +.. class:: DepCache(cache) - .. attribute:: StatError + Return a :class:`DepCache` object. The parameter *cache* specifies an + instance of :class:`Cache`. - Constant for comparing :attr:`AcquireItem.Status` + The DepCache object contains various methods to manipulate the cache, + to install packages, to remove them, and much more. - .. attribute:: StatAuthError + .. method:: Commit(fprogress, iprogress) - Constant for comparing :attr:`AcquireItem.Status` + Apply all the changes made. -:class:`ActionGroup` --------------------- + The parameter *fprogress* has to be set to an instance of + apt.progress.FetchProgress or one of its subclasses. -.. class:: ActionGroup + The parameter *iprogress* has to be set to an instance of + apt.progress.InstallProgress or one of its subclasses. - 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). + .. method:: FixBroken() - Using ActionGroups you can turn this off and therefore make your code - much faster. + Try to fix all broken packages in the cache. - Initialize it using :func:`apt_pkg.GetPkgActionGroup`, eg:: + .. method:: GetCandidateVer(pkg) - apt_pkg.GetPkgActionGroup(depcache) + Return the candidate version of the package, ie. the version that + would be installed normally. - .. method:: release + The parameter *pkg* refers to an :class:`Package` object, + available using the :class:`pkgCache`. - Release the ActionGroup. This will reactive the collection of package - garbage. + This method returns a :class:`Version` object. + .. method:: SetCandidateVer(pkg, version) -:class:`Configuration` ----------------------- + The opposite of :meth:`pkgDepCache.GetCandidateVer`. Set the candidate + version of the :class:`Package` *pkg* to the :class:`Version` + *version*. -.. class:: Configuration - The Configuration objects store the configuration of apt. + .. method:: Upgrade([distUpgrade=False]) - .. describe:: key in conf + 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. - Return ``True`` if *conf* has a key *key*, else ``False``. + To perform a dist-upgrade, the optional parameter *distUpgrade* has + to be set to True. - .. versionadded:: 0.8.0 + .. method:: FixBroken() - .. describe:: conf[key] + Fix broken packages. - Return the value of the option given key *key*. If it does not - exist, raise :exc:`KeyError`. + .. method:: ReadPinFile() - .. describe:: conf[key] = value + Read the policy, eg. /etc/apt/preferences. - Set the option at *key* to *value*. + .. method:: MinimizeUpgrade() - .. method:: Find(key[, default='']) + 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. - Return the value for the given key *key*. This is the same as - :meth:`Configuration.get`. + .. todo:: + Explain better.. - If *key* does not exist, return *default*. + .. method:: MarkKeep(pkg) - .. method:: FindFile(key[, default='']) + Mark the :class:`Package` *pkg* for keep. - Return the filename hold by the configuration at *key*. This formats the - filename correctly and supports the Dir:: stuff in the configuration. + .. method:: MarkDelete(pkg[, purge]) - If *key* does not exist, return *default*. + Mark the :class:`Package` *pkg* for delete. If *purge* is True, + the configuration files will be removed as well. - .. method:: FindDir(key[, default='/']) + .. method:: MarkInstall(pkg[, autoInst=True[, fromUser=True]]) - Return the absolute path to the directory specified in *key*. A - trailing slash is appended. + Mark the :class:`Package` *pkg* for install. - If *key* does not exist, return *default*. + If *autoInst* is ``True``, the dependencies of the package will be + installed as well. This is the default. - .. method:: FindI(key[, default=0]) + If *fromUser* is ``True``, the package will be marked as manually + installed. This is the default. - Return the integer value stored at *key*. + .. method:: SetReinstall(pkg) - If *key* does not exist, return *default*. + Set if the :class:`Package` *pkg* should be reinstalled. - .. method:: FindB(key[, default=0]) + .. method:: IsUpgradable(pkg) - Return the boolean value stored at *key*. This returns an integer, but - it should be treated like True/False. + Return ``1`` if the package is upgradable. - If *key* does not exist, return *default*. + The package can be upgraded by calling :meth:`pkgDepCache.MarkInstall`. - .. method:: Set(key, value) + .. method:: IsNowBroken(pkg) - Set the value of *key* to *value*. + Return `1` if the package is broken now (including changes made, but + not committed). - .. method:: Exists(key) + .. method:: IsInstBroken(pkg) - Check whether the key *key* exists in the configuration. + Return ``1`` if the package is broken on the current install. This + takes changes which have not been committed not into effect. - .. method:: SubTree(key) + .. method:: IsGarbage(pkg) - Return a sub tree starting at *key*. The resulting object can be used - like this one. + Return ``1`` if the package is garbage, ie. if it is automatically + installed and no longer referenced by other packages. - .. method:: List([key]) + .. method:: IsAutoInstalled(pkg) - List all items at *key*. Normally, return the keys at the top level, - eg. APT, Dir, etc. + Return ``1`` if the package is automatically installed (eg. as the + dependency of another package). - Use *key* to specify a key of which the childs will be returned. + .. method:: MarkedInstall(pkg) - .. method:: ValueList([key]) + Return ``1`` if the package is marked for install. - Same as :meth:`Configuration.List`, but this time for the values. + .. method:: MarkedUpgrade(pkg) - .. method:: MyTag() + Return ``1`` if the package is marked for upgrade. - 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:: MarkedDelete(pkg) - .. method:: Clear(key) + Return ``1`` if the package is marked for delete. - Clear the configuration. Remove all values and keys at *key*. + .. method:: MarkedKeep(pkg) - .. method:: keys([key]) + Return ``1`` if the package is marked for keep. - Return all the keys, recursive. If *key* is specified, ... (FIXME) + .. method:: MarkedReinstall(pkg) - .. method:: has_key(key) + Return ``1`` if the package should be installed. - Return whether the configuration contains the key *key*. + .. method:: MarkedDowngrade(pkg) - .. deprecated:: 0.8.0 + Return ``1`` if the package should be downgraded. - .. method:: get(key[, default='']) + .. attribute:: KeepCount - This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`, - it returns the value of key or if it does not exist, *default*. + Integer, number of packages marked as keep + .. attribute:: InstCount -:class:`pkgCache` ------------------ -.. class:: pkgCache + Integer, number of packages marked for installation. - The :class:`pkgCache` class prov + .. attribute:: DelCount - .. describe:: cache[pkgname] + Number of packages which should be removed. - Return the :class:`Package()` object for the package name given by - *pkgname*. + .. attribute:: BrokenCount - .. method:: Close() + Number of packages which are broken. - Close the package cache. + .. attribute:: UsrSize - .. method:: Open([progress]) + The size required for the changes on the filesystem. If you install + packages, this is positive, if you remove them its negative. - Open the package cache again. The parameter *progress* may be set to - an :class:`apt.progress.OpProgress()` object or `None`. + .. attribute:: DebSize - .. method:: Update(progress, list) + The size of the packages which are needed for the changes to be + applied. - Update the package cache. - The parameter *progress* points to an :class:`apt.progress.FetchProgress()` - object. +.. class:: PackageManager(depcache) - The parameter *list* refers to an object as returned by - :func:`apt_pkg.GetPkgSourceList`. + Return a new :class:`PackageManager` object. The parameter *depcache* + specifies a :class:`DepCache` object. - .. attribute:: DependsCount + :class:`PackageManager` objects provide several methods and attributes, + which will be listed here: - The total number of dependencies. + .. method:: GetArchives(fetcher, list, records) - .. attribute:: PackageCount + Add all the selected packages to the :class:`Acquire()` object + *fetcher*. - The total number of packages available in the cache. + The parameter *list* refers to a :class:`SourceList()` object. - .. attribute:: ProvidesCount + The parameter *records* refers to a :class:`PackageRecords()` object. - The number of provided packages. + .. method:: DoInstall() - .. attribute:: VerFileCount + Install the packages. - .. todo:: Seems to be some mixture of versions and pkgFile. + .. method:: FixMissing - .. attribute:: VersionCount + Fix the installation if a package could not be downloaded. - The total number of package versions available in the cache. + .. attribute:: ResultCompleted - .. attribute:: PackageFileCount + A constant for checking whether the the result is 'completed'. - 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`. + Compare it against the return value of :meth:`PkgManager.GetArchives` + or :meth:`PkgManager.DoInstall`. - .. attribute:: FileList + .. attribute:: ResultFailed - A list of :class:`PackageFile` objects. + 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`. + +Improve performance with :class:`ActionGroup` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. class:: ActionGroup(depcache) + + Create a new :class:`ActionGroup()` object for the :class:`DepCache` object + given by the parameter *depcache*. + + :class:`ActionGroup()` objects make operations on the cache faster by + delaying certain cleanup operations until the action group is released. + + ActionGroup is also a context manager and therefore supports the + :keyword:`with` statement. But because it becomes active as soon as it + is created, you should not create an ActionGroup() object before entering + the with statement. + + If you want to use ActionGroup as a with statement (which is recommended + because it makes it easier to see when an actiongroup is active), always + use the following form:: + + with apt_pkg.ActionGroup(depcache): + ... + + For code which has to run on Python versions prior to 2.5, you can also + use the traditional way:: + + actiongroup = apt_pkg.ActionGroup(depcache) + ... + actiongroup.release() + + :class:`ActionGroup` provides the following method: + + .. method:: release() + + Release the ActionGroup. This will reactive the collection of package + garbage. + +Resolving Dependencies +^^^^^^^^^^^^^^^^^^^^^^ + +.. class:: ProblemResolver(depcache) + + Return a new :class:`ProblemResolver` object. The parameter *depcache* + specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`. + + 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. :class:`PackageFile` @@ -348,7 +451,7 @@ Classes in apt_pkg Example ^^^^^^^ -.. literalinclude:: ../examples/cache-pkgfile.py +.. literalinclude:: examples/cache-pkgfile.py :class:`Package` @@ -439,7 +542,7 @@ Example Example: ^^^^^^^^^ -.. literalinclude:: ../examples/cache-packages.py +.. literalinclude:: examples/cache-packages.py @@ -612,7 +715,7 @@ 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 +.. literalinclude:: examples/missing-deps.py :class:`Description` @@ -635,169 +738,6 @@ broken dependencies: -:class:`pkgDepCache` --------------------- -.. 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:`Package` object, - available using the :class:`pkgCache`. - - 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. - - :class:`MetaIndex` ------------------ @@ -843,64 +783,17 @@ broken dependencies: Whether we can trust the file. -:class:`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`. +Records +-------- -:class:`pkgRecords` --------------------- +.. class:: PackageRecords(cache) -.. class:: PkgRecords + Create a new :class:`PackageRecords` object, for the packages in the cache + specified by the parameter *cache*. Provide access to the packages records. This provides very useful attributes for fast (convient) access to some fields of the record. - See :func:`apt_pkg.GetPkgRecords` for initialization. - - .. method:: Lookup(verfile_iter) Change the actual package to the package given by the verfile_iter. @@ -980,10 +873,8 @@ broken dependencies: section = apt_pkg.ParseSection(records.Record) print section['SHA256'] -:class:`PkgSrcRecords` ----------------------- -.. class:: PkgSrcRecords +.. class:: SourceRecords This represents the entries in the Sources files, ie. the dsc files of the source packages. @@ -1100,82 +991,209 @@ broken dependencies: :func:`apt_pkg.ParseSrcDepends`. -:class:`PkgSourceList` ------------------------ -.. class:: PkgSourceList +The Acquire interface +---------------------- +The Acquire Interface is responsible for all sorts of downloading in apt. All +packages, index files, etc. downloading is done using the Acquire functionality. - This is for :file:`/etc/apt/sources.list`. +The :mod:`apt_pkg` module provides a subset of this functionality which allows +you to implement file downloading in your applications. Together with the +:class:`PackageManager` class you can also fetch all the packages marked for +installation. - .. method:: FindIndex(pkgfile) - Return a :class:`PackageIndexFile` object for the :class:`PackageFile` - *pkgfile*. +.. class:: Acquire([progress]) - .. method:: ReadMainList + Return an :class:`Acquire` object. The parameter *progress* refers to + an :class:`apt.progress.FetchProgress()` object. - Read the main list. + Acquire objects maintaing a list of items which will be fetched or have + been fetched already during the lifetime of this object. To add new items + to this list, you can create new :class:`AcquireFile` objects which allow + you to add single files. - .. method:: GetIndexes(acq[, all]) + Acquire items have multiple methods: - Add the index files to the :class:`Acquire()` object *acq*. If *all* is - given and ``True``, all files are fetched. + .. method:: Acquire.Run() + Fetch all the items which have been added by :func:`GetPkgAcqFile`. -:class:`ProblemResolver` ------------------------- -.. class:: ProblemResolver + .. method:: Acquire.Shutdown() - The problem resolver helps when there are problems in the package - selection. An example is a package which conflicts with another, already - installed package. + Shut the fetcher down. - .. method:: Protect(pkg) + .. attribute:: Acquire.TotalNeeded - Protect the :class:`Package()` object given by the parameter *pkg*. + The total amount of bytes needed (including those of files which are + already present) - .. todo:: + .. attribute:: Acquire.FetchNeeded - Really document it. + The total amount of bytes which need to be fetched. - .. method:: InstallProtect() + .. attribute:: Acquire.PartialPresent - Protect all installed packages from being removed. + Whether some files have been acquired already. (???) - .. method:: Remove(pkg) +.. class:: AcquireItem - Remove the :class:`Package()` object given by the parameter *pkg*. + The :class:`AcquireItem()` objects represent the items of a + :class:`Acquire` object. :class:`AcquireItem()` objects can not be created + by the user, they are solely available through the :attr:`Acquire.Items` + list of an :class:`Acquire` object. - .. todo:: + .. attribute:: ID - Really document it. + The ID of the item. - .. method:: Clear(pkg) + .. attribute:: Complete - Reset the :class:`Package()` *pkg* to the default state. + Is the item completely acquired? - .. todo:: + .. attribute:: Local - Really document it. + Is the item a local file? - .. method:: Resolve() + .. attribute:: IsTrusted - Try to resolve problems by installing and removing packages. + Can the file be trusted? - .. method:: ResolveByKeep() + .. attribute:: FileSize - Try to resolve problems only by using keep. + 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. -:class:`TagFile` ----------------- + .. 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` + + +.. class:: AcquireFile(owner, uri[, md5, size, descr, shortdescr, destdir, destfile]) + + Create a new :class:`AcquireFile()` object and register it with *acquire*, + so it will be fetched. AcquireFile objects provide no methods or attributes + and are completely useless at the moment. + + The parameter *owner* refers to an :class:`Acquire()` object as returned + by :func:`GetAcquire`. The file will be added to the Acquire queue + automatically. -.. class:: TagFile + 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. Instead of *destdir*, you can also specify the full path to + the file using the parameter *destfile*. You can not combine both. + + + + + + +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 (or a file descriptor), in which case the md5sum of its contents is + returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +.. function:: sha1sum(object) + + Return the sha1sum of the object. *object* may either be a string, in + which case the sha1sum of the string is returned, or a :class:`file()` + object (or a file descriptor), in which case the sha1sum of its contents + is returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +.. function:: sha256sum(object) + + Return the sha256sum of the object. *object* may either be a string, in + which case the sha256sum of the string is returned, or a :class:`file()` + object (or a file descriptor), in which case the sha256sum of its contents + is returned. + + .. versionchanged:: 0.8.0 + Added support for using file descriptors. + +Debian control files +-------------------- +Debian control files are files containing multiple stanzas of :RFC:`822`-style +header sections. They are widely used in the Debian community, and can represent +many kinds of information. One example for such a file is the +:file:`/var/lib/dpkg/status` file which contains a list of the currently +installed packages. + +The :mod:`apt_pkg` module provides two classes to read those files and parts +thereof and provides a function :func:`RewriteSection` which takes a +:class:`TagSection()` object and sorting information and outputs a sorted +section as a string. + +.. class:: TagFile(file) An object which represents a typical debian control file. Can be used for Packages, Sources, control, Release, etc. - Use :func:`apt_pkg.ParseTagFile` to parse a file. + An example for working with a TagFile could look like:: + + tagf = apt_pkg.TagFile(open('/var/lib/dpkg/status')) + tagf.Step() + print tagf.Section['Package'] .. method:: Step @@ -1195,10 +1213,7 @@ broken dependencies: This is the current :class:`TagSection()` instance. -:class:`TagSection` -------------------- - -.. class:: TagSection +.. class:: TagSection(text) Represent a single section of a debian control file. @@ -1241,3 +1256,485 @@ broken dependencies: .. method:: keys() Return a list of keys in the section. + +.. autofunction:: RewriteSection(section, order, rewrite_list) + +.. data:: RewritePackageOrder + + The order in which the information for binary packages should be rewritten, + i.e. the order in which the fields should appear. + +.. data:: RewriteSourceOrder + + The order in which the information for source packages should be rewritten, + i.e. the order in which the fields should appear. + +Dependencies +------------ +.. function:: CheckDep(pkgver, op, depver) + + Check that the dependency requirements consisting of op and depver can be + satisfied by the version pkgver. + + Example:: + + >>> bool(apt_pkg.CheckDep("1.0", ">=", "1")) + True + +.. function:: ParseDepends(depends) + + Parse the string *depends* which contains dependency information as + specified in Debian Policy, Section 7.1. + + Returns a list. The members of this list are lists themselves and contain + one or more tuples in the format ``(package,version,operation)`` for every + 'or'-option given, e.g.:: + + >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + +.. function:: ParseSrcDepends(depends) + + Parse the string *depends* which contains dependency information as + specified in Debian Policy, Section 7.1. + + Returns a list. The members of this list are lists themselves and contain + one or more tuples in the format ``(package,version,operation)`` for every + 'or'-option given, e.g.:: + + >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") + [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] + + + Furthemore, this function also supports to limit the architectures, as + used in e.g. Build-Depends:: + + >>> apt_pkg.ParseSrcDepends("a (>= 01) [i386 amd64]") + [[('a', '01', '>=')]] + + +Configuration +------------- + +.. class:: Configuration() + + Configuration() objects store the configuration of apt, mostly created from + the contents of :file:`/etc/apt.conf` and the files in + :file:`/etc/apt.conf.d`. + + .. describe:: key in conf + + Return ``True`` if *conf* has a key *key*, else ``False``. + + .. versionadded:: 0.8.0 + + .. describe:: conf[key] + + Return the value of the option given key *key*. If it does not + exist, raise :exc:`KeyError`. + + .. describe:: conf[key] = value + + Set the option at *key* to *value*. + + .. method:: Find(key[, default='']) + + Return the value for the given key *key*. This is the same as + :meth:`Configuration.get`. + + If *key* does not exist, return *default*. + + .. method:: 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 key *key* exists in the configuration. + + .. method:: SubTree(key) + + Return a sub tree starting at *key*. The resulting object can be used + like this one. + + .. method:: List([key]) + + List all items at *key*. Normally, return the keys at the top level, + eg. APT, Dir, etc. + + Use *key* to specify a key of which the childs will be returned. + + .. method:: 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*. + + .. deprecated:: 0.8.0 + + .. method:: get(key[, default='']) + + This behaves just like :meth:`dict.get` and :meth:`Configuration.Find`, + it returns the value of key or if it does not exist, *default*. + +.. class:: ConfigurationPtr + + Behaves like a :class:`Configuration()` objects, but uses a pointer to the + underlying C++ object. This is used for the default configuration in the + :data:`Config` attribute of the module. + +.. class:: ConfigurationSub + + Behaves like a :class:`Configuration()` objects, but provides access to + a subsection of another Configuration-like object. This type of object is + returned by the :meth:`Configuration.SubTree()` method. + +.. data:: Config + + A :class:`ConfigurationPtr()` object with the default configuration. This + object is initialized by calling :func:`InitConfig`. + + +Modifying +^^^^^^^^^ + + +.. function:: ReadConfigFile(configuration, filename) + + Read the configuration file specified by the parameter *filename* and add + the settings therein to the :class:`Configuration()` object specified by + the parameter *configuration* + +.. function:: ReadConfigDir(configuration, dirname) + + Read configuration files in the directory specified by the parameter + *dirname* and add the settings therein to the :class:`Configuration()` + object specified by the parameter *configuration*. + +.. function:: ReadConfigFileISC(configuration, filename) + + Read the configuration file specified by the parameter *filename* and add + the settings therein to the :class:`Configuration()` object specified by + the parameter *configuration* + +.. function:: ParseCommandLine(configuration,options,argv) + + This function is like getopt except it manipulates a configuration space. + output is a list of non-option arguments (filenames, etc). *options* is a + list of tuples of the form ``(‘c’,”long-opt or None”, + ”Configuration::Variable”,”optional type”)``. + + Where ``type`` may be one of HasArg, IntLevel, Boolean, InvBoolean, + ConfigFile, or ArbItem. The default is Boolean. + +Locking +-------- + +.. function:: GetLock(filename) + + Create an empty file at the path specified by the parameter *filename* and + lock it. + + While the file is locked by a process, calling this function in another + process returns ``-1``. + + When the lock is not required anymore, the file descriptor should be closed + using :func:`os.close`. + +.. function:: PkgSystemLock() + + Lock the global pkgsystem. + +.. function:: PkgSystemUnLock() + + Unlock the global pkgsystem. + +Other classes +-------------- +.. class:: Cdrom() + + Return a Cdrom object with the following methods: + + .. method:: Ident(progress) + + Identify the cdrom. The parameter *progress* refers to an + :class:`apt.progress.CdromProgress()` object. + + .. method:: Add(progress) + + Add the cdrom to the sources.list file. The parameter *progress* + refers to an :class:`apt.progress.CdromProgress()` object. + +.. class:: SourceList + + This is for :file:`/etc/apt/sources.list`. + + .. method:: FindIndex(pkgfile) + + Return a :class:`PackageIndexFile` object for the :class:`PackageFile` + *pkgfile*. + + .. method:: ReadMainList + + 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. + +String functions +---------------- +.. function:: Base64Encode(string) + + Encode the given string using base64, e.g:: + + >>> apt_pkg.Base64Encode(u"A") + 'QQ==' + + +.. function:: CheckDomainList(host, list) + + See if Host is in a ',' seperated list, e.g.:: + + apt_pkg.CheckDomainList("alioth.debian.org","debian.net,debian.org") + +.. function:: DeQuoteString(string) + + Dequote the string specified by the parameter *string*, e.g.:: + + >>> apt_pkg.DeQuoteString("%61%70%74%20is%20cool") + 'apt is cool' + +.. function:: QuoteString(string, repl) + + For every character listed in the string *repl*, replace all occurences in + the string *string* with the correct HTTP encoded value: + + >>> apt_pkg.QuoteString("apt is cool","apt") + '%61%70%74%20is%20cool' + +.. function:: SizeToStr(size) + + Return a string presenting the human-readable version of the integer + *size*. When calculating the units (k,M,G,etc.) the size is divided by the + factor 1000. + + Example:: + + >>> apt_pkg.SizeToStr(10000) + '10.0k' + +.. function:: StringToBool(input) + + Parse the string *input* and return one of **-1**, **0**, **1**. + + .. table:: Return values + + ===== ============================================= + Value Meaning + ===== ============================================= + -1 The string *input* is not recognized. + 0 The string *input* evaluates to **False**. + +1 The string *input* evaluates to **True**. + ===== ============================================= + + Example:: + + >>> apt_pkg.StringToBool("yes") + 1 + >>> apt_pkg.StringToBool("no") + 0 + >>> apt_pkg.StringToBool("not-recognized") + -1 + +.. function:: StrToTime(rfc_time) + + Convert the :rfc:`1123` conforming string *rfc_time* to the unix time, and + return the integer. This is the opposite of :func:`TimeRFC1123`. + + Example:: + + >> apt_pkg.StrToTime('Thu, 01 Jan 1970 00:00:00 GMT') + 0 + +.. function:: TimeRFC1123(seconds) + + Format the unix time specified by the integer *seconds*, according to the + requirements of :rfc:`1123`. + + Example:: + + >>> apt_pkg.TimeRFC1123(0) + 'Thu, 01 Jan 1970 00:00:00 GMT' + + +.. function:: TimeToStr(seconds) + + Format a given duration in a human-readable manner. The parameter *seconds* + refers to a number of seconds, given as an integer. The return value is a + string with a unit like 's' for seconds. + + Example:: + + >>> apt_pkg.TimeToStr(3601) + '1h0min1s' + +.. function:: UpstreamVersion(version) + + Return the string *version*, eliminating everything following the last + '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``. + +.. function:: URItoFileName(uri) + + Take a string *uri* as parameter and return a filename which can be used to + store the file, based on the URI. + + Example:: + + >>> apt_pkg.URItoFileName('http://debian.org/index.html') + 'debian.org_index.html' + + +.. function:: VersionCompare(a, b) + + Compare two versions, *a* and *b*, and return an integer value which has + the same characteristic as the built-in :func:`cmp` function. + + .. table:: Return values + + ===== ============================================= + Value Meaning + ===== ============================================= + > 0 The version *a* is greater than version *b*. + = 0 Both versions are equal. + < 0 The version *a* is less than version *b*. + ===== ============================================= + + + + +Module Constants +---------------- +.. _CurStates: + +Package States +^^^^^^^^^^^^^^^ +.. data:: 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 + +.. _InstStates: + +Installed states +^^^^^^^^^^^^^^^^ +.. data:: InstStateHold +.. data:: InstStateHoldReInstReq +.. data:: InstStateOk +.. data:: InstStateReInstReq + +.. _Priorities: + +Priorities +^^^^^^^^^^^ +.. data:: PriExtra +.. data:: PriImportant +.. data:: PriOptional +.. data:: PriRequired +.. data:: PriStandard + + +.. _SelStates: + +Select states +^^^^^^^^^^^^^ +.. data:: SelStateDeInstall +.. data:: SelStateHold +.. data:: SelStateInstall +.. data:: SelStatePurge +.. data:: SelStateUnknown + + +Build information +^^^^^^^^^^^^^^^^^ +.. data:: Date + + The date on which this extension has been compiled. + +.. data:: LibVersion + + The version of the apt_pkg library. This is **not** the version of apt, + nor the version of python-apt. + +.. data:: Time + + The time this extension has been built. + +.. data:: Version + + The version of apt (not of python-apt). + +.. data:: _COMPAT_0_7 + + A more or less internal variable defining whether this build provides an + API which is compatible to the one of python-apt 0.7. This is used in the + apt and aptsources packages to decide whether compatibility should be + enabled or not. diff --git a/doc/source/apt_pkg/index.rst b/doc/source/apt_pkg/index.rst deleted file mode 100644 index 47923c23..00000000 --- a/doc/source/apt_pkg/index.rst +++ /dev/null @@ -1,530 +0,0 @@ -:mod:`apt_pkg` --- The low-level bindings for apt-pkg -===================================================== -.. module:: apt_pkg - -The apt_pkg extensions provides a more low-level way to work with apt. It can -do everything apt can, and is written in C++. It has been in python-apt since -the beginning. - - -.. toctree:: - :maxdepth: 2 - :glob: - - * - - -Module Initialization ---------------------- - -Initialization is needed for most functions, but not for all of them. Some can -be called without having run init*(), but will not return the expected value. - -.. function:: 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. - -.. function:: GetPackageManager(depcache) - - Return a new :class:`PkgManager` object. The parameter *depcache* specifies - a :class:`pkgDepCache` object as returned by :func:`GetDepCache`. - -.. function:: GetPkgActionGroup(depcache) - - Return a new :class:`ActionGroup` object. The parameter *depcache* - specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`. - -.. function:: GetPkgProblemResolver(depcache) - - Return a new :class:`ProblemResolver` object. The parameter *depcache* - specifies a :class:`pkgDepCache` object as returned by :func:`GetDepCache`. - -.. function:: GetPkgRecords(cache) - - Return a new :class:`PkgRecords` object. - - The parameter *cache* refers to an :class:`pkgCache` object, as returned - by :func:`GetCache`. - -.. function:: GetPkgSrcRecords() - - Return a new :class:`PkgSrcRecords` 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. - - .. 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]) - - Create a new :class:`PkgAcqFile()` object and register it with *acquire*, - so it will be fetched. - - 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. Instead of *destDir*, you can also specify the full path to - the file using the parameter *destFile*. You can not combine both. - - - -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 (or a file descriptor), in which case the md5sum of its contents is - returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -.. function:: sha1sum(object) - - Return the sha1sum of the object. *object* may either be a string, in - which case the sha1sum of the string is returned, or a :class:`file()` - object (or a file descriptor), in which case the sha1sum of its contents - is returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -.. function:: sha256sum(object) - - Return the sha256sum of the object. *object* may either be a string, in - which case the sha256sum of the string is returned, or a :class:`file()` - object (or a file descriptor), in which case the sha256sum of its contents - is returned. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -Debian control files --------------------- -.. function:: ParseSection(text) - - Parse the string given in the parameter *text* and return a - :class:`TagSection` object. - -.. function:: ParseTagFile(file) - - Parse the given *file* and return a :class:`TagFile()` object. *file* may - be a :class:`file()` object, a file descriptor, or anything providing a - :meth:`fileno()` method. - - .. versionchanged:: 0.8.0 - Added support for using file descriptors. - -.. autofunction:: RewriteSection(section, order, rewrite_list) - -.. data:: RewritePackageOrder - - The order in which the information for binary packages should be rewritten, - i.e. the order in which the fields should appear. - -.. data:: RewriteSourceOrder - - The order in which the information for source packages should be rewritten, - i.e. the order in which the fields should appear. - -Dependencies ------------- -.. function:: CheckDep(pkgver, op, depver) - - Check that the dependency requirements consisting of op and depver can be - satisfied by the version pkgver. - - Example:: - - >>> bool(apt_pkg.CheckDep("1.0", ">=", "1")) - True - -.. function:: ParseDepends(depends) - - Parse the string *depends* which contains dependency information as - specified in Debian Policy, Section 7.1. - - Returns a list. The members of this list are lists themselves and contain - one or more tuples in the format ``(package,version,operation)`` for every - 'or'-option given, e.g.:: - - >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") - [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] - -.. function:: ParseSrcDepends(depends) - - Parse the string *depends* which contains dependency information as - specified in Debian Policy, Section 7.1. - - Returns a list. The members of this list are lists themselves and contain - one or more tuples in the format ``(package,version,operation)`` for every - 'or'-option given, e.g.:: - - >>> apt_pkg.ParseDepends("PkgA (>= VerA) | PkgB (>= VerB)") - [[('PkgA', 'VerA', '>='), ('PkgB', 'VerB', '>=')]] - - - Furthemore, this function also supports to limit the architectures, as - used in e.g. Build-Depends:: - - >>> apt_pkg.ParseSrcDepends("a (>= 01) [i386 amd64]") - [[('a', '01', '>=')]] - - -Configuration -------------- - -.. data:: Config - - A :class:`Configuration()`-like object with the default configuration. This - is implemented in the :class:`ConfigurationPtr` class, which has the same - API like the :class:`Configuration` class. - -.. function:: newConfiguration() - - Return a new :class:`Configuration` object. - -.. function:: ReadConfigFile(configuration, filename) - - Read the configuration file specified by the parameter *filename* and add - the settings therein to the :class:`Configuration()` object specified by - the parameter *configuration* - -.. function:: ReadConfigDir(configuration, dirname) - - Read configuration files in the directory specified by the parameter - *dirname* and add the settings therein to the :class:`Configuration()` - object specified by the parameter *configuration*. - -.. function:: ReadConfigFileISC(configuration, filename) - - Read the configuration file specified by the parameter *filename* and add - the settings therein to the :class:`Configuration()` object specified by - the parameter *configuration* - -.. function:: ParseCommandLine(configuration,options,argv) - - This function is like getopt except it manipulates a configuration space. - output is a list of non-option arguments (filenames, etc). *options* is a - list of tuples of the form ``(‘c’,”long-opt or None”, - ”Configuration::Variable”,”optional type”)``. - - Where ``type`` may be one of HasArg, IntLevel, Boolean, InvBoolean, - ConfigFile, or ArbItem. The default is Boolean. - -Locking --------- - -.. function:: GetLock(filename) - - Create an empty file at the path specified by the parameter *filename* and - lock it. - - While the file is locked by a process, calling this function in another - process returns ``-1``. - - When the lock is not required anymore, the file descriptor should be closed - using :func:`os.close`. - -.. function:: PkgSystemLock() - - Lock the global pkgsystem. - -.. function:: PkgSystemUnLock() - - Unlock the global pkgsystem. - -Other functions ----------------- -.. function:: Base64Encode(string) - - Encode the given string using base64, e.g:: - - >>> apt_pkg.Base64Encode(u"A") - 'QQ==' - - -.. function:: CheckDomainList(host, list) - - See if Host is in a ',' seperated list, e.g.:: - - apt_pkg.CheckDomainList("alioth.debian.org","debian.net,debian.org") - -.. function:: DeQuoteString(string) - - Dequote the string specified by the parameter *string*, e.g.:: - - >>> apt_pkg.DeQuoteString("%61%70%74%20is%20cool") - 'apt is cool' - -.. function:: QuoteString(string, repl) - - For every character listed in the string *repl*, replace all occurences in - the string *string* with the correct HTTP encoded value: - - >>> apt_pkg.QuoteString("apt is cool","apt") - '%61%70%74%20is%20cool' - -.. function:: SizeToStr(size) - - Return a string presenting the human-readable version of the integer - *size*. When calculating the units (k,M,G,etc.) the size is divided by the - factor 1000. - - Example:: - - >>> apt_pkg.SizeToStr(10000) - '10.0k' - -.. function:: StringToBool(input) - - Parse the string *input* and return one of **-1**, **0**, **1**. - - .. table:: Return values - - ===== ============================================= - Value Meaning - ===== ============================================= - -1 The string *input* is not recognized. - 0 The string *input* evaluates to **False**. - +1 The string *input* evaluates to **True**. - ===== ============================================= - - Example:: - - >>> apt_pkg.StringToBool("yes") - 1 - >>> apt_pkg.StringToBool("no") - 0 - >>> apt_pkg.StringToBool("not-recognized") - -1 - -.. function:: StrToTime(rfc_time) - - Convert the :rfc:`1123` conforming string *rfc_time* to the unix time, and - return the integer. This is the opposite of :func:`TimeRFC1123`. - - Example:: - - >> apt_pkg.StrToTime('Thu, 01 Jan 1970 00:00:00 GMT') - 0 - -.. function:: TimeRFC1123(seconds) - - Format the unix time specified by the integer *seconds*, according to the - requirements of :rfc:`1123`. - - Example:: - - >>> apt_pkg.TimeRFC1123(0) - 'Thu, 01 Jan 1970 00:00:00 GMT' - - -.. function:: TimeToStr(seconds) - - Format a given duration in a human-readable manner. The parameter *seconds* - refers to a number of seconds, given as an integer. The return value is a - string with a unit like 's' for seconds. - - Example:: - - >>> apt_pkg.TimeToStr(3601) - '1h0min1s' - -.. function:: UpstreamVersion(version) - - Return the string *version*, eliminating everything following the last - '-'. Thus, this should be equivalent to ``version.rsplit('-', 1)[0]``. - -.. function:: URItoFileName(uri) - - Take a string *uri* as parameter and return a filename which can be used to - store the file, based on the URI. - - Example:: - - >>> apt_pkg.URItoFileName('http://debian.org/index.html') - 'debian.org_index.html' - - -.. function:: VersionCompare(a, b) - - Compare two versions, *a* and *b*, and return an integer value which has - the same characteristic as the built-in :func:`cmp` function. - - .. table:: Return values - - ===== ============================================= - Value Meaning - ===== ============================================= - > 0 The version *a* is greater than version *b*. - = 0 Both versions are equal. - < 0 The version *a* is less than version *b*. - ===== ============================================= - - - - -.. _CurStates: - -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 - -.. _InstStates: - -Installed states ------------------ -.. data:: InstStateHold -.. data:: InstStateHoldReInstReq -.. data:: InstStateOk -.. data:: InstStateReInstReq - -.. _Priorities: - -Priorities ----------- -.. data:: PriExtra -.. data:: PriImportant -.. data:: PriOptional -.. data:: PriRequired -.. data:: PriStandard - - -.. _SelStates: - -Select states --------------- -.. data:: SelStateDeInstall -.. data:: SelStateHold -.. data:: SelStateInstall -.. data:: SelStatePurge -.. data:: SelStateUnknown - - -Build information ------------------ -.. data:: Date - - The date on which this extension has been compiled. - -.. data:: LibVersion - - The version of the apt_pkg library. This is **not** the version of apt, - nor the version of python-apt. - -.. data:: Time - - The time this extension has been built. - -.. data:: Version - - The version of apt (not of python-apt). diff --git a/doc/source/index.rst b/doc/source/index.rst index 930ff55c..2e05061a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,27 +1,27 @@ Welcome to python-apt's documentation! ====================================== -.. note:: +This is the official documentation for version |version| of the Python bindings +for Debian's famous APT package management. - This documentation can not be considered complete at the moment. But it - provides better documentation than the documentation available through - pydoc. +This documentation has been created by Sphinx, using reStructuredText files +written by Julian Andres Klode <jak@debian.org>, and in case of the apt +package, from the documentation shipped in the modules. -.. note:: +Contents: - This documentation has been created by Sphinx, using reStructuredText files - written by Julian Andres Klode <jak@debian.org>, and in case of the apt - package, from the documentation shipped in the modules. - +.. toctree:: + :hidden: -Contents: + whatsnew/index .. toctree:: :maxdepth: 2 + whatsnew/0.8.0 apt/index - apt_pkg/index + apt_pkg apt_inst aptsources/index contributing diff --git a/doc/source/whatsnew/0.8.0.rst b/doc/source/whatsnew/0.8.0.rst new file mode 100644 index 00000000..d1ac3ac5 --- /dev/null +++ b/doc/source/whatsnew/0.8.0.rst @@ -0,0 +1,33 @@ +What's New In python-apt 0.8 +============================ +Python-apt 0.8 is a new major release of the python bindings for the APT +package management libraries. It provides support for Python 3, new language +features and an API conforming to :PEP:`8`. + +Despite the many changes made in python-apt 0.8, the release still provides +backwards compatibility to the 0.7 series. This makes it possible to run your +old applications. Applications using the old API should be updated to the new +API, because the old one will be removed after some time. + +Support for Python 3 +-------------------- +Python-apt is the first Debian package to support the third major release of +Python. The port is straight forward and integrates as nicely in Python 3 as +the Python 2 builds integrate in Python 2. + +Real classes in :mod:`apt_pkg` +------------------------------ + +Complete rename of functions, methods and attributes +----------------------------------------------------- + +Supporting new language features like the :keyword:`with` statement +------------------------------------------------------------------- + +Other changes +------------- +This release of python-apt also features several other, smaller changes: + + * Reduced memory usage by creating Package() objects in apt.Cache() only + when needed. + * Support to set the candidate version in :class:`apt.package.Package` diff --git a/doc/source/whatsnew/index.rst b/doc/source/whatsnew/index.rst new file mode 100644 index 00000000..cc270a16 --- /dev/null +++ b/doc/source/whatsnew/index.rst @@ -0,0 +1,9 @@ +What's new in python-apt +======================== + +.. toctree:: + :maxdepth: 2 + :glob: + + * + |