Extension Point : ISearchSource

Interface	ISearchSource	Since	0.9
Module	trac.search	Source	api.py​

The ISearchSource allows extending the search system with additional information sources.

Purpose

Trac provides a unified search system for full-text search in any resources. By default it supports searching tickets, wiki pages, changesets and milestones. However plugins can implement arbitrary search sources allowing the user to search its resources or any other data of interest.

Usage

Implementing the interface follows the standard guidelines found in TracDev/ComponentArchitecture and of course TracDev/PluginDevelopment.

The implementation reports the supported filters and whether they should be enabled by default. It is then called when a user performs a search, and should return any results matching the search terms for any relevant enabled filters.

The trac.search.api module also provides some helper functions that can often be used to implement the search itself (search_to_sql) or to format the results appropriately (shorten_result).

Examples

The following example implements a simple search source for user names. (Note that Trac stores names of authenticated users in the sid field of the session table.)

from datetime import datetime
from trac.core import *
from trac.search import ISearchSource, search_to_sql
from trac.util.datefmt import utc

class UserSearchModule(Component):
    """Search user names."""

    implements(ISearchSource)

    # ISearchSource methods

    def get_search_filters(self, req):
        yield ('usernames', 'User Names', False)

    def get_search_results(self, req, terms, filters):
        if not 'usernames' in filters:
            return
        with self.env.db_query as db:
            sql_query, args = search_to_sql(db, ['sid'], terms)

            for name, last_visit in db("""
                    SELECT sid, last_visit FROM session
                    WHERE authenticated=1 AND """ + sql_query, args):
                dt = last_visit if last_visit else datetime.now(utc)
                args = '?owner=%s&or&reporter=%s' % (name, name)
                link = req.href.query() + args
                yield (link, name, dt, '', '')

In this example the search result consists simply of a title (the matching name), a date (when the user last visited this Trac instance) and a query link (tickets owned or reported by that user).

More traditional implementations would show resources as search results, with title (retrieved by get_resource_name), URL (get_resource_url), excerpt (shorten_result) and possibly an author and creation date.

Often such implementations would also perform permission checks (and possibly implement IPermissionRequestor). The user might not have permission to search the subsystem at all, or certain individual search results (resources) might need to be filtered out.

The milestone search​ is a good example for all of the above.

Available Implementations

In Trac:

TicketModule​	Searches ticket text fields and attachments.
WikiModule​	Searches wiki pages and attachments.
ChangesetModule​	Searches changesets (in the repository cache).
MilestoneModule​	Searches milestone name, description and attachments.

In third-party plugins:

​th:SearchAllPlugin	Searches all Trac projects in the Trac multi-project environment.
​th:RepoSearchPlugin	Searches the source code repository (using a custom indexer).
​th:FilenameSearchPlugin	Searches filenames in the source code repository.
​th:SearchAttachmentsPlugin	Searches attachments (using the Swish-e indexer).
​th:TracFormsPlugin	Provides (searchable) Forms anywhere on Trac.
​th:DoxygenPlugin	Integrates (searchable) doxygen documentation.
​th:PyDocPlugin	Integrates (searchable) pydoc documentation.

Additional Information and References

• ​Epydoc API Reference
• See TracSearch for user documentation of the search system
• See AdvancedSearch for possible improvements
• Related tickets

API History

• 0.9 introduced the interface.
• 0.10 changed parameter query string to list of terms. ([2940]; ​example supporting both APIs)
• 0.11 refactored trac.Search module into trac.search package. ([4262])