Add a tutorial on how to do things which are possible with apt-get,

like apt-get --print-uris update (cf. #551164).

3 files changed, 70 insertions, 1 deletions

diff --git a/debian/changelog b/debian/changelog
index 7588d35a..fb3b72f9 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,6 +1,8 @@
-python-apt (0.7.93) experimental; urgency=low
+python-apt (0.7.93) UNRELEASED; urgency=low
 
   * Merge 0.7.13.0 - 0.7.13.3 from unstable.
+  * Add a tutorial on how to do things which are possible with apt-get,
+    like apt-get --print-uris update (cf. #551164).
 
  -- Julian Andres Klode <jak@debian.org>  Wed, 16 Sep 2009 19:26:17 +0200
 
diff --git a/doc/source/examples/update-print-uris.py b/doc/source/examples/update-print-uris.py
new file mode 100644
index 00000000..f078cdc5
--- /dev/null
+++ b/doc/source/examples/update-print-uris.py
@@ -0,0 +1,22 @@
+#!/usr/bin/python
+"""Print out the URIs of all indexes files.
+
+This behaves somewhat like apt-get --print-uris update."""
+import apt_pkg
+
+def main():
+    apt_pkg.init_config()
+    apt_pkg.init_system()
+    acquire = apt_pkg.Acquire()
+    slist = apt_pkg.SourceList()
+    # Read the list
+    slist.read_main_list()
+    # Add all indexes to the fetcher.
+    slist.get_indexes(acquire, True)
+
+    # Now print the URI of every item.
+    for item in acquire.items:
+        print item.desc_uri
+
+if __name__ == '__main__':
+    main()
diff --git a/doc/source/tutorials/apt-get.rst b/doc/source/tutorials/apt-get.rst
new file mode 100644
index 00000000..575f0c46
--- /dev/null
+++ b/doc/source/tutorials/apt-get.rst
@@ -0,0 +1,45 @@
+Doing stuff :command:`apt-get` does
+===================================
+:Author: Julian Andres Klode <jak@debian.org>
+:Release: |release|
+:Date: |today|
+
+The following article will show how you can use python-apt to do actions done
+by the :command:`apt-get` command.
+
+
+Printing the URIs of all index files
+------------------------------------
+We all now that we can print the URIs of all our index files by running a
+simple ``apt-get -s --print-uris update``. We can do the same. Responsible for
+the source entries is the class :class:`apt_pkg.SourceList`, which can be
+combined with an :class:`apt_pkg.Acquire` object using :meth:`get_indexes`.
+
+First of all, we have to create the objects::
+
+    acquire = apt_pkg.Acquire()
+    slist = apt_pkg.SourceList()
+
+Now we have to parse /etc/apt/sources.list and its friends, by using
+:meth:`apt_pkg.SourceList.read_main_list`::
+    slist.read_main_list()
+
+Now the **slist** object knows about the location of the indexes. We now have
+to load those indexes into the *acquire* object by calling
+:meth:`apt_pkg.SourceList.get_indexes`::
+
+    slist.get_indexes(acquire, True)
+
+The first argument is the acquire object into which we will load these indexes,
+and the second argument means that we want to fetch all indexes. Now the only
+thing left to do is iterating over the list of items and printing out their
+URIs. Luckily, there is :attr:`apt_pkg.Acquire.items` which allows us to
+iterate over the items::
+
+    for item in acquire.items:
+        print item.desc_uri
+
+In the end a program could look like this:
+
+.. literalinclude:: ../examples/update-print-uris.py
+