D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
usr
/
share
/
doc
/
python2-docs
/
html
/
c-api
/
Filename :
file.html
back
Copy
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>File Objects — Python 2.7.16 documentation</title> <link rel="stylesheet" href="../_static/classic.css" type="text/css" /> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script> <script type="text/javascript" src="../_static/jquery.js"></script> <script type="text/javascript" src="../_static/underscore.js"></script> <script type="text/javascript" src="../_static/doctools.js"></script> <script type="text/javascript" src="../_static/sidebar.js"></script> <link rel="search" type="application/opensearchdescription+xml" title="Search within Python 2.7.16 documentation" href="../_static/opensearch.xml"/> <link rel="author" title="About these documents" href="../about.html" /> <link rel="index" title="Index" href="../genindex.html" /> <link rel="search" title="Search" href="../search.html" /> <link rel="copyright" title="Copyright" href="../copyright.html" /> <link rel="next" title="Module Objects" href="module.html" /> <link rel="prev" title="Method Objects" href="method.html" /> <link rel="shortcut icon" type="image/png" href="../_static/py.png" /> <link rel="canonical" href="https://docs.python.org/2/c-api/file.html" /> <script type="text/javascript" src="../_static/copybutton.js"></script> </head><body> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="module.html" title="Module Objects" accesskey="N">next</a> |</li> <li class="right" > <a href="method.html" title="Method Objects" accesskey="P">previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.16 documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li> <li class="nav-item nav-item-2"><a href="concrete.html" accesskey="U">Concrete Objects Layer</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="file-objects"> <span id="fileobjects"></span><h1>File Objects<a class="headerlink" href="#file-objects" title="Permalink to this headline">¶</a></h1> <p id="index-0">Python’s built-in file objects are implemented entirely on the <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> support from the C standard library. This is an implementation detail and may change in future releases of Python.</p> <dl class="type"> <dt id="c.PyFileObject"> <code class="descname">PyFileObject</code><a class="headerlink" href="#c.PyFileObject" title="Permalink to this definition">¶</a></dt> <dd><p>This subtype of <a class="reference internal" href="structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> represents a Python file object.</p> </dd></dl> <dl class="var"> <dt id="c.PyFile_Type"> <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject">PyTypeObject</a> <code class="descname">PyFile_Type</code><a class="headerlink" href="#c.PyFile_Type" title="Permalink to this definition">¶</a></dt> <dd><p id="index-1">This instance of <a class="reference internal" href="type.html#c.PyTypeObject" title="PyTypeObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyTypeObject</span></code></a> represents the Python file type. This is exposed to Python programs as <code class="docutils literal notranslate"><span class="pre">file</span></code> and <code class="docutils literal notranslate"><span class="pre">types.FileType</span></code>.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_Check"> int <code class="descname">PyFile_Check</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_Check" title="Permalink to this definition">¶</a></dt> <dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a> or a subtype of <a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a>.</p> <div class="versionchanged"> <p><span class="versionmodified">Changed in version 2.2: </span>Allowed subtypes to be accepted.</p> </div> </dd></dl> <dl class="function"> <dt id="c.PyFile_CheckExact"> int <code class="descname">PyFile_CheckExact</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_CheckExact" title="Permalink to this definition">¶</a></dt> <dd><p>Return true if its argument is a <a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a>, but not a subtype of <a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a>.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.2.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyFile_FromString"> <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFile_FromString</code><span class="sig-paren">(</span>char<em> *filename</em>, char<em> *mode</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_FromString" title="Permalink to this definition">¶</a></dt> <dd><em class="refcount">Return value: New reference.</em><p id="index-2">On success, return a new file object that is opened on the file given by <em>filename</em>, with a file mode given by <em>mode</em>, where <em>mode</em> has the same semantics as the standard C routine <code class="xref c c-func docutils literal notranslate"><span class="pre">fopen()</span></code>. On failure, return <em>NULL</em>.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_FromFile"> <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFile_FromFile</code><span class="sig-paren">(</span>FILE<em> *fp</em>, char<em> *name</em>, char<em> *mode</em>, int (<em>*close</em>)(FILE*)<span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_FromFile" title="Permalink to this definition">¶</a></dt> <dd><em class="refcount">Return value: New reference.</em><p>Create a new <a class="reference internal" href="#c.PyFileObject" title="PyFileObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyFileObject</span></code></a> from the already-open standard C file pointer, <em>fp</em>. The function <em>close</em> will be called when the file should be closed. Return <em>NULL</em> and close the file using <em>close</em> on failure. <em>close</em> is optional and can be set to <em>NULL</em>.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_AsFile"> FILE* <code class="descname">PyFile_AsFile</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_AsFile" title="Permalink to this definition">¶</a></dt> <dd><p>Return the file object associated with <em>p</em> as a <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code>.</p> <p>If the caller will ever use the returned <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> object while the <a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a> is released it must also call the <a class="reference internal" href="#c.PyFile_IncUseCount" title="PyFile_IncUseCount"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_IncUseCount()</span></code></a> and <a class="reference internal" href="#c.PyFile_DecUseCount" title="PyFile_DecUseCount"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_DecUseCount()</span></code></a> functions described below as appropriate.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_IncUseCount"> void <code class="descname">PyFile_IncUseCount</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_IncUseCount" title="Permalink to this definition">¶</a></dt> <dd><p>Increments the PyFileObject’s internal use count to indicate that the underlying <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code> is being used. This prevents Python from calling f_close() on it from another thread. Callers of this must call <a class="reference internal" href="#c.PyFile_DecUseCount" title="PyFile_DecUseCount"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_DecUseCount()</span></code></a> when they are finished with the <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code>. Otherwise the file object will never be closed by Python.</p> <p>The <a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a> must be held while calling this function.</p> <p>The suggested use is to call this after <a class="reference internal" href="#c.PyFile_AsFile" title="PyFile_AsFile"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_AsFile()</span></code></a> and before you release the GIL:</p> <div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="kt">FILE</span> <span class="o">*</span><span class="n">fp</span> <span class="o">=</span> <span class="n">PyFile_AsFile</span><span class="p">(</span><span class="n">p</span><span class="p">);</span> <span class="n">PyFile_IncUseCount</span><span class="p">(</span><span class="n">p</span><span class="p">);</span> <span class="cm">/* ... */</span> <span class="n">Py_BEGIN_ALLOW_THREADS</span> <span class="nf">do_something</span><span class="p">(</span><span class="n">fp</span><span class="p">);</span> <span class="n">Py_END_ALLOW_THREADS</span> <span class="cm">/* ... */</span> <span class="n">PyFile_DecUseCount</span><span class="p">(</span><span class="n">p</span><span class="p">);</span> </pre></div> </div> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyFile_DecUseCount"> void <code class="descname">PyFile_DecUseCount</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_DecUseCount" title="Permalink to this definition">¶</a></dt> <dd><p>Decrements the PyFileObject’s internal unlocked_count member to indicate that the caller is done with its own use of the <code class="xref c c-type docutils literal notranslate"><span class="pre">FILE*</span></code>. This may only be called to undo a prior call to <a class="reference internal" href="#c.PyFile_IncUseCount" title="PyFile_IncUseCount"><code class="xref c c-func docutils literal notranslate"><span class="pre">PyFile_IncUseCount()</span></code></a>.</p> <p>The <a class="reference internal" href="../glossary.html#term-gil"><span class="xref std std-term">GIL</span></a> must be held while calling this function (see the example above).</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyFile_GetLine"> <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFile_GetLine</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, int<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_GetLine" title="Permalink to this definition">¶</a></dt> <dd><em class="refcount">Return value: New reference.</em><p id="index-3">Equivalent to <code class="docutils literal notranslate"><span class="pre">p.readline([n])</span></code>, this function reads one line from the object <em>p</em>. <em>p</em> may be a file object or any object with a <a class="reference internal" href="../library/io.html#io.IOBase.readline" title="io.IOBase.readline"><code class="xref py py-meth docutils literal notranslate"><span class="pre">readline()</span></code></a> method. If <em>n</em> is <code class="docutils literal notranslate"><span class="pre">0</span></code>, exactly one line is read, regardless of the length of the line. If <em>n</em> is greater than <code class="docutils literal notranslate"><span class="pre">0</span></code>, no more than <em>n</em> bytes will be read from the file; a partial line can be returned. In both cases, an empty string is returned if the end of the file is reached immediately. If <em>n</em> is less than <code class="docutils literal notranslate"><span class="pre">0</span></code>, however, one line is read regardless of length, but <a class="reference internal" href="../library/exceptions.html#exceptions.EOFError" title="exceptions.EOFError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">EOFError</span></code></a> is raised if the end of the file is reached immediately.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_Name"> <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a>* <code class="descname">PyFile_Name</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_Name" title="Permalink to this definition">¶</a></dt> <dd><em class="refcount">Return value: Borrowed reference.</em><p>Return the name of the file specified by <em>p</em> as a string object.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_SetBufSize"> void <code class="descname">PyFile_SetBufSize</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em>, int<em> n</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_SetBufSize" title="Permalink to this definition">¶</a></dt> <dd><p id="index-4">Available on systems with <code class="xref c c-func docutils literal notranslate"><span class="pre">setvbuf()</span></code> only. This should only be called immediately after file object creation.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_SetEncoding"> int <code class="descname">PyFile_SetEncoding</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em>, const char<em> *enc</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_SetEncoding" title="Permalink to this definition">¶</a></dt> <dd><p>Set the file’s encoding for Unicode output to <em>enc</em>. Return <code class="docutils literal notranslate"><span class="pre">1</span></code> on success and <code class="docutils literal notranslate"><span class="pre">0</span></code> on failure.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.3.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyFile_SetEncodingAndErrors"> int <code class="descname">PyFile_SetEncodingAndErrors</code><span class="sig-paren">(</span><a class="reference internal" href="#c.PyFileObject" title="PyFileObject">PyFileObject</a><em> *p</em>, const char<em> *enc</em>, *errors<span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_SetEncodingAndErrors" title="Permalink to this definition">¶</a></dt> <dd><p>Set the file’s encoding for Unicode output to <em>enc</em>, and its error mode to <em>err</em>. Return <code class="docutils literal notranslate"><span class="pre">1</span></code> on success and <code class="docutils literal notranslate"><span class="pre">0</span></code> on failure.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 2.6.</span></p> </div> </dd></dl> <dl class="function"> <dt id="c.PyFile_SoftSpace"> int <code class="descname">PyFile_SoftSpace</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, int<em> newflag</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_SoftSpace" title="Permalink to this definition">¶</a></dt> <dd><p id="index-5">This function exists for internal use by the interpreter. Set the <code class="xref py py-attr docutils literal notranslate"><span class="pre">softspace</span></code> attribute of <em>p</em> to <em>newflag</em> and return the previous value. <em>p</em> does not have to be a file object for this function to work properly; any object is supported (thought its only interesting if the <code class="xref py py-attr docutils literal notranslate"><span class="pre">softspace</span></code> attribute can be set). This function clears any errors, and will return <code class="docutils literal notranslate"><span class="pre">0</span></code> as the previous value if the attribute either does not exist or if there were errors in retrieving it. There is no way to detect errors from this function, but doing so should not be needed.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_WriteObject"> int <code class="descname">PyFile_WriteObject</code><span class="sig-paren">(</span><a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *obj</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em>, int<em> flags</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_WriteObject" title="Permalink to this definition">¶</a></dt> <dd><p id="index-6">Write object <em>obj</em> to file object <em>p</em>. The only supported flag for <em>flags</em> is <code class="xref py py-const docutils literal notranslate"><span class="pre">Py_PRINT_RAW</span></code>; if given, the <a class="reference internal" href="../library/functions.html#str" title="str"><code class="xref py py-func docutils literal notranslate"><span class="pre">str()</span></code></a> of the object is written instead of the <a class="reference internal" href="../library/functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure; the appropriate exception will be set.</p> </dd></dl> <dl class="function"> <dt id="c.PyFile_WriteString"> int <code class="descname">PyFile_WriteString</code><span class="sig-paren">(</span>const char<em> *s</em>, <a class="reference internal" href="structures.html#c.PyObject" title="PyObject">PyObject</a><em> *p</em><span class="sig-paren">)</span><a class="headerlink" href="#c.PyFile_WriteString" title="Permalink to this definition">¶</a></dt> <dd><p>Write string <em>s</em> to file object <em>p</em>. Return <code class="docutils literal notranslate"><span class="pre">0</span></code> on success or <code class="docutils literal notranslate"><span class="pre">-1</span></code> on failure; the appropriate exception will be set.</p> </dd></dl> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h4>Previous topic</h4> <p class="topless"><a href="method.html" title="previous chapter">Method Objects</a></p> <h4>Next topic</h4> <p class="topless"><a href="module.html" title="next chapter">Module Objects</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../_sources/c-api/file.rst.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="module.html" title="Module Objects" >next</a> |</li> <li class="right" > <a href="method.html" title="Method Objects" >previous</a> |</li> <li><img src="../_static/py.png" alt="" style="vertical-align: middle; margin-top: -1px"/></li> <li><a href="https://www.python.org/">Python</a> »</li> <li> <a href="../index.html">Python 2.7.16 documentation</a> » </li> <li class="nav-item nav-item-1"><a href="index.html" >Python/C API Reference Manual</a> »</li> <li class="nav-item nav-item-2"><a href="concrete.html" >Concrete Objects Layer</a> »</li> </ul> </div> <div class="footer"> © <a href="../copyright.html">Copyright</a> 1990-2019, Python Software Foundation. <br /> The Python Software Foundation is a non-profit corporation. <a href="https://www.python.org/psf/donations/">Please donate.</a> <br /> Last updated on Mar 27, 2019. <a href="../bugs.html">Found a bug</a>? <br /> Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.7.6. </div> </body> </html>