hypatia.catalog

class hypatia.catalog.Catalog(family=None)
__setitem__(name, index)
__getitem__(key)

Retrieve an index.

get(key, failobj=None)

Retrieve an index or return failobj.

reset()

Clear all indexes in this catalog.

index_doc(docid, obj)

Register the document represented by obj in indexes of this catalog using docid docid.

unindex_doc(docid)

Unregister the document id from indexes of this catalog.

reindex_doc(docid, obj)

Reindex the document referenced by docid using the object passed in as obj (typically just does the equivalent of unindex_doc, then index_doc, but specialized indexes can override the method that this API calls to do less work.

index_doc(docid, obj)

Register the document represented by obj in indexes of this catalog using docid docid.

reindex_doc(docid, obj)

Reindex the document referenced by docid using the object passed in as obj (typically just does the equivalent of unindex_doc, then index_doc, but specialized indexes can override the method that this API calls to do less work.

reset()

Clear all indexes in this catalog.

unindex_doc(docid)

Unregister the document id from indexes of this catalog.

class hypatia.catalog.CatalogQuery(catalog, family=None)

Legacy query API for non-index-based queries; might be useful if/when an index-based query doesn’t work properly, or a particular contstraint can’t be spelled with one.

__call__(queryobject, sort_index=None, limit=None, sort_type=None, reverse=False, names=None)

Use the arguments to perform a query. Return a tuple of (num, resultseq).

sort(docidset, sort_index, limit=None, sort_type=None, reverse=False)

Return (num, sorted-resultseq) for the concrete docidset.

query(queryobject, sort_index=None, limit=None, sort_type=None, reverse=False, names=None)

Use the arguments to perform a query. Return a tuple of (num, resultseq).

search(**query)

Use the query terms to perform a query. Return a tuple of (num, resultseq) based on the merging of results from individual indexes.

Note

This method is deprecated. Use hypatia.catalog.CatalogQuery.__call__() instead.

sort(docidset, sort_index, limit=None, sort_type=None, reverse=False)

Return (num, sorted-resultseq) for the concrete docidset.

hypatia.query

Comparators

class hypatia.query.Contains(index, value)

Contains query.

CQE equivalent: ‘foo’ in index

class hypatia.query.Eq(index, value)

Equals query.

CQE equivalent: index == ‘foo’

class hypatia.query.NotEq(index, value)

Not equal query.

CQE eqivalent: index != ‘foo’

class hypatia.query.Gt(index, value)

Greater than query.

CQE equivalent: index > ‘foo’

class hypatia.query.Lt(index, value)

Less than query.

CQE equivalent: index < ‘foo’

class hypatia.query.Ge(index, value)

Greater (or equal) query.

CQE equivalent: index >= ‘foo’

class hypatia.query.Le(index, value)

Less (or equal) query.

CQE equivalent: index <= ‘foo

class hypatia.query.Contains(index, value)

Contains query.

CQE equivalent: ‘foo’ in index

class hypatia.query.NotContains(index, value)

CQE equivalent: ‘foo’ not in index

class hypatia.query.Any(index, value)

Any of query.

CQE equivalent: index in any([‘foo’, ‘bar’])

class hypatia.query.NotAny(index, value)

Not any of query (ie, None of query)

CQE equivalent: index not in any([‘foo’, ‘bar’])

class hypatia.query.All(index, value)

All query.

CQE equivalent: index in all([‘foo’, ‘bar’])

class hypatia.query.NotAll(index, value)

NotAll query.

CQE equivalent: index not in all([‘foo’, ‘bar’])

class hypatia.query.InRange(index, start, end, start_exclusive=False, end_exclusive=False)

Index value falls within a range.

CQE eqivalent: lower < index < upper
lower <= index <= upper
class hypatia.query.NotInRange(index, start, end, start_exclusive=False, end_exclusive=False)

Index value falls outside a range.

CQE eqivalent: not(lower < index < upper)
not(lower <= index <= upper)

Boolean Operators

class hypatia.query.Or(*queries)

Boolean Or of multiple queries.

class hypatia.query.And(*queries)

Boolean And of multiple queries.

class hypatia.query.Not(query)

Negation of a query.

Other Helpers

class hypatia.query.Name(name)

A variable name in an expression, evaluated at query time. Can be used to defer evaluation of variables used inside of expressions until query time.

Example:

from hypatia.query import Eq
from hypatia.query import Name

# Define query at module scope
find_cats = Eq('color', Name('color')) & Eq('sex', Name('sex'))

# Use query in a search function, evaluating color and sex at the
# time of the query
def search_cats(catalog, resolver, color='tabby', sex='female'):
    # Let resolver be some function which can retrieve a cat object
    # from your application given a docid.
    params = dict(color=color, sex=sex)
    count, docids = catalog.query(find_cats, params)
    for docid in docids:
        yield resolver(docid)
hypatia.query.parse_query(expr, catalog, optimize_query=True)

Parses the given expression string and returns a query object. Requires Python >= 2.6.

hypatia.util

class hypatia.util.ResultSet(ids, numids, resolver, sort_type=None)

Implements hypatia.interfaces.IResultSet

intersect(docids)

Intersect this resultset with a sequence of docids or another resultset. Returns a new ResultSet.

hypatia.exc

class hypatia.exc.BadResults(resultset)

Superclass of hypatia.exc.MultipleResults and hypatia.exc.NoResults. Has an attribute named resultset which is the resultset related to the error.

class hypatia.exc.MultipleResults(resultset)

Raised when a method that was expected to return a single result returns multiple results.

class hypatia.exc.NoResults(resultset)

Raised when a method that was expected to return at least one result returns zero results.

class hypatia.exc.Unsortable(docids)

Raised when a method which was expected to sort a set of provided document identifiers cannot sort one or more of those identifiers. An attribute named docids is a sequence containing the identifiers.

hypatia.field

Field index

class hypatia.field.FieldIndex(discriminator, family=None)

Field indexing.

Query types supported:

  • Eq
  • NotEq
  • Gt
  • Ge
  • Lt
  • Le
  • In
  • NotIn
  • Any
  • NotAny
  • InRange
  • NotInRange
index_doc(docid, value)

See interface IIndexInjection

reindex_doc(docid, value)

See interface IIndexInjection

reset()

Initialize forward and reverse mappings.

unindex_doc(docid)

See interface IIndexInjection.

unique_values()

Return the unique values in the index for all docids as an iterable

word_count()

See interface IIndexStatistics

hypatia.keyword

class hypatia.keyword.KeywordIndex(discriminator, family=None)

Keyword index.

Query types supported:

  • Eq
  • NotEq
  • In
  • NotIn
  • Any
  • NotAny
  • All
  • NotAll
normalize(seq)

Perform normalization on sequence of keywords.

Return normalized sequence. This method may be overriden by subclasses.

optimize()

Optimize the index. Call this after changing tree_threshold.

This converts internal data structures between Sets and TreeSets based on tree_threshold.

reset()

Initialize forward and reverse mappings.

search(query, operator='and')

Execute a search given by ‘query’.

unique_values()

Return the unique values in the index for all docids as an iterable

word_count()

Return the number of indexed words

hypatia.text

Text index.

class hypatia.text.TextIndex(discriminator, lexicon=None, index=None, family=None)
check_query(querytext)

Returns True if the querytext can be turned into a parse tree, returns False if otherwise.

sort(result, reverse=False, limit=None, sort_type=None, raise_unsortable=True)

Sort by text relevance.

This only works if the query includes at least one text query, leading to a weighted result. This method raises TypeError if the result is not weighted.

A weighted result is a dictionary-ish object that has docids as keys and floating point weights as values. This method sorts the dictionary by weight and returns the sorted docids as a list.

word_count()

Return the number of words in the index.

hypatia.facet

class hypatia.facet.FacetIndex(discriminator, facets, family=None)

Facet index.

Query types supported:

  • Eq
  • NotEq
  • In
  • NotIn
  • Any
  • NotAny
  • All
  • NotAll
counts(docids, omit_facets=())

Given a set of docids (usually returned from query), provide count information for further facet narrowing. Optionally omit count information for facets and their ancestors that are in ‘omit_facets’ (a sequence of facets)

index_doc(docid, obj)

Pass in an integer document id and an object supporting a sequence of facet specifiers ala [‘style:gucci:handbag’] via the discriminator

hypatia.interfaces

hypatia.interfaces.STABLE

Used as an argument to the sort_type parameter of IIndexSort.sort.

hypatia.interfaces.OPTIMAL

Used as an argument to the sort_type parameter of IIndexSort.sort.