[tor-commits] [stem/master] Move all convenience functions to Controller class, and minor changes on them

[atagar at torproject.org]

commit fc327f29f66a84850ab89a32f3dd358756797029
Author: Beck <csybeck at gmail.com>
Date:   Fri Jun 8 00:31:56 2012 +0800

    Move all convenience functions to Controller class, and minor changes on them
---
 stem/control.py |   69 +++++++++++++++++++++++++++++++++---------------------
 1 files changed, 42 insertions(+), 27 deletions(-)

diff --git a/stem/control.py b/stem/control.py
index 3568937..25b7b68 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -13,16 +13,16 @@ interacting at a higher level.
   from_socket_file - Provides a Controller based on a socket file connection.
   
   Controller - General controller class intended for direct use.
-    +- get_info - issues a GETINFO query
-    +- get_version - convenient method to get tor version
+    |- get_info - issues a GETINFO query
+    |- get_version - convenience method to get tor version
+    |- authenticate - convenience method to authenticate the controller
+    +- protocolinfo - convenience method to get the protocol info
   
   BaseController - Base controller class asynchronous message handling.
     |- msg - communicates with the tor process
     |- is_alive - reports if our connection to tor is open or closed
     |- connect - connects or reconnects to tor
     |- close - shuts down our connection to the tor process
-    |- authenticate - convenient method to authenticate the controller
-    |- protocolinfo - convenient method to get the protocol info
     |- get_socket - provides the socket used for control communication
     |- add_status_listener - notifies a callback of changes in our status
     |- remove_status_listener - prevents further notification of status changes
@@ -201,25 +201,7 @@ class BaseController:
     
     return self._socket
 
-  def authenticate(self, *args, **kwargs):
-    """
-    A convenient method to authenticate the controller. See the docstring of 
-    :func:`stem.connection.authenticate` for details about parameters and 
-    exceptions.
-    """
-
-    import stem.connection
-    stem.connection.authenticate(self, *args, **kwargs)
-
-  def protocolinfo(self):
-    """
-    A convenient method to get the protocol info of the controller. See the
-    docstring of :func:`stem.connection.get_protocolinfo()` for details about 
-    params, return value, and exceptions.
-    """
-
-    import stem.connection
-    return stem.connection.get_protocolinfo(self)
+  
   
   def add_status_listener(self, callback, spawn = True):
     """
@@ -502,10 +484,43 @@ class Controller(BaseController):
 
   def get_version(self):
     """
-    A convenient method to get tor version from controller. See the docstring
-    of :func:`get_info` for details about parameters, return value and 
-    exceptions.
+    A convenience method to get tor version that current controller is
+    connected to.
+
+    :returns: :class:`stem.version.Version`
+
+    :raises:
+      * :class:`stem.socket.ControllerError` if unable to query the version
+      * ValueError if unable to parse the version
     """
 
-    return self.get_info("version")
+    import stem.version
+    raw_str = self.get_info("version")
+    version_str = raw_str[:raw_str.find(' ')]
+    return stem.version.Version(version_str)
 
+  def authenticate(self, *args, **kwargs):
+    """
+    A convenience method to authenticate the controller.
+
+    :param: see :func:`stem.connection.authenticate`
+
+    :raises: see :func:`stem.connection.authenticate`
+    """
+
+    import stem.connection
+    stem.connection.authenticate(self, *args, **kwargs)
+
+  def protocolinfo(self):
+    """
+    A convenience method to get the protocol info of the controller.
+  
+    :returns: :class:`stem.response.protocolinfo.ProtocolInfoResponse` provided by tor
+  
+    :raises:
+      * :class:`stem.socket.ProtocolError` if the PROTOCOLINFO response is malformed
+      * :class:`stem.socket.SocketError` if problems arise in establishing or using the socket
+    """
+
+    import stem.connection
+    return stem.connection.get_protocolinfo(self)