1 files changed, 104 insertions, 0 deletions
diff --git a/debian/foo/doc-debtags b/debian/foo/doc-debtags
new file mode 100755
index 0000000..366f1bf
--- /dev/null
+++ b/debian/foo/doc-debtags
@@ -0,0 +1,104 @@
+#!/usr/bin/python
+
+from __future__ import absolute_import, print_function
+
+import sys
+import os
+import inspect
+
+sys.path.insert(0, os.path.join(sys.path[0], os.pardir))
+
+from debian import debtags
+
+def print_indented (spaces, string):
+	for line in string.split("\n"):
+		for i in range(1,spaces):
+			sys.stdout.write(" ")
+		sys.stdout.write(line)
+		sys.stdout.write("\n")
+
+def document (callable):
+	if callable.__doc__ != None:
+		print_indented(2, callable.__name__)
+		print_indented(4, inspect.getdoc(callable))
+		print()
+
+
+print("""debtags.py README
+=================
+
+The Debtags python module provides support for accessing and manipulating
+Debtags tag data.
+
+The module provides a single class, debtags.DB, which implements various kinds
+of tag operations on an in-memory tag database.
+
+The database can be queried both as a database of packages with associated tags
+and as a database of tags with associated packages.  Performance are good in
+both ways: querying the tags of a package has the same peed as querying the
+packages having a tag.
+
+debtags.DB allows both simple queries and more complex algorithms to be
+implemented easily and efficiently.  Have a look at the Sample usage section
+below for some examples.
+
+
+Classes
+=======
+
+There is only one class: debtags.DB:
+""")
+
+document (debtags.DB)
+
+print("""
+The methods of debtags.DB are:
+""")
+
+for m in dir(debtags.DB):
+	if m[0:2] != '__' and callable(getattr(debtags.DB, m)):
+		document(getattr(debtags.DB, m))
+
+print("""Iteration
+=========
+
+debtags.DB provides various iteration methods to iterate the collection either
+in a package-centered or in a tag-centered way:
+""")
+
+document(debtags.DB.iter_packages)
+document(debtags.DB.iter_packages_tags)
+document(debtags.DB.iter_tags)
+document(debtags.DB.iter_tags_packages)
+
+
+print("""Sample usage
+============
+
+This example reads the system debtags database and performs a simple tag
+search::
+
+    import debtags
+    
+    db = debtags.DB()
+    db.read(open("/var/lib/debtags/package-tags", "r"))
+    print(db.package_count(), "packages in the database")
+    print("Image editors:")
+    for pkg in db.packages_of_tags(set(("use::editing", "works-with::image:raster"))):
+    	print(" *", pkg)
+
+This example computes the set of tags that belong to all the packages in a
+list, then shows all the other packages that have those tags:
+
+    import debtags
+
+    db = debtags.DB()
+    db.read(open("/var/lib/debtags/package-tags", "r"))
+    tags = db.tags_of_packages(("gimp", "krita"))
+    print("Common tags:")
+    for tag in tags:
+	print(" *", tag)
+    print("Packages similar to gimp and krita:")
+    for pkg in db.packages_of_tags(tags):
+	print(" *", pkg)
+""")