编写Trac插件

原文：  http://trac.edgewall.org/wiki/TracDev/PluginDevelopment

Writing Plugins for Trac¶

编写Trac插件

Starting with version 0.9 , you can develop plugins for Trac that extend the 
builtin functionality. The plugin functionality is based on the component architecture , so please 
read that document before continuing here.

从0.9版本开始，你可以开发trac插件，来扩展trac的内置功能。插件功能基于组件架构，所以请先阅读那份文档，然后才继续。

Extension points¶

扩展点

Trac offers an increasing number of extension points  that allow you to 
plugin custom extensions for various functions. You can view a list of provided 
extension points on the page About Trac/Plugins  of your Trac 
installation.

Trac提供越来越多的扩展点，允许你自定义插件来扩展各种功能。你可以在你安装的Trac系统中关于Trac/Plugins 页面查看一份支持可用扩展点的列表。

Currently we have:

目前我们有以下扩展点：

trac.env.IEnvironmentSetupParticipant

Allows plugins to participate in the creation and upgrade of the 
environment. Can be used to setup additional database tables or directories 
needed for the plugin to operate 

允许插件参与environment的创建和更新。可用于安装插件所需要的额外的数据表或者目录

trac.web.api.IRequestHandler

Allows plugins to add handlers for HTTP requests. 

允许插件新增响应HTTP请求的。

trac.web.api.IRequestFilter

Allows plugins to add filters to the HTTP requests. 

允许插件添加新的HTTP请求过滤器

trac.web.chrome.INavigationContributor

Allows plugins to extend the navigation menus of the web interface. 

允许插件扩展web界面的导航菜单

trac.web.chrome.ITemplateProvider

Extension point interface for components that provide their own  ClearSilver  templates and accompanying static resources. 

这个扩展点接口允许组件提供他们自己的ClearSilver模板 和 附属静态资源。

trac.perm.IPermissionRequestor

Plugins can use this extension point to define additional "actions" for the 
permission system. 

插件可以使用这个扩展点来定义permission system的额外的"功能"

trac.timeline.ITimelineEventProvider

Allows plugins to contribute events to the  timeline . 

允许插件在timeline发布事件

trac.mimeview.api.IHTMLPreviewRenderer

Allows plugins to provide support for rendering specific content of a 
specific type as HTML (used for  TracSyntaxColoring  and image preview) 

允许插件提供对HTML特殊类型的渲染具体内容的支持(被TracSyntaxColoring和图片预览(image preview)使用)

trac.wiki.api.IWikiChangeListener

Allows plugins to observe creation, modification and deletion of wiki pages.

允许插件监听wiki页面的创建、修改和删除。

trac.wiki.api.IWikiMacroProvider

Allows plugins to contribute  WikiMacros  to Trac. 

允许插件为Trac贡献WikiMacro

trac.wiki.api.IWikiSyntaxProvider

Plugins can extend this extension point to add custom syntax rules to the 
wiki formatting system. In particular, this allows registration of additional  TracLinks  types. 

插件可以扩展这个扩展点，为wiki format system 添加定制的语法规则。尤其，允许注册额外的TracLinks类型。

trac.ticket.api.ITicketChangeListener

Extension point interface for components that require notification when 
tickets are created, modified, or deleted.

当传票(tickets)被、修改或删除时，需要被通知的组件需要这个扩展接口。

Note that plugins can themselves add new extension points, so the list 
above is incomplete by nature.

注意插件它们自己可以添加新的扩展点，所以从本质上说上面的列表是不完全的。

Writing the plugin code¶

编写插件代码

To extend Trac with a custom plugin, you need to implement a 
component . For example, to add a new web module to Trac (i.e. a component 
that handles HTTP requests and extends the navigation bar), you'd start with 
something like the following code:

为了用一个定制的插件扩展Trac, 你需要实现一个组件。例如，向Trac添加一个新的web模块(如，这个组件能够处理HTTP请求和扩展导航栏)，你应该使用类似下面代码来开始: 

from
 trac.core
 import
 *


from
 trac.util.html
 import
 html

from
 trac.web
 import
 IRequestHandler

from
 trac.web.chrome
 import
 INavigationContributor



class
 HelloWorldPlugin
(
Component):


    implements(
INavigationContributor,
 IRequestHandler)




    # INavigationContributor methods


    def
 get_active_navigation_item
(
self
,
 req):


        return
 'helloworld'


    def
 get_navigation_items
(
self
,
 req):


        yield
 (
'mainnav'
,
 'helloworld'
,


            html.
A(
'Hello world'
,
 href=
 req.
href.
helloworld()))




    # IRequestHandler methods


    def
 match_request
(
self
,
 req):


        return
 req.
path_info ==
 '/helloworld'


    def
 process_request
(
self
,
 req):


        req.
send_response(
200
)


        req.
send_header(
'Content-Type'
,
 'text/plain'
)


        req.
end_headers()


        req.
write(
'Hello world!'
)

Look at the API documentation for the extension point interfaces to see what 
you're expected to return. See the tutorial  
page for more plugin tutorials.

查看API文档获得你想查找的扩展接口。 阅读技巧页面获得更多的插件技巧。

Component member variables¶

组件的成员变量

Every component that gets instantiated through the Trac environment gets 
three extra member variables for convenience:

为了方便起见， 从Trac environment 获取实例的每个组件拥有3个额外的成员变量。

• 
  
• env : The environment, an instance of the 
  trac.env.Environment  class (see trac.env ). 
• env: 环境，类 trac.env.Environment 的实例
• config : The configuration, an instance of the 
  trac.config.Configuration  class (see trac.config ). 
• config: 配置，类trac.config.Configuration的实例
• log : The configured logger, see the Python logging 
  API  for more information.
• log： 配置日志，阅读python的日志API获取更多信息

These variables can also be accessed from the initializer (__init__ ) 
of a component.

这些变量也可以从组件的nitializer ( __init__ ) 方法访问。

Storing any other objects as instance variables of your component is probably 
a bad idea: remember that a component is only instantiated once for a given 
environment; unless your plugin is used in a CGI deployment of Trac, that means 
that the same component instance will get invoked for multiple HTTP requests; if 
the server is multi-threaded, this will even happen concurrently.

保存其他任何像你的组件实例变量的对象很可能是一个坏主意：记住一个组件在一个environment只实例化一次；除非你的插件是用于Trac的CGI部署，这意味着同样的组件实例会被多个HTTP请求调用；如果服务器是多线程的，甚至会同时发生。

Packaging plugins¶

打包插件

TracPlugins  are packaged as Python Eggs . You can use setuptools  to make a setup.py  script that will produce a Python egg for your plugin.

TracPlugins 以 Python Eggs方式打包。  你可以使用 setuptools 来生成 setup.py 脚本，这个脚本会生成你插件的python egg文件。 

The egg needs to export an entry point  group named trac.plugins , listing the 
names of the modules that Trac should import for the plugin-provided  components 
to get registered. For example:

这个egg文件需要导出一个名为trac.plugins的入口点组(entry point group), 这个入口点列出Trac会导入需要注册的组件的模块。

from
 setuptools
 import
 find_packages,
 setup



setup(


    name=
'TracHelloWorld'
,
 version=
'1.0'
,


    packages=
find_packages(
exclude=
[
'*.tests*'
]),


    entry_points =
 """

        [trac.plugins]

        helloworld = myplugs.helloworld

    """
,


)

This assumes that the HelloWorldPlugin  example above is defined in 
the module helloworld.py  in the myplugs  package. The entry 
point name  (in this example “helloworld”) is required by the Python egg 
runtime, but not currently used by Trac. In most cases, you can simply use the 
qualified module name there.

假设上面的HelloWorldPlugin例子是在myplugins包的helloworld.py模块里定义。python egg运行时需要入口点名字(在这个例子是"helloworld")，但当前的Trac不需要。 大多数情况下，在这里你可以简单有限制的模块名字

For backwards-compatibility reasons, Trac still supports an alternative to 
entry points: you can have a file named trac_plugin.txt  in the 
EGG-INFO  directory. This file should contain the names of all modules 
that need to be imported by Trac to register your components. Note that this 
method is deprecated  and will be removed in a future version of 
Trac (probably as soon as 0.11 ).

          由于 向后兼容原因，Trac仍然支持另一种入口点：你可以在 EGG_INFO 目录下有一个                       trac_plugin.txt 文件。这个文件包含了Trac注册你组件所需的所有模块的名字。注意这                  个方法不推荐使用，在Trac的未来版本会被移除(最快可能是0.11版本)

Plugin deployment¶

部署插件

A plugin can either be deployed globally, or only for a specific environment. 
Global deployment is done by installing the plugin:

一个插件可以全局部署，也可以只对特定的environment部署。 通过安装该插件完成全局部署:

$ cd /path/to/pluginsource

$ python setup.py install

To deploy a plugin only to a specific Trac environment, copy the egg file 
into the plugins  directory of that environment:

为了仅对某个Trac environment部署插件，把文件file拷贝到environment的plugins目录。

$ cd /path/to/pluginsource

$ python setup.py bdist_egg

$ cp dist/*.egg /path/to/projenv/plugins

During development of a plugin, it is inconvenient to have to install it in 
either of the ways described above. Instead, you should use the setuptools 
develop  command:

在开发插件期间，通过上面两种方法安装插件都是不方便的。 相反，你可以使用 setuptools的develop  命令：

$ cd /path/to/pluginsource

$ python setup.py develop --multi-version --install-dir /path/to/projenv/plugins

or the short version :

或者

$ python setup.py develop -md /path/to/projenv/plugins

You can omit the --install-dir  and --multi-version  
arguments to make the development version of your plugin available globally.

你可以省略 --install-dir 和 --multi-version参数，使得开发版本的插件在全局范围起作用。

This will install an .egg-link  file instead of the actual egg. That 
file is basically a link to the source directory of your plugin, so that Trac 
will always see the latest version of your code. In this case you will have to 
explicitly enable your plugin in the trac configuration as explained on TracPlugins .

它会安装一个文件.egg-link 取代实际的egg文件。这个文件基本上是插件源代码目录的链接，所以Trac

总是会找到最新版本的代码。在这种情况下，你必须像TracPlugins解释的那样，明确地在trac的配置是插件可用。

A tutorial to build your own plugins is available here .

一个编译插件的技巧可在这里找到。

Disabling built-in components¶

禁止内置组件

Sometimes you might want to write a plugin that completely replaces a 
built-in component, for example to develop an advanced variant of an existing 
module. Trac uses a list of default component to load , as specified in the 
default_components  list in trac.db_default . These built-in components are always loaded, and might therefore conflict with your replacement plugin.

有时你可能想写一个插件，完全取代一个内置的组件，例如开发一个现有模块的高级衍生版。

这些内置组件总会被加载，因此可能与你的取代插件冲突。

You can however disable built-in components using a special trac.ini  section called [components] . This section contains the qualified name of the components to disable, along with 
disabled  or off  as the value.

你可以使用trac.ini特殊字段[components] 来禁止内置组件。这个字段包含了被禁用组件正确的名字，紧接着

disable 或 off 值。

For example, to disable the built-in Wiki macro RecentChanges , you'd 
include the following in trac.ini :

例如，为了禁止内置的wiki宏 RecentChanges组件，你应该在trac.ini包含下面配置:

[components]

trac.wiki.macros.RecentChangesMacro = disabled

You can also use a wildcard at the end of a name, so you could even disable 
the complete Wiki module (although wiki formatting will still work in the 
remaining modules, of course):

你也可以在名字后面使用通配符，你可能是禁止wiki所有模块（当然，在余下模块的wiki 格式组件仍然运行）

[components]

trac.wiki.* = disabled

Debugging¶

调试

The logging API is very good debugging tool. Simply use this code when you 
want to view value of a variable:

日志记录API 是一个非常好用的调试工具。当你想查看一个变量的指时，可以很简单地使用下面的代码:

  env.log.info(varname) or self.env.log.info(varname)

You need to turn on logging in the trac.ini file. Info level log is not as 
often as debug level. Thus it is very good way to debug the plug-in code. 
However, you should use debug method if you want to leave the code when you 
finish developing the plug-in.

你需要在trac.ini文件里打开日志功能。 Info级别不像调试级别经常使用。因此，这是一种很好的调试你插件代码的方式。不过， 当你完成开发插件时还想保留代码，应该使用debug方法。