parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="io — Core tools for working with streams" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/io.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/io.py Overview: The io module provides Python’s main facilities for dealing with various types of I/O. There are three main types of I/O: text I/O, binary I/O and raw I/O. These ar..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_io_b81db5bf.png" />15<meta property="og:image:alt" content="Source code: Lib/io.py Overview: The io module provides Python’s main facilities for dealing with various types of I/O. There are three main types of I/O: text I/O, binary I/O and raw I/O. These ar..." />16<meta name="description" content="Source code: Lib/io.py Overview: The io module provides Python’s main facilities for dealing with various types of I/O. There are three main types of I/O: text I/O, binary I/O and raw I/O. These ar..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>io — Core tools for working with streams — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="time — Time access and conversions" href="time.html" />43 <link rel="prev" title="os — Miscellaneous operating system interfaces" href="os.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/io.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<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>108<li><a class="reference internal" href="#overview">Overview</a><ul>109<li><a class="reference internal" href="#text-i-o">Text I/O</a></li>110<li><a class="reference internal" href="#binary-i-o">Binary I/O</a></li>111<li><a class="reference internal" href="#raw-i-o">Raw I/O</a></li>112</ul>113</li>114<li><a class="reference internal" href="#text-encoding">Text Encoding</a><ul>115<li><a class="reference internal" href="#opt-in-encodingwarning">Opt-in EncodingWarning</a></li>116</ul>117</li>118<li><a class="reference internal" href="#high-level-module-interface">High-level Module Interface</a></li>119<li><a class="reference internal" href="#class-hierarchy">Class hierarchy</a><ul>120<li><a class="reference internal" href="#i-o-base-classes">I/O Base Classes</a></li>121<li><a class="reference internal" href="#raw-file-i-o">Raw File I/O</a></li>122<li><a class="reference internal" href="#buffered-streams">Buffered Streams</a></li>123<li><a class="reference internal" href="#id1">Text I/O</a></li>124</ul>125</li>126<li><a class="reference internal" href="#static-typing">Static Typing</a></li>127<li><a class="reference internal" href="#performance">Performance</a><ul>128<li><a class="reference internal" href="#id2">Binary I/O</a></li>129<li><a class="reference internal" href="#id3">Text I/O</a></li>130<li><a class="reference internal" href="#multi-threading">Multi-threading</a></li>131<li><a class="reference internal" href="#reentrancy">Reentrancy</a></li>132</ul>133</li>134</ul>135</li>136</ul>137 138 </div>139 <div>140 <h4>Previous topic</h4>141 <p class="topless"><a href="os.html"142 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code> — Miscellaneous operating system interfaces</a></p>143 </div>144 <div>145 <h4>Next topic</h4>146 <p class="topless"><a href="time.html"147 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">time</span></code> — Time access and conversions</a></p>148 </div>149 <script>150 document.addEventListener('DOMContentLoaded', () => {151 const title = document.querySelector('meta[property="og:title"]').content;152 const elements = document.querySelectorAll('.improvepage');153 const pageurl = window.location.href.split('?')[0];154 elements.forEach(element => {155 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));156 url.searchParams.set('pagetitle', title);157 url.searchParams.set('pageurl', pageurl);158 url.searchParams.set('pagesource', "library/io.rst");159 element.href = url.toString();160 });161 });162 </script>163 <div role="note" aria-label="source link">164 <h3>This page</h3>165 <ul class="this-page-menu">166 <li><a href="../bugs.html">Report a bug</a></li>167 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>168 <li>169 <a href="https://github.com/python/cpython/blob/main/Doc/library/io.rst?plain=1"170 rel="nofollow">Show source171 </a>172 </li>173 174 </ul>175 </div>176 </nav>177 </div>178</div>179 180 181 <div class="related" role="navigation" aria-label="Related">182 <h3>Navigation</h3>183 <ul>184 <li class="right" style="margin-right: 10px">185 <a href="../genindex.html" title="General Index"186 accesskey="I">index</a></li>187 <li class="right" >188 <a href="../py-modindex.html" title="Python Module Index"189 >modules</a> |</li>190 <li class="right" >191 <a href="time.html" title="time — Time access and conversions"192 accesskey="N">next</a> |</li>193 <li class="right" >194 <a href="os.html" title="os — Miscellaneous operating system interfaces"195 accesskey="P">previous</a> |</li>196 197 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>198 <li><a href="https://www.python.org/">Python</a> »</li>199 <li class="switchers">200 <div class="language_switcher_placeholder"></div>201 <div class="version_switcher_placeholder"></div>202 </li>203 <li>204 205 </li>206 <li id="cpython-language-and-version">207 <a href="../index.html">3.15.0a6 Documentation</a> »208 </li>209 210 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>211 <li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">Generic Operating System Services</a> »</li>212 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> — Core tools for working with streams</a></li>213 <li class="right">214 215 216 <div class="inline-search" role="search">217 <form class="inline-search" action="../search.html" method="get">218 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">219 <input type="submit" value="Go">220 </form>221 </div>222 |223 </li>224 <li class="right">225<label class="theme-selector-label">226 Theme227 <select class="theme-selector" oninput="activateTheme(this.value)">228 <option value="auto" selected>Auto</option>229 <option value="light">Light</option>230 <option value="dark">Dark</option>231 </select>232</label> |</li>233 234 </ul>235 </div> 236 237 <div class="document">238 <div class="documentwrapper">239 <div class="bodywrapper">240 <div class="body" role="main">241 242 <section id="module-io">243<span id="io-core-tools-for-working-with-streams"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> — Core tools for working with streams<a class="headerlink" href="#module-io" title="Link to this heading">¶</a></h1>244<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/io.py">Lib/io.py</a></p>245<hr class="docutils" />246<section id="overview">247<span id="io-overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Link to this heading">¶</a></h2>248<p id="index-0">The <code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> module provides Python’s main facilities for dealing with various249types of I/O. There are three main types of I/O: <em>text I/O</em>, <em>binary I/O</em>250and <em>raw I/O</em>. These are generic categories, and various backing stores can251be used for each of them. A concrete object belonging to any of these252categories 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>253and <em>file-like object</em>.</p>254<p>Independent of its category, each concrete stream object will also have255various capabilities: it can be read-only, write-only, or read-write. It can256also allow arbitrary random access (seeking forwards or backwards to any257location), or only sequential access (for example in the case of a socket or258pipe).</p>259<p>All streams are careful about the type of data you give to them. For example260giving 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="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> method of a binary stream261will 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 the262<code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> method of a text stream.</p>263<div class="versionchanged">264<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>, since265<code class="xref py py-exc docutils literal notranslate"><span class="pre">IOError</span></code> is now an alias of <code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code>.</p>266</div>267<section id="text-i-o">268<h3>Text I/O<a class="headerlink" href="#text-i-o" title="Link to this heading">¶</a></h3>269<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 whenever270the backing store is natively made of bytes (such as in the case of a file),271encoding and decoding of data is made transparently as well as optional272translation of platform-specific newline characters.</p>273<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>, optionally274specifying an encoding:</p>275<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>276</pre></div>277</div>278<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>279<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>280</pre></div>281</div>282<div class="admonition note">283<p class="admonition-title">Note</p>284<p>When working with a non-blocking stream, be aware that read operations on text I/O objects285might raise 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> if the stream cannot perform the operation286immediately.</p>287</div>288<p>The text stream API is described in detail in the documentation of289<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>290</section>291<section id="binary-i-o">292<h3>Binary I/O<a class="headerlink" href="#binary-i-o" title="Link to this heading">¶</a></h3>293<p>Binary I/O (also called <em>buffered I/O</em>) expects294<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>295objects. No encoding, decoding, or newline translation is performed. This296category of streams can be used for all kinds of non-text data, and also when297manual control over the handling of text data is desired.</p>298<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> in299the mode string:</p>300<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>301</pre></div>302</div>303<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>304<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>305</pre></div>306</div>307<p>The binary stream API is described in detail in the docs of308<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>309<p>Other library modules may provide additional ways to create text or binary310streams. 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>311</section>312<section id="raw-i-o">313<h3>Raw I/O<a class="headerlink" href="#raw-i-o" title="Link to this heading">¶</a></h3>314<p>Raw I/O (also called <em>unbuffered I/O</em>) is generally used as a low-level315building-block for binary and text streams; it is rarely useful to directly316manipulate a raw stream from user code. Nevertheless, you can create a raw317stream by opening a file in binary mode with buffering disabled:</p>318<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>319</pre></div>320</div>321<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>322</section>323</section>324<section id="text-encoding">325<span id="io-text-encoding"></span><h2>Text Encoding<a class="headerlink" href="#text-encoding" title="Link to this heading">¶</a></h2>326<p>The default encoding 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> and <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> is327locale-specific (<a class="reference internal" href="locale.html#locale.getencoding" title="locale.getencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getencoding()</span></code></a>).</p>328<p>However, many developers forget to specify the encoding when opening text files329encoded in UTF-8 (e.g. JSON, TOML, Markdown, etc…) since most Unix330platforms use UTF-8 locale by default. This causes bugs because the locale331encoding is not UTF-8 for most Windows users. For example:</p>332<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># May not work on Windows when non-ASCII characters in the file.</span>333<span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"README.md"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>334 <span class="n">long_description</span> <span class="o">=</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>335</pre></div>336</div>337<p>Accordingly, it is highly recommended that you specify the encoding338explicitly when opening text files. If you want to use UTF-8, pass339<code class="docutils literal notranslate"><span class="pre">encoding="utf-8"</span></code>. To use the current locale encoding,340<code class="docutils literal notranslate"><span class="pre">encoding="locale"</span></code> is supported since Python 3.10.</p>341<div class="admonition seealso">342<p class="admonition-title">See also</p>343<dl class="simple">344<dt><a class="reference internal" href="os.html#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a></dt><dd><p>Python UTF-8 Mode can be used to change the default encoding to345UTF-8 from locale-specific encoding.</p>346</dd>347<dt><span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0686/"><strong>PEP 686</strong></a></dt><dd><p>Python 3.15 will make <a class="reference internal" href="os.html#utf8-mode"><span class="std std-ref">Python UTF-8 Mode</span></a> default.</p>348</dd>349</dl>350</div>351<section id="opt-in-encodingwarning">352<span id="io-encoding-warning"></span><h3>Opt-in EncodingWarning<a class="headerlink" href="#opt-in-encodingwarning" title="Link to this heading">¶</a></h3>353<div class="versionadded">354<p><span class="versionmodified added">Added in version 3.10: </span>See <span class="target" id="index-2"></span><a class="pep reference external" href="https://peps.python.org/pep-0597/"><strong>PEP 597</strong></a> for more details.</p>355</div>356<p>To find where the default locale encoding is used, you can enable357the <a class="reference internal" href="../using/cmdline.html#cmdoption-X"><code class="xref std std-option docutils literal notranslate"><span class="pre">-X</span> <span class="pre">warn_default_encoding</span></code></a> command line option or set the358<span class="target" id="index-3"></span><a class="reference internal" href="../using/cmdline.html#envvar-PYTHONWARNDEFAULTENCODING"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONWARNDEFAULTENCODING</span></code></a> environment variable, which will359emit an <a class="reference internal" href="exceptions.html#EncodingWarning" title="EncodingWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EncodingWarning</span></code></a> when the default encoding is used.</p>360<p>If you are providing an API that uses <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> or361<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> and passes <code class="docutils literal notranslate"><span class="pre">encoding=None</span></code> as a parameter, you362can use <a class="reference internal" href="#io.text_encoding" title="io.text_encoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">text_encoding()</span></code></a> so that callers of the API will emit an363<a class="reference internal" href="exceptions.html#EncodingWarning" title="EncodingWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EncodingWarning</span></code></a> if they don’t pass an <code class="docutils literal notranslate"><span class="pre">encoding</span></code>. However,364please consider using UTF-8 by default (i.e. <code class="docutils literal notranslate"><span class="pre">encoding="utf-8"</span></code>) for365new APIs.</p>366</section>367</section>368<section id="high-level-module-interface">369<h2>High-level Module Interface<a class="headerlink" href="#high-level-module-interface" title="Link to this heading">¶</a></h2>370<dl class="py data">371<dt class="sig sig-object py" id="io.DEFAULT_BUFFER_SIZE">372<span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">DEFAULT_BUFFER_SIZE</span></span><a class="headerlink" href="#io.DEFAULT_BUFFER_SIZE" title="Link to this definition">¶</a></dt>373<dd><p>An int containing the default buffer size used by the module’s buffered I/O374classes. <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 by375<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>376</dd></dl>377 378<dl class="py function">379<dt class="sig sig-object py" id="io.open">380<span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">open</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffering</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errors</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">newline</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">closefd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">opener</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.open" title="Link to this definition">¶</a></dt>381<dd><p>This is an alias for the builtin <code class="xref py py-func docutils literal notranslate"><span class="pre">open()</span></code> function.</p>382<p class="audit-hook"><p>This function raises an <a class="reference internal" href="sys.html#auditing"><span class="std std-ref">auditing event</span></a> <code class="docutils literal notranslate"><span class="pre">open</span></code> with383arguments <em>path</em>, <em>mode</em> and <em>flags</em>. The <em>mode</em> and <em>flags</em>384arguments may have been modified or inferred from the original call.</p>385</p>386</dd></dl>387 388<dl class="py function">389<dt class="sig sig-object py" id="io.open_code">390<span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">open_code</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">path</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.open_code" title="Link to this definition">¶</a></dt>391<dd><p>Opens the provided file with mode <code class="docutils literal notranslate"><span class="pre">'rb'</span></code>. This function should be used392when the intent is to treat the contents as executable code.</p>393<p><em>path</em> should be 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> and an absolute path.</p>394<p>The behavior of this function may be overridden by an earlier call to the395<a class="reference internal" href="../c-api/file.html#c.PyFile_SetOpenCodeHook" title="PyFile_SetOpenCodeHook"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_SetOpenCodeHook()</span></code></a>. However, assuming that <em>path</em> is a396<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> and an absolute path, <code class="docutils literal notranslate"><span class="pre">open_code(path)</span></code> should always behave397the same as <code class="docutils literal notranslate"><span class="pre">open(path,</span> <span class="pre">'rb')</span></code>. Overriding the behavior is intended for398additional validation or preprocessing of the file.</p>399<div class="versionadded">400<p><span class="versionmodified added">Added in version 3.8.</span></p>401</div>402</dd></dl>403 404<dl class="py function">405<dt class="sig sig-object py" id="io.text_encoding">406<span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">text_encoding</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">encoding</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">stacklevel</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">2</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.text_encoding" title="Link to this definition">¶</a></dt>407<dd><p>This is a helper function for callables that use <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> or408<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> and have an <code class="docutils literal notranslate"><span class="pre">encoding=None</span></code> parameter.</p>409<p>This function returns <em>encoding</em> if it is not <code class="docutils literal notranslate"><span class="pre">None</span></code>.410Otherwise, it returns <code class="docutils literal notranslate"><span class="pre">"locale"</span></code> or <code class="docutils literal notranslate"><span class="pre">"utf-8"</span></code> depending on411<a class="reference internal" href="os.html#utf8-mode"><span class="std std-ref">UTF-8 Mode</span></a>.</p>412<p>This function emits an <a class="reference internal" href="exceptions.html#EncodingWarning" title="EncodingWarning"><code class="xref py py-class docutils literal notranslate"><span class="pre">EncodingWarning</span></code></a> if413<a class="reference internal" href="sys.html#sys.flags" title="sys.flags"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.flags.warn_default_encoding</span></code></a> is true and <em>encoding</em>414is <code class="docutils literal notranslate"><span class="pre">None</span></code>. <em>stacklevel</em> specifies where the warning is emitted.415For example:</p>416<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">read_text</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="kc">None</span><span class="p">):</span>417 <span class="n">encoding</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">text_encoding</span><span class="p">(</span><span class="n">encoding</span><span class="p">)</span> <span class="c1"># stacklevel=2</span>418 <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">encoding</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span>419 <span class="k">return</span> <span class="n">f</span><span class="o">.</span><span class="n">read</span><span class="p">()</span>420</pre></div>421</div>422<p>In this example, an <a class="reference internal" href="exceptions.html#EncodingWarning" title="EncodingWarning"><code class="xref py py-class docutils literal notranslate"><span class="pre">EncodingWarning</span></code></a> is emitted for the caller of423<code class="docutils literal notranslate"><span class="pre">read_text()</span></code>.</p>424<p>See <a class="reference internal" href="#io-text-encoding"><span class="std std-ref">Text Encoding</span></a> for more information.</p>425<div class="versionadded">426<p><span class="versionmodified added">Added in version 3.10.</span></p>427</div>428<div class="versionchanged">429<p><span class="versionmodified changed">Changed in version 3.11: </span><code class="xref py py-func docutils literal notranslate"><span class="pre">text_encoding()</span></code> returns “utf-8” when UTF-8 mode is enabled and430<em>encoding</em> is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>431</div>432</dd></dl>433 434<dl class="py exception">435<dt class="sig sig-object py" id="io.BlockingIOError">436<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">BlockingIOError</span></span><a class="headerlink" href="#io.BlockingIOError" title="Link to this definition">¶</a></dt>437<dd><p>This is a compatibility alias for the builtin <code class="xref py py-exc docutils literal notranslate"><span class="pre">BlockingIOError</span></code>438exception.</p>439</dd></dl>440 441<dl class="py exception">442<dt class="sig sig-object py" id="io.UnsupportedOperation">443<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">UnsupportedOperation</span></span><a class="headerlink" href="#io.UnsupportedOperation" title="Link to this definition">¶</a></dt>444<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 raised445when an unsupported operation is called on a stream.</p>446</dd></dl>447 448<div class="admonition seealso">449<p class="admonition-title">See also</p>450<dl class="simple">451<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>,452and <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>453</dd>454</dl>455</div>456</section>457<section id="class-hierarchy">458<h2>Class hierarchy<a class="headerlink" href="#class-hierarchy" title="Link to this heading">¶</a></h2>459<p>The implementation of I/O streams is organized as a hierarchy of classes. First460<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 to461specify the various categories of streams, then concrete classes providing the462standard stream implementations.</p>463<div class="admonition note">464<p class="admonition-title">Note</p>465<p>The abstract base classes also provide default implementations of some466methods in order to help implementation of concrete stream classes. For467example, <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 of468<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">readline()</span></code>.</p>469</div>470<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>. It471defines the basic interface to a stream. Note, however, that there is no472separation between reading and writing to streams; implementations are allowed473to 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>474<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 reading475and 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 <code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code>476to provide an interface to files in the machine’s file system.</p>477<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 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 with478buffering on a raw binary 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,479<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>480buffer raw binary streams that are writable, readable, and both readable and writable,481respectively. <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 seekable streams.482Another <code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code> 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 of483in-memory bytes.</p>484<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 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 with485streams whose bytes represent text, and handles encoding and decoding to and486from 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 <code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code>, is a buffered text487interface 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,488<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>489<p>Argument names are not part of the specification, and only the arguments of490<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>491<p>The following table summarizes the ABCs provided by the <code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> module:</p>492<table class="docutils align-default">493<thead>494<tr class="row-odd"><th class="head"><p>ABC</p></th>495<th class="head"><p>Inherits</p></th>496<th class="head"><p>Stub Methods</p></th>497<th class="head"><p>Mixin Methods and Properties</p></th>498</tr>499</thead>500<tbody>501<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>502<td></td>503<td><p><code class="docutils literal notranslate"><span class="pre">fileno</span></code>, <code class="docutils literal notranslate"><span class="pre">seek</span></code>,504and <code class="docutils literal notranslate"><span class="pre">truncate</span></code></p></td>505<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>,506<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>,507<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>,508<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>,509<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>510</tr>511<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>512<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>513<td><p><code class="docutils literal notranslate"><span class="pre">readinto</span></code> and514<code class="docutils literal notranslate"><span class="pre">write</span></code></p></td>515<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>,516and <code class="docutils literal notranslate"><span class="pre">readall</span></code></p></td>517</tr>518<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>519<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>520<td><p><code class="docutils literal notranslate"><span class="pre">detach</span></code>, <code class="docutils literal notranslate"><span class="pre">read</span></code>,521<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>522<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>,523and <code class="docutils literal notranslate"><span class="pre">readinto1</span></code></p></td>524</tr>525<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>526<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>527<td><p><code class="docutils literal notranslate"><span class="pre">detach</span></code>, <code class="docutils literal notranslate"><span class="pre">read</span></code>,528<code class="docutils literal notranslate"><span class="pre">readline</span></code>, and529<code class="docutils literal notranslate"><span class="pre">write</span></code></p></td>530<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>,531<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>532</tr>533</tbody>534</table>535<section id="i-o-base-classes">536<h3>I/O Base Classes<a class="headerlink" href="#i-o-base-classes" title="Link to this heading">¶</a></h3>537<dl class="py class">538<dt class="sig sig-object py" id="io.IOBase">539<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">IOBase</span></span><a class="headerlink" href="#io.IOBase" title="Link to this definition">¶</a></dt>540<dd><p>The abstract base class for all I/O classes.</p>541<p>This class provides empty abstract implementations for many methods542that derived classes can override selectively; the default543implementations represent a file that cannot be read, written or544seeked.</p>545<p>Even though <code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code> does not declare <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code>546or <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> because their signatures will vary, implementations and547clients should consider those methods part of the interface. Also,548implementations 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>)549when operations they do not support are called.</p>550<p>The basic type used for binary data read from or written to a file is551<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> are552accepted 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>553<p>Note that calling any method (even inquiries) on a closed stream is554undefined. 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>555<p><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code> (and its subclasses) supports the iterator protocol, meaning556that an <code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code> object can be iterated over yielding the lines in a557stream. Lines are defined slightly differently depending on whether the558stream is a binary stream (yielding bytes), or a text stream (yielding559character 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>560<p><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code> is also a context manager and therefore supports the561<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 the562<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>563<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>564 <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>565</pre></div>566</div>567<p><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code> provides these data attributes and methods:</p>568<dl class="py method">569<dt class="sig sig-object py" id="io.IOBase.close">570<span class="sig-name descname"><span class="pre">close</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.close" title="Link to this definition">¶</a></dt>571<dd><p>Flush and close this stream. This method has no effect if the file is572already closed. Once the file is closed, any operation on the file573(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>574<p>As a convenience, it is allowed to call this method more than once;575only the first call, however, will have an effect.</p>576</dd></dl>577 578<dl class="py attribute">579<dt class="sig sig-object py" id="io.IOBase.closed">580<span class="sig-name descname"><span class="pre">closed</span></span><a class="headerlink" href="#io.IOBase.closed" title="Link to this definition">¶</a></dt>581<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the stream is closed.</p>582</dd></dl>583 584<dl class="py method">585<dt class="sig sig-object py" id="io.IOBase.fileno">586<span class="sig-name descname"><span class="pre">fileno</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.fileno" title="Link to this definition">¶</a></dt>587<dd><p>Return the underlying file descriptor (an integer) of the stream if it588exists. 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 file589descriptor.</p>590</dd></dl>591 592<dl class="py method">593<dt class="sig sig-object py" id="io.IOBase.flush">594<span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.flush" title="Link to this definition">¶</a></dt>595<dd><p>Flush the write buffers of the stream if applicable. This does nothing596for read-only and non-blocking streams.</p>597</dd></dl>598 599<dl class="py method">600<dt class="sig sig-object py" id="io.IOBase.isatty">601<span class="sig-name descname"><span class="pre">isatty</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.isatty" title="Link to this definition">¶</a></dt>602<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the stream is interactive (i.e., connected to603a terminal/tty device).</p>604</dd></dl>605 606<dl class="py method">607<dt class="sig sig-object py" id="io.IOBase.readable">608<span class="sig-name descname"><span class="pre">readable</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readable" title="Link to this definition">¶</a></dt>609<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if the stream can be read from.610If <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>611</dd></dl>612 613<dl class="py method">614<dt class="sig sig-object py" id="io.IOBase.readline">615<span class="sig-name descname"><span class="pre">readline</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readline" title="Link to this definition">¶</a></dt>616<dd><p>Read and return one line from the stream. If <em>size</em> is specified, at617most <em>size</em> bytes will be read.</p>618<p>The line terminator is always <code class="docutils literal notranslate"><span class="pre">b'\n'</span></code> for binary files; for text files,619the <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 line620terminator(s) recognized.</p>621</dd></dl>622 623<dl class="py method">624<dt class="sig sig-object py" id="io.IOBase.readlines">625<span class="sig-name descname"><span class="pre">readlines</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">hint</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readlines" title="Link to this definition">¶</a></dt>626<dd><p>Read and return a list of lines from the stream. <em>hint</em> can be specified627to control the number of lines read: no more lines will be read if the628total size (in bytes/characters) of all lines so far exceeds <em>hint</em>.</p>629<p><em>hint</em> values of <code class="docutils literal notranslate"><span class="pre">0</span></code> or less, as well as <code class="docutils literal notranslate"><span class="pre">None</span></code>, are treated as no630hint.</p>631<p>Note that it’s already possible to iterate on file objects using <code class="docutils literal notranslate"><span class="pre">for</span>632<span class="pre">line</span> <span class="pre">in</span> <span class="pre">file:</span> <span class="pre">...</span></code> without calling <code class="xref py py-meth docutils literal notranslate"><span class="pre">file.readlines()</span></code>.</p>633</dd></dl>634 635<dl class="py method">636<dt class="sig sig-object py" id="io.IOBase.seek">637<span class="sig-name descname"><span class="pre">seek</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">offset</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">whence</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">os.SEEK_SET</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.seek" title="Link to this definition">¶</a></dt>638<dd><p>Change the stream position to the given byte <em>offset</em>,639interpreted relative to the position indicated by <em>whence</em>,640and return the new absolute position.641Values for <em>whence</em> are:</p>642<ul class="simple">643<li><p><a class="reference internal" href="os.html#os.SEEK_SET" title="os.SEEK_SET"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_SET</span></code></a> or <code class="docutils literal notranslate"><span class="pre">0</span></code> – start of the stream (the default);644<em>offset</em> should be zero or positive</p></li>645<li><p><a class="reference internal" href="os.html#os.SEEK_CUR" title="os.SEEK_CUR"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_CUR</span></code></a> or <code class="docutils literal notranslate"><span class="pre">1</span></code> – current stream position;646<em>offset</em> may be negative</p></li>647<li><p><a class="reference internal" href="os.html#os.SEEK_END" title="os.SEEK_END"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_END</span></code></a> or <code class="docutils literal notranslate"><span class="pre">2</span></code> – end of the stream;648<em>offset</em> is usually negative</p></li>649</ul>650<div class="versionadded">651<p><span class="versionmodified added">Added in version 3.1: </span>The <code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_*</span></code> constants.</p>652</div>653<div class="versionadded">654<p><span class="versionmodified added">Added in version 3.3: </span>Some operating systems could support additional values, like655<a class="reference internal" href="os.html#os.SEEK_HOLE" title="os.SEEK_HOLE"><code class="xref py py-const docutils literal notranslate"><span class="pre">os.SEEK_HOLE</span></code></a> or <a class="reference internal" href="os.html#os.SEEK_DATA" title="os.SEEK_DATA"><code class="xref py py-const docutils literal notranslate"><span class="pre">os.SEEK_DATA</span></code></a>. The valid values656for a file could depend on it being open in text or binary mode.</p>657</div>658</dd></dl>659 660<dl class="py method">661<dt class="sig sig-object py" id="io.IOBase.seekable">662<span class="sig-name descname"><span class="pre">seekable</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.seekable" title="Link to this definition">¶</a></dt>663<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>,664<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>665</dd></dl>666 667<dl class="py method">668<dt class="sig sig-object py" id="io.IOBase.tell">669<span class="sig-name descname"><span class="pre">tell</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.tell" title="Link to this definition">¶</a></dt>670<dd><p>Return the current stream position.</p>671</dd></dl>672 673<dl class="py method">674<dt class="sig sig-object py" id="io.IOBase.truncate">675<span class="sig-name descname"><span class="pre">truncate</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.truncate" title="Link to this definition">¶</a></dt>676<dd><p>Resize the stream to the given <em>size</em> in bytes (or the current position677if <em>size</em> is not specified). The current stream position isn’t changed.678This resizing can extend or reduce the current file size. In case of679extension, the contents of the new file area depend on the platform680(on most systems, additional bytes are zero-filled). The new file size681is returned.</p>682<div class="versionchanged">683<p><span class="versionmodified changed">Changed in version 3.5: </span>Windows will now zero-fill files when extending.</p>684</div>685</dd></dl>686 687<dl class="py method">688<dt class="sig sig-object py" id="io.IOBase.writable">689<span class="sig-name descname"><span class="pre">writable</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.writable" title="Link to this definition">¶</a></dt>690<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>,691<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>692</dd></dl>693 694<dl class="py method">695<dt class="sig sig-object py" id="io.IOBase.writelines">696<span class="sig-name descname"><span class="pre">writelines</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">lines</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.writelines" title="Link to this definition">¶</a></dt>697<dd><p>Write a list of lines to the stream. Line separators are not added, so it698is usual for each of the lines provided to have a line separator at the699end.</p>700</dd></dl>701 702<dl class="py method">703<dt class="sig sig-object py" id="io.IOBase.__del__">704<span class="sig-name descname"><span class="pre">__del__</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.__del__" title="Link to this definition">¶</a></dt>705<dd><p>Prepare for object destruction. <code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code> provides a default706implementation of this method that calls the instance’s707<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>708</dd></dl>709 710</dd></dl>711 712<dl class="py class">713<dt class="sig sig-object py" id="io.RawIOBase">714<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">RawIOBase</span></span><a class="headerlink" href="#io.RawIOBase" title="Link to this definition">¶</a></dt>715<dd><p>Base class for raw binary streams. It inherits 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>716<p>Raw binary streams typically provide low-level access to an underlying OS717device or API, and do not try to encapsulate it in high-level primitives718(this functionality is done at a higher-level in buffered binary streams and text streams, described later719in this page).</p>720<p><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code> provides these methods in addition to those from721<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>722<dl class="py method">723<dt class="sig sig-object py" id="io.RawIOBase.read">724<span class="sig-name descname"><span class="pre">read</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.read" title="Link to this definition">¶</a></dt>725<dd><p>Read up to <em>size</em> bytes from the object and return them. As a convenience,726if <em>size</em> is unspecified or -1, all bytes until EOF are returned.727Otherwise, only one system call is ever made. Fewer than <em>size</em> bytes may728be returned if the operating system call returns fewer than <em>size</em> bytes.</p>729<p>If 0 bytes are returned, and <em>size</em> was not 0, this indicates end of file.730If the object is in non-blocking mode and no bytes are available,731<code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>732<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> and733<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>734</dd></dl>735 736<dl class="py method">737<dt class="sig sig-object py" id="io.RawIOBase.readall">738<span class="sig-name descname"><span class="pre">readall</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.readall" title="Link to this definition">¶</a></dt>739<dd><p>Read and return all the bytes from the stream until EOF, using multiple740calls to the stream if necessary.</p>741</dd></dl>742 743<dl class="py method">744<dt class="sig sig-object py" id="io.RawIOBase.readinto">745<span class="sig-name descname"><span class="pre">readinto</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.readinto" title="Link to this definition">¶</a></dt>746<dd><p>Read bytes into a pre-allocated, writable747<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 the748number 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>.749If the object is in non-blocking mode and no bytes750are available, <code class="docutils literal notranslate"><span class="pre">None</span></code> is returned.</p>751</dd></dl>752 753<dl class="py method">754<dt class="sig sig-object py" id="io.RawIOBase.write">755<span class="sig-name descname"><span class="pre">write</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.write" title="Link to this definition">¶</a></dt>756<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 the757underlying raw stream, and return the number of758bytes written. This can be less than the length of <em>b</em> in759bytes, depending on specifics of the underlying raw760stream, and especially if it is in non-blocking mode. <code class="docutils literal notranslate"><span class="pre">None</span></code> is761returned if the raw stream is set not to block and no single byte could762be readily written to it. The caller may release or mutate <em>b</em> after763this method returns, so the implementation should only access <em>b</em>764during the method call.</p>765</dd></dl>766 767</dd></dl>768 769<dl class="py class">770<dt class="sig sig-object py" id="io.BufferedIOBase">771<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">BufferedIOBase</span></span><a class="headerlink" href="#io.BufferedIOBase" title="Link to this definition">¶</a></dt>772<dd><p>Base class for binary streams that support some kind of buffering.773It inherits 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>774<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>,775<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 read776as much input as requested or to emit all provided data.</p>777<p>In addition, if the underlying raw stream is in non-blocking mode, when the778system returns would block <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 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>779with <a class="reference internal" href="exceptions.html#BlockingIOError.characters_written" title="BlockingIOError.characters_written"><code class="xref py py-attr docutils literal notranslate"><span class="pre">BlockingIOError.characters_written</span></code></a> and <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> will return780data read so far or <code class="docutils literal notranslate"><span class="pre">None</span></code> if no data is available.</p>781<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 default782implementation 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>783<p>A typical <code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code> implementation should not inherit from a784<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, like785<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>786<p><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code> provides or overrides these data attributes and787methods 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>788<dl class="py attribute">789<dt class="sig sig-object py" id="io.BufferedIOBase.raw">790<span class="sig-name descname"><span class="pre">raw</span></span><a class="headerlink" href="#io.BufferedIOBase.raw" title="Link to this definition">¶</a></dt>791<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) that792<code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code> deals with. This is not part of the793<code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code> API and may not exist on some implementations.</p>794</dd></dl>795 796<dl class="py method">797<dt class="sig sig-object py" id="io.BufferedIOBase.detach">798<span class="sig-name descname"><span class="pre">detach</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.detach" title="Link to this definition">¶</a></dt>799<dd><p>Separate the underlying raw stream from the buffer and return it.</p>800<p>After the raw stream has been detached, the buffer is in an unusable801state.</p>802<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 single803raw stream to return from this method. They raise804<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>805<div class="versionadded">806<p><span class="versionmodified added">Added in version 3.1.</span></p>807</div>808</dd></dl>809 810<dl class="py method">811<dt class="sig sig-object py" id="io.BufferedIOBase.read">812<span class="sig-name descname"><span class="pre">read</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.read" title="Link to this definition">¶</a></dt>813<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>,814or negative read as much as possible.</p>815<p>Fewer bytes may be returned than requested. 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> object816is returned if the stream is already at EOF. More than one read may be817made and calls may be retried if specific errors are encountered, see818<a class="reference internal" href="os.html#os.read" title="os.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">os.read()</span></code></a> and <span class="target" id="index-4"></span><a class="pep reference external" href="https://peps.python.org/pep-0475/"><strong>PEP 475</strong></a> for more details. Less than size bytes819being returned does not imply that EOF is imminent.</p>820<p>When reading as much as possible the default implementation will use821<code class="docutils literal notranslate"><span class="pre">raw.readall</span></code> if available (which should implement822<a class="reference internal" href="#io.RawIOBase.readall" title="io.RawIOBase.readall"><code class="xref py py-meth docutils literal notranslate"><span class="pre">RawIOBase.readall()</span></code></a>), otherwise will read in a loop until read823returns <code class="docutils literal notranslate"><span class="pre">None</span></code>, 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>, or a non-retryable error. For824most streams this is to EOF, but for non-blocking streams more data may825become available.</p>826<div class="admonition note">827<p class="admonition-title">Note</p>828<p>When the underlying raw stream is non-blocking, implementations may829either 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> or return <code class="docutils literal notranslate"><span class="pre">None</span></code> if no data is830available. <code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> implementations return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>831</div>832</dd></dl>833 834<dl class="py method">835<dt class="sig sig-object py" id="io.BufferedIOBase.read1">836<span class="sig-name descname"><span class="pre">read1</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.read1" title="Link to this definition">¶</a></dt>837<dd><p>Read and return up to <em>size</em> bytes, calling <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>838which may retry if <a class="reference internal" href="errno.html#errno.EINTR" title="errno.EINTR"><code class="xref py py-const docutils literal notranslate"><span class="pre">EINTR</span></code></a> is encountered per839<span class="target" id="index-5"></span><a class="pep reference external" href="https://peps.python.org/pep-0475/"><strong>PEP 475</strong></a>. If <em>size</em> is <code class="docutils literal notranslate"><span class="pre">-1</span></code> or not provided, the implementation will840choose an arbitrary value for <em>size</em>.</p>841<div class="admonition note">842<p class="admonition-title">Note</p>843<p>When the underlying raw stream is non-blocking, implementations may844either 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> or return <code class="docutils literal notranslate"><span class="pre">None</span></code> if no data is845available. <code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> implementations return <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>846</div>847</dd></dl>848 849<dl class="py method">850<dt class="sig sig-object py" id="io.BufferedIOBase.readinto">851<span class="sig-name descname"><span class="pre">readinto</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.readinto" title="Link to this definition">¶</a></dt>852<dd><p>Read bytes into a pre-allocated, writable853<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.854For 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>855<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 raw856stream, unless the latter is interactive.</p>857<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 non858blocking-mode, and has no data available at the moment.</p>859</dd></dl>860 861<dl class="py method">862<dt class="sig sig-object py" id="io.BufferedIOBase.readinto1">863<span class="sig-name descname"><span class="pre">readinto1</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.readinto1" title="Link to this definition">¶</a></dt>864<dd><p>Read bytes into a pre-allocated, writable865<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 to866the 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> (or867<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>868<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 non869blocking-mode, and has no data available at the moment.</p>870<div class="versionadded">871<p><span class="versionmodified added">Added in version 3.5.</span></p>872</div>873</dd></dl>874 875<dl class="py method">876<dt class="sig sig-object py" id="io.BufferedIOBase.write">877<span class="sig-name descname"><span class="pre">write</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.write" title="Link to this definition">¶</a></dt>878<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 number879of bytes written (always equal to the length of <em>b</em> in bytes, since if880the 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 the881actual implementation, these bytes may be readily written to the882underlying stream, or held in a buffer for performance and latency883reasons.</p>884<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 the885data needed to be written to the raw stream but it couldn’t accept886all the data without blocking.</p>887<p>The caller may release or mutate <em>b</em> after this method returns,888so the implementation should only access <em>b</em> during the method call.</p>889</dd></dl>890 891</dd></dl>892 893</section>894<section id="raw-file-i-o">895<h3>Raw File I/O<a class="headerlink" href="#raw-file-i-o" title="Link to this heading">¶</a></h3>896<dl class="py class">897<dt class="sig sig-object py" id="io.FileIO">898<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">FileIO</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mode</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'r'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">closefd</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">opener</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.FileIO" title="Link to this definition">¶</a></dt>899<dd><p>A raw binary stream representing an OS-level file containing bytes data. It900inherits from <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>901<p>The <em>name</em> can be one of two things:</p>902<ul class="simple">903<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 the904file which will be opened. In this case closefd must be <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default)905otherwise an error will be raised.</p></li>906<li><p>an integer representing the number of an existing OS-level file descriptor907to which the resulting <code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code> object will give access. When the908FileIO object is closed this fd will be closed as well, unless <em>closefd</em>909is set to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p></li>910</ul>911<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 reading912(default), writing, exclusive creation or appending. The file will be913created if it doesn’t exist when opened for writing or appending; it will be914truncated 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 if915it already exists when opened for creating. Opening a file for creating916implies writing, so this mode behaves in a similar way to <code class="docutils literal notranslate"><span class="pre">'w'</span></code>. Add a917<code class="docutils literal notranslate"><span class="pre">'+'</span></code> to the mode to allow simultaneous reading and writing.</p>918<p>The <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> (when called with a positive argument),919<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> and <a class="reference internal" href="#io.RawIOBase.write" title="io.RawIOBase.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> methods on this920class will only make one system call.</p>921<p>A custom opener can be used by passing a callable as <em>opener</em>. The underlying922file descriptor for the file object is then obtained by calling <em>opener</em> with923(<em>name</em>, <em>flags</em>). <em>opener</em> must return an open file descriptor (passing924<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 passing925<code class="docutils literal notranslate"><span class="pre">None</span></code>).</p>926<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>927<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>928parameter.</p>929<div class="versionchanged">930<p><span class="versionmodified changed">Changed in version 3.3: </span>The <em>opener</em> parameter was added.931The <code class="docutils literal notranslate"><span class="pre">'x'</span></code> mode was added.</p>932</div>933<div class="versionchanged">934<p><span class="versionmodified changed">Changed in version 3.4: </span>The file is now non-inheritable.</p>935</div>936<p><code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code> provides these data attributes in addition to those from937<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> 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>938<dl class="py attribute">939<dt class="sig sig-object py" id="io.FileIO.mode">940<span class="sig-name descname"><span class="pre">mode</span></span><a class="headerlink" href="#io.FileIO.mode" title="Link to this definition">¶</a></dt>941<dd><p>The mode as given in the constructor.</p>942</dd></dl>943 944<dl class="py attribute">945<dt class="sig sig-object py" id="io.FileIO.name">946<span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#io.FileIO.name" title="Link to this definition">¶</a></dt>947<dd><p>The file name. This is the file descriptor of the file when no name is948given in the constructor.</p>949</dd></dl>950 951</dd></dl>952 953</section>954<section id="buffered-streams">955<h3>Buffered Streams<a class="headerlink" href="#buffered-streams" title="Link to this heading">¶</a></h3>956<p>Buffered I/O streams provide a higher-level interface to an I/O device957than raw I/O does.</p>958<dl class="py class">959<dt class="sig sig-object py" id="io.BytesIO">960<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">BytesIO</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">initial_bytes</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">b''</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO" title="Link to this definition">¶</a></dt>961<dd><p>A binary stream using an in-memory bytes buffer. It inherits from962<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 the963<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>964<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> that965contains initial data.</p>966<p>Methods may be used from multiple threads without external locking in967<a class="reference internal" href="../glossary.html#term-free-threaded-build"><span class="xref std std-term">free-threaded builds</span></a>.</p>968<p><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code> provides or overrides these methods in addition to those969from <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>970<dl class="py method">971<dt class="sig sig-object py" id="io.BytesIO.getbuffer">972<span class="sig-name descname"><span class="pre">getbuffer</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.getbuffer" title="Link to this definition">¶</a></dt>973<dd><p>Return a readable and writable view over the contents of the buffer974without copying them. Also, mutating the view will transparently975update the contents of the buffer:</p>976<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>977<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>978<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>979<span class="gp">>>> </span><span class="n">b</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>980<span class="go">b'ab56ef'</span>981</pre></div>982</div>983<div class="admonition note">984<p class="admonition-title">Note</p>985<p>As long as the view exists, the <code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code> object cannot be986resized or closed.</p>987</div>988<div class="versionadded">989<p><span class="versionmodified added">Added in version 3.2.</span></p>990</div>991</dd></dl>992 993<dl class="py method">994<dt class="sig sig-object py" id="io.BytesIO.getvalue">995<span class="sig-name descname"><span class="pre">getvalue</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.getvalue" title="Link to this definition">¶</a></dt>996<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>997</dd></dl>998 999<dl class="py method">1000<dt class="sig sig-object py" id="io.BytesIO.read1">1001<span class="sig-name descname"><span class="pre">read1</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.read1" title="Link to this definition">¶</a></dt>1002<dd><p>In <code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code>, 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>1003<div class="versionchanged">1004<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>size</em> argument is now optional.</p>1005</div>1006</dd></dl>1007 1008<dl class="py method">1009<dt class="sig sig-object py" id="io.BytesIO.readinto1">1010<span class="sig-name descname"><span class="pre">readinto1</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.readinto1" title="Link to this definition">¶</a></dt>1011<dd><p>In <code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code>, 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>1012<div class="versionadded">1013<p><span class="versionmodified added">Added in version 3.5.</span></p>1014</div>1015</dd></dl>1016 1017</dd></dl>1018 1019<dl class="py class">1020<dt class="sig sig-object py" id="io.BufferedReader">1021<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">BufferedReader</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">raw</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffer_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT_BUFFER_SIZE</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader" title="Link to this definition">¶</a></dt>1022<dd><p>A buffered binary stream providing higher-level access to a readable, non1023seekable <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> raw binary stream. It inherits from1024<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>1025<p>When reading data from this object, a larger amount of data may be1026requested from the underlying raw stream, and kept in an internal buffer.1027The buffered data can then be returned directly on subsequent reads.</p>1028<p>The constructor creates a <code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code> for the given readable1029<em>raw</em> stream and <em>buffer_size</em>. If <em>buffer_size</em> is omitted,1030<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>1031<p><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code> provides or overrides these methods in addition to1032those 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>1033<dl class="py method">1034<dt class="sig sig-object py" id="io.BufferedReader.peek">1035<span class="sig-name descname"><span class="pre">peek</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.peek" title="Link to this definition">¶</a></dt>1036<dd><p>Return bytes from the stream without advancing the position. The number of1037bytes returned may be less or more than requested. If the underlying raw1038stream is non-blocking and the operation would block, returns empty bytes.</p>1039</dd></dl>1040 1041<dl class="py method">1042<dt class="sig sig-object py" id="io.BufferedReader.read">1043<span class="sig-name descname"><span class="pre">read</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.read" title="Link to this definition">¶</a></dt>1044<dd><p>In <code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code> 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">io.BufferedIOBase.read()</span></code></a></p>1045</dd></dl>1046 1047<dl class="py method">1048<dt class="sig sig-object py" id="io.BufferedReader.read1">1049<span class="sig-name descname"><span class="pre">read1</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.read1" title="Link to this definition">¶</a></dt>1050<dd><p>In <code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code> this is the same as <a class="reference internal" href="#io.BufferedIOBase.read1" title="io.BufferedIOBase.read1"><code class="xref py py-meth docutils literal notranslate"><span class="pre">io.BufferedIOBase.read1()</span></code></a></p>1051<div class="versionchanged">1052<p><span class="versionmodified changed">Changed in version 3.7: </span>The <em>size</em> argument is now optional.</p>1053</div>1054</dd></dl>1055 1056</dd></dl>1057 1058<dl class="py class">1059<dt class="sig sig-object py" id="io.BufferedWriter">1060<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">BufferedWriter</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">raw</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffer_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT_BUFFER_SIZE</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter" title="Link to this definition">¶</a></dt>1061<dd><p>A buffered binary stream providing higher-level access to a writeable, non1062seekable <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> raw binary stream. It inherits from1063<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>1064<p>When writing to this object, data is normally placed into an internal1065buffer. 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>1066object under various conditions, including:</p>1067<ul class="simple">1068<li><p>when the buffer gets too small for all pending data;</p></li>1069<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>1070<li><p>when a <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> 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>1071<li><p>when the <code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code> object is closed or destroyed.</p></li>1072</ul>1073<p>The constructor creates a <code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code> for the given writeable1074<em>raw</em> stream. If the <em>buffer_size</em> is not given, it defaults to1075<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>1076<p><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code> provides or overrides these methods in addition to1077those 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>1078<dl class="py method">1079<dt class="sig sig-object py" id="io.BufferedWriter.flush">1080<span class="sig-name descname"><span class="pre">flush</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter.flush" title="Link to this definition">¶</a></dt>1081<dd><p>Force bytes held in the buffer into the raw stream. A1082<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>1083</dd></dl>1084 1085<dl class="py method">1086<dt class="sig sig-object py" id="io.BufferedWriter.write">1087<span class="sig-name descname"><span class="pre">write</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">b</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter.write" title="Link to this definition">¶</a></dt>1088<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 the1089number of bytes written. When in non-blocking mode, a1090<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> with <a class="reference internal" href="exceptions.html#BlockingIOError.characters_written" title="BlockingIOError.characters_written"><code class="xref py py-attr docutils literal notranslate"><span class="pre">BlockingIOError.characters_written</span></code></a> set1091is raised if the buffer needs to be written out but the raw stream blocks.</p>1092</dd></dl>1093 1094</dd></dl>1095 1096<dl class="py class">1097<dt class="sig sig-object py" id="io.BufferedRandom">1098<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">BufferedRandom</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">raw</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffer_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT_BUFFER_SIZE</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedRandom" title="Link to this definition">¶</a></dt>1099<dd><p>A buffered binary stream providing higher-level access to a seekable1100<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> raw binary stream. It inherits from <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>1101and <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>.</p>1102<p>The constructor creates a reader and writer for a seekable raw stream, given1103in the first argument. If the <em>buffer_size</em> is omitted it defaults to1104<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>1105<p><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code> 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> or1106<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. In addition, <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> and1107<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> are guaranteed to be implemented.</p>1108</dd></dl>1109 1110<dl class="py class">1111<dt class="sig sig-object py" id="io.BufferedRWPair">1112<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">BufferedRWPair</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">reader</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">writer</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">buffer_size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DEFAULT_BUFFER_SIZE</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedRWPair" title="Link to this definition">¶</a></dt>1113<dd><p>A buffered binary stream providing higher-level access to two non seekable1114<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> raw binary streams—one readable, the other writeable.1115It inherits 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>.</p>1116<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 and1117writeable respectively. If the <em>buffer_size</em> is omitted it defaults to1118<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>1119<p><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code> 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 methods1120except 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 raises1121<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>1122<div class="admonition warning">1123<p class="admonition-title">Warning</p>1124<p><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code> does not attempt to synchronize accesses to1125its underlying raw streams. You should not pass it the same object1126as 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>1127</div>1128</dd></dl>1129 1130</section>1131<section id="id1">1132<h3>Text I/O<a class="headerlink" href="#id1" title="Link to this heading">¶</a></h3>1133<dl class="py class">1134<dt class="sig sig-object py" id="io.TextIOBase">1135<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">io.</span></span><span class="sig-name descname"><span class="pre">TextIOBase</span></span><a class="headerlink" href="#io.TextIOBase" title="Link to this definition">¶</a></dt>1136<dd><p>Base class for text streams. This class provides a character and line based1137interface to stream I/O. It inherits 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>1138<p><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code> provides or overrides these data attributes and1139methods 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>1140<dl class="py attribute">1141<dt class="sig sig-object py" id="io.TextIOBase.encoding">1142<span class="sig-name descname"><span class="pre">encoding</span></span><a class="headerlink" href="#io.TextIOBase.encoding" title="Link to this definition">¶</a></dt>1143<dd><p>The name of the encoding used to decode the stream’s bytes into1144strings, and to encode strings into bytes.</p>1145</dd></dl>1146 1147<dl class="py attribute">1148<dt class="sig sig-object py" id="io.TextIOBase.errors">1149<span class="sig-name descname"><span class="pre">errors</span></span><a class="headerlink" href="#io.TextIOBase.errors" title="Link to this definition">¶</a></dt>1150<dd><p>The error setting of the decoder or encoder.</p>1151</dd></dl>1152 1153<dl class="py attribute">1154<dt class="sig sig-object py" id="io.TextIOBase.newlines">1155<span class="sig-name descname"><span class="pre">newlines</span></span><a class="headerlink" href="#io.TextIOBase.newlines" title="Link to this definition">¶</a></dt>1156<dd><p>A string, a tuple of strings, or <code class="docutils literal notranslate"><span class="pre">None</span></code>, indicating the newlines1157translated so far. Depending on the implementation and the initial1158constructor flags, this may not be available.</p>1159</dd></dl>1160 1161<dl class="py attribute">1162<dt class="sig sig-object py" id="io.TextIOBase.buffer">1163<span class="sig-name descname"><span class="pre">buffer</span></span><a class="headerlink" href="#io.TextIOBase.buffer" title="Link to this definition">¶</a></dt>1164<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>1165or <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 <code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code> deals with.1166This is not part of the <code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code> API and may not exist1167in some implementations.</p>1168</dd></dl>1169 1170<dl class="py method">1171<dt class="sig sig-object py" id="io.TextIOBase.detach">1172<span class="sig-name descname"><span class="pre">detach</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.detach" title="Link to this definition">¶</a></dt>1173<dd><p>Separate the underlying binary buffer from the <code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code> and1174return it.</p>1175<p>After the underlying buffer has been detached, the <code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code> is1176in an unusable state.</p>1177<p>Some <code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code> 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 not1178have the concept of an underlying buffer and calling this method will1179raise <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>1180<div class="versionadded">1181<p><span class="versionmodified added">Added in version 3.1.</span></p>1182</div>1183</dd></dl>1184 1185<dl class="py method">1186<dt class="sig sig-object py" id="io.TextIOBase.read">1187<span class="sig-name descname"><span class="pre">read</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.read" title="Link to this definition">¶</a></dt>1188<dd><p>Read and return at most <em>size</em> characters from the stream as a single1189<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>1190</dd></dl>1191 1192<dl class="py method">1193<dt class="sig sig-object py" id="io.TextIOBase.readline">1194<span class="sig-name descname"><span class="pre">readline</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">-1</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.readline" title="Link to this definition">¶</a></dt>1195<dd><p>Read until newline or EOF and return 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 the stream is1196already at EOF, an empty string is returned.</p>1197<p>If <em>size</em> is specified, at most <em>size</em> characters will be read.</p>1198</dd></dl>1199 1200<dl class="py method">