apt_pkg: Add OrderList, wanted for mancoosi (Closes: #623485)

3 files changed, 123 insertions, 0 deletions

diff --git a/doc/source/c++/api.rst b/doc/source/c++/api.rst
index 25cfcd9e..63ed1599 100644
--- a/doc/source/c++/api.rst
+++ b/doc/source/c++/api.rst
@@ -622,6 +622,34 @@ IndexFile (pkgIndexFile)
     Return the :ctype:`pkgIndexFile` pointer contained in the Python object
     *object*.
 
+OrderList (pkgOrderList)
+---------------------------
+.. cvar:: PyTypeObject PyOrderList_Type
+
+    The type object for :class:`apt_pkg.OrderList` objects.
+
+.. cfunction:: int PyOrderList_Check(PyObject *object)
+
+    Check that the object *object* is an :class:`apt_pkg.OrderList` object, or
+    a subclass thereof.
+
+.. cfunction:: int PyOrderList_CheckExact(PyObject *object)
+
+    Check that the object *object* is an :class:`apt_pkg.OrderList` object
+    and no subclass thereof.
+
+.. cfunction:: PyObject* PyOrderList_FromCpp(pkgOrderList *cpp, bool delete, PyObject *owner)
+
+    Create a new :class:`apt_pkg.OrderList` object from the :ctype:`pkgOrderList`
+    pointer given by the parameter *cpp*. If the parameter *delete* is
+    true, the object pointed to by *cpp* will be deleted when the reference
+    count of the returned object reaches 0. The owner must be a
+    :class:`apt_pkg.DepCache` object.
+
+.. cfunction:: pkgOrderList* PyOrderList_ToCpp(PyObject *object)
+
+    Return the :ctype:`pkgOrderList` pointer contained in the Python object
+    *object*.
 
 PackageManager (pkgPackageManager)
 ----------------------------------
diff --git a/doc/source/library/apt_pkg.rst b/doc/source/library/apt_pkg.rst
index 28914395..fce4f804 100644
--- a/doc/source/library/apt_pkg.rst
+++ b/doc/source/library/apt_pkg.rst
@@ -422,6 +422,99 @@ Installing with :class:`PackageManager`
 
         A constant for checking whether the the result of the call to
         :meth:`do_install` is 'incomplete'.
+        
+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`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
diff --git a/doc/source/whatsnew/0.8.0.rst b/doc/source/whatsnew/0.8.0.rst
index fda53443..fa58a022 100644
--- a/doc/source/whatsnew/0.8.0.rst
+++ b/doc/source/whatsnew/0.8.0.rst
@@ -23,6 +23,8 @@ This release of python-apt also features several other, smaller changes:
 
     * apt_pkg.Cache() now takes None for the progress parameter, preventing
       progress reporting.
+    * A new class :class:`apt_pkg.OrderList` has been added on request
+      of the mancoosi project.
 
 There have been various other changes, see the changelog for a complete list
 of changes.