[tor-commits] [stem/master] Converting stem.control to reStructuredText
atagar at torproject.org
atagar at torproject.org
Wed Jun 6 04:30:17 UTC 2012
commit cbcf257ee91f78a58984a2335814a589c51f14e9
Author: Damian Johnson <atagar at torproject.org>
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?
More information about the tor-commits
mailing list