* apt/*.py:

  - Almost complete cleanup of the code
  - Remove inconsistent use of tabs and spaces (Closes: #505443)
  - Improved documentation
* apt/debfile.py:
  - Drop get*() methods, as they are deprecated and were
    never in a stable release
  - Make DscSrcPackage working
* apt/gtk/widgets.py:
  - Fix the code and document the signals
* Introduce new documentation build with Sphinx
  - Contains style Guide (Closes: #481562)
  - debian/rules: Build the documentation here
  - setup.py: Remove pydoc building and add new docs.
  - debian/examples: Include examples from documentation
  - debian/python-apt.docs:
    + Change html/ to build/doc/html.
    + Add build/doc/text for the text-only documentation
* setup.py:
  - Only create build/data when building, not all the time
  - Remove build/mo and build/data on clean -a
* debian/control:
  - Remove the Conflicts on python2.3-apt, python2.4-apt, as
    they are only needed for oldstable (sarge)
  - Build-Depend on python-sphinx (>= 0.5)
* aptsources/distinfo.py:
  - Allow @ in mirror urls (Closes: #478171) (LP: #223097)
* Merge Ben Finney's whitespace changes (Closes: #481563)
* Merge Ben Finney's do not use has_key() (Closes: #481878)
* Do not use deprecated form of raise statement (Closes: #494259)
* Add support for PkgRecords.SHA256Hash (Closes: #456113)

1 files changed, 78 insertions, 0 deletions

diff --git a/doc/source/apt/cache.rst b/doc/source/apt/cache.rst
new file mode 100644
index 00000000..d96cba97
--- /dev/null
+++ b/doc/source/apt/cache.rst
@@ -0,0 +1,78 @@
+:mod:`apt.cache` --- The Cache class
+=====================================
+.. automodule:: apt.cache
+
+The Cache class
+---------------
+
+.. autoclass:: Cache
+    :members:
+    :undoc-members:
+
+    .. describe:: cache[pkgname]
+
+        Return a :class:`Package()` for the package with the name *pkgname*.
+
+Example
+^^^^^^^
+
+The following example shows how to load the cache, update it, and upgrade
+all the packages on the system::
+
+    import apt
+    import apt.progress
+
+    # First of all, open the cache
+    cache = apt.Cache()
+    # Now, lets update the package list
+    cache.update()
+    # We need to re-open the cache because it needs to read the package list
+    cache.open(None)
+    # Now we can do the same as 'apt-get upgrade' does
+    cache.upgrade()
+    # or we can play 'apt-get dist-upgrade'
+    cache.upgrade(True)
+    # Q: Why does nothing happen?
+    # A: You forgot to call commit()!
+    cache.commit(apt.progress.TextFetchProgress(),
+                 apt.progress.InstallProgress())
+
+
+
+Working with Filters
+--------------------
+.. autoclass:: Filter
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+.. autoclass:: MarkedChangesFilter
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+.. autoclass:: FilteredCache
+    :members:
+    :inherited-members:
+    :undoc-members:
+
+
+Example
+^^^^^^^
+
+This is an example for a filtered cache, which only allows access to the
+packages whose state has been changed, eg. packages marked for installation::
+
+    >>> from apt.cache import FilteredCache, Cache, MarkedChangesFilter
+    >>> cache = apt.Cache()
+    >>> changed = apt.FilteredCache(cache)
+    >>> changed.setFilter(MarkedChangesFilter())
+    >>> print len(changed) == len(cache.GetChanges()) # Both need to have same length
+    True
+
+
+Exceptions
+----------
+.. autoexception:: FetchCancelledException
+.. autoexception:: FetchFailedException
+.. autoexception:: LockFailedException