apt.package: Add 'tasks' to Version, improve doc (Closes: #619574)

3 files changed, 64 insertions, 4 deletions

diff --git a/apt/package.py b/apt/package.py
index 54ef1c01..14e80594 100644
--- a/apt/package.py
+++ b/apt/package.py
@@ -162,10 +162,23 @@ class Origin(object):
 
 
 class Record(Mapping):
-    """Represent a pkgRecord.
+    """Record in a Packages file
+
+    Represent a record as stored in a Packages file. You can use this like
+    a dictionary mapping the field names of the record to their values::
+
+        >>> record = Record("Package: python-apt\\nVersion: 0.8.0\\n\\n")
+        >>> record["Package"]
+        'python-apt'
+        >>> record["Version"]
+        '0.8.0'
+
+    For example, to get the tasks of a package from a cache, you could do::
+
+        package.candidate.record["Tasks"].split()
+
+    Of course, you can also use the :attr:`Version.tasks` property.
 
-    It can be accessed like a dictionary and can also give the original package
-    record if accessed as a string.
     """
 
     def __init__(self, record_str):
@@ -209,6 +222,9 @@ class Record(Mapping):
 class Version(object):
     """Representation of a package version.
 
+    The Version class contains all information related to a
+    specific package version.
+
     .. versionadded:: 0.7.9
     """
 
@@ -393,7 +409,11 @@ class Version(object):
 
     @property
     def record(self):
-        """Return a Record() object for this version."""
+        """Return a Record() object for this version.
+
+        Return a Record() object for this version which provides access
+        to the raw attributes of the candidate version
+        """
         return Record(self._records.record)
 
     def get_dependencies(self, *types):
@@ -474,6 +494,16 @@ class Version(object):
         """
         return self._records.sha256_hash
 
+    @property
+    def tasks(self):
+        """Get the tasks of the package.
+
+        A set of the names of the tasks this package belongs to.
+
+        .. versionadded:: 0.8.0
+        """
+        return set(self.record["Task"].split())
+
     def _uris(self):
         """Return an iterator over all available urls.
 
diff --git a/debian/changelog b/debian/changelog
index ebe2de3f..c8b47acc 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -15,6 +15,7 @@ python-apt (0.8.0~exp2) UNRELEASED; urgency=low
   * apt.cache: Document that update() may need an open() (Closes: #622342)
   * apt.cache: Add a fetch_archives() method (Closes: #622347)
   * doc: Fix a minor formatting error, patch by Jakub Wilk (Closes: #608914)
+  * apt.package: Add 'tasks' to Version, improve doc (Closes: #619574)
 
  -- Julian Andres Klode <jak@debian.org>  Wed, 06 Apr 2011 09:46:52 +0200
 
diff --git a/doc/source/library/apt.package.rst b/doc/source/library/apt.package.rst
index 4b143b8a..d8731ea8 100644
--- a/doc/source/library/apt.package.rst
+++ b/doc/source/library/apt.package.rst
@@ -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