- tor-commits - lists.torproject.org

[stem/master] Revised API docs for stem.process
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit d2cd6ccb0c9df470478278e570f732beec973df6 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 18:42:32 2012 -0700 Revised API docs for stem.process --- docs/api.rst | 1 + docs/api/process.rst | 5 +++++ docs/contents.rst | 1 + stem/process.py | 34 +++++++++++++++++++++------------- 4 files changed, 28 insertions(+), 13 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 223b5bc..c138240 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -9,6 +9,7 @@ Controller * `stem.control <api/control.html>`_ - **Controller used to talk with Tor**. * `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. + * `stem.process <api/process.html>`_ - Launcher for the Tor process. * **Types** diff --git a/docs/api/process.rst b/docs/api/process.rst new file mode 100644 index 0000000..0e87abf --- /dev/null +++ b/docs/api/process.rst @@ -0,0 +1,5 @@ +Tor Process +=========== + +.. automodule:: stem.process + diff --git a/docs/contents.rst b/docs/contents.rst index 6c19f33..03274a4 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -11,6 +11,7 @@ Contents api/control api/connection api/socket + api/process api/exit_policy api/version diff --git a/stem/process.py b/stem/process.py index 04f787a..25ff88a 100644 --- a/stem/process.py +++ b/stem/process.py @@ -39,19 +39,23 @@ def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_perce while. Usually this is done in 50 seconds or so, but occasionally calls seem to get stuck, taking well over the default timeout. - Note: Timeout argument does not work on Windows (`ticket + Note: The timeout argument does not work on Windows (`ticket <https://trac.torproject.org/5783>`_) :param str tor_cmd: command for starting tor :param list args: additional arguments for tor :param str torrc_path: location of the torrc for us to use - :param int completion_percent: percent of bootstrap completion at which this'll return - :param functor init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it - :param int timeout: time after which the attempt to start tor is aborted, no timeouts are applied if None + :param int completion_percent: percent of bootstrap completion at which + this'll return + :param functor init_msg_handler: optional functor that will be provided with + tor's initialization stdout as we get it + :param int timeout: time after which the attempt to start tor is aborted, no + timeouts are applied if **None** - :returns: subprocess.Popen instance for the tor subprocess + :returns: **subprocess.Popen** instance for the tor subprocess - :raises: OSError if we either fail to create the tor process or reached a timeout without success + :raises: **OSError** if we either fail to create the tor process or reached a + timeout without success """ if stem.util.system.is_windows(): @@ -138,19 +142,23 @@ def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_perce def launch_tor_with_config(config, tor_cmd = "tor", completion_percent = 100, init_msg_handler = None, timeout = DEFAULT_INIT_TIMEOUT): """ - Initializes a tor process, like :func:`stem.process.launch_tor`, but with a + Initializes a tor process, like :func:`~stem.process.launch_tor`, but with a customized configuration. This writes a temporary torrc to disk, launches tor, then deletes the torrc. - :param dict config: configuration options, such as ``{"ControlPort": "9051"}`` + :param dict config: configuration options, such as '{"ControlPort": "9051"}' :param str tor_cmd: command for starting tor - :param int completion_percent: percent of bootstrap completion at which this'll return - :param functor init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it - :param int timeout: time after which the attempt to start tor is aborted, no timeouts are applied if None + :param int completion_percent: percent of bootstrap completion at which + this'll return + :param functor init_msg_handler: optional functor that will be provided with + tor's initialization stdout as we get it + :param int timeout: time after which the attempt to start tor is aborted, no + timeouts are applied if **None** - :returns: subprocess.Popen instance for the tor subprocess + :returns: **subprocess.Popen** instance for the tor subprocess - :raises: OSError if we either fail to create the tor process or reached a timeout without success + :raises: **OSError** if we either fail to create the tor process or reached a + timeout without success """ torrc_path = tempfile.mkstemp(prefix = "torrc-", text = True)[1]

1 0

[stem/master] Revised API docs for stem.socket
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 08fa765d219b24a8c0bb0142b71a940cd6fd7bf2 Author: Damian Johnson <atagar(a)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

1 0

[stem/master] Revised API docs for stem.control
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 04ea42cba22be4defeddf0d11803c23476612bdd Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 18:16:34 2012 -0700 Revised API docs for stem.control --- docs/api.rst | 1 + docs/api/control.rst | 5 + docs/contents.rst | 1 + stem/control.py | 250 +++++++++++++++++++++++++++++--------------------- 4 files changed, 153 insertions(+), 104 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index a893677..223b5bc 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -6,6 +6,7 @@ Controller * **Core** + * `stem.control <api/control.html>`_ - **Controller used to talk with Tor**. * `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. diff --git a/docs/api/control.rst b/docs/api/control.rst new file mode 100644 index 0000000..45a3439 --- /dev/null +++ b/docs/api/control.rst @@ -0,0 +1,5 @@ +Controller +========== + +.. automodule:: stem.control + diff --git a/docs/contents.rst b/docs/contents.rst index ca93591..6c19f33 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -8,6 +8,7 @@ Contents download tutorial + api/control api/connection api/socket diff --git a/stem/control.py b/stem/control.py index 9fae790..b87048d 100644 --- a/stem/control.py +++ b/stem/control.py @@ -1,15 +1,15 @@ """ Classes for interacting with the tor control socket. -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. +Controllers are a wrapper around a :class:`~stem.socket.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:** :: - Controller - General controller class intended for direct use. + Controller - General controller class intended for direct use | |- from_port - Provides a Controller based on a port connection. | +- from_socket_file - Provides a Controller based on a socket file connection. | @@ -37,7 +37,7 @@ interacting at a higher level. |- authenticate - convenience method to authenticate the controller +- protocolinfo - convenience method to get the protocol info - BaseController - Base controller class asynchronous message handling. + 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 @@ -46,6 +46,11 @@ interacting at a higher level. |- 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 + + State - enumeration for states that a controller can have + |- INIT - new control connection + |- RESET - received a reset/sighup signal + +- CLOSED - control connection closed """ from __future__ import with_statement @@ -64,9 +69,6 @@ import stem.util.connection import stem.util.log as log # state changes a control socket can have -# INIT - new control connection -# RESET - received a reset/sighup signal -# CLOSED - control connection closed State = stem.util.enum.Enum("INIT", "RESET", "CLOSED") @@ -113,11 +115,12 @@ class BaseController(object): """ Controller for the tor process. This is a minimal base class for other controllers, providing basic process communication and event listing. Don't - use this directly - subclasses like the Controller provide higher level - functionality. + use this directly - subclasses like the :class:`~stem.control.Controller` + provide higher level functionality. - Do not continue to directly interacte with the ControlSocket we're - constructed from - use our wrapper methods instead. + It's highly suggested that you don't interact directly with the + :class:`~stem.socket.ControlSocket` that we're constructed from - use our + wrapper methods instead. """ def __init__(self, control_socket): @@ -156,11 +159,13 @@ class BaseController(object): :param str message: message to be formatted and sent to tor - :returns: :class:`stem.response.ControlMessage` with the response + :returns: :class:`~stem.response.ControlMessage` with the response :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.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 """ @@ -223,9 +228,9 @@ class BaseController(object): def is_alive(self): """ Checks if our socket is currently connected. This is a passthrough for our - socket's is_alive() method. + socket's :func:`~stem.socket.ControlSocket.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() @@ -233,7 +238,7 @@ class BaseController(object): def connect(self): """ Reconnects our control socket. This is a passthrough for our socket's - connect() method. + :func:`~stem.socket.ControlSocket.connect` method. :raises: :class:`stem.socket.SocketError` if unable to make a socket """ @@ -243,7 +248,7 @@ class BaseController(object): def close(self): """ Closes our socket connection. This is a passthrough for our socket's - :func:`stem.socket.ControlSocket.close` method. + :func:`~stem.socket.ControlSocket.close` method. """ self._socket.close() @@ -251,9 +256,9 @@ class BaseController(object): def get_socket(self): """ Provides the socket used to speak with the tor process. Communicating with - the socket directly isn't advised since it may confuse the controller. + the socket directly isn't advised since it may confuse this controller. - :returns: :class:`stem.socket.ControlSocket` we're communicating with + :returns: :class:`~stem.socket.ControlSocket` we're communicating with """ return self._socket @@ -271,16 +276,17 @@ class BaseController(object): 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 - false then the notice is under our locks, within the thread where the - change occured. In general this isn't advised, especially if your callback - could block for a while. + If spawn is **True** then the callback is notified via a new daemon thread. + If **False** then the notice is under our locks, within the thread where + the change occured. In general this isn't advised, especially if your + callback could block for a while. :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 + :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: @@ -292,7 +298,8 @@ class BaseController(object): :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: @@ -317,7 +324,8 @@ class BaseController(object): Callback to be overwritten by subclasses for event listening. This is notified whenever we receive an event from the control socket. - :param stem.response.ControlMessage event_message: message received from the control socket + :param stem.response.ControlMessage event_message: message received from + the control socket """ pass @@ -349,16 +357,17 @@ class BaseController(object): 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 + 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. + **State.RESET** last, implying that we were alive. If set, the expect_alive flag will discard our event if it conflicts with - our current :func:`stem.control.BaseController.is_alive` state. + our current :func:`~stem.control.BaseController.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 + :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 @@ -457,12 +466,12 @@ class Controller(BaseController): def from_port(control_addr = "127.0.0.1", control_port = 9051): """ - Constructs a ControlPort based Controller. + Constructs a :class:`~stem.socket.ControlPort` based Controller. :param str control_addr: ip address of the controller :param int control_port: port number of the controller - :returns: :class:`stem.control.Controller` attached to the given port + :returns: :class:`~stem.control.Controller` attached to the given port :raises: :class:`stem.socket.SocketError` if we're unable to establish a connection """ @@ -477,11 +486,11 @@ class Controller(BaseController): def from_socket_file(socket_path = "/var/run/tor/control"): """ - Constructs a ControlSocketFile based Controller. + Constructs a :class:`~stem.socket.ControlSocketFile` based Controller. :param str socket_path: path where the control socket is located - :returns: :class:`stem.control.Controller` attached to the given socket file + :returns: :class:`~stem.control.Controller` attached to the given socket file :raises: :class:`stem.socket.SocketError` if we're unable to establish a connection """ @@ -516,7 +525,7 @@ class Controller(BaseController): def is_caching_enabled(self): """ - True if caching has been enabled, False otherwise. + **True** if caching has been enabled, **False** otherwise. :returns: bool to indicate if caching is enabled """ @@ -525,14 +534,15 @@ class Controller(BaseController): def is_geoip_unavailable(self): """ - Provides True if we've concluded hat our geoip database is unavailable, - False otherwise. This is determined by having our 'GETINFO ip-to-country/*' - lookups fail so this will default to False if we aren't making those - queries. + Provides **True** if we've concluded hat our geoip database is unavailable, + **False** otherwise. This is determined by having our 'GETINFO + ip-to-country/\*' lookups fail so this will default to **False** if we + aren't making those queries. Geoip failures will be untracked if caching is disabled. - :returns: bool to indicate if we've concluded our geoip database to be unavailable or not + :returns: **bool** to indicate if we've concluded our geoip database to be + unavailable or not """ return self._geoip_failure_count >= GEOIP_FAILURE_THRESHOLD @@ -558,13 +568,15 @@ class Controller(BaseController): :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 + * **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: - * :class:`stem.socket.ControllerError` if the call fails and we weren't provided a default response - * :class:`stem.socket.InvalidArguments` if the 'param' requested was invalid + * :class:`stem.socket.ControllerError` if the call fails and we weren't + provided a default response + * :class:`stem.socket.InvalidArguments` if the 'param' requested was + invalid """ start_time = time.time() @@ -640,11 +652,12 @@ class Controller(BaseController): A convenience method to get tor version that current controller is connected to. - :returns: :class:`stem.version.Version` + :returns: :class:`~stem.version.Version` of the tor instance that we're + connected to :raises: * :class:`stem.socket.ControllerError` if unable to query the version - * ValueError if unable to parse the version + * **ValueError** if unable to parse the version """ if not self.is_caching_enabled(): @@ -663,11 +676,12 @@ class Controller(BaseController): :param str relay: fingerprint or nickname of the relay to be queried - :returns: :class:`stem.descriptor.server_descriptor.RelayDescriptor` for the given relay + :returns: :class:`~stem.descriptor.server_descriptor.RelayDescriptor` for the given relay :raises: * :class:`stem.socket.ControllerError` if unable to query the descriptor - * ValueError if **relay** doesn't conform with the patter for being a fingerprint or nickname + * **ValueError** if **relay** doesn't conform with the pattern for being + a fingerprint or nickname """ if stem.util.tor_tools.is_valid_fingerprint(relay): @@ -685,7 +699,9 @@ class Controller(BaseController): Provides an iterator for all of the server descriptors that tor presently knows about. - :returns: iterates over :class:`stem.descriptor.server_descriptor.RelayDescriptor` for relays in the tor network + :returns: iterates over + :class:`~stem.descriptor.server_descriptor.RelayDescriptor` for relays in + the tor network :raises: :class:`stem.socket.ControllerError` if unable to query tor """ @@ -706,11 +722,13 @@ class Controller(BaseController): :param str relay: fingerprint or nickname of the relay to be queried - :returns: :class:`stem.descriptor.router_status_entry.RouterStatusEntryV2` for the given relay + :returns: :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` + for the given relay :raises: * :class:`stem.socket.ControllerError` if unable to query the descriptor - * ValueError if **relay** doesn't conform with the patter for being a fingerprint or nickname + * **ValueError** if **relay** doesn't conform with the patter for being a + fingerprint or nickname """ if stem.util.tor_tools.is_valid_fingerprint(relay): @@ -728,7 +746,9 @@ class Controller(BaseController): Provides an iterator for all of the router status entries that tor presently knows about. - :returns: iterates over :class:`stem.descriptor.router_status_entry.RouterStatusEntryV2` for relays in the tor network + :returns: iterates over + :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV2` for + relays in the tor network :raises: :class:`stem.socket.ControllerError` if unable to query tor """ @@ -749,11 +769,8 @@ class Controller(BaseController): def authenticate(self, *args, **kwargs): """ - A convenience method to authenticate the controller. - - :param: see :func:`stem.connection.authenticate` - - :raises: see :func:`stem.connection.authenticate` + A convenience method to authenticate the controller. This is just a + passthrough to :func:`stem.connection.authenticate`. """ import stem.connection @@ -763,11 +780,13 @@ class Controller(BaseController): """ A convenience method to get the protocol info of the controller. - :returns: :class:`stem.response.protocolinfo.ProtocolInfoResponse` provided by tor + :returns: :class:`~stem.response.protocolinfo.ProtocolInfoResponse` provided by tor :raises: - * :class:`stem.socket.ProtocolError` if the PROTOCOLINFO response is malformed - * :class:`stem.socket.SocketError` if problems arise in establishing or using the socket + * :class:`stem.socket.ProtocolError` if the PROTOCOLINFO response is + malformed + * :class:`stem.socket.SocketError` if problems arise in establishing or + using the socket """ import stem.connection @@ -779,22 +798,26 @@ class Controller(BaseController): provided a default then that's returned as if the GETCONF option is undefined or if the call fails for any reason (invalid configuration option, error response, control port closed, initiated, etc). If the configuration key - consists of whitespace only, None is returned unless a default value is given. + consists of whitespace only, **None** is returned unless a default value is + given. :param str param: configuration option to be queried :param object default: response if the query fails - :param bool multiple: if True, the value(s) provided are lists of all returned values, otherwise this just provides the first value + :param bool multiple: if **True**, the value(s) provided are lists of all + returned values, otherwise this just provides the first value :returns: Response depends upon how we were called as follows... - * str with the response if multiple was False - * list with the response strings if multiple was True + * **str** with the response if multiple was **False** + * **list** with the response strings if multiple was **True** * default if one was provided and our call failed :raises: - * :class:`stem.socket.ControllerError` if the call fails and we weren't provided a default response - * :class:`stem.socket.InvalidArguments` if the configuration option requested was invalid + * :class:`stem.socket.ControllerError` if the call fails and we weren't + provided a default response + * :class:`stem.socket.InvalidArguments` if the configuration option + requested was invalid """ # Config options are case insensitive and don't contain whitespace. Using @@ -818,30 +841,36 @@ class Controller(BaseController): only whitespace are ignored. There's three use cases for GETCONF: + 1. a single value is provided 2. multiple values are provided for the option queried - 3. a set of options that weren't necessarily requested are returned (for instance querying HiddenServiceOptions gives HiddenServiceDir, HiddenServicePort, etc) + 3. a set of options that weren't necessarily requested are returned (for + instance querying HiddenServiceOptions gives HiddenServiceDir, + HiddenServicePort, etc) The vast majority of the options fall into the first two categories, in - which case calling get_conf() is sufficient. However, for batch queries or - the special options that give a set of values this provides back the full - response. As of tor version 0.2.1.25 HiddenServiceOptions was the only - option like this. - - The get_conf() and get_conf_map() functions both try to account for these - special mappings, so queried like get_conf("HiddenServicePort") should - behave as you'd expect. This method, however, simply returns whatever Tor - provides so get_conf_map("HiddenServicePort") will give the same response - as get_conf_map("HiddenServiceOptions"). + which case calling :func:`~stem.control.Controller.get_conf` is sufficient. + However, for batch queries or the special options that give a set of values + this provides back the full response. As of tor version 0.2.1.25 + HiddenServiceOptions was the only option like this. + + The :func:`~stem.control.Controller.get_conf` and + :func:`~stem.control.Controller.get_conf_map` functions both try to account + for these special mappings, so queried like get_conf("HiddenServicePort") + should behave as you'd expect. This method, however, simply returns + whatever Tor provides so get_conf_map("HiddenServicePort") will give the + same response as get_conf_map("HiddenServiceOptions"). :param str,list params: configuration option(s) to be queried :param object default: response if the query fails - :param bool multiple: if True, the value(s) provided are lists of all returned values,otherwise this just provides the first value + :param bool multiple: if **True**, the value(s) provided are lists of all + returned values,otherwise this just provides the first value :returns: Response depends upon how we were called as follows... - * dict of 'config key => value' mappings, the value is a list if 'multiple' is True and a str of just the first value otherwise + * **dict** of 'config key => value' mappings, the value is a list if + 'multiple' is **True** and a **str** of just the first value otherwise * default if one was provided and our call failed :raises: @@ -932,8 +961,10 @@ class Controller(BaseController): :raises: * :class:`stem.socket.ControllerError` if the call fails - * :class:`stem.socket.InvalidArguments` if configuration options requested was invalid - * :class:`stem.socket.InvalidRequest` if the configuration setting is impossible or if there's a syntax error in the configuration values + * :class:`stem.socket.InvalidArguments` if configuration options + requested was invalid + * :class:`stem.socket.InvalidRequest` if the configuration setting is + impossible or if there's a syntax error in the configuration values """ self.set_options({param: value}, False) @@ -947,7 +978,8 @@ class Controller(BaseController): :raises: * :class:`stem.socket.ControllerError` if the call fails * :class:`stem.socket.InvalidArguments` if configuration options requested was invalid - * :class:`stem.socket.InvalidRequest` if the configuration setting is impossible or if there's a syntax error in the configuration values + * :class:`stem.socket.InvalidRequest` if the configuration setting is + impossible or if there's a syntax error in the configuration values """ self.set_options(dict([(entry, None) for entry in params]), True) @@ -958,7 +990,7 @@ class Controller(BaseController): RESETCONF query. Both behave identically unless our value is None, in which case SETCONF sets the value to 0 or NULL, and RESETCONF returns it to its default value. This accepts str, list, or None values in a similar fashion - to :func:`stem.control.Controller.set_conf`. For example... + to :func:`~stem.control.Controller.set_conf`. For example... :: @@ -973,13 +1005,17 @@ class Controller(BaseController): reason this type of arguement would be useful is for hidden service configuration (those options are order dependent). - :param dict,list params: mapping of configuration options to the values we're setting it to - :param bool reset: issues a RESETCONF, returning None values to their defaults if True + :param dict,list params: mapping of configuration options to the values + we're setting it to + :param bool reset: issues a RESETCONF, returning **None** values to their + defaults if **True** :raises: * :class:`stem.socket.ControllerError` if the call fails - * :class:`stem.socket.InvalidArguments` if configuration options requested was invalid - * :class:`stem.socket.InvalidRequest` if the configuration setting is impossible or if there's a syntax error in the configuration values + * :class:`stem.socket.InvalidArguments` if configuration options + requested was invalid + * :class:`stem.socket.InvalidRequest` if the configuration setting is + impossible or if there's a syntax error in the configuration values """ start_time = time.time() @@ -1055,7 +1091,8 @@ class Controller(BaseController): :raises: * :class:`stem.socket.ControllerError` if the call fails - * :class:`stem.socket.OperationFailed` if the client is unable to save the configuration file + * :class:`stem.socket.OperationFailed` if the client is unable to save + the configuration file """ response = self.msg("SAVECONF") @@ -1071,11 +1108,11 @@ class Controller(BaseController): def is_feature_enabled(self, feature): """ Checks if a control connection feature is enabled. These features can be - enabled using :func:`stem.control.Controller.enable_feature`. + enabled using :func:`~stem.control.Controller.enable_feature`. :param str feature: feature to be checked - :returns: True if feature is enabled, False otherwise + :returns: **True** if feature is enabled, **False** otherwise """ feature = feature.upper() @@ -1104,6 +1141,7 @@ class Controller(BaseController): disabled. Feature names are case-insensitive. The following features are currently accepted: + * EXTENDED_EVENTS - Requests the extended event syntax * VERBOSE_NAMES - Replaces ServerID with LongName in events and GETINFO results @@ -1134,15 +1172,19 @@ class Controller(BaseController): Sends a signal to the Tor client. :param str signal: type of signal to be sent. Must be one of the following... - * RELOAD or HUP - reload configuration - * SHUTDOWN or INT - shut down, waiting ShutdownWaitLength first if we're a relay - * DUMP or USR1 - dump log information about open connections and circuits - * DEBUG or USR2 - switch logging to the DEBUG runlevel - * HALT or TERM - exit immediately - * NEWNYM - switch to new circuits, so new application requests don't share any circuits with old ones (this also clears our DNS cache) - * CLEARDNSCACHE - clears cached DNS results - :raises: :class:`stem.socket.InvalidArguments` if signal provided wasn't recognized. + * **RELOAD** or **HUP** - reload configuration + * **SHUTDOWN** or **INT** - shut down, waiting ShutdownWaitLength first + if we're a relay + * **DUMP** or **USR1** - dump log information about open connections and + circuits + * **DEBUG** or **USR2** - switch logging to the DEBUG runlevel + * **HALT** or **TERM** - exit immediately + * **NEWNYM** - switch to new circuits, so new application requests don't + share any circuits with old ones (this also clears our DNS cache) + * **CLEARDNSCACHE** - clears cached DNS results + + :raises: :class:`stem.socket.InvalidArguments` if signal provided wasn't recognized """ response = self.msg("SIGNAL %s" % signal) @@ -1242,7 +1284,7 @@ class Controller(BaseController): * :class:`stem.socket.InvalidRequest` if the addresses are malformed * :class:`stem.socket.OperationFailed` if Tor couldn't fulfill the request - :returns: dictionary with original -> replacement address mappings + :returns: **dict** with 'original -> replacement' address mappings """ mapaddress_arg = " ".join(["%s=%s" % (k, v) for (k, v) in mapping.items()]) @@ -1262,7 +1304,7 @@ def _case_insensitive_lookup(entries, key, default = UNDEFINED): :returns: case insensitive match or default if one was provided and key wasn't found - :raises: ValueError if no such value exists + :raises: **ValueError** if no such value exists """ if isinstance(entries, dict):

1 0

[stem/master] Linking image and clone command to gitweb
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit a78ea67a521197b8c57c8556df4250ec5161b6b0 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Oct 28 12:17:20 2012 -0700 Linking image and clone command to gitweb I disliked having a '(browse)' link for a couple reasons... 1. people might copy it as part of the clone command if they're new to git 2. it was pretty small considering its relevant importance Instead linking the clone command itself and the git image. --- docs/download.rst | 4 +++- 1 files changed, 3 insertions(+), 1 deletions(-) diff --git a/docs/download.rst b/docs/download.rst index ae3d8f0..6edf10e 100644 --- a/docs/download.rst +++ b/docs/download.rst @@ -6,12 +6,14 @@ Download :header-rows: 0 * - .. image:: /_static/section/git.png + :target: https://gitweb.torproject.org/ + - .. image:: /_static/label/git.png For those wanting to live on the bleeding edge or contribute to stem, its git repository can be fetched with... - **git clone git://git.torproject.org/stem.git** (`browse <https://gitweb.torproject.org/stem.git>`_) + `git clone git://git.torproject.org/stem.git <https://gitweb.torproject.org/stem.git>`_ * - .. image:: /_static/section/debian.png - .. image:: /_static/label/debian.png

1 0

[stem/master] Revised API docs for stem.response
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit ebb3de86c9af92001845f3560f857615e1f633eb Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Oct 27 19:32:43 2012 -0700 Revised API docs for stem.response This is a little different from the other modules in that we're including stem.response.__init__ as an automodule then autoclasses for all of the contents. The response classes each have precious little documentation to having them each on their own page would be pointless. Also moving the AuthMethod enum to the connection so we can drop the protocolinfo module documentation (it wouldn't be included since we're using autoclass). --- docs/api.rst | 1 + docs/api/response.rst | 14 ++++++ docs/contents.rst | 1 + stem/connection.py | 26 ++++++++++- stem/response/__init__.py | 99 ++++++++++++++++++++++------------------- stem/response/getconf.py | 3 +- stem/response/protocolinfo.py | 30 +------------ 7 files changed, 97 insertions(+), 77 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index c138240..e149c81 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -10,6 +10,7 @@ Controller * `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. * `stem.process <api/process.html>`_ - Launcher for the Tor process. + * `stem.response <api/response.html>`_ - Messages that Tor may provide the controller. * **Types** diff --git a/docs/api/response.rst b/docs/api/response.rst new file mode 100644 index 0000000..bf3b722 --- /dev/null +++ b/docs/api/response.rst @@ -0,0 +1,14 @@ +Controller Responses +==================== + +.. automodule:: stem.response + +Responses +--------- + +.. autoclass:: stem.response.authchallenge.AuthChallengeResponse +.. autoclass:: stem.response.getconf.GetConfResponse +.. autoclass:: stem.response.getinfo.GetInfoResponse +.. autoclass:: stem.response.mapaddress.MapAddressResponse +.. autoclass:: stem.response.protocolinfo.ProtocolInfoResponse + diff --git a/docs/contents.rst b/docs/contents.rst index 03274a4..6b0311c 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -12,6 +12,7 @@ Contents api/connection api/socket api/process + api/response api/exit_policy api/version diff --git a/stem/connection.py b/stem/connection.py index 730ad27..edad9d8 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -42,6 +42,29 @@ fine-grained control over the authentication process. For instance... print "Unable to authenticate: %s" % exc sys.exit(1) +The AuthMethod enumeration includes methods by which a controller can +authenticate to the control port. Tor gives a list of all the authentication +methods it will accept in response to PROTOCOLINFO queries. + +**AuthMethod.NONE** + No authentication required + +**AuthMethod.PASSWORD** + See tor's HashedControlPassword option. Controllers must provide the password + used to generate the hash. + +**AuthMethod.COOKIE** + See tor's CookieAuthentication option. Controllers need to supply the + contents of the cookie file. + +**AuthMethod.SAFECOOKIE** + See tor's CookieAuthentication option. Controllers need to reply to a + hmac challenge using the contents of the cookie file. + +**AuthMethod.UNKNOWN** + Tor provided one or more authentication methods that we don't recognize. This + is probably from a new addition to the control protocol. + **Module Overview:** :: @@ -99,7 +122,8 @@ import stem.util.enum import stem.util.system import stem.util.connection import stem.util.log as log -from stem.response.protocolinfo import AuthMethod + +AuthMethod = stem.util.enum.Enum("NONE", "PASSWORD", "COOKIE", "SAFECOOKIE", "UNKNOWN") CLIENT_HASH_CONSTANT = "Tor safe cookie authentication controller-to-server hash" SERVER_HASH_CONSTANT = "Tor safe cookie authentication server-to-controller hash" diff --git a/stem/response/__init__.py b/stem/response/__init__.py index 4a05be2..5c9b889 100644 --- a/stem/response/__init__.py +++ b/stem/response/__init__.py @@ -54,9 +54,10 @@ CONTROL_ESCAPES = {r"\\": "\\", r"\"": "\"", r"\'": "'", def convert(response_type, message, **kwargs): """ - Converts a ControlMessage into a particular kind of tor response. This does - an in-place conversion of the message from being a ControlMessage to a - subclass for its response type. Recognized types include... + Converts a :class:`~stem.response.ControlMessage` into a particular kind of + tor response. This does an in-place conversion of the message from being a + :class:`~stem.response.ControlMessage` to a subclass for its response type. + Recognized types include... * **\*** GETINFO * **\*** GETCONF @@ -65,19 +66,23 @@ def convert(response_type, message, **kwargs): * AUTHCHALLENGE * SINGLELINE - **\*** can raise a :class:`stem.socket.InvalidArguments` exception - **^** can raise a :class:`stem.socket.InvalidRequest` exception - **&** can raise a :class:`stem.socket.OperationFailed` exception + * **\*** can raise a :class:`stem.socket.InvalidArguments` exception + * **^** can raise a :class:`stem.socket.InvalidRequest` exception + * **&** can raise a :class:`stem.socket.OperationFailed` exception :param str response_type: type of tor response to convert to :param stem.response.ControlMessage message: message to be converted :param kwargs: optional keyword arguments to be passed to the parser method :raises: - * :class:`stem.socket.ProtocolError` the message isn't a proper response of that type - * :class:`stem.socket.InvalidArguments` the arguments given as input are invalid - * :class:`stem.socket.InvalidRequest` the arguments given as input are invalid - * TypeError if argument isn't a :class:`stem.response.ControlMessage` or response_type isn't supported + * :class:`stem.socket.ProtocolError` the message isn't a proper response of + that type + * :class:`stem.socket.InvalidArguments` the arguments given as input are + invalid + * :class:`stem.socket.InvalidRequest` the arguments given as input are + invalid + * **TypeError** if argument isn't a :class:`~stem.response.ControlMessage` + or response_type isn't supported """ import stem.response.getinfo @@ -124,7 +129,7 @@ class ControlMessage(object): """ Checks if any of our lines have a 250 response. - :returns: True if any lines have a 250 response code, False otherwise + :returns: **True** if any lines have a 250 response code, **False** otherwise """ for code, _, _ in self._parsed_content: @@ -154,7 +159,7 @@ class ControlMessage(object): For data entries the content is the full multi-line payload with newline linebreaks and leading periods unescaped. - :returns: list of (str, str, str) tuples for the components of this message + :returns: **list** of (str, str, str) tuples for the components of this message """ return list(self._parsed_content) @@ -163,7 +168,7 @@ class ControlMessage(object): """ Provides the unparsed content read from the control socket. - :returns: string of the socket data used to generate this message + :returns: **str** of the socket data used to generate this message """ return self._raw_content @@ -178,8 +183,8 @@ class ControlMessage(object): def __iter__(self): """ - Provides ControlLine instances for the content of the message. This is - stripped of status codes and dividers, for instance... + Provides :class:`~stem.response.ControlLine` instances for the content of + the message. This is stripped of status codes and dividers, for instance... :: @@ -204,14 +209,14 @@ class ControlMessage(object): def __len__(self): """ - :returns: Number of ControlLines + :returns: number of ControlLines """ return len(self._parsed_content) def __getitem__(self, index): """ - :returns: ControlLine at index + :returns: :class:`~stem.response.ControlLine` at the index """ return ControlLine(self._parsed_content[index][2]) @@ -238,7 +243,7 @@ class ControlLine(str): Provides our unparsed content. This is an empty string after we've popped all entries. - :returns: str of the unparsed content + :returns: **str** of the unparsed content """ return self._remainder @@ -247,7 +252,7 @@ class ControlLine(str): """ Checks if we have further content to pop or not. - :returns: True if we have additional content, False otherwise + :returns: **True** if we have additional content, **False** otherwise """ return self._remainder == "" @@ -256,9 +261,9 @@ class ControlLine(str): """ Checks if our next entry is a quoted value or not. - :param bool escaped: unescapes the ``CONTROL_ESCAPES`` escape sequences + :param bool escaped: unescapes the CONTROL_ESCAPES escape sequences - :returns: True if the next entry can be parsed as a quoted value, False otherwise + :returns: **True** if the next entry can be parsed as a quoted value, **False** otherwise """ start_quote, end_quote = _get_quote_indeces(self._remainder, escaped) @@ -268,11 +273,12 @@ class ControlLine(str): """ Checks if our next entry is a KEY=VALUE mapping or not. - :param str key: checks that the key matches this value, skipping the check if ``None`` + :param str key: checks that the key matches this value, skipping the check if **None** :param bool quoted: checks that the mapping is to a quoted value - :param bool escaped: unescapes the ``CONTROL_ESCAPES`` escape sequences + :param bool escaped: unescapes the CONTROL_ESCAPES escape sequences - :returns: True if the next entry can be parsed as a key=value mapping, False otherwise + :returns: **True** if the next entry can be parsed as a key=value mapping, + **False** otherwise """ remainder = self._remainder # temp copy to avoid locking @@ -293,10 +299,10 @@ class ControlLine(str): def peek_key(self): """ - Provides the key of the next entry, providing None if it isn't a key/value - mapping. + Provides the key of the next entry, providing **None** if it isn't a + key/value mapping. - :returns: str with the next entry's key + :returns: **str** with the next entry's key """ remainder = self._remainder @@ -327,13 +333,13 @@ class ControlLine(str): "this has a \\" and \\\\ in it" :param bool quoted: parses the next entry as a quoted value, removing the quotes - :param bool escaped: unescapes the ``CONTROL_ESCAPES`` escape sequences + :param bool escaped: unescapes the CONTROL_ESCAPES escape sequences - :returns: str of the next space separated entry + :returns: **str** of the next space separated entry :raises: - * ValueError if quoted is True without the value being quoted - * IndexError if we don't have any remaining content left to parse + * **ValueError** if quoted is True without the value being quoted + * **IndexError** if we don't have any remaining content left to parse """ with self._remainder_lock: @@ -347,12 +353,13 @@ class ControlLine(str): and the space from our remaining content. :param bool quoted: parses the value as being quoted, removing the quotes - :param bool escaped: unescapes the ``CONTROL_ESCAPES`` escape sequences + :param bool escaped: unescapes the CONTROL_ESCAPES escape sequences - :returns: tuple of the form (key, value) + :returns: **tuple** of the form (key, value) - :raises: ValueError if this isn't a KEY=VALUE mapping or if quoted is True without the value being quoted - :raises: IndexError if there's nothing to parse from the line + :raises: **ValueError** if this isn't a KEY=VALUE mapping or if quoted is + **True** without the value being quoted + :raises: **IndexError** if there's nothing to parse from the line """ with self._remainder_lock: @@ -376,13 +383,13 @@ def _parse_entry(line, quoted, escaped): :param str line: content to be parsed :param bool quoted: parses the next entry as a quoted value, removing the quotes - :param bool escaped: unescapes the ``CONTROL_ESCAPES`` escape sequences + :param bool escaped: unescapes the CONTROL_ESCAPES escape sequences - :returns: tuple of the form (entry, remainder) + :returns: **tuple** of the form (entry, remainder) :raises: - * ValueError if quoted is True without the next value being quoted - * IndexError if there's nothing to parse from the line + * **ValueError** if quoted is True without the next value being quoted + * **IndexError** if there's nothing to parse from the line """ if line == "": @@ -414,9 +421,9 @@ def _get_quote_indeces(line, escaped): Provides the indices of the next two quotes in the given content. :param str line: content to be parsed - :param bool escaped: unescapes the ``CONTROL_ESCAPES`` escape sequences + :param bool escaped: unescapes the CONTROL_ESCAPES escape sequences - :returns: tuple of two ints, indices being -1 if a quote doesn't exist + :returns: **tuple** of two ints, indices being -1 if a quote doesn't exist """ indices, quote_index = [], -1 @@ -446,14 +453,14 @@ class SingleLineResponse(ControlMessage): def is_ok(self, strict = False): """ - Checks if the response code is "250". If strict is True, checks if the - response is "250 OK" + Checks if the response code is "250". If strict is **True** then this + checks if the response is "250 OK" - :param bool strict: checks for a "250 OK" message if True + :param bool strict: checks for a "250 OK" message if **True** :returns: - * If strict is False: True if the response code is "250", False otherwise - * If strict is True: True if the response is "250 OK", False otherwise + * If strict is **False**: **True** if the response code is "250", **False** otherwise + * If strict is **True**: **True** if the response is "250 OK", **False** otherwise """ if strict: diff --git a/stem/response/getconf.py b/stem/response/getconf.py index 627e7bc..72bfc34 100644 --- a/stem/response/getconf.py +++ b/stem/response/getconf.py @@ -8,7 +8,8 @@ class GetConfResponse(stem.response.ControlMessage): Note that configuration parameters won't match what we queried for if it's one of the special mapping options (ex. "HiddenServiceOptions"). - :var dict entries: mapping between the config parameter (str) and their values (list of str) + :var dict entries: mapping between the config parameter (**str**) and their + values (**list** of **str**) """ def _parse_message(self): diff --git a/stem/response/protocolinfo.py b/stem/response/protocolinfo.py index eccad88..258c5b6 100644 --- a/stem/response/protocolinfo.py +++ b/stem/response/protocolinfo.py @@ -1,37 +1,9 @@ -""" -Parses replies to a tor PROTOCOLINFO queries. - -The AuthMethod enumeration includes methods by which a controller can -authenticate to the control port. Tor gives a list of all the authentication -methods it will accept in response to PROTOCOLINFO queries. - -**AuthMethod.NONE** - No authentication required - -**AuthMethod.PASSWORD** - See tor's HashedControlPassword option. Controllers must provide the password - used to generate the hash. - -**AuthMethod.COOKIE** - See tor's CookieAuthentication option. Controllers need to supply the - contents of the cookie file. - -**AuthMethod.SAFECOOKIE** - See tor's CookieAuthentication option. Controllers need to reply to a - hmac challenge using the contents of the cookie file. - -**AuthMethod.UNKNOWN** - Tor provided one or more authentication methods that we don't recognize. This - is probably from a new addition to the control protocol. -""" - import stem.socket import stem.response import stem.version -import stem.util.enum import stem.util.log as log -AuthMethod = stem.util.enum.Enum("NONE", "PASSWORD", "COOKIE", "SAFECOOKIE", "UNKNOWN") +from stem.connection import AuthMethod class ProtocolInfoResponse(stem.response.ControlMessage): """

1 0

[stem/master] Moving AuthMethod docs to the module overview
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 1e1d84143b26212d3158f30555145687d3c653d3 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Oct 28 12:31:04 2012 -0700 Moving AuthMethod docs to the module overview We were using definition entries for the AuthMethod enums which was nice, but gave them more emphasis than they deserved. Users won't usually touch a PROTOCOLINFO response directly so the enumeration really isn't that important. --- stem/connection.py | 88 +++++++++++++++++++++------------------------------ 1 files changed, 36 insertions(+), 52 deletions(-) diff --git a/stem/connection.py b/stem/connection.py index edad9d8..fa41c67 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -42,70 +42,54 @@ fine-grained control over the authentication process. For instance... print "Unable to authenticate: %s" % exc sys.exit(1) -The AuthMethod enumeration includes methods by which a controller can -authenticate to the control port. Tor gives a list of all the authentication -methods it will accept in response to PROTOCOLINFO queries. - -**AuthMethod.NONE** - No authentication required - -**AuthMethod.PASSWORD** - See tor's HashedControlPassword option. Controllers must provide the password - used to generate the hash. - -**AuthMethod.COOKIE** - See tor's CookieAuthentication option. Controllers need to supply the - contents of the cookie file. - -**AuthMethod.SAFECOOKIE** - See tor's CookieAuthentication option. Controllers need to reply to a - hmac challenge using the contents of the cookie file. - -**AuthMethod.UNKNOWN** - Tor provided one or more authentication methods that we don't recognize. This - is probably from a new addition to the control protocol. - **Module Overview:** :: - connect_port - Convenience method to get an authenticated control connection. - connect_socket_file - Similar to connect_port, but for control socket files. + connect_port - Convenience method to get an authenticated control connection + connect_socket_file - Similar to connect_port, but for control socket files - authenticate - Main method for authenticating to a control socket. - authenticate_none - Authenticates to an open control socket. - authenticate_password - Authenticates to a socket supporting password auth. - authenticate_cookie - Authenticates to a socket supporting cookie auth. - authenticate_safecookie - Authenticates to a socket supporting safecookie auth. + authenticate - Main method for authenticating to a control socket + authenticate_none - Authenticates to an open control socket + authenticate_password - Authenticates to a socket supporting password auth + authenticate_cookie - Authenticates to a socket supporting cookie auth + authenticate_safecookie - Authenticates to a socket supporting safecookie auth - get_protocolinfo - Issues a PROTOCOLINFO query. + get_protocolinfo - Issues a PROTOCOLINFO query - AuthenticationFailure - Base exception raised for authentication failures. - |- UnrecognizedAuthMethods - Authentication methods are unsupported. - |- IncorrectSocketType - Socket does not speak the tor control protocol. + AuthenticationFailure - Base exception raised for authentication failures + |- UnrecognizedAuthMethods - Authentication methods are unsupported + |- IncorrectSocketType - Socket does not speak the tor control protocol | - |- OpenAuthFailed - Failure when authenticating by an open socket. - | +- OpenAuthRejected - Tor rejected this method of authentication. + |- OpenAuthFailed - Failure when authenticating by an open socket + | +- OpenAuthRejected - Tor rejected this method of authentication | - |- PasswordAuthFailed - Failure when authenticating by a password. - | |- PasswordAuthRejected - Tor rejected this method of authentication. - | |- IncorrectPassword - Password was rejected. - | +- MissingPassword - Socket supports password auth but wasn't attempted. + |- PasswordAuthFailed - Failure when authenticating by a password + | |- PasswordAuthRejected - Tor rejected this method of authentication + | |- IncorrectPassword - Password was rejected + | +- MissingPassword - Socket supports password auth but wasn't attempted | - |- CookieAuthFailed - Failure when authenticating by a cookie. - | |- CookieAuthRejected - Tor rejected this method of authentication. - | |- IncorrectCookieValue - Authentication cookie was rejected. - | |- IncorrectCookieSize - Size of the cookie file is incorrect. - | |- UnreadableCookieFile - Unable to read the contents of the auth cookie. - | +- AuthChallengeFailed - Failure completing the authchallenge request. - | |- AuthChallengeUnsupported - Tor doesn't recognize the AUTHCHALLENGE command. - | |- AuthSecurityFailure - Server provided the wrong nonce credentials. - | |- InvalidClientNonce - The client nonce is invalid. + |- CookieAuthFailed - Failure when authenticating by a cookie + | |- CookieAuthRejected - Tor rejected this method of authentication + | |- IncorrectCookieValue - Authentication cookie was rejected + | |- IncorrectCookieSize - Size of the cookie file is incorrect + | |- UnreadableCookieFile - Unable to read the contents of the auth cookie + | +- AuthChallengeFailed - Failure completing the authchallenge request + | |- AuthChallengeUnsupported - Tor doesn't recognize the AUTHCHALLENGE command + | |- AuthSecurityFailure - Server provided the wrong nonce credentials + | |- InvalidClientNonce - The client nonce is invalid | +- UnrecognizedAuthChallengeMethod - AUTHCHALLENGE does not support the given methods. | - +- MissingAuthInfo - Unexpected PROTOCOLINFO response, missing auth info. - |- NoAuthMethods - Missing any methods for authenticating. - +- NoAuthCookie - Supports cookie auth but doesn't have its path. + +- MissingAuthInfo - Unexpected PROTOCOLINFO response, missing auth info + |- NoAuthMethods - Missing any methods for authenticating + +- NoAuthCookie - Supports cookie auth but doesn't have its path + + AuthMethod - Enumeration on PROTOCOLINFO responses for supported authentication methods + |- NONE - No authentication required + |- PASSWORD - Password required, see tor's HashedControlPassword option + |- COOKIE - Contents of the cookie file required, see tor's CookieAuthentication option + |- SAFECOOKIE - Need to reply to a hmac challenge using the contents of the cookie file + +- UNKNOWN - Tor provided one or more authentication methods that we don't recognize, probably something new """ from __future__ import with_statement

1 0

[stem/master] Making the logging NullHandler private
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit f31b19b966bc2f1243f58eebf8a1db0ce2876ff0 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Oct 28 13:49:17 2012 -0700 Making the logging NullHandler private We have a null logging handler to avoid having the logging module give a warning about no handlers being present. There's no reason for stem's users to care about it so making it private. --- stem/util/log.py | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-) diff --git a/stem/util/log.py b/stem/util/log.py index fbb8fdc..62b2bbc 100644 --- a/stem/util/log.py +++ b/stem/util/log.py @@ -69,11 +69,11 @@ DEDUPLICATION_MESSAGE_IDS = set() # could be found for logger "stem"' warning as per... # http://docs.python.org/release/3.1.3/library/logging.html#configuring-loggi… -class NullHandler(logging.Handler): +class _NullHandler(logging.Handler): def emit(self, record): pass if not LOGGER.handlers: - LOGGER.addHandler(NullHandler()) + LOGGER.addHandler(_NullHandler()) def get_logger(): """

1 0

[stem/master] Revised API documentation
by atagar＠torproject.org 28 Oct '12

28 Oct '12

1 0

[stem/master] Spelling corrections
by atagar＠torproject.org 28 Oct '12

28 Oct '12

commit 07c75fa254926b2e14ef91d8edc9e8e20170ce81 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Oct 28 13:48:04 2012 -0700 Spelling corrections Spell checked all of the stem/* files and the test utilites. Quite a few mistakes... --- docs/api.rst | 2 +- stem/control.py | 44 +++++++++++++++--------------- stem/descriptor/__init__.py | 8 +++--- stem/descriptor/export.py | 2 +- stem/descriptor/extrainfo_descriptor.py | 6 ++-- stem/descriptor/networkstatus.py | 8 +++--- stem/descriptor/reader.py | 2 +- stem/descriptor/router_status_entry.py | 10 +++--- stem/descriptor/server_descriptor.py | 10 +++--- stem/exit_policy.py | 24 ++++++++-------- stem/prereq.py | 4 +- stem/response/__init__.py | 2 +- stem/response/getinfo.py | 2 +- stem/socket.py | 4 +- stem/util/conf.py | 4 +- stem/util/connection.py | 6 ++-- stem/util/log.py | 6 ++-- stem/util/proc.py | 2 +- stem/util/system.py | 4 +- stem/version.py | 10 +++--- test/check_whitespace.py | 2 +- test/mocking.py | 14 +++++----- test/output.py | 4 +- test/prompt.py | 2 +- test/runner.py | 12 ++++---- 25 files changed, 97 insertions(+), 97 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index e149c81..938a10b 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -15,7 +15,7 @@ Controller * **Types** * `stem.exit_policy <api/exit_policy.html>`_ - Relay policy for the destinations it will or won't allow traffic to. - * `stem.version <api/version.html>`_ - Tor versions that can be compared to determine Tor's capablilites. + * `stem.version <api/version.html>`_ - Tor versions that can be compared to determine Tor's capabilities. Descriptors ----------- diff --git a/stem/control.py b/stem/control.py index b87048d..af5c8ee 100644 --- a/stem/control.py +++ b/stem/control.py @@ -182,8 +182,8 @@ class BaseController(object): # message. # # - This is a leftover response for a msg() call. We can't tell who an - # exception was airmarked for, so we only know that this was the case - # if it's a ControlMessage. This should not be possable and indicates + # exception was earmarked for, so we only know that this was the case + # if it's a ControlMessage. This should not be possible and indicates # a stem bug. This deserves a NOTICE level log message since it # indicates that one of our callers didn't get their reply. @@ -227,7 +227,7 @@ class BaseController(object): def is_alive(self): """ - Checks if our socket is currently connected. This is a passthrough for our + Checks if our socket is currently connected. This is a pass-through for our socket's :func:`~stem.socket.ControlSocket.is_alive` method. :returns: **bool** that's **True** if we're shut down and **False** otherwise @@ -237,7 +237,7 @@ class BaseController(object): def connect(self): """ - Reconnects our control socket. This is a passthrough for our socket's + Reconnects our control socket. This is a pass-through for our socket's :func:`~stem.socket.ControlSocket.connect` method. :raises: :class:`stem.socket.SocketError` if unable to make a socket @@ -247,7 +247,7 @@ class BaseController(object): def close(self): """ - Closes our socket connection. This is a passthrough for our socket's + Closes our socket connection. This is a pass-through for our socket's :func:`~stem.socket.ControlSocket.close` method. """ @@ -274,14 +274,14 @@ class BaseController(object): 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. + the change occurred. 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 **False** then the notice is under our locks, within the thread where - the change occured. In general this isn't advised, especially if your + the change occurred. In general this isn't advised, especially if your callback could block for a while. :param function callback: function to be notified when our state changes @@ -298,7 +298,7 @@ class BaseController(object): :param function callback: function to be removed from our listeners - :returns: **bool** that's **True** if we removed one or more occurances of + :returns: **bool** that's **True** if we removed one or more occurrences of the callback, **False** otherwise """ @@ -353,19 +353,19 @@ class BaseController(object): def _notify_status_listeners(self, state, expect_alive = None): """ - Informs our status listeners that a state change occured. + Informs our status listeners that a state change occurred. 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 + true when multiple events occur 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.CLOSE** if it causes tor to crash). However, there's no guarantee + of the order in which they occur, 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 :func:`~stem.control.BaseController.is_alive` state. - :param stem.socket.State state: state change that has occured + :param stem.socket.State state: state change that has occurred :param bool expect_alive: discard event if it conflicts with our :func:`~stem.control.BaseController.is_alive` state """ @@ -373,7 +373,7 @@ class BaseController(object): # Any changes to our is_alive() state happen under the send lock, so we # need to have it to ensure it doesn't change beneath us. - # TODO: when we drop python 2.5 compatability we can simplify this + # TODO: when we drop python 2.5 compatibility we can simplify this with self._socket._get_send_lock(): with self._status_listeners_lock: change_timestamp = time.time() @@ -398,8 +398,8 @@ class BaseController(object): them if we're restarted. """ - # In theory concurrent calls could result in multple start() calls on a - # single thread, which would cause an unexpeceted exception. Best be safe. + # In theory concurrent calls could result in multiple start() calls on a + # single thread, which would cause an unexpected exception. Best be safe. with self._socket._get_send_lock(): if not self._reader_thread or not self._reader_thread.isAlive(): @@ -507,7 +507,7 @@ class Controller(BaseController): self._is_caching_enabled = enable_caching self._request_cache = {} - # number of sequental 'GETINFO ip-to-country/*' lookups that have failed + # number of sequential 'GETINFO ip-to-country/*' lookups that have failed self._geoip_failure_count = 0 self.enabled_features = [] @@ -621,7 +621,7 @@ class Controller(BaseController): if key in CACHEABLE_GETINFO_PARAMS: self._request_cache["getinfo.%s" % key] = value elif key.startswith('ip-to-country/'): - # both cacheable and means that we should reset the geoip failure count + # both cache-able and means that we should reset the geoip failure count self._request_cache["getinfo.%s" % key] = value self._geoip_failure_count = -1 @@ -635,7 +635,7 @@ class Controller(BaseController): # bump geoip failure count if... # * we're caching results # * this was soley a geoip lookup - # * we've never had a successful geoip lookup (faiure count isn't -1) + # * we've never had a successful geoip lookup (failure count isn't -1) is_geoip_request = len(params) == 1 and list(params)[0].startswith('ip-to-country/') @@ -707,7 +707,7 @@ class Controller(BaseController): """ # TODO: We should iterate over the descriptors as they're read from the - # socket rather than reading the whole thing into memeory. + # socket rather than reading the whole thing into memory. desc_content = self.get_info("desc/all-recent") @@ -770,7 +770,7 @@ class Controller(BaseController): def authenticate(self, *args, **kwargs): """ A convenience method to authenticate the controller. This is just a - passthrough to :func:`stem.connection.authenticate`. + pass-through to :func:`stem.connection.authenticate`. """ import stem.connection @@ -1002,7 +1002,7 @@ class Controller(BaseController): }) The params can optionally be a list a key/value tuples, though the only - reason this type of arguement would be useful is for hidden service + reason this type of argument would be useful is for hidden service configuration (those options are order dependent). :param dict,list params: mapping of configuration options to the values diff --git a/stem/descriptor/__init__.py b/stem/descriptor/__init__.py index edf4009..ff3d59f 100644 --- a/stem/descriptor/__init__.py +++ b/stem/descriptor/__init__.py @@ -74,7 +74,7 @@ def parse_file(path, descriptor_file): # by an annotation on their first line... # https://trac.torproject.org/5651 - # Cached descriptor handling. These contain mulitple descriptors per file. + # Cached descriptor handling. These contain multiple descriptors per file. filename, file_parser = os.path.basename(path), None @@ -268,7 +268,7 @@ def _get_descriptor_components(raw_contents, validate, extra_keywords = ()): followed by an optional value. Lines can also be followed by a signature block. - To get a sublisting with just certain keywords use extra_keywords. This can + To get a sub-listing with just certain keywords use extra_keywords. This can be useful if we care about their relative ordering with respect to each other. For instance, we care about the ordering of 'accept' and 'reject' entries because this influences the resulting exit policy, but for everything @@ -293,7 +293,7 @@ def _get_descriptor_components(raw_contents, validate, extra_keywords = ()): while remaining_lines: line = remaining_lines.pop(0) - # V2 network status documents explicitely can contain blank lines... + # V2 network status documents explicitly can contain blank lines... # # "Implementations MAY insert blank lines for clarity between sections; # these blank lines are ignored." @@ -303,7 +303,7 @@ def _get_descriptor_components(raw_contents, validate, extra_keywords = ()): if not line: continue - # Some lines have an 'opt ' for backward compatability. They should be + # Some lines have an 'opt ' for backward compatibility. They should be # ignored. This prefix is being removed in... # https://trac.torproject.org/projects/tor/ticket/5124 diff --git a/stem/descriptor/export.py b/stem/descriptor/export.py index 3b71455..9785421 100644 --- a/stem/descriptor/export.py +++ b/stem/descriptor/export.py @@ -21,7 +21,7 @@ def export_csv(descriptors, included_fields = (), excluded_fields = (), header = """ Provides a newline separated CSV for one or more descriptors. If simply provided with descriptors then the CSV contains all of its attributes, - labelled with a header row. Either 'included_fields' or 'excluded_fields' can + labeled with a header row. Either 'included_fields' or 'excluded_fields' can be used for more granular control over its attributes and the order. :param Descriptor,list descriptors: either a diff --git a/stem/descriptor/extrainfo_descriptor.py b/stem/descriptor/extrainfo_descriptor.py index 026b59b..2bf76e3 100644 --- a/stem/descriptor/extrainfo_descriptor.py +++ b/stem/descriptor/extrainfo_descriptor.py @@ -34,7 +34,7 @@ Extra-info descriptors are available from a few sources... DirStats - known stats for ExtraInfoDescriptor's dir_*_direct_dl and dir_*_tunneled_dl |- COMPLETE - requests that completed successfully |- TIMEOUT - requests that didn't complete within a ten minute timeout - |- RUNNING - requests still in procress when measurement's taken + |- RUNNING - requests still in process when measurement's taken |- MIN - smallest rate at which a descriptor was downloaded in B/s |- MAX - largest rate at which a descriptor was downloaded in B/s |- D1-4 and D6-9 - rate of the slowest x/10 download rates in B/s @@ -184,7 +184,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): :var datetime published: **\*** time in GMT when this descriptor was made :var str geoip_db_digest: sha1 of geoIP database file :var dict transport: **\*** mapping of transport methods to their (address, - port, args) tuple, these usually appeear on bridges in which case all of + port, args) tuple, these usually appear on bridges in which case all of those are **None** **Bi-directional connection usage:** @@ -399,7 +399,7 @@ class ExtraInfoDescriptor(stem.descriptor.Descriptor): :param dict entries: descriptor contents to be applied :param bool validate: checks the validity of descriptor content if True - :raises: **ValueError** if an error occures in validation + :raises: **ValueError** if an error occurs in validation """ for keyword, values in entries.items(): diff --git a/stem/descriptor/networkstatus.py b/stem/descriptor/networkstatus.py index a3eed1f..893129b 100644 --- a/stem/descriptor/networkstatus.py +++ b/stem/descriptor/networkstatus.py @@ -168,7 +168,7 @@ BANDWIDTH_WEIGHT_ENTRIES = ( def parse_file(document_file, validate = True, is_microdescriptor = False, document_version = 3): """ Parses a network status and iterates over the RouterStatusEntry in it. The - document that these instances reference have an empty 'rotuers' attribute to + document that these instances reference have an empty 'routers' attribute to allow for limited memory usage. :param file document_file: file with network status document content @@ -366,7 +366,7 @@ class NetworkStatusDocumentV2(NetworkStatusDocument): self.published = datetime.datetime.strptime(value, "%Y-%m-%d %H:%M:%S") except ValueError: if validate: - raise ValueError("Versino 2 network status document's 'published' time wasn't parseable: %s" % value) + raise ValueError("Version 2 network status document's 'published' time wasn't parseable: %s" % value) elif keyword == "dir-options": self.options = value.split() elif keyword == "directory-signature": @@ -727,7 +727,7 @@ class _DocumentFooter(object): content = document_file.read() if validate and content and not header.meets_consensus_method(9): - raise ValueError("Network status document's footer should only apepar in consensus-method 9 or later") + raise ValueError("Network status document's footer should only appear in consensus-method 9 or later") elif not content and not header.meets_consensus_method(9): return # footer is optional and there's nothing to parse @@ -798,7 +798,7 @@ def _check_for_missing_and_disallowed_fields(header, entries, fields): :param list fields: expected field attributes (either **HEADER_STATUS_DOCUMENT_FIELDS** or **FOOTER_STATUS_DOCUMENT_FIELDS**) - :raises: **ValueError** if we're missing mandatory fields or have fiels we shouldn't + :raises: **ValueError** if we're missing mandatory fields or have fields we shouldn't """ missing_fields, disallowed_fields = [], [] diff --git a/stem/descriptor/reader.py b/stem/descriptor/reader.py index de525d1..c03b996 100644 --- a/stem/descriptor/reader.py +++ b/stem/descriptor/reader.py @@ -134,7 +134,7 @@ class UnrecognizedType(FileSkipped): class ReadFailed(FileSkipped): """ - An IOError occured while trying to read the file. + An IOError occurred while trying to read the file. :param IOError exception: issue that arose when reading the file, **None** if this arose due to the file not being present diff --git a/stem/descriptor/router_status_entry.py b/stem/descriptor/router_status_entry.py index dfa26fe..321b7c0 100644 --- a/stem/descriptor/router_status_entry.py +++ b/stem/descriptor/router_status_entry.py @@ -249,14 +249,14 @@ class RouterStatusEntryV3(RouterStatusEntry): :var str digest: **\*** router's digest :var int bandwidth: bandwidth claimed by the relay (in kb/s) - :var int measured: bandwith measured to be available by the relay + :var int measured: bandwidth measured to be available by the relay :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting information that isn't yet recognized :var stem.exit_policy.MicrodescriptorExitPolicy exit_policy: router's exit policy :var list microdescriptor_hashes: tuples of two values, the list of consensus - methods for generting a set of digests and the 'algorithm => digest' mappings + methods for generating a set of digests and the 'algorithm => digest' mappings **\*** attribute is either required when we're parsed with validation or has a default value, others are left as **None** if undefined @@ -317,7 +317,7 @@ class RouterStatusEntryMicroV3(RouterStatusEntry): flavored network status document. :var int bandwidth: bandwidth claimed by the relay (in kb/s) - :var int measured: bandwith measured to be available by the relay + :var int measured: bandwidth measured to be available by the relay :var list unrecognized_bandwidth_entries: **\*** bandwidth weighting information that isn't yet recognized @@ -566,8 +566,8 @@ def _decode_fingerprint(identity, validate): raise ValueError("Unable to decode identity string '%s'" % identity) for char in identity_decoded: - # Individual characters are either standard ascii or hex encoded, and each - # represent two hex digits. For instnace... + # Individual characters are either standard ASCII or hex encoded, and each + # represent two hex digits. For instance... # # >>> ord('\n') # 10 diff --git a/stem/descriptor/server_descriptor.py b/stem/descriptor/server_descriptor.py index 80df7bc..f8cdb00 100644 --- a/stem/descriptor/server_descriptor.py +++ b/stem/descriptor/server_descriptor.py @@ -313,7 +313,7 @@ class ServerDescriptor(stem.descriptor.Descriptor): :param dict entries: descriptor contents to be applied :param bool validate: checks the validity of descriptor content if **True** - :raises: **ValueError** if an error occures in validation + :raises: **ValueError** if an error occurs in validation """ for keyword, values in entries.items(): @@ -381,7 +381,7 @@ class ServerDescriptor(stem.descriptor.Descriptor): # platform Tor 0.2.2.35 (git-73ff13ab3cc9570d) on Linux x86_64 # # There's no guarantee that we'll be able to pick these out the - # version, but might as well try to save our caller the effot. + # version, but might as well try to save our caller the effort. platform_match = re.match("^Tor (\S*).* on (.*)$", self.platform) @@ -411,7 +411,7 @@ class ServerDescriptor(stem.descriptor.Descriptor): raise ValueError("Fingerprint line should have groupings of four hex digits: %s" % value) if not stem.util.tor_tools.is_valid_fingerprint(fingerprint): - raise ValueError("Tor relay fingerprints consist of fourty hex digits: %s" % value) + raise ValueError("Tor relay fingerprints consist of forty hex digits: %s" % value) self.fingerprint = fingerprint elif keyword == "hibernating": @@ -439,7 +439,7 @@ class ServerDescriptor(stem.descriptor.Descriptor): else: self.hidden_service_dir = ["2"] elif keyword == "uptime": - # We need to be tolerant of negative uptimes to accomidate a past tor + # We need to be tolerant of negative uptimes to accommodate a past tor # bug... # # Changes in version 0.1.2.7-alpha - 2007-02-06 @@ -448,7 +448,7 @@ class ServerDescriptor(stem.descriptor.Descriptor): # buckets go absurdly negative. # # After parsing all of the attributes we'll double check that negative - # uptimes only occured prior to this fix. + # uptimes only occurred prior to this fix. try: self.uptime = int(value) diff --git a/stem/exit_policy.py b/stem/exit_policy.py index dc50c6e..f228786 100644 --- a/stem/exit_policy.py +++ b/stem/exit_policy.py @@ -1,6 +1,6 @@ """ Representation of tor exit policies. These can be easily used to check if -exiting to a destination is permissable or not. For instance... +exiting to a destination is permissible or not. For instance... :: @@ -63,7 +63,7 @@ AddressType = stem.util.enum.Enum(("WILDCARD", "Wildcard"), ("IPv4", "IPv4"), (" # That said, I'm not sure if this is entirely desirable since for most use # cases we *want* the caller to have an immutable ExitPolicy (since it # reflects something they... well, can't modify). However, I can think of -# some use cases where we might want to construct custom policies. Mabye make +# some use cases where we might want to construct custom policies. Maybe make # it a CustomExitPolicyRule subclass? class ExitPolicy(object): @@ -148,7 +148,7 @@ class ExitPolicy(object): """ Provides a short description of our policy chain, similar to a microdescriptor. This excludes entries that don't cover all IP - addresses, and is either whitelist or blacklist policy based on + addresses, and is either white-list or blacklist policy based on the final entry. For instance... :: @@ -165,7 +165,7 @@ class ExitPolicy(object): """ if self._summary_representation is None: - # determines if we're a whitelist or blacklist + # determines if we're a white-list or blacklist is_whitelist = not self._is_allowed_default for rule in self._rules: @@ -173,8 +173,8 @@ class ExitPolicy(object): is_whitelist = not rule.is_accept break - # Iterates over the policys and adds the the ports we'll return (ie, - # allows if a whitelist and rejects if a blacklist). Regardless of a + # Iterates over the policies and adds the the ports we'll return (ie, + # allows if a white-list and rejects if a blacklist). Regardless of a # port's allow/reject policy, all further entries with that port are # ignored since policies respect the first matching policy. @@ -187,7 +187,7 @@ class ExitPolicy(object): for port in xrange(rule.min_port, rule.max_port + 1): if port in skip_ports: continue - # if accept + whitelist or reject + blacklist then add + # if accept + white-list or reject + blacklist then add if rule.is_accept == is_whitelist: display_ports.append(port) @@ -244,7 +244,7 @@ class MicrodescriptorExitPolicy(ExitPolicy): :: accept 80,443 # only accepts common http ports - reject 1-1024 # only accepts non-privilaged ports + reject 1-1024 # only accepts non-privileged ports Since these policies are a subset of the exit policy information (lacking IP ranges) clients can only use them to guess if a relay will accept traffic or @@ -334,7 +334,7 @@ class ExitPolicyRule(object): <https://gitweb.torproject.org/torspec.git/blob/HEAD:/dir-spec.txt>`_ as an "exitpattern". Note that while these are similar to tor's man page entry for ExitPolicies, it's not the exact same. An exitpattern is better defined and - scricter in what it'll accept. For instance, ports are not optional and it + stricter in what it'll accept. For instance, ports are not optional and it does not contain the 'private' alias. This should be treated as an immutable object. @@ -435,7 +435,7 @@ class ExitPolicyRule(object): :raises: **ValueError** if provided with a malformed address or port """ - # validate our input and check if the argumement doens't match our address type + # validate our input and check if the argument doesn't match our address type if address != None: if stem.util.connection.is_valid_ip_address(address): if self.address_type == AddressType.IPv6: return False @@ -490,7 +490,7 @@ class ExitPolicyRule(object): label += "[%s]" % self.address # Including our mask label as follows... - # - exclde our mask if it doesn't do anything + # - exclude our mask if it doesn't do anything # - use our masked bit count if we can # - use the mask itself otherwise @@ -607,7 +607,7 @@ class ExitPolicyRule(object): # Our string representation encompasses our effective policy. Technically # this isn't quite right since our rule attribute may differ (ie, "accept # 0.0.0.0/0" == "accept 0.0.0.0/0.0.0.0" will be True), but these - # policies are effectively equivilant. + # policies are effectively equivalent. return str(self) == str(other) else: diff --git a/stem/prereq.py b/stem/prereq.py index e443078..3e899dd 100644 --- a/stem/prereq.py +++ b/stem/prereq.py @@ -8,7 +8,7 @@ series). Other requirements for complete functionality are... * rsa module - * validating descriptor signagure integrity + * validating descriptor signature integrity :: @@ -70,7 +70,7 @@ def is_rsa_available(): IS_RSA_AVAILABLE = False msg = "Unable to import the rsa module. Because of this we'll be unable to verify descriptor signature integrity." - log.log_once("stem.prereq.is_rsa_availabe", log.INFO, msg) + log.log_once("stem.prereq.is_rsa_available", log.INFO, msg) return IS_RSA_AVAILABLE diff --git a/stem/response/__init__.py b/stem/response/__init__.py index 5c9b889..bd73f85 100644 --- a/stem/response/__init__.py +++ b/stem/response/__init__.py @@ -471,7 +471,7 @@ class SingleLineResponse(ControlMessage): content = self.content() if len(content) > 1: - raise stem.socket.ProtocolError("Received multiline response") + raise stem.socket.ProtocolError("Received multi-line response") elif len(content) == 0: raise stem.socket.ProtocolError("Received empty response") else: diff --git a/stem/response/getinfo.py b/stem/response/getinfo.py index 24aeb84..ddedc34 100644 --- a/stem/response/getinfo.py +++ b/stem/response/getinfo.py @@ -47,7 +47,7 @@ class GetInfoResponse(stem.response.ControlMessage): if "\n" in value: if not value.startswith("\n"): - raise stem.socket.ProtocolError("GETINFO response contained a multiline value that didn't start with a newline:\n%s" % self) + raise stem.socket.ProtocolError("GETINFO response contained a multi-line value that didn't start with a newline:\n%s" % self) value = value[1:] diff --git a/stem/socket.py b/stem/socket.py index 58dc5e2..2b13466 100644 --- a/stem/socket.py +++ b/stem/socket.py @@ -174,7 +174,7 @@ class ControlSocket(object): self._socket_file = self._socket.makefile() self._is_alive = True - # It's possable for this to have a transient failure... + # It's possible for this to have a transient failure... # SocketError: [Errno 4] Interrupted system call # # It's safe to retry, so give it another try if it fails. @@ -359,7 +359,7 @@ class ControlSocketFile(ControlSocket): def send_message(control_file, message, raw = False): """ Sends a message to the control socket, adding the expected formatting for - single verses multiline messages. Neither message type should contain an + single verses multi-line messages. Neither message type should contain an ending newline (if so it'll be treated as a multi-line message with a blank line at the end). If the message doesn't contain a newline then it's sent as... diff --git a/stem/util/conf.py b/stem/util/conf.py index 7bf157a..9c15973 100644 --- a/stem/util/conf.py +++ b/stem/util/conf.py @@ -124,7 +124,7 @@ Alternatively you can get a read-only dictionary that stays in sync with the |- save - writes the current configuration to a file |- clear - empties our loaded configuration contents |- synchronize - replaces mappings in a dictionary with the config's values - |- add_listener - notifies the given listener when an update occures + |- add_listener - notifies the given listener when an update occurs |- clear_listeners - removes any attached listeners |- keys - provides keys in the loaded configuration |- set - sets the given key/value pair @@ -355,7 +355,7 @@ class Config(object): elif not self._path: raise ValueError("Unable to save configuration: no path provided") - # TODO: when we drop python 2.5 compatability we can simplify this + # TODO: when we drop python 2.5 compatibility we can simplify this with self._contents_lock: with open(self._path, 'w') as output_file: for entry_key in sorted(self.keys()): diff --git a/stem/util/connection.py b/stem/util/connection.py index 104ad5c..a5afc2b 100644 --- a/stem/util/connection.py +++ b/stem/util/connection.py @@ -91,7 +91,7 @@ def is_valid_port(entry, allow_zero = False): Checks if a string or int is a valid port number. :param list,str,int entry: string, integer or list to be checked - :param bool allow_zero: accept port number of zero (reserved by defintion) + :param bool allow_zero: accept port number of zero (reserved by definition) :returns: **True** if input is an integer and within the valid port range, **False** otherwise """ @@ -190,7 +190,7 @@ def get_masked_bits(mask): if not is_valid_ip_address(mask): raise ValueError("'%s' is an invalid subnet mask" % mask) - # converts octets to binary representatino + # converts octets to binary representation mask_bin = get_address_binary(mask) mask_match = re.match("^(1*)(0*)$", mask_bin) @@ -239,7 +239,7 @@ def get_address_binary(address): """ Provides the binary value for an IPv4 or IPv6 address. - :returns: **str** with the binary prepresentation of this address + :returns: **str** with the binary representation of this address :raises: **ValueError** if address is neither an IPv4 nor IPv6 address """ diff --git a/stem/util/log.py b/stem/util/log.py index b9dd988..fbb8fdc 100644 --- a/stem/util/log.py +++ b/stem/util/log.py @@ -2,8 +2,8 @@ Functions to aid library logging. Default logging is usually NOTICE and above, runlevels being used as follows... -* **ERROR** - critical issue occured, the user needs to be notified -* **WARN** - non-critical issue occured that the user should be aware of +* **ERROR** - critical issue occurred, the user needs to be notified +* **WARN** - non-critical issue occurred that the user should be aware of * **NOTICE** - information that is helpful to the user * **INFO** - high level library activity * **DEBUG** - low level library activity @@ -96,7 +96,7 @@ def logging_level(runlevel): def escape(message): """ - Escapes specific sequences for logging (newlines, tabs, carrage returns). + Escapes specific sequences for logging (newlines, tabs, carriage returns). :param str message: string to be escaped diff --git a/stem/util/proc.py b/stem/util/proc.py index 5315167..084caf2 100644 --- a/stem/util/proc.py +++ b/stem/util/proc.py @@ -124,7 +124,7 @@ def get_cwd(pid): :param int pid: process id of the process to be queried - :returns: **str** with the path of the workign direcctory for the process + :returns: **str** with the path of the working directory for the process :raises: **IOError** if it can't be determined """ diff --git a/stem/util/system.py b/stem/util/system.py index 6c2be06..85c8faf 100644 --- a/stem/util/system.py +++ b/stem/util/system.py @@ -10,7 +10,7 @@ best-effort, providing **None** if the lookup fails. is_windows - checks if we're running on windows is_mac - checks if we're running on a mac is_bsd - checks if we're running on the bsd family of operating systems - is_available - determines if a command is availabe on this system + is_available - determines if a command is available on this system is_running - determines if a given process is running get_pid_by_name - gets the pid for a process by the given name get_pid_by_port - gets the pid for a process listening to a given port @@ -511,7 +511,7 @@ def get_bsd_jail_id(pid): def expand_path(path, cwd = None): """ - Provides an absolute path, expanding tildas with the user's home and + Provides an absolute path, expanding tildes with the user's home and appending a current working directory if the path was relative. This is unix-specific and paths never have an ending slash. diff --git a/stem/version.py b/stem/version.py index 42ef062..8a792b3 100644 --- a/stem/version.py +++ b/stem/version.py @@ -135,7 +135,7 @@ class Version(object): be compared to either a :class:`~stem.version.Version` or :class:`~stem.version.VersionRequirements`. - :param requirements: requrirements to be checked for + :param requirements: requirements to be checked for """ if isinstance(requirements, Version): @@ -196,7 +196,7 @@ class VersionRequirements(object): """ Adds a constraint that we're greater than the given version. - :param stem.version.Version verison: version we're checking against + :param stem.version.Version version: version we're checking against :param bool inclusive: if comparison is inclusive or not """ @@ -209,7 +209,7 @@ class VersionRequirements(object): """ Adds a constraint that we're less than the given version. - :param stem.version.Version verison: version we're checking against + :param stem.version.Version version: version we're checking against :param bool inclusive: if comparison is inclusive or not """ @@ -222,8 +222,8 @@ class VersionRequirements(object): """ Adds constraint that we're within the range from one version to another. - :param stem.version.Version from_verison: beginning of the comparison range - :param stem.version.Version to_verison: end of the comparison range + :param stem.version.Version from_version: beginning of the comparison range + :param stem.version.Version to_version: end of the comparison range :param bool from_inclusive: if comparison is inclusive with the starting version :param bool to_inclusive: if comparison is inclusive with the ending version """ diff --git a/test/check_whitespace.py b/test/check_whitespace.py index d30f99a..314230f 100644 --- a/test/check_whitespace.py +++ b/test/check_whitespace.py @@ -8,7 +8,7 @@ which are... * no trailing whitespace unless the line is empty, in which case it should have the same indentation as the surrounding code -This also checks for 2.5 compatability issues (yea, they're not whitespace but +This also checks for 2.5 compatibility issues (yea, they're not whitespace but it's so much easier to do here...): * checks that anything using the 'with' keyword has... diff --git a/test/mocking.py b/test/mocking.py index 4cfe91a..66d3017 100644 --- a/test/mocking.py +++ b/test/mocking.py @@ -10,8 +10,8 @@ calling :func:`test.mocking.revert_mocking`. revert_mocking - reverts any changes made by the mock function get_real_function - provides the non-mocked version of a function get_all_combinations - provides all combinations of attributes - support_with - makes object be compatable for use via the 'with' keyword - get_object - get an abitrary mock object of any class + support_with - makes object be compatible for use via the 'with' keyword + get_object - get an arbitrary mock object of any class Mocking Functions no_op - does nothing @@ -252,8 +252,8 @@ def mock(target, mock_call, target_module=None): The target_module only needs to be set if the results of 'inspect.getmodule(target)' doesn't match the module that we want to mock - (for instance, the 'os' module provies the platform module that it wraps like - 'postix', which won't work). + (for instance, the 'os' module provides the platform module that it wraps + like 'postix', which won't work). :param function target: function to be mocked :param functor mock_call: mocking to replace the function with @@ -282,7 +282,7 @@ def mock(target, mock_call, target_module=None): def mock_method(target_class, method_name, mock_call): """ - Mocks the given class method in a similar fasion as what mock() does for + Mocks the given class method in a similar fashion as what mock() does for functions. :param class target_class: class with the method we want to mock @@ -426,10 +426,10 @@ def get_message(content, reformat = True): the following changes unless 'reformat' is false... * ensures the content ends with a newline - * newlines are replaced with a carrage return and newline pair + * newlines are replaced with a carriage return and newline pair :param str content: base content for the controller message - :param str reformat: modifies content to be more accomidateing to being parsed + :param str reformat: modifies content to be more accommodating to being parsed :returns: stem.socket.ControlMessage instance """ diff --git a/test/output.py b/test/output.py index 084a79a..001c6a5 100644 --- a/test/output.py +++ b/test/output.py @@ -71,7 +71,7 @@ def print_config(test_config): def apply_filters(testing_output, *filters): """ - Gets the tests results, possably processed through a series of filters. The + Gets the tests results, possibly processed through a series of filters. The filters are applied in order, each getting the output of the previous. A filter's input arguments should be the line's (type, content) and the @@ -115,7 +115,7 @@ def colorize(line_type, line_content): def strip_module(line_type, line_content): """ Removes the module name from testing output. This information tends to be - repetative, and redundant with the headers. + repetitive, and redundant with the headers. """ m = re.match(".*( $.*?$).*", line_content) diff --git a/test/prompt.py b/test/prompt.py index fad9d4e..91ad6d3 100644 --- a/test/prompt.py +++ b/test/prompt.py @@ -68,7 +68,7 @@ def is_running(): """ Checks if we're likely running a tor instance spawned by this module. This is simply a check if our custom control port is in use, so it can be confused by - other applications (not likely, but possable). + other applications (not likely, but possible). :returns: True if the control port is used, False otherwise """ diff --git a/test/runner.py b/test/runner.py index a372c42..acf346e 100644 --- a/test/runner.py +++ b/test/runner.py @@ -100,7 +100,7 @@ class RunnerStopped(Exception): "Raised when we try to use a Runner that doesn't have an active tor instance" class TorInaccessable(Exception): - "Raised when information is needed from tor but the instance we have is inaccessable" + "Raised when information is needed from tor but the instance we have is inaccessible" def skip(test_case, message): """ @@ -209,7 +209,7 @@ def get_runner(): class _MockChrootFile(object): """ Wrapper around a file object that strips given content from readline() - responses. This is used to simulate a chroot setup by removing the restign + responses. This is used to simulate a chroot setup by removing the prefix directory from the paths we report. """ @@ -335,7 +335,7 @@ class Runner(object): if self._test_dir and CONFIG["integ.test_directory"] == "": shutil.rmtree(self._test_dir, ignore_errors = True) - # reverts any mockin of stem.socket.recv_message + # reverts any mocking of stem.socket.recv_message if self._original_recv_message: stem.socket.recv_message = self._original_recv_message self._original_recv_message = None @@ -382,7 +382,7 @@ class Runner(object): a lot of adverse side effects (`ticket <https://trac.torproject.org/projects/tor/ticket/3313>`_). - :returns: True if debugger attachment is allowd, False otherwise + :returns: True if debugger attachment is allowed, False otherwise """ # If we're running a tor version where ptrace is disabled and we didn't @@ -407,7 +407,7 @@ class Runner(object): :param str resource: file within our test directory to provide the path for - :returns: str with our test direcectory's absolute path or that of a file within it + :returns: str with our test directory's absolute path or that of a file within it :raises: :class:`test.runner.RunnerStopped` if we aren't running """ @@ -596,7 +596,7 @@ class Runner(object): # Makes a directory for the control socket if needed. As of, at least, Tor # 0.2.3.10 it checks during startup that the directory a control socket - # resides in is only accessable by the tor user (and refuses to finish + # resides in is only accessible by the tor user (and refuses to finish # starting if it isn't). if Torrc.SOCKET in self._custom_opts:

1 0

r25854: {website} Notice on RPM updates break (website/trunk/docs/en)
by Ondrej Mikle 28 Oct '12

28 Oct '12

Author: hiviah Date: 2012-10-28 15:56:07 +0000 (Sun, 28 Oct 2012) New Revision: 25854 Modified: website/trunk/docs/en/rpms.wml Log: Notice on RPM updates break Modified: website/trunk/docs/en/rpms.wml =================================================================== --- website/trunk/docs/en/rpms.wml 2012-10-26 04:53:54 UTC (rev 25853) +++ website/trunk/docs/en/rpms.wml 2012-10-28 15:56:07 UTC (rev 25854) @@ -20,6 +20,13 @@ security fixes. + Notice: there will be a break in updates of RPM + repositories, expected until around 2012-12-20. Latest versions packaged are + 0.2.3.24-rc and 0.2.4.5-alpha. In the meantime, <a + href="<gitblob>doc/tor-rpm-creation.txt">building from source</a> will be + necessary. + + You'll need to set up our package repository before you can fetch Tor. Repositories contain i686 and x86_64 builds. Assuming yum, in

1 0