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

1 files changed, 34 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.