~certify-web-dev/twisted/certify-staging

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml" lang="en"><head><title>Twisted Documentation: The Twisted Plugin System</title><link href="stylesheet.css" type="text/css" rel="stylesheet" /></head><body bgcolor="white"><h1 class="title">The Twisted Plugin System</h1><div class="toc"><ol><li><a href="#auto0">Writing Extensible Programs</a></li><li><a href="#auto1">Extending an Existing Program</a></li><li><a href="#auto2">Alternate Plugin Packages</a></li><li><a href="#auto3">Plugin Caching</a></li><li><a href="#auto4">Further Reading</a></li></ol></div><div class="content">The purpose of this guide is to describe the preferred way to

<?xml version="1.0" encoding="utf-8"?>

<!DOCTYPE html

PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN'

'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'>

<head>

<title>Twisted Documentation: The Twisted Plugin System</title>

</head>

<h1 class="title">The Twisted Plugin System</h1>

<div class="toc"><ol><li><a href="#auto0">Writing Extensible Programs</a></li><li><a href="#auto1">Extending an Existing Program</a></li><li><a href="#auto2">Alternate Plugin Packages</a></li><li><a href="#auto3">Plugin Caching</a></li><li><a href="#auto4">Further Reading</a></li></ol></div>

The purpose of this guide is to describe the preferred way to

write extensible Twisted applications (and consequently, also to

describe how to extend applications written in such a way). This

extensibility is achieved through the definition of one or more

APIs and a mechanism for collecting code plugins which

implement this API to provide some additional functionality.

At the base of this system is the <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.plugin.html" title="twisted.plugin">twisted.plugin</a></code> module.Making an application extensible using the plugin system has

several strong advantages over other techniques:<ul><li>It allows third-party developers to easily enhance your

At the base of this system is the <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.plugin.html" title="twisted.plugin">twisted.plugin</a></code> module.

Making an application extensible using the plugin system has

several strong advantages over other techniques:

<ul>

<li>It allows third-party developers to easily enhance your

software in a way that is loosely coupled: only the plugin API

is required to remain stable.</li><li>It allows new plugins to be discovered flexibly. For

is required to remain stable.</li>

<li>It allows new plugins to be discovered flexibly. For

example, plugins can be loaded and saved when a program is first

run, or re-discovered each time the program starts up, or they

can be polled for repeatedly at runtime (allowing the discovery

of new plugins installed after the program has started).</li></ul><h2>Writing Extensible Programs<a name="auto0"></a></h2>Taking advantage of <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.plugin.html" title="twisted.plugin">twisted.plugin</a></code> is

a two step process:<ol><li>

of new plugins installed after the program has started).</li>

</ul>

<h2>Writing Extensible Programs<a name="auto0"/></h2>

Taking advantage of <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.plugin.html" title="twisted.plugin">twisted.plugin</a></code> is

a two step process:

<ol>

<li>

Define an interface which plugins will be required to implement.

This is done using the zope.interface package in the same way one

would define an interface for any other purpose.

A convention for defining interfaces is do so in a file named like

ProjectName/projectname/iprojectname.py. The rest of this

document will follow that convention: consider the following

interface definition be in <code>Matsim/matsim/imatsim.py</code>, an

interface definition module for a hypothetical material simulation

package.

</li><li>

At one or more places in your program, invoke <code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.plugin.getPlugins.html" title="twisted.plugin.getPlugins">twisted.plugin.getPlugins</a></code> and iterate over its

</li>

<li>

At one or more places in your program, invoke <code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.plugin.getPlugins.html" title="twisted.plugin.getPlugins">twisted.plugin.getPlugins</a></code> and iterate over its

result.

</li></ol>

</li>

</ol>

As an example of the first step, consider the following interface

definition for a physical modelling system.

from zope.interface import Interface, Attribute

<pre class="python"> 1

from zope.interface import Interface, Attribute

100

class IMaterial(Interface):

101

"""

119

real part giving reflective surface properties and the

120

imaginary part giving the radio absorption coefficient.

121

""")

</pre>In another module, we might have a function that operates on

objects providing the <code>IMaterial</code> interface:<pre class="python">

def displayMaterial(m):

122

</pre>

123

124

In another module, we might have a function that operates on

125

objects providing the <code>IMaterial</code> interface:

126

127

<pre class="python">1

128

129

130

def displayMaterial(m):

131

print 'A material with yield stress %s at 500 K' % (m.yieldStress(500),)

132

print 'Also a dielectric constant of %s.' % (m.dielectricConstant,)

</pre>The last piece of required code is that which collects

133

</pre>

134

135

The last piece of required code is that which collects

136

<code>IMaterial</code> providers and passes them to the

<code>displayMaterial</code> function.<pre class="python">

from twisted.plugin import getPlugins

137

<code>displayMaterial</code> function.

138

139

<pre class="python">1

140

141

142

143

144

145

from twisted.plugin import getPlugins

146

from matsim import imatsim

147

148

def displayAllKnownMaterials():

149

for material in getPlugins(imatsim.IMaterial):

150

displayMaterial(material)

</pre>Third party developers may now contribute different materials

151

</pre>

152

153

Third party developers may now contribute different materials

154

to be used by this modelling system by implementing one or more

plugins for the <code>IMaterial</code> interface.<h2>Extending an Existing Program<a name="auto1"></a></h2>The above code demonstrates how an extensible program might be

155

plugins for the <code>IMaterial</code> interface.

156

157

<h2>Extending an Existing Program<a name="auto1"/></h2>

158

159

The above code demonstrates how an extensible program might be

160

written using Twisted's plugin system. How do we write plugins

161

for it, though? Essentially, we create objects which provide the

162

required interface and then make them available at a particular

location. Consider the following example.<pre class="python">

163

location. Consider the following example.

164

165

<pre class="python"> 1

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

from matsim import imatsim

184

194

195

steelPlate = SimpleMaterial(2.06842719e11, 2.7 + 0.2j)

196

brassPlate = SimpleMaterial(1.03421359e11, 1.4 + 0.5j)

</pre><code>steelPlate</code> and <code>brassPlate</code> now provide both

<code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.plugin.IPlugin.html" title="twisted.plugin.IPlugin">IPlugin</a></code> and <code>IMaterial</code>.

197

</pre>

198

199

<code>steelPlate</code> and <code>brassPlate</code> now provide both

200

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.plugin.IPlugin.html" title="twisted.plugin.IPlugin">IPlugin</a></code> and <code>IMaterial</code>.

201

All that remains is to make this module available at an appropriate

202

location. For this, there are two options. The first of these is

203

primarily useful during development: if a directory which

106

210

directory to be skipped and no plugins loaded from it. Second, each

107

211

module in the installed version of Twisted's <code class="shell">

108

212

twisted.plugins</code> package will also be loaded as a source of

109

plugins.Once this plugin is installed in one of these two ways,

213

plugins.

214

215

Once this plugin is installed in one of these two ways,

110

216

<code>displayAllKnownMaterials</code> can be run and we will see

111

217

two pairs of output: one for a steel plate and one for a brass

112

plate.<h2>Alternate Plugin Packages<a name="auto2"></a></h2><code class="API"><a href="http://twistedmatrix.com/documents/8.2.0/api/twisted.plugin.getPlugins.html" title="twisted.plugin.getPlugins">getPlugins</a></code> takes one

218

plate.

219

220

<h2>Alternate Plugin Packages<a name="auto2"/></h2>

221

222

<code class="API"><a href="http://twistedmatrix.com/documents/9.0.0/api/twisted.plugin.getPlugins.html" title="twisted.plugin.getPlugins">getPlugins</a></code> takes one

113

223

additional argument not mentioned above. If passed in, the 2nd argument

114

224

should be a module or package to be used instead of

115

225

<code>twisted.plugins</code> as the plugin meta-package. If you

119

229

are installed in your own plugins package, rather than in

120

230

Twisted's. In this case, you probably also want to support <code class="shell">yourproject/plugins/</code> directories for ease of

121

231

development. To do so, you should make the <code class="shell">__init__.py</code> for that package contain at least

122

the following lines.<pre class="python">

123

232

the following lines.

233

234

<pre class="python">1

235

236

237

124

238

__path__.extend(pluginPackagePaths(__name__))

125

239

__all__ = []

126

</pre>The key behavior here is that interfaces are essentially paired

240

</pre>

241

242

The key behavior here is that interfaces are essentially paired

127

243

with a particular plugin package. If plugins are installed in a

128

244

different package than the one the code which relies on the

129

245

interface they provide, they will not be found when the

130

application goes to load them.<h2>Plugin Caching<a name="auto3"></a></h2>In the course of using the Twisted plugin system, you may

246

application goes to load them.

247

248

<h2>Plugin Caching<a name="auto3"/></h2>

249

250

In the course of using the Twisted plugin system, you may

131

251

notice <code class="shell">dropin.cache</code> files appearing at

132

252

various locations. These files are used to cache information

133

253

about what plugins are present in the directory which contains

135

255

Twisted uses the mtimes of various files involved in the plugin

136

256

system to determine when this cache may have become invalid.

137

257

Twisted will try to re-write the cache each time it tries to use

138

it but finds it out of date.For a site-wide install, it may not (indeed, should not) be

258

it but finds it out of date.

259

260

For a site-wide install, it may not (indeed, should not) be

139

261

possible for applications running as normal users to rewrite the

140

262

cache file. While these applications will still run and find

141

263

correct plugin information, they may run more slowly than they

147

269

Well-behaved package managers for such software should take this

148

270

task upon themselves, since it is trivially automatable. The

149

271

canonical way to regenerate the cache is to run the following

150

Python code:<pre class="python">

151

272

Python code:

273

274

<pre class="python">1

275

276

152

277

list(getPlugins(IPlugin))

153

</pre>As mentioned, it is normal for exceptions to be raised

154

once here if plugins have been removed.<h2>Further Reading<a name="auto4"></a></h2><ul><li><a href="components.html">Components: Interfaces and Adapters</a></li></ul></div><a href="index.html">Index</a>Version: 8.2.0</body></html>

b'\\ No newline at end of file'

278

</pre>

279

280

As mentioned, it is normal for exceptions to be raised

281

once here if plugins have been removed.

282

283

<h2>Further Reading<a name="auto4"/></h2>

284

285

<ul>

286

287

<li><a href="components.html" shape="rect">Components: Interfaces and Adapters</a></li>

288

289

</ul>

290

291

</div>

292

293

<a href="index.html">Index</a>

294

Version: 9.0.0

295

</body>

296

</html>

b'\\ No newline at end of file'

Older »