~dkuhlman/python-training-materials/Materials

<h1>16.2. <a class="reference internal" href="#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal">io</code></a> — Core tools for working with streams<a class="headerlink" href="#module-io" title="Permalink to this headline">¶</a></h1>

<h2>16.2.1. Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>

The <a class="reference internal" href="#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal">io</code></a> module provides Python’s main facilities for dealing with various

types of I/O. There are three main types of I/O: text I/O, binary I/O

and raw I/O. These are generic categories, and various backing stores can

be used for each of them. A concrete object belonging to any of these

categories is called a <a class="reference internal" href="../glossary.html#term-file-object">file object</a>. Other common terms are stream

and file-like object.

Independently of its category, each concrete stream object will also have

various capabilities: it can be read-only, write-only, or read-write. It can

also allow arbitrary random access (seeking forwards or backwards to any

location), or only sequential access (for example in the case of a socket or

pipe).

All streams are careful about the type of data you give to them. For example

giving a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> object to the <code class="docutils literal">write()</code> method of a binary stream

will raise a <code class="docutils literal">TypeError</code>. So will giving a <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a> object to the

<code class="docutils literal">write()</code> method of a text stream.

Changed in version 3.3: Operations that used to raise <a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal">IOError</code></a> now raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a>, since

<a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal">IOError</code></a> is now an alias of <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a>.

</div>

100

101

102

Text I/O expects and produces <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> objects. This means that whenever

103

the backing store is natively made of bytes (such as in the case of a file),

104

encoding and decoding of data is made transparently as well as optional

105

translation of platform-specific newline characters.

106

The easiest way to create a text stream is with <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-meth docutils literal">open()</code></a>, optionally

107

specifying an encoding:

108

<div class="highlight-python3"><div class="highlight"><pre>f = open("myfile.txt", "r", encoding="utf-8")

109

</pre></div>

110

</div>

111

In-memory text streams are also available as <a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal">StringIO</code></a> objects:

112

<div class="highlight-python3"><div class="highlight"><pre>f = io.StringIO("some initial text data")

113

</pre></div>

114

</div>

115

The text stream API is described in detail in the documentation of

116

<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a>.

117

</div>

118

119

<h3>16.2.1.2. Binary I/O<a class="headerlink" href="#binary-i-o" title="Permalink to this headline">¶</a></h3>

120

Binary I/O (also called buffered I/O) expects and produces <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a>

121

objects. No encoding, decoding, or newline translation is performed. This

122

category of streams can be used for all kinds of non-text data, and also when

123

manual control over the handling of text data is desired.

124

The easiest way to create a binary stream is with <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-meth docutils literal">open()</code></a> with <code class="docutils literal">'b'</code> in

125

the mode string:

126

<div class="highlight-python3"><div class="highlight"><pre>f = open("myfile.jpg", "rb")

127

</pre></div>

128

</div>

129

In-memory binary streams are also available as <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal">BytesIO</code></a> objects:

130

<div class="highlight-python3"><div class="highlight"><pre>f = io.BytesIO(b"some initial binary data: \x00\x01")

131

</pre></div>

132

</div>

133

The binary stream API is described in detail in the docs of

134

<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a>.

135

Other library modules may provide additional ways to create text or binary

136

streams. See <a class="reference internal" href="socket.html#socket.socket.makefile" title="socket.socket.makefile"><code class="xref py py-meth docutils literal">socket.socket.makefile()</code></a> for example.

137

</div>

138

139

140

Raw I/O (also called unbuffered I/O) is generally used as a low-level

141

building-block for binary and text streams; it is rarely useful to directly

142

manipulate a raw stream from user code. Nevertheless, you can create a raw

143

stream by opening a file in binary mode with buffering disabled:

144

<div class="highlight-python3"><div class="highlight"><pre>f = open("myfile.jpg", "rb", buffering=0)

145

</pre></div>

146

</div>

147

The raw stream API is described in detail in the docs of <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a>.

148

</div>

149

</div>

150

151

<h2>16.2.2. High-level Module Interface<a class="headerlink" href="#high-level-module-interface" title="Permalink to this headline">¶</a></h2>

152

153

154

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

155

<dd>An int containing the default buffer size used by the module’s buffered I/O

156

classes. <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> uses the file’s blksize (as obtained by

157

<a class="reference internal" href="os.html#os.stat" title="os.stat"><code class="xref py py-func docutils literal">os.stat()</code></a>) if possible.

158

</dd></dl>

159

160

161

162

<code class="descclassname">io.</code><code class="descname">open</code>(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, closefd=True, opener=None)<a class="headerlink" href="#io.open" title="Permalink to this definition">¶</a></dt>

163

<dd>This is an alias for the builtin <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> function.

164

</dd></dl>

165

166

167

168

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

169

<dd>This is a compatibility alias for the builtin <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal">BlockingIOError</code></a>

170

exception.

171

</dd></dl>

172

173

174

175

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

176

<dd>An exception inheriting <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> and <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> that is raised

177

when an unsupported operation is called on a stream.

178

</dd></dl>

179

180

181

<h3>16.2.2.1. In-memory streams<a class="headerlink" href="#in-memory-streams" title="Permalink to this headline">¶</a></h3>

182

It is also possible to use a <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a> or <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a>-like object as a

183

file for both reading and writing. For strings <a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal">StringIO</code></a> can be used

184

like a file opened in text mode. <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal">BytesIO</code></a> can be used like a file

185

opened in binary mode. Both provide full read-write capabilities with random

186

access.

187

188

See also

189

190

191

<dd>contains the standard IO streams: <a class="reference internal" href="sys.html#sys.stdin" title="sys.stdin"><code class="xref py py-data docutils literal">sys.stdin</code></a>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal">sys.stdout</code></a>,

192

and <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal">sys.stderr</code></a>.</dd>

193

</dl>

194

</div>

195

</div>

196

</div>

197

198

<h2>16.2.3. Class hierarchy<a class="headerlink" href="#class-hierarchy" title="Permalink to this headline">¶</a></h2>

199

The implementation of I/O streams is organized as a hierarchy of classes. First

200

<a class="reference internal" href="../glossary.html#term-abstract-base-class">abstract base classes</a> (ABCs), which are used to

201

specify the various categories of streams, then concrete classes providing the

202

standard stream implementations.

203

204

205

Note

206

The abstract base classes also provide default implementations of some

207

methods in order to help implementation of concrete stream classes. For

208

example, <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> provides unoptimized implementations of

209

<code class="xref py py-meth docutils literal">readinto()</code> and <a class="reference internal" href="#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal">readline()</code></a>.

210

</div>

211

</div></blockquote>

212

At the top of the I/O hierarchy is the abstract base class <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>. It

213

defines the basic interface to a stream. Note, however, that there is no

214

separation between reading and writing to streams; implementations are allowed

215

to raise <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal">UnsupportedOperation</code></a> if they do not support a given operation.

216

The <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a> ABC extends <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>. It deals with the reading

217

and writing of bytes to a stream. <a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal">FileIO</code></a> subclasses <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a>

218

to provide an interface to files in the machine’s file system.

219

The <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> ABC deals with buffering on a raw byte stream

220

(<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a>). Its subclasses, <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal">BufferedWriter</code></a>,

221

<a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal">BufferedReader</code></a>, and <a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal">BufferedRWPair</code></a> buffer streams that are

222

readable, writable, and both readable and writable. <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal">BufferedRandom</code></a>

223

provides a buffered interface to random access streams. Another

224

<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> subclass, <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal">BytesIO</code></a>, is a stream of in-memory

225

bytes.

226

The <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a> ABC, another subclass of <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>, deals with

227

streams whose bytes represent text, and handles encoding and decoding to and

228

from strings. <a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal">TextIOWrapper</code></a>, which extends it, is a buffered text

229

interface to a buffered raw stream (<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a>). Finally,

230

<a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal">StringIO</code></a> is an in-memory stream for text.

231

Argument names are not part of the specification, and only the arguments of

232

<a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> are intended to be used as keyword arguments.

233

The following table summarizes the ABCs provided by the <a class="reference internal" href="#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal">io</code></a> module:

234

235

236

237

238

239

240

</colgroup>

241

242

243

<th class="head">Inherits</th>

244

<th class="head">Stub Methods</th>

245

<th class="head">Mixin Methods and Properties</th>

246

</tr>

247

</thead>

248

249

<tr class="row-even"><td><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a></td>

250

251

<td><code class="docutils literal">fileno</code>, <code class="docutils literal">seek</code>,

252

and <code class="docutils literal">truncate</code></td>

253

<td><code class="docutils literal">close</code>, <code class="docutils literal">closed</code>, <code class="docutils literal">__enter__</code>,

254

<code class="docutils literal">__exit__</code>, <code class="docutils literal">flush</code>, <code class="docutils literal">isatty</code>, <code class="docutils literal">__iter__</code>,

255

<code class="docutils literal">__next__</code>, <code class="docutils literal">readable</code>, <code class="docutils literal">readline</code>,

256

<code class="docutils literal">readlines</code>, <code class="docutils literal">seekable</code>, <code class="docutils literal">tell</code>,

257

<code class="docutils literal">writable</code>, and <code class="docutils literal">writelines</code></td>

258

</tr>

259

<tr class="row-odd"><td><a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a></td>

260

<td><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a></td>

261

<td><code class="docutils literal">readinto</code> and

262

<code class="docutils literal">write</code></td>

263

<td>Inherited <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a> methods, <code class="docutils literal">read</code>,

264

and <code class="docutils literal">readall</code></td>

265

</tr>

266

<tr class="row-even"><td><a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a></td>

267

<td><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a></td>

268

<td><code class="docutils literal">detach</code>, <code class="docutils literal">read</code>,

269

<code class="docutils literal">read1</code>, and <code class="docutils literal">write</code></td>

270

271

</tr>

272

<tr class="row-odd"><td><a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a></td>

273

<td><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a></td>

274

<td><code class="docutils literal">detach</code>, <code class="docutils literal">read</code>,

275

<code class="docutils literal">readline</code>, and

276

<code class="docutils literal">write</code></td>

277

278

<code class="docutils literal">errors</code>, and <code class="docutils literal">newlines</code></td>

279

</tr>

280

</tbody>

281

</table>

282

283

<h3>16.2.3.1. I/O Base Classes<a class="headerlink" href="#i-o-base-classes" title="Permalink to this headline">¶</a></h3>

284

285

286

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

287

<dd>The abstract base class for all I/O classes, acting on streams of bytes.

288

There is no public constructor.

289

This class provides empty abstract implementations for many methods

290

that derived classes can override selectively; the default

291

implementations represent a file that cannot be read, written or

292

seeked.

293

Even though <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a> does not declare <code class="xref py py-meth docutils literal">read()</code>, <code class="xref py py-meth docutils literal">readinto()</code>,

294

or <code class="xref py py-meth docutils literal">write()</code> because their signatures will vary, implementations and

295

clients should consider those methods part of the interface. Also,

296

implementations may raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> (or <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal">UnsupportedOperation</code></a>)

297

when operations they do not support are called.

298

The basic type used for binary data read from or written to a file is

299

<a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a>. <a class="reference internal" href="functions.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal">bytearray</code></a>s are accepted too, and in some cases

300

(such as <code class="xref py py-meth docutils literal">readinto()</code>) required. Text I/O classes work with

301

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

302

Note that calling any method (even inquiries) on a closed stream is

303

undefined. Implementations may raise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a> in this case.

304

<a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a> (and its subclasses) supports the iterator protocol, meaning

305

that an <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a> object can be iterated over yielding the lines in a

306

stream. Lines are defined slightly differently depending on whether the

307

stream is a binary stream (yielding bytes), or a text stream (yielding

308

character strings). See <a class="reference internal" href="#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal">readline()</code></a> below.

309

<a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a> is also a context manager and therefore supports the

310

<a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal">with</code></a> statement. In this example, file is closed after the

311

<a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal">with</code></a> statement’s suite is finished—even if an exception occurs:

312

<div class="highlight-python3"><div class="highlight"><pre>with open('spam.txt', 'w') as file:

313

file.write('Spam and eggs!')

314

</pre></div>

315

</div>

316

<a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a> provides these data attributes and methods:

317

318

319

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

320

<dd>Flush and close this stream. This method has no effect if the file is

321

already closed. Once the file is closed, any operation on the file

322

(e.g. reading or writing) will raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a>.

323

As a convenience, it is allowed to call this method more than once;

324

only the first call, however, will have an effect.

325

</dd></dl>

326

327

328

329

<code class="descname">closed</code><a class="headerlink" href="#io.IOBase.closed" title="Permalink to this definition">¶</a></dt>

330

<dd><code class="docutils literal">True</code> if the stream is closed.

331

</dd></dl>

332

333

334

335

<code class="descname">fileno</code>()<a class="headerlink" href="#io.IOBase.fileno" title="Permalink to this definition">¶</a></dt>

336

<dd>Return the underlying file descriptor (an integer) of the stream if it

337

exists. An <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> is raised if the IO object does not use a file

338

descriptor.

339

</dd></dl>

340

341

342

343

<code class="descname">flush</code>()<a class="headerlink" href="#io.IOBase.flush" title="Permalink to this definition">¶</a></dt>

344

<dd>Flush the write buffers of the stream if applicable. This does nothing

345

for read-only and non-blocking streams.

346

</dd></dl>

347

348

349

350

<code class="descname">isatty</code>()<a class="headerlink" href="#io.IOBase.isatty" title="Permalink to this definition">¶</a></dt>

351

<dd>Return <code class="docutils literal">True</code> if the stream is interactive (i.e., connected to

352

a terminal/tty device).

353

</dd></dl>

354

355

356

357

<code class="descname">readable</code>()<a class="headerlink" href="#io.IOBase.readable" title="Permalink to this definition">¶</a></dt>

358

<dd>Return <code class="docutils literal">True</code> if the stream can be read from. If <code class="docutils literal">False</code>, <code class="xref py py-meth docutils literal">read()</code>

359

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

360

</dd></dl>

361

362

363

364

<code class="descname">readline</code>(size=-1)<a class="headerlink" href="#io.IOBase.readline" title="Permalink to this definition">¶</a></dt>

365

<dd>Read and return one line from the stream. If size is specified, at

366

most size bytes will be read.

367

The line terminator is always <code class="docutils literal">b'\n'</code> for binary files; for text files,

368

the newline argument to <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> can be used to select the line

369

terminator(s) recognized.

370

</dd></dl>

371

372

373

374

<code class="descname">readlines</code>(hint=-1)<a class="headerlink" href="#io.IOBase.readlines" title="Permalink to this definition">¶</a></dt>

375

<dd>Read and return a list of lines from the stream. hint can be specified

376

to control the number of lines read: no more lines will be read if the

377

total size (in bytes/characters) of all lines so far exceeds hint.

378

Note that it’s already possible to iterate on file objects using <code class="docutils literal">for

379

line in file: ...</code> without calling <code class="docutils literal">file.readlines()</code>.

380

</dd></dl>

381

382

383

384

<code class="descname">seek</code>(offset[, whence])<a class="headerlink" href="#io.IOBase.seek" title="Permalink to this definition">¶</a></dt>

385

<dd>Change the stream position to the given byte offset. offset is

386

interpreted relative to the position indicated by whence. The default

387

value for whence is <code class="xref py py-data docutils literal">SEEK_SET</code>. Values for whence are:

388

389

<li><code class="xref py py-data docutils literal">SEEK_SET</code> or <code class="docutils literal">0</code> – start of the stream (the default);

390

offset should be zero or positive</li>

391

<li><code class="xref py py-data docutils literal">SEEK_CUR</code> or <code class="docutils literal">1</code> – current stream position; offset may

392

be negative</li>

393

<li><code class="xref py py-data docutils literal">SEEK_END</code> or <code class="docutils literal">2</code> – end of the stream; offset is usually

394

negative</li>

395

</ul>

396

Return the new absolute position.

397

398

New in version 3.1: The <code class="docutils literal">SEEK_*</code> constants.

399

</div>

400

401

New in version 3.3: Some operating systems could support additional values, like

402

<code class="xref py py-data docutils literal">os.SEEK_HOLE</code> or <code class="xref py py-data docutils literal">os.SEEK_DATA</code>. The valid values

403

for a file could depend on it being open in text or binary mode.

404

</div>

405

</dd></dl>

406

407

408

409

<code class="descname">seekable</code>()<a class="headerlink" href="#io.IOBase.seekable" title="Permalink to this definition">¶</a></dt>

410

<dd>Return <code class="docutils literal">True</code> if the stream supports random access. If <code class="docutils literal">False</code>,

411

<a class="reference internal" href="#io.IOBase.seek" title="io.IOBase.seek"><code class="xref py py-meth docutils literal">seek()</code></a>, <a class="reference internal" href="#io.IOBase.tell" title="io.IOBase.tell"><code class="xref py py-meth docutils literal">tell()</code></a> and <a class="reference internal" href="#io.IOBase.truncate" title="io.IOBase.truncate"><code class="xref py py-meth docutils literal">truncate()</code></a> will raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a>.

412

</dd></dl>

413

414

415

416

417

<dd>Return the current stream position.

418

</dd></dl>

419

420

421

422

<code class="descname">truncate</code>(size=None)<a class="headerlink" href="#io.IOBase.truncate" title="Permalink to this definition">¶</a></dt>

423

<dd>Resize the stream to the given size in bytes (or the current position

424

if size is not specified). The current stream position isn’t changed.

425

This resizing can extend or reduce the current file size. In case of

426

extension, the contents of the new file area depend on the platform

427

(on most systems, additional bytes are zero-filled). The new file size

428

is returned.

429

</dd></dl>

430

431

432

Changed in version 3.5: Windows will now zero-fill files when extending.

433

</div>

434

435

436

<code class="descname">writable</code>()<a class="headerlink" href="#io.IOBase.writable" title="Permalink to this definition">¶</a></dt>

437

<dd>Return <code class="docutils literal">True</code> if the stream supports writing. If <code class="docutils literal">False</code>,

438

<code class="xref py py-meth docutils literal">write()</code> and <a class="reference internal" href="#io.IOBase.truncate" title="io.IOBase.truncate"><code class="xref py py-meth docutils literal">truncate()</code></a> will raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a>.

439

</dd></dl>

440

441

442

443

<code class="descname">writelines</code>(lines)<a class="headerlink" href="#io.IOBase.writelines" title="Permalink to this definition">¶</a></dt>

444

<dd>Write a list of lines to the stream. Line separators are not added, so it

445

is usual for each of the lines provided to have a line separator at the

446

end.

447

</dd></dl>

448

449

450

451

452

<dd>Prepare for object destruction. <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a> provides a default

453

implementation of this method that calls the instance’s

454

<a class="reference internal" href="#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal">close()</code></a> method.

455

</dd></dl>

456

457

</dd></dl>

458

459

460

461

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

462

<dd>Base class for raw binary I/O. It inherits <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>. There is no

463

public constructor.

464

Raw binary I/O typically provides low-level access to an underlying OS

465

device or API, and does not try to encapsulate it in high-level primitives

466

(this is left to Buffered I/O and Text I/O, described later in this page).

467

In addition to the attributes and methods from <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>,

468

469

470

471

472

<dd>Read up to size bytes from the object and return them. As a convenience,

473

if size is unspecified or -1, <a class="reference internal" href="#io.RawIOBase.readall" title="io.RawIOBase.readall"><code class="xref py py-meth docutils literal">readall()</code></a> is called. Otherwise,

474

only one system call is ever made. Fewer than size bytes may be

475

returned if the operating system call returns fewer than size bytes.

476

If 0 bytes are returned, and size was not 0, this indicates end of file.

477

If the object is in non-blocking mode and no bytes are available,

478

<code class="docutils literal">None</code> is returned.

479

</dd></dl>

480

481

482

483

<code class="descname">readall</code>()<a class="headerlink" href="#io.RawIOBase.readall" title="Permalink to this definition">¶</a></dt>

484

<dd>Read and return all the bytes from the stream until EOF, using multiple

485

calls to the stream if necessary.

486

</dd></dl>

487

488

489

490

<code class="descname">readinto</code>(b)<a class="headerlink" href="#io.RawIOBase.readinto" title="Permalink to this definition">¶</a></dt>

491

<dd>Read up to <code class="docutils literal">len(b)</code> bytes into <a class="reference internal" href="functions.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal">bytearray</code></a> b and return the

492

number of bytes read. If the object is in non-blocking mode and no bytes

493

are available, <code class="docutils literal">None</code> is returned.

494

</dd></dl>

495

496

497

498

<code class="descname">write</code>(b)<a class="headerlink" href="#io.RawIOBase.write" title="Permalink to this definition">¶</a></dt>

499

<dd>Write the given <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a> or <a class="reference internal" href="functions.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal">bytearray</code></a> object, b, to the

500

underlying raw stream and return the number of bytes written. This can

501

be less than <code class="docutils literal">len(b)</code>, depending on specifics of the underlying raw

502

stream, and especially if it is in non-blocking mode. <code class="docutils literal">None</code> is

503

returned if the raw stream is set not to block and no single byte could

504

be readily written to it.

505

</dd></dl>

506

507

</dd></dl>

508

509

510

511

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

512

<dd>Base class for binary streams that support some kind of buffering.

513

It inherits <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>. There is no public constructor.

514

The main difference with <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a> is that methods <a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal">read()</code></a>,

515

<a class="reference internal" href="#io.BufferedIOBase.readinto" title="io.BufferedIOBase.readinto"><code class="xref py py-meth docutils literal">readinto()</code></a> and <a class="reference internal" href="#io.BufferedIOBase.write" title="io.BufferedIOBase.write"><code class="xref py py-meth docutils literal">write()</code></a> will try (respectively) to read as much

516

input as requested or to consume all given output, at the expense of

517

making perhaps more than one system call.

518

In addition, those methods can raise <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal">BlockingIOError</code></a> if the

519

underlying raw stream is in non-blocking mode and cannot take or give

520

enough data; unlike their <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a> counterparts, they will

521

never return <code class="docutils literal">None</code>.

522

Besides, the <a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal">read()</code></a> method does not have a default

523

implementation that defers to <a class="reference internal" href="#io.BufferedIOBase.readinto" title="io.BufferedIOBase.readinto"><code class="xref py py-meth docutils literal">readinto()</code></a>.

524

A typical <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> implementation should not inherit from a

525

526

527

<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> provides or overrides these methods and attribute in

528

addition to those from <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>:

529

530

531

532

<dd>The underlying raw stream (a <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a> instance) that

533

534

535

</dd></dl>

536

537

538

539

<code class="descname">detach</code>()<a class="headerlink" href="#io.BufferedIOBase.detach" title="Permalink to this definition">¶</a></dt>

540

<dd>Separate the underlying raw stream from the buffer and return it.

541

After the raw stream has been detached, the buffer is in an unusable

542

state.

543

Some buffers, like <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal">BytesIO</code></a>, do not have the concept of a single

544

raw stream to return from this method. They raise

545

<a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal">UnsupportedOperation</code></a>.

546

547

New in version 3.1.

548

</div>

549

</dd></dl>

550

551

552

553

554

<dd>Read and return up to size bytes. If the argument is omitted, <code class="docutils literal">None</code>,

555

or negative, data is read and returned until EOF is reached. An empty

556

557

If the argument is positive, and the underlying raw stream is not

558

interactive, multiple raw reads may be issued to satisfy the byte count

559

(unless EOF is reached first). But for interactive raw streams, at most

560

one raw read will be issued, and a short result does not imply that EOF is

561

imminent.

562

A <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal">BlockingIOError</code></a> is raised if the underlying raw stream is in

563

non blocking-mode, and has no data available at the moment.

564

</dd></dl>

565

566

567

568

569

<dd>Read and return up to size bytes, with at most one call to the

570

underlying raw stream’s <a class="reference internal" href="#io.RawIOBase.read" title="io.RawIOBase.read"><code class="xref py py-meth docutils literal">read()</code></a> (or

571

<a class="reference internal" href="#io.RawIOBase.readinto" title="io.RawIOBase.readinto"><code class="xref py py-meth docutils literal">readinto()</code></a>) method. This can be useful if you are

572

implementing your own buffering on top of a <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a>

573

object.

574

</dd></dl>

575

576

577

578

<code class="descname">readinto</code>(b)<a class="headerlink" href="#io.BufferedIOBase.readinto" title="Permalink to this definition">¶</a></dt>

579

<dd>Read up to <code class="docutils literal">len(b)</code> bytes into bytearray b and return the number of

580

bytes read.

581

Like <a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal">read()</code></a>, multiple reads may be issued to the underlying raw

582

stream, unless the latter is interactive.

583

584

blocking-mode, and has no data available at the moment.

585

</dd></dl>

586

587

588

589

<code class="descname">readinto1</code>(b)<a class="headerlink" href="#io.BufferedIOBase.readinto1" title="Permalink to this definition">¶</a></dt>

590

<dd>Read up to <code class="docutils literal">len(b)</code> bytes into bytearray b, using at most one call to

591

the underlying raw stream’s <a class="reference internal" href="#io.RawIOBase.read" title="io.RawIOBase.read"><code class="xref py py-meth docutils literal">read()</code></a> (or

592

593

594

blocking-mode, and has no data available at the moment.

595

596

New in version 3.5.

597

</div>

598

</dd></dl>

599

600

601

602

<code class="descname">write</code>(b)<a class="headerlink" href="#io.BufferedIOBase.write" title="Permalink to this definition">¶</a></dt>

603

604

return the number of bytes written (never less than <code class="docutils literal">len(b)</code>, since if

605

the write fails an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal">OSError</code></a> will be raised). Depending on the

606

actual implementation, these bytes may be readily written to the

607

underlying stream, or held in a buffer for performance and latency

608

reasons.

609

When in non-blocking mode, a <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal">BlockingIOError</code></a> is raised if the

610

data needed to be written to the raw stream but it couldn’t accept

611

all the data without blocking.

612

</dd></dl>

613

614

</dd></dl>

615

616

</div>

617

618

619

620

621

class <code class="descclassname">io.</code><code class="descname">FileIO</code>(name, mode='r', closefd=True, opener=None)<a class="headerlink" href="#io.FileIO" title="Permalink to this definition">¶</a></dt>

622

<dd><a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal">FileIO</code></a> represents an OS-level file containing bytes data.

623

It implements the <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a> interface (and therefore the

624

<a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a> interface, too).

625

The name can be one of two things:

626

627

<li>a character string or <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a> object representing the path to the

628

file which will be opened. In this case closefd must be True (the default)

629

otherwise an error will be raised.</li>

630

<li>an integer representing the number of an existing OS-level file descriptor

631

to which the resulting <a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal">FileIO</code></a> object will give access. When the

632

FileIO object is closed this fd will be closed as well, unless closefd

633

is set to <code class="docutils literal">False</code>.</li>

634

</ul>

635

The mode can be <code class="docutils literal">'r'</code>, <code class="docutils literal">'w'</code>, <code class="docutils literal">'x'</code> or <code class="docutils literal">'a'</code> for reading

636

(default), writing, exclusive creation or appending. The file will be

637

created if it doesn’t exist when opened for writing or appending; it will be

638

truncated when opened for writing. <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal">FileExistsError</code></a> will be raised if

639

it already exists when opened for creating. Opening a file for creating

640

implies writing, so this mode behaves in a similar way to <code class="docutils literal">'w'</code>. Add a

641

<code class="docutils literal">'+'</code> to the mode to allow simultaneous reading and writing.

642

The <code class="xref py py-meth docutils literal">read()</code> (when called with a positive argument), <code class="xref py py-meth docutils literal">readinto()</code>

643

and <code class="xref py py-meth docutils literal">write()</code> methods on this class will only make one system call.

644

A custom opener can be used by passing a callable as opener. The underlying

645

file descriptor for the file object is then obtained by calling opener with

646

(name, flags). opener must return an open file descriptor (passing

647

<a class="reference internal" href="os.html#os.open" title="os.open"><code class="xref py py-mod docutils literal">os.open</code></a> as opener results in functionality similar to passing

648

<code class="docutils literal">None</code>).

649

The newly created file is <a class="reference internal" href="os.html#fd-inheritance">non-inheritable</a>.

650

See the <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> built-in function for examples on using the opener

651

parameter.

652

653

Changed in version 3.3: The opener parameter was added.

654

The <code class="docutils literal">'x'</code> mode was added.

655

</div>

656

657

Changed in version 3.4: The file is now non-inheritable.

658

</div>

659

660

<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a>, <a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal">FileIO</code></a> provides the following data

661

attributes:

662

663

664

665

<dd>The mode as given in the constructor.

666

</dd></dl>

667

668

669

670

671

<dd>The file name. This is the file descriptor of the file when no name is

672

given in the constructor.

673

</dd></dl>

674

675

</dd></dl>

676

677

</div>

678

679

<h3>16.2.3.3. Buffered Streams<a class="headerlink" href="#buffered-streams" title="Permalink to this headline">¶</a></h3>

680

Buffered I/O streams provide a higher-level interface to an I/O device

681

than raw I/O does.

682

683

684

class <code class="descclassname">io.</code><code class="descname">BytesIO</code>([initial_bytes])<a class="headerlink" href="#io.BytesIO" title="Permalink to this definition">¶</a></dt>

685

<dd>A stream implementation using an in-memory bytes buffer. It inherits

686

687

<a class="reference internal" href="#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal">close()</code></a> method is called.

688

The argument initial_bytes contains optional initial <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a> data.

689

<a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal">BytesIO</code></a> provides or overrides these methods in addition to those

690

from <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> and <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>:

691

692

693

<code class="descname">getbuffer</code>()<a class="headerlink" href="#io.BytesIO.getbuffer" title="Permalink to this definition">¶</a></dt>

694

<dd>Return a readable and writable view over the contents of the buffer

695

without copying them. Also, mutating the view will transparently

696

update the contents of the buffer:

697

<div class="highlight-python3"><div class="highlight"><pre>>>> b = io.BytesIO(b"abcdef")

698

>>> view = b.getbuffer()

699

>>> view[2:4] = b"56"

700

>>> b.getvalue()

701

b'ab56ef'

702

</pre></div>

703

</div>

704

705

Note

706

As long as the view exists, the <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal">BytesIO</code></a> object cannot be

707

resized or closed.

708

</div>

709

710

New in version 3.2.

711

</div>

712

</dd></dl>

713

714

715

716

<code class="descname">getvalue</code>()<a class="headerlink" href="#io.BytesIO.getvalue" title="Permalink to this definition">¶</a></dt>

717

<dd>Return <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a> containing the entire contents of the buffer.

718

</dd></dl>

719

720

721

722

723

<dd>In <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal">BytesIO</code></a>, this is the same as <code class="xref py py-meth docutils literal">read()</code>.

724

</dd></dl>

725

726

727

728

<code class="descname">readinto1</code>()<a class="headerlink" href="#io.BytesIO.readinto1" title="Permalink to this definition">¶</a></dt>

729

730

731

New in version 3.5.

732

</div>

733

</dd></dl>

734

735

</dd></dl>

736

737

738

739

class <code class="descclassname">io.</code><code class="descname">BufferedReader</code>(raw, buffer_size=DEFAULT_BUFFER_SIZE)<a class="headerlink" href="#io.BufferedReader" title="Permalink to this definition">¶</a></dt>

740

<dd>A buffer providing higher-level access to a readable, sequential

741

<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a> object. It inherits <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a>.

742

When reading data from this object, a larger amount of data may be

743

requested from the underlying raw stream, and kept in an internal buffer.

744

The buffered data can then be returned directly on subsequent reads.

745

The constructor creates a <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal">BufferedReader</code></a> for the given readable

746

raw stream and buffer_size. If buffer_size is omitted,

747

<a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal">DEFAULT_BUFFER_SIZE</code></a> is used.

748

<a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal">BufferedReader</code></a> provides or overrides these methods in addition to

749

those from <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> and <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>:

750

751

752

753

<dd>Return bytes from the stream without advancing the position. At most one

754

single read on the raw stream is done to satisfy the call. The number of

755

bytes returned may be less or more than requested.

756

</dd></dl>

757

758

759

760

761

<dd>Read and return size bytes, or if size is not given or negative, until

762

EOF or if the read call would block in non-blocking mode.

763

</dd></dl>

764

765

766

767

768

<dd>Read and return up to size bytes with only one call on the raw stream.

769

If at least one byte is buffered, only buffered bytes are returned.

770

Otherwise, one raw stream read call is made.

771

</dd></dl>

772

773

</dd></dl>

774

775

776

777

class <code class="descclassname">io.</code><code class="descname">BufferedWriter</code>(raw, buffer_size=DEFAULT_BUFFER_SIZE)<a class="headerlink" href="#io.BufferedWriter" title="Permalink to this definition">¶</a></dt>

778

<dd>A buffer providing higher-level access to a writeable, sequential

779

<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a> object. It inherits <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a>.

780

When writing to this object, data is normally placed into an internal

781

buffer. The buffer will be written out to the underlying <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a>

782

object under various conditions, including:

783

784

<li>when the buffer gets too small for all pending data;</li>

785

<li>when <a class="reference internal" href="#io.BufferedWriter.flush" title="io.BufferedWriter.flush"><code class="xref py py-meth docutils literal">flush()</code></a> is called;</li>

786

<li>when a <code class="xref py py-meth docutils literal">seek()</code> is requested (for <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal">BufferedRandom</code></a> objects);</li>

787

<li>when the <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal">BufferedWriter</code></a> object is closed or destroyed.</li>

788

</ul>

789

The constructor creates a <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal">BufferedWriter</code></a> for the given writeable

790

raw stream. If the buffer_size is not given, it defaults to

791

<a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal">DEFAULT_BUFFER_SIZE</code></a>.

792

<a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal">BufferedWriter</code></a> provides or overrides these methods in addition to

793

794

795

796

<code class="descname">flush</code>()<a class="headerlink" href="#io.BufferedWriter.flush" title="Permalink to this definition">¶</a></dt>

797

<dd>Force bytes held in the buffer into the raw stream. A

798

<a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal">BlockingIOError</code></a> should be raised if the raw stream blocks.

799

</dd></dl>

800

801

802

803

<code class="descname">write</code>(b)<a class="headerlink" href="#io.BufferedWriter.write" title="Permalink to this definition">¶</a></dt>

804

<dd>Write the <a class="reference internal" href="functions.html#bytes" title="bytes"><code class="xref py py-class docutils literal">bytes</code></a> or <a class="reference internal" href="functions.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal">bytearray</code></a> object, b and return the

805

number of bytes written. When in non-blocking mode, a

806

807

the raw stream blocks.

808

</dd></dl>

809

810

</dd></dl>

811

812

813

814

class <code class="descclassname">io.</code><code class="descname">BufferedRandom</code>(raw, buffer_size=DEFAULT_BUFFER_SIZE)<a class="headerlink" href="#io.BufferedRandom" title="Permalink to this definition">¶</a></dt>

815

<dd>A buffered interface to random access streams. It inherits

816

<a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal">BufferedReader</code></a> and <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal">BufferedWriter</code></a>, and further supports

817

<code class="xref py py-meth docutils literal">seek()</code> and <code class="xref py py-meth docutils literal">tell()</code> functionality.

818

The constructor creates a reader and writer for a seekable raw stream, given

819

in the first argument. If the buffer_size is omitted it defaults to

820

<a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal">DEFAULT_BUFFER_SIZE</code></a>.

821

<a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal">BufferedRandom</code></a> is capable of anything <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal">BufferedReader</code></a> or

822

<a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal">BufferedWriter</code></a> can do.

823

</dd></dl>

824

825

826

827

class <code class="descclassname">io.</code><code class="descname">BufferedRWPair</code>(reader, writer, buffer_size=DEFAULT_BUFFER_SIZE)<a class="headerlink" href="#io.BufferedRWPair" title="Permalink to this definition">¶</a></dt>

828

<dd>A buffered I/O object combining two unidirectional <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a>

829

objects – one readable, the other writeable – into a single bidirectional

830

endpoint. It inherits <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a>.

831

reader and writer are <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal">RawIOBase</code></a> objects that are readable and

832

writeable respectively. If the buffer_size is omitted it defaults to

833

<a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal">DEFAULT_BUFFER_SIZE</code></a>.

834

<a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal">BufferedRWPair</code></a> implements all of <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a>‘s methods

835

except for <a class="reference internal" href="#io.BufferedIOBase.detach" title="io.BufferedIOBase.detach"><code class="xref py py-meth docutils literal">detach()</code></a>, which raises

836

837

838

Warning

839

<a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal">BufferedRWPair</code></a> does not attempt to synchronize accesses to

840

its underlying raw streams. You should not pass it the same object

841

as reader and writer; use <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal">BufferedRandom</code></a> instead.

842

</div>

843

</dd></dl>

844

845

</div>

846

847

848

849

850

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

851

<dd>Base class for text streams. This class provides a character and line based

852

interface to stream I/O. There is no <code class="xref py py-meth docutils literal">readinto()</code> method because

853

Python’s character strings are immutable. It inherits <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>.

854

There is no public constructor.

855

<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a> provides or overrides these data attributes and

856

methods in addition to those from <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal">IOBase</code></a>:

857

858

859

<code class="descname">encoding</code><a class="headerlink" href="#io.TextIOBase.encoding" title="Permalink to this definition">¶</a></dt>

860

<dd>The name of the encoding used to decode the stream’s bytes into

861

strings, and to encode strings into bytes.

862

</dd></dl>

863

864

865

866

<code class="descname">errors</code><a class="headerlink" href="#io.TextIOBase.errors" title="Permalink to this definition">¶</a></dt>

867

<dd>The error setting of the decoder or encoder.

868

</dd></dl>

869

870

871

872

<code class="descname">newlines</code><a class="headerlink" href="#io.TextIOBase.newlines" title="Permalink to this definition">¶</a></dt>

873

<dd>A string, a tuple of strings, or <code class="docutils literal">None</code>, indicating the newlines

874

translated so far. Depending on the implementation and the initial

875

constructor flags, this may not be available.

876

</dd></dl>

877

878

879

880

<code class="descname">buffer</code><a class="headerlink" href="#io.TextIOBase.buffer" title="Permalink to this definition">¶</a></dt>

881

<dd>The underlying binary buffer (a <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> instance) that

882

<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a> deals with. This is not part of the

883

884

</dd></dl>

885

886

887

888

<code class="descname">detach</code>()<a class="headerlink" href="#io.TextIOBase.detach" title="Permalink to this definition">¶</a></dt>

889

<dd>Separate the underlying binary buffer from the <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a> and

890

return it.

891

After the underlying buffer has been detached, the <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a> is

892

in an unusable state.

893

Some <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a> implementations, like <a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal">StringIO</code></a>, may not

894

have the concept of an underlying buffer and calling this method will

895

raise <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal">UnsupportedOperation</code></a>.

896

897

New in version 3.1.

898

</div>

899

</dd></dl>

900

901

902

903

904

<dd>Read and return at most size characters from the stream as a single

905

<a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal">str</code></a>. If size is negative or <code class="docutils literal">None</code>, reads until EOF.

906

</dd></dl>

907

908

909

910

<code class="descname">readline</code>(size=-1)<a class="headerlink" href="#io.TextIOBase.readline" title="Permalink to this definition">¶</a></dt>

911

<dd>Read until newline or EOF and return a single <code class="docutils literal">str</code>. If the stream is

912

already at EOF, an empty string is returned.

913

If size is specified, at most size characters will be read.

914

</dd></dl>

915

916

917

918

<code class="descname">seek</code>(offset[, whence])<a class="headerlink" href="#io.TextIOBase.seek" title="Permalink to this definition">¶</a></dt>

919

<dd>Change the stream position to the given offset. Behaviour depends on

920

the whence parameter. The default value for whence is

921

<code class="xref py py-data docutils literal">SEEK_SET</code>.

922

923

<li><code class="xref py py-data docutils literal">SEEK_SET</code> or <code class="docutils literal">0</code>: seek from the start of the stream

924

(the default); offset must either be a number returned by

925

<a class="reference internal" href="#io.TextIOBase.tell" title="io.TextIOBase.tell"><code class="xref py py-meth docutils literal">TextIOBase.tell()</code></a>, or zero. Any other offset value

926

produces undefined behaviour.</li>

927

<li><code class="xref py py-data docutils literal">SEEK_CUR</code> or <code class="docutils literal">1</code>: “seek” to the current position;

928

offset must be zero, which is a no-operation (all other values

929

are unsupported).</li>

930

<li><code class="xref py py-data docutils literal">SEEK_END</code> or <code class="docutils literal">2</code>: seek to the end of the stream;

931

offset must be zero (all other values are unsupported).</li>

932

</ul>

933

Return the new absolute position as an opaque number.

934

935

New in version 3.1: The <code class="docutils literal">SEEK_*</code> constants.

936

</div>

937

</dd></dl>

938

939

940

941

942

<dd>Return the current stream position as an opaque number. The number

943

does not usually represent a number of bytes in the underlying

944

binary storage.

945

</dd></dl>

946

947

948

949

<code class="descname">write</code>(s)<a class="headerlink" href="#io.TextIOBase.write" title="Permalink to this definition">¶</a></dt>

950

<dd>Write the string s to the stream and return the number of characters

951

written.

952

</dd></dl>

953

954

</dd></dl>

955

956

957

958

class <code class="descclassname">io.</code><code class="descname">TextIOWrapper</code>(buffer, encoding=None, errors=None, newline=None, line_buffering=False, write_through=False)<a class="headerlink" href="#io.TextIOWrapper" title="Permalink to this definition">¶</a></dt>

959

<dd>A buffered text stream over a <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal">BufferedIOBase</code></a> binary stream.

960

It inherits <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a>.

961

encoding gives the name of the encoding that the stream will be decoded or

962

encoded with. It defaults to

963

<a class="reference internal" href="locale.html#locale.getpreferredencoding" title="locale.getpreferredencoding"><code class="xref py py-func docutils literal">locale.getpreferredencoding(False)</code></a>.

964

errors is an optional string that specifies how encoding and decoding

965

errors are to be handled. Pass <code class="docutils literal">'strict'</code> to raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal">ValueError</code></a>

966

exception if there is an encoding error (the default of <code class="docutils literal">None</code> has the same

967

effect), or pass <code class="docutils literal">'ignore'</code> to ignore errors. (Note that ignoring encoding

968

errors can lead to data loss.) <code class="docutils literal">'replace'</code> causes a replacement marker

969

(such as <code class="docutils literal">'?'</code>) to be inserted where there is malformed data.

970

<code class="docutils literal">'backslashreplace'</code> causes malformed data to be replaced by a

971

backslashed escape sequence. When writing, <code class="docutils literal">'xmlcharrefreplace'</code>

972

(replace with the appropriate XML character reference) or <code class="docutils literal">'namereplace'</code>

973

(replace with <code class="docutils literal">\N{...}</code> escape sequences) can be used. Any other error

974

handling name that has been registered with

975

<a class="reference internal" href="codecs.html#codecs.register_error" title="codecs.register_error"><code class="xref py py-func docutils literal">codecs.register_error()</code></a> is also valid.

976

newline controls how line endings are handled. It can be <code class="docutils literal">None</code>,

977

<code class="docutils literal">''</code>, <code class="docutils literal">'\n'</code>, <code class="docutils literal">'\r'</code>, and <code class="docutils literal">'\r\n'</code>. It works as follows:

978

979

<li>When reading input from the stream, if newline is <code class="docutils literal">None</code>,

980

<a class="reference internal" href="../glossary.html#term-universal-newlines">universal newlines</a> mode is enabled. Lines in the input can end in

981

<code class="docutils literal">'\n'</code>, <code class="docutils literal">'\r'</code>, or <code class="docutils literal">'\r\n'</code>, and these are translated into <code class="docutils literal">'\n'</code>

982

before being returned to the caller. If it is <code class="docutils literal">''</code>, universal newlines

983

mode is enabled, but line endings are returned to the caller untranslated.

984

If it has any of the other legal values, input lines are only terminated

985

by the given string, and the line ending is returned to the caller

986

untranslated.</li>

987

<li>When writing output to the stream, if newline is <code class="docutils literal">None</code>, any <code class="docutils literal">'\n'</code>

988

characters written are translated to the system default line separator,

989

<a class="reference internal" href="os.html#os.linesep" title="os.linesep"><code class="xref py py-data docutils literal">os.linesep</code></a>. If newline is <code class="docutils literal">''</code> or <code class="docutils literal">'\n'</code>, no translation

990

takes place. If newline is any of the other legal values, any <code class="docutils literal">'\n'</code>

991

characters written are translated to the given string.</li>

992

</ul>

993

If line_buffering is <code class="docutils literal">True</code>, <code class="xref py py-meth docutils literal">flush()</code> is implied when a call to

994

write contains a newline character.

995

If write_through is <code class="docutils literal">True</code>, calls to <code class="xref py py-meth docutils literal">write()</code> are guaranteed

996

not to be buffered: any data written on the <a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal">TextIOWrapper</code></a>

997

object is immediately handled to its underlying binary buffer.

998

999

Changed in version 3.3: The write_through argument has been added.

1000

</div>

1001

1002

Changed in version 3.3: The default encoding is now <code class="docutils literal">locale.getpreferredencoding(False)</code>

1003

instead of <code class="docutils literal">locale.getpreferredencoding()</code>. Don’t change temporary the

1004

locale encoding using <a class="reference internal" href="locale.html#locale.setlocale" title="locale.setlocale"><code class="xref py py-func docutils literal">locale.setlocale()</code></a>, use the current locale

1005

encoding instead of the user preferred encoding.

1006

</div>

1007

<a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal">TextIOWrapper</code></a> provides one attribute in addition to those of

1008

<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a> and its parents:

1009

1010

1011

<code class="descname">line_buffering</code><a class="headerlink" href="#io.TextIOWrapper.line_buffering" title="Permalink to this definition">¶</a></dt>

1012

<dd>Whether line buffering is enabled.

1013

</dd></dl>

1014

1015

</dd></dl>

1016

1017

1018

1019

class <code class="descclassname">io.</code><code class="descname">StringIO</code>(initial_value='', newline='\n')<a class="headerlink" href="#io.StringIO" title="Permalink to this definition">¶</a></dt>

1020

<dd>An in-memory stream for text I/O. The text buffer is discarded when the

1021

<a class="reference internal" href="#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal">close()</code></a> method is called.

1022

The initial value of the buffer can be set by providing initial_value.

1023

If newline translation is enabled, newlines will be encoded as if by

1024

<a class="reference internal" href="#io.TextIOBase.write" title="io.TextIOBase.write"><code class="xref py py-meth docutils literal">write()</code></a>. The stream is positioned at the start of

1025

the buffer.

1026

The newline argument works like that of <a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal">TextIOWrapper</code></a>.

1027

The default is to consider only <code class="docutils literal">\n</code> characters as ends of lines and

1028

to do no newline translation. If newline is set to <code class="docutils literal">None</code>,

1029

newlines are written as <code class="docutils literal">\n</code> on all platforms, but universal

1030

newline decoding is still performed when reading.

1031

<a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal">StringIO</code></a> provides this method in addition to those from

1032

<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal">TextIOBase</code></a> and its parents:

1033

1034

1035

<code class="descname">getvalue</code>()<a class="headerlink" href="#io.StringIO.getvalue" title="Permalink to this definition">¶</a></dt>

1036

<dd>Return a <code class="docutils literal">str</code> containing the entire contents of the buffer.

1037

Newlines are decoded as if by <a class="reference internal" href="#io.TextIOBase.read" title="io.TextIOBase.read"><code class="xref py py-meth docutils literal">read()</code></a>, although

1038

the stream position is not changed.

1039

</dd></dl>

1040

1041

Example usage:

1042

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

1043

1044

output = io.StringIO()

1045

output.write('First line.\n')

1046

print('Second line.', file=output)

1047

1048

# Retrieve file contents -- this will be

1049

# 'First line.\nSecond line.\n'

1050

contents = output.getvalue()

1051

1052

# Close object and discard memory buffer --

1053

# .getvalue() will now raise an exception.

1054

output.close()

1055

</pre></div>

1056

</div>

1057

</dd></dl>

1058

1059

1060

1061

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

1062

<dd>A helper codec that decodes newlines for <a class="reference internal" href="../glossary.html#term-universal-newlines">universal newlines</a> mode.

1063

It inherits <a class="reference internal" href="codecs.html#codecs.IncrementalDecoder" title="codecs.IncrementalDecoder"><code class="xref py py-class docutils literal">codecs.IncrementalDecoder</code></a>.

1064

</dd></dl>

1065

1066

</div>

1067

</div>

1068

1069

<h2>16.2.4. Performance<a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h2>

1070

This section discusses the performance of the provided concrete I/O

1071

implementations.

1072

1073

<h3>16.2.4.1. Binary I/O<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>

1074

By reading and writing only large chunks of data even when the user asks for a

1075

single byte, buffered I/O hides any inefficiency in calling and executing the

1076

operating system’s unbuffered I/O routines. The gain depends on the OS and the

1077

kind of I/O which is performed. For example, on some modern OSes such as Linux,

1078

unbuffered disk I/O can be as fast as buffered I/O. The bottom line, however,

1079

is that buffered I/O offers predictable performance regardless of the platform

1080

and the backing device. Therefore, it is almost always preferable to use

1081

buffered I/O rather than unbuffered I/O for binary data.

1082

</div>

1083

1084

1085

Text I/O over a binary storage (such as a file) is significantly slower than

1086

binary I/O over the same storage, because it requires conversions between

1087

unicode and binary data using a character codec. This can become noticeable

1088

handling huge amounts of text data like large log files. Also,

1089

<code class="xref py py-meth docutils literal">TextIOWrapper.tell()</code> and <code class="xref py py-meth docutils literal">TextIOWrapper.seek()</code> are both quite slow

1090

due to the reconstruction algorithm used.

1091

1092

exhibit similar speed to <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal">BytesIO</code></a>.

1093

</div>

1094

1095

<h3>16.2.4.3. Multi-threading<a class="headerlink" href="#multi-threading" title="Permalink to this headline">¶</a></h3>

1096

<a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal">FileIO</code></a> objects are thread-safe to the extent that the operating system

1097

calls (such as <code class="docutils literal">read(2)</code> under Unix) they wrap are thread-safe too.

1098

Binary buffered objects (instances of <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal">BufferedReader</code></a>,

1099

<a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal">BufferedWriter</code></a>, <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal">BufferedRandom</code></a> and <a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal">BufferedRWPair</code></a>)

1100

protect their internal structures using a lock; it is therefore safe to call

1101

them from multiple threads at once.

1102

1103

</div>

1104

1105

<h3>16.2.4.4. Reentrancy<a class="headerlink" href="#reentrancy" title="Permalink to this headline">¶</a></h3>

1106

1107

1108

are not reentrant. While reentrant calls will not happen in normal situations,

1109

they can arise from doing I/O in a <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> handler. If a thread tries to

1110

re-enter a buffered object which it is already accessing, a <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal">RuntimeError</code></a>

1111

is raised. Note this doesn’t prohibit a different thread from entering the

1112

buffered object.

1113

The above implicitly extends to text files, since the <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal">open()</code></a> function

1114

will wrap a buffered object inside a <a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal">TextIOWrapper</code></a>. This includes

1115

standard streams and therefore affects the built-in function <a class="reference internal" href="functions.html#print" title="print"><code class="xref py py-func docutils literal">print()</code></a> as

1116

well.

1117

</div>

1118

</div>

1119

</div>

1120

1121

1122

</div>

1123

</div>

1124

</div>

1125

1126

1127

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

1128

<ul>

1129

<li><a class="reference internal" href="#">16.2. <code class="docutils literal">io</code> — Core tools for working with streams</a><ul>

1130

<li><a class="reference internal" href="#overview">16.2.1. Overview</a><ul>

1131

1132

<li><a class="reference internal" href="#binary-i-o">16.2.1.2. Binary I/O</a></li>

1133

1134

</ul>

1135

</li>

1136

<li><a class="reference internal" href="#high-level-module-interface">16.2.2. High-level Module Interface</a><ul>

1137

<li><a class="reference internal" href="#in-memory-streams">16.2.2.1. In-memory streams</a></li>

1138

</ul>

1139

</li>

1140

<li><a class="reference internal" href="#class-hierarchy">16.2.3. Class hierarchy</a><ul>

1141

<li><a class="reference internal" href="#i-o-base-classes">16.2.3.1. I/O Base Classes</a></li>

1142

1143

<li><a class="reference internal" href="#buffered-streams">16.2.3.3. Buffered Streams</a></li>

1144

1145

</ul>

1146

</li>

1147

<li><a class="reference internal" href="#performance">16.2.4. Performance</a><ul>

1148

<li><a class="reference internal" href="#id2">16.2.4.1. Binary I/O</a></li>

1149

1150

<li><a class="reference internal" href="#multi-threading">16.2.4.3. Multi-threading</a></li>

1151

<li><a class="reference internal" href="#reentrancy">16.2.4.4. Reentrancy</a></li>

1152

</ul>

1153

</li>

1154

</ul>

1155

</li>

1156

</ul>

1157

1158

<h4>Previous topic</h4>

1159

<a href="os.html"

1160

title="previous chapter">16.1. <code class="docutils literal">os</code> — Miscellaneous operating system interfaces</a>

1161

<h4>Next topic</h4>

1162

<a href="time.html"

1163

title="next chapter">16.3. <code class="docutils literal">time</code> — Time access and conversions</a>

1164

1165

1166

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

1167

<li><a href="../_sources/library/io.txt"

1168

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

1169

</ul>

1170

1171

1172

<h3>Quick search</h3>

1173

1174

1175

1176

1177

1178

</form>

1179

1180

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

1181

1182

</div>

1183

1184

</div>

1185

</div>

1186

1187

</div>

1188

1189

<h3>Navigation</h3>

1190

<ul>

1191

1192

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

1193

>index</a></li>

1194

1195

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

1196

>modules</a> |</li>

1197

1198

<a href="time.html" title="16.3. time — Time access and conversions"

1199

>next</a> |</li>

1200

1201

<a href="os.html" title="16.1. os — Miscellaneous operating system interfaces"

1202

>previous</a> |</li>

1203

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

1204

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

1205

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

1206

<li>

1207

3.5.1

1208

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

1209

</li>

1210

1211

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

1212

<li class="nav-item nav-item-2"><a href="allos.html" >16. Generic Operating System Services</a> »</li>

1213

</ul>

1214

</div>

1215

1216

1217

1218

The Python Software Foundation is a non-profit corporation.

1219

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

1220

1221

Last updated on Jan 22, 2016.

1222

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

1223

1224

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

1225

</div>

1226

1227

</body>

1228

</html>

b'\\ No newline at end of file'

Older »