[tor-commits] [stem/master] Revised API docs for stem.socket
atagar at torproject.org
atagar at torproject.org
Sun Oct 28 20:56:34 UTC 2012
commit 08fa765d219b24a8c0bb0142b71a940cd6fd7bf2
Author: Damian Johnson <atagar at torproject.org>
Date: Sat Oct 27 17:42:38 2012 -0700
Revised API docs for stem.socket
---
docs/api.rst | 1 +
docs/api/connection.rst | 4 +-
docs/api/socket.rst | 5 +++
docs/contents.rst | 1 +
stem/connection.py | 64 +++++++++++++++++++-------------------
stem/socket.py | 80 +++++++++++++++++++++-------------------------
6 files changed, 78 insertions(+), 77 deletions(-)
diff --git a/docs/api.rst b/docs/api.rst
index 65fa524..a893677 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -7,6 +7,7 @@ Controller
* **Core**
* `stem.connection <api/connection.html>`_ - Connection and authentication to the Tor control port or socket.
+ * `stem.socket <api/socket.html>`_ - Low level control socket used to talk with Tor.
* **Types**
diff --git a/docs/api/connection.rst b/docs/api/connection.rst
index 115ba26..ae3c7c7 100644
--- a/docs/api/connection.rst
+++ b/docs/api/connection.rst
@@ -1,5 +1,5 @@
-Connection
-==========
+Controller Connection
+=====================
.. automodule:: stem.connection
diff --git a/docs/api/socket.rst b/docs/api/socket.rst
new file mode 100644
index 0000000..33b7c51
--- /dev/null
+++ b/docs/api/socket.rst
@@ -0,0 +1,5 @@
+Control Socket
+==============
+
+.. automodule:: stem.socket
+
diff --git a/docs/contents.rst b/docs/contents.rst
index 467a122..ca93591 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -9,6 +9,7 @@ Contents
tutorial
api/connection
+ api/socket
api/exit_policy
api/version
diff --git a/stem/connection.py b/stem/connection.py
index 85b318a..730ad27 100644
--- a/stem/connection.py
+++ b/stem/connection.py
@@ -209,75 +209,75 @@ def authenticate(controller, password = None, chroot_path = None, protocolinfo_r
try multiple authentication methods it may encounter multiple exceptions.
If so then the exception this raises is prioritized as follows...
- * :class:`~stem.connection.IncorrectSocketType`
+ * :class:`stem.connection.IncorrectSocketType`
The controller does not speak the tor control protocol. Most often this
happened because the user confused the SocksPort or ORPort with the
ControlPort.
- * :class:`~stem.connection.UnrecognizedAuthMethods`
+ * :class:`stem.connection.UnrecognizedAuthMethods`
All of the authentication methods tor will accept are new and
unrecognized. Please upgrade stem and, if that doesn't work, file a
ticket on 'trac.torproject.org' and I'd be happy to add support.
- * :class:`~stem.connection.MissingPassword`
+ * :class:`stem.connection.MissingPassword`
We were unable to authenticate but didn't attempt password authentication
because none was provided. You should prompt the user for a password and
try again via 'authenticate_password'.
- * :class:`~stem.connection.IncorrectPassword`
+ * :class:`stem.connection.IncorrectPassword`
We were provided with a password but it was incorrect.
- * :class:`~stem.connection.IncorrectCookieSize`
+ * :class:`stem.connection.IncorrectCookieSize`
Tor allows for authentication by reading it a cookie file, but that file
is the wrong size to be an authentication cookie.
- * :class:`~stem.connection.UnreadableCookieFile`
+ * :class:`stem.connection.UnreadableCookieFile`
Tor allows for authentication by reading it a cookie file, but we can't
read that file (probably due to permissions).
- * **\***:class:`~stem.connection.IncorrectCookieValue`
+ * **\***:class:`stem.connection.IncorrectCookieValue`
Tor allows for authentication by reading it a cookie file, but rejected
the contents of that file.
- * **\***:class:`~stem.connection.AuthChallengeUnsupported`
+ * **\***:class:`stem.connection.AuthChallengeUnsupported`
Tor doesn't recognize the AUTHCHALLENGE command. This is probably a Tor
version prior to SAFECOOKIE being implement, but this exception shouldn't
arise because we won't attempt SAFECOOKIE auth unless Tor claims to
support it.
- * **\***:class:`~stem.connection.UnrecognizedAuthChallengeMethod`
+ * **\***:class:`stem.connection.UnrecognizedAuthChallengeMethod`
Tor couldn't recognize the AUTHCHALLENGE method Stem sent to it. This
shouldn't happen at all.
- * **\***:class:`~stem.connection.InvalidClientNonce`
+ * **\***:class:`stem.connection.InvalidClientNonce`
Tor says that the client nonce provided by Stem during the AUTHCHALLENGE
process is invalid.
- * **\***:class:`~stem.connection.AuthSecurityFailure`
+ * **\***:class:`stem.connection.AuthSecurityFailure`
Nonce value provided by the server was invalid.
- * **\***:class:`~stem.connection.OpenAuthRejected`
+ * **\***:class:`stem.connection.OpenAuthRejected`
Tor says that it allows for authentication without any credentials, but
then rejected our authentication attempt.
- * **\***:class:`~stem.connection.MissingAuthInfo`
+ * **\***:class:`stem.connection.MissingAuthInfo`
Tor provided us with a PROTOCOLINFO reply that is technically valid, but
missing the information we need to authenticate.
- * **\***:class:`~stem.connection.AuthenticationFailure`
+ * **\***:class:`stem.connection.AuthenticationFailure`
There are numerous other ways that authentication could have failed
including socket failures, malformed controller responses, etc. These
@@ -413,7 +413,7 @@ def authenticate_none(controller, suppress_ctl_errors = True):
:class:`~stem.socket.ControllerError` as authentication rejection if
**True**, otherwise they're re-raised
- :raises: :class:`~stem.connection.OpenAuthRejected` if the empty authentication credentials aren't accepted
+ :raises: :class:`stem.connection.OpenAuthRejected` if the empty authentication credentials aren't accepted
"""
try:
@@ -460,9 +460,9 @@ def authenticate_password(controller, password, suppress_ctl_errors = True):
**True**, otherwise they're re-raised
:raises:
- * :class:`~stem.connection.PasswordAuthRejected` if the socket doesn't
+ * :class:`stem.connection.PasswordAuthRejected` if the socket doesn't
accept password authentication
- * :class:`~stem.connection.IncorrectPassword` if the authentication
+ * :class:`stem.connection.IncorrectPassword` if the authentication
credentials aren't accepted
"""
@@ -530,11 +530,11 @@ def authenticate_cookie(controller, cookie_path, suppress_ctl_errors = True):
**True**, otherwise they're re-raised
:raises:
- * :class:`~stem.connection.IncorrectCookieSize` if the cookie file's size
+ * :class:`stem.connection.IncorrectCookieSize` if the cookie file's size
is wrong
- * :class:`~stem.connection.UnreadableCookieFile` if the cookie file doesn't
+ * :class:`stem.connection.UnreadableCookieFile` if the cookie file doesn't
exist or we're unable to read it
- * :class:`~stem.connection.CookieAuthRejected` if cookie authentication is
+ * :class:`stem.connection.CookieAuthRejected` if cookie authentication is
attempted but the socket doesn't accept it
* :class:`stem.connection.IncorrectCookieValue` if the cookie file's value
is rejected
@@ -609,21 +609,21 @@ def authenticate_safecookie(controller, cookie_path, suppress_ctl_errors = True)
**True**, otherwise they're re-raised
:raises:
- * :class:`~stem.connection.IncorrectCookieSize` if the cookie file's size
+ * :class:`stem.connection.IncorrectCookieSize` if the cookie file's size
is wrong
- * :class:`~stem.connection.UnreadableCookieFile` if the cookie file doesn't
+ * :class:`stem.connection.UnreadableCookieFile` if the cookie file doesn't
exist or we're unable to read it
- * :class:`~stem.connection.CookieAuthRejected` if cookie authentication is
+ * :class:`stem.connection.CookieAuthRejected` if cookie authentication is
attempted but the socket doesn't accept it
- * :class:`~stem.connection.IncorrectCookieValue` if the cookie file's value
+ * :class:`stem.connection.IncorrectCookieValue` if the cookie file's value
is rejected
- * :class:`~stem.connection.UnrecognizedAuthChallengeMethod` if the Tor
+ * :class:`stem.connection.UnrecognizedAuthChallengeMethod` if the Tor
client fails to recognize the AuthChallenge method
- * :class:`~stem.connection.AuthChallengeUnsupported` if AUTHCHALLENGE is
+ * :class:`stem.connection.AuthChallengeUnsupported` if AUTHCHALLENGE is
unimplemented, or if unable to parse AUTHCHALLENGE response
- * :class:`~stem.connection.AuthSecurityFailure` if AUTHCHALLENGE's response
+ * :class:`stem.connection.AuthSecurityFailure` if AUTHCHALLENGE's response
looks like a security attack
- * :class:`~stem.connection.InvalidClientNonce` if stem's AUTHCHALLENGE
+ * :class:`stem.connection.InvalidClientNonce` if stem's AUTHCHALLENGE
client nonce is rejected for being invalid
"""
@@ -713,9 +713,9 @@ def get_protocolinfo(controller):
:returns: :class:`~stem.response.protocolinfo.ProtocolInfoResponse` provided by tor
:raises:
- * :class:`~stem.socket.ProtocolError` if the PROTOCOLINFO response is
+ * :class:`stem.socket.ProtocolError` if the PROTOCOLINFO response is
malformed
- * :class:`~stem.socket.SocketError` if problems arise in establishing or
+ * :class:`stem.socket.SocketError` if problems arise in establishing or
using the socket
"""
@@ -780,9 +780,9 @@ def _read_cookie(cookie_path, is_safecookie):
authentication, **False** if for COOKIE
:raises:
- * :class:`~stem.connection.UnreadableCookieFile` if the cookie file is
+ * :class:`stem.connection.UnreadableCookieFile` if the cookie file is
unreadable
- * :class:`~stem.connection.IncorrectCookieSize` if the cookie size is
+ * :class:`stem.connection.IncorrectCookieSize` if the cookie size is
incorrect (not 32 bytes)
"""
diff --git a/stem/socket.py b/stem/socket.py
index e76e841..58dc5e2 100644
--- a/stem/socket.py
+++ b/stem/socket.py
@@ -1,7 +1,7 @@
"""
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 :class:`stem.response.ControlMessage` class.
+as instances of the :class:`~stem.response.ControlMessage` class.
**Module Overview:**
@@ -54,7 +54,7 @@ class ControlSocket(object):
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):
@@ -71,7 +71,7 @@ class ControlSocket(object):
def send(self, message, raw = False):
"""
Formats and sends a message to the control socket. For more information see
- the :func:`stem.socket.send_message` function.
+ the :func:`~stem.socket.send_message` function.
: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
@@ -94,9 +94,9 @@ class ControlSocket(object):
def recv(self):
"""
Receives a message from the control socket, blocking until we've received
- one. For more information see the :func:`stem.socket.recv_message` function.
+ one. For more information see the :func:`~stem.socket.recv_message` function.
- :returns: :class:`stem.response.ControlMessage` for the message received
+ :returns: :class:`~stem.response.ControlMessage` for the message received
:raises:
* :class:`stem.socket.ProtocolError` the content from the socket is malformed
@@ -140,12 +140,14 @@ class ControlSocket(object):
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 :func:`~stem.socket.ControlSocket.recv` call. Socket file
+ derived connections know after either a
+ :func:`~stem.socket.ControlSocket.send` or
+ :func:`~stem.socket.ControlSocket.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
- :class:`stem.control.BaseController` does).
+ :class:`~stem.control.BaseController` does).
:returns: bool that's True if we're known to be shut down and False otherwise
"""
@@ -222,10 +224,12 @@ class ControlSocket(object):
def _get_send_lock(self):
"""
The send lock is useful to classes that interact with us at a deep level
- because it's used to lock connect() / close(), and by extension our
- is_alive() state changes.
+ because it's used to lock :func:`stem.socket.ControlSocket.connect` /
+ :func:`stem.socket.ControlSocket.close`, and by extension our
+ :func:`stem.socket.ControlSocket.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
@@ -254,11 +258,11 @@ class ControlSocket(object):
"""
Constructs and connects new socket. This is implemented by subclasses.
- :returns: socket.socket for our configuration
+ :returns: **socket.socket** for our configuration
:raises:
* :class:`stem.socket.SocketError` if unable to make a socket
- * NotImplementedError if not implemented by a subclass
+ * **NotImplementedError** if not implemented by a subclass
"""
raise NotImplementedError("Unsupported Operation: this should be implemented by the ControlSocket subclass")
@@ -277,7 +281,8 @@ class ControlPort(ControlSocket):
:param int control_port: port number of the controller
:param bool connect: connects to the socket if True, leaves it unconnected otherwise
- :raises: :class:`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
"""
super(ControlPort, self).__init__()
@@ -325,7 +330,8 @@ class ControlSocketFile(ControlSocket):
: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: :class:`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
"""
super(ControlSocketFile, self).__init__()
@@ -371,9 +377,11 @@ def send_message(control_file, message, raw = False):
<line 3>\\r\\n
.\\r\\n
- :param file control_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)
: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
+ :param bool raw: leaves the message formatting untouched, passing it to the
+ socket as-is
:raises:
* :class:`stem.socket.SocketError` if a problem arises in using the socket
@@ -411,13 +419,15 @@ def recv_message(control_file):
Pulls from a control socket until we either have a complete message or
encounter a problem.
- :param file control_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: :class:`stem.response.ControlMessage` read from the socket
+ :returns: :class:`~stem.response.ControlMessage` read from the socket
: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
+ * :class:`stem.socket.SocketClosed` if the socket closes before we receive
+ a complete message
"""
parsed_content, raw_content = [], ""
@@ -522,11 +532,12 @@ def recv_message(control_file):
def send_formatting(message):
"""
Performs the formatting expected from sent control messages. For more
- information see the :func:`stem.socket.send_message` function.
+ information see the :func:`~stem.socket.send_message` function.
: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...
@@ -557,19 +568,11 @@ class OperationFailed(ControllerError):
Base exception class for failed operations that return an error code
:var str code: error code returned by Tor
- :var str message: error message returned by Tor or a human readable error message
+ :var str message: error message returned by Tor or a human readable error
+ message
"""
def __init__(self, code = None, message = None):
- """
- Initializes an OperationFailed object.
-
- :param str code: error code returned by Tor
- :param str message: error message returned by Tor or a human readable error message
-
- :returns: object of OperationFailed class
- """
-
super(ControllerError, self).__init__(message)
self.code = code
self.message = message
@@ -589,21 +592,12 @@ class InvalidArguments(InvalidRequest):
Exception class for requests which had invalid arguments.
:var str code: error code returned by Tor
- :var str message: error message returned by Tor or a human readable error message
+ :var str message: error message returned by Tor or a human readable error
+ message
:var list arguments: a list of arguments which were invalid
"""
def __init__(self, code = None, message = None, arguments = None):
- """
- Initializes an InvalidArguments object.
-
- :param str code: error code returned by Tor
- :param str message: error message returned by Tor or a human readable error message
- :param list arguments: a list of arguments which were invalid
-
- :returns: object of InvalidArguments class
- """
-
super(InvalidArguments, self).__init__(code, message)
self.arguments = arguments
More information about the tor-commits
mailing list