Bunch more info fields

paramiko/packet.py

@@ -171,8 +171,6 @@ class Packetizer (object):
         Returns ``True`` if a new set of keys needs to be negotiated.  This
         will be triggered during a packet read or write, so it should be
         checked after every read or write, or at least after every few.
-
-        :return: ``True`` if a new set of keys needs to be negotiated
         """
         return self.__need_rekey
 
@@ -190,12 +188,11 @@ class Packetizer (object):
         """
         Read as close to N bytes as possible, blocking as long as necessary.
 
-        :param n: number of bytes to read
+        :param int n: number of bytes to read
-        :type n: int
+        :return: the data read, as a `str`
-        :return: the data read
+
-        :rtype: str
+        :raises EOFError:
-        :raises EOFError: if the socket was closed before all the bytes could
+            if the socket was closed before all the bytes could be read
-            be read
         """
         out = ''
         # handle over-reading from reading the banner line

paramiko/pkey.py

@@ -52,9 +52,8 @@ class PKey (object):
         ``data`` is given, the key's public part(s) will be filled in from
         the string.
 
-        :param msg:
+        :param .Message msg:
             an optional SSH `.Message` containing a public key of this type.
-        :type msg: `.Message`
         :param str data: an optional string containing a public key of this type
 
         :raises SSHException:
@@ -68,9 +67,6 @@ class PKey (object):
         Return a string of an SSH `.Message` made up of the public part(s) of
         this key.  This string is suitable for passing to `__init__` to
         re-create the key object later.
-
-        :return: string representation of an SSH key message.
-        :rtype: str
         """
         return ''
 
@@ -81,10 +77,7 @@ class PKey (object):
         of the key are compared, so a public key will compare equal to its
         corresponding private key.
 
-        :param other: key to compare to.
+        :param .Pkey other: key to compare to.
-        :type other: `.PKey`
-        :return: 0 if the two keys are equivalent, non-0 otherwise.
-        :rtype: int
         """
         hs = hash(self)
         ho = hash(other)
@@ -97,9 +90,8 @@ class PKey (object):
         Return the name of this private key implementation.
 
         :return:
-            name of this private key type, in SSH terminology (for example,
+            name of this private key type, in SSH terminology, as a `str` (for
-            ``"ssh-rsa"``).
+            example, ``"ssh-rsa"``).
-        :rtype: str
         """
         return ''
 
@@ -108,8 +100,7 @@ class PKey (object):
         Return the number of significant bits in this key.  This is useful
         for judging the relative security of a key.
 
-        :return: bits in the key.
+        :return: bits in the key (as an `int`)
-        :rtype: int
         """
         return 0
 
@@ -117,9 +108,6 @@ class PKey (object):
         """
         Return ``True`` if this key has the private part necessary for signing
         data.
-
-        :return: ``True`` if this is a private key.
-        :rtype: bool
         """
         return False
 
@@ -128,9 +116,9 @@ class PKey (object):
         Return an MD5 fingerprint of the public part of this key.  Nothing
         secret is revealed.
 
-        :return: a 16-byte string (binary) of the MD5 fingerprint, in SSH
+        :return:
+            a 16-byte `string <str>` (binary) of the MD5 fingerprint, in SSH
             format.
-        :rtype: str
         """
         return MD5.new(str(self)).digest()
 
@@ -140,8 +128,7 @@ class PKey (object):
         secret is revealed.  This format is compatible with that used to store
         public key files or recognized host keys.
 
-        :return: a base64 string containing the public part of the key.
+        :return: a base64 `string <str>` containing the public part of the key.
-        :rtype: str
         """
         return base64.encodestring(str(self)).replace('\n', '')
 
@@ -150,12 +137,9 @@ class PKey (object):
         Sign a blob of data with this private key, and return a `.Message`
         representing an SSH signature message.
 
-        :param rng: a secure random number generator.
+        :param .Crypto.Util.rng.RandomPool rng: a secure random number generator.
-        :type rng: `Crypto.Util.rng.RandomPool`
+        :param str data: the data to sign.
-        :param data: the data to sign.
+        :return: an SSH signature `message <.Message>`.
-        :type data: str
-        :return: an SSH signature message.
-        :rtype: `.Message`
         """
         return ''
 
@@ -164,13 +148,10 @@ class PKey (object):
         Given a blob of data, and an SSH message representing a signature of
         that data, verify that it was signed with this key.
 
-        :param data: the data that was signed.
+        :param str data: the data that was signed.
-        :type data: str
+        :param .Message msg: an SSH signature message
-        :param msg: an SSH signature message
+        :return:
-        :type msg: `.Message`
+            ``True`` if the signature verifies correctly; ``False`` otherwise.
-        :return: ``True`` if the signature verifies correctly; ``False``
-            otherwise.
-        :rtype: boolean
         """
         return False
 
@@ -183,13 +164,10 @@ class PKey (object):
         exist in all subclasses of PKey (such as `.RSAKey` or `.DSSKey`), but
         is useless on the abstract PKey class.
 
-        :param filename: name of the file to read
+        :param str filename: name of the file to read
-        :type filename: str
+        :param str password: an optional password to use to decrypt the key file,
-        :param password: an optional password to use to decrypt the key file,
             if it's encrypted
-        :type password: str
+        :return: a new `.PKey` based on the given private key
-        :return: a new key object based on the given private key
-        :rtype: `.PKey`
 
         :raises IOError: if there was an error reading the file
         :raises PasswordRequiredException: if the private key file is
@@ -207,13 +185,10 @@ class PKey (object):
         the given password will be used to decrypt the key (otherwise
         `.PasswordRequiredException` is thrown).
 
-        :param file_obj: the file to read from
+        :param file file_obj: the file to read from
-        :type file_obj: file
+        :param str password:
-        :param password: an optional password to use to decrypt the key, if it's
+            an optional password to use to decrypt the key, if it's encrypted
-            encrypted
+        :return: a new `.PKey` based on the given private key
-        :type password: str
-        :return: a new key object based on the given private key
-        :rtype: `.PKey`
 
         :raises IOError: if there was an error reading the key
         :raises PasswordRequiredException: if the private key file is encrypted,
@@ -229,10 +204,9 @@ class PKey (object):
         Write private key contents into a file.  If the password is not
         ``None``, the key is encrypted before writing.
 
-        :param filename: name of the file to write
+        :param str filename: name of the file to write
-        :type filename: str
+        :param str password:
-        :param password: an optional password to use to encrypt the key file
+            an optional password to use to encrypt the key file
-        :type password: str
 
         :raises IOError: if there was an error writing the file
         :raises SSHException: if the key is invalid
@@ -244,10 +218,8 @@ class PKey (object):
         Write private key contents into a file (or file-like) object.  If the
         password is not ``None``, the key is encrypted before writing.
 
-        :param file_obj: the file object to write into
+        :param file file_obj: the file object to write into
-        :type file_obj: file
+        :param str password: an optional password to use to encrypt the key
-        :param password: an optional password to use to encrypt the key
-        :type password: str
 
         :raises IOError: if there was an error writing to the file
         :raises SSHException: if the key is invalid
@@ -262,15 +234,12 @@ class PKey (object):
         ``password`` is not ``None``, the given password will be used to decrypt
         the key (otherwise `.PasswordRequiredException` is thrown).
 
-        :param tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block.
+        :param str tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block.
-        :type tag: str
+        :param str filename: name of the file to read.
-        :param filename: name of the file to read.
+        :param str password:
-        :type filename: str
+            an optional password to use to decrypt the key file, if it's
-        :param password: an optional password to use to decrypt the key file,
+            encrypted.
-            if it's encrypted.
+        :return: data blob (`str`) that makes up the private key.
-        :type password: str
-        :return: data blob that makes up the private key.
-        :rtype: str
 
         :raises IOError: if there was an error reading the file.
         :raises PasswordRequiredException: if the private key file is
@@ -336,14 +305,10 @@ class PKey (object):
         a trivially-encoded format (base64) which is completely insecure.  If
         a password is given, DES-EDE3-CBC is used.
 
-        :param tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block.
+        :param str tag: ``"RSA"`` or ``"DSA"``, the tag used to mark the data block.
-        :type tag: str
+        :param file filename: name of the file to write.
-        :param filename: name of the file to write.
+        :param str data: data blob that makes up the private key.
-        :type filename: str
+        :param str password: an optional password to use to encrypt the file.
-        :param data: data blob that makes up the private key.
-        :type data: str
-        :param password: an optional password to use to encrypt the file.
-        :type password: str
 
         :raises IOError: if there was an error writing the file.
         """

paramiko/proxy.py

@@ -39,9 +39,8 @@ class ProxyCommand(object):
         Create a new CommandProxy instance. The instance created by this
         class can be passed as an argument to the `.Transport` class.
 
-        :param command_line: the command that should be executed and
+        :param str command_line:
-            used as the proxy.
+            the command that should be executed and used as the proxy.
-        :type command_line: str
         """
         self.cmd = shlsplit(command_line)
         self.process = Popen(self.cmd, stdin=PIPE, stdout=PIPE, stderr=PIPE)
@@ -51,8 +50,7 @@ class ProxyCommand(object):
         Write the content received from the SSH client to the standard
         input of the forked command.
 
-        :param content: string to be sent to the forked command
+        :param str content: string to be sent to the forked command
-        :type content: str
         """
         try:
             self.process.stdin.write(content)
@@ -68,11 +66,9 @@ class ProxyCommand(object):
         """
         Read from the standard output of the forked program.
 
-        :param size: how many chars should be read
+        :param int size: how many chars should be read
-        :type size: int
 
-        :return: the length of the read content
+        :return: the length of the read content, as an `int`
-        :rtype: int
         """
         try:
             return os.read(self.process.stdout.fileno(), size)

paramiko/resource.py

@@ -51,10 +51,9 @@ class ResourceManager (object):
         the ``resource`` will be closed by having its ``close()`` method called.
         Any exceptions are ignored.
         
-        :param obj: the object to track
+        :param object obj: the object to track
-        :type obj: object
+        :param object resource:
-        :param resource: the resource to close when the object is collected
+            the resource to close when the object is collected
-        :type resource: object
         """
         def callback(ref):
             try:

paramiko/rsakey.py

@@ -129,13 +129,11 @@ class RSAKey (PKey):
         Generate a new private RSA key.  This factory function can be used to
         generate a new host key or authentication key.
 
-        :param bits: number of bits the generated key should be.
+        :param int bits: number of bits the generated key should be.
-        :type bits: int
+        :param function progress_func:
-        :param progress_func: an optional function to call at key points in
+            an optional function to call at key points in key generation (used
-            key generation (used by ``pyCrypto.PublicKey``).
+            by ``pyCrypto.PublicKey``).
-        :type progress_func: function
+        :return: new `.RSAKey` private key
-        :return: new private key
-        :rtype: `.RSAKey`
         """
         rsa = RSA.generate(bits, rng.read, progress_func)
         key = RSAKey(vals=(rsa.e, rsa.n))