~justin-fathomdb/nova/justinsb-openstack-api-volumes

<?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'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<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/10.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

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"/></h2>

Taking advantage of <code class="API"><a href="http://twistedmatrix.com/documents/10.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/10.0.0/api/twisted.plugin.getPlugins.html" title="twisted.plugin.getPlugins">twisted.plugin.getPlugins</a></code> and iterate over its

result.

</li>

</ol>

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

definition for a physical modelling system.

<pre class="python"> 1

from zope.interface import Interface, Attribute

class IMaterial(Interface):

"""

An object with specific physical properties

"""

100

def yieldStress(temperature):

101

"""

102

Returns the pressure this material can support without

103

fracturing at the given temperature.

104

105

@type temperature: C{float}

106

@param temperature: Kelvins

107

108

@rtype: C{float}

109

@return: Pascals

110

"""

111

112

dielectricConstant = Attribute("""

113

@type dielectricConstant: C{complex}

114

@ivar dielectricConstant: The relative permittivity, with the

115

real part giving reflective surface properties and the

116

imaginary part giving the radio absorption coefficient.

117

""")

118

</pre>

119

120

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

121

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

122

123

<pre class="python">1

124

125

126

def displayMaterial(m):

127

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

128

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

129

</pre>

130

131

The last piece of required code is that which collects

132

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

133

<code>displayMaterial</code> function.

134

135

<pre class="python">1

136

137

138

139

140

141

from twisted.plugin import getPlugins

142

from matsim import imatsim

143

144

def displayAllKnownMaterials():

145

for material in getPlugins(imatsim.IMaterial):

146

displayMaterial(material)

147

</pre>

148

149

Third party developers may now contribute different materials

150

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

151

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

152

153

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

154

155

The above code demonstrates how an extensible program might be

156

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

157

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

158

required interface and then make them available at a particular

159

location. Consider the following example.

160

161

<pre class="python"> 1

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

from twisted.plugin import IPlugin

179

from matsim import imatsim

180

181

class SimpleMaterial(object):

182

implements(IPlugin, imatsim.IMaterial)

183

184

def __init__(self, yieldStressFactor, dielectricConstant):

185

self._yieldStressFactor = yieldStressFactor

186

self.dielectricConstant = dielectricConstant

187

188

def yieldStress(self, temperature):

189

return self._yieldStressFactor * temperature

190

191

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

192

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

193

</pre>

194

195

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

196

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

197

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

198

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

199

primarily useful during development: if a directory which

200

has been added to <code>sys.path</code> (typically by adding it to the

201

<code class="shell">PYTHONPATH</code> environment variable) contains a

202

directory named <code class="shell">twisted/plugins/</code>,

203

each <code class="shell">.py</code> file in that directory will be loaded

204

as a source of plugins. This directory must not be a Python

205

package: including <code class="shell">__init__.py</code> will cause the

206

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

207

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

208

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

209

plugins.

210

211

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

212

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

213

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

214

plate.

215

216

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

217

218

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

219

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

220

should be a module or package to be used instead of

221

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

222

are writing a plugin for a Twisted interface, you should never

223

need to pass this argument. However, if you have developed an

224

interface of your own, you may want to mandate that plugins for it

225

are installed in your own plugins package, rather than in

226

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

227

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

228

the following lines.

229

230

<pre class="python">1

231

232

233

234

__path__.extend(pluginPackagePaths(__name__))

235

__all__ = []

236

</pre>

237

238

The key behavior here is that interfaces are essentially paired

239

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

240

different package than the one the code which relies on the

241

interface they provide, they will not be found when the

242

application goes to load them.

243

244

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

245

246

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

247

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

248

various locations. These files are used to cache information

249

about what plugins are present in the directory which contains

250

them. At times, this cached information may become out of date.

251

Twisted uses the mtimes of various files involved in the plugin

252

system to determine when this cache may have become invalid.

253

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

254

it but finds it out of date.

255

256

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

257

possible for applications running as normal users to rewrite the

258

cache file. While these applications will still run and find

259

correct plugin information, they may run more slowly than they

260

would if the cache was up to date, and they may also report

261

exceptions if certain plugins have been removed but which the

262

cache still references. For these reasons, when installing or

263

removing software which provides Twisted plugins, the site

264

administrator should be sure the cache is regenerated.

265

Well-behaved package managers for such software should take this

266

task upon themselves, since it is trivially automatable. The

267

canonical way to regenerate the cache is to run the following

268

Python code:

269

270

<pre class="python">1

271

272

273

list(getPlugins(IPlugin))

274

</pre>

275

276

As mentioned, it is normal for exceptions to be raised

277

once here if plugins have been removed.

278

279

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

280

281

<ul>

282

283

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

284

285

</ul>

286

287

</div>

288

289

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

290

Version: 10.0.0

291

</body>

292

</html>

b'\\ No newline at end of file'

Older »