commit fc327f29f66a84850ab89a32f3dd358756797029 Author: Beck csybeck@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)