[tor-commits] [stem/master] Converting stem.socket to reStructuredText
atagar at torproject.org
atagar at torproject.org
Wed Jun 6 04:30:17 UTC 2012
commit c350257b05455509ab99c9019747e63553a668d5
Author: Damian Johnson <atagar at torproject.org>
Date: Tue Jun 5 08:25:48 2012 -0700
Converting stem.socket to reStructuredText
---
docs/index.rst | 5 ++
stem/control.py | 2 +
stem/socket.py | 209 +++++++++++++++++++++++++------------------------------
3 files changed, 101 insertions(+), 115 deletions(-)
diff --git a/docs/index.rst b/docs/index.rst
index 2cf68fd..c3cd4d9 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -18,6 +18,11 @@ Connecting and authenticating to a Tor process.
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.socket`
+------------------
+
+Base classes for communicating with a tor control socket.
+
:mod:`stem.process`
-------------------
diff --git a/stem/control.py b/stem/control.py
index 7b56194..dbad4da 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -5,6 +5,8 @@ Controllers are a wrapper around a ControlSocket, retaining many of its methods
(connect, close, is_alive, etc) in addition to providing its own for
interacting at a higher level.
+**Module Overview:**
+
::
from_port - Provides a Controller based on a port connection.
diff --git a/stem/socket.py b/stem/socket.py
index 68cc7e4..2a9e737 100644
--- a/stem/socket.py
+++ b/stem/socket.py
@@ -1,31 +1,35 @@
"""
Supports message based communication with sockets speaking the tor control
protocol. This lets users send messages as basic strings and receive responses
-as instances of the ControlMessage class.
+as instances of the :class:`stem.response.ControlMessage` class.
-ControlSocket - Socket wrapper that speaks the tor control protocol.
- |- ControlPort - Control connection via a port.
- | |- get_address - provides the ip address of our socket
- | +- get_port - provides the port of our socket
- |
- |- ControlSocketFile - Control connection via a local file socket.
- | +- get_socket_path - provides the path of the socket we connect to
- |
- |- send - sends a message to the socket
- |- recv - receives a ControlMessage from the socket
- |- is_alive - reports if the socket is known to be closed
- |- connect - connects a new socket
- |- close - shuts down the socket
- +- __enter__ / __exit__ - manages socket connection
+**Module Overview:**
-send_message - Writes a message to a control socket.
-recv_message - Reads a ControlMessage from a control socket.
-send_formatting - Performs the formatting expected from sent messages.
+::
-ControllerError - Base exception raised when using the controller.
- |- ProtocolError - Malformed socket data.
- +- SocketError - Communication with the socket failed.
- +- SocketClosed - Socket has been shut down.
+ ControlSocket - Socket wrapper that speaks the tor control protocol.
+ |- ControlPort - Control connection via a port.
+ | |- get_address - provides the ip address of our socket
+ | +- get_port - provides the port of our socket
+ |
+ |- ControlSocketFile - Control connection via a local file socket.
+ | +- get_socket_path - provides the path of the socket we connect to
+ |
+ |- send - sends a message to the socket
+ |- recv - receives a ControlMessage from the socket
+ |- is_alive - reports if the socket is known to be closed
+ |- connect - connects a new socket
+ |- close - shuts down the socket
+ +- __enter__ / __exit__ - manages socket connection
+
+ send_message - Writes a message to a control socket.
+ recv_message - Reads a ControlMessage from a control socket.
+ send_formatting - Performs the formatting expected from sent messages.
+
+ ControllerError - Base exception raised when using the controller.
+ |- ProtocolError - Malformed socket data.
+ +- SocketError - Communication with the socket failed.
+ +- SocketClosed - Socket has been shut down.
"""
from __future__ import absolute_import
@@ -37,18 +41,6 @@ import stem.response
import stem.util.enum
import stem.util.log as log
-class ControllerError(Exception):
- "Base error for controller communication issues."
-
-class ProtocolError(ControllerError):
- "Malformed content from the control socket."
-
-class SocketError(ControllerError):
- "Error arose while communicating with the control socket."
-
-class SocketClosed(SocketError):
- "Control socket was closed before completing the message."
-
class ControlSocket:
"""
Wrapper for a socket connection that speaks the Tor control protocol. To the
@@ -56,7 +48,7 @@ class ControlSocket:
receiving complete messages. All methods are thread safe.
Callers should not instantiate this class directly, but rather use subclasses
- which are expected to implement the _make_socket method.
+ which are expected to implement the ``_make_socket()`` method.
"""
def __init__(self):
@@ -73,16 +65,14 @@ class ControlSocket:
def send(self, message, raw = False):
"""
Formats and sends a message to the control socket. For more information see
- the stem.socket.send_message function.
+ the :func:`stem.socket.send_message` function.
- Arguments:
- message (str) - message to be formatted and sent to the socket
- raw (bool) - leaves the message formatting untouched, passing it to
- the socket as-is
+ :param str message: message to be formatted and sent to the socket
+ :param bool raw: leaves the message formatting untouched, passing it to the socket as-is
- Raises:
- stem.socket.SocketError if a problem arises in using the socket
- stem.socket.SocketClosed if the socket is known to be shut down
+ :raises:
+ * :class:`stem.socket.SocketError` if a problem arises in using the socket
+ * :class:`stem.socket.SocketClosed` if the socket is known to be shut down
"""
with self._send_lock:
@@ -98,15 +88,13 @@ class ControlSocket:
def recv(self):
"""
Receives a message from the control socket, blocking until we've received
- one. For more information see the stem.socket.recv_message function.
+ one. For more information see the :func:`stem.socket.recv_message` function.
- Returns:
- stem.response.ControlMessage for the message received
+ :returns: :class:`stem.response.ControlMessage` for the message received
- Raises:
- stem.socket.ProtocolError the content from the socket is malformed
- stem.socket.SocketClosed if the socket closes before we receive a
- complete message
+ :raises:
+ * :class:`stem.socket.ProtocolError` the content from the socket is malformed
+ * :class:`stem.socket.SocketClosed` if the socket closes before we receive a complete message
"""
with self._recv_lock:
@@ -146,15 +134,14 @@ class ControlSocket:
until we either use it or have explicitily shut it down.
In practice a socket derived from a port knows about its disconnection
- after a failed recv() call. Socket file derived connections know after
- either a send() or recv().
+ after a failed ``recv()`` call. Socket file derived connections know after
+ either a ``send()`` or ``recv()``.
This means that to have reliable detection for when we're disconnected
you need to continually pull from the socket (which is part of what the
- BaseController does).
+ :class:`stem.control.BaseController` does).
- Returns:
- bool that's True if we're known to be shut down and False otherwise
+ :returns: bool that's True if we're known to be shut down and False otherwise
"""
return self._is_alive
@@ -164,8 +151,7 @@ class ControlSocket:
Connects to a new socket, closing our previous one if we're already
attached.
- Raises:
- stem.socket.SocketError if unable to make a socket
+ :raises: :class:`stem.socket.SocketError` if unable to make a socket
"""
with self._send_lock:
@@ -233,9 +219,7 @@ class ControlSocket:
because it's used to lock connect() / close(), and by extension our
is_alive() state changes.
- Returns:
- threading.RLock that governs sending messages to our socket and state
- changes
+ :returns: threading.RLock that governs sending messages to our socket and state changes
"""
return self._send_lock
@@ -264,12 +248,11 @@ class ControlSocket:
"""
Constructs and connects new socket. This is implemented by subclasses.
- Returns:
- socket.socket for our configuration
+ :returns: socket.socket for our configuration
- Raises:
- stem.socket.SocketError if unable to make a socket
- NotImplementedError if not implemented by a subclass
+ :raises:
+ * :class:`stem.socket.SocketError` if unable to make a socket
+ * NotImplementedError if not implemented by a subclass
"""
raise NotImplementedError("Unsupported Operation: this should be implemented by the ControlSocket subclass")
@@ -284,15 +267,11 @@ class ControlPort(ControlSocket):
"""
ControlPort constructor.
- Arguments:
- control_addr (str) - ip address of the controller
- control_port (int) - port number of the controller
- connect (bool) - connects to the socket if True, leaves it
- unconnected otherwise
+ :param str control_addr: ip address of the controller
+ :param int control_port: port number of the controller
+ :param bool connect: connects to the socket if True, leaves it unconnected otherwise
- Raises:
- stem.socket.SocketError if connect is True and we're unable to establish
- a connection
+ :raises: :class:`stem.socket.SocketError` if connect is True and we're unable to establish a connection
"""
ControlSocket.__init__(self)
@@ -305,8 +284,7 @@ class ControlPort(ControlSocket):
"""
Provides the ip address our socket connects to.
- Returns:
- str with the ip address of our socket
+ :returns: str with the ip address of our socket
"""
return self._control_addr
@@ -315,8 +293,7 @@ class ControlPort(ControlSocket):
"""
Provides the port our socket connects to.
- Returns:
- int with the port of our socket
+ :returns: int with the port of our socket
"""
return self._control_port
@@ -339,14 +316,10 @@ class ControlSocketFile(ControlSocket):
"""
ControlSocketFile constructor.
- Arguments:
- socket_path (str) - path where the control socket is located
- connect (bool) - connects to the socket if True, leaves it
- unconnected otherwise
+ :param str socket_path: path where the control socket is located
+ :param bool connect: connects to the socket if True, leaves it unconnected otherwise
- Raises:
- stem.socket.SocketError if connect is True and we're unable to establish
- a connection
+ :raises: :class:`stem.socket.SocketError` if connect is True and we're unable to establish a connection
"""
ControlSocket.__init__(self)
@@ -358,8 +331,7 @@ class ControlSocketFile(ControlSocket):
"""
Provides the path our socket connects to.
- Returns:
- str with the path for our control socket
+ :returns: str with the path for our control socket
"""
return self._socket_path
@@ -380,25 +352,26 @@ def send_message(control_file, message, raw = False):
line at the end). If the message doesn't contain a newline then it's sent
as...
- <message>\r\n
+ ::
+
+ <message>\\r\\n
+
+ and if it does contain newlines then it's split on ``\\n`` and sent as...
- and if it does contain newlines then it's split on \n and sent as...
+ ::
- +<line 1>\r\n
- <line 2>\r\n
- <line 3>\r\n
- .\r\n
+ +<line 1>\\r\\n
+ <line 2>\\r\\n
+ <line 3>\\r\\n
+ .\\r\\n
- Arguments:
- control_file (file) - file derived from the control socket (see the
- socket's makefile() method for more information)
- message (str) - message to be sent on the control socket
- raw (bool) - leaves the message formatting untouched, passing it
- to the socket as-is
+ :param file control_file: file derived from the control socket (see the socket's makefile() method for more information)
+ :param str message: message to be sent on the control socket
+ :param bool raw: leaves the message formatting untouched, passing it to the socket as-is
- Raises:
- stem.socket.SocketError if a problem arises in using the socket
- stem.socket.SocketClosed if the socket is known to be shut down
+ :raises:
+ * :class:`stem.socket.SocketError` if a problem arises in using the socket
+ * :class:`stem.socket.SocketClosed` if the socket is known to be shut down
"""
if not raw: message = send_formatting(message)
@@ -432,17 +405,13 @@ def recv_message(control_file):
Pulls from a control socket until we either have a complete message or
encounter a problem.
- Arguments:
- control_file (file) - file derived from the control socket (see the
- socket's makefile() method for more information)
+ :param file control_file: file derived from the control socket (see the socket's makefile() method for more information)
- Returns:
- stem.response.ControlMessage read from the socket
+ :returns: :class:`stem.response.ControlMessage` read from the socket
- Raises:
- stem.socket.ProtocolError the content from the socket is malformed
- stem.socket.SocketClosed if the socket closes before we receive a complete
- message
+ :raises:
+ * :class:`stem.socket.ProtocolError` the content from the socket is malformed
+ * :class:`stem.socket.SocketClosed` if the socket closes before we receive a complete message
"""
parsed_content, raw_content = [], ""
@@ -547,13 +516,11 @@ def recv_message(control_file):
def send_formatting(message):
"""
Performs the formatting expected from sent control messages. For more
- information see the stem.socket.send_message function.
+ information see the :func:`stem.socket.send_message` function.
- Arguments:
- message (str) - message to be formatted
+ :param str message: message to be formatted
- Returns:
- str of the message wrapped by the formatting expected from controllers
+ :returns: str of the message wrapped by the formatting expected from controllers
"""
# From control-spec section 2.2...
@@ -573,3 +540,15 @@ def send_formatting(message):
else:
return message + "\r\n"
+class ControllerError(Exception):
+ "Base error for controller communication issues."
+
+class ProtocolError(ControllerError):
+ "Malformed content from the control socket."
+
+class SocketError(ControllerError):
+ "Error arose while communicating with the control socket."
+
+class SocketClosed(SocketError):
+ "Control socket was closed before completing the message."
+
More information about the tor-commits
mailing list