- tor-commits - lists.torproject.org

[stem/master] Missed linking a funcion
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit 438dc79a512879473499211988a86e08099720de Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jun 3 16:21:26 2012 -0700 Missed linking a funcion --- stem/process.py | 6 +++--- 1 files changed, 3 insertions(+), 3 deletions(-) diff --git a/stem/process.py b/stem/process.py index 0224e3e..5df04dc 100644 --- a/stem/process.py +++ b/stem/process.py @@ -111,9 +111,9 @@ 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 launch_tor(), but with a customized - configuration. This writes a temporary torrc to disk, launches tor, then - deletes the torrc. + 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 str tor_cmd: command for starting tor

1 0

[stem/master] Adding module metadata (author, version, etc)
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit 5c9579626a131e8bd17c283e0904525e30fe4488 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Jun 2 11:06:42 2012 -0700 Adding module metadata (author, version, etc) --- stem/__init__.py | 8 ++++++++ 1 files changed, 8 insertions(+), 0 deletions(-) diff --git a/stem/__init__.py b/stem/__init__.py index 30e4f81..152a7df 100644 --- a/stem/__init__.py +++ b/stem/__init__.py @@ -2,5 +2,13 @@ Library for working with the tor process. """ +__version__ = '0.0.1' +__author__ = 'Damian Johnson' +__contact__ = 'atagar(a)torproject.org' +__url__ = 'http://www.atagar.com/stem/' +__license__ = 'LGPLv3' + __all__ = ["descriptor", "response", "util", "connection", "control", "process", "socket", "version"] + +

1 0

[stem/master] Defaulting connect_* to provide a Controller
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit c03ebb23ae39f9c9b68a1471dbf3debb30c399a7 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jun 3 21:26:21 2012 -0700 Defaulting connect_* to provide a Controller As a TODO comment mentioned, the connect_* convenience functions were supposed to provide a higher level controller class when one was available. It now does. --- stem/connection.py | 7 +++---- 1 files changed, 3 insertions(+), 4 deletions(-) diff --git a/stem/connection.py b/stem/connection.py index 99bc623..3f971bf 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -72,13 +72,14 @@ import binascii import stem.response import stem.socket +import stem.control import stem.version import stem.util.enum import stem.util.system import stem.util.log as log from stem.response.protocolinfo import AuthMethod -def connect_port(control_addr = "127.0.0.1", control_port = 9051, password = None, chroot_path = None, controller = None): +def connect_port(control_addr = "127.0.0.1", control_port = 9051, password = None, chroot_path = None, controller = stem.control.Controller): """ Convenience function for quickly getting a control connection. This is very handy for debugging or CLI setup, handling setup and prompting for a password @@ -94,8 +95,6 @@ def connect_port(control_addr = "127.0.0.1", control_port = 9051, password = Non :returns: authenticated control connection, the type based on the controller argument """ - # TODO: replace the controller arg's default when we have something better - try: control_port = stem.socket.ControlPort(control_addr, control_port) except stem.socket.SocketError, exc: @@ -104,7 +103,7 @@ def connect_port(control_addr = "127.0.0.1", control_port = 9051, password = Non return _connect(control_port, password, chroot_path, controller) -def connect_socket_file(socket_path = "/var/run/tor/control", password = None, chroot_path = None, controller = None): +def connect_socket_file(socket_path = "/var/run/tor/control", password = None, chroot_path = None, controller = stem.control.Controller): """ Convenience function for quickly getting a control connection. For more information see the connect_port function.

1 0

[stem/master] Switching to the haiku theme
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit 1ccf6be7dec076afdf4c4a4150c38b5065a8f17e Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jun 3 16:28:07 2012 -0700 Switching to the haiku theme The haiku theme is lighter, and lacks a left-hand bar which makes the content far less cramped. All in all, looks far nicer for the content that we have so far. --- docs/conf.py | 4 ++-- 1 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a9d4b7d..ada61ec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -97,8 +97,8 @@ pygments_style = 'sphinx' # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' -#html_theme = 'haiku' +#html_theme = 'default' +html_theme = 'haiku' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the

1 0

[stem/master] Adding module overviews back to docs
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit 1cfad693de89bc4769605f21d52ef9ba4f38205b Author: Damian Johnson <atagar(a)torproject.org> Date: Mon Jun 4 10:04:45 2012 -0700 Adding module overviews back to docs One bit of documentation that I've found very useful, and sphinx lacks, is a brief summary of a module's contents. Hence adding that back to the headers. --- stem/connection.py | 14 +++++++++++++- stem/process.py | 7 +++++++ stem/version.py | 33 ++++++++++++++++++++------------- 3 files changed, 40 insertions(+), 14 deletions(-) diff --git a/stem/connection.py b/stem/connection.py index 3f971bf..ce83068 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -41,8 +41,20 @@ the authentication process. For instance... print "Unable to authenticate: %s" % exc sys.exit(1) -Authentication failure exception hierchy:: +**Module Overview:** +:: + + 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. + + 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. diff --git a/stem/process.py b/stem/process.py index 5df04dc..b0e5015 100644 --- a/stem/process.py +++ b/stem/process.py @@ -6,6 +6,13 @@ Helper functions for working with tor as a process. :DEFAULT_INIT_TIMEOUT: number of seconds before we time out our attempt to start a tor instance + +**Module Overview:** + +:: + + launch_tor - starts up a tor process + launch_tor_with_config - starts a tor process with a custom torrc """ import re diff --git a/stem/version.py b/stem/version.py index 925acf0..0159512 100644 --- a/stem/version.py +++ b/stem/version.py @@ -2,19 +2,26 @@ Tor versioning information and requirements for its features. These can be easily parsed and compared, for instance... ->>> my_version = stem.version.get_system_tor_version() ->>> print my_version -0.2.1.30 ->>> my_version > stem.version.Requirement.CONTROL_SOCKET -True +:: -+----------------------------------------------------------+ -|Requirement | -+=====================+====================================+ -|GETINFO_CONFIG_TEXT |'GETINFO config-text' query | -+---------------------+------------------------------------+ -|CONTROL_SOCKET |'ControlSocket <path>' config option| -+---------------------+------------------------------------+ + >>> my_version = stem.version.get_system_tor_version() + >>> print my_version + 0.2.1.30 + >>> my_version > stem.version.Requirement.CONTROL_SOCKET + True + +**Module Overview:** + +:: + + get_system_tor_version - gets the version of our system's tor installation + Version - Tor versioning information. + |- __str__ - string representation + +- __cmp__ - compares with another Version + + Requirement - Enumerations for the version requirements of features. + |- GETINFO_CONFIG_TEXT - 'GETINFO config-text' query + +- CONTROL_SOCKET - 'ControlSocket <path>' config option """ import re

1 0

[stem/master] Converting stem.connection to reStructuredText
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit f46b5c7c0e543d90f26155e472a1658827c5f8fe Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jun 3 21:23:49 2012 -0700 Converting stem.connection to reStructuredText --- docs/index.rst | 5 + stem/connection.py | 456 +++++++++++++++++++++++++--------------------------- 2 files changed, 225 insertions(+), 236 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index c735bf6..04348da 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,6 +8,11 @@ Welcome to Stem! Stem is a python controller library for `Tor <https://www.torproject.org/>`_. Like its predecessor, `TorCtl <https://www.torproject.org/getinvolved/volunteer.html.en#project-torctl>`_, it uses Tor's `control protocol <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_ to help developers program against the Tor process, enabling them to build things similar to `Vidalia <https://www.torproject.org/getinvolved/volunteer.html.en#project-vidalia>`_ and `arm <http://www.atagar.com/arm/>`_. +:mod:`stem.connection` +---------------------- + +Connecting and authenticating to a Tor process. + :mod:`stem.process` ------------------- diff --git a/stem/connection.py b/stem/connection.py index c48a7b5..99bc623 100644 --- a/stem/connection.py +++ b/stem/connection.py @@ -10,6 +10,8 @@ undesirable for applications (uses stdin/stdout, suppresses exceptions, etc). The 'authenticate' function, however, gives easy but fine-grained control over the authentication process. For instance... +:: + import sys import getpass import stem.connection @@ -39,37 +41,29 @@ the authentication process. For instance... print "Unable to authenticate: %s" % exc sys.exit(1) -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. - -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. - | - |- 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. - | - |- 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. - | - +- MissingAuthInfo - Unexpected PROTOCOLINFO response, missing auth info. - |- NoAuthMethods - Missing any methods for authenticating. - +- NoAuthCookie - Supports cookie auth but doesn't have its path. +Authentication failure exception hierchy:: + + 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. + | + |- 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. + | + +- MissingAuthInfo - Unexpected PROTOCOLINFO response, missing auth info. + |- NoAuthMethods - Missing any methods for authenticating. + +- NoAuthCookie - Supports cookie auth but doesn't have its path. """ import os @@ -84,92 +78,6 @@ import stem.util.system import stem.util.log as log from stem.response.protocolinfo import AuthMethod -class AuthenticationFailure(Exception): - """ - Base error for authentication failures. - - Attributes: - auth_response (stem.socket.ControlMessage) - AUTHENTICATE response from - the control socket, None if one wasn't received - """ - - def __init__(self, message, auth_response = None): - Exception.__init__(self, message) - self.auth_response = auth_response - -class UnrecognizedAuthMethods(AuthenticationFailure): - "All methods for authenticating aren't recognized." - - def __init__(self, message, unknown_auth_methods): - AuthenticationFailure.__init__(self, message) - self.unknown_auth_methods = unknown_auth_methods - -class IncorrectSocketType(AuthenticationFailure): - "Socket does not speak the control protocol." - -class OpenAuthFailed(AuthenticationFailure): - "Failure to authenticate to an open socket." - -class OpenAuthRejected(OpenAuthFailed): - "Attempt to connect to an open control socket was rejected." - -class PasswordAuthFailed(AuthenticationFailure): - "Failure to authenticate with a password." - -class PasswordAuthRejected(PasswordAuthFailed): - "Socket does not support password authentication." - -class IncorrectPassword(PasswordAuthFailed): - "Authentication password incorrect." - -class MissingPassword(PasswordAuthFailed): - "Password authentication is supported but we weren't provided with one." - -class CookieAuthFailed(AuthenticationFailure): - "Failure to authenticate with an authentication cookie." - - def __init__(self, message, cookie_path, auth_response = None): - AuthenticationFailure.__init__(self, message, auth_response) - self.cookie_path = cookie_path - -class CookieAuthRejected(CookieAuthFailed): - "Socket does not support password authentication." - -class IncorrectCookieValue(CookieAuthFailed): - "Authentication cookie value was rejected." - -class IncorrectCookieSize(CookieAuthFailed): - "Aborted because the cookie file is the wrong size." - -class UnreadableCookieFile(CookieAuthFailed): - "Error arose in reading the authentication cookie." - -class MissingAuthInfo(AuthenticationFailure): - """ - The PROTOCOLINFO response didn't have enough information to authenticate. - These are valid control responses but really shouldn't happen in practice. - """ - -class NoAuthMethods(MissingAuthInfo): - "PROTOCOLINFO response didn't have any methods for authenticating." - -class NoAuthCookie(MissingAuthInfo): - "PROTOCOLINFO response supports cookie auth but doesn't have its path." - -# authentication exceptions ordered as per the authenticate function's pydocs -AUTHENTICATE_EXCEPTIONS = ( - IncorrectSocketType, - UnrecognizedAuthMethods, - MissingPassword, - IncorrectPassword, - IncorrectCookieSize, - UnreadableCookieFile, - IncorrectCookieValue, - OpenAuthRejected, - MissingAuthInfo, - AuthenticationFailure, -) - def connect_port(control_addr = "127.0.0.1", control_port = 9051, password = None, chroot_path = None, controller = None): """ Convenience function for quickly getting a control connection. This is very @@ -177,17 +85,13 @@ def connect_port(control_addr = "127.0.0.1", control_port = 9051, password = Non if necessary (and none is provided). If any issues arise this prints a description of the problem and returns None. - Arguments: - control_addr (str) - ip address of the controller - control_port (int) - port number of the controller - password (str) - passphrase to authenticate to the socket - chroot_path (str) - path prefix if in a chroot environment - controller (Class) - BaseController subclass to be returned, this provides - a ControlSocket if None - - Returns: - Authenticated control connection, the type based on the controller - argument. + :param str control_addr: ip address of the controller + :param int control_port: port number of the controller + :param str password: passphrase to authenticate to the socket + :param str chroot_path: path prefix if in a chroot environment + :param Class controller: BaseController subclass to be returned, this provides a ControlSocket if None + + :returns: authenticated control connection, the type based on the controller argument """ # TODO: replace the controller arg's default when we have something better @@ -205,15 +109,12 @@ def connect_socket_file(socket_path = "/var/run/tor/control", password = None, c Convenience function for quickly getting a control connection. For more information see the connect_port function. - Arguments: - socket_path (str) - path where the control socket is located - password (str) - passphrase to authenticate to the socket - chroot_path (str) - path prefix if in a chroot environment - controller (Class) - BaseController subclass to be returned, this provides - a ControlSocket if None + :param str socket_path: path where the control socket is located + :param str password: passphrase to authenticate to the socket + :param str chroot_path: path prefix if in a chroot environment + :param Class controller: BaseController subclass to be returned, this provides a ControlSocket if None - Returns: - Authenticated control connection, the type based on the controller enum. + :returns: authenticated control connection, the type based on the controller argument """ try: @@ -228,15 +129,12 @@ def _connect(control_socket, password, chroot_path, controller): """ Common implementation for the connect_* functions. - Arguments: - control_socket (stem.socket.ControlSocket) - socket being authenticated to - password (str) - passphrase to authenticate to the socket - chroot_path (str) - path prefix if in a chroot environment - controller (Class) - BaseController subclass to be returned, this provides - a ControlSocket if None + :param stem.socket.ControlSocket control_socket: socket being authenticated to + :param str password: passphrase to authenticate to the socket + :param str chroot_path: path prefix if in a chroot environment + :param Class controller: BaseController subclass to be returned, this provides a ControlSocket if None - Returns: - Authenticated control connection with a type based on the controller enum. + :returns: authenticated control connection, the type based on the controller argument """ try: @@ -268,71 +166,76 @@ def authenticate(controller, password = None, chroot_path = None, protocolinfo_r callers should catch the types of authentication failure that they care about, then have a AuthenticationFailure catch-all at the end. - Arguments: - controller (stem.socket.ControlSocket or stem.control.BaseController) - - tor controller connection to be authenticated - password (str) - passphrase to present to the socket if it uses password - authentication (skips password auth if None) - chroot_path (str) - path prefix if in a chroot environment - protocolinfo_response (stem.response.protocolinfo.ProtocolInfoResponse) - - tor protocolinfo response, this is retrieved on our own if None - - Raises: - AuthenticationFailed subclass if all attempts to authenticate fail. Since - this may try multiple authentication methods it may encounter multiple - exceptions. If so then the exception this raises is prioritized as - follows... - - stem.connection.IncorrectSocketType + This can authenticate to either a :class:`stem.control.BaseController` or + :class:`stem.socket.ControlSocket`. + + :param controller: tor controller or socket to be authenticated + :param str password: passphrase to present to the socket if it uses password authentication (skips password auth if None) + :param str chroot_path: path prefix if in a chroot environment + :param stem.response.protocolinfo.ProtocolInfoResponse protocolinfo_response: tor protocolinfo response, this is retrieved on our own if None + + :raises: If all attempts to authenticate fails then this will raise a :class:`stem.connection.AuthenticationFailure` subclass. Since this may try multiple authentication methods it may encounter multiple exceptions. If so then the exception this raises is prioritized as follows... + + * :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. - 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. - 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'. - stem.connection.IncorrectPassword + * :class:`stem.connection.IncorrectPassword` + We were provided with a password but it was incorrect. - 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. - 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). - stem.connection.IncorrectCookieValue (*) + * **\***:class:`stem.connection.IncorrectCookieValue` + Tor allows for authentication by reading it a cookie file, but rejected the contents of that file. - stem.connection.OpenAuthRejected (*) + * **\***:class:`stem.connection.OpenAuthRejected` + Tor says that it allows for authentication without any credentials, but then rejected our authentication attempt. - 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. - 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 mostly constitute transient failures or bugs. - * In practice it is highly unusual for this to occur, being more of a - theoretical possibility rather than something you should expect. It's - fine to treat these as errors. If you have a use case where this commonly - happens, please file a ticket on 'trac.torproject.org'. - - In the future new AuthenticationFailure subclasses may be added to allow - for better error handling. + **\*** In practice it is highly unusual for this to occur, being more of a + theoretical possibility rather than something you should expect. It's fine + to treat these as errors. If you have a use case where this commonly + happens, please file a ticket on 'trac.torproject.org'. + + In the future new :class:`stem.connection.AuthenticationFailure` subclasses + may be added to allow for better error handling. """ if not protocolinfo_response: @@ -431,17 +334,15 @@ def authenticate_none(controller, suppress_ctl_errors = True): attempt to re-establish the connection. This may not succeed, so check is_alive() before using the socket further. - For general usage use the authenticate() function instead. + This can authenticate to either a :class:`stem.control.BaseController` or + :class:`stem.socket.ControlSocket`. - Arguments: - controller (stem.socket.ControlSocket or stem.control.BaseController) - - tor controller connection - suppress_ctl_errors (bool) - reports raised stem.socket.ControllerError as - authentication rejection if True, otherwise they're re-raised + *For general usage use the authenticate() function instead.* - Raises: - stem.connection.OpenAuthRejected if the empty authentication credentials - aren't accepted + :param controller: tor controller or socket to be authenticated + :param bool suppress_ctl_errors: reports raised :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 """ try: @@ -469,26 +370,23 @@ def authenticate_password(controller, password, suppress_ctl_errors = True): attempt to re-establish the connection. This may not succeed, so check is_alive() before using the socket further. - For general usage use the authenticate() function instead. - - note: If you use this function directly, rather than authenticate(), we may + If you use this function directly, rather than authenticate(), we may mistakenly raise a PasswordAuthRejected rather than IncorrectPassword. This is because we rely on tor's error messaging which is liable to change in - future versions... - https://trac.torproject.org/4817 - - Arguments: - controller (stem.socket.ControlSocket or stem.control.BaseController) - - tor controller connection - password (str) - passphrase to present to the socket - suppress_ctl_errors (bool) - reports raised stem.socket.ControllerError as - authentication rejection if True, otherwise they're re-raised - - Raises: - stem.connection.PasswordAuthRejected if the socket doesn't accept password - authentication - stem.connection.IncorrectPassword if the authentication credentials aren't - accepted + future versions (`ticket <https://trac.torproject.org/4817>`_). + + This can authenticate to either a :class:`stem.control.BaseController` or + :class:`stem.socket.ControlSocket`. + + *For general usage use the authenticate() function instead.* + + :param controller: tor controller or socket to be authenticated + :param str password: passphrase to present to the socket + :param bool suppress_ctl_errors: reports raised :class:`stem.socket.ControllerError` as authentication rejection if True, otherwise they're re-raised + + :raises: + * :class:`stem.connection.PasswordAuthRejected` if the socket doesn't accept password authentication + * :class:`stem.connection.IncorrectPassword` if the authentication credentials aren't accepted """ # Escapes quotes. Tor can include those in the password hash, in which case @@ -534,28 +432,25 @@ def authenticate_cookie(controller, cookie_path, suppress_ctl_errors = True): attempt to re-establish the connection. This may not succeed, so check is_alive() before using the socket further. - For general usage use the authenticate() function instead. - - note: If you use this function directly, rather than authenticate(), we may + If you use this function directly, rather than authenticate(), we may mistakenly raise a CookieAuthRejected rather than IncorrectCookieValue. This is because we rely on tor's error messaging which is liable to change in - future versions... - https://trac.torproject.org/4817 - - Arguments: - controller (stem.socket.ControlSocket or stem.control.BaseController) - - tor controller connection - cookie_path (str) - path of the authentication cookie to send to tor - suppress_ctl_errors (bool) - reports raised stem.socket.ControllerError as - authentication rejection if True, otherwise they're re-raised - - Raises: - stem.connection.IncorrectCookieSize if the cookie file's size is wrong - stem.connection.UnreadableCookieFile if the cookie file doesn't exist or - we're unable to read it - stem.connection.CookieAuthRejected if cookie authentication is attempted - but the socket doesn't accept it - stem.connection.IncorrectCookieValue if the cookie file's value is rejected + future versions (`ticket <https://trac.torproject.org/4817>`_). + + This can authenticate to either a :class:`stem.control.BaseController` or + :class:`stem.socket.ControlSocket`. + + *For general usage use the authenticate() function instead.* + + :param controller: tor controller or socket to be authenticated + :param str cookie_path: path of the authentication cookie to send to tor + :param bool suppress_ctl_errors: reports raised :class:`stem.socket.ControllerError` as authentication rejection if True, otherwise they're re-raised + + :raises: + * :class:`stem.connection.IncorrectCookieSize` if the cookie file's size is wrong + * :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 attempted but the socket doesn't accept it + * :class:`stem.connection.IncorrectCookieValue` if the cookie file's value is rejected """ if not os.path.exists(cookie_path): @@ -615,23 +510,20 @@ def get_protocolinfo(controller): first reconnected. According to the control spec the cookie_file is an absolute path. However, - this often is not the case (especially for the Tor Browser Bundle)... - https://trac.torproject.org/projects/tor/ticket/1101 + this often is not the case (especially for the Tor Browser Bundle). If the + path is relative then we'll make an attempt (which may not work) to correct + this (`ticket <https://trac.torproject.org/1101>`_). - If the path is relative then we'll make an attempt (which may not work) to - correct this. + This can authenticate to either a :class:`stem.control.BaseController` or + :class:`stem.socket.ControlSocket`. - Arguments: - controller (stem.socket.ControlSocket or stem.control.BaseController) - - tor controller connection + :param controller: tor controller or socket to be queried - Returns: - stem.response.protocolinfo.ProtocolInfoResponse provided by tor + :returns: :class:`stem.response.protocolinfo.ProtocolInfoResponse` provided by tor - Raises: - stem.socket.ProtocolError if the PROTOCOLINFO response is malformed - stem.socket.SocketError if problems arise in establishing or using the - socket + :raises: + * :class:`stem.socket.ProtocolError` if the PROTOCOLINFO response is malformed + * :class:`stem.socket.SocketError` if problems arise in establishing or using the socket """ try: @@ -714,3 +606,95 @@ def _expand_cookie_path(protocolinfo_response, pid_resolver, pid_resolution_arg) protocolinfo_response.cookie_path = cookie_path +class AuthenticationFailure(Exception): + """ + Base error for authentication failures. + + :var stem.socket.ControlMessage auth_response: AUTHENTICATE response from the control socket, None if one wasn't received + """ + + def __init__(self, message, auth_response = None): + Exception.__init__(self, message) + self.auth_response = auth_response + +class UnrecognizedAuthMethods(AuthenticationFailure): + """ + All methods for authenticating aren't recognized. + + :var list unknown_auth_methods: authentication methods that weren't recognized + """ + + def __init__(self, message, unknown_auth_methods): + AuthenticationFailure.__init__(self, message) + self.unknown_auth_methods = unknown_auth_methods + +class IncorrectSocketType(AuthenticationFailure): + "Socket does not speak the control protocol." + +class OpenAuthFailed(AuthenticationFailure): + "Failure to authenticate to an open socket." + +class OpenAuthRejected(OpenAuthFailed): + "Attempt to connect to an open control socket was rejected." + +class PasswordAuthFailed(AuthenticationFailure): + "Failure to authenticate with a password." + +class PasswordAuthRejected(PasswordAuthFailed): + "Socket does not support password authentication." + +class IncorrectPassword(PasswordAuthFailed): + "Authentication password incorrect." + +class MissingPassword(PasswordAuthFailed): + "Password authentication is supported but we weren't provided with one." + +class CookieAuthFailed(AuthenticationFailure): + """ + Failure to authenticate with an authentication cookie. + + :param str cookie_path: location of the authentication cookie we attempted + """ + + def __init__(self, message, cookie_path, auth_response = None): + AuthenticationFailure.__init__(self, message, auth_response) + self.cookie_path = cookie_path + +class CookieAuthRejected(CookieAuthFailed): + "Socket does not support password authentication." + +class IncorrectCookieValue(CookieAuthFailed): + "Authentication cookie value was rejected." + +class IncorrectCookieSize(CookieAuthFailed): + "Aborted because the cookie file is the wrong size." + +class UnreadableCookieFile(CookieAuthFailed): + "Error arose in reading the authentication cookie." + +class MissingAuthInfo(AuthenticationFailure): + """ + The PROTOCOLINFO response didn't have enough information to authenticate. + These are valid control responses but really shouldn't happen in practice. + """ + +class NoAuthMethods(MissingAuthInfo): + "PROTOCOLINFO response didn't have any methods for authenticating." + +class NoAuthCookie(MissingAuthInfo): + "PROTOCOLINFO response supports cookie auth but doesn't have its path." + +# authentication exceptions ordered as per the authenticate function's pydocs +AUTHENTICATE_EXCEPTIONS = ( + IncorrectSocketType, + UnrecognizedAuthMethods, + MissingPassword, + IncorrectPassword, + IncorrectCookieSize, + UnreadableCookieFile, + IncorrectCookieValue, + OpenAuthRejected, + MissingAuthInfo, + AuthenticationFailure, +) +

1 0

[stem/master] Converting stem.response to reStructuredText
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit 68dc6af5c74cd8b733b07542c88f5af96bb146be Author: Damian Johnson <atagar(a)torproject.org> Date: Tue Jun 5 09:31:55 2012 -0700 Converting stem.response to reStructuredText --- docs/index.rst | 7 +- stem/response/__init__.py | 206 ++++++++++++++++++++--------------------- stem/response/getinfo.py | 3 +- stem/response/protocolinfo.py | 50 ++++++---- 4 files changed, 136 insertions(+), 130 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index c3cd4d9..a5bc151 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,7 +21,7 @@ Provides the :class:`stem.control.Controller` class which, as the name implies, :mod:`stem.socket` ------------------ -Base classes for communicating with a tor control socket. +Base classes for communicating with a Tor control socket. :mod:`stem.process` ------------------- @@ -33,6 +33,11 @@ Used for launching Tor and managing the process. Parsed versions that can be compared to the requirement for various features. +:mod:`stem.response` +-------------------- + +Parsed replies that we receive from the Tor control socket. + .. toctree:: :maxdepth: 2 diff --git a/stem/response/__init__.py b/stem/response/__init__.py index 1f2ed0c..823cefa 100644 --- a/stem/response/__init__.py +++ b/stem/response/__init__.py @@ -1,22 +1,26 @@ """ Parses replies from the control socket. -convert - translates a ControlMessage into a particular response subclass +**Module Overview:** -ControlMessage - Message that's read from the control socket. - |- content - provides the parsed message content - |- raw_content - unparsed socket data - |- __str__ - content stripped of protocol formatting - +- __iter__ - ControlLine entries for the content of the message +:: -ControlLine - String subclass with methods for parsing controller responses. - |- remainder - provides the unparsed content - |- is_empty - checks if the remaining content is empty - |- is_next_quoted - checks if the next entry is a quoted value - |- is_next_mapping - checks if the next entry is a KEY=VALUE mapping - |- peek_key - provides the key of the next entry - |- pop - removes and returns the next entry - +- pop_mapping - removes and returns the next entry as a KEY=VALUE mapping + convert - translates a ControlMessage into a particular response subclass + + ControlMessage - Message that's read from the control socket. + |- content - provides the parsed message content + |- raw_content - unparsed socket data + |- __str__ - content stripped of protocol formatting + +- __iter__ - ControlLine entries for the content of the message + + ControlLine - String subclass with methods for parsing controller responses. + |- remainder - provides the unparsed content + |- is_empty - checks if the remaining content is empty + |- is_next_quoted - checks if the next entry is a quoted value + |- is_next_mapping - checks if the next entry is a KEY=VALUE mapping + |- peek_key - provides the key of the next entry + |- pop - removes and returns the next entry + +- pop_mapping - removes and returns the next entry as a KEY=VALUE mapping """ __all__ = ["getinfo", "protocolinfo", "convert", "ControlMessage", "ControlLine"] @@ -47,14 +51,12 @@ def convert(response_type, message): If the response_type isn't recognized then this is leaves it alone. - Arguments: - response_type (str) - type of tor response to convert to - message (stem.response.ControlMessage) - message to be converted + :param str response_type: type of tor response to convert to + :param stem.response.ControlMessage message: message to be converted - Raises: - stem.socket.ProtocolError the message isn't a proper response of that type - TypeError if argument isn't a ControlMessage or response_type isn't - supported + :raises: + * :class:`stem.socket.ProtocolError` the message isn't a proper response of that type + * TypeError if argument isn't a :class:`stem.response.ControlMessage` or response_type isn't supported """ import stem.response.getinfo @@ -86,8 +88,7 @@ class ControlMessage: """ Checks if all of our lines have a 250 response. - Returns: - True if all lines have a 250 response code, False otherwise + :returns: True if all lines have a 250 response code, False otherwise """ for code, _, _ in self._parsed_content: @@ -98,20 +99,26 @@ class ControlMessage: def content(self): """ Provides the parsed message content. These are entries of the form... - (status_code, divider, content) - * status_code - Three character code for the type of response (defined in - section 4 of the control-spec). - * divider - Single character to indicate if this is mid-reply, data, or - an end to the message (defined in section 2.3 of the - control-spec). - * content - The following content is the actual payload of the line. + :: + + (status_code, divider, content) + + **status_code** + Three character code for the type of response (defined in section 4 of + the control-spec). + + **divider** + Single character to indicate if this is mid-reply, data, or an end to the + message (defined in section 2.3 of the control-spec). + + **content** + The following content is the actual payload of the line. 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) @@ -120,8 +127,7 @@ class ControlMessage: """ Provides the unparsed content read from the control socket. - Returns: - string of the socket data used to generate this message + :returns: string of the socket data used to generate this message """ return self._raw_content @@ -139,17 +145,22 @@ class ControlMessage: Provides ControlLine instances for the content of the message. This is stripped of status codes and dividers, for instance... - 250+info/names= - desc/id/* -- Router descriptors by ID. - desc/name/* -- Router descriptors by nickname. - . - 250 OK + :: + + 250+info/names= + desc/id/* -- Router descriptors by ID. + desc/name/* -- Router descriptors by nickname. + . + 250 OK Would provide two entries... - 1st - "info/names= - desc/id/* -- Router descriptors by ID. - desc/name/* -- Router descriptors by nickname." - 2nd - "OK" + + :: + + 1st - "info/names= + desc/id/* -- Router descriptors by ID. + desc/name/* -- Router descriptors by nickname." + 2nd - "OK" """ for _, _, content in self._parsed_content: @@ -177,8 +188,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 @@ -187,8 +197,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 == "" @@ -197,11 +206,9 @@ class ControlLine(str): """ Checks if our next entry is a quoted value or not. - Arguments: - escaped (bool) - 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) @@ -211,15 +218,11 @@ class ControlLine(str): """ Checks if our next entry is a KEY=VALUE mapping or not. - Arguments: - key (str) - checks that the key matches this value, skipping the - check if None - quoted (bool) - checks that the mapping is to a quoted value - escaped (bool) - unescapes the CONTROL_ESCAPES escape sequences + :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 - 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 @@ -243,8 +246,7 @@ class ControlLine(str): 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 @@ -260,29 +262,28 @@ class ControlLine(str): Parses the next space separated entry, removing it and the space from our remaining content. Examples... - >>> line = ControlLine("\"We're all mad here.\" says the grinning cat.") - >>> print line.pop(True) - "We're all mad here." - >>> print line.pop() - "says" - >>> print line.remainder() - "the grinning cat." - - >>> line = ControlLine("\"this has a \\\" and \\\\ in it\" foo=bar more_data") - >>> print line.pop(True, True) - "this has a \" and \\ in it" - - Arguments: - quoted (bool) - parses the next entry as a quoted value, removing the - quotes - escaped (bool) - unescapes the CONTROL_ESCAPES escape sequences - - 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 + :: + + >>> line = ControlLine("\\"We're all mad here.\\" says the grinning cat.") + >>> print line.pop(True) + "We're all mad here." + >>> print line.pop() + "says" + >>> print line.remainder() + "the grinning cat." + + >>> line = ControlLine("\\"this has a \\\\\\" and \\\\\\\\ in it\\" foo=bar more_data") + >>> print line.pop(True, True) + "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 + + :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 """ with self._remainder_lock: @@ -295,16 +296,12 @@ class ControlLine(str): Parses the next space separated entry as a KEY=VALUE mapping, removing it and the space from our remaining content. - Arguments: - quoted (bool) - parses the value as being quoted, removing the quotes - escaped (bool) - unescapes the CONTROL_ESCAPES escape sequences + :param bool quoted: parses the value as being quoted, removing the quotes + :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: ValueError if this isn't a KEY=VALUE mapping or if quoted is True without the value being quoted """ with self._remainder_lock: @@ -326,18 +323,15 @@ def _parse_entry(line, quoted, escaped): """ Parses the next entry from the given space separated content. - Arguments: - line (str) - content to be parsed - quoted (bool) - parses the next entry as a quoted value, removing the - quotes - escaped (bool) - unescapes the CONTROL_ESCAPES escape sequences + :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 - 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 + :raises: + * ValueError if quoted is True without the next value being quoted + * IndexError if there's nothing to parse from the line """ if line == "": @@ -368,12 +362,10 @@ def _get_quote_indeces(line, escaped): """ Provides the indices of the next two quotes in the given content. - Arguments: - line (str) - content to be parsed - escaped (bool) - unescapes the CONTROL_ESCAPES escape sequences + :param str line: content to be parsed + :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 diff --git a/stem/response/getinfo.py b/stem/response/getinfo.py index 6f6cde4..9b1fe75 100644 --- a/stem/response/getinfo.py +++ b/stem/response/getinfo.py @@ -5,8 +5,7 @@ class GetInfoResponse(stem.response.ControlMessage): """ Reply for a GETINFO query. - Attributes: - entries (dict) - mapping between the queried options and their values + :var dict entries: mapping between the queried options and their values """ def _parse_message(self): diff --git a/stem/response/protocolinfo.py b/stem/response/protocolinfo.py index ce9a82c..ece96a3 100644 --- a/stem/response/protocolinfo.py +++ b/stem/response/protocolinfo.py @@ -1,22 +1,32 @@ +""" +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.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 -# 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. -# -# NONE - No authentication required -# PASSWORD - See tor's HashedControlPassword option. Controllers must provide -# the password used to generate the hash. -# COOKIE - See tor's CookieAuthentication option. Controllers need to supply -# the contents of the cookie file. -# UNKNOWN - Tor provided one or more authentication methods that we don't -# recognize. This is probably from a new addition to the control -# protocol. - AuthMethod = stem.util.enum.Enum("NONE", "PASSWORD", "COOKIE", "UNKNOWN") class ProtocolInfoResponse(stem.response.ControlMessage): @@ -24,14 +34,14 @@ class ProtocolInfoResponse(stem.response.ControlMessage): Version one PROTOCOLINFO query response. The protocol_version is the only mandatory data for a valid PROTOCOLINFO - response, so all other values are None if undefined or empty if a collection. + response, so all other values are ``None`` if undefined or empty if a + collection. - Attributes: - protocol_version (int) - protocol version of the response - tor_version (stem.version.Version) - version of the tor process - auth_methods (tuple) - AuthMethod types that tor will accept - unknown_auth_methods (tuple) - strings of unrecognized auth methods - cookie_path (str) - path of tor's authentication cookie + :var int protocol_version: protocol version of the response + :var stem.version.Version tor_version: version of the tor process + :var tuple auth_methods: AuthMethod types that tor will accept + :var tuple unknown_auth_methods: strings of unrecognized auth methods + :var str cookie_path: path of tor's authentication cookie """ def _parse_message(self):

1 0

[stem/master] Converting stem.util.connection to reStructuredText
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit c1392cd8b3322be4b39980dea54d5b224ed7062f Author: Damian Johnson <atagar(a)torproject.org> Date: Tue Jun 5 19:26:54 2012 -0700 Converting stem.util.connection to reStructuredText --- stem/util/connection.py | 26 +++++++++----------------- 1 files changed, 9 insertions(+), 17 deletions(-) diff --git a/stem/util/connection.py b/stem/util/connection.py index 93030fc..cbf9856 100644 --- a/stem/util/connection.py +++ b/stem/util/connection.py @@ -1,8 +1,7 @@ """ Connection and networking based utility functions. This will likely be expanded -later to have all of arm's functions... -https://gitweb.torproject.org/arm.git/blob/HEAD:/src/util/connections.py - +later to have all of `arm's functions +<https://gitweb.torproject.org/arm.git/blob/HEAD:/src/util/connections.py>`_, but for now just moving the parts we need. """ @@ -12,11 +11,9 @@ def is_valid_ip_address(address): """ Checks if a string is a valid IPv4 address. - Arguments: - address (str) - string to be checked + :param str address: string to be checked - Returns: - True if input is a valid IPv4 address, False otherwise. + :returns: True if input is a valid IPv4 address, False otherwise """ # checks if theres four period separated values @@ -35,11 +32,9 @@ def is_valid_ipv6_address(address): """ Checks if a string is a valid IPv6 address. - Arguments: - address (str) - string to be checked + :param str address: string to be checked - Returns: - True if input is a valid IPv6 address, False otherwise. + :returns: True if input is a valid IPv6 address, False otherwise """ # addresses are made up of eight colon separated groups of four hex digits @@ -65,13 +60,10 @@ def is_valid_port(entry, allow_zero = False): """ Checks if a string or int is a valid port number. - Arguments: - entry (str or int) - string or integer to be checked - allow_zero (bool) - accept port number of zero (reserved by defintion) + :param str,int entry: string or integer to be checked + :param bool allow_zero: accept port number of zero (reserved by defintion) - Returns: - True if input is an integer and within the valid port range, False - otherwise. + :returns: True if input is an integer and within the valid port range, False otherwise """ if isinstance(entry, str):

1 0

[stem/master] Converting stem.socket to reStructuredText
by atagar＠torproject.org 06 Jun '12

06 Jun '12

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

1 0

[stem/master] Converting stem.control to reStructuredText
by atagar＠torproject.org 06 Jun '12

06 Jun '12

commit cbcf257ee91f78a58984a2335814a589c51f14e9 Author: Damian Johnson <atagar(a)torproject.org> Date: Tue Jun 5 07:54:20 2012 -0700 Converting stem.control to reStructuredText --- docs/index.rst | 5 ++ stem/control.py | 144 ++++++++++++++++++++++++------------------------------- 2 files changed, 68 insertions(+), 81 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 04348da..2cf68fd 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,11 @@ Stem is a python controller library for `Tor <https://www.torproject.org/>`_. Li Connecting and authenticating to a Tor process. +:mod:`stem.control` +---------------------- + +Provides the :class:`stem.control.Controller` class which, as the name implies, is used for talking with and controlling a Tor instance. As a user this is the primary class that you'll need. + :mod:`stem.process` ------------------- diff --git a/stem/control.py b/stem/control.py index a6bc3d2..7b56194 100644 --- a/stem/control.py +++ b/stem/control.py @@ -2,24 +2,26 @@ Classes for interacting with the tor control socket. Controllers are a wrapper around a ControlSocket, retaining many of its methods -(send, recv, is_alive, etc) in addition to providing its own for interacting at -a higher level. +(connect, close, is_alive, etc) in addition to providing its own for +interacting at a higher level. -from_port - Provides a Controller based on a port connection. -from_socket_file - Provides a Controller based on a socket file connection. +:: -Controller - General controller class intended for direct use. - +- get_info - issues a GETINFO query - -BaseController - Base controller class asynchronous message handling. - |- msg - communicates with the tor process - |- is_alive - reports if our connection to tor is open or closed - |- connect - connects or reconnects to tor - |- close - shuts down our connection to the tor process - |- get_socket - provides the socket used for control communication - |- add_status_listener - notifies a callback of changes in our status - |- remove_status_listener - prevents further notification of status changes - +- __enter__ / __exit__ - manages socket connection + from_port - Provides a Controller based on a port connection. + from_socket_file - Provides a Controller based on a socket file connection. + + Controller - General controller class intended for direct use. + +- get_info - issues a GETINFO query + + BaseController - Base controller class asynchronous message handling. + |- msg - communicates with the tor process + |- is_alive - reports if our connection to tor is open or closed + |- connect - connects or reconnects to tor + |- close - shuts down our connection to the tor process + |- get_socket - provides the socket used for control communication + |- add_status_listener - notifies a callback of changes in our status + |- remove_status_listener - prevents further notification of status changes + +- __enter__ / __exit__ - manages socket connection """ import time @@ -39,9 +41,9 @@ State = stem.util.enum.Enum("INIT", "RESET", "CLOSED") # Constant to indicate an undefined argument default. Usually we'd use None for # this, but users will commonly provide None as the argument so need something -# else very, very unique... +# else fairly unique... -UNDEFINED = "<Undefined>" * 10 +UNDEFINED = "<Undefined_ >" class BaseController: """ @@ -88,16 +90,14 @@ class BaseController: """ Sends a message to our control socket and provides back its reply. - Arguments: - message (str) - message to be formatted and sent to tor + :param str message: message to be formatted and sent to tor - Returns: - stem.response.ControlMessage with the response + :returns: :class:`stem.response.ControlMessage` with the response - Raises: - stem.socket.ProtocolError the content from the socket is malformed - stem.socket.SocketError if a problem arises in using the socket - stem.socket.SocketClosed if the socket is shut down + :raises: + * :class:`stem.socket.ProtocolError` the content from the socket is malformed + * :class:`stem.socket.SocketError` if a problem arises in using the socket + * :class:`stem.socket.SocketClosed` if the socket is shut down """ with self._msg_lock: @@ -161,8 +161,7 @@ class BaseController: Checks if our socket is currently connected. This is a passthrough for our socket's is_alive() method. - Returns: - bool that's True if we're shut down and False otherwise + :returns: bool that's True if we're shut down and False otherwise """ return self._socket.is_alive() @@ -172,8 +171,7 @@ class BaseController: Reconnects our control socket. This is a passthrough for our socket's connect() method. - Raises: - stem.socket.SocketError if unable to make a socket + :raises: :class:`stem.socket.SocketError` if unable to make a socket """ self._socket.connect() @@ -181,7 +179,7 @@ class BaseController: def close(self): """ Closes our socket connection. This is a passthrough for our socket's - close() method. + :func:`stem.socket.ControlSocket.close` method. """ self._socket.close() @@ -191,8 +189,7 @@ class BaseController: Provides the socket used to speak with the tor process. Communicating with the socket directly isn't advised since it may confuse the controller. - Returns: - ControlSocket for process communications + :returns: :class:`stem.socket.ControlSocket` we're communicating with """ return self._socket @@ -202,13 +199,15 @@ class BaseController: Notifies a given function when the state of our socket changes. Functions are expected to be of the form... + :: + my_function(controller, state, timestamp) - The state is a value from stem.socket.State, functions *must* allow for + The state is a value from stem.socket.State, functions **must** allow for new values in this field. The timestamp is a float for the unix time when the change occured. - This class only provides State.INIT and State.CLOSED notifications. + This class only provides ``State.INIT`` and ``State.CLOSED`` notifications. Subclasses may provide others. If spawn is True then the callback is notified via a new daemon thread. If @@ -216,10 +215,8 @@ class BaseController: change occured. In general this isn't advised, especially if your callback could block for a while. - Arguments: - callback (function) - function to be notified when our state changes - spawn (bool) - calls function via a new thread if True, otherwise - it's part of the connect/close method call + :param function callback: function to be notified when our state changes + :param bool spawn: calls function via a new thread if True, otherwise it's part of the connect/close method call """ with self._status_listeners_lock: @@ -229,12 +226,9 @@ class BaseController: """ Stops listener from being notified of further events. - Arguments: - callback (function) - function to be removed from our listeners + :param function callback: function to be removed from our listeners - Returns: - bool that's True if we removed one or more occurances of the callback, - False otherwise + :returns: bool that's True if we removed one or more occurances of the callback, False otherwise """ with self._status_listeners_lock: @@ -259,9 +253,7 @@ class BaseController: Callback to be overwritten by subclasses for event listening. This is notified whenever we receive an event from the control socket. - Arguments: - event_message (stem.response.ControlMessage) - message received from the - control socket + :param stem.response.ControlMessage event_message: message received from the control socket """ pass @@ -293,18 +285,16 @@ class BaseController: States imply that our socket is either alive or not, which may not hold true when multiple events occure in quick succession. For instance, a - sighup could cause two events (State.RESET for the sighup and State.CLOSE - if it causes tor to crash). However, there's no guarentee of the order in - which they occure, and it would be bad if listeners got the State.RESET - last, implying that we were alive. + sighup could cause two events (``State.RESET`` for the sighup and + ``State.CLOSE`` if it causes tor to crash). However, there's no guarentee + of the order in which they occure, and it would be bad if listeners got the + ``State.RESET`` last, implying that we were alive. If set, the expect_alive flag will discard our event if it conflicts with - our current is_alive() state. + our current :func:`stem.control.BaseController.is_alive` state. - Arguments: - state (stem.socket.State) - state change that has occured - expect_alive (bool) - discard event if it conflicts with our - is_alive() state + :param stem.socket.State state: state change that has occured + :param bool expect_alive: discard event if it conflicts with our :func:`stem.control.BaseController.is_alive` state """ # Any changes to our is_alive() state happen under the send lock, so we @@ -352,8 +342,8 @@ class BaseController: Continually pulls from the control socket, directing the messages into queues based on their type. Controller messages come in two varieties... - - Responses to messages we've sent (GETINFO, SETCONF, etc). - - Asynchronous events, identified by a status code of 650. + * Responses to messages we've sent (GETINFO, SETCONF, etc). + * Asynchronous events, identified by a status code of 650. """ while self.is_alive(): @@ -403,15 +393,12 @@ class Controller(BaseController): """ Constructs a ControlPort based Controller. - Arguments: - control_addr (str) - ip address of the controller - control_port (int) - port number of the controller + :param str control_addr: ip address of the controller + :param int control_port: port number of the controller - Returns: - stem.control.Controller attached to the given port + :returns: :class:`stem.control.Controller` attached to the given port - Raises: - stem.socket.SocketError if we're unable to establish a connection + :raises: :class:`stem.socket.SocketError` if we're unable to establish a connection """ control_port = stem.socket.ControlPort(control_addr, control_port) @@ -421,14 +408,11 @@ class Controller(BaseController): """ Constructs a ControlSocketFile based Controller. - Arguments: - socket_path (str) - path where the control socket is located + :param str socket_path: path where the control socket is located - Returns: - stem.control.Controller attached to the given socket file + :returns: :class:`stem.control.Controller` attached to the given socket file - Raises: - stem.socket.SocketError if we're unable to establish a connection + :raises: :class:`stem.socket.SocketError` if we're unable to establish a connection """ control_socket = stem.socket.ControlSocketFile(socket_path) @@ -444,19 +428,17 @@ class Controller(BaseController): call fails for any reason (error response, control port closed, initiated, etc). - Arguments: - param (str, list) - GETINFO option or options to be queried - default (object) - response if the query fails + :param str,list param: GETINFO option or options to be queried + :param object default: response if the query fails - Returns: + :returns: Response depends upon how we were called as follows... - - str with the response if our param was a str - - dict with the param => response mapping if our param was a list - - default if one was provided and our call failed + + * str with the response if our param was a str + * dict with the param => response mapping if our param was a list + * default if one was provided and our call failed - Raises: - stem.socket.ControllerError if the call fails, and we weren't provided a - default response + :raises: :class:`stem.socket.ControllerError` if the call fails, and we weren't provided a default response """ # TODO: add caching?

1 0