#!/usr/bin/python

import debtags
import sys
import inspect

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.iterPackages)
document(debtags.DB.iterPackagesTags)
document(debtags.DB.iterTags)
document(debtags.DB.iterTagsPackages)


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.packageCount(), "packages in the database"
    print "Image editors:"
    for pkg in db.packagesOfTags(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.tagsOfPackages(("gimp", "krita"))
    print "Common tags:"
    for tag in tags:
	print " *", tag
    print "Packages similar to gimp and krita:"
    for pkg in db.packagesOfTags(tags):
	print " *", pkg
"""
