1304 lines
122 KiB
HTML
1304 lines
122 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta charset="utf-8" />
|
||
<title>io — Core tools for working with streams — Python 3.7.4 documentation</title>
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script type="text/javascript" src="../_static/jquery.js"></script>
|
||
<script type="text/javascript" src="../_static/underscore.js"></script>
|
||
<script type="text/javascript" src="../_static/doctools.js"></script>
|
||
<script type="text/javascript" src="../_static/language_data.js"></script>
|
||
|
||
<script type="text/javascript" src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="Search within Python 3.7.4 documentation"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="About these documents" href="../about.html" />
|
||
<link rel="index" title="Index" href="../genindex.html" />
|
||
<link rel="search" title="Search" href="../search.html" />
|
||
<link rel="copyright" title="Copyright" href="../copyright.html" />
|
||
<link rel="next" title="time — Time access and conversions" href="time.html" />
|
||
<link rel="prev" title="os — Miscellaneous operating system interfaces" href="os.html" />
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.png" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/io.html" />
|
||
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/switchers.js"></script>
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
|
||
|
||
</head><body>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
accesskey="I">index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="time.html" title="time — Time access and conversions"
|
||
accesskey="N">next</a> |</li>
|
||
<li class="right" >
|
||
<a href="os.html" title="os — Miscellaneous operating system interfaces"
|
||
accesskey="P">previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">Generic Operating System Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<div class="section" id="module-io">
|
||
<span id="io-core-tools-for-working-with-streams"></span><h1><a class="reference internal" href="#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code></a> — Core tools for working with streams<a class="headerlink" href="#module-io" title="Permalink to this headline">¶</a></h1>
|
||
<p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.7/Lib/io.py">Lib/io.py</a></p>
|
||
<hr class="docutils" />
|
||
<div class="section" id="overview">
|
||
<span id="io-overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
|
||
<p id="index-0">The <a class="reference internal" href="#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code></a> module provides Python’s main facilities for dealing with various
|
||
types of I/O. There are three main types of I/O: <em>text I/O</em>, <em>binary I/O</em>
|
||
and <em>raw I/O</em>. 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"><span class="xref std std-term">file object</span></a>. Other common terms are <em>stream</em>
|
||
and <em>file-like object</em>.</p>
|
||
<p>Independent 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).</p>
|
||
<p>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 notranslate"><span class="pre">str</span></code></a> object to the <code class="docutils literal notranslate"><span class="pre">write()</span></code> method of a binary stream
|
||
will raise a <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a>. So will giving a <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object to the
|
||
<code class="docutils literal notranslate"><span class="pre">write()</span></code> method of a text stream.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>Operations that used to raise <a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code></a> now raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>, since
|
||
<a class="reference internal" href="exceptions.html#IOError" title="IOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></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 notranslate"><span class="pre">OSError</span></code></a>.</p>
|
||
</div>
|
||
<div class="section" id="text-i-o">
|
||
<h3>Text I/O<a class="headerlink" href="#text-i-o" title="Permalink to this headline">¶</a></h3>
|
||
<p>Text I/O expects and produces <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> objects. This means that whenever
|
||
the backing store is natively made of bytes (such as in the case of a file),
|
||
encoding and decoding of data is made transparently as well as optional
|
||
translation of platform-specific newline characters.</p>
|
||
<p>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 notranslate"><span class="pre">open()</span></code></a>, optionally
|
||
specifying an encoding:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile.txt"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"utf-8"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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 notranslate"><span class="pre">StringIO</span></code></a> objects:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">StringIO</span><span class="p">(</span><span class="s2">"some initial text data"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The text stream API is described in detail in the documentation of
|
||
<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a>.</p>
|
||
</div>
|
||
<div class="section" id="binary-i-o">
|
||
<h3>Binary I/O<a class="headerlink" href="#binary-i-o" title="Permalink to this headline">¶</a></h3>
|
||
<p>Binary I/O (also called <em>buffered I/O</em>) expects
|
||
<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a> and produces <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>
|
||
objects. No encoding, decoding, or newline translation is performed. This
|
||
category of streams can be used for all kinds of non-text data, and also when
|
||
manual control over the handling of text data is desired.</p>
|
||
<p>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 notranslate"><span class="pre">open()</span></code></a> with <code class="docutils literal notranslate"><span class="pre">'b'</span></code> in
|
||
the mode string:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile.jpg"</span><span class="p">,</span> <span class="s2">"rb"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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 notranslate"><span class="pre">BytesIO</span></code></a> objects:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">BytesIO</span><span class="p">(</span><span class="sa">b</span><span class="s2">"some initial binary data: </span><span class="se">\x00\x01</span><span class="s2">"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>The binary stream API is described in detail in the docs of
|
||
<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>.</p>
|
||
<p>Other library modules may provide additional ways to create text or binary
|
||
streams. See <a class="reference internal" href="socket.html#socket.socket.makefile" title="socket.socket.makefile"><code class="xref py py-meth docutils literal notranslate"><span class="pre">socket.socket.makefile()</span></code></a> for example.</p>
|
||
</div>
|
||
<div class="section" id="raw-i-o">
|
||
<h3>Raw I/O<a class="headerlink" href="#raw-i-o" title="Permalink to this headline">¶</a></h3>
|
||
<p>Raw I/O (also called <em>unbuffered I/O</em>) is generally used as a low-level
|
||
building-block for binary and text streams; it is rarely useful to directly
|
||
manipulate a raw stream from user code. Nevertheless, you can create a raw
|
||
stream by opening a file in binary mode with buffering disabled:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile.jpg"</span><span class="p">,</span> <span class="s2">"rb"</span><span class="p">,</span> <span class="n">buffering</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>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 notranslate"><span class="pre">RawIOBase</span></code></a>.</p>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="high-level-module-interface">
|
||
<h2>High-level Module Interface<a class="headerlink" href="#high-level-module-interface" title="Permalink to this headline">¶</a></h2>
|
||
<dl class="data">
|
||
<dt id="io.DEFAULT_BUFFER_SIZE">
|
||
<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>
|
||
<dd><p>An int containing the default buffer size used by the module’s buffered I/O
|
||
classes. <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> uses the file’s blksize (as obtained by
|
||
<a class="reference internal" href="os.html#os.stat" title="os.stat"><code class="xref py py-func docutils literal notranslate"><span class="pre">os.stat()</span></code></a>) if possible.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="io.open">
|
||
<code class="descclassname">io.</code><code class="descname">open</code><span class="sig-paren">(</span><em>file</em>, <em>mode='r'</em>, <em>buffering=-1</em>, <em>encoding=None</em>, <em>errors=None</em>, <em>newline=None</em>, <em>closefd=True</em>, <em>opener=None</em><span class="sig-paren">)</span><a class="headerlink" href="#io.open" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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 notranslate"><span class="pre">open()</span></code></a> function.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="io.BlockingIOError">
|
||
<em class="property">exception </em><code class="descclassname">io.</code><code class="descname">BlockingIOError</code><a class="headerlink" href="#io.BlockingIOError" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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 notranslate"><span class="pre">BlockingIOError</span></code></a>
|
||
exception.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="io.UnsupportedOperation">
|
||
<em class="property">exception </em><code class="descclassname">io.</code><code class="descname">UnsupportedOperation</code><a class="headerlink" href="#io.UnsupportedOperation" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An exception inheriting <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> and <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> that is raised
|
||
when an unsupported operation is called on a stream.</p>
|
||
</dd></dl>
|
||
|
||
<div class="section" id="in-memory-streams">
|
||
<h3>In-memory streams<a class="headerlink" href="#in-memory-streams" title="Permalink to this headline">¶</a></h3>
|
||
<p>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 notranslate"><span class="pre">str</span></code></a> or <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> as a
|
||
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 notranslate"><span class="pre">StringIO</span></code></a> can be used
|
||
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 notranslate"><span class="pre">BytesIO</span></code></a> can be used like a file
|
||
opened in binary mode. Both provide full read-write capabilities with random
|
||
access.</p>
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">See also</p>
|
||
<dl class="simple">
|
||
<dt><a class="reference internal" href="sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a></dt><dd><p>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 notranslate"><span class="pre">sys.stdin</span></code></a>, <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a>,
|
||
and <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a>.</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="section" id="class-hierarchy">
|
||
<h2>Class hierarchy<a class="headerlink" href="#class-hierarchy" title="Permalink to this headline">¶</a></h2>
|
||
<p>The implementation of I/O streams is organized as a hierarchy of classes. First
|
||
<a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">abstract base classes</span></a> (ABCs), which are used to
|
||
specify the various categories of streams, then concrete classes providing the
|
||
standard stream implementations.</p>
|
||
<blockquote>
|
||
<div><div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>The abstract base classes also provide default implementations of some
|
||
methods in order to help implementation of concrete stream classes. For
|
||
example, <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> provides unoptimized implementations of
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code> and <a class="reference internal" href="#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a>.</p>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>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 notranslate"><span class="pre">IOBase</span></code></a>. It
|
||
defines the basic interface to a stream. Note, however, that there is no
|
||
separation between reading and writing to streams; implementations are allowed
|
||
to raise <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a> if they do not support a given operation.</p>
|
||
<p>The <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> ABC extends <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>. It deals with the reading
|
||
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 notranslate"><span class="pre">FileIO</span></code></a> subclasses <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a>
|
||
to provide an interface to files in the machine’s file system.</p>
|
||
<p>The <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> ABC deals with buffering on a raw byte stream
|
||
(<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a>). Its subclasses, <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a>,
|
||
<a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a>, and <a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code></a> buffer streams that are
|
||
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 notranslate"><span class="pre">BufferedRandom</span></code></a>
|
||
provides a buffered interface to random access streams. Another
|
||
<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> subclass, <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a>, is a stream of in-memory
|
||
bytes.</p>
|
||
<p>The <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> ABC, another subclass of <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>, deals with
|
||
streams whose bytes represent text, and handles encoding and decoding to and
|
||
from strings. <a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOWrapper</span></code></a>, which extends it, is a buffered text
|
||
interface to a buffered raw stream (<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>). Finally,
|
||
<a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code></a> is an in-memory stream for text.</p>
|
||
<p>Argument names are not part of the specification, and only the arguments of
|
||
<a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> are intended to be used as keyword arguments.</p>
|
||
<p>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 notranslate"><span class="pre">io</span></code></a> module:</p>
|
||
<table class="docutils align-center">
|
||
<colgroup>
|
||
<col style="width: 21%" />
|
||
<col style="width: 15%" />
|
||
<col style="width: 21%" />
|
||
<col style="width: 43%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>ABC</p></th>
|
||
<th class="head"><p>Inherits</p></th>
|
||
<th class="head"><p>Stub Methods</p></th>
|
||
<th class="head"><p>Mixin Methods and Properties</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a></p></td>
|
||
<td></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">fileno</span></code>, <code class="docutils literal notranslate"><span class="pre">seek</span></code>,
|
||
and <code class="docutils literal notranslate"><span class="pre">truncate</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">close</span></code>, <code class="docutils literal notranslate"><span class="pre">closed</span></code>, <code class="docutils literal notranslate"><span class="pre">__enter__</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">__exit__</span></code>, <code class="docutils literal notranslate"><span class="pre">flush</span></code>, <code class="docutils literal notranslate"><span class="pre">isatty</span></code>, <code class="docutils literal notranslate"><span class="pre">__iter__</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">__next__</span></code>, <code class="docutils literal notranslate"><span class="pre">readable</span></code>, <code class="docutils literal notranslate"><span class="pre">readline</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">readlines</span></code>, <code class="docutils literal notranslate"><span class="pre">seekable</span></code>, <code class="docutils literal notranslate"><span class="pre">tell</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">writable</span></code>, and <code class="docutils literal notranslate"><span class="pre">writelines</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a></p></td>
|
||
<td><p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">readinto</span></code> and
|
||
<code class="docutils literal notranslate"><span class="pre">write</span></code></p></td>
|
||
<td><p>Inherited <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> methods, <code class="docutils literal notranslate"><span class="pre">read</span></code>,
|
||
and <code class="docutils literal notranslate"><span class="pre">readall</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a></p></td>
|
||
<td><p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">detach</span></code>, <code class="docutils literal notranslate"><span class="pre">read</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">read1</span></code>, and <code class="docutils literal notranslate"><span class="pre">write</span></code></p></td>
|
||
<td><p>Inherited <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> methods, <code class="docutils literal notranslate"><span class="pre">readinto</span></code>,
|
||
and <code class="docutils literal notranslate"><span class="pre">readinto1</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a></p></td>
|
||
<td><p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">detach</span></code>, <code class="docutils literal notranslate"><span class="pre">read</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">readline</span></code>, and
|
||
<code class="docutils literal notranslate"><span class="pre">write</span></code></p></td>
|
||
<td><p>Inherited <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> methods, <code class="docutils literal notranslate"><span class="pre">encoding</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">errors</span></code>, and <code class="docutils literal notranslate"><span class="pre">newlines</span></code></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<div class="section" id="i-o-base-classes">
|
||
<h3>I/O Base Classes<a class="headerlink" href="#i-o-base-classes" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="io.IOBase">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">IOBase</code><a class="headerlink" href="#io.IOBase" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The abstract base class for all I/O classes, acting on streams of bytes.
|
||
There is no public constructor.</p>
|
||
<p>This class provides empty abstract implementations for many methods
|
||
that derived classes can override selectively; the default
|
||
implementations represent a file that cannot be read, written or
|
||
seeked.</p>
|
||
<p>Even though <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> does not declare <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code>
|
||
or <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> because their signatures will vary, implementations and
|
||
clients should consider those methods part of the interface. Also,
|
||
implementations may raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> (or <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a>)
|
||
when operations they do not support are called.</p>
|
||
<p>The basic type used for binary data read from or written to a file is
|
||
<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a>. Other <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a> are
|
||
accepted as method arguments too. Text I/O classes work with <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> data.</p>
|
||
<p>Note that calling any method (even inquiries) on a closed stream is
|
||
undefined. Implementations may raise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> in this case.</p>
|
||
<p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> (and its subclasses) supports the iterator protocol, meaning
|
||
that an <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> object can be iterated over yielding the lines in a
|
||
stream. Lines are defined slightly differently depending on whether the
|
||
stream is a binary stream (yielding bytes), or a text stream (yielding
|
||
character strings). See <a class="reference internal" href="#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> below.</p>
|
||
<p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> is also a context manager and therefore supports the
|
||
<a class="reference internal" href="../reference/compound_stmts.html#with"><code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code></a> statement. In this example, <em>file</em> is closed after the
|
||
<code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code> statement’s suite is finished—even if an exception occurs:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'spam.txt'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">file</span><span class="p">:</span>
|
||
<span class="n">file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'Spam and eggs!'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> provides these data attributes and methods:</p>
|
||
<dl class="method">
|
||
<dt id="io.IOBase.close">
|
||
<code class="descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.close" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Flush and close this stream. This method has no effect if the file is
|
||
already closed. Once the file is closed, any operation on the file
|
||
(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 notranslate"><span class="pre">ValueError</span></code></a>.</p>
|
||
<p>As a convenience, it is allowed to call this method more than once;
|
||
only the first call, however, will have an effect.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.IOBase.closed">
|
||
<code class="descname">closed</code><a class="headerlink" href="#io.IOBase.closed" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the stream is closed.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.fileno">
|
||
<code class="descname">fileno</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.fileno" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the underlying file descriptor (an integer) of the stream if it
|
||
exists. An <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> is raised if the IO object does not use a file
|
||
descriptor.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.flush">
|
||
<code class="descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.flush" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Flush the write buffers of the stream if applicable. This does nothing
|
||
for read-only and non-blocking streams.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.isatty">
|
||
<code class="descname">isatty</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.isatty" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the stream is interactive (i.e., connected to
|
||
a terminal/tty device).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.readable">
|
||
<code class="descname">readable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the stream can be read from. If <code class="docutils literal notranslate"><span class="pre">False</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code>
|
||
will raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.readline">
|
||
<code class="descname">readline</code><span class="sig-paren">(</span><em>size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readline" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and return one line from the stream. If <em>size</em> is specified, at
|
||
most <em>size</em> bytes will be read.</p>
|
||
<p>The line terminator is always <code class="docutils literal notranslate"><span class="pre">b'\n'</span></code> for binary files; for text files,
|
||
the <em>newline</em> argument to <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> can be used to select the line
|
||
terminator(s) recognized.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.readlines">
|
||
<code class="descname">readlines</code><span class="sig-paren">(</span><em>hint=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readlines" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and return a list of lines from the stream. <em>hint</em> can be specified
|
||
to control the number of lines read: no more lines will be read if the
|
||
total size (in bytes/characters) of all lines so far exceeds <em>hint</em>.</p>
|
||
<p>Note that it’s already possible to iterate on file objects using <code class="docutils literal notranslate"><span class="pre">for</span>
|
||
<span class="pre">line</span> <span class="pre">in</span> <span class="pre">file:</span> <span class="pre">...</span></code> without calling <code class="docutils literal notranslate"><span class="pre">file.readlines()</span></code>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.seek">
|
||
<code class="descname">seek</code><span class="sig-paren">(</span><em>offset</em>, <em>whence=SEEK_SET</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.seek" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the stream position to the given byte <em>offset</em>. <em>offset</em> is
|
||
interpreted relative to the position indicated by <em>whence</em>. The default
|
||
value for <em>whence</em> is <code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_SET</span></code>. Values for <em>whence</em> are:</p>
|
||
<ul class="simple">
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_SET</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code> – start of the stream (the default);
|
||
<em>offset</em> should be zero or positive</p></li>
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_CUR</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> – current stream position; <em>offset</em> may
|
||
be negative</p></li>
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_END</span></code> or <code class="docutils literal notranslate"><span class="pre">2</span></code> – end of the stream; <em>offset</em> is usually
|
||
negative</p></li>
|
||
</ul>
|
||
<p>Return the new absolute position.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.1: </span>The <code class="docutils literal notranslate"><span class="pre">SEEK_*</span></code> constants.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.3: </span>Some operating systems could support additional values, like
|
||
<code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_HOLE</span></code> or <code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_DATA</span></code>. The valid values
|
||
for a file could depend on it being open in text or binary mode.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.seekable">
|
||
<code class="descname">seekable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.seekable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the stream supports random access. If <code class="docutils literal notranslate"><span class="pre">False</span></code>,
|
||
<a class="reference internal" href="#io.IOBase.seek" title="io.IOBase.seek"><code class="xref py py-meth docutils literal notranslate"><span class="pre">seek()</span></code></a>, <a class="reference internal" href="#io.IOBase.tell" title="io.IOBase.tell"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tell()</span></code></a> and <a class="reference internal" href="#io.IOBase.truncate" title="io.IOBase.truncate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">truncate()</span></code></a> will raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.tell">
|
||
<code class="descname">tell</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.tell" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the current stream position.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.truncate">
|
||
<code class="descname">truncate</code><span class="sig-paren">(</span><em>size=None</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.truncate" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Resize the stream to the given <em>size</em> in bytes (or the current position
|
||
if <em>size</em> is not specified). The current stream position isn’t changed.
|
||
This resizing can extend or reduce the current file size. In case of
|
||
extension, the contents of the new file area depend on the platform
|
||
(on most systems, additional bytes are zero-filled). The new file size
|
||
is returned.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.5: </span>Windows will now zero-fill files when extending.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.writable">
|
||
<code class="descname">writable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.writable" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the stream supports writing. If <code class="docutils literal notranslate"><span class="pre">False</span></code>,
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> and <a class="reference internal" href="#io.IOBase.truncate" title="io.IOBase.truncate"><code class="xref py py-meth docutils literal notranslate"><span class="pre">truncate()</span></code></a> will raise <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.writelines">
|
||
<code class="descname">writelines</code><span class="sig-paren">(</span><em>lines</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.writelines" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write a list of lines to the stream. Line separators are not added, so it
|
||
is usual for each of the lines provided to have a line separator at the
|
||
end.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.__del__">
|
||
<code class="descname">__del__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.__del__" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Prepare for object destruction. <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> provides a default
|
||
implementation of this method that calls the instance’s
|
||
<a class="reference internal" href="#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.RawIOBase">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">RawIOBase</code><a class="headerlink" href="#io.RawIOBase" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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 notranslate"><span class="pre">IOBase</span></code></a>. There is no
|
||
public constructor.</p>
|
||
<p>Raw binary I/O typically provides low-level access to an underlying OS
|
||
device or API, and does not try to encapsulate it in high-level primitives
|
||
(this is left to Buffered I/O and Text I/O, described later in this page).</p>
|
||
<p>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 notranslate"><span class="pre">IOBase</span></code></a>,
|
||
<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> provides the following methods:</p>
|
||
<dl class="method">
|
||
<dt id="io.RawIOBase.read">
|
||
<code class="descname">read</code><span class="sig-paren">(</span><em>size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.read" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read up to <em>size</em> bytes from the object and return them. As a convenience,
|
||
if <em>size</em> is unspecified or -1, all bytes until EOF are returned.
|
||
Otherwise, only one system call is ever made. Fewer than <em>size</em> bytes may
|
||
be returned if the operating system call returns fewer than <em>size</em> bytes.</p>
|
||
<p>If 0 bytes are returned, and <em>size</em> was not 0, this indicates end of file.
|
||
If the object is in non-blocking mode and no bytes are available,
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
|
||
<p>The default implementation defers to <a class="reference internal" href="#io.RawIOBase.readall" title="io.RawIOBase.readall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readall()</span></code></a> and
|
||
<a class="reference internal" href="#io.RawIOBase.readinto" title="io.RawIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.RawIOBase.readall">
|
||
<code class="descname">readall</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.readall" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and return all the bytes from the stream until EOF, using multiple
|
||
calls to the stream if necessary.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.RawIOBase.readinto">
|
||
<code class="descname">readinto</code><span class="sig-paren">(</span><em>b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.readinto" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read bytes into a pre-allocated, writable
|
||
<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> <em>b</em>, and return the
|
||
number of bytes read. For example, <em>b</em> might be a <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>.
|
||
If the object is in non-blocking mode and no bytes
|
||
are available, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.RawIOBase.write">
|
||
<code class="descname">write</code><span class="sig-paren">(</span><em>b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the given <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>, <em>b</em>, to the
|
||
underlying raw stream, and return the number of
|
||
bytes written. This can be less than the length of <em>b</em> in
|
||
bytes, depending on specifics of the underlying raw
|
||
stream, and especially if it is in non-blocking mode. <code class="docutils literal notranslate"><span class="pre">None</span></code> is
|
||
returned if the raw stream is set not to block and no single byte could
|
||
be readily written to it. The caller may release or mutate <em>b</em> after
|
||
this method returns, so the implementation should only access <em>b</em>
|
||
during the method call.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedIOBase">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">BufferedIOBase</code><a class="headerlink" href="#io.BufferedIOBase" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Base class for binary streams that support some kind of buffering.
|
||
It inherits <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>. There is no public constructor.</p>
|
||
<p>The main difference with <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></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 notranslate"><span class="pre">read()</span></code></a>,
|
||
<a class="reference internal" href="#io.BufferedIOBase.readinto" title="io.BufferedIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a> and <a class="reference internal" href="#io.BufferedIOBase.write" title="io.BufferedIOBase.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> will try (respectively) to read as much
|
||
input as requested or to consume all given output, at the expense of
|
||
making perhaps more than one system call.</p>
|
||
<p>In addition, those methods can raise <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> if the
|
||
underlying raw stream is in non-blocking mode and cannot take or give
|
||
enough data; unlike their <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> counterparts, they will
|
||
never return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
|
||
<p>Besides, the <a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> method does not have a default
|
||
implementation that defers to <a class="reference internal" href="#io.BufferedIOBase.readinto" title="io.BufferedIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a>.</p>
|
||
<p>A typical <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> implementation should not inherit from a
|
||
<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> implementation, but wrap one, like
|
||
<a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> and <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> do.</p>
|
||
<p><a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> provides or overrides these methods and attribute in
|
||
addition to those from <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>:</p>
|
||
<dl class="attribute">
|
||
<dt id="io.BufferedIOBase.raw">
|
||
<code class="descname">raw</code><a class="headerlink" href="#io.BufferedIOBase.raw" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The underlying raw stream (a <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> instance) that
|
||
<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> deals with. This is not part of the
|
||
<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> API and may not exist on some implementations.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.detach">
|
||
<code class="descname">detach</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.detach" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Separate the underlying raw stream from the buffer and return it.</p>
|
||
<p>After the raw stream has been detached, the buffer is in an unusable
|
||
state.</p>
|
||
<p>Some buffers, like <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a>, do not have the concept of a single
|
||
raw stream to return from this method. They raise
|
||
<a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.1.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.read">
|
||
<code class="descname">read</code><span class="sig-paren">(</span><em>size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.read" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and return up to <em>size</em> bytes. If the argument is omitted, <code class="docutils literal notranslate"><span class="pre">None</span></code>,
|
||
or negative, data is read and returned until EOF is reached. An empty
|
||
<a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object is returned if the stream is already at EOF.</p>
|
||
<p>If the argument is positive, and the underlying raw stream is not
|
||
interactive, multiple raw reads may be issued to satisfy the byte count
|
||
(unless EOF is reached first). But for interactive raw streams, at most
|
||
one raw read will be issued, and a short result does not imply that EOF is
|
||
imminent.</p>
|
||
<p>A <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> is raised if the underlying raw stream is in
|
||
non blocking-mode, and has no data available at the moment.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.read1">
|
||
<code class="descname">read1</code><span class="sig-paren">(</span><span class="optional">[</span><em>size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.read1" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and return up to <em>size</em> bytes, with at most one call to 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 notranslate"><span class="pre">read()</span></code></a> (or
|
||
<a class="reference internal" href="#io.RawIOBase.readinto" title="io.RawIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a>) method. This can be useful if you are
|
||
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 notranslate"><span class="pre">BufferedIOBase</span></code></a>
|
||
object.</p>
|
||
<p>If <em>size</em> is <code class="docutils literal notranslate"><span class="pre">-1</span></code> (the default), an arbitrary number of bytes are
|
||
returned (more than zero unless EOF is reached).</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.readinto">
|
||
<code class="descname">readinto</code><span class="sig-paren">(</span><em>b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.readinto" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read bytes into a pre-allocated, writable
|
||
<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> <em>b</em> and return the number of bytes read.
|
||
For example, <em>b</em> might be a <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>.</p>
|
||
<p>Like <a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a>, multiple reads may be issued to the underlying raw
|
||
stream, unless the latter is interactive.</p>
|
||
<p>A <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> is raised if the underlying raw stream is in non
|
||
blocking-mode, and has no data available at the moment.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.readinto1">
|
||
<code class="descname">readinto1</code><span class="sig-paren">(</span><em>b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.readinto1" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read bytes into a pre-allocated, writable
|
||
<a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> <em>b</em>, using at most one call to
|
||
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 notranslate"><span class="pre">read()</span></code></a> (or
|
||
<a class="reference internal" href="#io.RawIOBase.readinto" title="io.RawIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a>) method. Return the number of bytes read.</p>
|
||
<p>A <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> is raised if the underlying raw stream is in non
|
||
blocking-mode, and has no data available at the moment.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.write">
|
||
<code class="descname">write</code><span class="sig-paren">(</span><em>b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the given <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>, <em>b</em>, and return the number
|
||
of bytes written (always equal to the length of <em>b</em> in bytes, since if
|
||
the write fails an <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> will be raised). Depending on the
|
||
actual implementation, these bytes may be readily written to the
|
||
underlying stream, or held in a buffer for performance and latency
|
||
reasons.</p>
|
||
<p>When in non-blocking mode, a <a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> is raised if the
|
||
data needed to be written to the raw stream but it couldn’t accept
|
||
all the data without blocking.</p>
|
||
<p>The caller may release or mutate <em>b</em> after this method returns,
|
||
so the implementation should only access <em>b</em> during the method call.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="raw-file-i-o">
|
||
<h3>Raw File I/O<a class="headerlink" href="#raw-file-i-o" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="io.FileIO">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">FileIO</code><span class="sig-paren">(</span><em>name</em>, <em>mode='r'</em>, <em>closefd=True</em>, <em>opener=None</em><span class="sig-paren">)</span><a class="headerlink" href="#io.FileIO" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p><a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code></a> represents an OS-level file containing bytes data.
|
||
It implements the <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> interface (and therefore the
|
||
<a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> interface, too).</p>
|
||
<p>The <em>name</em> can be one of two things:</p>
|
||
<ul class="simple">
|
||
<li><p>a character string or <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> object representing the path to the
|
||
file which will be opened. In this case closefd must be <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default)
|
||
otherwise an error will be raised.</p></li>
|
||
<li><p>an integer representing the number of an existing OS-level file descriptor
|
||
to which the resulting <a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code></a> object will give access. When the
|
||
FileIO object is closed this fd will be closed as well, unless <em>closefd</em>
|
||
is set to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p></li>
|
||
</ul>
|
||
<p>The <em>mode</em> can be <code class="docutils literal notranslate"><span class="pre">'r'</span></code>, <code class="docutils literal notranslate"><span class="pre">'w'</span></code>, <code class="docutils literal notranslate"><span class="pre">'x'</span></code> or <code class="docutils literal notranslate"><span class="pre">'a'</span></code> for reading
|
||
(default), writing, exclusive creation or appending. The file will be
|
||
created if it doesn’t exist when opened for writing or appending; it will be
|
||
truncated when opened for writing. <a class="reference internal" href="exceptions.html#FileExistsError" title="FileExistsError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">FileExistsError</span></code></a> will be raised if
|
||
it already exists when opened for creating. Opening a file for creating
|
||
implies writing, so this mode behaves in a similar way to <code class="docutils literal notranslate"><span class="pre">'w'</span></code>. Add a
|
||
<code class="docutils literal notranslate"><span class="pre">'+'</span></code> to the mode to allow simultaneous reading and writing.</p>
|
||
<p>The <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> (when called with a positive argument), <code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code>
|
||
and <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> methods on this class will only make one system call.</p>
|
||
<p>A custom opener can be used by passing a callable as <em>opener</em>. The underlying
|
||
file descriptor for the file object is then obtained by calling <em>opener</em> with
|
||
(<em>name</em>, <em>flags</em>). <em>opener</em> must return an open file descriptor (passing
|
||
<a class="reference internal" href="os.html#os.open" title="os.open"><code class="xref py py-mod docutils literal notranslate"><span class="pre">os.open</span></code></a> as <em>opener</em> results in functionality similar to passing
|
||
<code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>
|
||
<p>The newly created file is <a class="reference internal" href="os.html#fd-inheritance"><span class="std std-ref">non-inheritable</span></a>.</p>
|
||
<p>See the <a class="reference internal" href="functions.html#open" title="open"><code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code></a> built-in function for examples on using the <em>opener</em>
|
||
parameter.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>The <em>opener</em> parameter was added.
|
||
The <code class="docutils literal notranslate"><span class="pre">'x'</span></code> mode was added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.4: </span>The file is now non-inheritable.</p>
|
||
</div>
|
||
<p>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 notranslate"><span class="pre">IOBase</span></code></a> and
|
||
<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a>, <a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code></a> provides the following data
|
||
attributes:</p>
|
||
<dl class="attribute">
|
||
<dt id="io.FileIO.mode">
|
||
<code class="descname">mode</code><a class="headerlink" href="#io.FileIO.mode" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The mode as given in the constructor.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.FileIO.name">
|
||
<code class="descname">name</code><a class="headerlink" href="#io.FileIO.name" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The file name. This is the file descriptor of the file when no name is
|
||
given in the constructor.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="buffered-streams">
|
||
<h3>Buffered Streams<a class="headerlink" href="#buffered-streams" title="Permalink to this headline">¶</a></h3>
|
||
<p>Buffered I/O streams provide a higher-level interface to an I/O device
|
||
than raw I/O does.</p>
|
||
<dl class="class">
|
||
<dt id="io.BytesIO">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">BytesIO</code><span class="sig-paren">(</span><span class="optional">[</span><em>initial_bytes</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A stream implementation using an in-memory bytes buffer. It inherits
|
||
<a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>. The buffer is discarded when the
|
||
<a class="reference internal" href="#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method is called.</p>
|
||
<p>The optional argument <em>initial_bytes</em> is a <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a> that
|
||
contains initial data.</p>
|
||
<p><a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> provides or overrides these methods in addition to those
|
||
from <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> and <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>:</p>
|
||
<dl class="method">
|
||
<dt id="io.BytesIO.getbuffer">
|
||
<code class="descname">getbuffer</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.getbuffer" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a readable and writable view over the contents of the buffer
|
||
without copying them. Also, mutating the view will transparently
|
||
update the contents of the buffer:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">BytesIO</span><span class="p">(</span><span class="sa">b</span><span class="s2">"abcdef"</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">view</span> <span class="o">=</span> <span class="n">b</span><span class="o">.</span><span class="n">getbuffer</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">view</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">4</span><span class="p">]</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">"56"</span>
|
||
<span class="gp">>>> </span><span class="n">b</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
|
||
<span class="go">b'ab56ef'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">Note</p>
|
||
<p>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 notranslate"><span class="pre">BytesIO</span></code></a> object cannot be
|
||
resized or closed.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.2.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BytesIO.getvalue">
|
||
<code class="descname">getvalue</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.getvalue" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return <a class="reference internal" href="stdtypes.html#bytes" title="bytes"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytes</span></code></a> containing the entire contents of the buffer.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BytesIO.read1">
|
||
<code class="descname">read1</code><span class="sig-paren">(</span><span class="optional">[</span><em>size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.read1" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>In <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a>, this is the same as <a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>size</em> argument is now optional.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BytesIO.readinto1">
|
||
<code class="descname">readinto1</code><span class="sig-paren">(</span><em>b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.readinto1" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>In <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a>, this is the same as <a class="reference internal" href="#io.BufferedIOBase.readinto" title="io.BufferedIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.5.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedReader">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">BufferedReader</code><span class="sig-paren">(</span><em>raw</em>, <em>buffer_size=DEFAULT_BUFFER_SIZE</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A buffer providing higher-level access to a readable, sequential
|
||
<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> object. It inherits <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>.
|
||
When reading data from this object, a larger amount of data may be
|
||
requested from the underlying raw stream, and kept in an internal buffer.
|
||
The buffered data can then be returned directly on subsequent reads.</p>
|
||
<p>The constructor creates a <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> for the given readable
|
||
<em>raw</em> stream and <em>buffer_size</em>. If <em>buffer_size</em> is omitted,
|
||
<a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT_BUFFER_SIZE</span></code></a> is used.</p>
|
||
<p><a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> provides or overrides these methods in addition to
|
||
those from <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> and <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>:</p>
|
||
<dl class="method">
|
||
<dt id="io.BufferedReader.peek">
|
||
<code class="descname">peek</code><span class="sig-paren">(</span><span class="optional">[</span><em>size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.peek" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return bytes from the stream without advancing the position. At most one
|
||
single read on the raw stream is done to satisfy the call. The number of
|
||
bytes returned may be less or more than requested.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedReader.read">
|
||
<code class="descname">read</code><span class="sig-paren">(</span><span class="optional">[</span><em>size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.read" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and return <em>size</em> bytes, or if <em>size</em> is not given or negative, until
|
||
EOF or if the read call would block in non-blocking mode.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedReader.read1">
|
||
<code class="descname">read1</code><span class="sig-paren">(</span><span class="optional">[</span><em>size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.read1" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and return up to <em>size</em> bytes with only one call on the raw stream.
|
||
If at least one byte is buffered, only buffered bytes are returned.
|
||
Otherwise, one raw stream read call is made.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>size</em> argument is now optional.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedWriter">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">BufferedWriter</code><span class="sig-paren">(</span><em>raw</em>, <em>buffer_size=DEFAULT_BUFFER_SIZE</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A buffer providing higher-level access to a writeable, sequential
|
||
<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> object. It inherits <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>.
|
||
When writing to this object, data is normally placed into an internal
|
||
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 notranslate"><span class="pre">RawIOBase</span></code></a>
|
||
object under various conditions, including:</p>
|
||
<ul class="simple">
|
||
<li><p>when the buffer gets too small for all pending data;</p></li>
|
||
<li><p>when <a class="reference internal" href="#io.BufferedWriter.flush" title="io.BufferedWriter.flush"><code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code></a> is called;</p></li>
|
||
<li><p>when a <code class="xref py py-meth docutils literal notranslate"><span class="pre">seek()</span></code> is requested (for <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> objects);</p></li>
|
||
<li><p>when the <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> object is closed or destroyed.</p></li>
|
||
</ul>
|
||
<p>The constructor creates a <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> for the given writeable
|
||
<em>raw</em> stream. If the <em>buffer_size</em> is not given, it defaults to
|
||
<a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT_BUFFER_SIZE</span></code></a>.</p>
|
||
<p><a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> provides or overrides these methods in addition to
|
||
those from <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> and <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>:</p>
|
||
<dl class="method">
|
||
<dt id="io.BufferedWriter.flush">
|
||
<code class="descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter.flush" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Force bytes held in the buffer into the raw stream. A
|
||
<a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> should be raised if the raw stream blocks.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedWriter.write">
|
||
<code class="descname">write</code><span class="sig-paren">(</span><em>b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter.write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>, <em>b</em>, and return the
|
||
number of bytes written. When in non-blocking mode, a
|
||
<a class="reference internal" href="exceptions.html#BlockingIOError" title="BlockingIOError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code></a> is raised if the buffer needs to be written out but
|
||
the raw stream blocks.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedRandom">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">BufferedRandom</code><span class="sig-paren">(</span><em>raw</em>, <em>buffer_size=DEFAULT_BUFFER_SIZE</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedRandom" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A buffered interface to random access streams. It inherits
|
||
<a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> and <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a>, and further supports
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">seek()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">tell()</span></code> functionality.</p>
|
||
<p>The constructor creates a reader and writer for a seekable raw stream, given
|
||
in the first argument. If the <em>buffer_size</em> is omitted it defaults to
|
||
<a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT_BUFFER_SIZE</span></code></a>.</p>
|
||
<p><a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> is capable of anything <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> or
|
||
<a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> can do.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedRWPair">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">BufferedRWPair</code><span class="sig-paren">(</span><em>reader</em>, <em>writer</em>, <em>buffer_size=DEFAULT_BUFFER_SIZE</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedRWPair" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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 notranslate"><span class="pre">RawIOBase</span></code></a>
|
||
objects – one readable, the other writeable – into a single bidirectional
|
||
endpoint. It inherits <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>.</p>
|
||
<p><em>reader</em> and <em>writer</em> are <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> objects that are readable and
|
||
writeable respectively. If the <em>buffer_size</em> is omitted it defaults to
|
||
<a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT_BUFFER_SIZE</span></code></a>.</p>
|
||
<p><a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code></a> implements all of <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>’s methods
|
||
except for <a class="reference internal" href="#io.BufferedIOBase.detach" title="io.BufferedIOBase.detach"><code class="xref py py-meth docutils literal notranslate"><span class="pre">detach()</span></code></a>, which raises
|
||
<a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a>.</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">Warning</p>
|
||
<p><a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code></a> does not attempt to synchronize accesses to
|
||
its underlying raw streams. You should not pass it the same object
|
||
as reader and writer; use <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> instead.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
<div class="section" id="id1">
|
||
<h3>Text I/O<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="io.TextIOBase">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">TextIOBase</code><a class="headerlink" href="#io.TextIOBase" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Base class for text streams. This class provides a character and line based
|
||
interface to stream I/O. It inherits <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>.
|
||
There is no public constructor.</p>
|
||
<p><a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> provides or overrides these data attributes and
|
||
methods in addition to those from <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a>:</p>
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOBase.encoding">
|
||
<code class="descname">encoding</code><a class="headerlink" href="#io.TextIOBase.encoding" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The name of the encoding used to decode the stream’s bytes into
|
||
strings, and to encode strings into bytes.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOBase.errors">
|
||
<code class="descname">errors</code><a class="headerlink" href="#io.TextIOBase.errors" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The error setting of the decoder or encoder.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOBase.newlines">
|
||
<code class="descname">newlines</code><a class="headerlink" href="#io.TextIOBase.newlines" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A string, a tuple of strings, or <code class="docutils literal notranslate"><span class="pre">None</span></code>, indicating the newlines
|
||
translated so far. Depending on the implementation and the initial
|
||
constructor flags, this may not be available.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOBase.buffer">
|
||
<code class="descname">buffer</code><a class="headerlink" href="#io.TextIOBase.buffer" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>The underlying binary buffer (a <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> instance) that
|
||
<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> deals with. This is not part of the
|
||
<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> API and may not exist in some implementations.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.detach">
|
||
<code class="descname">detach</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.detach" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>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 notranslate"><span class="pre">TextIOBase</span></code></a> and
|
||
return it.</p>
|
||
<p>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 notranslate"><span class="pre">TextIOBase</span></code></a> is
|
||
in an unusable state.</p>
|
||
<p>Some <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> implementations, like <a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code></a>, may not
|
||
have the concept of an underlying buffer and calling this method will
|
||
raise <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a>.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.1.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.read">
|
||
<code class="descname">read</code><span class="sig-paren">(</span><em>size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.read" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read and return at most <em>size</em> characters from the stream as a single
|
||
<a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a>. If <em>size</em> is negative or <code class="docutils literal notranslate"><span class="pre">None</span></code>, reads until EOF.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.readline">
|
||
<code class="descname">readline</code><span class="sig-paren">(</span><em>size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.readline" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Read until newline or EOF and return a single <code class="docutils literal notranslate"><span class="pre">str</span></code>. If the stream is
|
||
already at EOF, an empty string is returned.</p>
|
||
<p>If <em>size</em> is specified, at most <em>size</em> characters will be read.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.seek">
|
||
<code class="descname">seek</code><span class="sig-paren">(</span><em>offset</em>, <em>whence=SEEK_SET</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.seek" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Change the stream position to the given <em>offset</em>. Behaviour depends on
|
||
the <em>whence</em> parameter. The default value for <em>whence</em> is
|
||
<code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_SET</span></code>.</p>
|
||
<ul class="simple">
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_SET</span></code> or <code class="docutils literal notranslate"><span class="pre">0</span></code>: seek from the start of the stream
|
||
(the default); <em>offset</em> must either be a number returned by
|
||
<a class="reference internal" href="#io.TextIOBase.tell" title="io.TextIOBase.tell"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TextIOBase.tell()</span></code></a>, or zero. Any other <em>offset</em> value
|
||
produces undefined behaviour.</p></li>
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_CUR</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code>: “seek” to the current position;
|
||
<em>offset</em> must be zero, which is a no-operation (all other values
|
||
are unsupported).</p></li>
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_END</span></code> or <code class="docutils literal notranslate"><span class="pre">2</span></code>: seek to the end of the stream;
|
||
<em>offset</em> must be zero (all other values are unsupported).</p></li>
|
||
</ul>
|
||
<p>Return the new absolute position as an opaque number.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.1: </span>The <code class="docutils literal notranslate"><span class="pre">SEEK_*</span></code> constants.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.tell">
|
||
<code class="descname">tell</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.tell" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return the current stream position as an opaque number. The number
|
||
does not usually represent a number of bytes in the underlying
|
||
binary storage.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.write">
|
||
<code class="descname">write</code><span class="sig-paren">(</span><em>s</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.write" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Write the string <em>s</em> to the stream and return the number of characters
|
||
written.</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.TextIOWrapper">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">TextIOWrapper</code><span class="sig-paren">(</span><em>buffer</em>, <em>encoding=None</em>, <em>errors=None</em>, <em>newline=None</em>, <em>line_buffering=False</em>, <em>write_through=False</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOWrapper" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A buffered text stream over a <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> binary stream.
|
||
It inherits <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a>.</p>
|
||
<p><em>encoding</em> gives the name of the encoding that the stream will be decoded or
|
||
encoded with. It defaults to
|
||
<a class="reference internal" href="locale.html#locale.getpreferredencoding" title="locale.getpreferredencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getpreferredencoding(False)</span></code></a>.</p>
|
||
<p><em>errors</em> is an optional string that specifies how encoding and decoding
|
||
errors are to be handled. Pass <code class="docutils literal notranslate"><span class="pre">'strict'</span></code> to raise a <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>
|
||
exception if there is an encoding error (the default of <code class="docutils literal notranslate"><span class="pre">None</span></code> has the same
|
||
effect), or pass <code class="docutils literal notranslate"><span class="pre">'ignore'</span></code> to ignore errors. (Note that ignoring encoding
|
||
errors can lead to data loss.) <code class="docutils literal notranslate"><span class="pre">'replace'</span></code> causes a replacement marker
|
||
(such as <code class="docutils literal notranslate"><span class="pre">'?'</span></code>) to be inserted where there is malformed data.
|
||
<code class="docutils literal notranslate"><span class="pre">'backslashreplace'</span></code> causes malformed data to be replaced by a
|
||
backslashed escape sequence. When writing, <code class="docutils literal notranslate"><span class="pre">'xmlcharrefreplace'</span></code>
|
||
(replace with the appropriate XML character reference) or <code class="docutils literal notranslate"><span class="pre">'namereplace'</span></code>
|
||
(replace with <code class="docutils literal notranslate"><span class="pre">\N{...}</span></code> escape sequences) can be used. Any other error
|
||
handling name that has been registered with
|
||
<a class="reference internal" href="codecs.html#codecs.register_error" title="codecs.register_error"><code class="xref py py-func docutils literal notranslate"><span class="pre">codecs.register_error()</span></code></a> is also valid.</p>
|
||
<p id="index-1"><em>newline</em> controls how line endings are handled. It can be <code class="docutils literal notranslate"><span class="pre">None</span></code>,
|
||
<code class="docutils literal notranslate"><span class="pre">''</span></code>, <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>, <code class="docutils literal notranslate"><span class="pre">'\r'</span></code>, and <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code>. It works as follows:</p>
|
||
<ul class="simple">
|
||
<li><p>When reading input from the stream, if <em>newline</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>,
|
||
<a class="reference internal" href="../glossary.html#term-universal-newlines"><span class="xref std std-term">universal newlines</span></a> mode is enabled. Lines in the input can end in
|
||
<code class="docutils literal notranslate"><span class="pre">'\n'</span></code>, <code class="docutils literal notranslate"><span class="pre">'\r'</span></code>, or <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code>, and these are translated into <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>
|
||
before being returned to the caller. If it is <code class="docutils literal notranslate"><span class="pre">''</span></code>, universal newlines
|
||
mode is enabled, but line endings are returned to the caller untranslated.
|
||
If it has any of the other legal values, input lines are only terminated
|
||
by the given string, and the line ending is returned to the caller
|
||
untranslated.</p></li>
|
||
<li><p>When writing output to the stream, if <em>newline</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>, any <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>
|
||
characters written are translated to the system default line separator,
|
||
<a class="reference internal" href="os.html#os.linesep" title="os.linesep"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.linesep</span></code></a>. If <em>newline</em> is <code class="docutils literal notranslate"><span class="pre">''</span></code> or <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>, no translation
|
||
takes place. If <em>newline</em> is any of the other legal values, any <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>
|
||
characters written are translated to the given string.</p></li>
|
||
</ul>
|
||
<p>If <em>line_buffering</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, <code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code> is implied when a call to
|
||
write contains a newline character or a carriage return.</p>
|
||
<p>If <em>write_through</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, calls to <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> are guaranteed
|
||
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 notranslate"><span class="pre">TextIOWrapper</span></code></a>
|
||
object is immediately handled to its underlying binary <em>buffer</em>.</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>The <em>write_through</em> argument has been added.</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">Changed in version 3.3: </span>The default <em>encoding</em> is now <code class="docutils literal notranslate"><span class="pre">locale.getpreferredencoding(False)</span></code>
|
||
instead of <code class="docutils literal notranslate"><span class="pre">locale.getpreferredencoding()</span></code>. Don’t change temporary the
|
||
locale encoding using <a class="reference internal" href="locale.html#locale.setlocale" title="locale.setlocale"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.setlocale()</span></code></a>, use the current locale
|
||
encoding instead of the user preferred encoding.</p>
|
||
</div>
|
||
<p><a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOWrapper</span></code></a> provides these members in addition to those of
|
||
<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> and its parents:</p>
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOWrapper.line_buffering">
|
||
<code class="descname">line_buffering</code><a class="headerlink" href="#io.TextIOWrapper.line_buffering" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Whether line buffering is enabled.</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOWrapper.write_through">
|
||
<code class="descname">write_through</code><a class="headerlink" href="#io.TextIOWrapper.write_through" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Whether writes are passed immediately to the underlying binary
|
||
buffer.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOWrapper.reconfigure">
|
||
<code class="descname">reconfigure</code><span class="sig-paren">(</span><em>*[, encoding][, errors][, newline][, line_buffering][, write_through]</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOWrapper.reconfigure" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Reconfigure this text stream using new settings for <em>encoding</em>,
|
||
<em>errors</em>, <em>newline</em>, <em>line_buffering</em> and <em>write_through</em>.</p>
|
||
<p>Parameters not specified keep current settings, except
|
||
<code class="docutils literal notranslate"><span class="pre">errors='strict'</span></code> is used when <em>encoding</em> is specified but
|
||
<em>errors</em> is not specified.</p>
|
||
<p>It is not possible to change the encoding or newline if some data
|
||
has already been read from the stream. On the other hand, changing
|
||
encoding after write is possible.</p>
|
||
<p>This method does an implicit stream flush before setting the
|
||
new parameters.</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">New in version 3.7.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.StringIO">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">StringIO</code><span class="sig-paren">(</span><em>initial_value=''</em>, <em>newline='\n'</em><span class="sig-paren">)</span><a class="headerlink" href="#io.StringIO" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>An in-memory stream for text I/O. The text buffer is discarded when the
|
||
<a class="reference internal" href="#io.IOBase.close" title="io.IOBase.close"><code class="xref py py-meth docutils literal notranslate"><span class="pre">close()</span></code></a> method is called.</p>
|
||
<p>The initial value of the buffer can be set by providing <em>initial_value</em>.
|
||
If newline translation is enabled, newlines will be encoded as if by
|
||
<a class="reference internal" href="#io.TextIOBase.write" title="io.TextIOBase.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a>. The stream is positioned at the start of
|
||
the buffer.</p>
|
||
<p>The <em>newline</em> argument works like that of <a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOWrapper</span></code></a>.
|
||
The default is to consider only <code class="docutils literal notranslate"><span class="pre">\n</span></code> characters as ends of lines and
|
||
to do no newline translation. If <em>newline</em> is set to <code class="docutils literal notranslate"><span class="pre">None</span></code>,
|
||
newlines are written as <code class="docutils literal notranslate"><span class="pre">\n</span></code> on all platforms, but universal
|
||
newline decoding is still performed when reading.</p>
|
||
<p><a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code></a> provides this method in addition to those from
|
||
<a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> and its parents:</p>
|
||
<dl class="method">
|
||
<dt id="io.StringIO.getvalue">
|
||
<code class="descname">getvalue</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.StringIO.getvalue" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>Return a <code class="docutils literal notranslate"><span class="pre">str</span></code> containing the entire contents of the buffer.
|
||
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 notranslate"><span class="pre">read()</span></code></a>, although
|
||
the stream position is not changed.</p>
|
||
</dd></dl>
|
||
|
||
<p>Example usage:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">io</span>
|
||
|
||
<span class="n">output</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">StringIO</span><span class="p">()</span>
|
||
<span class="n">output</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'First line.</span><span class="se">\n</span><span class="s1">'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Second line.'</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">output</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Retrieve file contents -- this will be</span>
|
||
<span class="c1"># 'First line.\nSecond line.\n'</span>
|
||
<span class="n">contents</span> <span class="o">=</span> <span class="n">output</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
|
||
|
||
<span class="c1"># Close object and discard memory buffer --</span>
|
||
<span class="c1"># .getvalue() will now raise an exception.</span>
|
||
<span class="n">output</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-2"></span><dl class="class">
|
||
<dt id="io.IncrementalNewlineDecoder">
|
||
<em class="property">class </em><code class="descclassname">io.</code><code class="descname">IncrementalNewlineDecoder</code><a class="headerlink" href="#io.IncrementalNewlineDecoder" title="Permalink to this definition">¶</a></dt>
|
||
<dd><p>A helper codec that decodes newlines for <a class="reference internal" href="../glossary.html#term-universal-newlines"><span class="xref std std-term">universal newlines</span></a> mode.
|
||
It inherits <a class="reference internal" href="codecs.html#codecs.IncrementalDecoder" title="codecs.IncrementalDecoder"><code class="xref py py-class docutils literal notranslate"><span class="pre">codecs.IncrementalDecoder</span></code></a>.</p>
|
||
</dd></dl>
|
||
|
||
</div>
|
||
</div>
|
||
<div class="section" id="performance">
|
||
<h2>Performance<a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h2>
|
||
<p>This section discusses the performance of the provided concrete I/O
|
||
implementations.</p>
|
||
<div class="section" id="id2">
|
||
<h3>Binary I/O<a class="headerlink" href="#id2" title="Permalink to this headline">¶</a></h3>
|
||
<p>By reading and writing only large chunks of data even when the user asks for a
|
||
single byte, buffered I/O hides any inefficiency in calling and executing the
|
||
operating system’s unbuffered I/O routines. The gain depends on the OS and the
|
||
kind of I/O which is performed. For example, on some modern OSes such as Linux,
|
||
unbuffered disk I/O can be as fast as buffered I/O. The bottom line, however,
|
||
is that buffered I/O offers predictable performance regardless of the platform
|
||
and the backing device. Therefore, it is almost always preferable to use
|
||
buffered I/O rather than unbuffered I/O for binary data.</p>
|
||
</div>
|
||
<div class="section" id="id3">
|
||
<h3>Text I/O<a class="headerlink" href="#id3" title="Permalink to this headline">¶</a></h3>
|
||
<p>Text I/O over a binary storage (such as a file) is significantly slower than
|
||
binary I/O over the same storage, because it requires conversions between
|
||
unicode and binary data using a character codec. This can become noticeable
|
||
handling huge amounts of text data like large log files. Also,
|
||
<code class="xref py py-meth docutils literal notranslate"><span class="pre">TextIOWrapper.tell()</span></code> and <code class="xref py py-meth docutils literal notranslate"><span class="pre">TextIOWrapper.seek()</span></code> are both quite slow
|
||
due to the reconstruction algorithm used.</p>
|
||
<p><a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code></a>, however, is a native in-memory unicode container and will
|
||
exhibit similar speed to <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a>.</p>
|
||
</div>
|
||
<div class="section" id="multi-threading">
|
||
<h3>Multi-threading<a class="headerlink" href="#multi-threading" title="Permalink to this headline">¶</a></h3>
|
||
<p><a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code></a> objects are thread-safe to the extent that the operating system
|
||
calls (such as <code class="docutils literal notranslate"><span class="pre">read(2)</span></code> under Unix) they wrap are thread-safe too.</p>
|
||
<p>Binary buffered objects (instances of <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a>,
|
||
<a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a>, <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> and <a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code></a>)
|
||
protect their internal structures using a lock; it is therefore safe to call
|
||
them from multiple threads at once.</p>
|
||
<p><a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOWrapper</span></code></a> objects are not thread-safe.</p>
|
||
</div>
|
||
<div class="section" id="reentrancy">
|
||
<h3>Reentrancy<a class="headerlink" href="#reentrancy" title="Permalink to this headline">¶</a></h3>
|
||
<p>Binary buffered objects (instances of <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a>,
|
||
<a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a>, <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> and <a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code></a>)
|
||
are not reentrant. While reentrant calls will not happen in normal situations,
|
||
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 notranslate"><span class="pre">signal</span></code></a> handler. If a thread tries to
|
||
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 notranslate"><span class="pre">RuntimeError</span></code></a>
|
||
is raised. Note this doesn’t prohibit a different thread from entering the
|
||
buffered object.</p>
|
||
<p>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 notranslate"><span class="pre">open()</span></code></a> function
|
||
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 notranslate"><span class="pre">TextIOWrapper</span></code></a>. This includes
|
||
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 notranslate"><span class="pre">print()</span></code></a> as
|
||
well.</p>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">Table of Contents</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> — Core tools for working with streams</a><ul>
|
||
<li><a class="reference internal" href="#overview">Overview</a><ul>
|
||
<li><a class="reference internal" href="#text-i-o">Text I/O</a></li>
|
||
<li><a class="reference internal" href="#binary-i-o">Binary I/O</a></li>
|
||
<li><a class="reference internal" href="#raw-i-o">Raw I/O</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#high-level-module-interface">High-level Module Interface</a><ul>
|
||
<li><a class="reference internal" href="#in-memory-streams">In-memory streams</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#class-hierarchy">Class hierarchy</a><ul>
|
||
<li><a class="reference internal" href="#i-o-base-classes">I/O Base Classes</a></li>
|
||
<li><a class="reference internal" href="#raw-file-i-o">Raw File I/O</a></li>
|
||
<li><a class="reference internal" href="#buffered-streams">Buffered Streams</a></li>
|
||
<li><a class="reference internal" href="#id1">Text I/O</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#performance">Performance</a><ul>
|
||
<li><a class="reference internal" href="#id2">Binary I/O</a></li>
|
||
<li><a class="reference internal" href="#id3">Text I/O</a></li>
|
||
<li><a class="reference internal" href="#multi-threading">Multi-threading</a></li>
|
||
<li><a class="reference internal" href="#reentrancy">Reentrancy</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>Previous topic</h4>
|
||
<p class="topless"><a href="os.html"
|
||
title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code> — Miscellaneous operating system interfaces</a></p>
|
||
<h4>Next topic</h4>
|
||
<p class="topless"><a href="time.html"
|
||
title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">time</span></code> — Time access and conversions</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>This Page</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">Report a Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.7/Doc/library/io.rst"
|
||
rel="nofollow">Show Source
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>Navigation</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="General Index"
|
||
>index</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python Module Index"
|
||
>modules</a> |</li>
|
||
<li class="right" >
|
||
<a href="time.html" title="time — Time access and conversions"
|
||
>next</a> |</li>
|
||
<li class="right" >
|
||
<a href="os.html" title="os — Miscellaneous operating system interfaces"
|
||
>previous</a> |</li>
|
||
<li><img src="../_static/py.png" alt=""
|
||
style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li>
|
||
<span class="language_switcher_placeholder">en</span>
|
||
<span class="version_switcher_placeholder">3.7.4</span>
|
||
<a href="../index.html">Documentation </a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" >Generic Operating System Services</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" style="display: none" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="Quick search" type="text" name="q" />
|
||
<input type="submit" value="Go" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
<script type="text/javascript">$('.inline-search').show(0);</script>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">Copyright</a> 2001-2019, Python Software Foundation.
|
||
<br />
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
Last updated on Jul 13, 2019.
|
||
<a href="../bugs.html">Found a bug</a>?
|
||
<br />
|
||
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.0.1.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |