~dkuhlman/python-training-materials/Materials

<li class="nav-item nav-item-3"><a href="asyncio.html" accesskey="U">18.5. <code class="docutils literal">asyncio</code> – Asynchronous I/O, event loop, coroutines and tasks</a> »</li>

</ul>

</div>

<h1>18.5.4. Transports and protocols (callback based API)<a class="headerlink" href="#transports-and-protocols-callback-based-api" title="Permalink to this headline">¶</a></h1>

<h2>18.5.4.1. Transports<a class="headerlink" href="#transports" title="Permalink to this headline">¶</a></h2>

Transports are classes provided by <a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O, event loop, coroutines and tasks."><code class="xref py py-mod docutils literal">asyncio</code></a> in order to abstract

various kinds of communication channels. You generally won’t instantiate

a transport yourself; instead, you will call a <a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop" title="asyncio.BaseEventLoop"><code class="xref py py-class docutils literal">BaseEventLoop</code></a> method

which will create the transport and try to initiate the underlying

communication channel, calling you back when it succeeds.

Once the communication channel is established, a transport is always

paired with a <a class="reference internal" href="#asyncio-protocol">protocol</a> instance. The protocol can

then call the transport’s methods for various purposes.

<a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O, event loop, coroutines and tasks."><code class="xref py py-mod docutils literal">asyncio</code></a> currently implements transports for TCP, UDP, SSL, and

subprocess pipes. The methods available on a transport depend on

the transport’s kind.

The transport classes are <a class="reference internal" href="asyncio-dev.html#asyncio-multithreading">not thread safe</a>.

<h3>18.5.4.1.1. BaseTransport<a class="headerlink" href="#basetransport" title="Permalink to this headline">¶</a></h3>

class <code class="descclassname">asyncio.</code><code class="descname">BaseTransport</code><a class="headerlink" href="#asyncio.BaseTransport" title="Permalink to this definition">¶</a></dt>

<dd>Base class for transports.

100

101

102

<code class="descname">close</code>(self)<a class="headerlink" href="#asyncio.BaseTransport.close" title="Permalink to this definition">¶</a></dt>

103

<dd>Close the transport. If the transport has a buffer for outgoing

104

data, buffered data will be flushed asynchronously. No more data

105

will be received. After all buffered data is flushed, the

106

protocol’s <code class="xref py py-meth docutils literal">connection_lost()</code> method will be called with

107

<a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> as its argument.

108

</dd></dl>

109

110

111

112

<code class="descname">is_closing</code>(self)<a class="headerlink" href="#asyncio.BaseTransport.is_closing" title="Permalink to this definition">¶</a></dt>

113

<dd>Return <code class="docutils literal">True</code> if the transport is closing or is closed.

114

115

New in version 3.5.1.

116

</div>

117

</dd></dl>

118

119

120

121

<code class="descname">get_extra_info</code>(name, default=None)<a class="headerlink" href="#asyncio.BaseTransport.get_extra_info" title="Permalink to this definition">¶</a></dt>

122

<dd>Return optional transport information. name is a string representing

123

the piece of transport-specific information to get, default is the

124

value to return if the information doesn’t exist.

125

This method allows transport implementations to easily expose

126

channel-specific information.

127

128

<li>socket:<ul>

129

<li><code class="docutils literal">'peername'</code>: the remote address to which the socket is connected,

130

result of <a class="reference internal" href="socket.html#socket.socket.getpeername" title="socket.socket.getpeername"><code class="xref py py-meth docutils literal">socket.socket.getpeername()</code></a> (<code class="docutils literal">None</code> on error)</li>

131

<li><code class="docutils literal">'socket'</code>: <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal">socket.socket</code></a> instance</li>

132

<li><code class="docutils literal">'sockname'</code>: the socket’s own address,

133

result of <a class="reference internal" href="socket.html#socket.socket.getsockname" title="socket.socket.getsockname"><code class="xref py py-meth docutils literal">socket.socket.getsockname()</code></a></li>

134

</ul>

135

</li>

136

<li>SSL socket:<ul>

137

<li><code class="docutils literal">'compression'</code>: the compression algorithm being used as a string,

138

or <code class="docutils literal">None</code> if the connection isn’t compressed; result of

139

<a class="reference internal" href="ssl.html#ssl.SSLSocket.compression" title="ssl.SSLSocket.compression"><code class="xref py py-meth docutils literal">ssl.SSLSocket.compression()</code></a></li>

140

<li><code class="docutils literal">'cipher'</code>: a three-value tuple containing the name of the cipher

141

being used, the version of the SSL protocol that defines its use, and

142

the number of secret bits being used; result of

143

<a class="reference internal" href="ssl.html#ssl.SSLSocket.cipher" title="ssl.SSLSocket.cipher"><code class="xref py py-meth docutils literal">ssl.SSLSocket.cipher()</code></a></li>

144

<li><code class="docutils literal">'peercert'</code>: peer certificate; result of

145

<a class="reference internal" href="ssl.html#ssl.SSLSocket.getpeercert" title="ssl.SSLSocket.getpeercert"><code class="xref py py-meth docutils literal">ssl.SSLSocket.getpeercert()</code></a></li>

146

<li><code class="docutils literal">'sslcontext'</code>: <a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">ssl.SSLContext</code></a> instance</li>

147

<li><code class="docutils literal">'ssl_object'</code>: <a class="reference internal" href="ssl.html#ssl.SSLObject" title="ssl.SSLObject"><code class="xref py py-class docutils literal">ssl.SSLObject</code></a> or <a class="reference internal" href="ssl.html#ssl.SSLSocket" title="ssl.SSLSocket"><code class="xref py py-class docutils literal">ssl.SSLSocket</code></a>

148

instance</li>

149

</ul>

150

</li>

151

152

<li><code class="docutils literal">'pipe'</code>: pipe object</li>

153

</ul>

154

</li>

155

<li>subprocess:<ul>

156

<li><code class="docutils literal">'subprocess'</code>: <a class="reference internal" href="subprocess.html#subprocess.Popen" title="subprocess.Popen"><code class="xref py py-class docutils literal">subprocess.Popen</code></a> instance</li>

157

</ul>

158

</li>

159

</ul>

160

</dd></dl>

161

162

163

Changed in version 3.5.1: <code class="docutils literal">'ssl_object'</code> info was added to SSL sockets.

164

</div>

165

</dd></dl>

166

167

</div>

168

169

<h3>18.5.4.1.2. ReadTransport<a class="headerlink" href="#readtransport" title="Permalink to this headline">¶</a></h3>

170

171

172

class <code class="descclassname">asyncio.</code><code class="descname">ReadTransport</code><a class="headerlink" href="#asyncio.ReadTransport" title="Permalink to this definition">¶</a></dt>

173

<dd>Interface for read-only transports.

174

175

176

<code class="descname">pause_reading</code>()<a class="headerlink" href="#asyncio.ReadTransport.pause_reading" title="Permalink to this definition">¶</a></dt>

177

<dd>Pause the receiving end of the transport. No data will be passed to

178

the protocol’s <code class="xref py py-meth docutils literal">data_received()</code> method until <a class="reference internal" href="#asyncio.ReadTransport.resume_reading" title="asyncio.ReadTransport.resume_reading"><code class="xref py py-meth docutils literal">resume_reading()</code></a>

179

is called.

180

</dd></dl>

181

182

183

184

<code class="descname">resume_reading</code>()<a class="headerlink" href="#asyncio.ReadTransport.resume_reading" title="Permalink to this definition">¶</a></dt>

185

<dd>Resume the receiving end. The protocol’s <code class="xref py py-meth docutils literal">data_received()</code> method

186

will be called once again if some data is available for reading.

187

</dd></dl>

188

189

</dd></dl>

190

191

</div>

192

193

<h3>18.5.4.1.3. WriteTransport<a class="headerlink" href="#writetransport" title="Permalink to this headline">¶</a></h3>

194

195

196

class <code class="descclassname">asyncio.</code><code class="descname">WriteTransport</code><a class="headerlink" href="#asyncio.WriteTransport" title="Permalink to this definition">¶</a></dt>

197

<dd>Interface for write-only transports.

198

199

200

<code class="descname">abort</code>()<a class="headerlink" href="#asyncio.WriteTransport.abort" title="Permalink to this definition">¶</a></dt>

201

<dd>Close the transport immediately, without waiting for pending operations

202

to complete. Buffered data will be lost. No more data will be received.

203

The protocol’s <code class="xref py py-meth docutils literal">connection_lost()</code> method will eventually be

204

called with <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> as its argument.

205

</dd></dl>

206

207

208

209

<code class="descname">can_write_eof</code>()<a class="headerlink" href="#asyncio.WriteTransport.can_write_eof" title="Permalink to this definition">¶</a></dt>

210

<dd>Return <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a> if the transport supports <a class="reference internal" href="#asyncio.WriteTransport.write_eof" title="asyncio.WriteTransport.write_eof"><code class="xref py py-meth docutils literal">write_eof()</code></a>,

211

<a class="reference internal" href="constants.html#False" title="False"><code class="xref py py-const docutils literal">False</code></a> if not.

212

</dd></dl>

213

214

215

216

<code class="descname">get_write_buffer_size</code>()<a class="headerlink" href="#asyncio.WriteTransport.get_write_buffer_size" title="Permalink to this definition">¶</a></dt>

217

<dd>Return the current size of the output buffer used by the transport.

218

</dd></dl>

219

220

221

222

<code class="descname">get_write_buffer_limits</code>()<a class="headerlink" href="#asyncio.WriteTransport.get_write_buffer_limits" title="Permalink to this definition">¶</a></dt>

223

<dd>Get the high- and low-water limits for write flow control. Return a

224

tuple <code class="docutils literal">(low, high)</code> where low and high are positive number of

225

bytes.

226

Use <a class="reference internal" href="#asyncio.WriteTransport.set_write_buffer_limits" title="asyncio.WriteTransport.set_write_buffer_limits"><code class="xref py py-meth docutils literal">set_write_buffer_limits()</code></a> to set the limits.

227

228

New in version 3.4.2.

229

</div>

230

</dd></dl>

231

232

233

234

<code class="descname">set_write_buffer_limits</code>(high=None, low=None)<a class="headerlink" href="#asyncio.WriteTransport.set_write_buffer_limits" title="Permalink to this definition">¶</a></dt>

235

<dd>Set the high- and low-water limits for write flow control.

236

These two values control when call the protocol’s

237

<code class="xref py py-meth docutils literal">pause_writing()</code> and <code class="xref py py-meth docutils literal">resume_writing()</code> methods are called.

238

If specified, the low-water limit must be less than or equal to the

239

high-water limit. Neither high nor low can be negative.

240

The defaults are implementation-specific. If only the

241

high-water limit is given, the low-water limit defaults to an

242

implementation-specific value less than or equal to the

243

high-water limit. Setting high to zero forces low to zero as

244

well, and causes <code class="xref py py-meth docutils literal">pause_writing()</code> to be called whenever the

245

buffer becomes non-empty. Setting low to zero causes

246

<code class="xref py py-meth docutils literal">resume_writing()</code> to be called only once the buffer is empty.

247

Use of zero for either limit is generally sub-optimal as it

248

reduces opportunities for doing I/O and computation

249

concurrently.

250

Use <a class="reference internal" href="#asyncio.WriteTransport.get_write_buffer_limits" title="asyncio.WriteTransport.get_write_buffer_limits"><code class="xref py py-meth docutils literal">get_write_buffer_limits()</code></a> to get the limits.

251

</dd></dl>

252

253

254

255

<code class="descname">write</code>(data)<a class="headerlink" href="#asyncio.WriteTransport.write" title="Permalink to this definition">¶</a></dt>

256

<dd>Write some data bytes to the transport.

257

This method does not block; it buffers the data and arranges for it

258

to be sent out asynchronously.

259

</dd></dl>

260

261

262

263

<code class="descname">writelines</code>(list_of_data)<a class="headerlink" href="#asyncio.WriteTransport.writelines" title="Permalink to this definition">¶</a></dt>

264

<dd>Write a list (or any iterable) of data bytes to the transport.

265

This is functionally equivalent to calling <a class="reference internal" href="#asyncio.WriteTransport.write" title="asyncio.WriteTransport.write"><code class="xref py py-meth docutils literal">write()</code></a> on each

266

element yielded by the iterable, but may be implemented more efficiently.

267

</dd></dl>

268

269

270

271

<code class="descname">write_eof</code>()<a class="headerlink" href="#asyncio.WriteTransport.write_eof" title="Permalink to this definition">¶</a></dt>

272

<dd>Close the write end of the transport after flushing buffered data.

273

Data may still be received.

274

This method can raise <a class="reference internal" href="exceptions.html#NotImplementedError" title="NotImplementedError"><code class="xref py py-exc docutils literal">NotImplementedError</code></a> if the transport

275

(e.g. SSL) doesn’t support half-closes.

276

</dd></dl>

277

278

</dd></dl>

279

280

</div>

281

282

<h3>18.5.4.1.4. DatagramTransport<a class="headerlink" href="#datagramtransport" title="Permalink to this headline">¶</a></h3>

283

284

285

<code class="descclassname">DatagramTransport.</code><code class="descname">sendto</code>(data, addr=None)<a class="headerlink" href="#asyncio.DatagramTransport.sendto" title="Permalink to this definition">¶</a></dt>

286

<dd>Send the data bytes to the remote peer given by addr (a

287

transport-dependent target address). If addr is <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>, the

288

data is sent to the target address given on transport creation.

289

This method does not block; it buffers the data and arranges for it

290

to be sent out asynchronously.

291

</dd></dl>

292

293

294

295

<code class="descclassname">DatagramTransport.</code><code class="descname">abort</code>()<a class="headerlink" href="#asyncio.DatagramTransport.abort" title="Permalink to this definition">¶</a></dt>

296

<dd>Close the transport immediately, without waiting for pending operations

297

to complete. Buffered data will be lost. No more data will be received.

298

The protocol’s <code class="xref py py-meth docutils literal">connection_lost()</code> method will eventually be

299

called with <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> as its argument.

300

</dd></dl>

301

302

</div>

303

304

<h3>18.5.4.1.5. BaseSubprocessTransport<a class="headerlink" href="#basesubprocesstransport" title="Permalink to this headline">¶</a></h3>

305

306

307

class <code class="descclassname">asyncio.</code><code class="descname">BaseSubprocessTransport</code><a class="headerlink" href="#asyncio.BaseSubprocessTransport" title="Permalink to this definition">¶</a></dt>

308

309

310

311

<dd>Return the subprocess process id as an integer.

312

</dd></dl>

313

314

315

316

<code class="descname">get_pipe_transport</code>(fd)<a class="headerlink" href="#asyncio.BaseSubprocessTransport.get_pipe_transport" title="Permalink to this definition">¶</a></dt>

317

<dd>Return the transport for the communication pipe corresponding to the

318

integer file descriptor fd:

319

320

<li><code class="docutils literal">0</code>: readable streaming transport of the standard input (stdin),

321

or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a> if the subprocess was not created with <code class="docutils literal">stdin=PIPE</code></li>

322

<li><code class="docutils literal">1</code>: writable streaming transport of the standard output (stdout),

323

324

<li><code class="docutils literal">2</code>: writable streaming transport of the standard error (stderr),

325

326

<li>other fd: <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a></li>

327

</ul>

328

</dd></dl>

329

330

331

332

<code class="descname">get_returncode</code>()<a class="headerlink" href="#asyncio.BaseSubprocessTransport.get_returncode" title="Permalink to this definition">¶</a></dt>

333

<dd>Return the subprocess returncode as an integer or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>

334

if it hasn’t returned, similarly to the

335

<a class="reference internal" href="subprocess.html#subprocess.Popen.returncode" title="subprocess.Popen.returncode"><code class="xref py py-attr docutils literal">subprocess.Popen.returncode</code></a> attribute.

336

</dd></dl>

337

338

339

340

341

<dd>Kill the subprocess, as in <a class="reference internal" href="subprocess.html#subprocess.Popen.kill" title="subprocess.Popen.kill"><code class="xref py py-meth docutils literal">subprocess.Popen.kill()</code></a>.

342

On POSIX systems, the function sends SIGKILL to the subprocess.

343

On Windows, this method is an alias for <a class="reference internal" href="#asyncio.BaseSubprocessTransport.terminate" title="asyncio.BaseSubprocessTransport.terminate"><code class="xref py py-meth docutils literal">terminate()</code></a>.

344

</dd></dl>

345

346

347

348

<code class="descname">send_signal</code>(signal)<a class="headerlink" href="#asyncio.BaseSubprocessTransport.send_signal" title="Permalink to this definition">¶</a></dt>

349

<dd>Send the signal number to the subprocess, as in

350

<a class="reference internal" href="subprocess.html#subprocess.Popen.send_signal" title="subprocess.Popen.send_signal"><code class="xref py py-meth docutils literal">subprocess.Popen.send_signal()</code></a>.

351

</dd></dl>

352

353

354

355

<code class="descname">terminate</code>()<a class="headerlink" href="#asyncio.BaseSubprocessTransport.terminate" title="Permalink to this definition">¶</a></dt>

356

<dd>Ask the subprocess to stop, as in <a class="reference internal" href="subprocess.html#subprocess.Popen.terminate" title="subprocess.Popen.terminate"><code class="xref py py-meth docutils literal">subprocess.Popen.terminate()</code></a>.

357

This method is an alias for the <a class="reference internal" href="#asyncio.BaseSubprocessTransport.close" title="asyncio.BaseSubprocessTransport.close"><code class="xref py py-meth docutils literal">close()</code></a> method.

358

On POSIX systems, this method sends SIGTERM to the subprocess.

359

On Windows, the Windows API function TerminateProcess() is called to

360

stop the subprocess.

361

</dd></dl>

362

363

364

365

<code class="descname">close</code>()<a class="headerlink" href="#asyncio.BaseSubprocessTransport.close" title="Permalink to this definition">¶</a></dt>

366

<dd>Ask the subprocess to stop by calling the <a class="reference internal" href="#asyncio.BaseSubprocessTransport.terminate" title="asyncio.BaseSubprocessTransport.terminate"><code class="xref py py-meth docutils literal">terminate()</code></a> method if the

367

subprocess hasn’t returned yet, and close transports of all pipes

368

(stdin, stdout and stderr).

369

</dd></dl>

370

371

</dd></dl>

372

373

</div>

374

</div>

375

376

<h2>18.5.4.2. Protocols<a class="headerlink" href="#protocols" title="Permalink to this headline">¶</a></h2>

377

<a class="reference internal" href="asyncio.html#module-asyncio" title="asyncio: Asynchronous I/O, event loop, coroutines and tasks."><code class="xref py py-mod docutils literal">asyncio</code></a> provides base classes that you can subclass to implement

378

your network protocols. Those classes are used in conjunction with

379

<a class="reference internal" href="#asyncio-transport">transports</a> (see below): the protocol parses incoming

380

data and asks for the writing of outgoing data, while the transport is

381

responsible for the actual I/O and buffering.

382

When subclassing a protocol class, it is recommended you override certain

383

methods. Those methods are callbacks: they will be called by the transport

384

on certain events (for example when some data is received); you shouldn’t

385

call them yourself, unless you are implementing a transport.

386

387

Note

388

All callbacks have default implementations, which are empty. Therefore,

389

you only need to implement the callbacks for the events in which you

390

are interested.

391

</div>

392

393

<h3>18.5.4.2.1. Protocol classes<a class="headerlink" href="#protocol-classes" title="Permalink to this headline">¶</a></h3>

394

395

396

class <code class="descclassname">asyncio.</code><code class="descname">Protocol</code><a class="headerlink" href="#asyncio.Protocol" title="Permalink to this definition">¶</a></dt>

397

<dd>The base class for implementing streaming protocols (for use with

398

e.g. TCP and SSL transports).

399

</dd></dl>

400

401

402

403

class <code class="descclassname">asyncio.</code><code class="descname">DatagramProtocol</code><a class="headerlink" href="#asyncio.DatagramProtocol" title="Permalink to this definition">¶</a></dt>

404

<dd>The base class for implementing datagram protocols (for use with

405

e.g. UDP transports).

406

</dd></dl>

407

408

409

410

class <code class="descclassname">asyncio.</code><code class="descname">SubprocessProtocol</code><a class="headerlink" href="#asyncio.SubprocessProtocol" title="Permalink to this definition">¶</a></dt>

411

<dd>The base class for implementing protocols communicating with child

412

processes (through a set of unidirectional pipes).

413

</dd></dl>

414

415

</div>

416

417

<h3>18.5.4.2.2. Connection callbacks<a class="headerlink" href="#connection-callbacks" title="Permalink to this headline">¶</a></h3>

418

These callbacks may be called on <a class="reference internal" href="#asyncio.Protocol" title="asyncio.Protocol"><code class="xref py py-class docutils literal">Protocol</code></a>, <a class="reference internal" href="#asyncio.DatagramProtocol" title="asyncio.DatagramProtocol"><code class="xref py py-class docutils literal">DatagramProtocol</code></a>

419

and <a class="reference internal" href="#asyncio.SubprocessProtocol" title="asyncio.SubprocessProtocol"><code class="xref py py-class docutils literal">SubprocessProtocol</code></a> instances:

420

421

422

<code class="descclassname">BaseProtocol.</code><code class="descname">connection_made</code>(transport)<a class="headerlink" href="#asyncio.BaseProtocol.connection_made" title="Permalink to this definition">¶</a></dt>

423

<dd>Called when a connection is made.

424

The transport argument is the transport representing the

425

connection. You are responsible for storing it somewhere

426

(e.g. as an attribute) if you need to.

427

</dd></dl>

428

429

430

431

<code class="descclassname">BaseProtocol.</code><code class="descname">connection_lost</code>(exc)<a class="headerlink" href="#asyncio.BaseProtocol.connection_lost" title="Permalink to this definition">¶</a></dt>

432

<dd>Called when the connection is lost or closed.

433

The argument is either an exception object or <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>.

434

The latter means a regular EOF is received, or the connection was

435

aborted or closed by this side of the connection.

436

</dd></dl>

437

438

<a class="reference internal" href="#asyncio.BaseProtocol.connection_made" title="asyncio.BaseProtocol.connection_made"><code class="xref py py-meth docutils literal">connection_made()</code></a> and <a class="reference internal" href="#asyncio.BaseProtocol.connection_lost" title="asyncio.BaseProtocol.connection_lost"><code class="xref py py-meth docutils literal">connection_lost()</code></a>

439

are called exactly once per successful connection. All other callbacks will be

440

called between those two methods, which allows for easier resource management

441

in your protocol implementation.

442

The following callbacks may be called only on <a class="reference internal" href="#asyncio.SubprocessProtocol" title="asyncio.SubprocessProtocol"><code class="xref py py-class docutils literal">SubprocessProtocol</code></a>

443

instances:

444

445

446

<code class="descclassname">SubprocessProtocol.</code><code class="descname">pipe_data_received</code>(fd, data)<a class="headerlink" href="#asyncio.SubprocessProtocol.pipe_data_received" title="Permalink to this definition">¶</a></dt>

447

<dd>Called when the child process writes data into its stdout or stderr pipe.

448

fd is the integer file descriptor of the pipe. data is a non-empty

449

bytes object containing the data.

450

</dd></dl>

451

452

453

454

<code class="descclassname">SubprocessProtocol.</code><code class="descname">pipe_connection_lost</code>(fd, exc)<a class="headerlink" href="#asyncio.SubprocessProtocol.pipe_connection_lost" title="Permalink to this definition">¶</a></dt>

455

<dd>Called when one of the pipes communicating with the child process

456

is closed. fd is the integer file descriptor that was closed.

457

</dd></dl>

458

459

460

461

<code class="descclassname">SubprocessProtocol.</code><code class="descname">process_exited</code>()<a class="headerlink" href="#asyncio.SubprocessProtocol.process_exited" title="Permalink to this definition">¶</a></dt>

462

<dd>Called when the child process has exited.

463

</dd></dl>

464

465

</div>

466

467

<h3>18.5.4.2.3. Streaming protocols<a class="headerlink" href="#streaming-protocols" title="Permalink to this headline">¶</a></h3>

468

The following callbacks are called on <a class="reference internal" href="#asyncio.Protocol" title="asyncio.Protocol"><code class="xref py py-class docutils literal">Protocol</code></a> instances:

469

470

471

<code class="descclassname">Protocol.</code><code class="descname">data_received</code>(data)<a class="headerlink" href="#asyncio.Protocol.data_received" title="Permalink to this definition">¶</a></dt>

472

<dd>Called when some data is received. data is a non-empty bytes object

473

containing the incoming data.

474

475

Note

476

Whether the data is buffered, chunked or reassembled depends on

477

the transport. In general, you shouldn’t rely on specific semantics

478

and instead make your parsing generic and flexible enough. However,

479

data is always received in the correct order.

480

</div>

481

</dd></dl>

482

483

484

485

<code class="descclassname">Protocol.</code><code class="descname">eof_received</code>()<a class="headerlink" href="#asyncio.Protocol.eof_received" title="Permalink to this definition">¶</a></dt>

486

<dd>Calls when the other end signals it won’t send any more data

487

(for example by calling <code class="xref py py-meth docutils literal">write_eof()</code>, if the other end also uses

488

asyncio).

489

This method may return a false value (including None), in which case

490

the transport will close itself. Conversely, if this method returns a

491

true value, closing the transport is up to the protocol. Since the

492

default implementation returns None, it implicitly closes the connection.

493

494

Note

495

Some transports such as SSL don’t support half-closed connections,

496

in which case returning true from this method will not prevent closing

497

the connection.

498

</div>

499

</dd></dl>

500

501

<code class="xref py py-meth docutils literal">data_received()</code> can be called an arbitrary number of times during

502

a connection. However, <code class="xref py py-meth docutils literal">eof_received()</code> is called at most once

503

and, if called, <code class="xref py py-meth docutils literal">data_received()</code> won’t be called after it.

504

State machine:

505

506

<div>start -> <a class="reference internal" href="#asyncio.BaseProtocol.connection_made" title="asyncio.BaseProtocol.connection_made"><code class="xref py py-meth docutils literal">connection_made()</code></a>

507

[-> <a class="reference internal" href="#asyncio.Protocol.data_received" title="asyncio.Protocol.data_received"><code class="xref py py-meth docutils literal">data_received()</code></a> *]

508

[-> <a class="reference internal" href="#asyncio.Protocol.eof_received" title="asyncio.Protocol.eof_received"><code class="xref py py-meth docutils literal">eof_received()</code></a> ?]

509

-> <a class="reference internal" href="#asyncio.BaseProtocol.connection_lost" title="asyncio.BaseProtocol.connection_lost"><code class="xref py py-meth docutils literal">connection_lost()</code></a> -> end</div></blockquote>

510

</div>

511

512

<h3>18.5.4.2.4. Datagram protocols<a class="headerlink" href="#datagram-protocols" title="Permalink to this headline">¶</a></h3>

513

The following callbacks are called on <a class="reference internal" href="#asyncio.DatagramProtocol" title="asyncio.DatagramProtocol"><code class="xref py py-class docutils literal">DatagramProtocol</code></a> instances.

514

515

516

<code class="descclassname">DatagramProtocol.</code><code class="descname">datagram_received</code>(data, addr)<a class="headerlink" href="#asyncio.DatagramProtocol.datagram_received" title="Permalink to this definition">¶</a></dt>

517

<dd>Called when a datagram is received. data is a bytes object containing

518

the incoming data. addr is the address of the peer sending the data;

519

the exact format depends on the transport.

520

</dd></dl>

521

522

523

524

<code class="descclassname">DatagramProtocol.</code><code class="descname">error_received</code>(exc)<a class="headerlink" href="#asyncio.DatagramProtocol.error_received" title="Permalink to this definition">¶</a></dt>

525

<dd>Called when a previous send or receive operation raises an

526

<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-class docutils literal">OSError</code></a>. exc is the <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-class docutils literal">OSError</code></a> instance.

527

This method is called in rare conditions, when the transport (e.g. UDP)

528

detects that a datagram couldn’t be delivered to its recipient.

529

In many conditions though, undeliverable datagrams will be silently

530

dropped.

531

</dd></dl>

532

533

</div>

534

535

<h3>18.5.4.2.5. Flow control callbacks<a class="headerlink" href="#flow-control-callbacks" title="Permalink to this headline">¶</a></h3>

536

537

<a class="reference internal" href="#asyncio.DatagramProtocol" title="asyncio.DatagramProtocol"><code class="xref py py-class docutils literal">DatagramProtocol</code></a> and <a class="reference internal" href="#asyncio.SubprocessProtocol" title="asyncio.SubprocessProtocol"><code class="xref py py-class docutils literal">SubprocessProtocol</code></a> instances:

538

539

540

<code class="descclassname">BaseProtocol.</code><code class="descname">pause_writing</code>()<a class="headerlink" href="#asyncio.BaseProtocol.pause_writing" title="Permalink to this definition">¶</a></dt>

541

<dd>Called when the transport’s buffer goes over the high-water mark.

542

</dd></dl>

543

544

545

546

<code class="descclassname">BaseProtocol.</code><code class="descname">resume_writing</code>()<a class="headerlink" href="#asyncio.BaseProtocol.resume_writing" title="Permalink to this definition">¶</a></dt>

547

<dd>Called when the transport’s buffer drains below the low-water mark.

548

</dd></dl>

549

550

<code class="xref py py-meth docutils literal">pause_writing()</code> and <code class="xref py py-meth docutils literal">resume_writing()</code> calls are paired –

551

<code class="xref py py-meth docutils literal">pause_writing()</code> is called once when the buffer goes strictly over

552

the high-water mark (even if subsequent writes increases the buffer size

553

even more), and eventually <code class="xref py py-meth docutils literal">resume_writing()</code> is called once when the

554

buffer size reaches the low-water mark.

555

556

Note

557

If the buffer size equals the high-water mark,

558

<code class="xref py py-meth docutils literal">pause_writing()</code> is not called – it must go strictly over.

559

Conversely, <code class="xref py py-meth docutils literal">resume_writing()</code> is called when the buffer size is

560

equal or lower than the low-water mark. These end conditions

561

are important to ensure that things go as expected when either

562

mark is zero.

563

</div>

564

565

Note

566

On BSD systems (OS X, FreeBSD, etc.) flow control is not supported

567

for <a class="reference internal" href="#asyncio.DatagramProtocol" title="asyncio.DatagramProtocol"><code class="xref py py-class docutils literal">DatagramProtocol</code></a>, because send failures caused by

568

writing too many packets cannot be detected easily. The socket

569

always appears ‘ready’ and excess packets are dropped; an

570

<a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-class docutils literal">OSError</code></a> with errno set to <a class="reference internal" href="errno.html#errno.ENOBUFS" title="errno.ENOBUFS"><code class="xref py py-const docutils literal">errno.ENOBUFS</code></a> may or

571

may not be raised; if it is raised, it will be reported to

572

<a class="reference internal" href="#asyncio.DatagramProtocol.error_received" title="asyncio.DatagramProtocol.error_received"><code class="xref py py-meth docutils literal">DatagramProtocol.error_received()</code></a> but otherwise ignored.

573

</div>

574

</div>

575

576

<h3>18.5.4.2.6. Coroutines and protocols<a class="headerlink" href="#coroutines-and-protocols" title="Permalink to this headline">¶</a></h3>

577

Coroutines can be scheduled in a protocol method using <a class="reference internal" href="asyncio-task.html#asyncio.ensure_future" title="asyncio.ensure_future"><code class="xref py py-func docutils literal">ensure_future()</code></a>,

578

but there is no guarantee made about the execution order. Protocols are not

579

aware of coroutines created in protocol methods and so will not wait for them.

580

To have a reliable execution order, use <a class="reference internal" href="asyncio-stream.html#asyncio-streams">stream objects</a> in a

581

coroutine with <code class="docutils literal">yield from</code>. For example, the <a class="reference internal" href="asyncio-stream.html#asyncio.StreamWriter.drain" title="asyncio.StreamWriter.drain"><code class="xref py py-meth docutils literal">StreamWriter.drain()</code></a>

582

coroutine can be used to wait until the write buffer is flushed.

583

</div>

584

</div>

585

586

<h2>18.5.4.3. Protocol examples<a class="headerlink" href="#protocol-examples" title="Permalink to this headline">¶</a></h2>

587

588

<h3>18.5.4.3.1. TCP echo client protocol<a class="headerlink" href="#tcp-echo-client-protocol" title="Permalink to this headline">¶</a></h3>

589

TCP echo client using the <a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop.create_connection" title="asyncio.BaseEventLoop.create_connection"><code class="xref py py-meth docutils literal">BaseEventLoop.create_connection()</code></a> method, send

590

data and wait until the connection is closed:

591

<div class="highlight-python3"><div class="highlight"><pre>import asyncio

592

593

class EchoClientProtocol(asyncio.Protocol):

594

def __init__(self, message, loop):

595

self.message = message

596

self.loop = loop

597

598

def connection_made(self, transport):

599

transport.write(self.message.encode())

600

print('Data sent: {!r}'.format(self.message))

601

602

def data_received(self, data):

603

print('Data received: {!r}'.format(data.decode()))

604

605

def connection_lost(self, exc):

606

print('The server closed the connection')

607

print('Stop the event loop')

608

self.loop.stop()

609

610

loop = asyncio.get_event_loop()

611

message = 'Hello World!'

612

coro = loop.create_connection(lambda: EchoClientProtocol(message, loop),

613

'127.0.0.1', 8888)

614

loop.run_until_complete(coro)

615

loop.run_forever()

616

loop.close()

617

</pre></div>

618

</div>

619

The event loop is running twice. The

620

<a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop.run_until_complete" title="asyncio.BaseEventLoop.run_until_complete"><code class="xref py py-meth docutils literal">run_until_complete()</code></a> method is preferred in this short

621

example to raise an exception if the server is not listening, instead of

622

having to write a short coroutine to handle the exception and stop the

623

running loop. At <a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop.run_until_complete" title="asyncio.BaseEventLoop.run_until_complete"><code class="xref py py-meth docutils literal">run_until_complete()</code></a> exit, the loop is

624

no longer running, so there is no need to stop the loop in case of an error.

625

626

See also

627

The <a class="reference internal" href="asyncio-stream.html#asyncio-tcp-echo-client-streams">TCP echo client using streams</a>

628

example uses the <a class="reference internal" href="asyncio-stream.html#asyncio.open_connection" title="asyncio.open_connection"><code class="xref py py-func docutils literal">asyncio.open_connection()</code></a> function.

629

</div>

630

</div>

631

632

<h3>18.5.4.3.2. TCP echo server protocol<a class="headerlink" href="#tcp-echo-server-protocol" title="Permalink to this headline">¶</a></h3>

633

TCP echo server using the <a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop.create_server" title="asyncio.BaseEventLoop.create_server"><code class="xref py py-meth docutils literal">BaseEventLoop.create_server()</code></a> method, send back

634

received data and close the connection:

635

<div class="highlight-python3"><div class="highlight"><pre>import asyncio

636

637

class EchoServerClientProtocol(asyncio.Protocol):

638

639

peername = transport.get_extra_info('peername')

640

print('Connection from {}'.format(peername))

641

self.transport = transport

642

643

def data_received(self, data):

644

message = data.decode()

645

646

647

print('Send: {!r}'.format(message))

648

self.transport.write(data)

649

650

print('Close the client socket')

651

self.transport.close()

652

653

loop = asyncio.get_event_loop()

654

# Each client connection will create a new protocol instance

655

coro = loop.create_server(EchoServerClientProtocol, '127.0.0.1', 8888)

656

server = loop.run_until_complete(coro)

657

658

# Serve requests until Ctrl+C is pressed

659

print('Serving on {}'.format(server.sockets[0].getsockname()))

660

try:

661

loop.run_forever()

662

except KeyboardInterrupt:

663

pass

664

665

# Close the server

666

server.close()

667

loop.run_until_complete(server.wait_closed())

668

loop.close()

669

</pre></div>

670

</div>

671

<code class="xref py py-meth docutils literal">Transport.close()</code> can be called immediately after

672

<a class="reference internal" href="#asyncio.WriteTransport.write" title="asyncio.WriteTransport.write"><code class="xref py py-meth docutils literal">WriteTransport.write()</code></a> even if data are not sent yet on the socket: both

673

methods are asynchronous. <code class="docutils literal">yield from</code> is not needed because these transport

674

methods are not coroutines.

675

676

See also

677

The <a class="reference internal" href="asyncio-stream.html#asyncio-tcp-echo-server-streams">TCP echo server using streams</a>

678

example uses the <a class="reference internal" href="asyncio-stream.html#asyncio.start_server" title="asyncio.start_server"><code class="xref py py-func docutils literal">asyncio.start_server()</code></a> function.

679

</div>

680

</div>

681

682

<h3>18.5.4.3.3. UDP echo client protocol<a class="headerlink" href="#udp-echo-client-protocol" title="Permalink to this headline">¶</a></h3>

683

UDP echo client using the <a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop.create_datagram_endpoint" title="asyncio.BaseEventLoop.create_datagram_endpoint"><code class="xref py py-meth docutils literal">BaseEventLoop.create_datagram_endpoint()</code></a>

684

method, send data and close the transport when we received the answer:

685

<div class="highlight-python3"><div class="highlight"><pre>import asyncio

686

687

class EchoClientProtocol:

688

689

self.message = message

690

self.loop = loop

691

self.transport = None

692

693

694

self.transport = transport

695

print('Send:', self.message)

696

self.transport.sendto(self.message.encode())

697

698

def datagram_received(self, data, addr):

699

print("Received:", data.decode())

700

701

print("Close the socket")

702

self.transport.close()

703

704

def error_received(self, exc):

705

print('Error received:', exc)

706

707

def connection_lost(self, exc):

708

print("Socket closed, stop the event loop")

709

loop = asyncio.get_event_loop()

710

loop.stop()

711

712

loop = asyncio.get_event_loop()

713

message = "Hello World!"

714

connect = loop.create_datagram_endpoint(

715

lambda: EchoClientProtocol(message, loop),

716

remote_addr=('127.0.0.1', 9999))

717

transport, protocol = loop.run_until_complete(connect)

718

loop.run_forever()

719

transport.close()

720

loop.close()

721

</pre></div>

722

</div>

723

</div>

724

725

<h3>18.5.4.3.4. UDP echo server protocol<a class="headerlink" href="#udp-echo-server-protocol" title="Permalink to this headline">¶</a></h3>

726

UDP echo server using the <a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop.create_datagram_endpoint" title="asyncio.BaseEventLoop.create_datagram_endpoint"><code class="xref py py-meth docutils literal">BaseEventLoop.create_datagram_endpoint()</code></a>

727

method, send back received data:

728

<div class="highlight-python3"><div class="highlight"><pre>import asyncio

729

730

class EchoServerProtocol:

731

732

self.transport = transport

733

734

735

message = data.decode()

736

print('Received %r from %s' % (message, addr))

737

print('Send %r to %s' % (message, addr))

738

self.transport.sendto(data, addr)

739

740

loop = asyncio.get_event_loop()

741

print("Starting UDP server")

742

# One protocol instance will be created to serve all client requests

743

listen = loop.create_datagram_endpoint(

744

EchoServerProtocol, local_addr=('127.0.0.1', 9999))

745

746

747

try:

748

loop.run_forever()

749

except KeyboardInterrupt:

750

pass

751

752

transport.close()

753

loop.close()

754

</pre></div>

755

</div>

756

</div>

757

758

<h3>18.5.4.3.5. Register an open socket to wait for data using a protocol<a class="headerlink" href="#register-an-open-socket-to-wait-for-data-using-a-protocol" title="Permalink to this headline">¶</a></h3>

759

Wait until a socket receives data using the

760

<a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop.create_connection" title="asyncio.BaseEventLoop.create_connection"><code class="xref py py-meth docutils literal">BaseEventLoop.create_connection()</code></a> method with a protocol, and then close

761

the event loop

762

<div class="highlight-python3"><div class="highlight"><pre>import asyncio

763

try:

764

from socket import socketpair

765

except ImportError:

766

from asyncio.windows_utils import socketpair

767

768

# Create a pair of connected sockets

769

rsock, wsock = socketpair()

770

loop = asyncio.get_event_loop()

771

772

class MyProtocol(asyncio.Protocol):

773

transport = None

774

775

776

self.transport = transport

777

778

def data_received(self, data):

779

780

781

# We are done: close the transport (it will call connection_lost())

782

self.transport.close()

783

784

def connection_lost(self, exc):

785

# The socket has been closed, stop the event loop

786

loop.stop()

787

788

# Register the socket to wait for data

789

connect_coro = loop.create_connection(MyProtocol, sock=rsock)

790

791

792

# Simulate the reception of data from the network

793

loop.call_soon(wsock.send, 'abc'.encode())

794

795

# Run the event loop

796

loop.run_forever()

797

798

# We are done, close sockets and the event loop

799

rsock.close()

800

wsock.close()

801

loop.close()

802

</pre></div>

803

</div>

804

805

See also

806

The <a class="reference internal" href="asyncio-eventloop.html#asyncio-watch-read-event">watch a file descriptor for read events</a> example uses the low-level

807

<a class="reference internal" href="asyncio-eventloop.html#asyncio.BaseEventLoop.add_reader" title="asyncio.BaseEventLoop.add_reader"><code class="xref py py-meth docutils literal">BaseEventLoop.add_reader()</code></a> method to register the file descriptor of a

808

socket.

809

The <a class="reference internal" href="asyncio-stream.html#asyncio-register-socket-streams">register an open socket to wait for data using streams</a> example uses high-level streams

810

created by the <a class="reference internal" href="asyncio-stream.html#asyncio.open_connection" title="asyncio.open_connection"><code class="xref py py-func docutils literal">open_connection()</code></a> function in a coroutine.

811

</div>

812

</div>

813

</div>

814

</div>

815

816

817

</div>

818

</div>

819

</div>

820

821

822

<h3><a href="../contents.html">Table Of Contents</a></h3>

823

<ul>

824

<li><a class="reference internal" href="#">18.5.4. Transports and protocols (callback based API)</a><ul>

825

<li><a class="reference internal" href="#transports">18.5.4.1. Transports</a><ul>

826

<li><a class="reference internal" href="#basetransport">18.5.4.1.1. BaseTransport</a></li>

827

<li><a class="reference internal" href="#readtransport">18.5.4.1.2. ReadTransport</a></li>

828

<li><a class="reference internal" href="#writetransport">18.5.4.1.3. WriteTransport</a></li>

829

<li><a class="reference internal" href="#datagramtransport">18.5.4.1.4. DatagramTransport</a></li>

830

<li><a class="reference internal" href="#basesubprocesstransport">18.5.4.1.5. BaseSubprocessTransport</a></li>

831

</ul>

832

</li>

833

<li><a class="reference internal" href="#protocols">18.5.4.2. Protocols</a><ul>

834

<li><a class="reference internal" href="#protocol-classes">18.5.4.2.1. Protocol classes</a></li>

835

<li><a class="reference internal" href="#connection-callbacks">18.5.4.2.2. Connection callbacks</a></li>

836

<li><a class="reference internal" href="#streaming-protocols">18.5.4.2.3. Streaming protocols</a></li>

837

<li><a class="reference internal" href="#datagram-protocols">18.5.4.2.4. Datagram protocols</a></li>

838

<li><a class="reference internal" href="#flow-control-callbacks">18.5.4.2.5. Flow control callbacks</a></li>

839

<li><a class="reference internal" href="#coroutines-and-protocols">18.5.4.2.6. Coroutines and protocols</a></li>

840

</ul>

841

</li>

842

<li><a class="reference internal" href="#protocol-examples">18.5.4.3. Protocol examples</a><ul>

843

<li><a class="reference internal" href="#tcp-echo-client-protocol">18.5.4.3.1. TCP echo client protocol</a></li>

844

<li><a class="reference internal" href="#tcp-echo-server-protocol">18.5.4.3.2. TCP echo server protocol</a></li>

845

<li><a class="reference internal" href="#udp-echo-client-protocol">18.5.4.3.3. UDP echo client protocol</a></li>

846

<li><a class="reference internal" href="#udp-echo-server-protocol">18.5.4.3.4. UDP echo server protocol</a></li>

847

<li><a class="reference internal" href="#register-an-open-socket-to-wait-for-data-using-a-protocol">18.5.4.3.5. Register an open socket to wait for data using a protocol</a></li>

848

</ul>

849

</li>

850

</ul>

851

</li>

852

</ul>

853

854

<h4>Previous topic</h4>

855

<a href="asyncio-task.html"

856

title="previous chapter">18.5.3. Tasks and coroutines</a>

857

<h4>Next topic</h4>

858

<a href="asyncio-stream.html"

859

title="next chapter">18.5.5. Streams (coroutine based API)</a>

860

861

862

<li><a href="../bugs.html">Report a Bug</a></li>

863

<li><a href="../_sources/library/asyncio-protocol.txt"

864

rel="nofollow">Show Source</a></li>

865

</ul>

866

867

868

<h3>Quick search</h3>

869

870

871

872

873

874

</form>

875

876

Enter search terms or a module, class or function name.

877

878

</div>

879

880

</div>

881

</div>

882

883

</div>

884

885

<h3>Navigation</h3>

886

<ul>

887

888

<a href="../genindex.html" title="General Index"

889

>index</a></li>

890

891

<a href="../py-modindex.html" title="Python Module Index"

892

>modules</a> |</li>

893

894

<a href="asyncio-stream.html" title="18.5.5. Streams (coroutine based API)"

895

>next</a> |</li>

896

897

<a href="asyncio-task.html" title="18.5.3. Tasks and coroutines"

898

>previous</a> |</li>

899

<li><img src="../_static/py.png" alt=""

900

style="vertical-align: middle; margin-top: -1px"/></li>

901

<li><a href="https://www.python.org/">Python</a> »</li>

902

<li>

903

3.5.1

904

<a href="../index.html">Documentation </a> »

905

</li>

906

907

<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>

908

<li class="nav-item nav-item-2"><a href="ipc.html" >18. Interprocess Communication and Networking</a> »</li>

909

<li class="nav-item nav-item-3"><a href="asyncio.html" >18.5. <code class="docutils literal">asyncio</code> – Asynchronous I/O, event loop, coroutines and tasks</a> »</li>

910

</ul>

911

</div>

912

913

914

915

The Python Software Foundation is a non-profit corporation.

916

<a href="https://www.python.org/psf/donations/">Please donate.</a>

917

918

Last updated on Jan 22, 2016.

919

<a href="../bugs.html">Found a bug</a>?

920

921

Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.3.3.

922

</div>

923

924

</body>

925

</html>

b'\\ No newline at end of file'

Older »