[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Converting stem.control to reStructuredText



commit cbcf257ee91f78a58984a2335814a589c51f14e9
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Tue Jun 5 07:54:20 2012 -0700

    Converting stem.control to reStructuredText
---
 docs/index.rst  |    5 ++
 stem/control.py |  144 ++++++++++++++++++++++++-------------------------------
 2 files changed, 68 insertions(+), 81 deletions(-)

diff --git a/docs/index.rst b/docs/index.rst
index 04348da..2cf68fd 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -13,6 +13,11 @@ Stem is a python controller library for `Tor <https://www.torproject.org/>`_. Li
 
 Connecting and authenticating to a Tor process.
 
+:mod:`stem.control`
+----------------------
+
+Provides the :class:`stem.control.Controller` class which, as the name implies, is used for talking with and controlling a Tor instance. As a user this is the primary class that you'll need.
+
 :mod:`stem.process`
 -------------------
 
diff --git a/stem/control.py b/stem/control.py
index a6bc3d2..7b56194 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -2,24 +2,26 @@
 Classes for interacting with the tor control socket.
 
 Controllers are a wrapper around a ControlSocket, retaining many of its methods
-(send, recv, is_alive, etc) in addition to providing its own for interacting at
-a higher level.
+(connect, close, is_alive, etc) in addition to providing its own for
+interacting at a higher level.
 
-from_port - Provides a Controller based on a port connection.
-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
-
-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
-  |- 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
-  +- __enter__ / __exit__ - manages socket connection
+  from_port - Provides a Controller based on a port connection.
+  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
+  
+  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
+    |- 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
+    +- __enter__ / __exit__ - manages socket connection
 """
 
 import time
@@ -39,9 +41,9 @@ State = stem.util.enum.Enum("INIT", "RESET", "CLOSED")
 
 # Constant to indicate an undefined argument default. Usually we'd use None for
 # this, but users will commonly provide None as the argument so need something
-# else very, very unique...
+# else fairly unique...
 
-UNDEFINED = "<Undefined>" * 10
+UNDEFINED = "<Undefined_ >"
 
 class BaseController:
   """
@@ -88,16 +90,14 @@ class BaseController:
     """
     Sends a message to our control socket and provides back its reply.
     
-    Arguments:
-      message (str) - message to be formatted and sent to tor
+    :param str message: message to be formatted and sent to tor
     
-    Returns:
-      stem.response.ControlMessage with the response
+    :returns: :class:`stem.response.ControlMessage` with the response
     
-    Raises:
-      stem.socket.ProtocolError the content from the socket is malformed
-      stem.socket.SocketError if a problem arises in using the socket
-      stem.socket.SocketClosed if the socket is shut down
+    :raises:
+      * :class:`stem.socket.ProtocolError` the content from the socket is malformed
+      * :class:`stem.socket.SocketError` if a problem arises in using the socket
+      * :class:`stem.socket.SocketClosed` if the socket is shut down
     """
     
     with self._msg_lock:
@@ -161,8 +161,7 @@ class BaseController:
     Checks if our socket is currently connected. This is a passthrough for our
     socket's is_alive() method.
     
-    Returns:
-      bool that's True if we're shut down and False otherwise
+    :returns: bool that's True if we're shut down and False otherwise
     """
     
     return self._socket.is_alive()
@@ -172,8 +171,7 @@ class BaseController:
     Reconnects our control socket. This is a passthrough for our socket's
     connect() method.
     
-    Raises:
-      stem.socket.SocketError if unable to make a socket
+    :raises: :class:`stem.socket.SocketError` if unable to make a socket
     """
     
     self._socket.connect()
@@ -181,7 +179,7 @@ class BaseController:
   def close(self):
     """
     Closes our socket connection. This is a passthrough for our socket's
-    close() method.
+    :func:`stem.socket.ControlSocket.close` method.
     """
     
     self._socket.close()
@@ -191,8 +189,7 @@ class BaseController:
     Provides the socket used to speak with the tor process. Communicating with
     the socket directly isn't advised since it may confuse the controller.
     
-    Returns:
-      ControlSocket for process communications
+    :returns: :class:`stem.socket.ControlSocket` we're communicating with
     """
     
     return self._socket
@@ -202,13 +199,15 @@ class BaseController:
     Notifies a given function when the state of our socket changes. Functions
     are expected to be of the form...
     
+    ::
+    
       my_function(controller, state, timestamp)
     
-    The state is a value from stem.socket.State, functions *must* allow for
+    The state is a value from stem.socket.State, functions **must** allow for
     new values in this field. The timestamp is a float for the unix time when
     the change occured.
     
-    This class only provides State.INIT and State.CLOSED notifications.
+    This class only provides ``State.INIT`` and ``State.CLOSED`` notifications.
     Subclasses may provide others.
     
     If spawn is True then the callback is notified via a new daemon thread. If
@@ -216,10 +215,8 @@ class BaseController:
     change occured. In general this isn't advised, especially if your callback
     could block for a while.
     
-    Arguments:
-      callback (function) - function to be notified when our state changes
-      spawn (bool)        - calls function via a new thread if True, otherwise
-                            it's part of the connect/close method call
+    :param function callback: function to be notified when our state changes
+    :param bool spawn: calls function via a new thread if True, otherwise it's part of the connect/close method call
     """
     
     with self._status_listeners_lock:
@@ -229,12 +226,9 @@ class BaseController:
     """
     Stops listener from being notified of further events.
     
-    Arguments:
-      callback (function) - function to be removed from our listeners
+    :param function callback: function to be removed from our listeners
     
-    Returns:
-      bool that's True if we removed one or more occurances of the callback,
-      False otherwise
+    :returns: bool that's True if we removed one or more occurances of the callback, False otherwise
     """
     
     with self._status_listeners_lock:
@@ -259,9 +253,7 @@ class BaseController:
     Callback to be overwritten by subclasses for event listening. This is
     notified whenever we receive an event from the control socket.
     
-    Arguments:
-      event_message (stem.response.ControlMessage) - message received from the
-          control socket
+    :param stem.response.ControlMessage event_message: message received from the control socket
     """
     
     pass
@@ -293,18 +285,16 @@ class BaseController:
     
     States imply that our socket is either alive or not, which may not hold
     true when multiple events occure in quick succession. For instance, a
-    sighup could cause two events (State.RESET for the sighup and State.CLOSE
-    if it causes tor to crash). However, there's no guarentee of the order in
-    which they occure, and it would be bad if listeners got the State.RESET
-    last, implying that we were alive.
+    sighup could cause two events (``State.RESET`` for the sighup and
+    ``State.CLOSE`` if it causes tor to crash). However, there's no guarentee
+    of the order in which they occure, and it would be bad if listeners got the
+    ``State.RESET`` last, implying that we were alive.
     
     If set, the expect_alive flag will discard our event if it conflicts with
-    our current is_alive() state.
+    our current :func:`stem.control.BaseController.is_alive` state.
     
-    Arguments:
-      state (stem.socket.State) - state change that has occured
-      expect_alive (bool)       - discard event if it conflicts with our
-                                  is_alive() state
+    :param stem.socket.State state: state change that has occured
+    :param bool expect_alive: discard event if it conflicts with our :func:`stem.control.BaseController.is_alive` state
     """
     
     # Any changes to our is_alive() state happen under the send lock, so we
@@ -352,8 +342,8 @@ class BaseController:
     Continually pulls from the control socket, directing the messages into
     queues based on their type. Controller messages come in two varieties...
     
-    - Responses to messages we've sent (GETINFO, SETCONF, etc).
-    - Asynchronous events, identified by a status code of 650.
+    * Responses to messages we've sent (GETINFO, SETCONF, etc).
+    * Asynchronous events, identified by a status code of 650.
     """
     
     while self.is_alive():
@@ -403,15 +393,12 @@ class Controller(BaseController):
     """
     Constructs a ControlPort based Controller.
     
-    Arguments:
-      control_addr (str) - ip address of the controller
-      control_port (int) - port number of the controller
+    :param str control_addr: ip address of the controller
+    :param int control_port: port number of the controller
     
-    Returns:
-      stem.control.Controller attached to the given port
+    :returns: :class:`stem.control.Controller` attached to the given port
     
-    Raises:
-      stem.socket.SocketError if we're unable to establish a connection
+    :raises: :class:`stem.socket.SocketError` if we're unable to establish a connection
     """
     
     control_port = stem.socket.ControlPort(control_addr, control_port)
@@ -421,14 +408,11 @@ class Controller(BaseController):
     """
     Constructs a ControlSocketFile based Controller.
     
-    Arguments:
-      socket_path (str) - path where the control socket is located
+    :param str socket_path: path where the control socket is located
     
-    Returns:
-      stem.control.Controller attached to the given socket file
+    :returns: :class:`stem.control.Controller` attached to the given socket file
     
-    Raises:
-      stem.socket.SocketError if we're unable to establish a connection
+    :raises: :class:`stem.socket.SocketError` if we're unable to establish a connection
     """
     
     control_socket = stem.socket.ControlSocketFile(socket_path)
@@ -444,19 +428,17 @@ class Controller(BaseController):
     call fails for any reason (error response, control port closed, initiated,
     etc).
     
-    Arguments:
-      param (str, list) - GETINFO option or options to be queried
-      default (object)  - response if the query fails
+    :param str,list param: GETINFO option or options to be queried
+    :param object default: response if the query fails
     
-    Returns:
+    :returns:
       Response depends upon how we were called as follows...
-      - str with the response if our param was a str
-      - dict with the param => response mapping if our param was a list
-      - default if one was provided and our call failed
+      
+      * str with the response if our param was a str
+      * dict with the param => response mapping if our param was a list
+      * default if one was provided and our call failed
     
-    Raises:
-      stem.socket.ControllerError if the call fails, and we weren't provided a
-      default response
+    :raises: :class:`stem.socket.ControllerError` if the call fails, and we weren't provided a default response
     """
     
     # TODO: add caching?



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits