File: //usr/share/doc/python27-paramiko-1.15.1/docs/api/sftp.html
<!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="Content-Type" content="text/html; charset=utf-8" />
<title>SFTP — Paramiko documentation</title>
<link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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>
<link rel="top" title="Paramiko documentation" href="../index.html" />
<link rel="next" title="Buffered pipes" href="buffered_pipe.html" />
<link rel="prev" title="Server implementation" href="server.html" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9">
</head>
<body>
<div class="related">
<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="buffered_pipe.html" title="Buffered pipes"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="server.html" title="Server implementation"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Paramiko documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="module-paramiko.sftp">
<span id="sftp"></span><h1>SFTP<a class="headerlink" href="#module-paramiko.sftp" title="Permalink to this headline">¶</a></h1>
<span class="target" id="module-paramiko.sftp_client"></span><dl class="class">
<dt id="paramiko.sftp_client.SFTP">
<em class="property">class </em><tt class="descclassname">paramiko.sftp_client.</tt><tt class="descname">SFTP</tt><big>(</big><em>sock</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTP" title="Permalink to this definition">¶</a></dt>
<dd><p>An alias for <a class="reference internal" href="#paramiko.sftp_client.SFTPClient" title="paramiko.sftp_client.SFTPClient"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPClient</span></tt></a> for backwards compatability.</p>
</dd></dl>
<dl class="class">
<dt id="paramiko.sftp_client.SFTPClient">
<em class="property">class </em><tt class="descclassname">paramiko.sftp_client.</tt><tt class="descname">SFTPClient</tt><big>(</big><em>sock</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient" title="Permalink to this definition">¶</a></dt>
<dd><p>SFTP client object.</p>
<p>Used to open an SFTP session across an open SSH <a class="reference internal" href="transport.html#paramiko.transport.Transport" title="paramiko.transport.Transport"><tt class="xref py py-obj docutils literal"><span class="pre">Transport</span></tt></a> and perform
remote file operations.</p>
<p>Instances of this class may be used as context managers.</p>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.__init__">
<tt class="descname">__init__</tt><big>(</big><em>sock</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an SFTP client from an existing <a class="reference internal" href="channel.html#paramiko.channel.Channel" title="paramiko.channel.Channel"><tt class="xref py py-obj docutils literal"><span class="pre">Channel</span></tt></a>. The channel
should already have requested the <tt class="docutils literal"><span class="pre">"sftp"</span></tt> subsystem.</p>
<p>An alternate way to create an SFTP client context is by using
<a class="reference internal" href="#paramiko.sftp_client.SFTPClient.from_transport" title="paramiko.sftp_client.SFTPClient.from_transport"><tt class="xref py py-obj docutils literal"><span class="pre">from_transport</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>sock</strong> (<em>.Channel</em>) – an open <a class="reference internal" href="channel.html#paramiko.channel.Channel" title="paramiko.channel.Channel"><tt class="xref py py-obj docutils literal"><span class="pre">Channel</span></tt></a> using the <tt class="docutils literal"><span class="pre">"sftp"</span></tt> subsystem</td>
</tr>
<tr class="field-even field"><th class="field-name" colspan="2">Raises SSHException:</th></tr>
<tr class="field-even field"><td> </td><td class="field-body">if there’s an exception while negotiating
sftp</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.chdir">
<tt class="descname">chdir</tt><big>(</big><em>path=None</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.chdir" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the “current directory” of this SFTP session. Since SFTP
doesn’t really have the concept of a current working directory, this is
emulated by Paramiko. Once you use this method to set a working
directory, all operations on this <a class="reference internal" href="#paramiko.sftp_client.SFTPClient" title="paramiko.sftp_client.SFTPClient"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPClient</span></tt></a> object will be relative
to that path. You can pass in <tt class="docutils literal"><span class="pre">None</span></tt> to stop using a current working
directory.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – new current working directory</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises IOError:</th><td class="field-body">if the requested path doesn’t exist on the server</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.chmod">
<tt class="descname">chmod</tt><big>(</big><em>path</em>, <em>mode</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.chmod" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the mode (permissions) of a file. The permissions are
unix-style and identical to those used by Python’s <a class="reference external" href="http://docs.python.org/2.6/library/os.html#os.chmod" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.chmod</span></tt></a>
function.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path of the file to change the permissions of</li>
<li><strong>mode</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – new permissions</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.chown">
<tt class="descname">chown</tt><big>(</big><em>path</em>, <em>uid</em>, <em>gid</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.chown" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the owner (<tt class="docutils literal"><span class="pre">uid</span></tt>) and group (<tt class="docutils literal"><span class="pre">gid</span></tt>) of a file. As with
Python’s <a class="reference external" href="http://docs.python.org/2.6/library/os.html#os.chown" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.chown</span></tt></a> function, you must pass both arguments, so if you
only want to change one, use <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.stat" title="paramiko.sftp_client.SFTPClient.stat"><tt class="xref py py-obj docutils literal"><span class="pre">stat</span></tt></a> first to retrieve the current
owner and group.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path of the file to change the owner and group of</li>
<li><strong>uid</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – new owner’s uid</li>
<li><strong>gid</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – new group id</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Close the SFTP session and its underlying channel.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.file">
<tt class="descname">file</tt><big>(</big><em>filename</em>, <em>mode='r'</em>, <em>bufsize=-1</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.file" title="Permalink to this definition">¶</a></dt>
<dd><p>Open a file on the remote server. The arguments are the same as for
Python’s built-in <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#file" title="(in Python v2.6)"><tt class="docutils literal"><span class="pre">file</span></tt></a> (aka <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#open" title="(in Python v2.6)"><tt class="docutils literal"><span class="pre">open</span></tt></a>). A file-like
object is returned, which closely mimics the behavior of a normal
Python file object, including the ability to be used as a context
manager.</p>
<p>The mode indicates how the file is to be opened: <tt class="docutils literal"><span class="pre">'r'</span></tt> for reading,
<tt class="docutils literal"><span class="pre">'w'</span></tt> for writing (truncating an existing file), <tt class="docutils literal"><span class="pre">'a'</span></tt> for
appending, <tt class="docutils literal"><span class="pre">'r+'</span></tt> for reading/writing, <tt class="docutils literal"><span class="pre">'w+'</span></tt> for reading/writing
(truncating an existing file), <tt class="docutils literal"><span class="pre">'a+'</span></tt> for reading/appending. The
Python <tt class="docutils literal"><span class="pre">'b'</span></tt> flag is ignored, since SSH treats all files as binary.
The <tt class="docutils literal"><span class="pre">'U'</span></tt> flag is supported in a compatible way.</p>
<p>Since 1.5.2, an <tt class="docutils literal"><span class="pre">'x'</span></tt> flag indicates that the operation should only
succeed if the file was created and did not previously exist. This has
no direct mapping to Python’s file flags, but is commonly known as the
<tt class="docutils literal"><span class="pre">O_EXCL</span></tt> flag in posix.</p>
<p>The file will be buffered in standard Python style by default, but
can be altered with the <tt class="docutils literal"><span class="pre">bufsize</span></tt> parameter. <tt class="docutils literal"><span class="pre">0</span></tt> turns off
buffering, <tt class="docutils literal"><span class="pre">1</span></tt> uses line buffering, and any number greater than 1
(<tt class="docutils literal"><span class="pre">>1</span></tt>) uses that specific buffer size.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>filename</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – name of the file to open</li>
<li><strong>mode</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – mode (Python-style) to open in</li>
<li><strong>bufsize</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – desired buffering (-1 = default buffer size)</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">an <a class="reference internal" href="#paramiko.sftp_file.SFTPFile" title="paramiko.sftp_file.SFTPFile"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPFile</span></tt></a> object representing the open file</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises IOError:</th><td class="field-body"><p class="first last">if the file could not be opened.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="classmethod">
<dt id="paramiko.sftp_client.SFTPClient.from_transport">
<em class="property">classmethod </em><tt class="descname">from_transport</tt><big>(</big><em>t</em>, <em>window_size=None</em>, <em>max_packet_size=None</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.from_transport" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an SFTP client channel from an open <a class="reference internal" href="transport.html#paramiko.transport.Transport" title="paramiko.transport.Transport"><tt class="xref py py-obj docutils literal"><span class="pre">Transport</span></tt></a>.</p>
<p>Setting the window and packet sizes might affect the transfer speed.
The default settings in the <a class="reference internal" href="transport.html#paramiko.transport.Transport" title="paramiko.transport.Transport"><tt class="xref py py-obj docutils literal"><span class="pre">Transport</span></tt></a> class are the same as in
OpenSSH and should work adequately for both files transfers and
interactive sessions.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>t</strong> (<em>.Transport</em>) – an open <a class="reference internal" href="transport.html#paramiko.transport.Transport" title="paramiko.transport.Transport"><tt class="xref py py-obj docutils literal"><span class="pre">Transport</span></tt></a> which is already authenticated</li>
<li><strong>window_size</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – optional window size for the <a class="reference internal" href="#paramiko.sftp_client.SFTPClient" title="paramiko.sftp_client.SFTPClient"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPClient</span></tt></a> session.</li>
<li><strong>max_packet_size</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – optional max packet size for the <a class="reference internal" href="#paramiko.sftp_client.SFTPClient" title="paramiko.sftp_client.SFTPClient"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPClient</span></tt></a> session..</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a new <a class="reference internal" href="#paramiko.sftp_client.SFTPClient" title="paramiko.sftp_client.SFTPClient"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPClient</span></tt></a> object, referring to an sftp session (channel)
across the transport</p>
</td>
</tr>
</tbody>
</table>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.15: </span>Added the <tt class="docutils literal"><span class="pre">window_size</span></tt> and <tt class="docutils literal"><span class="pre">max_packet_size</span></tt> arguments.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.get">
<tt class="descname">get</tt><big>(</big><em>remotepath</em>, <em>localpath</em>, <em>callback=None</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy a remote file (<tt class="docutils literal"><span class="pre">remotepath</span></tt>) from the SFTP server to the local
host as <tt class="docutils literal"><span class="pre">localpath</span></tt>. Any exception raised by operations will be
passed through. This method is primarily provided as a convenience.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>remotepath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the remote file to copy</li>
<li><strong>localpath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the destination path on the local host</li>
<li><strong>callback</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#callable" title="(in Python v2.6)"><em>callable</em></a>) – optional callback function (form: <tt class="docutils literal"><span class="pre">func(int,</span> <span class="pre">int)</span></tt>) that accepts
the bytes transferred so far and the total bytes to be transferred</li>
</ul>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.7.4: </span>Added the <tt class="docutils literal"><span class="pre">callback</span></tt> param</p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.get_channel">
<tt class="descname">get_channel</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.get_channel" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the underlying <a class="reference internal" href="channel.html#paramiko.channel.Channel" title="paramiko.channel.Channel"><tt class="xref py py-obj docutils literal"><span class="pre">Channel</span></tt></a> object for this SFTP session. This
might be useful for doing things like setting a timeout on the channel.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.7.1.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.getcwd">
<tt class="descname">getcwd</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.getcwd" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the “current working directory” for this SFTP session, as
emulated by Paramiko. If no directory has been set with <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.chdir" title="paramiko.sftp_client.SFTPClient.chdir"><tt class="xref py py-obj docutils literal"><span class="pre">chdir</span></tt></a>,
this method will return <tt class="docutils literal"><span class="pre">None</span></tt>.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.getfo">
<tt class="descname">getfo</tt><big>(</big><em>remotepath</em>, <em>fl</em>, <em>callback=None</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.getfo" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy a remote file (<tt class="docutils literal"><span class="pre">remotepath</span></tt>) from the SFTP server and write to
an open file or file-like object, <tt class="docutils literal"><span class="pre">fl</span></tt>. Any exception raised by
operations will be passed through. This method is primarily provided
as a convenience.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>remotepath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#object" title="(in Python v2.6)"><em>object</em></a>) – opened file or file-like object to copy to</li>
<li><strong>fl</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the destination path on the local host or open file object</li>
<li><strong>callback</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#callable" title="(in Python v2.6)"><em>callable</em></a>) – optional callback function (form: <tt class="docutils literal"><span class="pre">func(int,</span> <span class="pre">int)</span></tt>) that accepts
the bytes transferred so far and the total bytes to be transferred</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">the <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">number</span></tt></a> of bytes written to the opened file object</p>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.10.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.listdir">
<tt class="descname">listdir</tt><big>(</big><em>path='.'</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.listdir" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a list containing the names of the entries in the given <tt class="docutils literal"><span class="pre">path</span></tt>.</p>
<p>The list is in arbitrary order. It does not include the special
entries <tt class="docutils literal"><span class="pre">'.'</span></tt> and <tt class="docutils literal"><span class="pre">'..'</span></tt> even if they are present in the folder.
This method is meant to mirror <tt class="docutils literal"><span class="pre">os.listdir</span></tt> as closely as possible.
For a list of full <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> objects, see <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.listdir_attr" title="paramiko.sftp_client.SFTPClient.listdir_attr"><tt class="xref py py-obj docutils literal"><span class="pre">listdir_attr</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path to list (defaults to <tt class="docutils literal"><span class="pre">'.'</span></tt>)</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.listdir_attr">
<tt class="descname">listdir_attr</tt><big>(</big><em>path='.'</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.listdir_attr" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a list containing <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> objects corresponding to
files in the given <tt class="docutils literal"><span class="pre">path</span></tt>. The list is in arbitrary order. It does
not include the special entries <tt class="docutils literal"><span class="pre">'.'</span></tt> and <tt class="docutils literal"><span class="pre">'..'</span></tt> even if they are
present in the folder.</p>
<p>The returned <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> objects will each have an additional
field: <tt class="docutils literal"><span class="pre">longname</span></tt>, which may contain a formatted string of the file’s
attributes, in unix format. The content of this string will probably
depend on the SFTP server implementation.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path to list (defaults to <tt class="docutils literal"><span class="pre">'.'</span></tt>)</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">list of <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> objects</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.2.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.listdir_iter">
<tt class="descname">listdir_iter</tt><big>(</big><em>path='.'</em>, <em>read_aheads=50</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.listdir_iter" title="Permalink to this definition">¶</a></dt>
<dd><p>Generator version of <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.listdir_attr" title="paramiko.sftp_client.SFTPClient.listdir_attr"><tt class="xref py py-obj docutils literal"><span class="pre">listdir_attr</span></tt></a>.</p>
<p>See the API docs for <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.listdir_attr" title="paramiko.sftp_client.SFTPClient.listdir_attr"><tt class="xref py py-obj docutils literal"><span class="pre">listdir_attr</span></tt></a> for overall details.</p>
<p>This function adds one more kwarg on top of <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.listdir_attr" title="paramiko.sftp_client.SFTPClient.listdir_attr"><tt class="xref py py-obj docutils literal"><span class="pre">listdir_attr</span></tt></a>:
<tt class="docutils literal"><span class="pre">read_aheads</span></tt>, an integer controlling how many
<tt class="docutils literal"><span class="pre">SSH_FXP_READDIR</span></tt> requests are made to the server. The default of 50
should suffice for most file listings as each request/response cycle
may contain multiple files (dependant on server implementation.)</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.15.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.lstat">
<tt class="descname">lstat</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.lstat" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve information about a file on the remote system, without
following symbolic links (shortcuts). This otherwise behaves exactly
the same as <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.stat" title="paramiko.sftp_client.SFTPClient.stat"><tt class="xref py py-obj docutils literal"><span class="pre">stat</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the filename to stat</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object containing attributes about the given
file</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.mkdir">
<tt class="descname">mkdir</tt><big>(</big><em>path</em>, <em>mode=511</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.mkdir" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a folder (directory) named <tt class="docutils literal"><span class="pre">path</span></tt> with numeric mode <tt class="docutils literal"><span class="pre">mode</span></tt>.
The default mode is 0777 (octal). On some systems, mode is ignored.
Where it is used, the current umask value is first masked out.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – name of the folder to create</li>
<li><strong>mode</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – permissions (posix-style) for the newly-created folder</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.normalize">
<tt class="descname">normalize</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.normalize" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the normalized path (on the server) of a given path. This
can be used to quickly resolve symbolic links or determine what the
server is considering to be the “current folder” (by passing <tt class="docutils literal"><span class="pre">'.'</span></tt>
as <tt class="docutils literal"><span class="pre">path</span></tt>).</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path to be normalized</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">normalized form of the given path (as a <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>)</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises IOError:</th><td class="field-body">if the path can’t be resolved on the server</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.open">
<tt class="descname">open</tt><big>(</big><em>filename</em>, <em>mode='r'</em>, <em>bufsize=-1</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.open" title="Permalink to this definition">¶</a></dt>
<dd><p>Open a file on the remote server. The arguments are the same as for
Python’s built-in <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#file" title="(in Python v2.6)"><tt class="docutils literal"><span class="pre">file</span></tt></a> (aka <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#open" title="(in Python v2.6)"><tt class="docutils literal"><span class="pre">open</span></tt></a>). A file-like
object is returned, which closely mimics the behavior of a normal
Python file object, including the ability to be used as a context
manager.</p>
<p>The mode indicates how the file is to be opened: <tt class="docutils literal"><span class="pre">'r'</span></tt> for reading,
<tt class="docutils literal"><span class="pre">'w'</span></tt> for writing (truncating an existing file), <tt class="docutils literal"><span class="pre">'a'</span></tt> for
appending, <tt class="docutils literal"><span class="pre">'r+'</span></tt> for reading/writing, <tt class="docutils literal"><span class="pre">'w+'</span></tt> for reading/writing
(truncating an existing file), <tt class="docutils literal"><span class="pre">'a+'</span></tt> for reading/appending. The
Python <tt class="docutils literal"><span class="pre">'b'</span></tt> flag is ignored, since SSH treats all files as binary.
The <tt class="docutils literal"><span class="pre">'U'</span></tt> flag is supported in a compatible way.</p>
<p>Since 1.5.2, an <tt class="docutils literal"><span class="pre">'x'</span></tt> flag indicates that the operation should only
succeed if the file was created and did not previously exist. This has
no direct mapping to Python’s file flags, but is commonly known as the
<tt class="docutils literal"><span class="pre">O_EXCL</span></tt> flag in posix.</p>
<p>The file will be buffered in standard Python style by default, but
can be altered with the <tt class="docutils literal"><span class="pre">bufsize</span></tt> parameter. <tt class="docutils literal"><span class="pre">0</span></tt> turns off
buffering, <tt class="docutils literal"><span class="pre">1</span></tt> uses line buffering, and any number greater than 1
(<tt class="docutils literal"><span class="pre">>1</span></tt>) uses that specific buffer size.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>filename</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – name of the file to open</li>
<li><strong>mode</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – mode (Python-style) to open in</li>
<li><strong>bufsize</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – desired buffering (-1 = default buffer size)</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first">an <a class="reference internal" href="#paramiko.sftp_file.SFTPFile" title="paramiko.sftp_file.SFTPFile"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPFile</span></tt></a> object representing the open file</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises IOError:</th><td class="field-body"><p class="first last">if the file could not be opened.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.put">
<tt class="descname">put</tt><big>(</big><em>localpath</em>, <em>remotepath</em>, <em>callback=None</em>, <em>confirm=True</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.put" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy a local file (<tt class="docutils literal"><span class="pre">localpath</span></tt>) to the SFTP server as <tt class="docutils literal"><span class="pre">remotepath</span></tt>.
Any exception raised by operations will be passed through. This
method is primarily provided as a convenience.</p>
<p>The SFTP operations use pipelining for speed.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>localpath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the local file to copy</li>
<li><strong>remotepath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the destination path on the SFTP server. Note
that the filename should be included. Only specifying a directory
may result in an error.</li>
<li><strong>callback</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#callable" title="(in Python v2.6)"><em>callable</em></a>) – optional callback function (form: <tt class="docutils literal"><span class="pre">func(int,</span> <span class="pre">int)</span></tt>) that accepts
the bytes transferred so far and the total bytes to be transferred</li>
<li><strong>confirm</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#bool" title="(in Python v2.6)"><em>bool</em></a>) – whether to do a stat() on the file afterwards to confirm the file
size</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object containing attributes about the given file</p>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.7.4: </span><tt class="docutils literal"><span class="pre">callback</span></tt> and rich attribute return value added.</p>
</div>
<div class="versionchanged">
<p><span class="versionmodified">Changed in version 1.7.7: </span><tt class="docutils literal"><span class="pre">confirm</span></tt> param added.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.putfo">
<tt class="descname">putfo</tt><big>(</big><em>fl</em>, <em>remotepath</em>, <em>file_size=0</em>, <em>callback=None</em>, <em>confirm=True</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.putfo" title="Permalink to this definition">¶</a></dt>
<dd><p>Copy the contents of an open file object (<tt class="docutils literal"><span class="pre">fl</span></tt>) to the SFTP server as
<tt class="docutils literal"><span class="pre">remotepath</span></tt>. Any exception raised by operations will be passed
through.</p>
<p>The SFTP operations use pipelining for speed.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>fl</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#file" title="(in Python v2.6)"><em>file</em></a>) – opened file or file-like object to copy</li>
<li><strong>remotepath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the destination path on the SFTP server</li>
<li><strong>file_size</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – optional size parameter passed to callback. If none is specified,
size defaults to 0</li>
<li><strong>callback</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#callable" title="(in Python v2.6)"><em>callable</em></a>) – optional callback function (form: <tt class="docutils literal"><span class="pre">func(int,</span> <span class="pre">int)</span></tt>) that accepts
the bytes transferred so far and the total bytes to be transferred
(since 1.7.4)</li>
<li><strong>confirm</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#bool" title="(in Python v2.6)"><em>bool</em></a>) – whether to do a stat() on the file afterwards to confirm the file
size (since 1.7.7)</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object containing attributes about the given
file.</p>
</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.10.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.readlink">
<tt class="descname">readlink</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.readlink" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the target of a symbolic link (shortcut). You can use
<a class="reference internal" href="#paramiko.sftp_client.SFTPClient.symlink" title="paramiko.sftp_client.SFTPClient.symlink"><tt class="xref py py-obj docutils literal"><span class="pre">symlink</span></tt></a> to create these. The result may be either an absolute or
relative pathname.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path of the symbolic link file</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">target path, as a <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a></td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.remove">
<tt class="descname">remove</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.remove" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the file at the given path. This only works on files; for
removing folders (directories), use <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.rmdir" title="paramiko.sftp_client.SFTPClient.rmdir"><tt class="xref py py-obj docutils literal"><span class="pre">rmdir</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path (absolute or relative) of the file to remove</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises IOError:</th><td class="field-body">if the path refers to a folder (directory)</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.rename">
<tt class="descname">rename</tt><big>(</big><em>oldpath</em>, <em>newpath</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.rename" title="Permalink to this definition">¶</a></dt>
<dd><p>Rename a file or folder from <tt class="docutils literal"><span class="pre">oldpath</span></tt> to <tt class="docutils literal"><span class="pre">newpath</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>oldpath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – existing name of the file or folder</li>
<li><strong>newpath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – new name for the file or folder</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises IOError:</th><td class="field-body"><p class="first last">if <tt class="docutils literal"><span class="pre">newpath</span></tt> is a folder, or something else goes
wrong</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.rmdir">
<tt class="descname">rmdir</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.rmdir" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the folder named <tt class="docutils literal"><span class="pre">path</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – name of the folder to remove</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.stat">
<tt class="descname">stat</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.stat" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve information about a file on the remote system. The return
value is an object whose attributes correspond to the attributes of
Python’s <tt class="docutils literal"><span class="pre">stat</span></tt> structure as returned by <tt class="docutils literal"><span class="pre">os.stat</span></tt>, except that it
contains fewer fields. An SFTP server may return as much or as little
info as it wants, so the results may vary from server to server.</p>
<p>Unlike a Python <a class="reference external" href="http://docs.python.org/2.6/library/stat.html#module-stat" title="(in Python v2.6)"><tt class="docutils literal"><span class="pre">stat</span></tt></a> object, the result may not be accessed as
a tuple. This is mostly due to the author’s slack factor.</p>
<p>The fields supported are: <tt class="docutils literal"><span class="pre">st_mode</span></tt>, <tt class="docutils literal"><span class="pre">st_size</span></tt>, <tt class="docutils literal"><span class="pre">st_uid</span></tt>,
<tt class="docutils literal"><span class="pre">st_gid</span></tt>, <tt class="docutils literal"><span class="pre">st_atime</span></tt>, and <tt class="docutils literal"><span class="pre">st_mtime</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the filename to stat</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object containing attributes about the given
file</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.symlink">
<tt class="descname">symlink</tt><big>(</big><em>source</em>, <em>dest</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.symlink" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a symbolic link (shortcut) of the <tt class="docutils literal"><span class="pre">source</span></tt> path at
<tt class="docutils literal"><span class="pre">destination</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>source</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path of the original file</li>
<li><strong>dest</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path of the newly created symlink</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.truncate">
<tt class="descname">truncate</tt><big>(</big><em>path</em>, <em>size</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.truncate" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the size of the file specified by <tt class="docutils literal"><span class="pre">path</span></tt>. This usually
extends or shrinks the size of the file, just like the <a class="reference external" href="http://docs.python.org/2.6/library/stdtypes.html#file.truncate" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">truncate</span></tt></a>
method on Python file objects.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path of the file to modify</li>
<li><strong>size</strong> (<em>int or long</em>) – the new size of the file</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.unlink">
<tt class="descname">unlink</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.unlink" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove the file at the given path. This only works on files; for
removing folders (directories), use <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.rmdir" title="paramiko.sftp_client.SFTPClient.rmdir"><tt class="xref py py-obj docutils literal"><span class="pre">rmdir</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path (absolute or relative) of the file to remove</td>
</tr>
<tr class="field-even field"><th class="field-name">Raises IOError:</th><td class="field-body">if the path refers to a folder (directory)</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_client.SFTPClient.utime">
<tt class="descname">utime</tt><big>(</big><em>path</em>, <em>times</em><big>)</big><a class="headerlink" href="#paramiko.sftp_client.SFTPClient.utime" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the access and modified times of the file specified by <tt class="docutils literal"><span class="pre">path</span></tt>. If
<tt class="docutils literal"><span class="pre">times</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt>, then the file’s access and modified times are set
to the current time. Otherwise, <tt class="docutils literal"><span class="pre">times</span></tt> must be a 2-tuple of numbers,
of the form <tt class="docutils literal"><span class="pre">(atime,</span> <span class="pre">mtime)</span></tt>, which is used to set the access and
modified times, respectively. This bizarre API is mimicked from Python
for the sake of consistency – I apologize.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path of the file to modify</li>
<li><strong>times</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#tuple" title="(in Python v2.6)"><em>tuple</em></a>) – <tt class="docutils literal"><span class="pre">None</span></tt> or a tuple of (access time, modified time) in standard
internet epoch time (seconds since 01 January 1970 GMT)</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<span class="target" id="module-paramiko.sftp_server"></span><p>Server-mode SFTP support.</p>
<dl class="class">
<dt id="paramiko.sftp_server.SFTPServer">
<em class="property">class </em><tt class="descclassname">paramiko.sftp_server.</tt><tt class="descname">SFTPServer</tt><big>(</big><em>channel</em>, <em>name</em>, <em>server</em>, <em>sftp_si=<class 'paramiko.sftp_si.SFTPServerInterface'></em>, <em>*largs</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#paramiko.sftp_server.SFTPServer" title="Permalink to this definition">¶</a></dt>
<dd><p>Server-side SFTP subsystem support. Since this is a <a class="reference internal" href="server.html#paramiko.server.SubsystemHandler" title="paramiko.server.SubsystemHandler"><tt class="xref py py-obj docutils literal"><span class="pre">SubsystemHandler</span></tt></a>,
it can be (and is meant to be) set as the handler for <tt class="docutils literal"><span class="pre">"sftp"</span></tt> requests.
Use <a class="reference internal" href="transport.html#paramiko.transport.Transport.set_subsystem_handler" title="paramiko.transport.Transport.set_subsystem_handler"><tt class="xref py py-obj docutils literal"><span class="pre">Transport.set_subsystem_handler</span></tt></a> to activate this class.</p>
<dl class="method">
<dt id="paramiko.sftp_server.SFTPServer.__init__">
<tt class="descname">__init__</tt><big>(</big><em>channel</em>, <em>name</em>, <em>server</em>, <em>sftp_si=<class 'paramiko.sftp_si.SFTPServerInterface'></em>, <em>*largs</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#paramiko.sftp_server.SFTPServer.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>The constructor for SFTPServer is meant to be called from within the
<a class="reference internal" href="transport.html#paramiko.transport.Transport" title="paramiko.transport.Transport"><tt class="xref py py-obj docutils literal"><span class="pre">Transport</span></tt></a> as a subsystem handler. <tt class="docutils literal"><span class="pre">server</span></tt> and any additional
parameters or keyword parameters are passed from the original call to
<a class="reference internal" href="transport.html#paramiko.transport.Transport.set_subsystem_handler" title="paramiko.transport.Transport.set_subsystem_handler"><tt class="xref py py-obj docutils literal"><span class="pre">Transport.set_subsystem_handler</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>channel</strong> (<em>.Channel</em>) – channel passed from the <a class="reference internal" href="transport.html#paramiko.transport.Transport" title="paramiko.transport.Transport"><tt class="xref py py-obj docutils literal"><span class="pre">Transport</span></tt></a>.</li>
<li><strong>name</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – name of the requested subsystem.</li>
<li><strong>server</strong> (<em>.ServerInterface</em>) – the server object associated with this channel and subsystem</li>
<li><strong>sftp_si</strong> (<em>class</em>) – a subclass of <a class="reference internal" href="#paramiko.sftp_si.SFTPServerInterface" title="paramiko.sftp_si.SFTPServerInterface"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPServerInterface</span></tt></a> to use for handling individual
requests.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="staticmethod">
<dt id="paramiko.sftp_server.SFTPServer.convert_errno">
<em class="property">static </em><tt class="descname">convert_errno</tt><big>(</big><em>e</em><big>)</big><a class="headerlink" href="#paramiko.sftp_server.SFTPServer.convert_errno" title="Permalink to this definition">¶</a></dt>
<dd><p>Convert an errno value (as from an <tt class="docutils literal"><span class="pre">OSError</span></tt> or <tt class="docutils literal"><span class="pre">IOError</span></tt>) into a
standard SFTP result code. This is a convenience function for trapping
exceptions in server code and returning an appropriate result.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>e</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – an errno code, as from <tt class="docutils literal"><span class="pre">OSError.errno</span></tt>.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">an <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> SFTP error code like <tt class="docutils literal"><span class="pre">SFTP_NO_SUCH_FILE</span></tt>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="staticmethod">
<dt id="paramiko.sftp_server.SFTPServer.set_file_attr">
<em class="property">static </em><tt class="descname">set_file_attr</tt><big>(</big><em>filename</em>, <em>attr</em><big>)</big><a class="headerlink" href="#paramiko.sftp_server.SFTPServer.set_file_attr" title="Permalink to this definition">¶</a></dt>
<dd><p>Change a file’s attributes on the local filesystem. The contents of
<tt class="docutils literal"><span class="pre">attr</span></tt> are used to change the permissions, owner, group ownership,
and/or modification & access time of the file, depending on which
attributes are present in <tt class="docutils literal"><span class="pre">attr</span></tt>.</p>
<p>This is meant to be a handy helper function for translating SFTP file
requests into local file operations.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>filename</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – name of the file to alter (should usually be an absolute path).</li>
<li><strong>attr</strong> (<em>.SFTPAttributes</em>) – attributes to change.</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<span class="target" id="module-paramiko.sftp_attr"></span><dl class="class">
<dt id="paramiko.sftp_attr.SFTPAttributes">
<em class="property">class </em><tt class="descclassname">paramiko.sftp_attr.</tt><tt class="descname">SFTPAttributes</tt><a class="headerlink" href="#paramiko.sftp_attr.SFTPAttributes" title="Permalink to this definition">¶</a></dt>
<dd><p>Representation of the attributes of a file (or proxied file) for SFTP in
client or server mode. It attemps to mirror the object returned by
<a class="reference external" href="http://docs.python.org/2.6/library/os.html#os.stat" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.stat</span></tt></a> as closely as possible, so it may have the following fields,
with the same meanings as those returned by an <a class="reference external" href="http://docs.python.org/2.6/library/os.html#os.stat" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.stat</span></tt></a> object:</p>
<blockquote>
<div><ul class="simple">
<li><tt class="docutils literal"><span class="pre">st_size</span></tt></li>
<li><tt class="docutils literal"><span class="pre">st_uid</span></tt></li>
<li><tt class="docutils literal"><span class="pre">st_gid</span></tt></li>
<li><tt class="docutils literal"><span class="pre">st_mode</span></tt></li>
<li><tt class="docutils literal"><span class="pre">st_atime</span></tt></li>
<li><tt class="docutils literal"><span class="pre">st_mtime</span></tt></li>
</ul>
</div></blockquote>
<p>Because SFTP allows flags to have other arbitrary named attributes, these
are stored in a dict named <tt class="docutils literal"><span class="pre">attr</span></tt>. Occasionally, the filename is also
stored, in <tt class="docutils literal"><span class="pre">filename</span></tt>.</p>
<dl class="method">
<dt id="paramiko.sftp_attr.SFTPAttributes.__init__">
<tt class="descname">__init__</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_attr.SFTPAttributes.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new (empty) SFTPAttributes object. All fields will be empty.</p>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_attr.SFTPAttributes.__str__">
<tt class="descname">__str__</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_attr.SFTPAttributes.__str__" title="Permalink to this definition">¶</a></dt>
<dd><p>create a unix-style long description of the file (like ls -l)</p>
</dd></dl>
<dl class="attribute">
<dt id="paramiko.sftp_attr.SFTPAttributes.__weakref__">
<tt class="descname">__weakref__</tt><a class="headerlink" href="#paramiko.sftp_attr.SFTPAttributes.__weakref__" title="Permalink to this definition">¶</a></dt>
<dd><p>list of weak references to the object (if defined)</p>
</dd></dl>
<dl class="classmethod">
<dt id="paramiko.sftp_attr.SFTPAttributes.from_stat">
<em class="property">classmethod </em><tt class="descname">from_stat</tt><big>(</big><em>obj</em>, <em>filename=None</em><big>)</big><a class="headerlink" href="#paramiko.sftp_attr.SFTPAttributes.from_stat" title="Permalink to this definition">¶</a></dt>
<dd><p>Create an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object from an existing <tt class="docutils literal"><span class="pre">stat</span></tt> object (an
object returned by <a class="reference external" href="http://docs.python.org/2.6/library/os.html#os.stat" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.stat</span></tt></a>).</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>obj</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#object" title="(in Python v2.6)"><em>object</em></a>) – an object returned by <a class="reference external" href="http://docs.python.org/2.6/library/os.html#os.stat" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.stat</span></tt></a> (or equivalent).</li>
<li><strong>filename</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the filename associated with this file.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">new <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object with the same attribute fields.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<span class="target" id="module-paramiko.sftp_file"></span><p>SFTP file object</p>
<dl class="class">
<dt id="paramiko.sftp_file.SFTPFile">
<em class="property">class </em><tt class="descclassname">paramiko.sftp_file.</tt><tt class="descname">SFTPFile</tt><big>(</big><em>sftp</em>, <em>handle</em>, <em>mode='r'</em>, <em>bufsize=-1</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile" title="Permalink to this definition">¶</a></dt>
<dd><p>Bases: <a class="reference internal" href="file.html#paramiko.file.BufferedFile" title="paramiko.file.BufferedFile"><tt class="xref py py-class docutils literal"><span class="pre">paramiko.file.BufferedFile</span></tt></a></p>
<p>Proxy object for a file on the remote server, in client mode SFTP.</p>
<p>Instances of this class may be used as context managers in the same way
that built-in Python file objects are.</p>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.check">
<tt class="descname">check</tt><big>(</big><em>hash_algorithm</em>, <em>offset=0</em>, <em>length=0</em>, <em>block_size=0</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.check" title="Permalink to this definition">¶</a></dt>
<dd><p>Ask the server for a hash of a section of this file. This can be used
to verify a successful upload or download, or for various rsync-like
operations.</p>
<p>The file is hashed from <tt class="docutils literal"><span class="pre">offset</span></tt>, for <tt class="docutils literal"><span class="pre">length</span></tt> bytes. If <tt class="docutils literal"><span class="pre">length</span></tt>
is 0, the remainder of the file is hashed. Thus, if both <tt class="docutils literal"><span class="pre">offset</span></tt>
and <tt class="docutils literal"><span class="pre">length</span></tt> are zero, the entire file is hashed.</p>
<p>Normally, <tt class="docutils literal"><span class="pre">block_size</span></tt> will be 0 (the default), and this method will
return a byte string representing the requested hash (for example, a
string of length 16 for MD5, or 20 for SHA-1). If a non-zero
<tt class="docutils literal"><span class="pre">block_size</span></tt> is given, each chunk of the file (from <tt class="docutils literal"><span class="pre">offset</span></tt> to
<tt class="docutils literal"><span class="pre">offset</span> <span class="pre">+</span> <span class="pre">length</span></tt>) of <tt class="docutils literal"><span class="pre">block_size</span></tt> bytes is computed as a separate
hash. The hash results are all concatenated and returned as a single
string.</p>
<p>For example, <tt class="docutils literal"><span class="pre">check('sha1',</span> <span class="pre">0,</span> <span class="pre">1024,</span> <span class="pre">512)</span></tt> will return a string of
length 40. The first 20 bytes will be the SHA-1 of the first 512 bytes
of the file, and the last 20 bytes will be the SHA-1 of the next 512
bytes.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>hash_algorithm</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the name of the hash algorithm to use (normally <tt class="docutils literal"><span class="pre">"sha1"</span></tt> or
<tt class="docutils literal"><span class="pre">"md5"</span></tt>)</li>
<li><strong>offset</strong> (<em>int or long</em>) – offset into the file to begin hashing (0 means to start from the
beginning)</li>
<li><strong>length</strong> (<em>int or long</em>) – number of bytes to hash (0 means continue to the end of the file)</li>
<li><strong>block_size</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – number of bytes to hash per result (must not be less than 256; 0
means to compute only one hash of the entire segment)</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first"><a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a> of bytes representing the hash of each block, concatenated
together</p>
</td>
</tr>
<tr class="field-odd field"><th class="field-name">Raises IOError:</th><td class="field-body"><p class="first last">if the server doesn’t support the “check-file”
extension, or possibly doesn’t support the hash algorithm
requested</p>
</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Many (most?) servers don’t support this extension yet.</p>
</div>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.4.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.chmod">
<tt class="descname">chmod</tt><big>(</big><em>mode</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.chmod" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the mode (permissions) of this file. The permissions are
unix-style and identical to those used by Python’s <a class="reference external" href="http://docs.python.org/2.6/library/os.html#os.chmod" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.chmod</span></tt></a>
function.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>mode</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – new permissions</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.chown">
<tt class="descname">chown</tt><big>(</big><em>uid</em>, <em>gid</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.chown" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the owner (<tt class="docutils literal"><span class="pre">uid</span></tt>) and group (<tt class="docutils literal"><span class="pre">gid</span></tt>) of this file. As with
Python’s <a class="reference external" href="http://docs.python.org/2.6/library/os.html#os.chown" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.chown</span></tt></a> function, you must pass both arguments, so if you
only want to change one, use <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.stat" title="paramiko.sftp_file.SFTPFile.stat"><tt class="xref py py-obj docutils literal"><span class="pre">stat</span></tt></a> first to retrieve the current
owner and group.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
<li><strong>uid</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – new owner’s uid</li>
<li><strong>gid</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – new group id</li>
</ul>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.close" title="Permalink to this definition">¶</a></dt>
<dd><p>Close the file.</p>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.flush">
<tt class="descname">flush</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.flush" title="Permalink to this definition">¶</a></dt>
<dd><p>Write out any data in the write buffer. This may do nothing if write
buffering is not turned on.</p>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.gettimeout">
<tt class="descname">gettimeout</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.gettimeout" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the timeout in seconds (as a <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#float" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">float</span></tt></a>) associated with the
socket or ssh <a class="reference internal" href="channel.html#paramiko.channel.Channel" title="paramiko.channel.Channel"><tt class="xref py py-obj docutils literal"><span class="pre">Channel</span></tt></a> used for this file.</p>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="channel.html#paramiko.channel.Channel.gettimeout" title="paramiko.channel.Channel.gettimeout"><tt class="xref py py-obj docutils literal"><span class="pre">Channel.gettimeout</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.next">
<tt class="descname">next</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.next" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the next line from the input, or raises
<a class="reference external" href="http://docs.python.org/2.6/library/exceptions.html#exceptions.StopIteration" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">StopIteration</span></tt></a> when EOF is hit. Unlike Python file
objects, it’s okay to mix calls to <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.next" title="paramiko.sftp_file.SFTPFile.next"><tt class="xref py py-obj docutils literal"><span class="pre">next</span></tt></a> and <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.readline" title="paramiko.sftp_file.SFTPFile.readline"><tt class="xref py py-obj docutils literal"><span class="pre">readline</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name" colspan="2">Raises StopIteration:</th></tr>
<tr class="field-odd field"><td> </td><td class="field-body">when the end of the file is reached.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">a line (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>) read from the file.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.prefetch">
<tt class="descname">prefetch</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.prefetch" title="Permalink to this definition">¶</a></dt>
<dd><p>Pre-fetch the remaining contents of this file in anticipation of future
<a class="reference internal" href="#paramiko.sftp_file.SFTPFile.read" title="paramiko.sftp_file.SFTPFile.read"><tt class="xref py py-obj docutils literal"><span class="pre">read</span></tt></a> calls. If reading the entire file, pre-fetching can
dramatically improve the download speed by avoiding roundtrip latency.
The file’s contents are incrementally buffered in a background thread.</p>
<p>The prefetched data is stored in a buffer until read via the <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.read" title="paramiko.sftp_file.SFTPFile.read"><tt class="xref py py-obj docutils literal"><span class="pre">read</span></tt></a>
method. Once data has been read, it’s removed from the buffer. The
data may be read in a random order (using <a class="reference internal" href="file.html#paramiko.file.BufferedFile.seek" title="paramiko.file.BufferedFile.seek"><tt class="xref py py-obj docutils literal"><span class="pre">seek</span></tt></a>); chunks of the
buffer that haven’t been read will continue to be buffered.</p>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.1.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.read">
<tt class="descname">read</tt><big>(</big><em>size=None</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Read at most <tt class="docutils literal"><span class="pre">size</span></tt> bytes from the file (less if we hit the end of the
file first). If the <tt class="docutils literal"><span class="pre">size</span></tt> argument is negative or omitted, read all
the remaining data in the file.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last"><tt class="docutils literal"><span class="pre">'b'</span></tt> mode flag is ignored (<tt class="docutils literal"><span class="pre">self.FLAG_BINARY</span></tt> in
<tt class="docutils literal"><span class="pre">self._flags</span></tt>), because SSH treats all files as binary, since we
have no idea what encoding the file is in, or even if the file is
text data.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>size</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – maximum number of bytes to read</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">data read from the file (as bytes), or an empty string if EOF was
encountered immediately</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.readline">
<tt class="descname">readline</tt><big>(</big><em>size=None</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.readline" title="Permalink to this definition">¶</a></dt>
<dd><p>Read one entire line from the file. A trailing newline character is
kept in the string (but may be absent when a file ends with an
incomplete line). If the size argument is present and non-negative, it
is a maximum byte count (including the trailing newline) and an
incomplete line may be returned. An empty string is returned only when
EOF is encountered immediately.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Unlike stdio’s <tt class="docutils literal"><span class="pre">fgets</span></tt>, the returned string contains null
characters (<tt class="docutils literal"><span class="pre">'\0'</span></tt>) if they occurred in the input.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>size</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – maximum length of returned string.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">next line of the file, or an empty string if the end of the
file has been reached.<p>If the file was opened in binary (<tt class="docutils literal"><span class="pre">'b'</span></tt>) mode: bytes are returned
Else: the encoding of the file is assumed to be UTF-8 and character
strings (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>) are returned</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.readlines">
<tt class="descname">readlines</tt><big>(</big><em>sizehint=None</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.readlines" title="Permalink to this definition">¶</a></dt>
<dd><p>Read all remaining lines using <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.readline" title="paramiko.sftp_file.SFTPFile.readline"><tt class="xref py py-obj docutils literal"><span class="pre">readline</span></tt></a> and return them as a list.
If the optional <tt class="docutils literal"><span class="pre">sizehint</span></tt> argument is present, instead of reading up
to EOF, whole lines totalling approximately sizehint bytes (possibly
after rounding up to an internal buffer size) are read.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>sizehint</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – desired maximum number of bytes to read.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><a class="reference external" href="http://docs.python.org/2.6/library/functions.html#list" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">list</span></tt></a> of lines read from the file.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.readv">
<tt class="descname">readv</tt><big>(</big><em>chunks</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.readv" title="Permalink to this definition">¶</a></dt>
<dd><p>Read a set of blocks from the file by (offset, length). This is more
efficient than doing a series of <a class="reference internal" href="file.html#paramiko.file.BufferedFile.seek" title="paramiko.file.BufferedFile.seek"><tt class="xref py py-obj docutils literal"><span class="pre">seek</span></tt></a> and <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.read" title="paramiko.sftp_file.SFTPFile.read"><tt class="xref py py-obj docutils literal"><span class="pre">read</span></tt></a> calls, since the
prefetch machinery is used to retrieve all the requested blocks at
once.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>chunks</strong> (<em>list(tuple(long, int))</em>) – a list of (offset, length) tuples indicating which sections of the
file to read</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">a list of blocks read, in the same order as in <tt class="docutils literal"><span class="pre">chunks</span></tt></td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.4.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.set_pipelined">
<tt class="descname">set_pipelined</tt><big>(</big><em>pipelined=True</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.set_pipelined" title="Permalink to this definition">¶</a></dt>
<dd><p>Turn on/off the pipelining of write operations to this file. When
pipelining is on, paramiko won’t wait for the server response after
each write operation. Instead, they’re collected as they come in. At
the first non-write operation (including <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.close" title="paramiko.sftp_file.SFTPFile.close"><tt class="xref py py-obj docutils literal"><span class="pre">close</span></tt></a>), all remaining
server responses are collected. This means that if there was an error
with one of your later writes, an exception might be thrown from within
<a class="reference internal" href="#paramiko.sftp_file.SFTPFile.close" title="paramiko.sftp_file.SFTPFile.close"><tt class="xref py py-obj docutils literal"><span class="pre">close</span></tt></a> instead of <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.write" title="paramiko.sftp_file.SFTPFile.write"><tt class="xref py py-obj docutils literal"><span class="pre">write</span></tt></a>.</p>
<p>By default, files are not pipelined.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>pipelined</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#bool" title="(in Python v2.6)"><em>bool</em></a>) – <tt class="docutils literal"><span class="pre">True</span></tt> if pipelining should be turned on for this file; <tt class="docutils literal"><span class="pre">False</span></tt>
otherwise</td>
</tr>
</tbody>
</table>
<div class="versionadded">
<p><span class="versionmodified">New in version 1.5.</span></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.setblocking">
<tt class="descname">setblocking</tt><big>(</big><em>blocking</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.setblocking" title="Permalink to this definition">¶</a></dt>
<dd><p>Set blocking or non-blocking mode on the underiying socket or ssh
<a class="reference internal" href="channel.html#paramiko.channel.Channel" title="paramiko.channel.Channel"><tt class="xref py py-obj docutils literal"><span class="pre">Channel</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>blocking</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – 0 to set non-blocking mode; non-0 to set blocking mode.</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="channel.html#paramiko.channel.Channel.setblocking" title="paramiko.channel.Channel.setblocking"><tt class="xref py py-obj docutils literal"><span class="pre">Channel.setblocking</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.settimeout">
<tt class="descname">settimeout</tt><big>(</big><em>timeout</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.settimeout" title="Permalink to this definition">¶</a></dt>
<dd><p>Set a timeout on read/write operations on the underlying socket or
ssh <a class="reference internal" href="channel.html#paramiko.channel.Channel" title="paramiko.channel.Channel"><tt class="xref py py-obj docutils literal"><span class="pre">Channel</span></tt></a>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>timeout</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#float" title="(in Python v2.6)"><em>float</em></a>) – seconds to wait for a pending read/write operation before raising
<tt class="docutils literal"><span class="pre">socket.timeout</span></tt>, or <tt class="docutils literal"><span class="pre">None</span></tt> for no timeout</td>
</tr>
</tbody>
</table>
<div class="admonition seealso">
<p class="first admonition-title">See also</p>
<p class="last"><a class="reference internal" href="channel.html#paramiko.channel.Channel.settimeout" title="paramiko.channel.Channel.settimeout"><tt class="xref py py-obj docutils literal"><span class="pre">Channel.settimeout</span></tt></a></p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.stat">
<tt class="descname">stat</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.stat" title="Permalink to this definition">¶</a></dt>
<dd><p>Retrieve information about this file from the remote system. This is
exactly like <a class="reference internal" href="#paramiko.sftp_client.SFTPClient.stat" title="paramiko.sftp_client.SFTPClient.stat"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPClient.stat</span></tt></a>, except that it operates on an
already-open file.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object containing attributes about this file.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.tell">
<tt class="descname">tell</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.tell" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the file’s current position. This may not be accurate or
useful if the underlying file doesn’t support random access, or was
opened in append mode.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">file position (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">number</span></tt></a> of bytes).</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.truncate">
<tt class="descname">truncate</tt><big>(</big><em>size</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.truncate" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the size of this file. This usually extends
or shrinks the size of the file, just like the <tt class="docutils literal"><span class="pre">truncate()</span></tt> method on
Python file objects.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>size</strong> (<em>int or long</em>) – the new size of the file</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.utime">
<tt class="descname">utime</tt><big>(</big><em>times</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.utime" title="Permalink to this definition">¶</a></dt>
<dd><p>Set the access and modified times of this file. If
<tt class="docutils literal"><span class="pre">times</span></tt> is <tt class="docutils literal"><span class="pre">None</span></tt>, then the file’s access and modified times are set
to the current time. Otherwise, <tt class="docutils literal"><span class="pre">times</span></tt> must be a 2-tuple of numbers,
of the form <tt class="docutils literal"><span class="pre">(atime,</span> <span class="pre">mtime)</span></tt>, which is used to set the access and
modified times, respectively. This bizarre API is mimicked from Python
for the sake of consistency – I apologize.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>times</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#tuple" title="(in Python v2.6)"><em>tuple</em></a>) – <tt class="docutils literal"><span class="pre">None</span></tt> or a tuple of (access time, modified time) in standard
internet epoch time (seconds since 01 January 1970 GMT)</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.write">
<tt class="descname">write</tt><big>(</big><em>data</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Write data to the file. If write buffering is on (<tt class="docutils literal"><span class="pre">bufsize</span></tt> was
specified and non-zero), some or all of the data may not actually be
written yet. (Use <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.flush" title="paramiko.sftp_file.SFTPFile.flush"><tt class="xref py py-obj docutils literal"><span class="pre">flush</span></tt></a> or <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.close" title="paramiko.sftp_file.SFTPFile.close"><tt class="xref py py-obj docutils literal"><span class="pre">close</span></tt></a> to force buffered data to be
written out.)</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>data</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – data to write</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.writelines">
<tt class="descname">writelines</tt><big>(</big><em>sequence</em><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.writelines" title="Permalink to this definition">¶</a></dt>
<dd><p>Write a sequence of strings to the file. The sequence can be any
iterable object producing strings, typically a list of strings. (The
name is intended to match <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.readlines" title="paramiko.sftp_file.SFTPFile.readlines"><tt class="xref py py-obj docutils literal"><span class="pre">readlines</span></tt></a>; <a class="reference internal" href="#paramiko.sftp_file.SFTPFile.writelines" title="paramiko.sftp_file.SFTPFile.writelines"><tt class="xref py py-obj docutils literal"><span class="pre">writelines</span></tt></a> does not add line
separators.)</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>sequence</strong> (<em>iterable</em>) – an iterable sequence of strings.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_file.SFTPFile.xreadlines">
<tt class="descname">xreadlines</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_file.SFTPFile.xreadlines" title="Permalink to this definition">¶</a></dt>
<dd><p>Identical to <tt class="docutils literal"><span class="pre">iter(f)</span></tt>. This is a deprecated file interface that
predates Python iterator support.</p>
</dd></dl>
</dd></dl>
<span class="target" id="module-paramiko.sftp_handle"></span><p>Abstraction of an SFTP file handle (for server mode).</p>
<dl class="class">
<dt id="paramiko.sftp_handle.SFTPHandle">
<em class="property">class </em><tt class="descclassname">paramiko.sftp_handle.</tt><tt class="descname">SFTPHandle</tt><big>(</big><em>flags=0</em><big>)</big><a class="headerlink" href="#paramiko.sftp_handle.SFTPHandle" title="Permalink to this definition">¶</a></dt>
<dd><p>Abstract object representing a handle to an open file (or folder) in an
SFTP server implementation. Each handle has a string representation used
by the client to refer to the underlying file.</p>
<p>Server implementations can (and should) subclass SFTPHandle to implement
features of a file handle, like <a class="reference internal" href="#paramiko.sftp_handle.SFTPHandle.stat" title="paramiko.sftp_handle.SFTPHandle.stat"><tt class="xref py py-obj docutils literal"><span class="pre">stat</span></tt></a> or <a class="reference internal" href="#paramiko.sftp_handle.SFTPHandle.chattr" title="paramiko.sftp_handle.SFTPHandle.chattr"><tt class="xref py py-obj docutils literal"><span class="pre">chattr</span></tt></a>.</p>
<p>Instances of this class may be used as context managers.</p>
<dl class="method">
<dt id="paramiko.sftp_handle.SFTPHandle.__init__">
<tt class="descname">__init__</tt><big>(</big><em>flags=0</em><big>)</big><a class="headerlink" href="#paramiko.sftp_handle.SFTPHandle.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new file handle representing a local file being served over
SFTP. If <tt class="docutils literal"><span class="pre">flags</span></tt> is passed in, it’s used to determine if the file
is open in append mode.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>flags</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – optional flags as passed to <a class="reference internal" href="#paramiko.sftp_si.SFTPServerInterface.open" title="paramiko.sftp_si.SFTPServerInterface.open"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPServerInterface.open</span></tt></a></td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_handle.SFTPHandle.chattr">
<tt class="descname">chattr</tt><big>(</big><em>attr</em><big>)</big><a class="headerlink" href="#paramiko.sftp_handle.SFTPHandle.chattr" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the attributes of this file. The <tt class="docutils literal"><span class="pre">attr</span></tt> object will contain
only those fields provided by the client in its request, so you should
check for the presence of fields before using them.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>attr</strong> (<em>.SFTPAttributes</em>) – the attributes to change on this file.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">an <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> error code like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_OK</span></tt>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_handle.SFTPHandle.close">
<tt class="descname">close</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_handle.SFTPHandle.close" title="Permalink to this definition">¶</a></dt>
<dd><p>When a client closes a file, this method is called on the handle.
Normally you would use this method to close the underlying OS level
file object(s).</p>
<p>The default implementation checks for attributes on <tt class="docutils literal"><span class="pre">self</span></tt> named
<tt class="docutils literal"><span class="pre">readfile</span></tt> and/or <tt class="docutils literal"><span class="pre">writefile</span></tt>, and if either or both are present,
their <tt class="docutils literal"><span class="pre">close()</span></tt> methods are called. This means that if you are
using the default implementations of <a class="reference internal" href="#paramiko.sftp_handle.SFTPHandle.read" title="paramiko.sftp_handle.SFTPHandle.read"><tt class="xref py py-obj docutils literal"><span class="pre">read</span></tt></a> and <a class="reference internal" href="#paramiko.sftp_handle.SFTPHandle.write" title="paramiko.sftp_handle.SFTPHandle.write"><tt class="xref py py-obj docutils literal"><span class="pre">write</span></tt></a>, this
method’s default implementation should be fine also.</p>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_handle.SFTPHandle.read">
<tt class="descname">read</tt><big>(</big><em>offset</em>, <em>length</em><big>)</big><a class="headerlink" href="#paramiko.sftp_handle.SFTPHandle.read" title="Permalink to this definition">¶</a></dt>
<dd><p>Read up to <tt class="docutils literal"><span class="pre">length</span></tt> bytes from this file, starting at position
<tt class="docutils literal"><span class="pre">offset</span></tt>. The offset may be a Python long, since SFTP allows it
to be 64 bits.</p>
<p>If the end of the file has been reached, this method may return an
empty string to signify EOF, or it may also return <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_EOF</span></tt>.</p>
<p>The default implementation checks for an attribute on <tt class="docutils literal"><span class="pre">self</span></tt> named
<tt class="docutils literal"><span class="pre">readfile</span></tt>, and if present, performs the read operation on the Python
file-like object found there. (This is meant as a time saver for the
common case where you are wrapping a Python file object.)</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>offset</strong> (<em>int or long</em>) – position in the file to start reading from.</li>
<li><strong>length</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – number of bytes to attempt to read.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">data read from the file, or an SFTP error code, as a <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a>.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_handle.SFTPHandle.stat">
<tt class="descname">stat</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_handle.SFTPHandle.stat" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object referring to this open file, or an
error code. This is equivalent to <a class="reference internal" href="#paramiko.sftp_si.SFTPServerInterface.stat" title="paramiko.sftp_si.SFTPServerInterface.stat"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPServerInterface.stat</span></tt></a>, except
it’s called on an open file instead of a path.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Returns:</th><td class="field-body">an attributes object for the given file, or an SFTP error code
(like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_PERMISSION_DENIED</span></tt>).</td>
</tr>
<tr class="field-even field"><th class="field-name">Return type:</th><td class="field-body"><a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> or error code</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_handle.SFTPHandle.write">
<tt class="descname">write</tt><big>(</big><em>offset</em>, <em>data</em><big>)</big><a class="headerlink" href="#paramiko.sftp_handle.SFTPHandle.write" title="Permalink to this definition">¶</a></dt>
<dd><p>Write <tt class="docutils literal"><span class="pre">data</span></tt> into this file at position <tt class="docutils literal"><span class="pre">offset</span></tt>. Extending the
file past its original end is expected. Unlike Python’s normal
<tt class="docutils literal"><span class="pre">write()</span></tt> methods, this method cannot do a partial write: it must
write all of <tt class="docutils literal"><span class="pre">data</span></tt> or else return an error.</p>
<p>The default implementation checks for an attribute on <tt class="docutils literal"><span class="pre">self</span></tt> named
<tt class="docutils literal"><span class="pre">writefile</span></tt>, and if present, performs the write operation on the
Python file-like object found there. The attribute is named
differently from <tt class="docutils literal"><span class="pre">readfile</span></tt> to make it easy to implement read-only
(or write-only) files, but if both attributes are present, they should
refer to the same file.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>offset</strong> (<em>int or long</em>) – position in the file to start reading from.</li>
<li><strong>data</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – data to write into the file.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">an SFTP error code like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_OK</span></tt>.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
<span class="target" id="module-paramiko.sftp_si"></span><p>An interface to override for SFTP server support.</p>
<dl class="class">
<dt id="paramiko.sftp_si.SFTPServerInterface">
<em class="property">class </em><tt class="descclassname">paramiko.sftp_si.</tt><tt class="descname">SFTPServerInterface</tt><big>(</big><em>server</em>, <em>*largs</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface" title="Permalink to this definition">¶</a></dt>
<dd><p>This class defines an interface for controlling the behavior of paramiko
when using the <a class="reference internal" href="#paramiko.sftp_server.SFTPServer" title="paramiko.sftp_server.SFTPServer"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPServer</span></tt></a> subsystem to provide an SFTP server.</p>
<p>Methods on this class are called from the SFTP session’s thread, so you can
block as long as necessary without affecting other sessions (even other
SFTP sessions). However, raising an exception will usually cause the SFTP
session to abruptly end, so you will usually want to catch exceptions and
return an appropriate error code.</p>
<p>All paths are in string form instead of unicode because not all SFTP
clients & servers obey the requirement that paths be encoded in UTF-8.</p>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.__init__">
<tt class="descname">__init__</tt><big>(</big><em>server</em>, <em>*largs</em>, <em>**kwargs</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.__init__" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new SFTPServerInterface object. This method does nothing by
default and is meant to be overridden by subclasses.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>server</strong> (<em>.ServerInterface</em>) – the server object associated with this channel and SFTP subsystem</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="attribute">
<dt id="paramiko.sftp_si.SFTPServerInterface.__weakref__">
<tt class="descname">__weakref__</tt><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.__weakref__" title="Permalink to this definition">¶</a></dt>
<dd><p>list of weak references to the object (if defined)</p>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.canonicalize">
<tt class="descname">canonicalize</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.canonicalize" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the canonical form of a path on the server. For example,
if the server’s home folder is <tt class="docutils literal"><span class="pre">/home/foo</span></tt>, the path
<tt class="docutils literal"><span class="pre">"../betty"</span></tt> would be canonicalized to <tt class="docutils literal"><span class="pre">"/home/betty"</span></tt>. Note
the obvious security issues: if you’re serving files only from a
specific folder, you probably don’t want this method to reveal path
names outside that folder.</p>
<p>You may find the Python methods in <tt class="docutils literal"><span class="pre">os.path</span></tt> useful, especially
<tt class="docutils literal"><span class="pre">os.path.normpath</span></tt> and <tt class="docutils literal"><span class="pre">os.path.realpath</span></tt>.</p>
<p>The default implementation returns <tt class="docutils literal"><span class="pre">os.path.normpath('/'</span> <span class="pre">+</span> <span class="pre">path)</span></tt>.</p>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.chattr">
<tt class="descname">chattr</tt><big>(</big><em>path</em>, <em>attr</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.chattr" title="Permalink to this definition">¶</a></dt>
<dd><p>Change the attributes of a file. The <tt class="docutils literal"><span class="pre">attr</span></tt> object will contain
only those fields provided by the client in its request, so you
should check for the presence of fields before using them.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – requested path (relative or absolute) of the file to change.</li>
<li><strong>attr</strong> – requested attributes to change on the file (an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a>
object)</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">an error code <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_OK</span></tt>.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.list_folder">
<tt class="descname">list_folder</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.list_folder" title="Permalink to this definition">¶</a></dt>
<dd><p>Return a list of files within a given folder. The <tt class="docutils literal"><span class="pre">path</span></tt> will use
posix notation (<tt class="docutils literal"><span class="pre">"/"</span></tt> separates folder names) and may be an absolute
or relative path.</p>
<p>The list of files is expected to be a list of <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a>
objects, which are similar in structure to the objects returned by
<tt class="docutils literal"><span class="pre">os.stat</span></tt>. In addition, each object should have its <tt class="docutils literal"><span class="pre">filename</span></tt>
field filled in, since this is important to a directory listing and
not normally present in <tt class="docutils literal"><span class="pre">os.stat</span></tt> results. The method
<a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes.from_stat" title="paramiko.sftp_attr.SFTPAttributes.from_stat"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes.from_stat</span></tt></a> will usually do what you want.</p>
<p>In case of an error, you should return one of the <tt class="docutils literal"><span class="pre">SFTP_*</span></tt> error
codes, such as <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_PERMISSION_DENIED</span></tt>.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the requested path (relative or absolute) to be listed.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">a list of the files in the given folder, using <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a>
objects.</td>
</tr>
</tbody>
</table>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You should normalize the given <tt class="docutils literal"><span class="pre">path</span></tt> first (see the <a class="reference external" href="http://docs.python.org/2.6/library/os.path.html#module-os.path" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">os.path</span></tt></a>
module) and check appropriate permissions before returning the list
of files. Be careful of malicious clients attempting to use
relative paths to escape restricted folders, if you’re doing a
direct translation from the SFTP server path to your local
filesystem.</p>
</div>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.lstat">
<tt class="descname">lstat</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.lstat" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object for a path on the server, or an
error code. If your server supports symbolic links (also known as
“aliases”), you should not follow them – instead, you should
return data on the symlink or alias itself. (<a class="reference internal" href="#paramiko.sftp_si.SFTPServerInterface.stat" title="paramiko.sftp_si.SFTPServerInterface.stat"><tt class="xref py py-obj docutils literal"><span class="pre">stat</span></tt></a> is the
corresponding call that follows symlinks/aliases.)</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the requested path (relative or absolute) to fetch file statistics
for.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object for the given file, or an SFTP error
code (like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_PERMISSION_DENIED</span></tt>).</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.mkdir">
<tt class="descname">mkdir</tt><big>(</big><em>path</em>, <em>attr</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.mkdir" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a new directory with the given attributes. The <tt class="docutils literal"><span class="pre">attr</span></tt>
object may be considered a “hint” and ignored.</p>
<p>The <tt class="docutils literal"><span class="pre">attr</span></tt> object will contain only those fields provided by the
client in its request, so you should use <tt class="docutils literal"><span class="pre">hasattr</span></tt> to check for
the presense of fields before using them. In some cases, the <tt class="docutils literal"><span class="pre">attr</span></tt>
object may be completely empty.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – requested path (relative or absolute) of the new folder.</li>
<li><strong>attr</strong> (<em>.SFTPAttributes</em>) – requested attributes of the new folder.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">an SFTP error code <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_OK</span></tt>.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.open">
<tt class="descname">open</tt><big>(</big><em>path</em>, <em>flags</em>, <em>attr</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.open" title="Permalink to this definition">¶</a></dt>
<dd><p>Open a file on the server and create a handle for future operations
on that file. On success, a new object subclassed from <a class="reference internal" href="#paramiko.sftp_handle.SFTPHandle" title="paramiko.sftp_handle.SFTPHandle"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPHandle</span></tt></a>
should be returned. This handle will be used for future operations
on the file (read, write, etc). On failure, an error code such as
<tt class="xref py py-obj docutils literal"><span class="pre">SFTP_PERMISSION_DENIED</span></tt> should be returned.</p>
<p><tt class="docutils literal"><span class="pre">flags</span></tt> contains the requested mode for opening (read-only,
write-append, etc) as a bitset of flags from the <tt class="docutils literal"><span class="pre">os</span></tt> module:</p>
<blockquote>
<div><ul class="simple">
<li><tt class="docutils literal"><span class="pre">os.O_RDONLY</span></tt></li>
<li><tt class="docutils literal"><span class="pre">os.O_WRONLY</span></tt></li>
<li><tt class="docutils literal"><span class="pre">os.O_RDWR</span></tt></li>
<li><tt class="docutils literal"><span class="pre">os.O_APPEND</span></tt></li>
<li><tt class="docutils literal"><span class="pre">os.O_CREAT</span></tt></li>
<li><tt class="docutils literal"><span class="pre">os.O_TRUNC</span></tt></li>
<li><tt class="docutils literal"><span class="pre">os.O_EXCL</span></tt></li>
</ul>
</div></blockquote>
<p>(One of <tt class="docutils literal"><span class="pre">os.O_RDONLY</span></tt>, <tt class="docutils literal"><span class="pre">os.O_WRONLY</span></tt>, or <tt class="docutils literal"><span class="pre">os.O_RDWR</span></tt> will always
be set.)</p>
<p>The <tt class="docutils literal"><span class="pre">attr</span></tt> object contains requested attributes of the file if it
has to be created. Some or all attribute fields may be missing if
the client didn’t specify them.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The SFTP protocol defines all files to be in “binary” mode.
There is no equivalent to Python’s “text” mode.</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the requested path (relative or absolute) of the file to be opened.</li>
<li><strong>flags</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><em>int</em></a>) – flags or’d together from the <tt class="docutils literal"><span class="pre">os</span></tt> module indicating the requested
mode for opening the file.</li>
<li><strong>attr</strong> (<em>.SFTPAttributes</em>) – requested attributes of the file if it is newly created.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">a new <a class="reference internal" href="#paramiko.sftp_handle.SFTPHandle" title="paramiko.sftp_handle.SFTPHandle"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPHandle</span></tt></a> or error code.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.readlink">
<tt class="descname">readlink</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.readlink" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the target of a symbolic link (or shortcut) on the server.
If the specified path doesn’t refer to a symbolic link, an error
should be returned.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path (relative or absolute) of the symbolic link.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">the target <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">str</span></tt></a> path of the symbolic link, or an error code like
<tt class="xref py py-obj docutils literal"><span class="pre">SFTP_NO_SUCH_FILE</span></tt>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.remove">
<tt class="descname">remove</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.remove" title="Permalink to this definition">¶</a></dt>
<dd><p>Delete a file, if possible.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the requested path (relative or absolute) of the file to delete.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">an SFTP error code <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_OK</span></tt>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.rename">
<tt class="descname">rename</tt><big>(</big><em>oldpath</em>, <em>newpath</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.rename" title="Permalink to this definition">¶</a></dt>
<dd><p>Rename (or move) a file. The SFTP specification implies that this
method can be used to move an existing file into a different folder,
and since there’s no other (easy) way to move files via SFTP, it’s
probably a good idea to implement “move” in this method too, even for
files that cross disk partition boundaries, if at all possible.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">You should return an error if a file with the same name as
<tt class="docutils literal"><span class="pre">newpath</span></tt> already exists. (The rename operation should be
non-desctructive.)</p>
</div>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>oldpath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the requested path (relative or absolute) of the existing file.</li>
<li><strong>newpath</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the requested new path of the file.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">an SFTP error code <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_OK</span></tt>.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.rmdir">
<tt class="descname">rmdir</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.rmdir" title="Permalink to this definition">¶</a></dt>
<dd><p>Remove a directory if it exists. The <tt class="docutils literal"><span class="pre">path</span></tt> should refer to an
existing, empty folder – otherwise this method should return an
error.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – requested path (relative or absolute) of the folder to remove.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">an SFTP error code <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_OK</span></tt>.</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.session_ended">
<tt class="descname">session_ended</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.session_ended" title="Permalink to this definition">¶</a></dt>
<dd><p>The SFTP server session has just ended, either cleanly or via an
exception. This method is meant to be overridden to perform any
necessary cleanup before this <a class="reference internal" href="#paramiko.sftp_si.SFTPServerInterface" title="paramiko.sftp_si.SFTPServerInterface"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPServerInterface</span></tt></a> object is
destroyed.</p>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.session_started">
<tt class="descname">session_started</tt><big>(</big><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.session_started" title="Permalink to this definition">¶</a></dt>
<dd><p>The SFTP server session has just started. This method is meant to be
overridden to perform any necessary setup before handling callbacks
from SFTP operations.</p>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.stat">
<tt class="descname">stat</tt><big>(</big><em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.stat" title="Permalink to this definition">¶</a></dt>
<dd><p>Return an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object for a path on the server, or an
error code. If your server supports symbolic links (also known as
“aliases”), you should follow them. (<a class="reference internal" href="#paramiko.sftp_si.SFTPServerInterface.lstat" title="paramiko.sftp_si.SFTPServerInterface.lstat"><tt class="xref py py-obj docutils literal"><span class="pre">lstat</span></tt></a> is the corresponding
call that doesn’t follow symlinks/aliases.)</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – the requested path (relative or absolute) to fetch file statistics
for.</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body">an <a class="reference internal" href="#paramiko.sftp_attr.SFTPAttributes" title="paramiko.sftp_attr.SFTPAttributes"><tt class="xref py py-obj docutils literal"><span class="pre">SFTPAttributes</span></tt></a> object for the given file, or an SFTP error
code (like <tt class="xref py py-obj docutils literal"><span class="pre">SFTP_PERMISSION_DENIED</span></tt>).</td>
</tr>
</tbody>
</table>
</dd></dl>
<dl class="method">
<dt id="paramiko.sftp_si.SFTPServerInterface.symlink">
<tt class="descname">symlink</tt><big>(</big><em>target_path</em>, <em>path</em><big>)</big><a class="headerlink" href="#paramiko.sftp_si.SFTPServerInterface.symlink" title="Permalink to this definition">¶</a></dt>
<dd><p>Create a symbolic link on the server, as new pathname <tt class="docutils literal"><span class="pre">path</span></tt>,
with <tt class="docutils literal"><span class="pre">target_path</span></tt> as the target of the link.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first simple">
<li><strong>target_path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path (relative or absolute) of the target for this new symbolic
link.</li>
<li><strong>path</strong> (<a class="reference external" href="http://docs.python.org/2.6/library/functions.html#str" title="(in Python v2.6)"><em>str</em></a>) – path (relative or absolute) of the symbolic link to create.</li>
</ul>
</td>
</tr>
<tr class="field-even field"><th class="field-name">Returns:</th><td class="field-body"><p class="first last">an error code <a class="reference external" href="http://docs.python.org/2.6/library/functions.html#int" title="(in Python v2.6)"><tt class="xref py py-obj docutils literal"><span class="pre">int</span></tt></a> like <tt class="docutils literal"><span class="pre">SFTP_OK</span></tt>.</p>
</td>
</tr>
</tbody>
</table>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h1 class="logo"><a href="../index.html">Paramiko</a></h1>
<p class="blurb">A Python implementation of SSHv2.</p>
<p>
<iframe src="http://ghbtns.com/github-btn.html?user=paramiko&repo=paramiko&type=watch&count=true&size=large"
allowtransparency="true" frameborder="0" scrolling="0" width="200px" height="35px"></iframe>
</p>
<p>
<a href="https://travis-ci.org/paramiko/paramiko">
<img
alt="https://secure.travis-ci.org/paramiko/paramiko.png?branch=master"
src="https://secure.travis-ci.org/paramiko/paramiko.png?branch=master"
>
</a>
</p>
<h3>Navigation</h3>
<ul>
<li class="toctree-l1"><a class="reference internal" href="channel.html">Channel</a></li>
<li class="toctree-l1"><a class="reference internal" href="client.html">Client</a></li>
<li class="toctree-l1"><a class="reference internal" href="message.html">Message</a></li>
<li class="toctree-l1"><a class="reference internal" href="packet.html">Packetizer</a></li>
<li class="toctree-l1"><a class="reference internal" href="transport.html">Transport</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="agent.html">SSH agents</a></li>
<li class="toctree-l1"><a class="reference internal" href="hostkeys.html">Host keys / <tt class="docutils literal"><span class="pre">known_hosts</span></tt> files</a></li>
<li class="toctree-l1"><a class="reference internal" href="keys.html">Key handling</a></li>
<li class="toctree-l1"><a class="reference internal" href="ssh_gss.html">GSS-API authentication</a></li>
<li class="toctree-l1"><a class="reference internal" href="kex_gss.html">GSS-API key exchange</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="config.html">Configuration</a></li>
<li class="toctree-l1"><a class="reference internal" href="proxy.html"><tt class="docutils literal"><span class="pre">ProxyCommand</span></tt> support</a></li>
<li class="toctree-l1"><a class="reference internal" href="server.html">Server implementation</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="">SFTP</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="buffered_pipe.html">Buffered pipes</a></li>
<li class="toctree-l1"><a class="reference internal" href="file.html">Buffered files</a></li>
<li class="toctree-l1"><a class="reference internal" href="pipe.html">Cross-platform pipe implementations</a></li>
<li class="toctree-l1"><a class="reference internal" href="ssh_exception.html">Exceptions</a></li>
</ul>
<hr />
<ul>
<li class="toctree-l1"><a href="http://www.paramiko.org">Main website</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<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>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
<h3>Donate</h3>
<p>
Consider supporting the authors on <a href="https://www.gratipay.com/">Gratipay</a>:
<script data-gratipay-username="bitprophet"
data-gratipay-widget="button"
src="//gttp.co/v1.js"></script>
</p>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©2014 Jeff Forcier.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.2.2</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.6.1</a>
|
<a href="../_sources/api/sftp.txt"
rel="nofollow">Page source</a></li>
</div>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-18486793-2']);
_gaq.push(['_setDomainName', 'none']);
_gaq.push(['_setAllowLinker', true]);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</body>
</html>