~cbehrens/nova/lp844160-build-works-with-zones

<?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: Writing a twistd Plugin</title>

</head>

<h1 class="title">Writing a twistd Plugin</h1>

<div class="toc"><ol><li><a href="#auto0">Goals</a></li><li><a href="#auto1">A note on .tap files</a></li><li><a href="#auto2">Alternatives to twistd plugins</a></li><li><a href="#auto3">Creating the plugin</a></li><li><a href="#auto4">Using cred with your TAP</a></li><li><a href="#auto5">Conclusion</a></li></ol></div>

This document describes adding subcommands to

the <code>twistd</code> command, as a way to facilitate the deployment

of your applications. (This feature was added in Twisted 2.5)

The target audience of this document are those that have developed

a Twisted application which needs a command line-based deployment

mechanism.

There are a few prerequisites to understanding this document:

<ul>

<li>A basic understanding of the Twisted Plugin System (i.e.,

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) is

necessary, however, step-by-step instructions will be

given. Reading <a href="plugin.html" shape="rect">The Twisted Plugin

System</a> is recommended, in particular the <q>Extending an

Existing Program</q> section.</li>

<li>The <a href="application.html" shape="rect">Application</a> infrastructure

is used in <code>twistd</code> plugins; in particular, you should

know how to expose your program's functionality as a Service.</li>

<li>In order to parse command line arguments, the <code>twistd</code> plugin

mechanism relies

on <code>twisted.python.usage</code>, which is documented

in <a href="options.html" shape="rect">Using usage.Options</a>.</li>

</ul>

<h2>Goals<a name="auto0"/></h2>

After reading this document, the reader should be able to expose

their Service-using application as a subcommand

of <code>twistd</code>, taking into consideration whatever was passed

on the command line.

<h2>A note on .tap files<a name="auto1"/></h2>

Readers may be confused about a historical file type associated

with Twisted, the <code>.tap</code> file. This was a kind of file that

was generated by a program named <code>mktap</code> and

which <code>twistd</code> can read. <code>.tap</code> files are

deprecated; this document has nothing to do with them, although the

technology described herein is very closely related to the old

system. Existing plugins that were written for the mktap system are

compatible with this <code>twistd</code> plugin system; the following

commands,

$ mktap [foo] [options...]

$ twistd -n -f [foo].tap

</pre>

are equivalent to the command:

<pre class="shell" xml:space="preserve">$ twistd -n [foo] [options...]</pre>

<h2>Alternatives to twistd plugins<a name="auto2"/></h2>

The major alternative to the twistd plugin mechanism is the <code>.tac</code>

file, which is a simple script to be used with the

twistd <code>-y/--python</code> parameter. The twistd plugin mechanism

exists to offer a more extensible command-line-driven interface to

your application. For more information on <code>.tac</code> files, see

the document <a href="application.html" shape="rect">Using the Twisted Application

Framework</a>.

<h2>Creating the plugin<a name="auto3"/></h2>

The following directory structure is assumed of your project:

<ul>

<li>MyProject - Top level directory

<ul>

<li>myproject - Python package

</li>

</ul>

</li>

</ul>

During development of your project, Twisted plugins can be loaded

from a special directory in your project, assuming your top level

directory ends up in sys.path. Create a directory

named <code>twisted</code> containing a directory

named <code>plugins</code>, and add a file

named <code>myproject_plugin.py</code> to it. This file will contain your

plugin. Note that you should not add any __init__.py files

100

to this directory structure, and the plugin file should not

101

be named <code>myproject.py</code> (because that would conflict with

102

your project's module name).

103

104

105

106

In this file, define an object which provides the interfaces

107

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

108

and <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.service.IServiceMaker.html" title="twisted.application.service.IServiceMaker">twisted.application.service.IServiceMaker</a></code>.

109

110

111

The <code>tapname</code> attribute of your IServiceMaker provider

112

will be used as the subcommand name in a command

113

like <code class="shell">twistd [subcommand] [args...]</code>, and

114

the <code>options</code> attribute (which should be

115

a <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.usage.Options.html" title="twisted.python.usage.Options">usage.Options</a></code>

116

subclass) will be used to parse the given args.

117

118

<pre class="python"> 1

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

from zope.interface import implements

151

152

from twisted.python import usage

153

from twisted.plugin import IPlugin

154

from twisted.application.service import IServiceMaker

155

from twisted.application import internet

156

157

from myproject import MyFactory

158

159

160

class Options(usage.Options):

161

optParameters = [["port", "p", 1235, "The port number to listen on."]]

162

163

164

class MyServiceMaker(object):

165

implements(IServiceMaker, IPlugin)

166

tapname = "myproject"

167

description = "Run this! It'll make your dog happy."

168

options = Options

169

170

def makeService(self, options):

171

"""

172

Construct a TCPServer from a factory defined in myproject.

173

"""

174

return internet.TCPServer(int(options["port"]), MyFactory())

175

176

177

# Now construct an object which *provides* the relevant interfaces

178

# The name of this variable is irrelevant, as long as there is *some*

179

# name bound to a provider of IPlugin and IServiceMaker.

180

181

serviceMaker = MyServiceMaker()

182

</pre>

183

184

185

Now running <code class="shell">twistd --help</code> should

186

print <code>myproject</code> in the list of available subcommands,

187

followed by the description that we specified in the

188

plugin. <code class="shell">twistd -n myproject</code> would,

189

assuming we defined a <code>MyFactory</code> factory

190

inside <code>myproject</code>, start a listening server on port 1235

191

with that factory.

192

193

194

<h2>Using cred with your TAP<a name="auto4"/></h2>

195

196

197

Twisted ships with a robust authentication framework to use with

198

your application. If your server needs authentication functionality,

199

and you haven't read about <a href="cred.html" shape="rect">twisted.cred</a>

200

yet, read up on it first.

201

202

203

204

If you are building a twistd plugin and you want to support a wide

205

variety of authentication patterns, Twisted provides an easy-to-use

206

mixin for your Options subclass:

207

<code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.cred.strcred.AuthOptionMixin.html" title="twisted.cred.strcred.AuthOptionMixin">strcred.AuthOptionMixin</a></code>.

208

The following code is an example of using this mixin:

209

210

211

<pre class="python"> 1

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

from twisted.cred import credentials, portal, strcred

260

261

262

263

from myserver import myservice

264

265

class ServerOptions(usage.Options, strcred.AuthOptionMixin):

266

# This part is optional; it tells AuthOptionMixin what

267

# kinds of credential interfaces the user can give us.

268

supportedInterfaces = (credentials.IUsernamePassword,)

269

270

optParameters = [

271

["port", "p", 1234, "Server port number"],

272

["host", "h", "localhost", "Server hostname"]]

273

274

class MyServerServiceMaker(object):

275

implements(IServiceMaker, IPlugin)

276

tapname = "myserver"

277

description = "This server does nothing productive."

278

options = ServerOptions

279

280

def makeService(self, options):

281

"""Construct a service object."""

282

# The realm is a custom object that your server defines.

283

realm = myservice.MyServerRealm(options["host"])

284

285

# The portal is something Cred can provide, as long as

286

# you have a list of checkers that you'll support. This

287

# list is provided my AuthOptionMixin.

288

portal = portal.Portal(realm, options["credCheckers"])

289

290

# OR, if you know you might get multiple interfaces, and

291

# only want to give your application one of them, you

292

# also have that option with AuthOptionMixin:

293

interface = credentials.IUsernamePassword

294

295

296

# The protocol factory is, like the realm, something you implement.

297

factory = myservice.ServerFactory(realm, portal)

298

299

# Finally, return a service that will listen for connections.

300

301

302

303

# As in our example above, we have to construct an object that

304

# provides the IPlugin and IServiceMaker interfaces.

305

306

serviceMaker = MyServerServiceMaker()

307

</pre>

308

309

310

Now that you have your TAP configured to support any authentication

311

we can throw at it, you're ready to use it. Here is an example of

312

starting your server using the /etc/passwd file for

313

authentication. (Clearly, this won't work on servers with shadow

314

passwords.)

315

316

317

318

$ twistd myserver --auth passwd:/etc/passwd

319

</pre>

320

321

322

For a full list of cred plugins supported, see <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.plugins.html" title="twisted.plugins">twisted.plugins</a></code>, or use the command-line help:

323

324

325

326

$ twistd myserver --help-auth

327

$ twistd myserver --help-auth-type passwd

328

</pre>

329

330

<h2>Conclusion<a name="auto5"/></h2>

331

332

You should now be able to

333

<ul>

334

<li>Create a twistd plugin</li>

335

<li>Incorporate authentication into your plugin</li>

336

<li>Use it from your development environment</li>

337

<li>Install it correctly and use it in deployment</li>

338

</ul>

339

340

341

</div>

342

343

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

344

Version: 10.0.0

345

</body>

346

</html>

b'\\ No newline at end of file'

Older »