#!/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)
""")