SFTP done, ugh

6 files changed, 197 insertions, 273 deletions

diff --git a/paramiko/sftp_attr.py b/paramiko/sftp_attr.py
index 9b30829c..3ef9703b 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 db8d196f..0580bc43 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 <int>` 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 068ca1a1..9add3c91 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 6965fd65..a799d57c 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 9b7ed5ca..0456e0a6 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 ead483a0..d4b34268 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