Context Navigation

Warning: リポジトリと同期できません (サポートされていないバージョンコントロールシステム "svn です。 Python のライブラリに "svn" が正しくインストールされているか確認してください。)

インタフェースのリファレンス

Tracは、ComponentArchitectureに基づき多くのインタフェースをプラグイン開発者に提供しています。
が、資料はほとんどないので、ここにまとめてみました。

インタフェース一覧

0.10で若干インタフェースが増えてるようです。

パッケージ	インタフェース	0.9	0.10	説明
trac.db.api	IDatabaseConnector	×	○	DBを変更するためのインタフェース？
trac.mimeview.api	IHTMLPreviewRenderer	○	○	リポジトリブラウザでHTMLを表示するためのインタフェース
trac.mimeview.api	IHTMLPreviewAnnotator	○	○	リポジトリブラウザで付加情報を表示するためのインタフェース
trac.tests.core	ITest	×	○
trac.ticket.api	ITicketChangeListener	×	○
trac.ticket.api	ITicketManipulator	×	○
trac.versioncontrol.api	IRepositoryConnector	×	○
trac.web.api	IAuthenticator	○	○
trac.web.api	IRequestHandler	○	○
trac.web.chrome	INavigationContributor	○	○
trac.web.chrome	ITemplateProvider	○	○
trac.wiki.api	IWikiChangeListener	○	○
trac.wiki.api	IWikiPageManipulator	×	○
trac.wiki.api	IWikiMacroProvider	○	○
trac.wiki.api	IWikiSyntaxProvider	○	○
trac.env	IEnvironmentSetupParticipant	○	○
trac.perm	IPermissionRequestor	○	○
trac.perm	IPermissionStore	○	○
trac.perm	IPermissionGroupProvider	○	○
trac.Search	ISearchSource	○	○
trac.Timeline	ITimelineEventProvider	○	○

リファレンス

IDatabaseConnector

Trac 0.10以降。DB接続先を変えるためのインタフェースみたいです。

class IDatabaseConnector(Interface):
    """Extension point interface for components that support the connection to
    relational databases."""

    def get_supported_schemes():
        """Return the connection URL schemes supported by the connector, and
        their relative priorities as an iterable of `(scheme, priority)` tuples.
        """

    def get_connection(**kwargs):
        """Create a new connection to the database."""
        
    def init_db(**kwargs):
        """Initialize the database."""

    def to_sql(table):
        """Return the DDL statements necessary to create the specified table,
        including indices."""

IHTMLPreviewRenderer

リポジトリブラウザで、MimeTypeに紐づくHTMLを出力するためのインタフェース。特定のMimeTypeに対して、リポジトリブラウザでデータを見せたいときにこれを使います。

class IHTMLPreviewRenderer(Interface):
    """Extension point interface for components that add HTML renderers of
    specific content types to the `Mimeview` component.
    """

    # implementing classes should set this property to True if they
    # support text content where Trac should expand tabs into spaces
    expand_tabs = False

    def get_quality_ratio(mimetype):
        """Return the level of support this renderer provides for the `content`
        of the specified MIME type. The return value must be a number between
        0 and 9, where 0 means no support and 9 means "perfect" support.
        """

    def render(req, mimetype, content, filename=None, url=None):
        """Render an XHTML preview of the raw `content`.

        The `content` might be:
         * a `str` object
         * an `unicode` string
         * any object with a `read` method, returning one of the above

        It is assumed that the content will correspond to the given `mimetype`.

        Besides the `content` value, the same content may eventually
        be available through the `filename` or `url` parameters.
        This is useful for renderers that embed objects, using <object> or
        <img> instead of including the content inline.
        
        Can return the generated XHTML text as a single string or as an
        iterable that yields strings. In the latter case, the list will
        be considered to correspond to lines of text in the original content.
        """

サンプル： source:/trunk/xdocviewplugin/xdocview/xdocview.py@36

IHTMLPreviewAnnotator

IHTMLPreviewRendererと似てますが、これは付加情報をXHTMLで表示するためのものみたい？使ってるのは見たことありません。

class IHTMLPreviewAnnotator(Interface):
    """Extension point interface for components that can annotate an XHTML
    representation of file contents with additional information."""

    def get_annotation_type():
        """Return a (type, label, description) tuple that defines the type of
        annotation and provides human readable names. The `type` element should
        be unique to the annotator. The `label` element is used as column
        heading for the table, while `description` is used as a display name to
        let the user toggle the appearance of the annotation type.
        """

    def annotate_line(number, content):
        """Return the XHTML markup for the table cell that contains the
        annotation data."""

ITicketChangeListener

Ver0.10以降。チケットの変更時に呼び出されるインタフェース。作成時、変更時、削除（削除ってあったっけ？）時にそれぞれ呼び出されるメソッドを定義する。

class ITicketChangeListener(Interface):
    """Extension point interface for components that require notification when
    tickets are created, modified, or deleted."""

    def ticket_created(ticket):
        """Called when a ticket is created."""

    def ticket_changed(ticket, comment, old_values):
        """Called when a ticket is modified.
        
        `old_values` is a dictionary containing the previous values of the
        fields that have changed.
        """

    def ticket_deleted(ticket):
        """Called when a ticket is deleted."""

ITicketManipulator

Ver0.10以降。チケットの登録時に呼び出されるインタフェース。値のチェックを行うのに使う。

class ITicketManipulator(Interface):
    """Miscellaneous manipulation of ticket workflow features."""

    def prepare_ticket(req, ticket, fields, actions):
        """Not currently called, but should be provided for future
        compatibility."""

    def validate_ticket(req, ticket):
        """Validate a ticket after it's been populated from user input.
        
        Must return a list of `(field, message)` tuples, one for each problem
        detected. `field` can be `None` to indicate an overall problem with the
        ticket. Therefore, a return value of `[]` means everything is OK."""

IRepositoryConnector

Ver0.10以降。 SVN以外のバージョン管理システムを使うためのインタフェース。

class IRepositoryConnector(Interface):
    """Extension point interface for components that provide support for a
    specific version control system."""

    def get_supported_types():
        """Return the types of version control systems that are supported by
        this connector, and their relative priorities.
        
        Highest number is highest priority.
        """

    def get_repository(repos_type, repos_dir, authname):
        """Return the Repository object for the given repository type and
        directory.
        """

IAuthenticator

class IAuthenticator(Interface):
    """Extension point interface for components that can provide the name
    of the remote user."""

    def authenticate(req):
        """Return the name of the remote user, or `None` if the identity of the
        user is unknown."""

IRequestHandler

リクエストハンドラ。リクエストを処理する場合に使う。っていうかメニューにアイテムを作ったらまず間違いなく使う。いろんなモジュールが使っているので参照すればだいたい分かる。

class IRequestHandler(Interface):
    """Extension point interface for request handlers."""

    # implementing classes should set this property to `True` if they
    # don't need session and authentication related information
    anonymous_request = False
    
    # implementing classes should set this property to `False` if they
    # don't need the HDF data and don't produce content using a template
    use_template = True
    
    def match_request(req):
        """Return whether the handler wants to process the given request."""

    def process_request(req):
        """Process the request. Should return a (template_name, content_type)
        tuple, where `template` is the ClearSilver template to use (either
        a `neo_cs.CS` object, or the file name of the template), and
        `content_type` is the MIME type of the content. If `content_type` is
        `None`, "text/html" is assumed.

        Note that if template processing should not occur, this method can
        simply send the response itself and not return anything.
        """

INavigationContributor

メニューバーにアイテムを出すときに使う。これも多くのコンポーネントで使われている。

class INavigationContributor(Interface):
    """Extension point interface for components that contribute items to the
    navigation.
    """

    def get_active_navigation_item(req):
        """This method is only called for the `IRequestHandler` processing the
        request.
        
        It should return the name of the navigation item that should be
        highlighted as active/current.
        """

    def get_navigation_items(req):
        """Should return an iterable object over the list of navigation items to
        add, each being a tuple in the form (category, name, text).
        """

ITemplateProvider

ClearSilverテンプレートから、静的なコンテンツ（画像とか）を呼びたい場合に使う。

class ITemplateProvider(Interface):
    """Extension point interface for components that provide their own
    ClearSilver templates and accompanying static resources.
    """

    def get_htdocs_dirs():
        """Return a list of directories with static resources (such as style
        sheets, images, etc.)

        Each item in the list must be a `(prefix, abspath)` tuple. The
        `prefix` part defines the path in the URL that requests to these
        resources are prefixed with.
        
        The `abspath` is the absolute path to the directory containing the
        resources on the local file system.
        """

異なるフォーマットでダウンロード:

テキスト