apt_pkg: Add subclassing fun to PackageManager, for #623485 as well

2 files changed, 69 insertions, 2 deletions

diff --git a/doc/source/library/apt_pkg.rst b/doc/source/library/apt_pkg.rst
index fce4f804..81f2d408 100644
--- a/doc/source/library/apt_pkg.rst
+++ b/doc/source/library/apt_pkg.rst
@@ -423,6 +423,65 @@ 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`
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/doc/source/whatsnew/0.8.0.rst b/doc/source/whatsnew/0.8.0.rst
index fa58a022..2eeb135e 100644
--- a/doc/source/whatsnew/0.8.0.rst
+++ b/doc/source/whatsnew/0.8.0.rst
@@ -16,6 +16,16 @@ This version of python-apt introduces multi-arch support:
     * A new class, :class:`apt_pkg.Group` has been added.
     * :class:`apt_pkg.Cache` can now be indexed by ``(name, architecture)``
       tuples
+      
+Features for mancoosi
+----------------------
+Several new features related to ordering have been added on request
+of the mancoosi project:
+
+    * A new class :class:`apt_pkg.OrderList` has been added
+    * The :class:`apt_pkg.PackageManager` class now provides new methods
+      for registering install/remove/configure actions which can be
+      subclassed to check ordering.
 
 Other changes
 -------------
@@ -23,8 +33,6 @@ 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.