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:

 DB
   In-memory database mapping packages to tags and tags to packages.


The methods of debtags.DB are:

 card
   Return the cardinality of a tag

 choose_packages
   Return a collection with only the packages in package_iter,
   sharing tagsets with this one

 choose_packages_copy
   Return a collection with only the packages in package_iter,
   with a copy of the tagsets of this one

 copy
   Return a copy of this collection, with the tagsets copied as
   well.

 correlations
   Generate the list of correlation as a tuple (hastag, hasalsotag, score).
   
   Every touple will indicate that the tag 'hastag' tends to also
   have 'hasalsotag' with a score of 'score'.

 discriminance
   Return the discriminance index if the tag.
   
   Th discriminance index of the tag is defined as the minimum
   number of packages that would be eliminated by selecting only
   those tagged with this tag or only those not tagged with this
   tag.

 facet_collection
   Return a copy of this collection, but replaces the tag names
   with only their facets.

 filter_packages
   Return a collection with only those packages that match a
   filter, sharing tagsets with this one.  The filter will match
   on the package.

 filter_packages_copy
   Return a collection with only those packages that match a
   filter, with a copy of the tagsets of this one.  The filter
   will match on the package.

 filter_packages_tags
   Return a collection with only those packages that match a
   filter, sharing tagsets with this one.  The filter will match
   on (package, tags).

 filter_packages_tags_copy
   Return a collection with only those packages that match a
   filter, with a copy of the tagsets of this one.  The filter
   will match on (package, tags).

 filter_tags
   Return a collection with only those tags that match a
   filter, sharing package sets with this one.  The filter will match
   on the tag.

 filter_tags_copy
   Return a collection with only those tags that match a
   filter, with a copy of the package sets of this one.  The
   filter will match on the tag.

 has_package
   Check if the collection contains the given package

 has_tag
   Check if the collection contains packages tagged with tag

 ideal_tagset
   Return an ideal selection of the top tags in a list of tags.
   
   Return the tagset made of the highest number of tags taken in
   consecutive sequence from the beginning of the given vector,
   that would intersecate with the tagset of a comfortable amount
   of packages.
   
   Comfortable is defined in terms of how far it is from 7.

 iter_packages
   Iterate over the packages

 iter_packages_tags
   Iterate over 2-tuples of (pkg, tags)

 iter_tags
   Iterate over the tags

 iter_tags_packages
   Iterate over 2-tuples of (tag, pkgs)

 package_count
   Return the number of packages

 packages_of_tag
   Return the package set of a tag

 packages_of_tags
   Return the set of packages that have all the tags in tags

 qread
   Quickly read the data from a pickled file

 qwrite
   Quickly write the data to a pickled file

 read
   Read the database from a file.
   
   Example::
           # Read the system Debtags database
           db.read(open("/var/lib/debtags/package-tags", "r"))

 reverse
   Return the reverse collection, sharing tagsets with this one

 reverse_copy
   Return the reverse collection, with a copy of the tagsets of
   this one.

 tag_count
   Return the number of tags

 tags_of_package
   Return the tag set of a package

 tags_of_packages
   Return the set of tags that have all the packages in pkgs

Iteration
=========

debtags.DB provides various iteration methods to iterate the collection either
in a package-centered or in a tag-centered way:

 iter_packages
   Iterate over the packages

 iter_packages_tags
   Iterate over 2-tuples of (pkg, tags)

 iter_tags
   Iterate over the tags

 iter_tags_packages
   Iterate over 2-tuples of (tag, pkgs)

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)

