~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: Using the Twisted Application Framework</title>

</head>

<h1 class="title">Using the Twisted Application Framework</h1>

<div class="toc"><ol><li><a href="#auto0">Introduction</a></li><ul><li><a href="#auto1">Audience</a></li><li><a href="#auto2">Goals</a></li></ul><li><a href="#auto3">Overview</a></li><li><a href="#auto4">Using application</a></li><ul><li><a href="#auto5">twistd and tac</a></li><li><a href="#auto6">Customizing twistd logging in a .tac application</a></li><li><a href="#auto7">Services provided by Twisted</a></li><li><a href="#auto8">Service Collection</a></li></ul></ol></div>

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

<h3>Audience<a name="auto1"/></h3>

The target audience of this document is a Twisted user who wants to deploy a

significant amount of Twisted code in a re-usable, standard and easily

configurable fashion. A Twisted user who wishes to use the Application

framework needs to be familiar with developing Twisted <a href="servers.html" shape="rect">servers</a> and/or <a href="clients.html" shape="rect">clients</a>.

<h3>Goals<a name="auto2"/></h3>

<ul>

<li>To introduce the Twisted Application infrastructure.</li>

<li>To explain how to deploy your Twisted application using <code>.tac</code>

files and <code>twistd</code></li>

<li>To outline the existing Twisted services.</li>

</ul>

<h2>Overview<a name="auto3"/></h2>

The Twisted Application infrastructure takes care of running and stopping

your application. Using this infrastructure frees you from from having to

write a large amount of boilerplate code by hooking your application into

existing tools that manage daemonization, logging, <a href="choosing-reactor.html" shape="rect">choosing a reactor</a> and more.

The major tool that manages Twisted applications is a command-line utility

called <code>twistd</code>. <code>twistd</code> is cross platform, and is the

recommended tool for running Twisted applications.

The core component of the Twisted Application infrastructure is the <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.service.Application.html" title="twisted.application.service.Application">twisted.application.service.Application</a></code> object — an

object which represents your application. However, Application doesn't provide

anything that you'd want to manipulate directly. Instead, Application acts as

a container of any <q>Services</q> (objects implementing <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.service.IService.html" title="twisted.application.service.IService">IService</a></code>) that your application

provides. Most of your interaction with the Application infrastructure will be

done through Services.

By <q>Service</q>, we mean anything in your application that can be started

and stopped. Typical services include web servers, FTP servers and SSH

clients. Your Application object can contain many services, and can even

contain structured hierarchies of Services using <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.service.IServiceCollection.html" title="twisted.application.service.IServiceCollection">IServiceCollection</a></code>s.

Here's a simple example of constructing an Application object which

represents an echo server that runs on TCP port 7001.

<pre class="python"> 1

from twisted.application import internet, service

from somemodule import EchoFactory

port = 7001

factory = EchoFactory()

# this is the important bit

application = service.Application("echo") # create the Application

echoService = internet.TCPServer(port, factory) # create the service

# add the service to the application

echoService.setServiceParent(application)

</pre>

See <a href="servers.html" shape="rect">Writing Servers</a> for an explanation of

EchoFactory.

This example creates a simple hierarchy:

application

`- echoService

</pre> More complicated hierarchies of services can be created using

IServiceCollection. You will most likely want to do this to manage Services

which are dependent on other Services. For example, a proxying Twisted

application might want its server Service to only start up after the associated

Client service.

100

<h2>Using application<a name="auto4"/></h2>

101

102

<h3>twistd and tac<a name="auto5"/></h3><a name="twistd" shape="rect"/>

103

104

To handle start-up and configuration of your Twisted application, the

105

Twisted Application infrastructure uses <code>.tac</code> files.

106

<code>.tac</code> are Python files which configure an <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.service.Application.html" title="twisted.application.service.Application">Application</a></code> object and assign this

107

object to the top-level variable <q><code>application</code></q>.

108

109

The following is a simple example of a <code>.tac</code> file:

110

111

<div class="py-listing"><pre> 1

112

113

114

115

116

117

118

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

# You can run this .tac file directly with:

146

# twistd -ny service.tac

147

148

"""

149

This is an example .tac file which starts a webserver on port 8080 and

150

serves files from the current working directory.

151

152

The important part of this, the part that makes it a .tac file, is

153

the final root-level section, which sets up the object called 'application'

154

which twistd will look for

155

"""

156

157

import os

158

from twisted.application import service, internet

159

from twisted.web import static, server

160

161

def getWebService():

162

"""

163

Return a service suitable for creating an application object.

164

165

This service is a simple web server that serves files on port 8080 from

166

underneath the current working directory.

167

"""

168

# create a resource to serve static files

169

fileServer = server.Site(static.File(os.getcwd()))

170

return internet.TCPServer(8080, fileServer)

171

172

# this is the core part of any tac file, the creation of the root-level

173

# application object

174

application = service.Application("Demo application")

175

176

# attach the service to its parent application

177

service = getWebService()

178

service.setServiceParent(application)

179

</pre><div class="caption">Source listing - <a href="listings/application/service.tac">listings/application/service.tac</a></div></div>

180

181

<code>twistd</code> is a program that runs Twisted applications using a

182

<code>.tac</code> file. In its most simple form, it takes a single argument

183

<code>-y</code> and a tac file name. For example, you can run the above server

184

with the command <code class="shell">twistd -y service.tac</code>.

185

186

By default, <code>twistd</code> daemonizes and logs to a file called

187

<code>twistd.log</code>. More usually, when debugging, you will want your

188

application to run in the foreground and log to the command line. To run the

189

above file like this, use the command <code class="shell">twistd -noy

190

service.tac</code>

191

192

For more information, see the <code>twistd</code> man page.

193

194

<h3>Customizing <code>twistd</code> logging in a .tac application<a name="auto6"/></h3>

195

196

197

The logging behavior can be customized through an API

198

accessible from <code>.tac</code> files. The <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.log.ILogObserver.html" title="twisted.python.log.ILogObserver">ILogObserver</a></code> component can be

199

set on an Application in order to customize the default log observer that

200

<code>twistd</code> will use.

201

202

203

204

Here is an example of how to use <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.logfile.DailyLogFile.html" title="twisted.python.logfile.DailyLogFile">DailyLogFile</a></code>, which rotates the log once

205

per day.

206

207

208

<pre class="python">1

209

210

211

212

213

214

215

from twisted.application.service import Application

216

from twisted.python.log import ILogObserver, FileLogObserver

217

from twisted.python.logfile import DailyLogFile

218

219

application = Application("myapp")

220

logfile = DailyLogFile("my.log", "/tmp")

221

application.setComponent(ILogObserver, FileLogObserver(logfile).emit)

222

</pre>

223

224

225

invoking <code class="shell">twistd -y my.tac</code> will create a log file

226

at<code>/tmp/my.log</code>.

227

228

229

<h3>Services provided by Twisted<a name="auto7"/></h3>

230

231

Twisted provides several services that you want to know about.

232

233

Each of these services (except TimerService) has a corresponding

234

<q>connect</q> or <q>listen</q> method on the reactor, and the constructors for

235

the services take the same arguments as the reactor methods. The

236

<q>connect</q> methods are for clients and the <q>listen</q> methods are for

237

servers. For example, TCPServer corresponds to reactor.listenTCP and TCPClient

238

corresponds to reactor.connectTCP.

239

240

<dl>

241

<dt><code>TCPServer</code>

242

</dt>

243

244

<dt><code>TCPClient</code>

245

</dt>

246

247

<dd>

248

Services which allow you to make connections and listen for connections

249

on TCP ports.

250

<ul>

251

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorTCP.listenTCP.html" title="twisted.internet.interfaces.IReactorTCP.listenTCP">listenTCP</a></code></li>

252

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorTCP.connectTCP.html" title="twisted.internet.interfaces.IReactorTCP.connectTCP">connectTCP</a></code></li>

253

</ul>

254

</dd>

255

256

<dt><code>UNIXServer</code></dt>

257

258

<dt><code>UNIXClient</code></dt>

259

260

<dd>

261

Services which listen and make connections over UNIX sockets.

262

<ul>

263

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorUNIX.listenUNIX.html" title="twisted.internet.interfaces.IReactorUNIX.listenUNIX">listenUNIX</a></code></li>

264

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorUNIX.connectUNIX.html" title="twisted.internet.interfaces.IReactorUNIX.connectUNIX">connectUNIX</a></code></li>

265

</ul>

266

</dd>

267

268

<dt><code>SSLServer</code></dt>

269

270

<dt><code>SSLClient</code></dt>

271

272

<dd>Services which allow you to make SSL connections and run SSL servers.

273

<ul>

274

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorSSL.listenSSL.html" title="twisted.internet.interfaces.IReactorSSL.listenSSL">listenSSL</a></code></li>

275

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorSSL.connectSSL.html" title="twisted.internet.interfaces.IReactorSSL.connectSSL">connectSSL</a></code></li>

276

</ul>

277

</dd>

278

279

<dt><code>UDPServer</code></dt>

280

281

<dt><code>UDPClient</code></dt>

282

283

<dd>Services which allow you to send and receive data over UDP

284

<ul>

285

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorUDP.listenUDP.html" title="twisted.internet.interfaces.IReactorUDP.listenUDP">listenUDP</a></code></li>

286

</ul>

287

288

See also the <a href="udp.html" shape="rect">UDP documentation</a>.

289

</dd>

290

291

<dt><code>UNIXDatagramServer</code></dt>

292

293

<dt><code>UNIXDatagramClient</code></dt>

294

295

<dd>Services which send and receive data over UNIX datagram sockets.

296

<ul>

297

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorUDP.listenUNIXDatagram.html" title="twisted.internet.interfaces.IReactorUDP.listenUNIXDatagram">listenUNIXDatagram</a></code></li>

298

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorUDP.connectUNIXDatagram.html" title="twisted.internet.interfaces.IReactorUDP.connectUNIXDatagram">connectUNIXDatagram</a></code></li>

299

</ul>

300

</dd>

301

302

<dt><code>MulticastServer</code></dt>

303

304

<dd>

305

A server for UDP socket methods that support multicast.

306

<ul>

307

<li><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.internet.interfaces.IReactorUDP.listenMulticast.html" title="twisted.internet.interfaces.IReactorUDP.listenMulticast">listenMulticast</a></code></li>

308

</ul>

309

</dd>

310

311

<dt><code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.internet.TimerService.html" title="twisted.application.internet.TimerService">TimerService</a></code></dt>

312

313

<dd>

314

A service to periodically call a function.

315

</dd>

316

317

</dl>

318

319

<h3>Service Collection<a name="auto8"/></h3>

320

321

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

322

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

323

IService objects can be added to IServiceCollection by calling <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.service.IService.setServiceParent.html" title="twisted.application.service.IService.setServiceParent">setServiceParent</a></code> and detached

324

by using <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.service.IService.disownServiceParent.html" title="twisted.application.service.IService.disownServiceParent">disownServiceParent</a></code>.

325

326

The standard implementation of IServiceCollection is <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.application.service.MultiService.html" title="twisted.application.service.MultiService">MultiService</a></code>, which also implements

327

IService. MultiService is useful for creating a new Service which combines two

328

or more existing Services. For example, you could create a DNS Service as a

329

MultiService which has a TCP and a UDP Service as children.

330

331

<pre class="python"> 1

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

from twisted.names import server, dns, hosts

352

353

port = 53

354

355

# Create a MultiService, and hook up a TCPServer and a UDPServer to it as

356

# children.

357

dnsService = service.MultiService()

358

hostsResolver = hosts.Resolver('/etc/hosts')

359

tcpFactory = server.DNSServerFactory([hostsResolver])

360

internet.TCPServer(port, tcpFactory).setServiceParent(dnsService)

361

udpFactory = dns.DNSDatagramProtocol(tcpFactory)

362

internet.UDPServer(port, udpFactory).setServiceParent(dnsService)

363

364

# Create an application as normal

365

application = service.Application("DNSExample")

366

367

# Connect our MultiService to the application, just like a normal service.

368

dnsService.setServiceParent(application)

369

</pre>

370

371

</div>

372

373

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

374

Version: 10.0.0

375

</body>

376

</html>

b'\\ No newline at end of file'

Older »