1050 lines
126 KiB
HTML
1050 lines
126 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>io --- 处理流的核心工具 — Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script src="../_static/translations.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="在 Python 3.8.20 文档 中搜索"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="关于这些文档" href="../about.html" />
|
||
<link rel="index" title="索引" href="../genindex.html" />
|
||
<link rel="search" title="搜索" href="../search.html" />
|
||
<link rel="copyright" title="版权所有" href="../copyright.html" />
|
||
<link rel="next" title="time --- 时间的访问和转换" href="time.html" />
|
||
<link rel="prev" title="os --- 多种操作系统接口" href="os.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/io.html" />
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<nav class="nav-content" role="navigation">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Logo"/>
|
||
</a>
|
||
<div class="version_switcher_placeholder"></div>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero"
|
||
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" fill="#444"></path>
|
||
</svg>
|
||
<input type="text" name="q" aria-label="快速搜索"/>
|
||
<input type="submit" value="转向"/>
|
||
</form>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> --- 处理流的核心工具</a><ul>
|
||
<li><a class="reference internal" href="#overview">概述</a><ul>
|
||
<li><a class="reference internal" href="#text-i-o">文本 I/O</a></li>
|
||
<li><a class="reference internal" href="#binary-i-o">二进制 I/O</a></li>
|
||
<li><a class="reference internal" href="#raw-i-o">原始 I/O</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#high-level-module-interface">高阶模块接口</a></li>
|
||
<li><a class="reference internal" href="#class-hierarchy">类的层次结构</a><ul>
|
||
<li><a class="reference internal" href="#i-o-base-classes">I/O 基类</a></li>
|
||
<li><a class="reference internal" href="#raw-file-i-o">原始文件 I/O</a></li>
|
||
<li><a class="reference internal" href="#buffered-streams">缓冲流</a></li>
|
||
<li><a class="reference internal" href="#id1">文本 I/O</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#performance">性能</a><ul>
|
||
<li><a class="reference internal" href="#id2">二进制 I/O</a></li>
|
||
<li><a class="reference internal" href="#id3">文本 I/O</a></li>
|
||
<li><a class="reference internal" href="#multi-threading">多线程</a></li>
|
||
<li><a class="reference internal" href="#reentrancy">可重入性</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="os.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code> --- 多种操作系统接口</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="time.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">time</span></code> --- 时间的访问和转换</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/io.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
|
||
这个文档所针对的是一个已不再受支持的 Python 旧版本。
|
||
你应当升级版本，并阅读
|
||
<a href="/3/library/io.html"> Python 当前稳定版本的文档</a>.
|
||
</div>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
accesskey="I">索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="time.html" title="time --- 时间的访问和转换"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="os.html" title="os --- 多种操作系统接口"
|
||
accesskey="P">上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" accesskey="U">通用操作系统服务</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-io">
|
||
<span id="io-core-tools-for-working-with-streams"></span><h1><a class="reference internal" href="#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code></a> --- 处理流的核心工具<a class="headerlink" href="#module-io" title="永久链接至标题">¶</a></h1>
|
||
<p><strong>源代码:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/io.py">Lib/io.py</a></p>
|
||
<hr class="docutils" />
|
||
<section id="overview">
|
||
<span id="io-overview"></span><h2>概述<a class="headerlink" href="#overview" title="永久链接至标题">¶</a></h2>
|
||
<p id="index-0"><a class="reference internal" href="#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code></a> 模块提供了 Python 用于处理各种 I/O 类型的主要工具。三种主要的 I/O类型分别为: <em>文本 I/O</em>, <em>二进制 I/O</em> 和 <em>原始 I/O</em>。这些是泛型类型，有很多种后端存储可以用在他们上面。一个隶属于任何这些类型的具体对象被称作 <a class="reference internal" href="../glossary.html#term-file-object"><span class="xref std std-term">file object</span></a>。 其他同类的术语还有 <em>流</em> 和 <em>类文件对象</em>。</p>
|
||
<p>独立于其类别，每个具体流对象也将具有各种功能：它可以是只读，只写或读写。它还可以允许任意随机访问（向前或向后寻找任何位置），或仅允许顺序访问（例如在套接字或管道的情况下）。</p>
|
||
<p>所有流对提供给它们的数据类型都很敏感。例如将 <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> 对象给二进制流的 <code class="docutils literal notranslate"><span class="pre">write()</span></code> 方法会引发 <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>。将 <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> 对象提供给文本流的 <code class="docutils literal notranslate"><span class="pre">write()</span></code> 方法也是如此。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>由于 <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> 现在是 <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> 的别名，因此用于引发 <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> 的操作现在会引发 <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> 。</p>
|
||
</div>
|
||
<section id="text-i-o">
|
||
<h3>文本 I/O<a class="headerlink" href="#text-i-o" title="永久链接至标题">¶</a></h3>
|
||
<p>文本I/O预期并生成 <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> 对象。这意味着，无论何时后台存储是由字节组成的（例如在文件的情况下），数据的编码和解码都是透明的，并且可以选择转换特定于平台的换行符。</p>
|
||
<p>创建文本流的最简单方法是使用 <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>，可以选择指定编码：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile.txt"</span><span class="p">,</span> <span class="s2">"r"</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s2">"utf-8"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>内存中文本流也可以作为 <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> 对象使用：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">StringIO</span><span class="p">(</span><span class="s2">"some initial text data"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> 的文档中详细描述了文本流的API</p>
|
||
</section>
|
||
<section id="binary-i-o">
|
||
<h3>二进制 I/O<a class="headerlink" href="#binary-i-o" title="永久链接至标题">¶</a></h3>
|
||
<p>二进制I/O（也称为缓冲I/O）预期 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></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> 对象。不执行编码、解码或换行转换。这种类型的流可以用于所有类型的非文本数据，并且还可以在需要手动控制文本数据的处理时使用。</p>
|
||
<p>创建二进制流的最简单方法是使用 <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>，并在模式字符串中指定 <code class="docutils literal notranslate"><span class="pre">'b'</span></code> ：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile.jpg"</span><span class="p">,</span> <span class="s2">"rb"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>内存中二进制流也可以作为 <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> 对象使用：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">BytesIO</span><span class="p">(</span><span class="sa">b</span><span class="s2">"some initial binary data: </span><span class="se">\x00\x01</span><span class="s2">"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> 的文档中详细描述了二进制流 API。</p>
|
||
<p>其他库模块可以提供额外的方式来创建文本或二进制流。参见 <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> 的示例。</p>
|
||
</section>
|
||
<section id="raw-i-o">
|
||
<h3>原始 I/O<a class="headerlink" href="#raw-i-o" title="永久链接至标题">¶</a></h3>
|
||
<p>原始 I/O（也称为 <em>非缓冲 I/O</em>）通常用作二进制和文本流的低级构建块。用户代码直接操作原始流的用法非常罕见。不过，可以通过在禁用缓冲的情况下以二进制模式打开文件来创建原始流：</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">f</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s2">"myfile.jpg"</span><span class="p">,</span> <span class="s2">"rb"</span><span class="p">,</span> <span class="n">buffering</span><span class="o">=</span><span class="mi">0</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><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> 的文档中详细描述了原始流的API</p>
|
||
</section>
|
||
</section>
|
||
<section id="high-level-module-interface">
|
||
<h2>高阶模块接口<a class="headerlink" href="#high-level-module-interface" title="永久链接至标题">¶</a></h2>
|
||
<dl class="data">
|
||
<dt id="io.DEFAULT_BUFFER_SIZE">
|
||
<code class="sig-prename descclassname">io.</code><code class="sig-name descname">DEFAULT_BUFFER_SIZE</code><a class="headerlink" href="#io.DEFAULT_BUFFER_SIZE" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>包含模块缓冲 I/O 类使用的默认缓冲区大小的 int。 在可能的情况下 <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> 将使用文件的 blksize（由 <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> 获得）。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="io.open">
|
||
<code class="sig-prename descclassname">io.</code><code class="sig-name descname">open</code><span class="sig-paren">(</span><em class="sig-param">file</em>, <em class="sig-param">mode='r'</em>, <em class="sig-param">buffering=-1</em>, <em class="sig-param">encoding=None</em>, <em class="sig-param">errors=None</em>, <em class="sig-param">newline=None</em>, <em class="sig-param">closefd=True</em>, <em class="sig-param">opener=None</em><span class="sig-paren">)</span><a class="headerlink" href="#io.open" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>这是内置的 <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> 函数的别名。</p>
|
||
<p class="audit-hook">引发一个 <a class="reference internal" href="sys.html#auditing"><span class="std std-ref">审计事件</span></a> <code class="docutils literal notranslate"><span class="pre">open</span></code> 并附带参数 <code class="docutils literal notranslate"><span class="pre">path</span></code>, <code class="docutils literal notranslate"><span class="pre">mode</span></code>, <code class="docutils literal notranslate"><span class="pre">flags</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="io.open_code">
|
||
<code class="sig-prename descclassname">io.</code><code class="sig-name descname">open_code</code><span class="sig-paren">(</span><em class="sig-param">path</em><span class="sig-paren">)</span><a class="headerlink" href="#io.open_code" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>以 <code class="docutils literal notranslate"><span class="pre">'rb'</span></code> 模式打开提供的文件。如果目的是将文件内容做为可执行代码，则应使用此函数。</p>
|
||
<p><code class="docutils literal notranslate"><span class="pre">path</span></code> 应当为 <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> 类型并且是一个绝对路径。</p>
|
||
<p>此函数的行为可以由对 <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> 的先期调用所重载。 但是，如果 <code class="docutils literal notranslate"><span class="pre">path</span></code> 为 <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> 类型并且是一个绝对路径，<code class="docutils literal notranslate"><span class="pre">open_code(path)</span></code> 的行为应当总是与 <code class="docutils literal notranslate"><span class="pre">open(path,</span> <span class="pre">'rb')</span></code> 一致。 重载此行为的目的是为了给文件附加额外的验证或预处理。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.8 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="io.BlockingIOError">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">BlockingIOError</code><a class="headerlink" href="#io.BlockingIOError" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>这是内置的 <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> 异常的兼容性别名。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="io.UnsupportedOperation">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">UnsupportedOperation</code><a class="headerlink" href="#io.UnsupportedOperation" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在流上调用不支持的操作时引发的继承 <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> 和 <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>
|
||
</dd></dl>
|
||
|
||
<div class="admonition seealso">
|
||
<p class="admonition-title">参见</p>
|
||
<dl class="simple">
|
||
<dt><a class="reference internal" href="sys.html#module-sys" title="sys: Access system-specific parameters and functions."><code class="xref py py-mod docutils literal notranslate"><span class="pre">sys</span></code></a></dt><dd><p>包含标准IO流: <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> 和 <a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a> 。</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</section>
|
||
<section id="class-hierarchy">
|
||
<h2>类的层次结构<a class="headerlink" href="#class-hierarchy" title="永久链接至标题">¶</a></h2>
|
||
<p>I/O 流被安排为按类的层次结构实现。 首先是 <a class="reference internal" href="../glossary.html#term-abstract-base-class"><span class="xref std std-term">抽象基类</span></a> (ABC)，用于指定流的各种类别，然后是提供标准流实现的具体类。</p>
|
||
<blockquote>
|
||
<div><div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>抽象基类还提供某些方法的默认实现，以帮助实现具体的流类。例如 <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> 提供了 <code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code> 和 <a class="reference internal" href="#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> 的未优化实现。</p>
|
||
</div>
|
||
</div></blockquote>
|
||
<p>I/O层次结构的顶部是抽象基类 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 。它定义了流的基本接口。但是请注意，对流的读取和写入之间没有分离。如果实现不支持指定的操作，则会引发 <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a> 。</p>
|
||
<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> 是 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 的子类。它负责将字节读取和写入流中。 <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> 的子类 <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> 提供计算机文件系统中文件的接口。</p>
|
||
<p>抽象基类 <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> 处理原始字节流（ <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> ）上的缓冲。其子类 <a class="reference internal" href="#io.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> 和 <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> 缓冲流是可读、可写以及可读写的。 <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> 为随机访问流提供缓冲接口。 <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> 的另一个子类 <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> 是内存中字节流。</p>
|
||
<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> 是 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 的另一个子类，它处理字节表示文本的流，并处理字符串之间的编码和解码。其一个子类 <a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOWrapper</span></code></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> ）的缓冲文本接口。另一个子类 <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> 用于文本的内存流。</p>
|
||
<p>参数名不是规范的一部分，只有 <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> 的参数才用作关键字参数。</p>
|
||
<p>下表总结了抽象基类提供的 <a class="reference internal" href="#module-io" title="io: Core tools for working with streams."><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code></a> 模块：</p>
|
||
<table class="docutils align-default">
|
||
<colgroup>
|
||
<col style="width: 21%" />
|
||
<col style="width: 15%" />
|
||
<col style="width: 21%" />
|
||
<col style="width: 43%" />
|
||
</colgroup>
|
||
<thead>
|
||
<tr class="row-odd"><th class="head"><p>抽象基类</p></th>
|
||
<th class="head"><p>继承</p></th>
|
||
<th class="head"><p>抽象方法</p></th>
|
||
<th class="head"><p>Mixin方法和属性</p></th>
|
||
</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a></p></td>
|
||
<td></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">fileno</span></code>, <code class="docutils literal notranslate"><span class="pre">seek</span></code>, 和 <code class="docutils literal notranslate"><span class="pre">truncate</span></code></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">close</span></code>, <code class="docutils literal notranslate"><span class="pre">closed</span></code>, <code class="docutils literal notranslate"><span class="pre">__enter__</span></code>, <code class="docutils literal notranslate"><span class="pre">__exit__</span></code>, <code class="docutils literal notranslate"><span class="pre">flush</span></code>, <code class="docutils literal notranslate"><span class="pre">isatty</span></code>, <code class="docutils literal notranslate"><span class="pre">__iter__</span></code>, <code class="docutils literal notranslate"><span class="pre">__next__</span></code>, <code class="docutils literal notranslate"><span class="pre">readable</span></code>, <code class="docutils literal notranslate"><span class="pre">readline</span></code>, <code class="docutils literal notranslate"><span class="pre">readlines</span></code>, <code class="docutils literal notranslate"><span class="pre">seekable</span></code>, <code class="docutils literal notranslate"><span class="pre">tell</span></code>, <code class="docutils literal notranslate"><span class="pre">writable</span></code> 和 <code class="docutils literal notranslate"><span class="pre">writelines</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a></p></td>
|
||
<td><p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">readinto</span></code> 和 <code class="docutils literal notranslate"><span class="pre">write</span></code></p></td>
|
||
<td><p>继承 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 方法, <code class="docutils literal notranslate"><span class="pre">read</span></code>, 和 <code class="docutils literal notranslate"><span class="pre">readall</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-even"><td><p><a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a></p></td>
|
||
<td><p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">detach</span></code>, <code class="docutils literal notranslate"><span class="pre">read</span></code>, <code class="docutils literal notranslate"><span class="pre">read1</span></code>, 和 <code class="docutils literal notranslate"><span class="pre">write</span></code></p></td>
|
||
<td><p>继承 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 方法, <code class="docutils literal notranslate"><span class="pre">readinto</span></code>, 和 <code class="docutils literal notranslate"><span class="pre">readinto1</span></code></p></td>
|
||
</tr>
|
||
<tr class="row-odd"><td><p><a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a></p></td>
|
||
<td><p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a></p></td>
|
||
<td><p><code class="docutils literal notranslate"><span class="pre">detach</span></code>, <code class="docutils literal notranslate"><span class="pre">read</span></code>, <code class="docutils literal notranslate"><span class="pre">readline</span></code>, 和 <code class="docutils literal notranslate"><span class="pre">write</span></code></p></td>
|
||
<td><p>继承 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 方法, <code class="docutils literal notranslate"><span class="pre">encoding</span></code>, <code class="docutils literal notranslate"><span class="pre">errors</span></code>, 和 <code class="docutils literal notranslate"><span class="pre">newlines</span></code></p></td>
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
<section id="i-o-base-classes">
|
||
<h3>I/O 基类<a class="headerlink" href="#i-o-base-classes" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="io.IOBase">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">IOBase</code><a class="headerlink" href="#io.IOBase" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>所有 I/O 类的抽象基类，作用于字节流。没有公共构造函数。</p>
|
||
<p>此类为许多方法提供了空的抽象实现，派生类可以有选择地重写。默认实现代表一个无法读取、写入或查找的文件。</p>
|
||
<p>尽管 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 没有声明 <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> 或 <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> ，因为它们的签名会有所不同，但是实现和客户端应该将这些方法视为接口的一部分。此外，当调用不支持的操作时可能会引发 <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> （或 <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>
|
||
<p>从文件读取或写入文件的二进制数据的基本类型为 <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> 。其他 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like objects</span></a> 也可以作为方法参数。文本I/O类使用 <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> 数据。</p>
|
||
<p>请注意，在关闭的流上调用任何方法（甚至查询）都是未定义的（undefined）。在这种情况下，实现可能会引发 <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> 。</p>
|
||
<p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> （及其子类）支持迭代器协议，这意味着可以迭代 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 对象以产生流中的行。根据流是二进制流（产生字节）还是文本流（产生字符串），行的定义略有不同。请参见下面的 <a class="reference internal" href="#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> 。</p>
|
||
<p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 也是一个上下文管理器，因此支持 <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> 语句。 在这个示例中，<em>file</em> 将在 <code class="xref std std-keyword docutils literal notranslate"><span class="pre">with</span></code> 语句块执行完成之后被关闭 --- 即使是发生了异常:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="s1">'spam.txt'</span><span class="p">,</span> <span class="s1">'w'</span><span class="p">)</span> <span class="k">as</span> <span class="n">file</span><span class="p">:</span>
|
||
<span class="n">file</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'Spam and eggs!'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p><a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 提供以下数据属性和方法：</p>
|
||
<dl class="method">
|
||
<dt id="io.IOBase.close">
|
||
<code class="sig-name descname">close</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.close" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>刷新并关闭此流。如果文件已经关闭，则此方法无效。文件关闭后，对文件的任何操作（例如读取或写入）都会引发 <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> 。</p>
|
||
<p>为方便起见，允许多次调用此方法。但是，只有第一个调用才会生效。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.IOBase.closed">
|
||
<code class="sig-name descname">closed</code><a class="headerlink" href="#io.IOBase.closed" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果流已关闭，则返回 True。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.fileno">
|
||
<code class="sig-name descname">fileno</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.fileno" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回流的底层文件描述符（整数）---如果存在。如果 IO 对象不使用文件描述符，则会引发 <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> 。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.flush">
|
||
<code class="sig-name descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.flush" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>刷新流的写入缓冲区（如果适用）。这对只读和非阻塞流不起作用。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.isatty">
|
||
<code class="sig-name descname">isatty</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.isatty" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果流是交互式的（即连接到终端/tty设备），则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code> 。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.readable">
|
||
<code class="sig-name descname">readable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readable" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果可以读取流，则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code> 。否则为 <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> 将引发 <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a> 错误。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.readline">
|
||
<code class="sig-name descname">readline</code><span class="sig-paren">(</span><em class="sig-param">size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readline" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从流中读取并返回一行。如果指定了 <em>size</em>，将至多读取 <em>size</em> 个字节。</p>
|
||
<p>对于二进制文件行结束符总是 <code class="docutils literal notranslate"><span class="pre">b'\n'</span></code>；对于文本文件，可以用将 <em>newline</em> 参数传给 <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> 的方式来选择要识别的行结束符。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.readlines">
|
||
<code class="sig-name descname">readlines</code><span class="sig-paren">(</span><em class="sig-param">hint=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.readlines" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从流中读取并返回包含多行的列表。可以指定 <em>hint</em> 来控制要读取的行数：如果（以字节/字符数表示的）所有行的总大小超出了 <em>hint</em> 则将不会读取更多的行。</p>
|
||
<p>请注意使用 <code class="docutils literal notranslate"><span class="pre">for</span> <span class="pre">line</span> <span class="pre">in</span> <span class="pre">file:</span> <span class="pre">...</span></code> 就足够对文件对象进行迭代了，可以不必调用 <code class="docutils literal notranslate"><span class="pre">file.readlines()</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.seek">
|
||
<code class="sig-name descname">seek</code><span class="sig-paren">(</span><em class="sig-param">offset</em>, <em class="sig-param">whence=SEEK_SET</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.seek" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将流位置修改到给定的字节 <em>offset</em>。 <em>offset</em> 将相对于由 <em>whence</em> 指定的位置进行解析。 <em>whence</em> 的默认值为 <code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_SET</span></code>。 <em>whence</em> 的可用值有：</p>
|
||
<ul class="simple">
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_SET</span></code> 或 <code class="docutils literal notranslate"><span class="pre">0</span></code> -- 流的开头（默认值）；<em>offset</em> 应为零或正值</p></li>
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_CUR</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> -- 当前流位置；<em>offset</em> 可以为负值</p></li>
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_END</span></code> or <code class="docutils literal notranslate"><span class="pre">2</span></code> -- 流的末尾；<em>offset</em> 通常为负值</p></li>
|
||
</ul>
|
||
<p>返回新的绝对位置。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.1 新版功能: </span><code class="docutils literal notranslate"><span class="pre">SEEK_*</span></code> 常量.</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.3 新版功能: </span>某些操作系统还可支持其他的值，例如 <code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_HOLE</span></code> 或 <code class="xref py py-data docutils literal notranslate"><span class="pre">os.SEEK_DATA</span></code>。特定文件的可用值还会取决于它是以文本还是二进制模式打开。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.seekable">
|
||
<code class="sig-name descname">seekable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.seekable" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果流支持随机访问则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code>。 如为 <code class="docutils literal notranslate"><span class="pre">False</span></code>，则 <a class="reference internal" href="#io.IOBase.seek" title="io.IOBase.seek"><code class="xref py py-meth docutils literal notranslate"><span class="pre">seek()</span></code></a>, <a class="reference internal" href="#io.IOBase.tell" title="io.IOBase.tell"><code class="xref py py-meth docutils literal notranslate"><span class="pre">tell()</span></code></a> 和 <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> 将引发 <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.tell">
|
||
<code class="sig-name descname">tell</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.tell" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回当前流的位置。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.truncate">
|
||
<code class="sig-name descname">truncate</code><span class="sig-paren">(</span><em class="sig-param">size=None</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.truncate" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将流的大小调整为给定的 <em>size</em> 个字节（如果未指定 <em>size</em> 则调整至当前位置）。 当前的流位置不变。 这个调整操作可扩展或减小当前文件大小。 在扩展的情况下，新文件区域的内容取决于具体平台（在大多数系统上，额外的字节会填充为零）。 返回新的文件大小。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>现在Windows在扩展时将文件填充为零。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.writable">
|
||
<code class="sig-name descname">writable</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.writable" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果流支持写入则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code>。 如为 <code class="docutils literal notranslate"><span class="pre">False</span></code>，则 <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> 和 <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> 将引发 <a class="reference internal" href="exceptions.html#OSError" title="OSError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">OSError</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.writelines">
|
||
<code class="sig-name descname">writelines</code><span class="sig-paren">(</span><em class="sig-param">lines</em><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.writelines" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将行列表写入到流。 不会添加行分隔符，因此通常所提供的每一行都带有末尾行分隔符。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.IOBase.__del__">
|
||
<code class="sig-name descname">__del__</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.IOBase.__del__" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 提供了此方法的默认实现，该实现会调用实例的 <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> 方法。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.RawIOBase">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">RawIOBase</code><a class="headerlink" href="#io.RawIOBase" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>原始二进制 I/O 的基类。 它继承自 <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>
|
||
<p>原始二进制 I/O 通常提供对下层 OS 设备或 API 的低层级访问，而不尝试将其封装到高层级的基元中（这是留给缓冲 I/O 和 Text I/O 的，将在下文中描述）。</p>
|
||
<p>在 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 的属性和方法之外，<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>
|
||
<dl class="method">
|
||
<dt id="io.RawIOBase.read">
|
||
<code class="sig-name descname">read</code><span class="sig-paren">(</span><em class="sig-param">size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.read" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从对象中读取 <em>size</em> 个字节并将其返回。 作为一个便捷选项，如果 <em>size</em> 未指定或为 -1，则返回所有字节直到 EOF。 在其他情况下，仅会执行一次系统调用。 如果操作系统调用返回字节数少于 <em>size</em> 则此方法也可能返回少于 <em>size</em> 个字节。</p>
|
||
<p>如果返回 0 个字节而 <em>size</em> 不为零 0，这表明到达文件末尾。 如果处于非阻塞模式并且没有更多字节可用，则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
|
||
<p>默认实现会转至 <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> 和 <a class="reference internal" href="#io.RawIOBase.readinto" title="io.RawIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.RawIOBase.readall">
|
||
<code class="sig-name descname">readall</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.readall" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从流中读取并返回所有字节直到 EOF，如有必要将对流执行多次调用。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.RawIOBase.readinto">
|
||
<code class="sig-name descname">readinto</code><span class="sig-paren">(</span><em class="sig-param">b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.readinto" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将字节数据读入预先分配的可写 <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>，并返回所读取的字节数。 例如，<em>b</em> 可以是一个 <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>。 如果对象处理非阻塞模式并且没有更多字节可用，则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.RawIOBase.write">
|
||
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.RawIOBase.write" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将给定的 <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> 写入到下层的原始流，并返回所写入的字节数。 这可以少于 <em>b</em> 的总字节数，具体取决于下层原始流的设定，特别是如果它处于非阻塞模式的话。 如果原始流设为非阻塞并且不能真正向其写入单个字节时则返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。 调用者可以在此方法返回后释放或改变 <em>b</em>，因此该实现应该仅在方法调用期间访问 <em>b</em>。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedIOBase">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">BufferedIOBase</code><a class="headerlink" href="#io.BufferedIOBase" title="永久链接至目标">¶</a></dt>
|
||
<dd><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>
|
||
<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> 的主要差别在于 <a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a>, <a class="reference internal" href="#io.BufferedIOBase.readinto" title="io.BufferedIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a> 和 <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> 等方法将（分别）尝试按照要求读取尽可能多的输入或是耗尽所有给定的输出，其代价是可能会执行一次以上的系统调用。</p>
|
||
<p>除此之外，那些方法还可能引发 <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>，如果下层的原始数据流处于非阻塞模式并且无法接受或给出足够数据的话；不同于对应的 <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> 方法，它们将永远不会返回 <code class="docutils literal notranslate"><span class="pre">None</span></code>。</p>
|
||
<p>并且，<a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> 方法也没有转向 <a class="reference internal" href="#io.BufferedIOBase.readinto" title="io.BufferedIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a> 的默认实现。</p>
|
||
<p>典型的 <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> 实现不应当继承自 <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> 实现，而要包装一个该实现，正如 <a class="reference internal" href="#io.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> 所做的那样。</p>
|
||
<p><a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> 在 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 的现有成员以外还提供或重载了下列方法和属性:</p>
|
||
<dl class="attribute">
|
||
<dt id="io.BufferedIOBase.raw">
|
||
<code class="sig-name descname">raw</code><a class="headerlink" href="#io.BufferedIOBase.raw" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 处理的下层原始流 (<a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> 的实例)。 它不是 <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> API 的组成部分并且不存在于某些实现中。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.detach">
|
||
<code class="sig-name descname">detach</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.detach" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从缓冲区分离出下层原始流并将其返回。</p>
|
||
<p>在原始流被分离之后，缓冲区将处于不可用的状态。</p>
|
||
<p>某些缓冲区例如 <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> 并无可从此方法返回的单独原始流的概念。 它们将会引发 <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a>。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.1 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.read">
|
||
<code class="sig-name descname">read</code><span class="sig-paren">(</span><em class="sig-param">size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.read" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>读取并返回最多 <em>size</em> 个字节。 如果此参数被省略、为 <code class="docutils literal notranslate"><span class="pre">None</span></code> 或为负值，则读取并返回所有数据直到 EOF。 如果流已经到达 EOF 则返回一个空的 <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> 对象。</p>
|
||
<p>如果此参数为正值，并且下层原始流不可交互，则可能发起多个原始读取以满足字节计数（直至先遇到 EOF）。 但对于可交互原始流，则将至多发起一个原始读取，并且简短的结果并不意味着已到达 EOF。</p>
|
||
<p><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> 会在下层原始流不处于阻塞模式，并且当前没有可用数据时被引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.read1">
|
||
<code class="sig-name descname">read1</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.read1" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>通过至多一次对下层流的 <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> (或 <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>) 方法的调用读取并返回至多 <em>size</em> 个字节。 这适用于在 <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> 对象之上实现你自己的缓冲区的情况。</p>
|
||
<p>如果 <em>size</em> 为 <code class="docutils literal notranslate"><span class="pre">-1</span></code> (默认值)，则返回任意数量的字节（多于零字节，除非已到达 EOF）。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.readinto">
|
||
<code class="sig-name descname">readinto</code><span class="sig-paren">(</span><em class="sig-param">b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.readinto" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将字节数据读入预先分配的可写 <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> 并返回所读取的字节数。 例如，<em>b</em> 可以是一个 <a class="reference internal" href="stdtypes.html#bytearray" title="bytearray"><code class="xref py py-class docutils literal notranslate"><span class="pre">bytearray</span></code></a>。</p>
|
||
<p>类似于 <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>
|
||
<p><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> 会在下层原始流不处于阻塞模式，并且当前没有可用数据时被引发。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.readinto1">
|
||
<code class="sig-name descname">readinto1</code><span class="sig-paren">(</span><em class="sig-param">b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.readinto1" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将字节数据读入预先分配的可写 <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>，其中至多使用一次对下层原始流 <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> (或 <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>
|
||
<p><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> 会在下层原始流不处于阻塞模式，并且当前没有可用数据时被引发。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.5 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedIOBase.write">
|
||
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedIOBase.write" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>写入给定的 <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>，并返回写入的字节数 (总是等于 <em>b</em> 的字节长度，因为如果写入失败则会引发 <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>
|
||
<p>当处于非阻塞模式时，如果需要将数据写入原始流但它无法在不阻塞的情况下接受所有数据则将引发 <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>。</p>
|
||
<p>调用者可能会在此方法返回后释放或改变 <em>b</em>，因此该实现应当仅在方法调用期间访问 <em>b</em>。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="raw-file-i-o">
|
||
<h3>原始文件 I/O<a class="headerlink" href="#raw-file-i-o" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="io.FileIO">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">FileIO</code><span class="sig-paren">(</span><em class="sig-param">name</em>, <em class="sig-param">mode='r'</em>, <em class="sig-param">closefd=True</em>, <em class="sig-param">opener=None</em><span class="sig-paren">)</span><a class="headerlink" href="#io.FileIO" title="永久链接至目标">¶</a></dt>
|
||
<dd><p><a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code></a> 代表在 OS 层级上包含文件的字节数据。 它实现了 <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> 接口（因而也实现了 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 接口）。</p>
|
||
<p><em>name</em> 可以是以下两项之一：</p>
|
||
<ul class="simple">
|
||
<li><p>代表将被打开的文件路径的字符串或 <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> 对象。 在此情况下 closefd 必须为 <code class="docutils literal notranslate"><span class="pre">True</span></code> (默认值) 否则将会引发异常。</p></li>
|
||
<li><p>代表一个现有 OS 层级文件描述符的号码的整数，作为结果的 <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> 对象将可访问该文件。 当 FileIO 对象被关闭时此 fd 也将被关闭，除非 <em>closefd</em> 设为 <code class="docutils literal notranslate"><span class="pre">False</span></code>。</p></li>
|
||
</ul>
|
||
<p><em>mode</em> 可以为 <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> 或 <code class="docutils literal notranslate"><span class="pre">'a'</span></code> 分别表示读取（默认模式）、写入、独占新建或添加。 如果以写入或添加模式打开的文件不存在将自动新建；当以写入模式打开时文件将先清空。 以新建模式打开时如果文件已存在则将引发 <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>。 以新建模式打开文件也意味着要写入，因此该模式的行为与 <code class="docutils literal notranslate"><span class="pre">'w'</span></code> 类似。 在模式中附带 <code class="docutils literal notranslate"><span class="pre">'+'</span></code> 将允许同时读取和写入。</p>
|
||
<p>该类的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code> (当附带正值参数调用时), <code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code> 和 <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> 方法将只执行一次系统调用。</p>
|
||
<p>可以通过传入一个可调用对象作为 <em>opener</em> 来使用自定义文件打开器。 然后通过调用 <em>opener</em> 并传入 (<em>name</em>, <em>flags</em>) 来获取文件对象所对应的下层文件描述符。 <em>opener</em> 必须返回一个打开文件描述符（传入 <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> 作为 <em>opener</em> 的结果在功能上将与传入 <code class="docutils literal notranslate"><span class="pre">None</span></code> 类似）。</p>
|
||
<p>新创建的文件是 <a class="reference internal" href="os.html#fd-inheritance"><span class="std std-ref">不可继承的</span></a>。</p>
|
||
<p>有关 opener 参数的示例，请参见内置函数 <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> 。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>增加了 <em>opener</em> 参数。增加了 <code class="docutils literal notranslate"><span class="pre">'x'</span></code> 模式。</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.4 版更改: </span>文件现在禁止继承。</p>
|
||
</div>
|
||
<p>除了来自 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 和 <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> 的属性和方法之外，<a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code></a> 还提供了下列数据属性:</p>
|
||
<dl class="attribute">
|
||
<dt id="io.FileIO.mode">
|
||
<code class="sig-name descname">mode</code><a class="headerlink" href="#io.FileIO.mode" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>构造函数中给定的模式。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.FileIO.name">
|
||
<code class="sig-name descname">name</code><a class="headerlink" href="#io.FileIO.name" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>文件名。当构造函数中没有给定名称时，这是文件的文件描述符。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="buffered-streams">
|
||
<h3>缓冲流<a class="headerlink" href="#buffered-streams" title="永久链接至标题">¶</a></h3>
|
||
<p>相比原始 I/O，缓冲 I/O 流提供了针对 I/O 设备的更高层级接口。</p>
|
||
<dl class="class">
|
||
<dt id="io.BytesIO">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">BytesIO</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">initial_bytes</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO" title="永久链接至目标">¶</a></dt>
|
||
<dd><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>。 在 <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> 方法被调用时将会丢弃缓冲区。</p>
|
||
<p>可选参数 <em>initial_bytes</em> 是一个包含初始数据的 <a class="reference internal" href="../glossary.html#term-bytes-like-object"><span class="xref std std-term">bytes-like object</span></a>。</p>
|
||
<p><a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> 在继承自 <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> 和 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 的成员以外还提供或重写了下列方法:</p>
|
||
<dl class="method">
|
||
<dt id="io.BytesIO.getbuffer">
|
||
<code class="sig-name descname">getbuffer</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.getbuffer" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回一个对应于缓冲区内容的可读写视图而不必拷贝其数据。 此外，改变视图将透明地更新缓冲区内容:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">BytesIO</span><span class="p">(</span><span class="sa">b</span><span class="s2">"abcdef"</span><span class="p">)</span>
|
||
<span class="gp">>>> </span><span class="n">view</span> <span class="o">=</span> <span class="n">b</span><span class="o">.</span><span class="n">getbuffer</span><span class="p">()</span>
|
||
<span class="gp">>>> </span><span class="n">view</span><span class="p">[</span><span class="mi">2</span><span class="p">:</span><span class="mi">4</span><span class="p">]</span> <span class="o">=</span> <span class="sa">b</span><span class="s2">"56"</span>
|
||
<span class="gp">>>> </span><span class="n">b</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
|
||
<span class="go">b'ab56ef'</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>只要视图保持存在，<a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> 对象就无法被改变大小或关闭。</p>
|
||
</div>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.2 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BytesIO.getvalue">
|
||
<code class="sig-name descname">getvalue</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.getvalue" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回包含整个缓冲区内容的 <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>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BytesIO.read1">
|
||
<code class="sig-name descname">read1</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.read1" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在 <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> 中，这与 <a class="reference internal" href="#io.BufferedIOBase.read" title="io.BufferedIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> 相同。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span><em>size</em> 参数现在是可选的。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BytesIO.readinto1">
|
||
<code class="sig-name descname">readinto1</code><span class="sig-paren">(</span><em class="sig-param">b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BytesIO.readinto1" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在 <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> 中，这与 <a class="reference internal" href="#io.BufferedIOBase.readinto" title="io.BufferedIOBase.readinto"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readinto()</span></code></a> 相同。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.5 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedReader">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">BufferedReader</code><span class="sig-paren">(</span><em class="sig-param">raw</em>, <em class="sig-param">buffer_size=DEFAULT_BUFFER_SIZE</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 对象更高层级访问的缓冲区。 它继承自 <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>。 当从此对象读取数据时，可能会从下层原始流请求更大量的数据，并存放到内部缓冲区中。 接下来可以在后续读取时直接返回缓冲数据。</p>
|
||
<p>根据给定的可读 <em>raw</em> 流和 <em>buffer_size</em> 创建 <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> 的构造器。 如果省略 <em>buffer_size</em>，则会使用 <a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT_BUFFER_SIZE</span></code></a>。</p>
|
||
<p><a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> 在继承自 <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a> 和 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 的成员以外还提供或重写了下列方法:</p>
|
||
<dl class="method">
|
||
<dt id="io.BufferedReader.peek">
|
||
<code class="sig-name descname">peek</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.peek" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从流返回字节数据而不前移位置。 完成此调用将至多读取一次原始流。 返回的字节数量可能少于或多于请求的数量。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedReader.read">
|
||
<code class="sig-name descname">read</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.read" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>读取并返回 <em>size</em> 个字节，如果 <em>size</em> 未给定或为负值，则读取至 EOF 或是在非阻塞模式下读取调用将会阻塞。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedReader.read1">
|
||
<code class="sig-name descname">read1</code><span class="sig-paren">(</span><span class="optional">[</span><em class="sig-param">size</em><span class="optional">]</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedReader.read1" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在原始流上通过单次调用读取并返回至多 <em>size</em> 个字节。 如果至少缓冲了一个字节，则只返回缓冲的字节。 在其他情况下，将执行一次原始流读取。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.7 版更改: </span><em>size</em> 参数现在是可选的。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedWriter">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">BufferedWriter</code><span class="sig-paren">(</span><em class="sig-param">raw</em>, <em class="sig-param">buffer_size=DEFAULT_BUFFER_SIZE</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 对象更高层级访问的缓冲区。 它继承自 <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>。 当写入到此对象时，数据通常会被放入到内部缓冲区中。 缓冲区将在满足某些条件的情况下被写到下层的 <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>
|
||
<ul class="simple">
|
||
<li><p>当缓冲区对于所有挂起数据而言太小时；</p></li>
|
||
<li><p>当 <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> 被调用时</p></li>
|
||
<li><p>当（为 <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> 对象）请求 <code class="xref py py-meth docutils literal notranslate"><span class="pre">seek()</span></code> 时；</p></li>
|
||
<li><p>当 <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> 对象被关闭或销毁时。</p></li>
|
||
</ul>
|
||
<p>该构造器会为给定的可写 <em>raw</em> 流创建一个 <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>。 如果未给定 <em>buffer_size</em>，则使用默认的 <a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT_BUFFER_SIZE</span></code></a>。</p>
|
||
<p><a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> 在继承自 <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> 和 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 的成员以外还提供或重写了下列方法:</p>
|
||
<dl class="method">
|
||
<dt id="io.BufferedWriter.flush">
|
||
<code class="sig-name descname">flush</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter.flush" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将缓冲区中保存的字节数据强制放入原始流。 如果原始流发生阻塞则应当引发 <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>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.BufferedWriter.write">
|
||
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">b</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedWriter.write" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>写入 <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> 并返回写入的字节数。 当处于非阻塞模式时，如果缓冲区需要被写入但原始流发生阻塞则将引发 <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>。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedRandom">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">BufferedRandom</code><span class="sig-paren">(</span><em class="sig-param">raw</em>, <em class="sig-param">buffer_size=DEFAULT_BUFFER_SIZE</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedRandom" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>随机访问流的带缓冲的接口。 它继承自 <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> 和 <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>
|
||
<p>该构造器会为在第一个参数中给定的可查找原始流创建一个读取器和写入器。 如果省略 <em>buffer_size</em> 则使用默认的 <a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT_BUFFER_SIZE</span></code></a>。</p>
|
||
<p><a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> 能做到 <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> 或 <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> 所能做的任何事。 此外，还会确保实现 <code class="xref py py-meth docutils literal notranslate"><span class="pre">seek()</span></code> 和 <code class="xref py py-meth docutils literal notranslate"><span class="pre">tell()</span></code>。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.BufferedRWPair">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">BufferedRWPair</code><span class="sig-paren">(</span><em class="sig-param">reader</em>, <em class="sig-param">writer</em>, <em class="sig-param">buffer_size=DEFAULT_BUFFER_SIZE</em><span class="sig-paren">)</span><a class="headerlink" href="#io.BufferedRWPair" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个带缓冲的 I/O 对象，它将两个单向 <a class="reference internal" href="#io.RawIOBase" title="io.RawIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">RawIOBase</span></code></a> 对象 -- 一个可读，另一个可写 -- 组合为单个双向端点。 它继承自 <a class="reference internal" href="#io.BufferedIOBase" title="io.BufferedIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedIOBase</span></code></a>。</p>
|
||
<p><em>reader</em> 和 <em>writer</em> 分别是可读和可写的 <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> 对象。 如果省略 <em>buffer_size</em> 则使用默认的 <a class="reference internal" href="#io.DEFAULT_BUFFER_SIZE" title="io.DEFAULT_BUFFER_SIZE"><code class="xref py py-data docutils literal notranslate"><span class="pre">DEFAULT_BUFFER_SIZE</span></code></a>。</p>
|
||
<p><a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code></a> 实现了 <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> 的所有方法，但 <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> 除外，调用该方法将引发 <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a>。</p>
|
||
<div class="admonition warning">
|
||
<p class="admonition-title">警告</p>
|
||
<p><a class="reference internal" href="#io.BufferedRWPair" title="io.BufferedRWPair"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRWPair</span></code></a> 不会尝试同步访问其下层的原始流。 你不应当将传给它与读取器和写入器相同的对象；而要改用 <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>。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="id1">
|
||
<h3>文本 I/O<a class="headerlink" href="#id1" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="io.TextIOBase">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">TextIOBase</code><a class="headerlink" href="#io.TextIOBase" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>文本流的基类。 该类提供了基于字符和行的流 I/O 接口。 它继承自 <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>
|
||
<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> 在来自 <a class="reference internal" href="#io.IOBase" title="io.IOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">IOBase</span></code></a> 的成员以外还提供或重写了以下数据属性和方法:</p>
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOBase.encoding">
|
||
<code class="sig-name descname">encoding</code><a class="headerlink" href="#io.TextIOBase.encoding" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于将流的字节串解码为字符串以及将字符串编码为字节串的编码格式名称。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOBase.errors">
|
||
<code class="sig-name descname">errors</code><a class="headerlink" href="#io.TextIOBase.errors" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>解码器或编码器的错误设置。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOBase.newlines">
|
||
<code class="sig-name descname">newlines</code><a class="headerlink" href="#io.TextIOBase.newlines" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个字符串、字符串元组或者 <code class="docutils literal notranslate"><span class="pre">None</span></code>，表示目前已经转写的新行。 根据具体实现和初始构造器旗标的不同，此属性或许会不可用。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOBase.buffer">
|
||
<code class="sig-name descname">buffer</code><a class="headerlink" href="#io.TextIOBase.buffer" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 处理的下层二进制缓冲区（为一个 <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> 的实例）。 它不是 <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a> API 的组成部分并且不存在于某些实现中。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.detach">
|
||
<code class="sig-name descname">detach</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.detach" title="永久链接至目标">¶</a></dt>
|
||
<dd><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>
|
||
<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>
|
||
<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> 的实现，例如 <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> 可能并无下层缓冲区的概念，因此调用此方法将引发 <a class="reference internal" href="#io.UnsupportedOperation" title="io.UnsupportedOperation"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnsupportedOperation</span></code></a>。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.1 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.read">
|
||
<code class="sig-name descname">read</code><span class="sig-paren">(</span><em class="sig-param">size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.read" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从流中读取至多 <em>size</em> 个字符并以单个 <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> 的形式返回。 如果 <em>size</em> 为负值或 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则读取至 EOF。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.readline">
|
||
<code class="sig-name descname">readline</code><span class="sig-paren">(</span><em class="sig-param">size=-1</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.readline" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>读取至换行符或 EOF 并返回单个 <code class="docutils literal notranslate"><span class="pre">str</span></code>。 如果流已经到达 EOF，则将返回一个空字符串。</p>
|
||
<p>如果指定了 <em>size</em> ，最多将读取 <em>size</em> 个字符。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.seek">
|
||
<code class="sig-name descname">seek</code><span class="sig-paren">(</span><em class="sig-param">offset</em>, <em class="sig-param">whence=SEEK_SET</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.seek" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将流位置改为给定的偏移位置 <em>offset</em>。 具体行为取决于 <em>whence</em> 形参。 <em>whence</em> 的默认值为 <code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_SET</span></code>。</p>
|
||
<ul class="simple">
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_SET</span></code> 或 <code class="docutils literal notranslate"><span class="pre">0</span></code>: 从流的开始位置起查找（默认值）；<em>offset</em> 必须为 <a class="reference internal" href="#io.TextIOBase.tell" title="io.TextIOBase.tell"><code class="xref py py-meth docutils literal notranslate"><span class="pre">TextIOBase.tell()</span></code></a> 所返回的数值或为零。 任何其他 <em>offset</em> 值都将导致未定义的行为。</p></li>
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_CUR</span></code> 或 <code class="docutils literal notranslate"><span class="pre">1</span></code>: "查找" 到当前位置；<em>offset</em> 必须为零，表示无操作（所有其他值均不受支持）。</p></li>
|
||
<li><p><code class="xref py py-data docutils literal notranslate"><span class="pre">SEEK_END</span></code> 或 <code class="docutils literal notranslate"><span class="pre">2</span></code>: 查找到流的末尾；<em>offset</em> 必须为零（所有其他值均不受支持）。</p></li>
|
||
</ul>
|
||
<p>以不透明数字形式返回新的绝对位置。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.1 新版功能: </span><code class="docutils literal notranslate"><span class="pre">SEEK_*</span></code> 常量.</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.tell">
|
||
<code class="sig-name descname">tell</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.tell" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>以不透明数字形式返回当前流的位置。 该数字通常并不代表下层二进制存储中对应的字节数。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOBase.write">
|
||
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">s</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOBase.write" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将字符串 <em>s</em> 写入到流并返回写入的字符数。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.TextIOWrapper">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">TextIOWrapper</code><span class="sig-paren">(</span><em class="sig-param">buffer</em>, <em class="sig-param">encoding=None</em>, <em class="sig-param">errors=None</em>, <em class="sig-param">newline=None</em>, <em class="sig-param">line_buffering=False</em>, <em class="sig-param">write_through=False</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOWrapper" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 二进制流的缓冲文本流。 它继承自 <a class="reference internal" href="#io.TextIOBase" title="io.TextIOBase"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOBase</span></code></a>。</p>
|
||
<p><em>encoding</em> 给出流被解码或编码时将使用的编码格式。 它默认为 <a class="reference internal" href="locale.html#locale.getpreferredencoding" title="locale.getpreferredencoding"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.getpreferredencoding(False)</span></code></a>。</p>
|
||
<p><em>errors</em> 是一个可选的字符串，它指明编码格式和编码格式错误的处理方式。 传入 <code class="docutils literal notranslate"><span class="pre">'strict'</span></code> 将在出现编码格式错误时引发 <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> (默认值 <code class="docutils literal notranslate"><span class="pre">None</span></code> 具有相同的效果)，传入 <code class="docutils literal notranslate"><span class="pre">'ignore'</span></code> 将忽略错误。 (请注意忽略编码格式错误会导致数据丢失。) <code class="docutils literal notranslate"><span class="pre">'replace'</span></code> 会在出现错误数据时插入一个替换标记 (例如 <code class="docutils literal notranslate"><span class="pre">'?'</span></code>)。 <code class="docutils literal notranslate"><span class="pre">'backslashreplace'</span></code> 将把错误数据替换为一个反斜杠转义序列。 在写入时，还可以使用 <code class="docutils literal notranslate"><span class="pre">'xmlcharrefreplace'</span></code> (替换为适当的 XML 字符引用) 或 <code class="docutils literal notranslate"><span class="pre">'namereplace'</span></code> (替换为 <code class="docutils literal notranslate"><span class="pre">\N{...}</span></code> 转义序列)。 任何其他通过 <a class="reference internal" href="codecs.html#codecs.register_error" title="codecs.register_error"><code class="xref py py-func docutils literal notranslate"><span class="pre">codecs.register_error()</span></code></a> 注册的错误处理方式名称也可以被接受。</p>
|
||
<p id="index-1"><em>newline</em> 控制行结束符处理方式。 它可以为 <code class="docutils literal notranslate"><span class="pre">None</span></code>, <code class="docutils literal notranslate"><span class="pre">''</span></code>, <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>, <code class="docutils literal notranslate"><span class="pre">'\r'</span></code> 和 <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code>。 其工作原理如下:</p>
|
||
<ul class="simple">
|
||
<li><p>当从流中读取输入时，如果 <em>newline</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则会启用 <a class="reference internal" href="../glossary.html#term-universal-newlines"><span class="xref std std-term">universal newlines</span></a> 模式。 输入中的行结束符可以为 <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>, <code class="docutils literal notranslate"><span class="pre">'\r'</span></code> 或 <code class="docutils literal notranslate"><span class="pre">'\r\n'</span></code>，在返回给调用者之前它们会被统一转写为 <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>。 如果参数为 <code class="docutils literal notranslate"><span class="pre">''</span></code>，也会启用通用换行模式，但行结束符会不加转写即返回给调用者。 如果它具有任何其他合法的值，则输入行将仅由给定的字符串结束，并且行结束符会不加转写即返回给调用者。</p></li>
|
||
<li><p>将输出写入流时，如果 <em>newline</em> 为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，则写入的任何 <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> 字符都将转换为系统默认行分隔符 <a class="reference internal" href="os.html#os.linesep" title="os.linesep"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.linesep</span></code></a>。如果 <em>newline</em> 是 <code class="docutils literal notranslate"><span class="pre">''</span></code> 或 <code class="docutils literal notranslate"><span class="pre">'\n'</span></code>，则不进行翻译。如果 <em>newline</em> 是任何其他合法值，则写入的任何 <code class="docutils literal notranslate"><span class="pre">'\n'</span></code> 字符将被转换为给定的字符串。</p></li>
|
||
</ul>
|
||
<p>如果 <em>line_buffering</em> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，则当一个写入调用包含换行符或回车时将会应用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">flush()</span></code>。</p>
|
||
<p>如果 <em>write_through</em> 为 <code class="docutils literal notranslate"><span class="pre">True</span></code>，对 <code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code> 的调用会确保不被缓冲：在 <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> 对象上写入的任何数据会立即交给其下层的 <em>buffer</em> 来处理。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>已添加 <em>write_through</em> 参数</p>
|
||
</div>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.3 版更改: </span>默认的 <em>encoding</em> 现在将为 <code class="docutils literal notranslate"><span class="pre">locale.getpreferredencoding(False)</span></code> 而非 <code class="docutils literal notranslate"><span class="pre">locale.getpreferredencoding()</span></code>。 不要使用 <a class="reference internal" href="locale.html#locale.setlocale" title="locale.setlocale"><code class="xref py py-func docutils literal notranslate"><span class="pre">locale.setlocale()</span></code></a> 来临时改变区域编码格式，要使用当前区域编码格式而不是用户的首选编码格式。</p>
|
||
</div>
|
||
<p><a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOWrapper</span></code></a> 在继承自 <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>
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOWrapper.line_buffering">
|
||
<code class="sig-name descname">line_buffering</code><a class="headerlink" href="#io.TextIOWrapper.line_buffering" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>是否启用行缓冲。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="io.TextIOWrapper.write_through">
|
||
<code class="sig-name descname">write_through</code><a class="headerlink" href="#io.TextIOWrapper.write_through" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>写入是否要立即传给下层的二进制缓冲。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.7 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="io.TextIOWrapper.reconfigure">
|
||
<code class="sig-name descname">reconfigure</code><span class="sig-paren">(</span><em class="sig-param">*[, encoding][, errors][, newline][, line_buffering][, write_through]</em><span class="sig-paren">)</span><a class="headerlink" href="#io.TextIOWrapper.reconfigure" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>使用 <em>encoding</em>, <em>errors</em>, <em>newline</em>, <em>line_buffering</em> 和 <em>write_through</em> 的新设置来重新配置此文本流。</p>
|
||
<p>未指定的形参将保留当前设定，例外情况是当指定了 <em>encoding</em> 但未指定 <em>errors</em> 时将会使用 <code class="docutils literal notranslate"><span class="pre">errors='strict'</span></code>。</p>
|
||
<p>如果已经有数据从流中被读取则将无法再改变编码格式或行结束符。 另一方面，在写入数据之后再改变编码格式则是可以的。</p>
|
||
<p>此方法会在设置新的形参之前执行隐式的流刷新。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.7 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
<dl class="class">
|
||
<dt id="io.StringIO">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">StringIO</code><span class="sig-paren">(</span><em class="sig-param">initial_value=''</em>, <em class="sig-param">newline='\n'</em><span class="sig-paren">)</span><a class="headerlink" href="#io.StringIO" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于文本 I/O 的内存数据流。 当调用 <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> 方法时将会丢弃文本缓冲区。</p>
|
||
<p>缓冲区的初始值可通过提供 <em>initial_value</em> 来设置。 如果启用了行结束符转写，换行将以 <a class="reference internal" href="#io.TextIOBase.write" title="io.TextIOBase.write"><code class="xref py py-meth docutils literal notranslate"><span class="pre">write()</span></code></a> 所用的方式被编码。 数据流位置将被设为缓冲区的开头。</p>
|
||
<p><em>newline</em> 参数的规则与 <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> 所用的一致。 默认规则是仅将 <code class="docutils literal notranslate"><span class="pre">\n</span></code> 字符视为行结束符并且不执行换行符转写。 如果 <em>newline</em> 设为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，在所有平台上换行符都将被写入为 <code class="docutils literal notranslate"><span class="pre">\n</span></code>，但当读取时仍然会执行通用换行编码格式。</p>
|
||
<p><a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code></a> 在继承自 <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>
|
||
<dl class="method">
|
||
<dt id="io.StringIO.getvalue">
|
||
<code class="sig-name descname">getvalue</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#io.StringIO.getvalue" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回一个包含缓冲区全部内容的 <code class="docutils literal notranslate"><span class="pre">str</span></code>。 换行符会以与 <a class="reference internal" href="#io.TextIOBase.read" title="io.TextIOBase.read"><code class="xref py py-meth docutils literal notranslate"><span class="pre">read()</span></code></a> 相同的方式被编码，但是流的位置不会被改变。</p>
|
||
</dd></dl>
|
||
|
||
<p>用法示例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">io</span>
|
||
|
||
<span class="n">output</span> <span class="o">=</span> <span class="n">io</span><span class="o">.</span><span class="n">StringIO</span><span class="p">()</span>
|
||
<span class="n">output</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">'First line.</span><span class="se">\n</span><span class="s1">'</span><span class="p">)</span>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s1">'Second line.'</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">output</span><span class="p">)</span>
|
||
|
||
<span class="c1"># Retrieve file contents -- this will be</span>
|
||
<span class="c1"># 'First line.\nSecond line.\n'</span>
|
||
<span class="n">contents</span> <span class="o">=</span> <span class="n">output</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span>
|
||
|
||
<span class="c1"># Close object and discard memory buffer --</span>
|
||
<span class="c1"># .getvalue() will now raise an exception.</span>
|
||
<span class="n">output</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-2"></span><dl class="class">
|
||
<dt id="io.IncrementalNewlineDecoder">
|
||
<em class="property">class </em><code class="sig-prename descclassname">io.</code><code class="sig-name descname">IncrementalNewlineDecoder</code><a class="headerlink" href="#io.IncrementalNewlineDecoder" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用于在 <a class="reference internal" href="../glossary.html#term-universal-newlines"><span class="xref std std-term">universal newlines</span></a> 模式下解码换行符的辅助编解码器。 它继承自 <a class="reference internal" href="codecs.html#codecs.IncrementalDecoder" title="codecs.IncrementalDecoder"><code class="xref py py-class docutils literal notranslate"><span class="pre">codecs.IncrementalDecoder</span></code></a>。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
</section>
|
||
<section id="performance">
|
||
<h2>性能<a class="headerlink" href="#performance" title="永久链接至标题">¶</a></h2>
|
||
<p>本节讨论所提供的具体 I/O 实现的性能。</p>
|
||
<section id="id2">
|
||
<h3>二进制 I/O<a class="headerlink" href="#id2" title="永久链接至标题">¶</a></h3>
|
||
<p>即使在用户请求单个字节时，也只读取和写入大块数据。通过该方法，缓冲 I/O 隐藏了操作系统调用和执行无缓冲 I/O 例程时的任何低效性。增益取决于操作系统和执行的 I/O 类型。例如，在某些现代操作系统上（例如 Linux），无缓冲磁盘 I/O 可以与缓冲 I/O 一样快。但最重要的是，无论平台和支持设备如何，缓冲 I/O 都能提供可预测的性能。因此，对于二进制数据，应首选使用缓冲的 I/O 而不是未缓冲的 I/O 。</p>
|
||
</section>
|
||
<section id="id3">
|
||
<h3>文本 I/O<a class="headerlink" href="#id3" title="永久链接至标题">¶</a></h3>
|
||
<p>二进制存储（如文件）上的文本 I/O 比同一存储上的二进制 I/O 慢得多，因为它需要使用字符编解码器在Unicode和二进制数据之间进行转换。这在处理大量文本数据（如大型日志文件）时会变得非常明显。此外，由于使用的重构算法 <code class="xref py py-meth docutils literal notranslate"><span class="pre">TextIOWrapper.tell()</span></code> 和 <code class="xref py py-meth docutils literal notranslate"><span class="pre">TextIOWrapper.seek()</span></code> 都相当慢。</p>
|
||
<p><a class="reference internal" href="#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">StringIO</span></code></a> 是原生的内存 Unicode 容器，速度与 <a class="reference internal" href="#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">BytesIO</span></code></a> 相似。</p>
|
||
</section>
|
||
<section id="multi-threading">
|
||
<h3>多线程<a class="headerlink" href="#multi-threading" title="永久链接至标题">¶</a></h3>
|
||
<p><a class="reference internal" href="#io.FileIO" title="io.FileIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">FileIO</span></code></a> 对象是线程安全的，只要它们封装的操作系统调用（比如Unix下的 <code class="docutils literal notranslate"><span class="pre">read(2)</span></code> ）也是线程安全的。</p>
|
||
<p>二进制缓冲对象（例如 <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a>, <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a>, <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> 和 <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>）使用锁来保护其内部结构；因此，可以安全地一次从多个线程中调用它们。</p>
|
||
<p><a class="reference internal" href="#io.TextIOWrapper" title="io.TextIOWrapper"><code class="xref py py-class docutils literal notranslate"><span class="pre">TextIOWrapper</span></code></a> 对象不再是线程安全的。</p>
|
||
</section>
|
||
<section id="reentrancy">
|
||
<h3>可重入性<a class="headerlink" href="#reentrancy" title="永久链接至标题">¶</a></h3>
|
||
<p>二进制缓冲对象（ <a class="reference internal" href="#io.BufferedReader" title="io.BufferedReader"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedReader</span></code></a> ， <a class="reference internal" href="#io.BufferedWriter" title="io.BufferedWriter"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedWriter</span></code></a> ， <a class="reference internal" href="#io.BufferedRandom" title="io.BufferedRandom"><code class="xref py py-class docutils literal notranslate"><span class="pre">BufferedRandom</span></code></a> 和 <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> 的实例）不是可重入的。虽然在正常情况下不会发生可重入调用，但仍可能会在 <a class="reference internal" href="signal.html#module-signal" title="signal: Set handlers for asynchronous events."><code class="xref py py-mod docutils literal notranslate"><span class="pre">signal</span></code></a> 处理程序执行 I/O 时产生。如果线程尝试重入已经访问的缓冲对象，则会引发 <a class="reference internal" href="exceptions.html#RuntimeError" title="RuntimeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">RuntimeError</span></code></a> 。注意，这并不禁止其他线程进入缓冲对象。</p>
|
||
<p>上面的内容隐含地扩展到文本文件，因为 <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> 函数会把缓冲对象封装在 <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> 中。这包括标准流，因此也会影响内置函数 <a class="reference internal" href="functions.html#print" title="print"><code class="xref py py-func docutils literal notranslate"><span class="pre">print()</span></code></a> 。</p>
|
||
</section>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">io</span></code> --- 处理流的核心工具</a><ul>
|
||
<li><a class="reference internal" href="#overview">概述</a><ul>
|
||
<li><a class="reference internal" href="#text-i-o">文本 I/O</a></li>
|
||
<li><a class="reference internal" href="#binary-i-o">二进制 I/O</a></li>
|
||
<li><a class="reference internal" href="#raw-i-o">原始 I/O</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#high-level-module-interface">高阶模块接口</a></li>
|
||
<li><a class="reference internal" href="#class-hierarchy">类的层次结构</a><ul>
|
||
<li><a class="reference internal" href="#i-o-base-classes">I/O 基类</a></li>
|
||
<li><a class="reference internal" href="#raw-file-i-o">原始文件 I/O</a></li>
|
||
<li><a class="reference internal" href="#buffered-streams">缓冲流</a></li>
|
||
<li><a class="reference internal" href="#id1">文本 I/O</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#performance">性能</a><ul>
|
||
<li><a class="reference internal" href="#id2">二进制 I/O</a></li>
|
||
<li><a class="reference internal" href="#id3">文本 I/O</a></li>
|
||
<li><a class="reference internal" href="#multi-threading">多线程</a></li>
|
||
<li><a class="reference internal" href="#reentrancy">可重入性</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="os.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">os</span></code> --- 多种操作系统接口</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="time.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">time</span></code> --- 时间的访问和转换</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/io.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
>索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="time.html" title="time --- 时间的访问和转换"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="os.html" title="os --- 多种操作系统接口"
|
||
>上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="allos.html" >通用操作系统服务</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
|
||
最后更新于 12月 09, 2024.
|
||
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |