Start fixing up blatantly wrong-under-py3 docstring types

author: Jeff Forcier <jeff@bitprophet.org> 2023-01-12 17:20:51 -0500
committer: Jeff Forcier <jeff@bitprophet.org> 2023-01-12 21:44:59 -0500
commit: 714350c4dd459577898d72a59edc3213a99443d6 (patch)
tree: 8244b90e69d635fc755bda80bda24cf7dc7eaffe
parent: 299556eebf3145019303278432e1fdb6cabb067e (diff)
6 files changed, 51 insertions, 41 deletions
diff --git a/paramiko/channel.py b/paramiko/channel.py
index ccd23e9d..5e0f6ab6 100644
--- a/paramiko/channel.py
+++ b/paramiko/channel.py
@@ -688,7 +688,7 @@ class Channel(ClosingContextManager):
         length zero is returned, the channel stream has closed.
 
         :param int nbytes: maximum number of bytes to read.
-        :return: received data, as a ``str``/``bytes``.
+        :return: received data, as a `bytes`.
 
         :raises socket.timeout:
             if no data is ready before the timeout set by `settimeout`.
@@ -734,7 +734,7 @@ class Channel(ClosingContextManager):
         channel stream has closed.
 
         :param int nbytes: maximum number of bytes to read.
-        :return: received data as a `str`
+        :return: received data as a `bytes`
 
         :raises socket.timeout: if no data is ready before the timeout set by
             `settimeout`.
@@ -786,7 +786,7 @@ class Channel(ClosingContextManager):
         transmitted, the application needs to attempt delivery of the remaining
         data.
 
-        :param str s: data to send
+        :param bytes s: data to send
         :return: number of bytes actually sent, as an `int`
 
         :raises socket.timeout: if no data could be sent before the timeout set
@@ -807,7 +807,7 @@ class Channel(ClosingContextManager):
         data has been sent: if only some of the data was transmitted, the
         application needs to attempt delivery of the remaining data.
 
-        :param str s: data to send.
+        :param bytes s: data to send.
         :return: number of bytes actually sent, as an `int`.
 
         :raises socket.timeout:
@@ -849,10 +849,10 @@ class Channel(ClosingContextManager):
         """
         Send data to the channel's "stderr" stream, without allowing partial
         results.  Unlike `send_stderr`, this method continues to send data
-        from the given string until all data has been sent or an error occurs.
-        Nothing is returned.
+        from the given bytestring until all data has been sent or an error
+        occurs. Nothing is returned.
 
-        :param str s: data to send to the client as "stderr" output.
+        :param bytes s: data to send to the client as "stderr" output.
 
         :raises socket.timeout:
             if sending stalled for longer than the timeout set by `settimeout`.
diff --git a/paramiko/message.py b/paramiko/message.py
index 5833f9dd..d02f7855 100644
--- a/paramiko/message.py
+++ b/paramiko/message.py
@@ -45,7 +45,7 @@ class Message(object):
         """
         Create a new SSH2 message.
 
-        :param str content:
+        :param bytes content:
             the byte stream to use as the message content (passed in only when
             decomposing a message).
         """
@@ -66,9 +66,10 @@ class Message(object):
         """
         return "paramiko.Message(" + repr(self.packet.getvalue()) + ")"
 
+    # TODO 4.0: just merge into __bytes__ (everywhere)
     def asbytes(self):
         """
-        Return the byte stream content of this Message, as bytes.
+        Return the byte stream content of this Message, as a `bytes`.
         """
         return self.packet.getvalue()
 
@@ -81,8 +82,8 @@ class Message(object):
 
     def get_remainder(self):
         """
-        Return the bytes (as a `str`) of this message that haven't already been
-        parsed and returned.
+        Return the `bytes` of this message that haven't already been parsed and
+        returned.
         """
         position = self.packet.tell()
         remainder = self.packet.read()
@@ -91,7 +92,7 @@ class Message(object):
 
     def get_so_far(self):
         """
-        Returns the `str` bytes of this message that have been parsed and
+        Returns the `bytes` of this message that have been parsed and
         returned. The string passed into a message's constructor can be
         regenerated by concatenating ``get_so_far`` and `get_remainder`.
         """
@@ -101,10 +102,10 @@ class Message(object):
 
     def get_bytes(self, n):
         """
-        Return the next ``n`` bytes of the message (as a `str`), without
-        decomposing into an int, decoded string, etc.  Just the raw bytes are
-        returned. Returns a string of ``n`` zero bytes if there weren't ``n``
-        bytes remaining in the message.
+        Return the next ``n`` bytes of the message, without decomposing into an
+        int, decoded string, etc.  Just the raw bytes are returned. Returns a
+        string of ``n`` zero bytes if there weren't ``n`` bytes remaining in
+        the message.
         """
         b = self.packet.read(n)
         max_pad_size = 1 << 20  # Limit padding to 1 MB
@@ -118,8 +119,8 @@ class Message(object):
         is equivalent to `get_bytes(1) <get_bytes>`.
 
         :return:
-            the next (`str`) byte of the message, or ``'\000'`` if there aren't
-            any bytes remaining.
+            the next (`bytes`) byte of the message, or ``b'\000'`` if there
+            aren't any bytes remaining.
         """
         return self.get_bytes(1)
 
@@ -164,25 +165,30 @@ class Message(object):
         """
         return util.inflate_long(self.get_binary())
 
+    # TODO 4.0: depending on where this is used internally or downstream, force
+    # users to specify get_binary instead and delete this.
     def get_string(self):
         """
-        Fetch a `str` from the stream.  This could be a byte string and may
-        contain unprintable characters.  (It's not unheard of for a string to
-        contain another byte-stream message.)
+        Fetch a "string" from the stream.  This will actually be a `bytes`
+        object, and may contain unprintable characters.  (It's not unheard of
+        for a string to contain another byte-stream message.)
         """
         return self.get_bytes(self.get_int())
 
+    # TODO 4.0: also consider having this take over the get_string name, and
+    # remove this name instead.
     def get_text(self):
         """
         Fetch a Unicode string from the stream.
+
+        This currently operates by attempting to encode the next "string" as
+        ``utf-8``.
         """
         return u(self.get_string())
 
     def get_binary(self):
         """
-        Fetch a string from the stream.  This could be a byte string and may
-        contain unprintable characters.  (It's not unheard of for a string to
-        contain another byte-stream Message.)
+        Alias for `get_string` (obtains a bytestring).
         """
         return self.get_bytes(self.get_int())
 
@@ -198,7 +204,7 @@ class Message(object):
         """
         Write bytes to the stream, without any formatting.
 
-        :param str b: bytes to add
+        :param bytes b: bytes to add
         """
         self.packet.write(b)
         return self
@@ -207,7 +213,7 @@ class Message(object):
         """
         Write a single byte to the stream, without any formatting.
 
-        :param str b: byte to add
+        :param bytes b: byte to add
         """
         self.packet.write(b)
         return self
@@ -250,7 +256,7 @@ class Message(object):
         """
         Add a 64-bit int to the stream.
 
-        :param long n: long int to add
+        :param int n: long int to add
         """
         self.packet.write(struct.pack(">Q", n))
         return self
@@ -260,16 +266,18 @@ class Message(object):
         Add a long int to the stream, encoded as an infinite-precision
         integer.  This method only works on positive numbers.
 
-        :param long z: long int to add
+        :param int z: long int to add
         """
         self.add_string(util.deflate_long(z))
         return self
 
+    # TODO: see the TODO for get_string/get_text/et al, this should change
+    # to match.
     def add_string(self, s):
         """
-        Add a string to the stream.
+        Add a bytestring to the stream.
 
-        :param str s: string to add
+        :param byte s: bytestring to add
         """
         s = util.asbytes(s)
         self.add_int(len(s))
@@ -297,10 +305,12 @@ class Message(object):
         else:
             return self.add_string(i)
 
+    # TODO: this would never have worked for unicode strings under Python 3,
+    # guessing nobody/nothing ever used it for that purpose?
     def add(self, *seq):
         """
         Add a sequence of items to the stream.  The values are encoded based
-        on their type: str, int, bool, list, or long.
+        on their type: bytes, str, int, bool, or list.
 
         .. warning::
             Longs are encoded non-deterministically.  Don't use this method.
diff --git a/paramiko/pkey.py b/paramiko/pkey.py
index a74b5e1d..058d1258 100644
--- a/paramiko/pkey.py
+++ b/paramiko/pkey.py
@@ -201,7 +201,7 @@ class PKey(object):
         Sign a blob of data with this private key, and return a `.Message`
         representing an SSH signature message.
 
-        :param str data:
+        :param bytes data:
             the data to sign.
         :param str algorithm:
             the signature algorithm to use, if different from the key's
@@ -218,7 +218,7 @@ 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 str data: the data that was signed.
+        :param bytes data: the data that was signed.
         :param .Message msg: an SSH signature message
         :return:
             ``True`` if the signature verifies correctly; ``False`` otherwise.
@@ -311,7 +311,7 @@ class PKey(object):
         :param str password:
             an optional password to use to decrypt the key file, if it's
             encrypted.
-        :return: data blob (`str`) that makes up the private key.
+        :return: the `bytes` that make up the private key.
 
         :raises: ``IOError`` -- if there was an error reading the file.
         :raises: `.PasswordRequiredException` -- if the private key file is
@@ -555,7 +555,7 @@ class PKey(object):
         :param str tag:
             ``"RSA"`` or ``"DSA"``, the tag used to mark the data block.
         :param filename: name of the file to write.
-        :param str data: data blob that makes up the private key.
+        :param bytes data: data blob that makes up the private key.
         :param str password: an optional password to use to encrypt the file.
 
         :raises: ``IOError`` -- if there was an error writing the file.
@@ -691,7 +691,7 @@ class PublicBlob(object):
         Create a new public blob of given type and contents.
 
         :param str type_: Type indicator, eg ``ssh-rsa``.
-        :param blob: The blob bytes themselves.
+        :param bytes blob: The blob bytes themselves.
         :param str comment: A comment, if one was given (e.g. file-based.)
         """
         self.key_type = type_
diff --git a/paramiko/sftp_handle.py b/paramiko/sftp_handle.py
index 1b4e1363..b2046526 100644
--- a/paramiko/sftp_handle.py
+++ b/paramiko/sftp_handle.py
@@ -87,7 +87,7 @@ class SFTPHandle(ClosingContextManager):
 
         :param offset: position in the file to start reading from.
         :param int length: number of bytes to attempt to read.
-        :return: data read from the file, or an SFTP error code, as a `str`.
+        :return: the `bytes` read, or an error code `int`.
         """
         readfile = getattr(self, "readfile", None)
         if readfile is None:
@@ -120,7 +120,7 @@ class SFTPHandle(ClosingContextManager):
         refer to the same file.
 
         :param offset: position in the file to start reading from.
-        :param str data: data to write into the file.
+        :param bytes data: data to write into the file.
         :return: an SFTP error code like ``SFTP_OK``.
         """
         writefile = getattr(self, "writefile", None)
diff --git a/paramiko/transport.py b/paramiko/transport.py
index 99a7bbc9..8c124403 100644
--- a/paramiko/transport.py
+++ b/paramiko/transport.py
@@ -343,7 +343,7 @@ class Transport(threading.Thread, ClosingContextManager):
         If the object is not actually a socket, it must have the following
         methods:
 
-        - ``send(str)``: Writes from 1 to ``len(str)`` bytes, and returns an
+        - ``send(bytes)``: Writes from 1 to ``len(bytes)`` bytes, and returns an
           int representing the number of bytes written.  Returns
           0 or raises ``EOFError`` if the stream has been closed.
         - ``recv(int)``: Reads from 1 to ``int`` bytes and returns them as a
diff --git a/paramiko/util.py b/paramiko/util.py
index 07892cb1..9d9b0064 100644
--- a/paramiko/util.py
+++ b/paramiko/util.py
@@ -149,10 +149,10 @@ def generate_key_bytes(hash_alg, salt, key, nbytes):
     :param function hash_alg: A function which creates a new hash object, such
         as ``hashlib.sha256``.
     :param salt: data to salt the hash with.
-    :type salt: byte string
+    :type bytes salt: Hash salt bytes.
     :param str key: human-entered password or passphrase.
     :param int nbytes: number of bytes to generate.
-    :return: Key data `str`
+    :return: Key data, as `bytes`.
     """
     keydata = bytes()
     digest = bytes()
author	Jeff Forcier <jeff@bitprophet.org>	2023-01-12 17:20:51 -0500
committer	Jeff Forcier <jeff@bitprophet.org>	2023-01-12 21:44:59 -0500
commit	714350c4dd459577898d72a59edc3213a99443d6 (patch)
tree	8244b90e69d635fc755bda80bda24cf7dc7eaffe
parent	299556eebf3145019303278432e1fdb6cabb067e (diff)