diff --git a/paramiko/sftp_attr.py b/paramiko/sftp_attr.py index 9b30829..3ef9703 100644 --- a/paramiko/sftp_attr.py +++ b/paramiko/sftp_attr.py @@ -65,12 +65,9 @@ class SFTPAttributes (object): Create an `.SFTPAttributes` object from an existing ``stat`` object (an object returned by `os.stat`). - :param obj: an object returned by `os.stat` (or equivalent). - :type obj: object - :param filename: the filename associated with this file. - :type filename: str + :param object obj: an object returned by `os.stat` (or equivalent). + :param str filename: the filename associated with this file. :return: new `.SFTPAttributes` object with the same attribute fields. - :rtype: `.SFTPAttributes` """ attr = cls() attr.st_size = obj.st_size diff --git a/paramiko/sftp_client.py b/paramiko/sftp_client.py index db8d196..0580bc4 100644 --- a/paramiko/sftp_client.py +++ b/paramiko/sftp_client.py @@ -61,8 +61,7 @@ class SFTPClient(BaseSFTP): An alternate way to create an SFTP client context is by using `from_transport`. - :param sock: an open `.Channel` using the ``"sftp"`` subsystem - :type sock: `.Channel` + :param .Channel sock: an open `.Channel` using the ``"sftp"`` subsystem :raises SSHException: if there's an exception while negotiating sftp @@ -91,11 +90,10 @@ class SFTPClient(BaseSFTP): """ Create an SFTP client channel from an open `.Transport`. - :param t: an open `.Transport` which is already authenticated - :type t: `.Transport` - :return: a new `.SFTPClient` object, referring to an sftp session - (channel) across the transport - :rtype: `.SFTPClient` + :param .Transport t: an open `.Transport` which is already authenticated + :return: + a new `.SFTPClient` object, referring to an sftp session (channel) + across the transport """ chan = t.open_session() if chan is None: @@ -125,9 +123,6 @@ class SFTPClient(BaseSFTP): Return the underlying `.Channel` object for this SFTP session. This might be useful for doing things like setting a timeout on the channel. - :return: the SSH channel - :rtype: `.Channel` - .. versionadded:: 1.7.1 """ return self.sock @@ -135,15 +130,13 @@ class SFTPClient(BaseSFTP): def listdir(self, 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 entries ``'.'`` and ``'..'`` even if they are present in the folder. This method is meant to mirror ``os.listdir`` as closely as possible. For a list of full `.SFTPAttributes` objects, see `listdir_attr`. - :param path: path to list (defaults to ``'.'``) - :type path: str - :return: list of filenames - :rtype: list of str + :param str path: path to list (defaults to ``'.'``) """ 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 depend on the SFTP server implementation. - :param path: path to list (defaults to ``'.'``) - :type path: str - :return: list of attributes - :rtype: list of `.SFTPAttributes` + :param str path: path to list (defaults to ``'.'``) + :return: list of `.SFTPAttributes` objects .. versionadded:: 1.2 """ @@ -216,14 +207,10 @@ class SFTPClient(BaseSFTP): buffering, ``1`` uses line buffering, and any number greater than 1 (``>1``) uses that specific buffer size. - :param filename: name of the file to open - :type filename: str - :param mode: mode (Python-style) to open in - :type mode: str - :param bufsize: desired buffering (-1 = default buffer size) - :type bufsize: int - :return: a file object representing the open file - :rtype: `.SFTPFile` + :param str filename: name of the file to open + :param str mode: mode (Python-style) to open in + :param int bufsize: desired buffering (-1 = default buffer size) + :return: an `.SFTPFile` object representing the open file :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 removing folders (directories), use `rmdir`. - :param path: path (absolute or relative) of the file to remove - :type path: str + :param str path: path (absolute or relative) of the file to remove :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``. - :param oldpath: existing name of the file or folder - :type oldpath: str - :param newpath: new name for the file or folder - :type newpath: str + :param str oldpath: existing name of the file or folder + :param str newpath: new name for the file or folder :raises IOError: if ``newpath`` is a folder, or something else goes wrong @@ -290,10 +274,8 @@ class SFTPClient(BaseSFTP): The default mode is 0777 (octal). On some systems, mode is ignored. Where it is used, the current umask value is first masked out. - :param path: name of the folder to create - :type path: str - :param mode: permissions (posix-style) for the newly-created folder - :type mode: int + :param str path: name of the folder to create + :param int mode: permissions (posix-style) for the newly-created folder """ path = self._adjust_cwd(path) self._log(DEBUG, 'mkdir(%r, %r)' % (path, mode)) @@ -305,8 +287,7 @@ class SFTPClient(BaseSFTP): """ Remove the folder named ``path``. - :param path: name of the folder to remove - :type path: str + :param str path: name of the folder to remove """ path = self._adjust_cwd(path) self._log(DEBUG, 'rmdir(%r)' % path) @@ -326,10 +307,10 @@ class SFTPClient(BaseSFTP): The fields supported are: ``st_mode``, ``st_size``, ``st_uid``, ``st_gid``, ``st_atime``, and ``st_mtime``. - :param path: the filename to stat - :type path: str - :return: an object containing attributes about the given file - :rtype: `.SFTPAttributes` + :param str path: the filename to stat + :return: + an `.SFTPAttributes` object containing attributes about the given + file """ path = self._adjust_cwd(path) self._log(DEBUG, 'stat(%r)' % path) @@ -344,10 +325,10 @@ class SFTPClient(BaseSFTP): following symbolic links (shortcuts). This otherwise behaves exactly the same as `stat`. - :param path: the filename to stat - :type path: str - :return: an object containing attributes about the given file - :rtype: `.SFTPAttributes` + :param str path: the filename to stat + :return: + an `.SFTPAttributes` object containing attributes about the given + file """ path = self._adjust_cwd(path) self._log(DEBUG, 'lstat(%r)' % path) @@ -361,10 +342,8 @@ class SFTPClient(BaseSFTP): Create a symbolic link (shortcut) of the ``source`` path at ``destination``. - :param source: path of the original file - :type source: str - :param dest: path of the newly created symlink - :type dest: str + :param str source: path of the original file + :param str dest: path of the newly created symlink """ dest = self._adjust_cwd(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` function. - :param path: path of the file to change the permissions of - :type path: str - :param mode: new permissions - :type mode: int + :param str path: path of the file to change the permissions of + :param int mode: new permissions """ path = self._adjust_cwd(path) 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 owner and group. - :param path: path of the file to change the owner and group of - :type path: str - :param uid: new owner's uid - :type uid: int - :param gid: new group id - :type gid: int + :param str path: path of the file to change the owner and group of + :param int uid: new owner's uid + :param int gid: new group id """ path = self._adjust_cwd(path) 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 for the sake of consistency -- I apologize. - :param path: path of the file to modify - :type path: str - :param times: ``None`` or a tuple of (access time, modified time) in - standard internet epoch time (seconds since 01 January 1970 GMT) - :type times: tuple(int) + :param str path: path of the file to modify + :param tuple times: + ``None`` or a tuple of (access time, modified time) in standard + internet epoch time (seconds since 01 January 1970 GMT) """ path = self._adjust_cwd(path) if times is None: @@ -438,8 +411,7 @@ class SFTPClient(BaseSFTP): extends or shrinks the size of the file, just like the `~file.truncate` method on Python file objects. - :param path: path of the file to modify - :type path: str + :param str path: path of the file to modify :param size: the new size of the file :type size: int or long """ @@ -455,10 +427,8 @@ class SFTPClient(BaseSFTP): `symlink` to create these. The result may be either an absolute or relative pathname. - :param path: path of the symbolic link file - :type path: str - :return: target path - :rtype: str + :param str path: path of the symbolic link file + :return: target path, as a `str` """ path = self._adjust_cwd(path) self._log(DEBUG, 'readlink(%r)' % path) @@ -479,10 +449,8 @@ class SFTPClient(BaseSFTP): server is considering to be the "current folder" (by passing ``'.'`` as ``path``). - :param path: path to be normalized - :type path: str - :return: normalized form of the given path - :rtype: str + :param str path: path to be normalized + :return: normalized form of the given path (as a `str`) :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 directory. - :param path: new current working directory - :type path: str + :param str path: new current working directory :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`, this method will return ``None``. - :return: the current working directory on the server, or ``None`` - :rtype: str - .. versionadded:: 1.4 """ return self._cwd @@ -540,26 +504,26 @@ class SFTPClient(BaseSFTP): The SFTP operations use pipelining for speed. - :param fl: opened file or file-like object to copy - :type localpath: object - :param remotepath: the destination path on the SFTP server - :type remotepath: str - :param file_size: optional size parameter passed to callback. If none is - specified, size defaults to 0 - :type file_size: int - :param callback: optional callback function that accepts the bytes - transferred so far and the total bytes to be transferred + :param file fl: opened file or file-like object to copy + :param str remotepath: the destination path on the SFTP server + :param int file_size: + optional size parameter passed to callback. If none is specified, + size defaults to 0 + :param callable callback: + optional callback function (form: ``func(int, int)``) that accepts + the bytes transferred so far and the total bytes to be transferred (since 1.7.4) - :type callback: function(int, int) - :param confirm: whether to do a stat() on the file afterwards to - confirm the file size (since 1.7.7) - :type confirm: bool + :param bool confirm: + whether to do a stat() on the file afterwards to confirm the file + size (since 1.7.7) - :return: an object containing attributes about the given file - (since 1.7.4) - :rtype: `.SFTPAttributes` + :return: + an `.SFTPAttributes` object containing attributes about the given + file. .. versionadded:: 1.4 + .. versionchanged:: 1.7.4 + Began returning rich attribute objects. """ fr = self.file(remotepath, 'wb') fr.set_pipelined(True) @@ -591,23 +555,22 @@ class SFTPClient(BaseSFTP): The SFTP operations use pipelining for speed. - :param localpath: the local file to copy - :type localpath: str - :param remotepath: the destination path on the SFTP server - :type remotepath: str - :param callback: optional callback function that accepts the bytes - transferred so far and the total bytes to be transferred - (since 1.7.4) - :type callback: function(int, int) - :param confirm: whether to do a stat() on the file afterwards to - confirm the file size (since 1.7.7) - :type confirm: bool + :param str localpath: the local file to copy + :param str remotepath: the destination path on the SFTP server + :param callable callback: + optional callback function (form: ``func(int, int)``) that accepts + the bytes transferred so far and the total bytes to be transferred + :param bool confirm: + whether to do a stat() on the file afterwards to confirm the file + size - :return: an object containing attributes about the given file - (since 1.7.4) - :rtype: `.SFTPAttributes` + :return: an `.SFTPAttributes` object containing attributes about the given file .. 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 fl = file(localpath, 'rb') @@ -623,18 +586,17 @@ class SFTPClient(BaseSFTP): operations will be passed through. This method is primarily provided as a convenience. - :param remotepath: opened file or file-like object to copy to - :type remotepath: object - :param fl: the destination path on the local host or open file - object - :type localpath: str - :param callback: optional callback function that accepts the bytes - transferred so far and the total bytes to be transferred - (since 1.7.4) - :type callback: function(int, int) - :return: the number of bytes written to the opened file object + :param object remotepath: opened file or file-like object to copy to + :param str fl: + the destination path on the local host or open file object + :param callable callback: + optional callback function (form: ``func(int, int)``) that accepts + the bytes transferred so far and the total bytes to be transferred + :return: the `number ` of bytes written to the opened file object .. versionadded:: 1.4 + .. versionchanged:: 1.7.4 + Added the ``callable`` param. """ fr = self.file(remotepath, 'rb') file_size = self.stat(remotepath).st_size @@ -659,16 +621,15 @@ class SFTPClient(BaseSFTP): host as ``localpath``. Any exception raised by operations will be passed through. This method is primarily provided as a convenience. - :param remotepath: the remote file to copy - :type remotepath: str - :param localpath: the destination path on the local host - :type localpath: str - :param callback: optional callback function that accepts the bytes - transferred so far and the total bytes to be transferred - (since 1.7.4) - :type callback: function(int, int) + :param str remotepath: the remote file to copy + :param str localpath: the destination path on the local host + :param callable callback: + optional callback function (form: ``func(int, int)``) that accepts + the bytes transferred so far and the total bytes to be transferred .. versionadded:: 1.4 + .. versionchanged:: 1.7.4 + Added the ``callback`` param """ file_size = self.stat(remotepath).st_size fl = file(localpath, 'wb') diff --git a/paramiko/sftp_file.py b/paramiko/sftp_file.py index 068ca1a..9add3c9 100644 --- a/paramiko/sftp_file.py +++ b/paramiko/sftp_file.py @@ -186,9 +186,9 @@ class SFTPFile (BufferedFile): Set a timeout on read/write operations on the underlying socket or ssh `.Channel`. - :param timeout: seconds to wait for a pending read/write operation - before raising ``socket.timeout``, or ``None`` for no timeout - :type timeout: float + :param float timeout: + seconds to wait for a pending read/write operation before raising + ``socket.timeout``, or ``None`` for no timeout .. seealso:: `.Channel.settimeout` """ @@ -196,10 +196,8 @@ class SFTPFile (BufferedFile): def gettimeout(self): """ - Returns the timeout in seconds (as a float) associated with the socket - or ssh `.Channel` used for this file. - - :rtype: float + Returns the timeout in seconds (as a `float`) associated with the + socket or ssh `.Channel` used for this file. .. seealso:: `.Channel.gettimeout` """ @@ -210,9 +208,8 @@ class SFTPFile (BufferedFile): Set blocking or non-blocking mode on the underiying socket or ssh `.Channel`. - :param blocking: + :param int blocking: 0 to set non-blocking mode; non-0 to set blocking mode. - :type blocking: int .. seealso:: `.Channel.setblocking` """ @@ -235,8 +232,7 @@ class SFTPFile (BufferedFile): exactly like `.SFTPClient.stat`, except that it operates on an already-open file. - :return: an object containing attributes about this file. - :rtype: `.SFTPAttributes` + :return: an `.SFTPAttributes` object containing attributes about this file. """ t, msg = self.sftp._request(CMD_FSTAT, self.handle) if t != CMD_ATTRS: @@ -249,8 +245,7 @@ class SFTPFile (BufferedFile): unix-style and identical to those used by Python's `os.chmod` function. - :param mode: new permissions - :type mode: int + :param int mode: new permissions """ self.sftp._log(DEBUG, 'chmod(%s, %r)' % (hexlify(self.handle), mode)) attr = SFTPAttributes() @@ -264,10 +259,8 @@ class SFTPFile (BufferedFile): only want to change one, use `stat` first to retrieve the current owner and group. - :param uid: new owner's uid - :type uid: int - :param gid: new group id - :type gid: int + :param int uid: new owner's uid + :param int gid: new group id """ self.sftp._log(DEBUG, 'chown(%s, %r, %r)' % (hexlify(self.handle), uid, gid)) attr = SFTPAttributes() @@ -283,9 +276,9 @@ class SFTPFile (BufferedFile): modified times, respectively. This bizarre API is mimicked from Python for the sake of consistency -- I apologize. - :param times: ``None`` or a tuple of (access time, modified time) in - standard internet epoch time (seconds since 01 January 1970 GMT) - :type times: tuple(int) + :param tuple times: + ``None`` or a tuple of (access time, modified time) in standard + internet epoch time (seconds since 01 January 1970 GMT) """ if times is None: 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 bytes. - :param hash_algorithm: the name of the hash algorithm to use (normally - ``"sha1"`` or ``"md5"``) - :type hash_algorithm: str - :param offset: offset into the file to begin hashing (0 means to start - from the beginning) + :param str hash_algorithm: + the name of the hash algorithm to use (normally ``"sha1"`` or + ``"md5"``) + :param offset: + offset into the file to begin hashing (0 means to start from the + beginning) :type offset: int or long - :param length: number of bytes to hash (0 means continue to the end of - the file) + :param length: + number of bytes to hash (0 means continue to the end of the file) :type length: int or long - :param block_size: number of bytes to hash per result (must not be less - than 256; 0 means to compute only one hash of the entire segment) + :param int block_size: + 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 - :return: string of bytes representing the hash of each block, - concatenated together - :rtype: str + :return: + `str` of bytes representing the hash of each block, concatenated + together :raises IOError: if the server doesn't support the "check-file" extension, or possibly doesn't support the hash algorithm @@ -374,9 +369,9 @@ class SFTPFile (BufferedFile): By default, files are not pipelined. - :param pipelined: ``True`` if pipelining should be turned on for this - file; ``False`` otherwise - :type pipelined: bool + :param bool pipelined: + ``True`` if pipelining should be turned on for this file; ``False`` + otherwise .. versionadded:: 1.5 """ @@ -414,11 +409,11 @@ class SFTPFile (BufferedFile): prefetch machinery is used to retrieve all the requested blocks at once. - :param chunks: a list of (offset, length) tuples indicating which - sections of the file to read + :param chunks: + a list of (offset, length) tuples indicating which sections of the + file to read :type chunks: list(tuple(long, int)) :return: a list of blocks read, in the same order as in ``chunks`` - :rtype: list(str) .. versionadded:: 1.5.4 """ diff --git a/paramiko/sftp_handle.py b/paramiko/sftp_handle.py index 6965fd6..a799d57 100644 --- a/paramiko/sftp_handle.py +++ b/paramiko/sftp_handle.py @@ -41,8 +41,7 @@ class SFTPHandle (object): SFTP. If ``flags`` is passed in, it's used to determine if the file is open in append mode. - :param flags: optional flags as passed to `.SFTPServerInterface.open` - :type flags: int + :param int flags: optional flags as passed to `.SFTPServerInterface.open` """ self.__flags = flags self.__name = None @@ -85,10 +84,8 @@ class SFTPHandle (object): :param offset: position in the file to start reading from. :type offset: int or long - :param length: number of bytes to attempt to read. - :type length: int - :return: data read from the file, or an SFTP error code. - :rtype: str + :param int length: number of bytes to attempt to read. + :return: data read from the file, or an SFTP error code, as a `str`. """ readfile = getattr(self, 'readfile', None) if readfile is None: @@ -122,8 +119,7 @@ class SFTPHandle (object): :param offset: position in the file to start reading from. :type offset: int or long - :param data: data to write into the file. - :type data: str + :param str data: data to write into the file. :return: an SFTP error code like `.SFTP_OK`. """ writefile = getattr(self, 'writefile', None) @@ -152,8 +148,9 @@ class SFTPHandle (object): error code. This is equivalent to `.SFTPServerInterface.stat`, except it's called on an open file instead of a path. - :return: an attributes object for the given file, or an SFTP error - code (like `.SFTP_PERMISSION_DENIED`). + :return: + an attributes object for the given file, or an SFTP error code + (like `.SFTP_PERMISSION_DENIED`). :rtype: `.SFTPAttributes` or error code """ return SFTP_OP_UNSUPPORTED @@ -164,10 +161,8 @@ class SFTPHandle (object): only those fields provided by the client in its request, so you should check for the presence of fields before using them. - :param attr: the attributes to change on this file. - :type attr: `.SFTPAttributes` - :return: an error code like `.SFTP_OK`. - :rtype: int + :param .SFTPAttributes attr: the attributes to change on this file. + :return: an `int` error code like `.SFTP_OK`. """ return SFTP_OP_UNSUPPORTED diff --git a/paramiko/sftp_server.py b/paramiko/sftp_server.py index 9b7ed5c..0456e0a 100644 --- a/paramiko/sftp_server.py +++ b/paramiko/sftp_server.py @@ -52,16 +52,13 @@ class SFTPServer (BaseSFTP, SubsystemHandler): parameters or keyword parameters are passed from the original call to `.Transport.set_subsystem_handler`. - :param channel: channel passed from the `.Transport`. - :type channel: `.Channel` - :param name: name of the requested subsystem. - :type name: str - :param server: the server object associated with this channel and - subsystem - :type server: `.ServerInterface` - :param sftp_si: a subclass of `.SFTPServerInterface` to use for handling - individual requests. - :type sftp_si: class + :param .Channel channel: channel passed from the `.Transport`. + :param str name: name of the requested subsystem. + :param .ServerInterface server: + the server object associated with this channel and subsystem + :param class sftp_si: + a subclass of `.SFTPServerInterface` to use for handling individual + requests. """ BaseSFTP.__init__(self) 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 exceptions in server code and returning an appropriate result. - :param e: an errno code, as from ``OSError.errno``. - :type e: int - :return: an SFTP error code like ``SFTP_NO_SUCH_FILE``. - :rtype: int + :param int e: an errno code, as from ``OSError.errno``. + :return: an `int` SFTP error code like ``SFTP_NO_SUCH_FILE``. """ if e == errno.EACCES: # permission denied @@ -151,11 +146,9 @@ class SFTPServer (BaseSFTP, SubsystemHandler): This is meant to be a handy helper function for translating SFTP file requests into local file operations. - :param filename: name of the file to alter (should usually be an - absolute path). - :type filename: str - :param attr: attributes to change. - :type attr: `.SFTPAttributes` + :param str filename: + name of the file to alter (should usually be an absolute path). + :param .SFTPAttributes attr: attributes to change. """ if sys.platform != 'win32': # mode operations are meaningless on win32 diff --git a/paramiko/sftp_si.py b/paramiko/sftp_si.py index ead483a..d4b3426 100644 --- a/paramiko/sftp_si.py +++ b/paramiko/sftp_si.py @@ -46,9 +46,8 @@ class SFTPServerInterface (object): Create a new SFTPServerInterface object. This method does nothing by default and is meant to be overridden by subclasses. - :param server: the server object associated with this channel and - SFTP subsystem - :type server: `.ServerInterface` + :param .ServerInterface server: + the server object associated with this channel and SFTP subsystem """ 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. There is no equivalent to Python's "text" mode. - :param path: the requested path (relative or absolute) of the file - to be opened. - :type path: str - :param flags: flags or'd together from the ``os`` module indicating the - requested mode for opening the file. - :type flags: int - :param attr: requested attributes of the file if it is newly created. - :type attr: `.SFTPAttributes` + :param str path: + the requested path (relative or absolute) of the file to be opened. + :param int flags: + flags or'd together from the ``os`` module indicating the requested + mode for opening the file. + :param .SFTPAttributes attr: + requested attributes of the file if it is newly created. :return: a new `.SFTPHandle` or error code. - :rtype: `.SFTPHandle` """ return SFTP_OP_UNSUPPORTED @@ -125,11 +122,10 @@ class SFTPServerInterface (object): In case of an error, you should return one of the ``SFTP_*`` error codes, such as `.SFTP_PERMISSION_DENIED`. - :param path: the requested path (relative or absolute) to be listed. - :type path: str - :return: a list of the files in the given folder, using - `.SFTPAttributes` objects. - :rtype: list of `.SFTPAttributes` or error code + :param str path: the requested path (relative or absolute) to be listed. + :return: + a list of the files in the given folder, using `.SFTPAttributes` + objects. .. note:: 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 call that doesn't follow symlinks/aliases.) - :param path: the requested path (relative or absolute) to fetch - file statistics for. - :type path: str - :return: an attributes object for the given file, or an SFTP error + :param str path: + the requested path (relative or absolute) to fetch file statistics + for. + :return: + an `.SFTPAttributes` object for the given file, or an SFTP error code (like `.SFTP_PERMISSION_DENIED`). - :rtype: `.SFTPAttributes` or error code """ return SFTP_OP_UNSUPPORTED @@ -165,12 +161,13 @@ class SFTPServerInterface (object): return data on the symlink or alias itself. (`stat` is the corresponding call that follows symlinks/aliases.) - :param path: the requested path (relative or absolute) to fetch - file statistics for. + :param str path: + the requested path (relative or absolute) to fetch file statistics + for. :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`). - :rtype: `.SFTPAttributes` or error code """ return SFTP_OP_UNSUPPORTED @@ -178,11 +175,9 @@ class SFTPServerInterface (object): """ Delete a file, if possible. - :param path: the requested path (relative or absolute) of the file - to delete. - :type path: str - :return: an SFTP error code like `.SFTP_OK`. - :rtype: int + :param str path: + the requested path (relative or absolute) of the file to delete. + :return: an SFTP error code `int` like `.SFTP_OK`. """ return SFTP_OP_UNSUPPORTED @@ -198,13 +193,10 @@ class SFTPServerInterface (object): ``newpath`` already exists. (The rename operation should be non-desctructive.) - :param oldpath: the requested path (relative or absolute) of the - existing file. - :type oldpath: str - :param newpath: the requested new path of the file. - :type newpath: str - :return: an SFTP error code like `.SFTP_OK`. - :rtype: int + :param str oldpath: + the requested path (relative or absolute) of the existing file. + :param str newpath: the requested new path of the file. + :return: an SFTP error code `int` like `.SFTP_OK`. """ return SFTP_OP_UNSUPPORTED @@ -218,13 +210,10 @@ class SFTPServerInterface (object): the presense of fields before using them. In some cases, the ``attr`` object may be completely empty. - :param path: requested path (relative or absolute) of the new - folder. - :type path: str - :param attr: requested attributes of the new folder. - :type attr: `.SFTPAttributes` - :return: an SFTP error code like `.SFTP_OK`. - :rtype: int + :param str path: + requested path (relative or absolute) of the new folder. + :param .SFTPAttributes attr: requested attributes of the new folder. + :return: an SFTP error code `int` like `.SFTP_OK`. """ return SFTP_OP_UNSUPPORTED @@ -234,11 +223,9 @@ class SFTPServerInterface (object): existing, empty folder -- otherwise this method should return an error. - :param path: requested path (relative or absolute) of the folder - to remove. - :type path: str - :return: an SFTP error code like `.SFTP_OK`. - :rtype: int + :param str path: + requested path (relative or absolute) of the folder to remove. + :return: an SFTP error code `int` like `.SFTP_OK`. """ return SFTP_OP_UNSUPPORTED @@ -248,13 +235,12 @@ class SFTPServerInterface (object): only those fields provided by the client in its request, so you should check for the presence of fields before using them. - :param path: requested path (relative or absolute) of the file to - change. - :type path: str - :param attr: requested attributes to change on the file. - :type attr: `.SFTPAttributes` - :return: an error code like `.SFTP_OK`. - :rtype: int + :param str path: + requested path (relative or absolute) of the file to change. + :param attr: + requested attributes to change on the file (an `.SFTPAttributes` + object) + :return: an error code `int` like `.SFTP_OK`. """ return SFTP_OP_UNSUPPORTED @@ -287,11 +273,10 @@ class SFTPServerInterface (object): If the specified path doesn't refer to a symbolic link, an error should be returned. - :param path: path (relative or absolute) of the symbolic link. - :type path: str - :return: the target path of the symbolic link, or an error code like + :param str path: path (relative or absolute) of the symbolic link. + :return: + the target `str` path of the symbolic link, or an error code like `.SFTP_NO_SUCH_FILE`. - :rtype: str or error code """ return SFTP_OP_UNSUPPORTED @@ -300,13 +285,11 @@ class SFTPServerInterface (object): Create a symbolic link on the server, as new pathname ``path``, with ``target_path`` as the target of the link. - :param target_path: path (relative or absolute) of the target for - this new symbolic link. - :type target_path: str - :param path: path (relative or absolute) of the symbolic link to - create. - :type path: str - :return: an error code like ``SFTP_OK``. - :rtype: int + :param str target_path: + path (relative or absolute) of the target for this new symbolic + link. + :param str path: + path (relative or absolute) of the symbolic link to create. + :return: an error code `int` like ``SFTP_OK``. """ return SFTP_OP_UNSUPPORTED