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
(page)¶ Called whenever a new Wiki page is added.
-
wiki_page_changed
(page, version, t, comment, author)¶ Called when a page has been modified.
-
wiki_page_comment_modified
(page, old_comment)¶ Called when a page comment has been modified.
-
wiki_page_deleted
(page)¶ Called when a page has been deleted.
-
wiki_page_renamed
(page, old_name)¶ Called when a page has been renamed.
-
wiki_page_version_deleted
(page)¶ Called when a version of a page has been deleted.
-
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
(req, 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 topage.text
but it can eventually be transformed in place before being used as input to the formatter.
- page – is the
-
validate_wiki_page
(req, 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 beNone
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.-
expand_macro
(formatter, 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
parameterParameters: - 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'}
andcontent
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 beNone
. Herecontent
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 theparse_args
function to conveniently extract them.
- formatter – the wiki
-
get_macro_description
(name)¶ 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.
-
get_macros
()¶ Return an iterable that provides the names of the provided macros.
-
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_link_resolvers
()¶ 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 thetarget
is not. Thefullmatch
argument is optional, and is bound to the regexp match object for the link.
-
get_wiki_syntax
()¶ Return an iterable that provides additional wiki syntax.
Additional wiki syntax correspond to a pair of
(regexp, cb)
, theregexp
for the additional syntax and the callbackcb
which will be called if there’s a match. That function is of the formcb(formatter, ns, match)
.
-
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
-
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.
-
ignore_missing_pages
¶ Enable/disable highlighting CamelCase links to missing pages.
-
macro_providers
¶ List of components that implement
IWikiMacroProvider
-
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.
-
pages
¶ Return the names of all existing wiki pages.
-
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.
-
resolve_relative_name
(pagename, referrer)¶ Resolves a pagename relative to a referrer pagename.
-
safe_origins
¶ List of URIs considered “safe cross-origin”, that will be rendered as
img
element withoutcrossorigin="anonymous"
attribute or used inurl()
of inline style attribute even if[wiki] render_unsafe_content
isfalse
(‘’since 1.0.15’‘).To make any origins safe, specify “*” in the list.
-
safe_schemes
¶ List of URI schemes considered “safe”, that will be rendered as external links even if
[wiki] render_unsafe_content
isfalse
.
-
split_page_names
¶ Enable/disable splitting the WikiPageNames with space characters.
-
syntax_providers
¶ List of components that implement
IWikiSyntaxProvider
-
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