trac.wiki.api – The Wiki API

Interfaces

The wiki module presents several possibilities of extension, for interacting with the Wiki application and also for extending the Wiki syntax.

First, components can be notified of the changes happening in the wiki.

class trac.wiki.api.IWikiChangeListener

Bases: trac.core.Interface

Components that want to get notified about the creation, deletion and modification of wiki pages should implement that interface.

See also trac.wiki.api.IWikiChangeListener extension point.

wiki_page_added()

Called whenever a new Wiki page is added.

wiki_page_changed(version, t, comment, author)

Called when a page has been modified.

wiki_page_deleted()

Called when a page has been deleted.

wiki_page_version_deleted()

Called when a version of a page has been deleted.

wiki_page_renamed(old_name)

Called when a page has been renamed.

wiki_page_comment_modified(old_comment)

Called when a page comment has been modified.

Components can also interfere with the changes, before or after they’re made.

class trac.wiki.api.IWikiPageManipulator

Bases: trac.core.Interface

Components that need to do specific pre- and post- processing of wiki page changes have to implement this interface.

Unlike change listeners, a manipulator can reject changes being committed to the database.

See also trac.wiki.api.IWikiPageManipulator extension point.

prepare_wiki_page(page, fields)

Validate a wiki page before rendering it.

Parameters:
  • page – is the WikiPage being viewed.
  • fields – is a dictionary which contains the wiki text of the page, initially identical to page.text but it can eventually be transformed in place before being used as input to the formatter.
validate_wiki_page(page)

Validate a wiki page after it’s been populated from user input.

Parameters:page – is the WikiPage being edited.
Returns:a list of (field, message) tuples, one for each problem detected. field can be None to indicate an overall problem with the page. Therefore, a return value of [] means everything is OK.

Then, the Wiki syntax itself can be extended. The first and less intrusive way is to provide new Wiki macros or Wiki processors. Those are basically the same thing, as they’re implemented using the following interface. The difference comes from the invocation syntax used in the Wiki markup, which manifests itself in the args parameter of IWikiMacroProvider.expand_macro().

class trac.wiki.api.IWikiMacroProvider

Bases: trac.core.Interface

Augment the Wiki markup with new Wiki macros.

Changed in version 0.12: new Wiki processors can also be added that way.

See also WikiMacroBase and wiki/WikiMacros#DevelopingCustomMacros and trac.wiki.api.IWikiMacroProvider extension point.

get_macros()

Return an iterable that provides the names of the provided macros.

get_macro_description()

Return a tuple of a domain name to translate and plain text description of the macro or only the description with the specified name.

Changed in version 1.0: get_macro_description can return a domain to translate the description.

Changed in version 1.3.6: the macro will be hidden from the macro index ([[MacroList]]) if None is returned.

is_inline()

Return True if the content generated is an inline XHTML element.

New in version 1.0.

expand_macro(name, content, args=None)

Called by the formatter when rendering the parsed wiki text.

New in version 0.11.

Changed in version 0.12: added the args parameter

Parameters:
  • formatter – the wiki Formatter currently processing the wiki markup
  • name – is the name by which the macro has been called; remember that via get_macros, multiple names could be associated to this macros. Note that the macro names are case sensitive.
  • content – is the content of the macro call. When called using macro syntax ([[Macro(content)]]), this is the string contained between parentheses, usually containing macro arguments. When called using wiki processor syntax ({{{!#Macro ...}}}), it is the content of the processor block, that is, the text starting on the line following the macro name.
  • args –

    will be a dictionary containing the named parameters passed when using the Wiki processor syntax.

    The named parameters can be specified when calling the macro using the wiki processor syntax:

    {{{#!Macro arg1=value1 arg2="value 2"`
... some content ...
}}}

    In this example, args will be {'arg1': 'value1', 'arg2': 'value 2'} and content will be "... some content ...".

    If no named parameters are given like in:

    {{{#!Macro
...
}}}

    then args will be {}. That makes it possible to differentiate the above situation from a call made using the macro syntax:

    [[Macro(arg1=value1, arg2="value 2", ... some content...)]]

    in which case args will always be None. Here content will be the "arg1=value1, arg2="value 2", ... some content..." string. If like in this example, content is expected to contain some arguments and named parameters, one can use the parse_args function to conveniently extract them.

The Wiki syntax can also be extended by introducing new markup.

class trac.wiki.api.IWikiSyntaxProvider

Bases: trac.core.Interface

Enrich the Wiki syntax with new markup.

See also wiki:TracDev/IWikiSyntaxProviderExample and trac.wiki.api.IWikiSyntaxProvider extension point.

get_wiki_syntax()

Return an iterable that provides additional wiki syntax.

Additional wiki syntax correspond to a pair of (regexp, cb), the regexp for the additional syntax and the callback cb which will be called if there’s a match. That function is of the form cb(formatter, ns, match).

Return an iterable over (namespace, formatter) tuples.

Each formatter should be a function of the form:

def format(formatter, ns, target, label, fullmatch=None):
    pass

and should return some HTML fragment. The label is already HTML escaped, whereas the target is not. The fullmatch argument is optional, and is bound to the regexp match object for the link.

The Wiki System

The wiki system provide an access to all the pages.

class trac.wiki.api.WikiSystem

Bases: trac.core.Component

Wiki system manager.

change_listeners

List of components that implement IWikiChangeListener

macro_providers

List of components that implement IWikiMacroProvider

syntax_providers

List of components that implement IWikiSyntaxProvider

ignore_missing_pages

Enable/disable highlighting CamelCase links to missing pages.

split_page_names

Enable/disable splitting the WikiPageNames with space characters.

render_unsafe_content

Enable/disable the use of unsafe HTML tags such as <script> or <embed> with the HTML [wiki:WikiProcessors WikiProcessor].

For public sites where anonymous users can edit the wiki it is recommended to leave this option disabled.

safe_schemes

List of URI schemes considered “safe”, that will be rendered as external links even if [wiki] render_unsafe_content is false.

safe_origins

List of URIs considered “safe cross-origin”, that will be rendered as img element without crossorigin="anonymous" attribute or used in url() of inline style attribute even if [wiki] render_unsafe_content is false (‘’since 1.0.15’’).

To make any origins safe, specify “*” in the list.

pages

Return the names of all existing wiki pages.

get_pages(prefix=None)

Iterate over the names of existing Wiki pages.

Parameters:prefix – if given, only names that start with that prefix are included.
has_page(pagename)

Whether a page with the specified name exists.

resolve_relative_name(pagename, referrer)

Resolves a pagename relative to a referrer pagename.

make_label_from_target(target)

Create a label from a wiki target.

A trailing fragment and query string is stripped. Then, leading ./, ../ and / elements are stripped, except when this would lead to an empty label. Finally, if split_page_names is true, the label is split accordingly.

Other Functions

trac.wiki.api.parse_args(args, strict=True)

Utility for parsing macro “content” and splitting them into arguments.

The content is split along commas, unless they are escaped with a backquote (see example below).

Parameters:
  • args – a string containing macros arguments
  • strict – if True, only Python-like identifiers will be recognized as keyword arguments

Example usage:

>>> parse_args('')
([], {})
>>> parse_args('Some text')
(['Some text'], {})
>>> parse_args('Some text, mode= 3, some other arg\, with a comma.')
(['Some text', ' some other arg, with a comma.'], {'mode': ' 3'})
>>> parse_args('milestone=milestone1,status!=closed', strict=False)
([], {'status!': 'closed', 'milestone': 'milestone1'})
trac.wiki.api.validate_page_name(pagename)

Utility for validating wiki page name.

Parameters:pagename – wiki page name to validate