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

[tor-commits] [stem/master] Revised API docs for stem.socket



commit 08fa765d219b24a8c0bb0142b71a940cd6fd7bf2
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
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
 



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