dorian
/
paramiko
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

SFTP done, ugh

This commit is contained in:
Jeff Forcier 2014-02-26 15:25:48 -08:00
parent dd9934f2b5
commit de99785ef0
6 changed files with 197 additions and 273 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
paramiko/sftp_attr.py
View File

@ -65,12 +65,9 @@ class SFTPAttributes (object):
Create an `.SFTPAttributes` object from an existing ``stat`` object (an Create an `.SFTPAttributes` object from an existing ``stat`` object (an
object returned by `os.stat`). object returned by `os.stat`).
:param obj: an object returned by `os.stat` (or equivalent). :param object obj: an object returned by `os.stat` (or equivalent).
:type obj: object :param str filename: the filename associated with this file.
:param filename: the filename associated with this file.
:type filename: str
:return: new `.SFTPAttributes` object with the same attribute fields. :return: new `.SFTPAttributes` object with the same attribute fields.
:rtype: `.SFTPAttributes`
""" """
attr = cls() attr = cls()
attr.st_size = obj.st_size attr.st_size = obj.st_size

217
paramiko/sftp_client.py
View File

@ -61,8 +61,7 @@ class SFTPClient(BaseSFTP):
An alternate way to create an SFTP client context is by using An alternate way to create an SFTP client context is by using
`from_transport`. `from_transport`.
:param sock: an open `.Channel` using the ``"sftp"`` subsystem :param .Channel sock: an open `.Channel` using the ``"sftp"`` subsystem
:type sock: `.Channel`
:raises SSHException: if there's an exception while negotiating :raises SSHException: if there's an exception while negotiating
sftp sftp
@ -91,11 +90,10 @@ class SFTPClient(BaseSFTP):
""" """
Create an SFTP client channel from an open `.Transport`. Create an SFTP client channel from an open `.Transport`.
:param t: an open `.Transport` which is already authenticated :param .Transport t: an open `.Transport` which is already authenticated
:type t: `.Transport` :return:
:return: a new `.SFTPClient` object, referring to an sftp session a new `.SFTPClient` object, referring to an sftp session (channel)
(channel) across the transport across the transport
:rtype: `.SFTPClient`
""" """
chan = t.open_session() chan = t.open_session()
if chan is None: if chan is None:
@ -125,9 +123,6 @@ class SFTPClient(BaseSFTP):
Return the underlying `.Channel` object for this SFTP session. This Return the underlying `.Channel` object for this SFTP session. This
might be useful for doing things like setting a timeout on the channel. might be useful for doing things like setting a timeout on the channel.
:return: the SSH channel
:rtype: `.Channel`
.. versionadded:: 1.7.1 .. versionadded:: 1.7.1
""" """
return self.sock return self.sock
@ -135,15 +130,13 @@ class SFTPClient(BaseSFTP):
def listdir(self, path='.'): def listdir(self, path='.'):
""" """
Return a list containing the names of the entries in the given ``path``. Return a list containing the names of the entries in the given ``path``.
The list is in arbitrary order. It does not include the special The list is in arbitrary order. It does not include the special
entries ``'.'`` and ``'..'`` even if they are present in the folder. entries ``'.'`` and ``'..'`` even if they are present in the folder.
This method is meant to mirror ``os.listdir`` as closely as possible. This method is meant to mirror ``os.listdir`` as closely as possible.
For a list of full `.SFTPAttributes` objects, see `listdir_attr`. For a list of full `.SFTPAttributes` objects, see `listdir_attr`.
:param path: path to list (defaults to ``'.'``) :param str path: path to list (defaults to ``'.'``)
:type path: str
:return: list of filenames
:rtype: list of str
""" """
return [f.filename for f in self.listdir_attr(path)] return [f.filename for f in self.listdir_attr(path)]
@ -159,10 +152,8 @@ class SFTPClient(BaseSFTP):
attributes, in unix format. The content of this string will probably attributes, in unix format. The content of this string will probably
depend on the SFTP server implementation. depend on the SFTP server implementation.
:param path: path to list (defaults to ``'.'``) :param str path: path to list (defaults to ``'.'``)
:type path: str :return: list of `.SFTPAttributes` objects
:return: list of attributes
:rtype: list of `.SFTPAttributes`
.. versionadded:: 1.2 .. versionadded:: 1.2
""" """
@ -216,14 +207,10 @@ class SFTPClient(BaseSFTP):
buffering, ``1`` uses line buffering, and any number greater than 1 buffering, ``1`` uses line buffering, and any number greater than 1
(``>1``) uses that specific buffer size. (``>1``) uses that specific buffer size.
:param filename: name of the file to open :param str filename: name of the file to open
:type filename: str :param str mode: mode (Python-style) to open in
:param mode: mode (Python-style) to open in :param int bufsize: desired buffering (-1 = default buffer size)
:type mode: str :return: an `.SFTPFile` object representing the open file
:param bufsize: desired buffering (-1 = default buffer size)
:type bufsize: int
:return: a file object representing the open file
:rtype: `.SFTPFile`
:raises IOError: if the file could not be opened. :raises IOError: if the file could not be opened.
""" """
@ -256,8 +243,7 @@ class SFTPClient(BaseSFTP):
Remove the file at the given path. This only works on files; for Remove the file at the given path. This only works on files; for
removing folders (directories), use `rmdir`. removing folders (directories), use `rmdir`.
:param path: path (absolute or relative) of the file to remove :param str path: path (absolute or relative) of the file to remove
:type path: str
:raises IOError: if the path refers to a folder (directory) :raises IOError: if the path refers to a folder (directory)
""" """
@ -271,10 +257,8 @@ class SFTPClient(BaseSFTP):
""" """
Rename a file or folder from ``oldpath`` to ``newpath``. Rename a file or folder from ``oldpath`` to ``newpath``.
:param oldpath: existing name of the file or folder :param str oldpath: existing name of the file or folder
:type oldpath: str :param str newpath: new name for the file or folder
:param newpath: new name for the file or folder
:type newpath: str
:raises IOError: if ``newpath`` is a folder, or something else goes :raises IOError: if ``newpath`` is a folder, or something else goes
wrong wrong
@ -290,10 +274,8 @@ class SFTPClient(BaseSFTP):
The default mode is 0777 (octal). On some systems, mode is ignored. The default mode is 0777 (octal). On some systems, mode is ignored.
Where it is used, the current umask value is first masked out. Where it is used, the current umask value is first masked out.
:param path: name of the folder to create :param str path: name of the folder to create
:type path: str :param int mode: permissions (posix-style) for the newly-created folder
:param mode: permissions (posix-style) for the newly-created folder
:type mode: int
""" """
path = self._adjust_cwd(path) path = self._adjust_cwd(path)
self._log(DEBUG, 'mkdir(%r, %r)' % (path, mode)) self._log(DEBUG, 'mkdir(%r, %r)' % (path, mode))
@ -305,8 +287,7 @@ class SFTPClient(BaseSFTP):
""" """
Remove the folder named ``path``. Remove the folder named ``path``.
:param path: name of the folder to remove :param str path: name of the folder to remove
:type path: str
""" """
path = self._adjust_cwd(path) path = self._adjust_cwd(path)
self._log(DEBUG, 'rmdir(%r)' % path) self._log(DEBUG, 'rmdir(%r)' % path)
@ -326,10 +307,10 @@ class SFTPClient(BaseSFTP):
The fields supported are: ``st_mode``, ``st_size``, ``st_uid``, The fields supported are: ``st_mode``, ``st_size``, ``st_uid``,
``st_gid``, ``st_atime``, and ``st_mtime``. ``st_gid``, ``st_atime``, and ``st_mtime``.
:param path: the filename to stat :param str path: the filename to stat
:type path: str :return:
:return: an object containing attributes about the given file an `.SFTPAttributes` object containing attributes about the given
:rtype: `.SFTPAttributes` file
""" """
path = self._adjust_cwd(path) path = self._adjust_cwd(path)
self._log(DEBUG, 'stat(%r)' % path) self._log(DEBUG, 'stat(%r)' % path)
@ -344,10 +325,10 @@ class SFTPClient(BaseSFTP):
following symbolic links (shortcuts). This otherwise behaves exactly following symbolic links (shortcuts). This otherwise behaves exactly
the same as `stat`. the same as `stat`.
:param path: the filename to stat :param str path: the filename to stat
:type path: str :return:
:return: an object containing attributes about the given file an `.SFTPAttributes` object containing attributes about the given
:rtype: `.SFTPAttributes` file
""" """
path = self._adjust_cwd(path) path = self._adjust_cwd(path)
self._log(DEBUG, 'lstat(%r)' % path) self._log(DEBUG, 'lstat(%r)' % path)
@ -361,10 +342,8 @@ class SFTPClient(BaseSFTP):
Create a symbolic link (shortcut) of the ``source`` path at Create a symbolic link (shortcut) of the ``source`` path at
``destination``. ``destination``.
:param source: path of the original file :param str source: path of the original file
:type source: str :param str dest: path of the newly created symlink
:param dest: path of the newly created symlink
:type dest: str
""" """
dest = self._adjust_cwd(dest) dest = self._adjust_cwd(dest)
self._log(DEBUG, 'symlink(%r, %r)' % (source, dest)) self._log(DEBUG, 'symlink(%r, %r)' % (source, dest))
@ -378,10 +357,8 @@ class SFTPClient(BaseSFTP):
unix-style and identical to those used by Python's `os.chmod` unix-style and identical to those used by Python's `os.chmod`
function. function.
:param path: path of the file to change the permissions of :param str path: path of the file to change the permissions of
:type path: str :param int mode: new permissions
:param mode: new permissions
:type mode: int
""" """
path = self._adjust_cwd(path) path = self._adjust_cwd(path)
self._log(DEBUG, 'chmod(%r, %r)' % (path, mode)) self._log(DEBUG, 'chmod(%r, %r)' % (path, mode))
@ -396,12 +373,9 @@ class SFTPClient(BaseSFTP):
only want to change one, use `stat` first to retrieve the current only want to change one, use `stat` first to retrieve the current
owner and group. owner and group.
:param path: path of the file to change the owner and group of :param str path: path of the file to change the owner and group of
:type path: str :param int uid: new owner's uid
:param uid: new owner's uid :param int gid: new group id
:type uid: int
:param gid: new group id
:type gid: int
""" """
path = self._adjust_cwd(path) path = self._adjust_cwd(path)
self._log(DEBUG, 'chown(%r, %r, %r)' % (path, uid, gid)) self._log(DEBUG, 'chown(%r, %r, %r)' % (path, uid, gid))
@ -418,11 +392,10 @@ class SFTPClient(BaseSFTP):
modified times, respectively. This bizarre API is mimicked from Python modified times, respectively. This bizarre API is mimicked from Python
for the sake of consistency -- I apologize. for the sake of consistency -- I apologize.
:param path: path of the file to modify :param str path: path of the file to modify
:type path: str :param tuple times:
:param times: ``None`` or a tuple of (access time, modified time) in ``None`` or a tuple of (access time, modified time) in standard
standard internet epoch time (seconds since 01 January 1970 GMT) internet epoch time (seconds since 01 January 1970 GMT)
:type times: tuple(int)
""" """
path = self._adjust_cwd(path) path = self._adjust_cwd(path)
if times is None: if times is None:
@ -438,8 +411,7 @@ class SFTPClient(BaseSFTP):
extends or shrinks the size of the file, just like the `~file.truncate` extends or shrinks the size of the file, just like the `~file.truncate`
method on Python file objects. method on Python file objects.
:param path: path of the file to modify :param str path: path of the file to modify
:type path: str
:param size: the new size of the file :param size: the new size of the file
:type size: int or long :type size: int or long
""" """
@ -455,10 +427,8 @@ class SFTPClient(BaseSFTP):
`symlink` to create these. The result may be either an absolute or `symlink` to create these. The result may be either an absolute or
relative pathname. relative pathname.
:param path: path of the symbolic link file :param str path: path of the symbolic link file
:type path: str :return: target path, as a `str`
:return: target path
:rtype: str
""" """
path = self._adjust_cwd(path) path = self._adjust_cwd(path)
self._log(DEBUG, 'readlink(%r)' % path) self._log(DEBUG, 'readlink(%r)' % path)
@ -479,10 +449,8 @@ class SFTPClient(BaseSFTP):
server is considering to be the "current folder" (by passing ``'.'`` server is considering to be the "current folder" (by passing ``'.'``
as ``path``). as ``path``).
:param path: path to be normalized :param str path: path to be normalized
:type path: str :return: normalized form of the given path (as a `str`)
:return: normalized form of the given path
:rtype: str
:raises IOError: if the path can't be resolved on the server :raises IOError: if the path can't be resolved on the server
""" """
@ -505,8 +473,7 @@ class SFTPClient(BaseSFTP):
to that path. You can pass in ``None`` to stop using a current working to that path. You can pass in ``None`` to stop using a current working
directory. directory.
:param path: new current working directory :param str path: new current working directory
:type path: str
:raises IOError: if the requested path doesn't exist on the server :raises IOError: if the requested path doesn't exist on the server
@ -525,9 +492,6 @@ class SFTPClient(BaseSFTP):
emulated by Paramiko. If no directory has been set with `chdir`, emulated by Paramiko. If no directory has been set with `chdir`,
this method will return ``None``. this method will return ``None``.
:return: the current working directory on the server, or ``None``
:rtype: str
.. versionadded:: 1.4 .. versionadded:: 1.4
""" """
return self._cwd return self._cwd
@ -540,26 +504,26 @@ class SFTPClient(BaseSFTP):
The SFTP operations use pipelining for speed. The SFTP operations use pipelining for speed.
:param fl: opened file or file-like object to copy :param file fl: opened file or file-like object to copy
:type localpath: object :param str remotepath: the destination path on the SFTP server
:param remotepath: the destination path on the SFTP server :param int file_size:
:type remotepath: str optional size parameter passed to callback. If none is specified,
:param file_size: optional size parameter passed to callback. If none is size defaults to 0
specified, size defaults to 0 :param callable callback:
:type file_size: int optional callback function (form: ``func(int, int)``) that accepts
:param callback: optional callback function that accepts the bytes the bytes transferred so far and the total bytes to be transferred
transferred so far and the total bytes to be transferred
(since 1.7.4) (since 1.7.4)
:type callback: function(int, int) :param bool confirm:
:param confirm: whether to do a stat() on the file afterwards to whether to do a stat() on the file afterwards to confirm the file
confirm the file size (since 1.7.7) size (since 1.7.7)
:type confirm: bool
:return: an object containing attributes about the given file :return:
(since 1.7.4) an `.SFTPAttributes` object containing attributes about the given
:rtype: `.SFTPAttributes` file.
.. versionadded:: 1.4 .. versionadded:: 1.4
.. versionchanged:: 1.7.4
Began returning rich attribute objects.
""" """
fr = self.file(remotepath, 'wb') fr = self.file(remotepath, 'wb')
fr.set_pipelined(True) fr.set_pipelined(True)
@ -591,23 +555,22 @@ class SFTPClient(BaseSFTP):
The SFTP operations use pipelining for speed. The SFTP operations use pipelining for speed.
:param localpath: the local file to copy :param str localpath: the local file to copy
:type localpath: str :param str remotepath: the destination path on the SFTP server
:param remotepath: the destination path on the SFTP server :param callable callback:
:type remotepath: str optional callback function (form: ``func(int, int)``) that accepts
:param callback: optional callback function that accepts the bytes the bytes transferred so far and the total bytes to be transferred
transferred so far and the total bytes to be transferred :param bool confirm:
(since 1.7.4) whether to do a stat() on the file afterwards to confirm the file
:type callback: function(int, int) size
:param confirm: whether to do a stat() on the file afterwards to
confirm the file size (since 1.7.7)
:type confirm: bool
:return: an object containing attributes about the given file :return: an `.SFTPAttributes` object containing attributes about the given file
(since 1.7.4)
:rtype: `.SFTPAttributes`
.. versionadded:: 1.4 .. versionadded:: 1.4
.. versionchanged:: 1.7.4
``callback`` and rich attribute return value added.
.. versionchanged:: 1.7.7
``confirm`` param added.
""" """
file_size = os.stat(localpath).st_size file_size = os.stat(localpath).st_size
fl = file(localpath, 'rb') fl = file(localpath, 'rb')
@ -623,18 +586,17 @@ class SFTPClient(BaseSFTP):
operations will be passed through. This method is primarily provided operations will be passed through. This method is primarily provided
as a convenience. as a convenience.
:param remotepath: opened file or file-like object to copy to :param object remotepath: opened file or file-like object to copy to
:type remotepath: object :param str fl:
:param fl: the destination path on the local host or open file the destination path on the local host or open file object
object :param callable callback:
:type localpath: str optional callback function (form: ``func(int, int)``) that accepts
:param callback: optional callback function that accepts the bytes the bytes transferred so far and the total bytes to be transferred
transferred so far and the total bytes to be transferred :return: the `number <int>` of bytes written to the opened file object
(since 1.7.4)
:type callback: function(int, int)
:return: the number of bytes written to the opened file object
.. versionadded:: 1.4 .. versionadded:: 1.4
.. versionchanged:: 1.7.4
Added the ``callable`` param.
""" """
fr = self.file(remotepath, 'rb') fr = self.file(remotepath, 'rb')
file_size = self.stat(remotepath).st_size file_size = self.stat(remotepath).st_size
@ -659,16 +621,15 @@ class SFTPClient(BaseSFTP):
host as ``localpath``. Any exception raised by operations will be host as ``localpath``. Any exception raised by operations will be
passed through. This method is primarily provided as a convenience. passed through. This method is primarily provided as a convenience.
:param remotepath: the remote file to copy :param str remotepath: the remote file to copy
:type remotepath: str :param str localpath: the destination path on the local host
:param localpath: the destination path on the local host :param callable callback:
:type localpath: str optional callback function (form: ``func(int, int)``) that accepts
:param callback: optional callback function that accepts the bytes the bytes transferred so far and the total bytes to be transferred
transferred so far and the total bytes to be transferred
(since 1.7.4)
:type callback: function(int, int)
.. versionadded:: 1.4 .. versionadded:: 1.4
.. versionchanged:: 1.7.4
Added the ``callback`` param
""" """
file_size = self.stat(remotepath).st_size file_size = self.stat(remotepath).st_size
fl = file(localpath, 'wb') fl = file(localpath, 'wb')

71
paramiko/sftp_file.py
View File

@ -186,9 +186,9 @@ class SFTPFile (BufferedFile):
Set a timeout on read/write operations on the underlying socket or Set a timeout on read/write operations on the underlying socket or
ssh `.Channel`. ssh `.Channel`.
:param timeout: seconds to wait for a pending read/write operation :param float timeout:
before raising ``socket.timeout``, or ``None`` for no timeout seconds to wait for a pending read/write operation before raising
:type timeout: float ``socket.timeout``, or ``None`` for no timeout
.. seealso:: `.Channel.settimeout` .. seealso:: `.Channel.settimeout`
""" """
@ -196,10 +196,8 @@ class SFTPFile (BufferedFile):
def gettimeout(self): def gettimeout(self):
""" """
Returns the timeout in seconds (as a float) associated with the socket Returns the timeout in seconds (as a `float`) associated with the
or ssh `.Channel` used for this file. socket or ssh `.Channel` used for this file.
:rtype: float
.. seealso:: `.Channel.gettimeout` .. seealso:: `.Channel.gettimeout`
""" """
@ -210,9 +208,8 @@ class SFTPFile (BufferedFile):
Set blocking or non-blocking mode on the underiying socket or ssh Set blocking or non-blocking mode on the underiying socket or ssh
`.Channel`. `.Channel`.
:param blocking: :param int blocking:
0 to set non-blocking mode; non-0 to set blocking mode. 0 to set non-blocking mode; non-0 to set blocking mode.
:type blocking: int
.. seealso:: `.Channel.setblocking` .. seealso:: `.Channel.setblocking`
""" """
@ -235,8 +232,7 @@ class SFTPFile (BufferedFile):
exactly like `.SFTPClient.stat`, except that it operates on an exactly like `.SFTPClient.stat`, except that it operates on an
already-open file. already-open file.
:return: an object containing attributes about this file. :return: an `.SFTPAttributes` object containing attributes about this file.
:rtype: `.SFTPAttributes`
""" """
t, msg = self.sftp._request(CMD_FSTAT, self.handle) t, msg = self.sftp._request(CMD_FSTAT, self.handle)
if t != CMD_ATTRS: if t != CMD_ATTRS:
@ -249,8 +245,7 @@ class SFTPFile (BufferedFile):
unix-style and identical to those used by Python's `os.chmod` unix-style and identical to those used by Python's `os.chmod`
function. function.
:param mode: new permissions :param int mode: new permissions
:type mode: int
""" """
self.sftp._log(DEBUG, 'chmod(%s, %r)' % (hexlify(self.handle), mode)) self.sftp._log(DEBUG, 'chmod(%s, %r)' % (hexlify(self.handle), mode))
attr = SFTPAttributes() attr = SFTPAttributes()
@ -264,10 +259,8 @@ class SFTPFile (BufferedFile):
only want to change one, use `stat` first to retrieve the current only want to change one, use `stat` first to retrieve the current
owner and group. owner and group.
:param uid: new owner's uid :param int uid: new owner's uid
:type uid: int :param int gid: new group id
:param gid: new group id
:type gid: int
""" """
self.sftp._log(DEBUG, 'chown(%s, %r, %r)' % (hexlify(self.handle), uid, gid)) self.sftp._log(DEBUG, 'chown(%s, %r, %r)' % (hexlify(self.handle), uid, gid))
attr = SFTPAttributes() attr = SFTPAttributes()
@ -283,9 +276,9 @@ class SFTPFile (BufferedFile):
modified times, respectively. This bizarre API is mimicked from Python modified times, respectively. This bizarre API is mimicked from Python
for the sake of consistency -- I apologize. for the sake of consistency -- I apologize.
:param times: ``None`` or a tuple of (access time, modified time) in :param tuple times:
standard internet epoch time (seconds since 01 January 1970 GMT) ``None`` or a tuple of (access time, modified time) in standard
:type times: tuple(int) internet epoch time (seconds since 01 January 1970 GMT)
""" """
if times is None: if times is None:
times = (time.time(), time.time()) times = (time.time(), time.time())
@ -331,21 +324,23 @@ class SFTPFile (BufferedFile):
of the file, and the last 20 bytes will be the SHA-1 of the next 512 of the file, and the last 20 bytes will be the SHA-1 of the next 512
bytes. bytes.
:param hash_algorithm: the name of the hash algorithm to use (normally :param str hash_algorithm:
``"sha1"`` or ``"md5"``) the name of the hash algorithm to use (normally ``"sha1"`` or
:type hash_algorithm: str ``"md5"``)
:param offset: offset into the file to begin hashing (0 means to start :param offset:
from the beginning) offset into the file to begin hashing (0 means to start from the
beginning)
:type offset: int or long :type offset: int or long
:param length: number of bytes to hash (0 means continue to the end of :param length:
the file) number of bytes to hash (0 means continue to the end of the file)
:type length: int or long :type length: int or long
:param block_size: number of bytes to hash per result (must not be less :param int block_size:
than 256; 0 means to compute only one hash of the entire segment) number of bytes to hash per result (must not be less than 256; 0
means to compute only one hash of the entire segment)
:type block_size: int :type block_size: int
:return: string of bytes representing the hash of each block, :return:
concatenated together `str` of bytes representing the hash of each block, concatenated
:rtype: str together
:raises IOError: if the server doesn't support the "check-file" :raises IOError: if the server doesn't support the "check-file"
extension, or possibly doesn't support the hash algorithm extension, or possibly doesn't support the hash algorithm
@ -374,9 +369,9 @@ class SFTPFile (BufferedFile):
By default, files are not pipelined. By default, files are not pipelined.
:param pipelined: ``True`` if pipelining should be turned on for this :param bool pipelined:
file; ``False`` otherwise ``True`` if pipelining should be turned on for this file; ``False``
:type pipelined: bool otherwise
.. versionadded:: 1.5 .. versionadded:: 1.5
""" """
@ -414,11 +409,11 @@ class SFTPFile (BufferedFile):
prefetch machinery is used to retrieve all the requested blocks at prefetch machinery is used to retrieve all the requested blocks at
once. once.
:param chunks: a list of (offset, length) tuples indicating which :param chunks:
sections of the file to read a list of (offset, length) tuples indicating which sections of the
file to read
:type chunks: list(tuple(long, int)) :type chunks: list(tuple(long, int))
:return: a list of blocks read, in the same order as in ``chunks`` :return: a list of blocks read, in the same order as in ``chunks``
:rtype: list(str)
.. versionadded:: 1.5.4 .. versionadded:: 1.5.4
""" """

23
paramiko/sftp_handle.py
View File

@ -41,8 +41,7 @@ class SFTPHandle (object):
SFTP. If ``flags`` is passed in, it's used to determine if the file SFTP. If ``flags`` is passed in, it's used to determine if the file
is open in append mode. is open in append mode.
:param flags: optional flags as passed to `.SFTPServerInterface.open` :param int flags: optional flags as passed to `.SFTPServerInterface.open`
:type flags: int
""" """
self.__flags = flags self.__flags = flags
self.__name = None self.__name = None
@ -85,10 +84,8 @@ class SFTPHandle (object):
:param offset: position in the file to start reading from. :param offset: position in the file to start reading from.
:type offset: int or long :type offset: int or long
:param length: number of bytes to attempt to read. :param int length: number of bytes to attempt to read.
:type length: int :return: data read from the file, or an SFTP error code, as a `str`.
:return: data read from the file, or an SFTP error code.
:rtype: str
""" """
readfile = getattr(self, 'readfile', None) readfile = getattr(self, 'readfile', None)
if readfile is None: if readfile is None:
@ -122,8 +119,7 @@ class SFTPHandle (object):
:param offset: position in the file to start reading from. :param offset: position in the file to start reading from.
:type offset: int or long :type offset: int or long
:param data: data to write into the file. :param str data: data to write into the file.
:type data: str
:return: an SFTP error code like `.SFTP_OK`. :return: an SFTP error code like `.SFTP_OK`.
""" """
writefile = getattr(self, 'writefile', None) writefile = getattr(self, 'writefile', None)
@ -152,8 +148,9 @@ class SFTPHandle (object):
error code. This is equivalent to `.SFTPServerInterface.stat`, except error code. This is equivalent to `.SFTPServerInterface.stat`, except
it's called on an open file instead of a path. it's called on an open file instead of a path.
:return: an attributes object for the given file, or an SFTP error :return:
code (like `.SFTP_PERMISSION_DENIED`). an attributes object for the given file, or an SFTP error code
(like `.SFTP_PERMISSION_DENIED`).
:rtype: `.SFTPAttributes` or error code :rtype: `.SFTPAttributes` or error code
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -164,10 +161,8 @@ class SFTPHandle (object):
only those fields provided by the client in its request, so you should only those fields provided by the client in its request, so you should
check for the presence of fields before using them. check for the presence of fields before using them.
:param attr: the attributes to change on this file. :param .SFTPAttributes attr: the attributes to change on this file.
:type attr: `.SFTPAttributes` :return: an `int` error code like `.SFTP_OK`.
:return: an error code like `.SFTP_OK`.
:rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED

31
paramiko/sftp_server.py
View File

@ -52,16 +52,13 @@ class SFTPServer (BaseSFTP, SubsystemHandler):
parameters or keyword parameters are passed from the original call to parameters or keyword parameters are passed from the original call to
`.Transport.set_subsystem_handler`. `.Transport.set_subsystem_handler`.
:param channel: channel passed from the `.Transport`. :param .Channel channel: channel passed from the `.Transport`.
:type channel: `.Channel` :param str name: name of the requested subsystem.
:param name: name of the requested subsystem. :param .ServerInterface server:
:type name: str the server object associated with this channel and subsystem
:param server: the server object associated with this channel and :param class sftp_si:
subsystem a subclass of `.SFTPServerInterface` to use for handling individual
:type server: `.ServerInterface` requests.
:param sftp_si: a subclass of `.SFTPServerInterface` to use for handling
individual requests.
:type sftp_si: class
""" """
BaseSFTP.__init__(self) BaseSFTP.__init__(self)
SubsystemHandler.__init__(self, channel, name, server) SubsystemHandler.__init__(self, channel, name, server)
@ -126,10 +123,8 @@ class SFTPServer (BaseSFTP, SubsystemHandler):
standard SFTP result code. This is a convenience function for trapping standard SFTP result code. This is a convenience function for trapping
exceptions in server code and returning an appropriate result. exceptions in server code and returning an appropriate result.
:param e: an errno code, as from ``OSError.errno``. :param int e: an errno code, as from ``OSError.errno``.
:type e: int :return: an `int` SFTP error code like ``SFTP_NO_SUCH_FILE``.
:return: an SFTP error code like ``SFTP_NO_SUCH_FILE``.
:rtype: int
""" """
if e == errno.EACCES: if e == errno.EACCES:
# permission denied # permission denied
@ -151,11 +146,9 @@ class SFTPServer (BaseSFTP, SubsystemHandler):
This is meant to be a handy helper function for translating SFTP file This is meant to be a handy helper function for translating SFTP file
requests into local file operations. requests into local file operations.
:param filename: name of the file to alter (should usually be an :param str filename:
absolute path). name of the file to alter (should usually be an absolute path).
:type filename: str :param .SFTPAttributes attr: attributes to change.
:param attr: attributes to change.
:type attr: `.SFTPAttributes`
""" """
if sys.platform != 'win32': if sys.platform != 'win32':
# mode operations are meaningless on win32 # mode operations are meaningless on win32

121
paramiko/sftp_si.py
View File

@ -46,9 +46,8 @@ class SFTPServerInterface (object):
Create a new SFTPServerInterface object. This method does nothing by Create a new SFTPServerInterface object. This method does nothing by
default and is meant to be overridden by subclasses. default and is meant to be overridden by subclasses.
:param server: the server object associated with this channel and :param .ServerInterface server:
SFTP subsystem the server object associated with this channel and SFTP subsystem
:type server: `.ServerInterface`
""" """
super(SFTPServerInterface, self).__init__(*largs, **kwargs) super(SFTPServerInterface, self).__init__(*largs, **kwargs)
@ -96,16 +95,14 @@ class SFTPServerInterface (object):
.. note:: The SFTP protocol defines all files to be in "binary" mode. .. note:: The SFTP protocol defines all files to be in "binary" mode.
There is no equivalent to Python's "text" mode. There is no equivalent to Python's "text" mode.
:param path: the requested path (relative or absolute) of the file :param str path:
to be opened. the requested path (relative or absolute) of the file to be opened.
:type path: str :param int flags:
:param flags: flags or'd together from the ``os`` module indicating the flags or'd together from the ``os`` module indicating the requested
requested mode for opening the file. mode for opening the file.
:type flags: int :param .SFTPAttributes attr:
:param attr: requested attributes of the file if it is newly created. requested attributes of the file if it is newly created.
:type attr: `.SFTPAttributes`
:return: a new `.SFTPHandle` or error code. :return: a new `.SFTPHandle` or error code.
:rtype: `.SFTPHandle`
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -125,11 +122,10 @@ class SFTPServerInterface (object):
In case of an error, you should return one of the ``SFTP_*`` error In case of an error, you should return one of the ``SFTP_*`` error
codes, such as `.SFTP_PERMISSION_DENIED`. codes, such as `.SFTP_PERMISSION_DENIED`.
:param path: the requested path (relative or absolute) to be listed. :param str path: the requested path (relative or absolute) to be listed.
:type path: str :return:
:return: a list of the files in the given folder, using a list of the files in the given folder, using `.SFTPAttributes`
`.SFTPAttributes` objects. objects.
:rtype: list of `.SFTPAttributes` or error code
.. note:: .. note::
You should normalize the given ``path`` first (see the `os.path` You should normalize the given ``path`` first (see the `os.path`
@ -148,12 +144,12 @@ class SFTPServerInterface (object):
"aliases"), you should follow them. (`lstat` is the corresponding "aliases"), you should follow them. (`lstat` is the corresponding
call that doesn't follow symlinks/aliases.) call that doesn't follow symlinks/aliases.)
:param path: the requested path (relative or absolute) to fetch :param str path:
file statistics for. the requested path (relative or absolute) to fetch file statistics
:type path: str for.
:return: an attributes object for the given file, or an SFTP error :return:
an `.SFTPAttributes` object for the given file, or an SFTP error
code (like `.SFTP_PERMISSION_DENIED`). code (like `.SFTP_PERMISSION_DENIED`).
:rtype: `.SFTPAttributes` or error code
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -165,12 +161,13 @@ class SFTPServerInterface (object):
return data on the symlink or alias itself. (`stat` is the return data on the symlink or alias itself. (`stat` is the
corresponding call that follows symlinks/aliases.) corresponding call that follows symlinks/aliases.)
:param path: the requested path (relative or absolute) to fetch :param str path:
file statistics for. the requested path (relative or absolute) to fetch file statistics
for.
:type path: str :type path: str
:return: an attributes object for the given file, or an SFTP error :return:
an `.SFTPAttributes` object for the given file, or an SFTP error
code (like `.SFTP_PERMISSION_DENIED`). code (like `.SFTP_PERMISSION_DENIED`).
:rtype: `.SFTPAttributes` or error code
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -178,11 +175,9 @@ class SFTPServerInterface (object):
""" """
Delete a file, if possible. Delete a file, if possible.
:param path: the requested path (relative or absolute) of the file :param str path:
to delete. the requested path (relative or absolute) of the file to delete.
:type path: str :return: an SFTP error code `int` like `.SFTP_OK`.
:return: an SFTP error code like `.SFTP_OK`.
:rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -198,13 +193,10 @@ class SFTPServerInterface (object):
``newpath`` already exists. (The rename operation should be ``newpath`` already exists. (The rename operation should be
non-desctructive.) non-desctructive.)
:param oldpath: the requested path (relative or absolute) of the :param str oldpath:
existing file. the requested path (relative or absolute) of the existing file.
:type oldpath: str :param str newpath: the requested new path of the file.
:param newpath: the requested new path of the file. :return: an SFTP error code `int` like `.SFTP_OK`.
:type newpath: str
:return: an SFTP error code like `.SFTP_OK`.
:rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -218,13 +210,10 @@ class SFTPServerInterface (object):
the presense of fields before using them. In some cases, the ``attr`` the presense of fields before using them. In some cases, the ``attr``
object may be completely empty. object may be completely empty.
:param path: requested path (relative or absolute) of the new :param str path:
folder. requested path (relative or absolute) of the new folder.
:type path: str :param .SFTPAttributes attr: requested attributes of the new folder.
:param attr: requested attributes of the new folder. :return: an SFTP error code `int` like `.SFTP_OK`.
:type attr: `.SFTPAttributes`
:return: an SFTP error code like `.SFTP_OK`.
:rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -234,11 +223,9 @@ class SFTPServerInterface (object):
existing, empty folder -- otherwise this method should return an existing, empty folder -- otherwise this method should return an
error. error.
:param path: requested path (relative or absolute) of the folder :param str path:
to remove. requested path (relative or absolute) of the folder to remove.
:type path: str :return: an SFTP error code `int` like `.SFTP_OK`.
:return: an SFTP error code like `.SFTP_OK`.
:rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -248,13 +235,12 @@ class SFTPServerInterface (object):
only those fields provided by the client in its request, so you only those fields provided by the client in its request, so you
should check for the presence of fields before using them. should check for the presence of fields before using them.
:param path: requested path (relative or absolute) of the file to :param str path:
change. requested path (relative or absolute) of the file to change.
:type path: str :param attr:
:param attr: requested attributes to change on the file. requested attributes to change on the file (an `.SFTPAttributes`
:type attr: `.SFTPAttributes` object)
:return: an error code like `.SFTP_OK`. :return: an error code `int` like `.SFTP_OK`.
:rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -287,11 +273,10 @@ class SFTPServerInterface (object):
If the specified path doesn't refer to a symbolic link, an error If the specified path doesn't refer to a symbolic link, an error
should be returned. should be returned.
:param path: path (relative or absolute) of the symbolic link. :param str path: path (relative or absolute) of the symbolic link.
:type path: str :return:
:return: the target path of the symbolic link, or an error code like the target `str` path of the symbolic link, or an error code like
`.SFTP_NO_SUCH_FILE`. `.SFTP_NO_SUCH_FILE`.
:rtype: str or error code
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED
@ -300,13 +285,11 @@ class SFTPServerInterface (object):
Create a symbolic link on the server, as new pathname ``path``, Create a symbolic link on the server, as new pathname ``path``,
with ``target_path`` as the target of the link. with ``target_path`` as the target of the link.
:param target_path: path (relative or absolute) of the target for :param str target_path:
this new symbolic link. path (relative or absolute) of the target for this new symbolic
:type target_path: str link.
:param path: path (relative or absolute) of the symbolic link to :param str path:
create. path (relative or absolute) of the symbolic link to create.
:type path: str :return: an error code `int` like ``SFTP_OK``.
:return: an error code like ``SFTP_OK``.
:rtype: int
""" """
return SFTP_OP_UNSUPPORTED return SFTP_OP_UNSUPPORTED