diff options
Diffstat (limited to 'paramiko/message.py')
| -rw-r--r-- | paramiko/message.py | 118 |
1 files changed, 46 insertions, 72 deletions
diff --git a/paramiko/message.py b/paramiko/message.py index 45086213..a487f2e8 100644 --- a/paramiko/message.py +++ b/paramiko/message.py @@ -28,9 +28,9 @@ from paramiko.common import * class Message (object): """ - An SSH2 I{Message} is a stream of bytes that encodes some combination of - strings, integers, bools, and infinite-precision integers (known in python - as I{long}s). This class builds or breaks down such a byte stream. + An SSH2 message is a stream of bytes that encodes some combination of + strings, integers, bools, and infinite-precision integers (known in Python + as longs). This class builds or breaks down such a byte stream. Normally you don't need to deal with anything this low-level, but it's exposed for people implementing custom extensions, or features that @@ -41,11 +41,11 @@ class Message (object): def __init__(self, content=None): """ - Create a new SSH2 Message. + Create a new SSH2 message. - @param content: the byte stream to use as the Message content (passed - in only when decomposing a Message). - @type content: string + :param str content: + the byte stream to use as the message content (passed in only when + decomposing a message). """ if content != None: self.packet = BytesIO(content) @@ -53,13 +53,14 @@ class Message (object): self.packet = BytesIO() def __str__(self): + """ + Return the byte stream content of this message, as a string/bytes obj. + """ return self.asbytes() def __repr__(self): """ Returns a string representation of this object, for debugging. - - @rtype: string """ return 'paramiko.Message(' + repr(self.packet.getvalue()) + ')' @@ -81,11 +82,8 @@ class Message (object): def get_remainder(self): """ - Return the bytes of this Message that haven't already been parsed and - returned. - - @return: a string of the bytes not parsed yet. - @rtype: string + Return the bytes (as a `str`) of this message that haven't already been + parsed and returned. """ position = self.packet.tell() remainder = self.packet.read() @@ -94,12 +92,9 @@ class Message (object): def get_so_far(self): """ - 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 C{get_so_far} and L{get_remainder}. - - @return: a string of the bytes parsed so far. - @rtype: string + Returns the `str` 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`. """ position = self.packet.tell() self.rewind() @@ -107,12 +102,10 @@ class Message (object): def get_bytes(self, n): """ - Return the next C{n} bytes of the Message, without decomposing into - an int, string, etc. Just the raw bytes are returned. - - @return: a string of the next C{n} bytes of the Message, or a string - of C{n} zero bytes, if there aren't C{n} bytes remaining. - @rtype: string + 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. """ b = self.packet.read(n) max_pad_size = 1<<20 # Limit padding to 1 MB @@ -122,21 +115,18 @@ class Message (object): def get_byte(self): """ - Return the next byte of the Message, without decomposing it. This - is equivalent to L{get_bytes(1)<get_bytes>}. + Return the next byte of the message, without decomposing it. This + is equivalent to `get_bytes(1) <get_bytes>`. - @return: the next byte of the Message, or C{'\000'} if there aren't + :return: + the next (`str`) byte of the message, or ``'\000'`` if there aren't any bytes remaining. - @rtype: string """ return self.get_bytes(1) def get_boolean(self): """ Fetch a boolean from the stream. - - @return: C{True} or C{False} (from the Message). - @rtype: bool """ b = self.get_bytes(1) return b != zero_byte @@ -145,8 +135,7 @@ class Message (object): """ Fetch an int from the stream. - @return: a 32-bit unsigned integer. - @rtype: int + :return: a 32-bit unsigned `int`. """ byte = self.get_bytes(1) if byte == max_byte: @@ -167,8 +156,7 @@ class Message (object): """ Fetch a 64-bit int from the stream. - @return: a 64-bit unsigned integer. - @rtype: long + :return: a 64-bit unsigned integer (`long`). """ return struct.unpack('>Q', self.get_bytes(8))[0] @@ -176,19 +164,15 @@ class Message (object): """ Fetch a long int (mpint) from the stream. - @return: an arbitrary-length integer. - @rtype: long + :return: an arbitrary-length integer (`long`). """ return util.inflate_long(self.get_binary()) def get_string(self): """ - Fetch a string from the stream. This could be a byte string and may + 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.) - - @return: a string. - @rtype: string + contain another byte-stream message.) """ return self.get_bytes(self.get_size()) @@ -217,11 +201,9 @@ class Message (object): def get_list(self): """ - Fetch a list of strings from the stream. These are trivially encoded - as comma-separated values in a string. - - @return: a list of strings. - @rtype: list of strings + Fetch a `list` of `strings <str>` from the stream. + + These are trivially encoded as comma-separated values in a string. """ return self.get_text().split(',') @@ -229,8 +211,7 @@ class Message (object): """ Write bytes to the stream, without any formatting. - @param b: bytes to add - @type b: str + :param str b: bytes to add """ self.packet.write(b) return self @@ -239,8 +220,7 @@ class Message (object): """ Write a single byte to the stream, without any formatting. - @param b: byte to add - @type b: str + :param str b: byte to add """ self.packet.write(b) return self @@ -249,8 +229,7 @@ class Message (object): """ Add a boolean value to the stream. - @param b: boolean value to add - @type b: bool + :param bool b: boolean value to add """ if b: self.packet.write(one_byte) @@ -267,27 +246,25 @@ class Message (object): """ self.packet.write(struct.pack('>I', n)) return self - + def add_int(self, n): """ Add an integer to the stream. - - @param n: integer to add - @type n: int + + :param int n: integer to add """ if n >= Message.big_int: self.packet.write(max_byte) self.add_string(util.deflate_long(n)) else: - self.packet.write(struct.pack('>I', n)) + self.packet.write(struct.pack('>I', n)) return self def add_int64(self, n): """ Add a 64-bit int to the stream. - @param n: long int to add - @type n: long + :param long n: long int to add """ self.packet.write(struct.pack('>Q', n)) return self @@ -297,8 +274,7 @@ class Message (object): Add a long int to the stream, encoded as an infinite-precision integer. This method only works on positive numbers. - @param z: long int to add - @type z: long + :param long z: long int to add """ self.add_string(util.deflate_long(z)) return self @@ -307,8 +283,7 @@ class Message (object): """ Add a string to the stream. - @param s: string to add - @type s: str + :param str s: string to add """ s = asbytes(s) self.add_size(len(s)) @@ -321,8 +296,7 @@ class Message (object): a single string of values separated by commas. (Yes, really, that's how SSH2 does it.) - @param l: list of strings to add - @type l: list(str) + :param list l: list of strings to add """ self.add_string(','.join(l)) return self @@ -341,11 +315,11 @@ class Message (object): """ Add a sequence of items to the stream. The values are encoded based on their type: str, int, bool, list, or long. + + .. warning:: + Longs are encoded non-deterministically. Don't use this method. - @param seq: the sequence of items - @type seq: sequence - - @bug: longs are encoded non-deterministically. Don't use this method. + :param seq: the sequence of items """ for item in seq: self._add(item) |