~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.1. Base Event Loop<a class="headerlink" href="#base-event-loop" title="Permalink to this headline">¶</a></h1>

The event loop is the central execution device 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>.

It provides multiple facilities, including:

<li>Registering, executing and cancelling delayed calls (timeouts).</li>

<li>Creating client and server <a class="reference internal" href="asyncio-protocol.html#asyncio-transport">transports</a> for various

kinds of communication.</li>

<li>Launching subprocesses and the associated <a class="reference internal" href="asyncio-protocol.html#asyncio-transport">transports</a> for communication with an external program.</li>

<li>Delegating costly function calls to a pool of threads.</li>

</ul>

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

<dd>Base class of event loops.

This class is <a class="reference internal" href="asyncio-dev.html#asyncio-multithreading">not thread safe</a>.

</dd></dl>

<h2>18.5.1.1. Run an event loop<a class="headerlink" href="#run-an-event-loop" title="Permalink to this headline">¶</a></h2>

100

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

101

<dd>Run until <a class="reference internal" href="#asyncio.BaseEventLoop.stop" title="asyncio.BaseEventLoop.stop"><code class="xref py py-meth docutils literal">stop()</code></a> is called. If <a class="reference internal" href="#asyncio.BaseEventLoop.stop" title="asyncio.BaseEventLoop.stop"><code class="xref py py-meth docutils literal">stop()</code></a> is called before

102

<a class="reference internal" href="#asyncio.BaseEventLoop.run_forever" title="asyncio.BaseEventLoop.run_forever"><code class="xref py py-meth docutils literal">run_forever()</code></a> is called, this polls the I/O selector once

103

with a timeout of zero, runs all callbacks scheduled in response to

104

I/O events (and those that were already scheduled), and then exits.

105

If <a class="reference internal" href="#asyncio.BaseEventLoop.stop" title="asyncio.BaseEventLoop.stop"><code class="xref py py-meth docutils literal">stop()</code></a> is called while <a class="reference internal" href="#asyncio.BaseEventLoop.run_forever" title="asyncio.BaseEventLoop.run_forever"><code class="xref py py-meth docutils literal">run_forever()</code></a> is running,

106

this will run the current batch of callbacks and then exit. Note

107

that callbacks scheduled by callbacks will not run in that case;

108

they will run the next time <a class="reference internal" href="#asyncio.BaseEventLoop.run_forever" title="asyncio.BaseEventLoop.run_forever"><code class="xref py py-meth docutils literal">run_forever()</code></a> is called.

109

110

Changed in version 3.5.1.

111

</div>

112

</dd></dl>

113

114

115

116

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

117

<dd>Run until the <a class="reference internal" href="asyncio-task.html#asyncio.Future" title="asyncio.Future"><code class="xref py py-class docutils literal">Future</code></a> is done.

118

If the argument is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine object</a>, it is wrapped by

119

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

120

Return the Future’s result, or raise its exception.

121

</dd></dl>

122

123

124

125

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

126

<dd>Returns running status of event loop.

127

</dd></dl>

128

129

130

131

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

132

<dd>Stop running the event loop.

133

This causes <a class="reference internal" href="#asyncio.BaseEventLoop.run_forever" title="asyncio.BaseEventLoop.run_forever"><code class="xref py py-meth docutils literal">run_forever()</code></a> to exit at the next suitable

134

opportunity (see there for more details).

135

136

Changed in version 3.5.1.

137

</div>

138

</dd></dl>

139

140

141

142

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

143

<dd>Returns <code class="docutils literal">True</code> if the event loop was closed.

144

145

New in version 3.4.2.

146

</div>

147

</dd></dl>

148

149

150

151

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

152

<dd>Close the event loop. The loop must not be running. Pending

153

callbacks will be lost.

154

This clears the queues and shuts down the executor, but does not wait for

155

the executor to finish.

156

This is idempotent and irreversible. No other methods should be called after

157

this one.

158

</dd></dl>

159

160

</div>

161

162

<h2>18.5.1.2. Calls<a class="headerlink" href="#calls" title="Permalink to this headline">¶</a></h2>

163

Most <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> functions don’t accept keywords. If you want to pass

164

keywords to your callback, use <a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal">functools.partial()</code></a>. For example,

165

<code class="docutils literal">loop.call_soon(functools.partial(print, "Hello", flush=True))</code> will call

166

<code class="docutils literal">print("Hello", flush=True)</code>.

167

168

Note

169

<a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal">functools.partial()</code></a> is better than <code class="docutils literal">lambda</code> functions, because

170

<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> can inspect <a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal">functools.partial()</code></a> object to display

171

parameters in debug mode, whereas <code class="docutils literal">lambda</code> functions have a poor

172

representation.

173

</div>

174

175

176

<code class="descclassname">BaseEventLoop.</code><code class="descname">call_soon</code>(callback, *args)<a class="headerlink" href="#asyncio.BaseEventLoop.call_soon" title="Permalink to this definition">¶</a></dt>

177

<dd>Arrange for a callback to be called as soon as possible. The callback is

178

called after <a class="reference internal" href="#asyncio.BaseEventLoop.call_soon" title="asyncio.BaseEventLoop.call_soon"><code class="xref py py-meth docutils literal">call_soon()</code></a> returns, when control returns to the event

179

loop.

180

This operates as a FIFO queue, callbacks are called in the order in

181

which they are registered. Each callback will be called exactly once.

182

Any positional arguments after the callback will be passed to the

183

callback when it is called.

184

An instance of <a class="reference internal" href="#asyncio.Handle" title="asyncio.Handle"><code class="xref py py-class docutils literal">asyncio.Handle</code></a> is returned, which can be

185

used to cancel the callback.

186

<a class="reference internal" href="#asyncio-pass-keywords">Use functools.partial to pass keywords to the callback</a>.

187

</dd></dl>

188

189

190

191

<code class="descclassname">BaseEventLoop.</code><code class="descname">call_soon_threadsafe</code>(callback, *args)<a class="headerlink" href="#asyncio.BaseEventLoop.call_soon_threadsafe" title="Permalink to this definition">¶</a></dt>

192

<dd>Like <a class="reference internal" href="#asyncio.BaseEventLoop.call_soon" title="asyncio.BaseEventLoop.call_soon"><code class="xref py py-meth docutils literal">call_soon()</code></a>, but thread safe.

193

See the <a class="reference internal" href="asyncio-dev.html#asyncio-multithreading">concurrency and multithreading</a>

194

section of the documentation.

195

</dd></dl>

196

197

</div>

198

199

<h2>18.5.1.3. Delayed calls<a class="headerlink" href="#delayed-calls" title="Permalink to this headline">¶</a></h2>

200

The event loop has its own internal clock for computing timeouts.

201

Which clock is used depends on the (platform-specific) event loop

202

implementation; ideally it is a monotonic clock. This will generally be

203

a different clock than <a class="reference internal" href="time.html#time.time" title="time.time"><code class="xref py py-func docutils literal">time.time()</code></a>.

204

205

Note

206

Timeouts (relative delay or absolute when) should not exceed one day.

207

</div>

208

209

210

<code class="descclassname">BaseEventLoop.</code><code class="descname">call_later</code>(delay, callback, *args)<a class="headerlink" href="#asyncio.BaseEventLoop.call_later" title="Permalink to this definition">¶</a></dt>

211

<dd>Arrange for the callback to be called after the given delay

212

seconds (either an int or float).

213

214

used to cancel the callback.

215

callback will be called exactly once per call to <a class="reference internal" href="#asyncio.BaseEventLoop.call_later" title="asyncio.BaseEventLoop.call_later"><code class="xref py py-meth docutils literal">call_later()</code></a>.

216

If two callbacks are scheduled for exactly the same time, it is

217

undefined which will be called first.

218

The optional positional args will be passed to the callback when it

219

is called. If you want the callback to be called with some named

220

arguments, use a closure or <a class="reference internal" href="functools.html#functools.partial" title="functools.partial"><code class="xref py py-func docutils literal">functools.partial()</code></a>.

221

<a class="reference internal" href="#asyncio-pass-keywords">Use functools.partial to pass keywords to the callback</a>.

222

</dd></dl>

223

224

225

226

<code class="descclassname">BaseEventLoop.</code><code class="descname">call_at</code>(when, callback, *args)<a class="headerlink" href="#asyncio.BaseEventLoop.call_at" title="Permalink to this definition">¶</a></dt>

227

<dd>Arrange for the callback to be called at the given absolute timestamp

228

when (an int or float), using the same time reference as

229

<a class="reference internal" href="#asyncio.BaseEventLoop.time" title="asyncio.BaseEventLoop.time"><code class="xref py py-meth docutils literal">BaseEventLoop.time()</code></a>.

230

This method’s behavior is the same as <a class="reference internal" href="#asyncio.BaseEventLoop.call_later" title="asyncio.BaseEventLoop.call_later"><code class="xref py py-meth docutils literal">call_later()</code></a>.

231

232

used to cancel the callback.

233

<a class="reference internal" href="#asyncio-pass-keywords">Use functools.partial to pass keywords to the callback</a>.

234

</dd></dl>

235

236

237

238

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

239

<dd>Return the current time, as a <a class="reference internal" href="functions.html#float" title="float"><code class="xref py py-class docutils literal">float</code></a> value, according to the

240

event loop’s internal clock.

241

</dd></dl>

242

243

244

See also

245

The <a class="reference internal" href="asyncio-task.html#asyncio.sleep" title="asyncio.sleep"><code class="xref py py-func docutils literal">asyncio.sleep()</code></a> function.

246

</div>

247

</div>

248

249

<h2>18.5.1.4. Tasks<a class="headerlink" href="#tasks" title="Permalink to this headline">¶</a></h2>

250

251

252

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

253

<dd>Schedule the execution of a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine object</a>: wrap it in

254

a future. Return a <a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal">Task</code></a> object.

255

Third-party event loops can use their own subclass of <a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal">Task</code></a> for

256

interoperability. In this case, the result type is a subclass of

257

<a class="reference internal" href="asyncio-task.html#asyncio.Task" title="asyncio.Task"><code class="xref py py-class docutils literal">Task</code></a>.

258

This method was added in Python 3.4.2. Use the <a class="reference internal" href="asyncio-task.html#asyncio.async" title="asyncio.async"><code class="xref py py-func docutils literal">async()</code></a> function to

259

support also older Python versions.

260

261

New in version 3.4.2.

262

</div>

263

</dd></dl>

264

265

266

267

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

268

<dd>Set a task factory that will be used by

269

<a class="reference internal" href="#asyncio.BaseEventLoop.create_task" title="asyncio.BaseEventLoop.create_task"><code class="xref py py-meth docutils literal">BaseEventLoop.create_task()</code></a>.

270

If factory is <code class="docutils literal">None</code> the default task factory will be set.

271

If factory is a callable, it should have a signature matching

272

<code class="docutils literal">(loop, coro)</code>, where loop will be a reference to the active

273

event loop, coro will be a coroutine object. The callable

274

must return an <a class="reference internal" href="asyncio-task.html#asyncio.Future" title="asyncio.Future"><code class="xref py py-class docutils literal">asyncio.Future</code></a> compatible object.

275

276

New in version 3.4.4.

277

</div>

278

</dd></dl>

279

280

281

282

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

283

<dd>Return a task factory, or <code class="docutils literal">None</code> if the default one is in use.

284

285

New in version 3.4.4.

286

</div>

287

</dd></dl>

288

289

</div>

290

291

<h2>18.5.1.5. Creating connections<a class="headerlink" href="#creating-connections" title="Permalink to this headline">¶</a></h2>

292

293

294

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">create_connection</code>(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)<a class="headerlink" href="#asyncio.BaseEventLoop.create_connection" title="Permalink to this definition">¶</a></dt>

295

<dd>Create a streaming transport connection to a given Internet host and

296

port: socket family <a class="reference internal" href="socket.html#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-data docutils literal">AF_INET</code></a> or

297

<a class="reference internal" href="socket.html#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-data docutils literal">AF_INET6</code></a> depending on host (or family if specified),

298

socket type <a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-data docutils literal">SOCK_STREAM</code></a>. protocol_factory must be a

299

callable returning a <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol">protocol</a> instance.

300

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a> which will try to

301

establish the connection in the background. When successful, the

302

coroutine returns a <code class="docutils literal">(transport, protocol)</code> pair.

303

The chronological synopsis of the underlying operation is as follows:

304

305

<li>The connection is established, and a <a class="reference internal" href="asyncio-protocol.html#asyncio-transport">transport</a>

306

is created to represent it.</li>

307

<li>protocol_factory is called without arguments and must return a

308

<a class="reference internal" href="asyncio-protocol.html#asyncio-protocol">protocol</a> instance.</li>

309

<li>The protocol instance is tied to the transport, and its

310

<code class="xref py py-meth docutils literal">connection_made()</code> method is called.</li>

311

<li>The coroutine returns successfully with the <code class="docutils literal">(transport, protocol)</code>

312

pair.</li>

313

</ol>

314

The created transport is an implementation-dependent bidirectional stream.

315

316

Note

317

protocol_factory can be any kind of callable, not necessarily

318

a class. For example, if you want to use a pre-created

319

protocol instance, you can pass <code class="docutils literal">lambda: my_protocol</code>.

320

</div>

321

Options that change how the connection is created:

322

<ul>

323

<li>ssl: if given and not false, a SSL/TLS transport is created

324

(by default a plain TCP transport is created). If ssl is

325

a <a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">ssl.SSLContext</code></a> object, this context is used to create

326

the transport; if ssl is <a class="reference internal" href="constants.html#True" title="True"><code class="xref py py-const docutils literal">True</code></a>, a context with some

327

unspecified default settings is used.

328

329

See also

330

<a class="reference internal" href="ssl.html#ssl-security">SSL/TLS security considerations</a>

331

</div>

332

</li>

333

<li>server_hostname, is only for use together with ssl,

334

and sets or overrides the hostname that the target server’s certificate

335

will be matched against. By default the value of the host argument

336

is used. If host is empty, there is no default and you must pass a

337

value for server_hostname. If server_hostname is an empty

338

string, hostname matching is disabled (which is a serious security

339

risk, allowing for man-in-the-middle-attacks).

340

</li>

341

<li>family, proto, flags are the optional address family, protocol

342

and flags to be passed through to getaddrinfo() for host resolution.

343

If given, these should all be integers from the corresponding

344

<a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal">socket</code></a> module constants.

345

</li>

346

<li>sock, if given, should be an existing, already connected

347

<a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal">socket.socket</code></a> object to be used by the transport.

348

If sock is given, none of host, port, family, proto, flags

349

and local_addr should be specified.

350

</li>

351

<li>local_addr, if given, is a <code class="docutils literal">(local_host, local_port)</code> tuple used

352

to bind the socket to locally. The local_host and local_port

353

are looked up using getaddrinfo(), similarly to host and port.

354

</li>

355

</ul>

356

357

Changed in version 3.5: On Windows with <a class="reference internal" href="asyncio-eventloops.html#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal">ProactorEventLoop</code></a>, SSL/TLS is now supported.

358

</div>

359

360

See also

361

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 can be used to get a pair of

362

(<a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal">StreamReader</code></a>, <a class="reference internal" href="asyncio-stream.html#asyncio.StreamWriter" title="asyncio.StreamWriter"><code class="xref py py-class docutils literal">StreamWriter</code></a>) instead of a protocol.

363

</div>

364

</dd></dl>

365

366

367

368

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">create_datagram_endpoint</code>(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)<a class="headerlink" href="#asyncio.BaseEventLoop.create_datagram_endpoint" title="Permalink to this definition">¶</a></dt>

369

<dd>Create datagram connection: socket family <a class="reference internal" href="socket.html#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-data docutils literal">AF_INET</code></a> or

370

371

socket type <a class="reference internal" href="socket.html#socket.SOCK_DGRAM" title="socket.SOCK_DGRAM"><code class="xref py py-data docutils literal">SOCK_DGRAM</code></a>. protocol_factory must be a

372

callable returning a <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol">protocol</a> instance.

373

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a> which will try to

374

establish the connection in the background. When successful, the

375

coroutine returns a <code class="docutils literal">(transport, protocol)</code> pair.

376

Options changing how the connection is created:

377

378

<li>local_addr, if given, is a <code class="docutils literal">(local_host, local_port)</code> tuple used

379

to bind the socket to locally. The local_host and local_port

380

are looked up using <a class="reference internal" href="#asyncio.BaseEventLoop.getaddrinfo" title="asyncio.BaseEventLoop.getaddrinfo"><code class="xref py py-meth docutils literal">getaddrinfo()</code></a>.</li>

381

<li>remote_addr, if given, is a <code class="docutils literal">(remote_host, remote_port)</code> tuple used

382

to connect the socket to a remote address. The remote_host and

383

remote_port are looked up using <a class="reference internal" href="#asyncio.BaseEventLoop.getaddrinfo" title="asyncio.BaseEventLoop.getaddrinfo"><code class="xref py py-meth docutils literal">getaddrinfo()</code></a>.</li>

384

<li>family, proto, flags are the optional address family, protocol

385

and flags to be passed through to <a class="reference internal" href="#asyncio.BaseEventLoop.getaddrinfo" title="asyncio.BaseEventLoop.getaddrinfo"><code class="xref py py-meth docutils literal">getaddrinfo()</code></a> for host

386

resolution. If given, these should all be integers from the

387

corresponding <a class="reference internal" href="socket.html#module-socket" title="socket: Low-level networking interface."><code class="xref py py-mod docutils literal">socket</code></a> module constants.</li>

388

<li>reuse_address tells the kernel to reuse a local socket in

389

TIME_WAIT state, without waiting for its natural timeout to

390

expire. If not specified will automatically be set to True on

391

UNIX.</li>

392

<li>reuse_port tells the kernel to allow this endpoint to be bound to the

393

same port as other existing endpoints are bound to, so long as they all

394

set this flag when being created. This option is not supported on Windows

395

and some UNIX’s. If the <code class="xref py py-data docutils literal">SO_REUSEPORT</code> constant is not

396

defined then this capability is unsupported.</li>

397

<li>allow_broadcast tells the kernel to allow this endpoint to send

398

messages to the broadcast address.</li>

399

<li>sock can optionally be specified in order to use a preexisting,

400

already connected, <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal">socket.socket</code></a> object to be used by the

401

transport. If specified, local_addr and remote_addr should be omitted

402

(must be <a class="reference internal" href="constants.html#None" title="None"><code class="xref py py-const docutils literal">None</code></a>).</li>

403

</ul>

404

On Windows with <a class="reference internal" href="asyncio-eventloops.html#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal">ProactorEventLoop</code></a>, this method is not supported.

405

See <a class="reference internal" href="asyncio-protocol.html#asyncio-udp-echo-client-protocol">UDP echo client protocol</a> and

406

<a class="reference internal" href="asyncio-protocol.html#asyncio-udp-echo-server-protocol">UDP echo server protocol</a> examples.

407

</dd></dl>

408

409

410

411

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">create_unix_connection</code>(protocol_factory, path, *, ssl=None, sock=None, server_hostname=None)<a class="headerlink" href="#asyncio.BaseEventLoop.create_unix_connection" title="Permalink to this definition">¶</a></dt>

412

<dd>Create UNIX connection: socket family <a class="reference internal" href="socket.html#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-data docutils literal">AF_UNIX</code></a>, socket

413

type <a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-data docutils literal">SOCK_STREAM</code></a>. The <a class="reference internal" href="socket.html#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-data docutils literal">AF_UNIX</code></a> socket

414

family is used to communicate between processes on the same machine

415

efficiently.

416

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a> which will try to

417

establish the connection in the background. When successful, the

418

coroutine returns a <code class="docutils literal">(transport, protocol)</code> pair.

419

See the <a class="reference internal" href="#asyncio.BaseEventLoop.create_connection" title="asyncio.BaseEventLoop.create_connection"><code class="xref py py-meth docutils literal">BaseEventLoop.create_connection()</code></a> method for parameters.

420

Availability: UNIX.

421

</dd></dl>

422

423

</div>

424

425

<h2>18.5.1.6. Creating listening connections<a class="headerlink" href="#creating-listening-connections" title="Permalink to this headline">¶</a></h2>

426

427

428

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">create_server</code>(protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None)<a class="headerlink" href="#asyncio.BaseEventLoop.create_server" title="Permalink to this definition">¶</a></dt>

429

<dd>Create a TCP server (socket type <a class="reference internal" href="socket.html#socket.SOCK_STREAM" title="socket.SOCK_STREAM"><code class="xref py py-data docutils literal">SOCK_STREAM</code></a>) bound to

430

host and port.

431

Return a <a class="reference internal" href="#asyncio.Server" title="asyncio.Server"><code class="xref py py-class docutils literal">Server</code></a> object, its <a class="reference internal" href="#asyncio.Server.sockets" title="asyncio.Server.sockets"><code class="xref py py-attr docutils literal">sockets</code></a> attribute

432

contains created sockets. Use the <a class="reference internal" href="#asyncio.Server.close" title="asyncio.Server.close"><code class="xref py py-meth docutils literal">Server.close()</code></a> method to stop the

433

server: close listening sockets.

434

Parameters:

435

436

<li>The host parameter can be a string, in that case the TCP server is

437

bound to host and port. The host parameter can also be a sequence

438

of strings and in that case the TCP server is bound to all hosts of the

439

sequence. If host is an empty string or <code class="docutils literal">None</code>, all interfaces are

440

assumed and a list of multiple sockets will be returned (most likely one

441

for IPv4 and another one for IPv6).</li>

442

<li>family can be set to either <a class="reference internal" href="socket.html#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-data docutils literal">socket.AF_INET</code></a> or

443

<a class="reference internal" href="socket.html#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-data docutils literal">AF_INET6</code></a> to force the socket to use IPv4 or IPv6. If not set

444

it will be determined from host (defaults to <code class="xref py py-data docutils literal">socket.AF_UNSPEC</code>).</li>

445

<li>flags is a bitmask for <a class="reference internal" href="#asyncio.BaseEventLoop.getaddrinfo" title="asyncio.BaseEventLoop.getaddrinfo"><code class="xref py py-meth docutils literal">getaddrinfo()</code></a>.</li>

446

<li>sock can optionally be specified in order to use a preexisting

447

socket object. If specified, host and port should be omitted (must be

448

449

<li>backlog is the maximum number of queued connections passed to

450

<a class="reference internal" href="socket.html#socket.socket.listen" title="socket.socket.listen"><code class="xref py py-meth docutils literal">listen()</code></a> (defaults to 100).</li>

451

<li>ssl can be set to an <a class="reference internal" href="ssl.html#ssl.SSLContext" title="ssl.SSLContext"><code class="xref py py-class docutils literal">SSLContext</code></a> to enable SSL over the

452

accepted connections.</li>

453

<li>reuse_address tells the kernel to reuse a local socket in

454

TIME_WAIT state, without waiting for its natural timeout to

455

expire. If not specified will automatically be set to True on

456

UNIX.</li>

457

<li>reuse_port tells the kernel to allow this endpoint to be bound to the

458

same port as other existing endpoints are bound to, so long as they all

459

set this flag when being created. This option is not supported on

460

Windows.</li>

461

</ul>

462

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

463

464

465

</div>

466

467

See also

468

The function <a class="reference internal" href="asyncio-stream.html#asyncio.start_server" title="asyncio.start_server"><code class="xref py py-func docutils literal">start_server()</code></a> creates a (<a class="reference internal" href="asyncio-stream.html#asyncio.StreamReader" title="asyncio.StreamReader"><code class="xref py py-class docutils literal">StreamReader</code></a>,

469

<a class="reference internal" href="asyncio-stream.html#asyncio.StreamWriter" title="asyncio.StreamWriter"><code class="xref py py-class docutils literal">StreamWriter</code></a>) pair and calls back a function with this pair.

470

</div>

471

472

Changed in version 3.5.1: The host parameter can now be a sequence of strings.

473

</div>

474

</dd></dl>

475

476

477

478

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">create_unix_server</code>(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None)<a class="headerlink" href="#asyncio.BaseEventLoop.create_unix_server" title="Permalink to this definition">¶</a></dt>

479

<dd>Similar to <a class="reference internal" href="#asyncio.BaseEventLoop.create_server" title="asyncio.BaseEventLoop.create_server"><code class="xref py py-meth docutils literal">BaseEventLoop.create_server()</code></a>, but specific to the

480

socket family <a class="reference internal" href="socket.html#socket.AF_UNIX" title="socket.AF_UNIX"><code class="xref py py-data docutils literal">AF_UNIX</code></a>.

481

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

482

Availability: UNIX.

483

</dd></dl>

484

485

</div>

486

487

<h2>18.5.1.7. Watch file descriptors<a class="headerlink" href="#watch-file-descriptors" title="Permalink to this headline">¶</a></h2>

488

On Windows with <a class="reference internal" href="asyncio-eventloops.html#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal">SelectorEventLoop</code></a>, only socket handles are supported

489

(ex: pipe file descriptors are not supported).

490

491

492

493

<code class="descclassname">BaseEventLoop.</code><code class="descname">add_reader</code>(fd, callback, *args)<a class="headerlink" href="#asyncio.BaseEventLoop.add_reader" title="Permalink to this definition">¶</a></dt>

494

<dd>Start watching the file descriptor for read availability and then call the

495

callback with specified arguments.

496

<a class="reference internal" href="#asyncio-pass-keywords">Use functools.partial to pass keywords to the callback</a>.

497

</dd></dl>

498

499

500

501

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

502

<dd>Stop watching the file descriptor for read availability.

503

</dd></dl>

504

505

506

507

<code class="descclassname">BaseEventLoop.</code><code class="descname">add_writer</code>(fd, callback, *args)<a class="headerlink" href="#asyncio.BaseEventLoop.add_writer" title="Permalink to this definition">¶</a></dt>

508

<dd>Start watching the file descriptor for write availability and then call the

509

callback with specified arguments.

510

<a class="reference internal" href="#asyncio-pass-keywords">Use functools.partial to pass keywords to the callback</a>.

511

</dd></dl>

512

513

514

515

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

516

<dd>Stop watching the file descriptor for write availability.

517

</dd></dl>

518

519

The <a class="reference internal" href="#asyncio-watch-read-event">watch a file descriptor for read events</a>

520

example uses the low-level <a class="reference internal" href="#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

521

the file descriptor of a socket.

522

</div>

523

524

<h2>18.5.1.8. Low-level socket operations<a class="headerlink" href="#low-level-socket-operations" title="Permalink to this headline">¶</a></h2>

525

526

527

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">sock_recv</code>(sock, nbytes)<a class="headerlink" href="#asyncio.BaseEventLoop.sock_recv" title="Permalink to this definition">¶</a></dt>

528

<dd>Receive data from the socket. The return value is a bytes object

529

representing the data received. The maximum amount of data to be received

530

at once is specified by nbytes.

531

With <a class="reference internal" href="asyncio-eventloops.html#asyncio.SelectorEventLoop" title="asyncio.SelectorEventLoop"><code class="xref py py-class docutils literal">SelectorEventLoop</code></a> event loop, the socket sock must be

532

non-blocking.

533

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

534

535

See also

536

The <a class="reference internal" href="socket.html#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal">socket.socket.recv()</code></a> method.

537

</div>

538

</dd></dl>

539

540

541

542

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">sock_sendall</code>(sock, data)<a class="headerlink" href="#asyncio.BaseEventLoop.sock_sendall" title="Permalink to this definition">¶</a></dt>

543

<dd>Send data to the socket. The socket must be connected to a remote socket.

544

This method continues to send data from data until either all data has

545

been sent or an error occurs. <code class="docutils literal">None</code> is returned on success. On error,

546

an exception is raised, and there is no way to determine how much data, if

547

any, was successfully processed by the receiving end of the connection.

548

549

non-blocking.

550

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

551

552

See also

553

The <a class="reference internal" href="socket.html#socket.socket.sendall" title="socket.socket.sendall"><code class="xref py py-meth docutils literal">socket.socket.sendall()</code></a> method.

554

</div>

555

</dd></dl>

556

557

558

559

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">sock_connect</code>(sock, address)<a class="headerlink" href="#asyncio.BaseEventLoop.sock_connect" title="Permalink to this definition">¶</a></dt>

560

<dd>Connect to a remote socket at address.

561

The address must be already resolved to avoid the trap of hanging the

562

entire event loop when the address requires doing a DNS lookup. For

563

example, it must be an IP address, not an hostname, for

564

<a class="reference internal" href="socket.html#socket.AF_INET" title="socket.AF_INET"><code class="xref py py-data docutils literal">AF_INET</code></a> and <a class="reference internal" href="socket.html#socket.AF_INET6" title="socket.AF_INET6"><code class="xref py py-data docutils literal">AF_INET6</code></a> address families.

565

Use <a class="reference internal" href="#asyncio.BaseEventLoop.getaddrinfo" title="asyncio.BaseEventLoop.getaddrinfo"><code class="xref py py-meth docutils literal">getaddrinfo()</code></a> to resolve the hostname asynchronously.

566

567

non-blocking.

568

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

569

570

See also

571

The <a class="reference internal" href="#asyncio.BaseEventLoop.create_connection" title="asyncio.BaseEventLoop.create_connection"><code class="xref py py-meth docutils literal">BaseEventLoop.create_connection()</code></a> method, the

572

<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 and the <a class="reference internal" href="socket.html#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal">socket.socket.connect()</code></a>

573

method.

574

</div>

575

</dd></dl>

576

577

578

579

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

580

<dd>Accept a connection. The socket must be bound to an address and listening

581

for connections. The return value is a pair <code class="docutils literal">(conn, address)</code> where conn

582

is a new socket object usable to send and receive data on the connection,

583

and address is the address bound to the socket on the other end of the

584

connection.

585

The socket sock must be non-blocking.

586

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

587

588

See also

589

The <a class="reference internal" href="#asyncio.BaseEventLoop.create_server" title="asyncio.BaseEventLoop.create_server"><code class="xref py py-meth docutils literal">BaseEventLoop.create_server()</code></a> method, the <a class="reference internal" href="asyncio-stream.html#asyncio.start_server" title="asyncio.start_server"><code class="xref py py-func docutils literal">start_server()</code></a>

590

function and the <a class="reference internal" href="socket.html#socket.socket.accept" title="socket.socket.accept"><code class="xref py py-meth docutils literal">socket.socket.accept()</code></a> method.

591

</div>

592

</dd></dl>

593

594

</div>

595

596

<h2>18.5.1.9. Resolve host name<a class="headerlink" href="#resolve-host-name" title="Permalink to this headline">¶</a></h2>

597

598

599

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">getaddrinfo</code>(host, port, *, family=0, type=0, proto=0, flags=0)<a class="headerlink" href="#asyncio.BaseEventLoop.getaddrinfo" title="Permalink to this definition">¶</a></dt>

600

<dd>This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>, similar to

601

<a class="reference internal" href="socket.html#socket.getaddrinfo" title="socket.getaddrinfo"><code class="xref py py-meth docutils literal">socket.getaddrinfo()</code></a> function but non-blocking.

602

</dd></dl>

603

604

605

606

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">getnameinfo</code>(sockaddr, flags=0)<a class="headerlink" href="#asyncio.BaseEventLoop.getnameinfo" title="Permalink to this definition">¶</a></dt>

607

<dd>This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>, similar to

608

<a class="reference internal" href="socket.html#socket.getnameinfo" title="socket.getnameinfo"><code class="xref py py-meth docutils literal">socket.getnameinfo()</code></a> function but non-blocking.

609

</dd></dl>

610

611

</div>

612

613

<h2>18.5.1.10. Connect pipes<a class="headerlink" href="#connect-pipes" title="Permalink to this headline">¶</a></h2>

614

615

Use <a class="reference internal" href="asyncio-eventloops.html#asyncio.ProactorEventLoop" title="asyncio.ProactorEventLoop"><code class="xref py py-class docutils literal">ProactorEventLoop</code></a> to support pipes on Windows.

616

617

618

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">connect_read_pipe</code>(protocol_factory, pipe)<a class="headerlink" href="#asyncio.BaseEventLoop.connect_read_pipe" title="Permalink to this definition">¶</a></dt>

619

<dd>Register read pipe in eventloop.

620

protocol_factory should instantiate object with <a class="reference internal" href="asyncio-protocol.html#asyncio.Protocol" title="asyncio.Protocol"><code class="xref py py-class docutils literal">Protocol</code></a>

621

interface. pipe is a <a class="reference internal" href="../glossary.html#term-file-object">file-like object</a>.

622

Return pair <code class="docutils literal">(transport, protocol)</code>, where transport supports the

623

<a class="reference internal" href="asyncio-protocol.html#asyncio.ReadTransport" title="asyncio.ReadTransport"><code class="xref py py-class docutils literal">ReadTransport</code></a> interface.

624

625

non-blocking mode.

626

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

627

</dd></dl>

628

629

630

631

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">connect_write_pipe</code>(protocol_factory, pipe)<a class="headerlink" href="#asyncio.BaseEventLoop.connect_write_pipe" title="Permalink to this definition">¶</a></dt>

632

<dd>Register write pipe in eventloop.

633

protocol_factory should instantiate object with <code class="xref py py-class docutils literal">BaseProtocol</code>

634

interface. pipe is <a class="reference internal" href="../glossary.html#term-file-object">file-like object</a>.

635

Return pair <code class="docutils literal">(transport, protocol)</code>, where transport supports

636

<a class="reference internal" href="asyncio-protocol.html#asyncio.WriteTransport" title="asyncio.WriteTransport"><code class="xref py py-class docutils literal">WriteTransport</code></a> interface.

637

638

non-blocking mode.

639

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

640

</dd></dl>

641

642

643

See also

644

The <a class="reference internal" href="asyncio-subprocess.html#asyncio.BaseEventLoop.subprocess_exec" title="asyncio.BaseEventLoop.subprocess_exec"><code class="xref py py-meth docutils literal">BaseEventLoop.subprocess_exec()</code></a> and

645

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

646

</div>

647

</div>

648

649

<h2>18.5.1.11. UNIX signals<a class="headerlink" href="#unix-signals" title="Permalink to this headline">¶</a></h2>

650

Availability: UNIX only.

651

652

653

<code class="descclassname">BaseEventLoop.</code><code class="descname">add_signal_handler</code>(signum, callback, *args)<a class="headerlink" href="#asyncio.BaseEventLoop.add_signal_handler" title="Permalink to this definition">¶</a></dt>

654

<dd>Add a handler for a signal.

655

Raise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> if the signal number is invalid or uncatchable.

656

Raise <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal">RuntimeError</code></a> if there is a problem setting up the handler.

657

<a class="reference internal" href="#asyncio-pass-keywords">Use functools.partial to pass keywords to the callback</a>.

658

</dd></dl>

659

660

661

662

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

663

<dd>Remove a handler for a signal.

664

Return <code class="docutils literal">True</code> if a signal handler was removed, <code class="docutils literal">False</code> if not.

665

</dd></dl>

666

667

668

See also

669

The <a class="reference internal" href="signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal">signal</code></a> module.

670

</div>

671

</div>

672

673

<h2>18.5.1.12. Executor<a class="headerlink" href="#executor" title="Permalink to this headline">¶</a></h2>

674

Call a function in an <a class="reference internal" href="concurrent.futures.html#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal">Executor</code></a> (pool of threads or

675

pool of processes). By default, an event loop uses a thread pool executor

676

(<a class="reference internal" href="concurrent.futures.html#concurrent.futures.ThreadPoolExecutor" title="concurrent.futures.ThreadPoolExecutor"><code class="xref py py-class docutils literal">ThreadPoolExecutor</code></a>).

677

678

679

coroutine <code class="descclassname">BaseEventLoop.</code><code class="descname">run_in_executor</code>(executor, func, *args)<a class="headerlink" href="#asyncio.BaseEventLoop.run_in_executor" title="Permalink to this definition">¶</a></dt>

680

<dd>Arrange for a func to be called in the specified executor.

681

The executor argument should be an <a class="reference internal" href="concurrent.futures.html#concurrent.futures.Executor" title="concurrent.futures.Executor"><code class="xref py py-class docutils literal">Executor</code></a>

682

instance. The default executor is used if executor is <code class="docutils literal">None</code>.

683

<a class="reference internal" href="#asyncio-pass-keywords">Use functools.partial to pass keywords to the *func*</a>.

684

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

685

</dd></dl>

686

687

688

689

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

690

<dd>Set the default executor used by <a class="reference internal" href="#asyncio.BaseEventLoop.run_in_executor" title="asyncio.BaseEventLoop.run_in_executor"><code class="xref py py-meth docutils literal">run_in_executor()</code></a>.

691

</dd></dl>

692

693

</div>

694

695

<h2>18.5.1.13. Error Handling API<a class="headerlink" href="#error-handling-api" title="Permalink to this headline">¶</a></h2>

696

Allows customizing how exceptions are handled in the event loop.

697

698

699

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

700

<dd>Set handler as the new event loop exception handler.

701

If handler is <code class="docutils literal">None</code>, the default exception handler will

702

be set.

703

If handler is a callable object, it should have a

704

matching signature to <code class="docutils literal">(loop, context)</code>, where <code class="docutils literal">loop</code>

705

will be a reference to the active event loop, <code class="docutils literal">context</code>

706

will be a <code class="docutils literal">dict</code> object (see <a class="reference internal" href="#asyncio.BaseEventLoop.call_exception_handler" title="asyncio.BaseEventLoop.call_exception_handler"><code class="xref py py-meth docutils literal">call_exception_handler()</code></a>

707

documentation for details about context).

708

</dd></dl>

709

710

711

712

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

713

<dd>Default exception handler.

714

This is called when an exception occurs and no exception

715

handler is set, and can be called by a custom exception

716

handler that wants to defer to the default behavior.

717

context parameter has the same meaning as in

718

<a class="reference internal" href="#asyncio.BaseEventLoop.call_exception_handler" title="asyncio.BaseEventLoop.call_exception_handler"><code class="xref py py-meth docutils literal">call_exception_handler()</code></a>.

719

</dd></dl>

720

721

722

723

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

724

<dd>Call the current event loop exception handler.

725

context is a <code class="docutils literal">dict</code> object containing the following keys

726

(new keys may be introduced later):

727

728

<li>‘message’: Error message;</li>

729

<li>‘exception’ (optional): Exception object;</li>

730

<li>‘future’ (optional): <a class="reference internal" href="asyncio-task.html#asyncio.Future" title="asyncio.Future"><code class="xref py py-class docutils literal">asyncio.Future</code></a> instance;</li>

731

<li>‘handle’ (optional): <a class="reference internal" href="#asyncio.Handle" title="asyncio.Handle"><code class="xref py py-class docutils literal">asyncio.Handle</code></a> instance;</li>

732

<li>‘protocol’ (optional): <a class="reference internal" href="asyncio-protocol.html#asyncio-protocol">Protocol</a> instance;</li>

733

<li>‘transport’ (optional): <a class="reference internal" href="asyncio-protocol.html#asyncio-transport">Transport</a> instance;</li>

734

<li>‘socket’ (optional): <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>

735

</ul>

736

737

Note

738

Note: this method should not be overloaded in subclassed

739

event loops. For any custom exception handling, use

740

<a class="reference internal" href="#asyncio.BaseEventLoop.set_exception_handler" title="asyncio.BaseEventLoop.set_exception_handler"><code class="xref py py-meth docutils literal">set_exception_handler()</code></a> method.

741

</div>

742

</dd></dl>

743

744

</div>

745

746

<h2>18.5.1.14. Debug mode<a class="headerlink" href="#debug-mode" title="Permalink to this headline">¶</a></h2>

747

748

749

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

750

<dd>Get the debug mode (<a class="reference internal" href="functions.html#bool" title="bool"><code class="xref py py-class docutils literal">bool</code></a>) of the event loop.

751

The default value is <code class="docutils literal">True</code> if the environment variable

752

<a class="reference internal" href="../using/cmdline.html#envvar-PYTHONASYNCIODEBUG"><code class="xref std std-envvar docutils literal">PYTHONASYNCIODEBUG</code></a> is set to a non-empty string, <code class="docutils literal">False</code>

753

otherwise.

754

755

New in version 3.4.2.

756

</div>

757

</dd></dl>

758

759

760

761

<code class="descclassname">BaseEventLoop.</code><code class="descname">set_debug</code>(enabled: bool)<a class="headerlink" href="#asyncio.BaseEventLoop.set_debug" title="Permalink to this definition">¶</a></dt>

762

<dd>Set the debug mode of the event loop.

763

764

New in version 3.4.2.

765

</div>

766

</dd></dl>

767

768

769

See also

770

The <a class="reference internal" href="asyncio-dev.html#asyncio-debug-mode">debug mode of asyncio</a>.

771

</div>

772

</div>

773

774

<h2>18.5.1.15. Server<a class="headerlink" href="#server" title="Permalink to this headline">¶</a></h2>

775

776

777

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

778

<dd>Server listening on sockets.

779

Object created by the <a class="reference internal" href="#asyncio.BaseEventLoop.create_server" title="asyncio.BaseEventLoop.create_server"><code class="xref py py-meth docutils literal">BaseEventLoop.create_server()</code></a> method and the

780

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

781

782

783

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

784

<dd>Stop serving: close listening sockets and set the <a class="reference internal" href="#asyncio.Server.sockets" title="asyncio.Server.sockets"><code class="xref py py-attr docutils literal">sockets</code></a>

785

attribute to <code class="docutils literal">None</code>.

786

The sockets that represent existing incoming client connections are left

787

open.

788

The server is closed asynchronously, use the <a class="reference internal" href="#asyncio.Server.wait_closed" title="asyncio.Server.wait_closed"><code class="xref py py-meth docutils literal">wait_closed()</code></a>

789

coroutine to wait until the server is closed.

790

</dd></dl>

791

792

793

794

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

795

<dd>Wait until the <a class="reference internal" href="#asyncio.Server.close" title="asyncio.Server.close"><code class="xref py py-meth docutils literal">close()</code></a> method completes.

796

This method is a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

797

</dd></dl>

798

799

800

801

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

802

<dd>List of <a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal">socket.socket</code></a> objects the server is listening to, or

803

<code class="docutils literal">None</code> if the server is closed.

804

</dd></dl>

805

806

</dd></dl>

807

808

</div>

809

810

<h2>18.5.1.16. Handle<a class="headerlink" href="#handle" title="Permalink to this headline">¶</a></h2>

811

812

813

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

814

<dd>A callback wrapper object returned by <a class="reference internal" href="#asyncio.BaseEventLoop.call_soon" title="asyncio.BaseEventLoop.call_soon"><code class="xref py py-func docutils literal">BaseEventLoop.call_soon()</code></a>,

815

<a class="reference internal" href="#asyncio.BaseEventLoop.call_soon_threadsafe" title="asyncio.BaseEventLoop.call_soon_threadsafe"><code class="xref py py-func docutils literal">BaseEventLoop.call_soon_threadsafe()</code></a>, <a class="reference internal" href="#asyncio.BaseEventLoop.call_later" title="asyncio.BaseEventLoop.call_later"><code class="xref py py-func docutils literal">BaseEventLoop.call_later()</code></a>,

816

and <a class="reference internal" href="#asyncio.BaseEventLoop.call_at" title="asyncio.BaseEventLoop.call_at"><code class="xref py py-func docutils literal">BaseEventLoop.call_at()</code></a>.

817

818

819

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

820

<dd>Cancel the call. If the callback is already canceled or executed,

821

this method has no effect.

822

</dd></dl>

823

824

</dd></dl>

825

826

</div>

827

828

<h2>18.5.1.17. Event loop examples<a class="headerlink" href="#event-loop-examples" title="Permalink to this headline">¶</a></h2>

829

830

<h3>18.5.1.17.1. Hello World with call_soon()<a class="headerlink" href="#hello-world-with-call-soon" title="Permalink to this headline">¶</a></h3>

831

Example using the <a class="reference internal" href="#asyncio.BaseEventLoop.call_soon" title="asyncio.BaseEventLoop.call_soon"><code class="xref py py-meth docutils literal">BaseEventLoop.call_soon()</code></a> method to schedule a

832

callback. The callback displays <code class="docutils literal">"Hello World"</code> and then stops the event

833

loop:

834

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

835

836

def hello_world(loop):

837

print('Hello World')

838

loop.stop()

839

840

loop = asyncio.get_event_loop()

841

842

# Schedule a call to hello_world()

843

loop.call_soon(hello_world, loop)

844

845

# Blocking call interrupted by loop.stop()

846

loop.run_forever()

847

loop.close()

848

</pre></div>

849

</div>

850

851

See also

852

The <a class="reference internal" href="asyncio-task.html#asyncio-hello-world-coroutine">Hello World coroutine</a> example

853

uses a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

854

</div>

855

</div>

856

857

<h3>18.5.1.17.2. Display the current date with call_later()<a class="headerlink" href="#display-the-current-date-with-call-later" title="Permalink to this headline">¶</a></h3>

858

Example of callback displaying the current date every second. The callback uses

859

the <a class="reference internal" href="#asyncio.BaseEventLoop.call_later" title="asyncio.BaseEventLoop.call_later"><code class="xref py py-meth docutils literal">BaseEventLoop.call_later()</code></a> method to reschedule itself during 5

860

seconds, and then stops the event loop:

861

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

862

import datetime

863

864

def display_date(end_time, loop):

865

print(datetime.datetime.now())

866

if (loop.time() + 1.0) < end_time:

867

loop.call_later(1, display_date, end_time, loop)

868

else:

869

loop.stop()

870

871

loop = asyncio.get_event_loop()

872

873

# Schedule the first call to display_date()

874

end_time = loop.time() + 5.0

875

loop.call_soon(display_date, end_time, loop)

876

877

# Blocking call interrupted by loop.stop()

878

loop.run_forever()

879

loop.close()

880

</pre></div>

881

</div>

882

883

See also

884

The <a class="reference internal" href="asyncio-task.html#asyncio-date-coroutine">coroutine displaying the current date</a> example uses a <a class="reference internal" href="asyncio-task.html#coroutine">coroutine</a>.

885

</div>

886

</div>

887

888

<h3>18.5.1.17.3. Watch a file descriptor for read events<a class="headerlink" href="#watch-a-file-descriptor-for-read-events" title="Permalink to this headline">¶</a></h3>

889

Wait until a file descriptor received some data using the

890

<a class="reference internal" href="#asyncio.BaseEventLoop.add_reader" title="asyncio.BaseEventLoop.add_reader"><code class="xref py py-meth docutils literal">BaseEventLoop.add_reader()</code></a> method and then close the event loop:

891

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

892

try:

893

from socket import socketpair

894

except ImportError:

895

from asyncio.windows_utils import socketpair

896

897

# Create a pair of connected file descriptors

898

rsock, wsock = socketpair()

899

loop = asyncio.get_event_loop()

900

901

def reader():

902

data = rsock.recv(100)

903

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

904

# We are done: unregister the file descriptor

905

loop.remove_reader(rsock)

906

# Stop the event loop

907

loop.stop()

908

909

# Register the file descriptor for read event

910

loop.add_reader(rsock, reader)

911

912

# Simulate the reception of data from the network

913

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

914

915

# Run the event loop

916

loop.run_forever()

917

918

# We are done, close sockets and the event loop

919

rsock.close()

920

wsock.close()

921

loop.close()

922

</pre></div>

923

</div>

924

925

See also

926

The <a class="reference internal" href="asyncio-protocol.html#asyncio-register-socket">register an open socket to wait for data using a protocol</a> example uses a low-level protocol created by the

927

<a class="reference internal" href="#asyncio.BaseEventLoop.create_connection" title="asyncio.BaseEventLoop.create_connection"><code class="xref py py-meth docutils literal">BaseEventLoop.create_connection()</code></a> method.

928

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

929

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.

930

</div>

931

</div>

932

933

<h3>18.5.1.17.4. Set signal handlers for SIGINT and SIGTERM<a class="headerlink" href="#set-signal-handlers-for-sigint-and-sigterm" title="Permalink to this headline">¶</a></h3>

934

Register handlers for signals <code class="xref py py-data docutils literal">SIGINT</code> and <code class="xref py py-data docutils literal">SIGTERM</code> using

935

the <a class="reference internal" href="#asyncio.BaseEventLoop.add_signal_handler" title="asyncio.BaseEventLoop.add_signal_handler"><code class="xref py py-meth docutils literal">BaseEventLoop.add_signal_handler()</code></a> method:

936

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

937

import functools

938

import os

939

import signal

940

941

def ask_exit(signame):

942

print("got signal %s: exit" % signame)

943

loop.stop()

944

945

loop = asyncio.get_event_loop()

946

for signame in ('SIGINT', 'SIGTERM'):

947

loop.add_signal_handler(getattr(signal, signame),

948

functools.partial(ask_exit, signame))

949

950

print("Event loop running forever, press Ctrl+C to interrupt.")

951

print("pid %s: send SIGINT or SIGTERM to exit." % os.getpid())

952

try:

953

loop.run_forever()

954

finally:

955

loop.close()

956

</pre></div>

957

</div>

958

This example only works on UNIX.

959

</div>

960

</div>

961

</div>

962

963

964

</div>

965

</div>

966

</div>

967

968

969

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

970

<ul>

971

<li><a class="reference internal" href="#">18.5.1. Base Event Loop</a><ul>

972

<li><a class="reference internal" href="#run-an-event-loop">18.5.1.1. Run an event loop</a></li>

973

<li><a class="reference internal" href="#calls">18.5.1.2. Calls</a></li>

974

<li><a class="reference internal" href="#delayed-calls">18.5.1.3. Delayed calls</a></li>

975

<li><a class="reference internal" href="#tasks">18.5.1.4. Tasks</a></li>

976

<li><a class="reference internal" href="#creating-connections">18.5.1.5. Creating connections</a></li>

977

<li><a class="reference internal" href="#creating-listening-connections">18.5.1.6. Creating listening connections</a></li>

978

<li><a class="reference internal" href="#watch-file-descriptors">18.5.1.7. Watch file descriptors</a></li>

979

<li><a class="reference internal" href="#low-level-socket-operations">18.5.1.8. Low-level socket operations</a></li>

980

<li><a class="reference internal" href="#resolve-host-name">18.5.1.9. Resolve host name</a></li>

981

<li><a class="reference internal" href="#connect-pipes">18.5.1.10. Connect pipes</a></li>

982

<li><a class="reference internal" href="#unix-signals">18.5.1.11. UNIX signals</a></li>

983

<li><a class="reference internal" href="#executor">18.5.1.12. Executor</a></li>

984

<li><a class="reference internal" href="#error-handling-api">18.5.1.13. Error Handling API</a></li>

985

<li><a class="reference internal" href="#debug-mode">18.5.1.14. Debug mode</a></li>

986

<li><a class="reference internal" href="#server">18.5.1.15. Server</a></li>

987

<li><a class="reference internal" href="#handle">18.5.1.16. Handle</a></li>

988

<li><a class="reference internal" href="#event-loop-examples">18.5.1.17. Event loop examples</a><ul>

989

<li><a class="reference internal" href="#hello-world-with-call-soon">18.5.1.17.1. Hello World with call_soon()</a></li>

990

<li><a class="reference internal" href="#display-the-current-date-with-call-later">18.5.1.17.2. Display the current date with call_later()</a></li>

991

<li><a class="reference internal" href="#watch-a-file-descriptor-for-read-events">18.5.1.17.3. Watch a file descriptor for read events</a></li>

992

<li><a class="reference internal" href="#set-signal-handlers-for-sigint-and-sigterm">18.5.1.17.4. Set signal handlers for SIGINT and SIGTERM</a></li>

993

</ul>

994

</li>

995

</ul>

996

</li>

997

</ul>

998

999

<h4>Previous topic</h4>

1000

<a href="asyncio.html"

1001

title="previous chapter">18.5. <code class="docutils literal">asyncio</code> – Asynchronous I/O, event loop, coroutines and tasks</a>

1002

<h4>Next topic</h4>

1003

<a href="asyncio-eventloops.html"

1004

title="next chapter">18.5.2. Event loops</a>

1005

1006

1007

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

1008

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

1009

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

1010

</ul>

1011

1012

1013

<h3>Quick search</h3>

1014

1015

1016

1017

1018

1019

</form>

1020

1021

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

1022

1023

</div>

1024

1025

</div>

1026

</div>

1027

1028

</div>

1029

1030

<h3>Navigation</h3>

1031

<ul>

1032

1033

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

1034

>index</a></li>

1035

1036

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

1037

>modules</a> |</li>

1038

1039

<a href="asyncio-eventloops.html" title="18.5.2. Event loops"

1040

>next</a> |</li>

1041

1042

<a href="asyncio.html" title="18.5. asyncio – Asynchronous I/O, event loop, coroutines and tasks"

1043

>previous</a> |</li>

1044

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

1045

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

1046

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

1047

<li>

1048

3.5.1

1049

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

1050

</li>

1051

1052

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

1053

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

1054

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

1055

</ul>

1056

</div>

1057

1058

1059

1060

The Python Software Foundation is a non-profit corporation.

1061

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

1062

1063

Last updated on Feb 10, 2016.

1064

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

1065

1066

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

1067

</div>

1068

1069

</body>

1070

</html>

b'\\ No newline at end of file'

Older »