merged from the debian-sid branch

3 files changed, 336 insertions, 7 deletions

diff --git a/doc/source/library/apt.package.rst b/doc/source/library/apt.package.rst
index 4b143b8a..01a26973 100644
--- a/doc/source/library/apt.package.rst
+++ b/doc/source/library/apt.package.rst
@@ -34,7 +34,7 @@ Dependency Information
 
     .. attribute:: relation
 
-        The relation (>>,>=,==,<<,<=,)
+        The relation (>,>=,==,<,<=,)
 
     .. attribute:: version
 
@@ -90,6 +90,35 @@ Origin Information
        it provides a GPG-signed Release file and the GPG-key used is in the
        keyring used by apt (see apt-key).
 
+
+
+The Record class
+-----------------
+.. autoclass:: Record
+    :members:
+
+    .. note::
+        .. versionchanged:: 0.7.100
+            This class is a subclass of :class:`collections.Mapping` when used
+            in Python 2.6 or newer.
+
+    .. describe:: record[name]
+
+        Return the value of the field with the name *name*.
+
+    .. describe:: name in record
+
+        Return whether a field *name* exists in record.
+
+    .. describe:: len(record)
+
+        The number of fields in the record
+
+    .. describe:: str(record)
+
+        Display the record as a string
+
+
 Examples
 ---------
 .. code-block:: python
diff --git a/doc/source/library/apt.progress.base.rst b/doc/source/library/apt.progress.base.rst
index 3fd2a7a0..22006f77 100644
--- a/doc/source/library/apt.progress.base.rst
+++ b/doc/source/library/apt.progress.base.rst
@@ -233,7 +233,7 @@ InstallProgress
     
         (Abstract) Called when a error is detected during the install.
 
-    The following method should be overriden to implement progress reporting
+    The following method should be overridden to implement progress reporting
     for dpkg-based runs i.e. calls to :meth:`run` with a filename:
 
     .. method:: processing(pkg, stage)
@@ -252,7 +252,7 @@ InstallProgress
         file (:file:`/var/lib/dpkg/status`) and documented
         in :manpage:`dpkg(1)`.
 
-    The following methods should be overriden to implement progress reporting
+    The following methods should be overridden to implement progress reporting
     for  :meth:`run` calls with an :class:`apt_pkg.PackageManager` object as
     their parameter:
 
@@ -274,7 +274,7 @@ InstallProgress
         This method is called when all changes have been applied.
 
     There are also several methods which are fully implemented and should not
-    be overriden by subclasses unless the subclass has very special needs:
+    be overridden by subclasses unless the subclass has very special needs:
 
     .. method:: fork() -> int
     
diff --git a/doc/source/library/apt_pkg.rst b/doc/source/library/apt_pkg.rst
index 3c9f8446..bba7491f 100644
--- a/doc/source/library/apt_pkg.rst
+++ b/doc/source/library/apt_pkg.rst
@@ -40,17 +40,43 @@ Working with the cache
     The constructor takes an optional argument which must be a subclass of
     :class:`apt.progress.base.OpProgress`. This object will then be used to
     display information during the cache opening process (or possible creation
-    of the cache).
+    of the cache). It may also be ``None``, in which case no progress will
+    be emitted. If not given, progress will be printed to standard output.
+
+    .. note::
+
+        The cache supports colon-separated name:architecture pairs. For
+        normal architectures, they are equal to a (name, architecture)
+        tuple. For the the "any" architecture behavior is different, as
+        "name:any" is equivalent to ("name:any", "any"). This is done so
+        that "name:any" matches all packages with that name which have
+        Multi-Arch: allowed set.
 
     .. describe:: cache[pkgname]
 
         Return the :class:`Package()` object for the package name given by
-        *pkgname*.
+        *pkgname*. If *pkgname* includes a colon, the part after the colon
+        is used as the architecture.
+
+    .. describe:: cache[name, architecture]
+
+        Return the :class:`Package()` object for the package with the given
+        name and architecture.
+
+        .. versionadded: 0.8.0
 
     .. describe:: pkgname in cache
 
         Check whether a package with the name given by *pkgname* exists in
-        the cache.
+        the cache for the native architecture. If *pkgname* includes a
+        colon, the part after the colon is used as the architecture.
+
+    .. describe:: (name, architecture) in cache
+
+        Check whether a package with the given name and architecture exists
+        in the cache.
+
+        .. versionadded: 0.8.0
 
     .. method:: update(progress, sources [, pulse_interval]) -> bool
 
@@ -73,6 +99,44 @@ Working with the cache
 
         A list of all :class:`PackageFile` objects stored in the cache.
 
+    .. attribute:: group_count
+
+        The number of groups in the cache.
+
+        .. versionadded: 0.8.0
+
+    .. attribute:: groups
+
+        A sequence of :class:`Group` objects, implemented as a
+        :class:`GroupList` object.
+
+        .. versionadded: 0.8.0
+
+        .. class:: GroupList
+
+            A simple sequence-like object which only provides a length and
+            an implementation of ``__getitem__`` for accessing groups at
+            a certain index. Apart from being iterable, it can be used in
+            the following ways:
+
+            .. versionadded: 0.8.0
+
+            .. describe:: list[index]
+
+                Get the :class:`Group` object for the group at the position
+                given by *index* in the GroupList *list*.
+
+            .. describe:: len(list)
+
+                Return the length of the GroupList object *list*.
+
+
+    .. attribute:: is_multi_arch
+
+        An attribute determining whether the cache supports multi-arch.
+
+        .. versionadded: 0.8.0
+
     .. attribute:: package_count
 
         The total number of packages available in the cache. This value is
@@ -358,6 +422,158 @@ Installing with :class:`PackageManager`
 
         A constant for checking whether the the result of the call to
         :meth:`do_install` is 'incomplete'.
+        
+    All instances of this class also support the following methods:
+    
+    .. note::
+        
+        This methods are provided mainly for subclassing purposes
+        and should not be used in most programs. This class is a
+        subclass of an internal :class:`_PackageManager` which does
+        not provide that methods. As the public C++ API creates such
+        an object without those methods, you should not rely on those
+        methods to be available unless you used the constructor of
+        :class:`PackageManager` to create the object.
+    
+    .. method:: configure(pkg: Package) -> bool 
+
+        Notify the package manager that the :class:`Package` given
+        by *pkg* is to be configured. Must return a ``True`` value
+        or ``None`` to continue, or a value which is ``False`` if
+        evaluated as boolean to abort.
+        
+        .. versionadded:: 0.8.0
+
+    .. method:: install(pkg: Package, filename: str) -> bool 
+
+        Notify the package manager that the :class:`Package` given
+        by *pkg* is to be installed from the .deb located at
+        *filename*. Must return a ``True`` value or ``None`` to
+        continue, or a value which is ``False`` if evaluated as
+        boolean to abort.
+        
+        
+        .. versionadded:: 0.8.0
+
+    .. method:: remove(pkg: Package, purge: bool) -> bool 
+
+        Notify the package manager that the :class:`Package` given
+        by *pkg* is to be removed. If *purge* is ``True``, the package
+        shall be purged. Must return a ``True`` value or ``None`` to
+        continue, or a value which is ``False`` if evaluated as boolean
+        to abort.
+        
+        
+        .. versionadded:: 0.8.0
+ 
+    .. method:: go(status_fd: int) -> bool  
+        
+        Start dpkg, writing status information to the file descriptor
+        given by *status_fd*. Must return a ``True`` value or ``None`` to
+        continue, or a value which is ``False`` if evaluated as boolean
+        to abort.
+        
+        .. versionadded:: 0.8.0
+
+    .. method:: reset()
+
+        Reset the package manager for a new round.
+        
+        .. versionadded:: 0.8.0
+
+        
+Installation ordering with :class:`OrderList`
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: OrderList(depcache: DepCache)
+
+	Represent a :ctype:`pkgOrderList`, used for installation
+	ordering. This class provides several methods and attributes,
+	is complicated and should not be used by normal programs.
+	
+	.. versionadded:: 0.8.0
+	
+	This class is a sequence and supports the following operations:
+	
+	.. describe:: list[index]
+	
+		Get the package at the given index in the list. Negative
+		index is supported.
+		
+	.. describe:: len(list)
+	
+		The length of the list.
+		
+	It also supports the append() method from :class:`list`:
+	
+	.. method:: append(pkg: Package)
+	
+		Append a new package to the end of the list. Please note that
+		you may not append a package twice, as only as much packages
+		as in the cache can be added.
+		
+	The class also defines several specific attributes and methods,
+	to be described hereinafter.
+		
+	.. method:: score(pkg: Package)
+	
+		Return the score of the package. Packages are basically
+		ordered by descending score.
+		
+	This class allows flags to be set on packages. Those flags are:
+	
+	.. attribute:: FLAG_ADDED
+	.. attribute:: FLAG_ADD_PENDING
+	.. attribute:: FLAG_IMMEDIATE
+	.. attribute:: FLAG_LOOP
+	.. attribute:: FLAG_UNPACKED
+	.. attribute:: FLAG_CONFIGURED
+	.. attribute:: FLAG_REMOVED
+	.. attribute:: FLAG_STATES_MASK
+	
+		Same as ``FLAG_UNPACKED | FLAG_CONFIGURED | FLAG_REMOVED``
+		
+	.. attribute:: FLAG_IN_LIST
+	.. attribute:: FLAG_AFTER
+	
+	The methods to work with those flags are:
+		
+	.. method:: flag(pkg: Package, flag: int[, unset_flags: int])
+
+		Flag a package. Sets the flags given in *flag* and unsets
+		any flags given in *unset_flags*.
+		
+	.. method:: is_flag(pkg: Package, flag: int)
+	
+		Check whether the flags in *flag* are set for the package.
+		
+	.. method:: wipe_flags(flags: int)
+	
+		Remove the flags in *flags* from all packages.
+	
+	.. method:: is_missing(pkg: Package)
+
+		Check if the package is missing (not really usable right now)
+
+	.. method:: is_now(pkg: Package)
+
+		Check if the package is flagged for any state but removal.
+		
+	The following methods for ordering are provided:
+	
+	.. method:: order_critical()
+	
+		Order the packages for critical unpacking; that is, only
+		respect pre-dependencies.
+	
+	.. method:: order_unpack()
+	
+		Order the packages for unpacking, repecting Pre-Depends and
+		Conflicts.
+	
+	.. method:: order_configure()
+	
+		Order the packages for configuration, respecting Depends.
 
 Improve performance with :class:`ActionGroup`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -432,6 +648,47 @@ Resolving Dependencies with :class:`ProblemResolver`
 
         Try to resolve the problems without installing or removing packages.
 
+:class:`Group` of packages with the same name
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. class:: Group(cache: Cache, name: str)
+
+    .. versionadded:: 0.8.0
+
+    A collection of packages in which all packages have the same name. Groups
+    are used in multi-arch environments, where two or more packages have the
+    same name, but different architectures.
+
+    Group objects provide the following parts for sequential access:
+
+    .. describe:: group[index]
+
+        Get the package at the given **index** in the group.
+
+        .. note::
+            Groups are internally implemented using a linked list. The object
+            keeps a pointer to the current object and the first object, so
+            access to the first element, or accesses in order have a
+            complexity of O(1). Random-access complexity is ranges from
+            O(1) to O(n).
+
+    Group objects also provide special methods to find single packages:
+
+    .. method:: find_package(architecture: str) -> Package
+
+        Find a package with the groups name and the architecture given
+        in the argument *architecture*. If no such package exists, return
+        ``None``.
+
+    .. method:: find_preferred_package(prefer_nonvirtual: bool = True) -> Package
+
+        Find the preferred package. This is the package of the native
+        architecture (specified in ``APT::Architecture``) if available,
+        or the package from the first foreign architecture. If no package
+        could be found, return ``None``
+
+        If **prefer_nonvirtual** is ``True``, the preferred package
+        will be a non-virtual package, if one exists.
+        
 
 :class:`Package` information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -653,6 +910,49 @@ Example:
     .. attribute:: installed_size
 
         The size of the package (in kilobytes), when unpacked on the disk.
+        
+    .. attribute:: multi_arch
+    
+		The multi-arch state of the package. Can be one of the following
+		attributes.
+		
+			.. attribute:: MULTI_ARCH_NONE
+			
+				No multi-arch
+				
+			.. attribute:: MULTI_ARCH_ALL
+			
+				An ``Architecture: all`` package
+				
+			
+			.. attribute:: MULTI_ARCH_FOREIGN
+			
+				Can satisfy dependencies of foreign-architecture
+				packages
+				
+			.. attribute:: MULTI_ARCH_ALL_FOREIGN
+			
+				:attr:`MULTI_ARCH_FOREIGN` for ``Architecture: all``
+				packages.
+				
+			.. attribute:: MULTI_ARCH_SAME
+			
+				Multiple versions from different architectures may be
+				installed in parallel, but may only satisfy dependencies
+				of packages from the same architecture
+				
+			.. attribute:: MULTI_ARCH_ALLOWED
+			
+				Installation in parallel and satisfying ``pkg:any``
+				style dependencies is allowed.
+				
+			.. attribute:: MULTI_ARCH_ALL_ALLOWED
+			
+				:attr:`MULTI_ARCH_ALLOWED` for ``Architecture: all``
+				packages.
+				
+				
+			
 
     .. attribute:: parent_pkg