[project @ Arch-1:robey@lag.net--2005-master-shake%paramiko--dev--1--patch-50]

add docs to Message

1 files changed, 59 insertions, 2 deletions

diff --git a/paramiko/message.py b/paramiko/message.py
index fd5505c7..e36d93a3 100644
--- a/paramiko/message.py
+++ b/paramiko/message.py
@@ -29,6 +29,10 @@ 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.
+    
+    Normally you don't need to deal with anything this low-level, but it's
+    exposed for people implementing custom extensions, or features that
+    paramiko doesn't support yet.
     """
 
     def __init__(self, content=None):
@@ -178,14 +182,32 @@ class Message (object):
         return self.get_string().split(',')
 
     def add_bytes(self, b):
+        """
+        Write bytes to the stream, without any formatting.
+        
+        @param b: bytes to add
+        @type b: str
+        """
         self.packet.write(b)
         return self
 
     def add_byte(self, b):
+        """
+        Write a single byte to the stream, without any formatting.
+        
+        @param b: byte to add
+        @type b: str
+        """
         self.packet.write(b)
         return self
 
     def add_boolean(self, b):
+        """
+        Add a boolean value to the stream.
+        
+        @param b: boolean value to add
+        @type b: bool
+        """
         if b:
             self.add_byte('\x01')
         else:
@@ -193,6 +215,12 @@ class Message (object):
         return self
             
     def add_int(self, n):
+        """
+        Add an integer to the stream.
+        
+        @param n: integer to add
+        @type n: int
+        """
         self.packet.write(struct.pack('>I', n))
         return self
 
@@ -200,23 +228,43 @@ class Message (object):
         """
         Add a 64-bit int to the stream.
 
-        @param n: long int to add.
+        @param n: long int to add
         @type n: long
         """
         self.packet.write(struct.pack('>Q', n))
         return self
 
     def add_mpint(self, z):
-        "this only works on positive numbers"
+        """
+        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
+        """
         self.add_string(util.deflate_long(z))
         return self
 
     def add_string(self, s):
+        """
+        Add a string to the stream.
+        
+        @param s: string to add
+        @type s: str
+        """
         self.add_int(len(s))
         self.packet.write(s)
         return self
 
     def add_list(self, l):
+        """
+        Add a list of strings to the stream.  They are encoded identically to
+        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)
+        """
         self.add_string(','.join(l))
         return self
         
@@ -238,5 +286,14 @@ class Message (object):
             raise exception('Unknown type')
 
     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.
+        
+        @param seq: the sequence of items
+        @type seq: sequence
+        
+        @bug: longs are encoded non-deterministically.  Don't use this method.
+        """
         for item in seq:
             self._add(item)