May 2014 - tor-commits - lists.torproject.org

[stem/master] Interpretor event handling
by atagar＠torproject.org 06 May '14

06 May '14

commit e4ea4f64e19c53a85414294f5b446d10cce4a074 Author: Damian Johnson <atagar(a)torproject.org> Date: Tue Apr 15 09:42:54 2014 -0700 Interpretor event handling Supporting SETEVENTS and an '/event [type]' interpretor command for listing the events we've received. --- stem/interpretor/commands.py | 42 ++++++++++++++++++++++++++++++++++++++++- stem/interpretor/settings.cfg | 6 ++++++ 2 files changed, 47 insertions(+), 1 deletion(-) diff --git a/stem/interpretor/commands.py b/stem/interpretor/commands.py index af1948c..c711ade 100644 --- a/stem/interpretor/commands.py +++ b/stem/interpretor/commands.py @@ -47,6 +47,7 @@ SIGNAL_DESCRIPTIONS = ( HELP_OPTIONS = { 'HELP': ("/help [OPTION]", 'help.help'), + 'EVENTS': ("/events [types]", 'help.events'), 'QUIT': ("/quit", 'help.quit'), 'GETINFO': ("GETINFO OPTION", 'help.getinfo'), 'GETCONF': ("GETCONF OPTION", 'help.getconf'), @@ -196,6 +197,14 @@ class ControlInterpretor(object): def __init__(self, controller): self.controller = controller + self.received_events = [] + + def register_event(self, event): + """ + Adds the event to our buffer so it'll be in '/events' output. + """ + + self.received_events.append(event) def do_help(self, arg): """ @@ -317,6 +326,21 @@ class ControlInterpretor(object): return output + def do_events(self, arg): + """ + Performs the '/events' operation, dumping the events that we've received + belonging to the given types. If no types are specified then this provides + all buffered events. + """ + + events = self.received_events + event_types = arg.upper().split() + + if event_types: + events = filter(lambda event: event.type in event_types, events) + + return '\n'.join([format(str(event), *OUTPUT_FORMAT) for event in events]) + def run_command(self, command): """ Runs the given command. Requests starting with a '/' are special commands @@ -356,6 +380,8 @@ class ControlInterpretor(object): if cmd.startswith('/'): if cmd == "/quit": raise stem.SocketClosed() + elif cmd == "/events": + output = self.do_events(arg) elif cmd == "/help": output = self.do_help(arg) else: @@ -411,7 +437,21 @@ class ControlInterpretor(object): except stem.ControllerError as exc: output = format(str(exc), *ERROR_FORMAT) elif cmd == 'SETEVENTS': - pass # TODO: implement + try: + # first discontinue listening to prior events + + self.controller.remove_event_listener(self.register_event) + + # attach listeners for the given group of events + + if arg: + events = arg.split() + self.controller.add_event_listener(self.register_event, *events) + output = format('Listing for %s events\n' % ', '.join(events), *OUTPUT_FORMAT) + else: + output = format('Disabled event listening\n', *OUTPUT_FORMAT) + except stem.ControllerError as exc: + output = format(str(exc), *ERROR_FORMAT) elif cmd.replace('+', '') in ('LOADCONF', 'POSTDESCRIPTOR'): # provides a notice that multi-line controller input isn't yet implemented output = format(msg('msg.multiline_unimplemented_notice'), *ERROR_FORMAT) diff --git a/stem/interpretor/settings.cfg b/stem/interpretor/settings.cfg index 9cd2201..e93b0e8 100644 --- a/stem/interpretor/settings.cfg +++ b/stem/interpretor/settings.cfg @@ -15,6 +15,7 @@ help.takeownership Instructs Tor to gracefully shut down when this control conne help.general |Interpretor commands include: | /help - provides information for interpretor and tor commands/config options +| /events - prints events that we've received | /quit - shuts down the interpretor | |Tor commands include: @@ -48,6 +49,11 @@ help.help |Example: | /help GETINFO # usage information for tor's GETINFO controller option +help.events +|Provides events that we've received belonging to the given event types. If +|no types are specified then this provides all the messages that we've +|received. + help.getinfo |Queries the tor process for information. Options are... |

1 0

[stem/master] Adding a @uses_settings to our config module
by atagar＠torproject.org 06 May '14

06 May '14

commit fb65766f1e74cf3218efa9889a5479a13ba70ca4 Author: Damian Johnson <atagar(a)torproject.org> Date: Fri Apr 18 10:29:22 2014 -0700 Adding a @uses_settings to our config module The @uses_settings helper our interpretor panel uses is actually a nice way of taking advantage of our config module. Moving the helper to our util so others can use it. --- stem/interpretor/__init__.py | 48 +++++++----------------------------------- stem/util/conf.py | 44 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 52 insertions(+), 40 deletions(-) diff --git a/stem/interpretor/__init__.py b/stem/interpretor/__init__.py index f1da5d9..93e4e6a 100644 --- a/stem/interpretor/__init__.py +++ b/stem/interpretor/__init__.py @@ -26,6 +26,14 @@ from stem.util.term import RESET, Attr, Color, format PROMPT = format(">>> ", Color.GREEN, Attr.BOLD) + RESET * 10 +settings_path = os.path.join(os.path.dirname(__file__), 'settings.cfg') +uses_settings = stem.util.conf.uses_settings('stem_interpretor', settings_path) + + +@uses_settings +def msg(config, message, **attr): + return config.get(message).format(**attr) + def main(): import readline @@ -70,43 +78,3 @@ def main(): except (KeyboardInterrupt, EOFError, stem.SocketClosed) as exc: print # move cursor to the following line break - - -def uses_settings(func): - """ - Loads our interpretor's internal settings. This should be treated as a fatal - failure if unsuccessful. - - :raises: **IOError** if we're unable to read or parse our internal - configurations - """ - - config = stem.util.conf.get_config('stem_interpretor') - - if not config.get('settings_loaded', False): - settings_path = os.path.join(os.path.dirname(__file__), 'settings.cfg') - config.load(settings_path) - config.set('settings_loaded', 'true') - - return func - - -@uses_settings -def msg(message, **attr): - """ - Provides the given message. - - :param str message: message handle - :param dict attr: values to insert into the message - - :returns: **str** that was requested - - :raises: **ValueError** if string key doesn't exist - """ - - config = stem.util.conf.get_config('stem_interpretor') - - try: - return config.get(message).format(**attr) - except: - raise ValueError('We attempted to use an undefined string resource (%s)' % message) diff --git a/stem/util/conf.py b/stem/util/conf.py index c11adf2..3f753f0 100644 --- a/stem/util/conf.py +++ b/stem/util/conf.py @@ -141,6 +141,7 @@ Here's an expanation of what happened... config_dict - provides a dictionary that's kept in sync with our config get_config - singleton for getting configurations + uses_settings - provides an annotation for functions that use configurations parse_enum_csv - helper funcion for parsing confguration entries for enums Config - Custom configuration @@ -156,6 +157,7 @@ Here's an expanation of what happened... +- get_value - provides the value for a given key as a string """ +import functools import threading from stem.util import log @@ -233,6 +235,48 @@ def get_config(handle): return CONFS[handle] +def uses_settings(handle, path, lazy_load = True): + """ + Provides a function that can be used as an annotation for other functions + that require settings to be loaded. Functions with this annotation will be + provided with the configuration as its first argument. + + :: + + uses_settings = stem.util.conf.uses_settings('my_app', '/path/to/settings.cfg') + + @uses_settings + def my_function(config): + print 'hello %s!' % config.get('username', '') + + :param str handle: hande for the configuration + :param str path: path where the configuration should be loaded from + :param bool lazy_load: loads the configuration file when the annotation is + used if true, otherwise it's loaded right away + + :returns: **function** that can be used as an annotation to provide the + configuration + + :raises: **IOError** if we fail to read the configuration file, if + **lazy_load** is true then this arises when we use the annotation + """ + + config = get_config(handle) + + if not lazy_load and not config.get('settings_loaded', False): + config.load(path) + config.set('settings_loaded', 'true') + + def annotation(func): + if lazy_load and not config.get('settings_loaded', False): + config.load(path) + config.set('settings_loaded', 'true') + + return functools.partial(func, config) + + return annotation + + def parse_enum(key, value, enumeration): """ Provides the enumeration value for a given key. This is a case insensitive

1 0

[stem/master] Supporting the /info option
by atagar＠torproject.org 06 May '14

06 May '14

commit ca331a6fba5ead083c4a010b72e5d4886396e7a1 Author: Damian Johnson <atagar(a)torproject.org> Date: Wed Apr 16 10:15:18 2014 -0700 Supporting the /info option Adding support for a /info option that provides a simple summary of a relay's information. This accepts a fingerprint, nickname, or IP address. If there's a match this provides basic information in a similar fashion to arm. --- stem/interpretor/commands.py | 132 ++++++++++++++++++++++++++++++++++++++++- stem/interpretor/settings.cfg | 6 ++ 2 files changed, 135 insertions(+), 3 deletions(-) diff --git a/stem/interpretor/commands.py b/stem/interpretor/commands.py index c711ade..2d2d0a5 100644 --- a/stem/interpretor/commands.py +++ b/stem/interpretor/commands.py @@ -6,8 +6,10 @@ import os import re import stem +import stem.util.connection import stem.util.conf import stem.util.log +import stem.util.tor_tools from stem.util.term import Attr, Color, format @@ -48,6 +50,7 @@ SIGNAL_DESCRIPTIONS = ( HELP_OPTIONS = { 'HELP': ("/help [OPTION]", 'help.help'), 'EVENTS': ("/events [types]", 'help.events'), + 'INFO': ("/info [relay fingerprint, nickname, or IP address]", 'help.info'), 'QUIT': ("/quit", 'help.quit'), 'GETINFO': ("GETINFO OPTION", 'help.getinfo'), 'GETCONF': ("GETCONF OPTION", 'help.getconf'), @@ -341,6 +344,127 @@ class ControlInterpretor(object): return '\n'.join([format(str(event), *OUTPUT_FORMAT) for event in events]) + def do_info(self, arg): + """ + Performs the '/info' operation, looking up a relay by fingerprint, IP + address, or nickname and printing its descriptor and consensus entries in a + pretty fashion. + """ + + output, fingerprint = '', None + + # determines the fingerprint, leaving it unset and adding an error message + # if unsuccessful + + if not arg: + # uses our fingerprint if we're a relay, otherwise gives an error + + fingerprint = self.controller.get_info('fingerprint', None) + + if not fingerprint: + output += format("We aren't a relay, no information to provide", *ERROR_FORMAT) + elif stem.util.tor_tools.is_valid_fingerprint(arg): + fingerprint = arg + elif stem.util.tor_tools.is_valid_nickname(arg): + desc = self.controller.get_network_status(arg, None) + + if desc: + fingerprint = desc.fingerprint + else: + return format("Unable to find a relay with the nickname of '%s'" % arg, *ERROR_FORMAT) + elif ':' in arg or stem.util.connection.is_valid_ipv4_address(arg): + # we got an address, so looking up the fingerprint + + if ':' in arg: + address, port = arg.split(':', 1) + + if not stem.util.connection.is_valid_ipv4_address(address): + return format("'%s' isn't a valid IPv4 address" % address, *ERROR_FORMAT) + elif port and not stem.util.connection.is_valid_port(port): + return format("'%s' isn't a valid port" % port, *ERROR_FORMAT) + + port = int(port) + else: + address, port = arg, None + + matches = {} + + for desc in self.controller.get_network_statuses(): + if desc.address == address: + if not port or desc.or_port == port: + matches[desc.or_port] = desc.fingerprint + + if len(matches) == 0: + output += format('No relays found at %s' % arg, *ERROR_FORMAT) + elif len(matches) == 1: + fingerprint = matches.values()[0] + else: + output += format("There's multiple relays at %s, include a port to specify which.\n\n" % arg, *ERROR_FORMAT) + + for i, or_port in enumerate(matches): + output += format(" %i. %s:%s, fingerprint: %s\n" % (i + 1, address, or_port, matches[or_port]), *ERROR_FORMAT) + else: + return format("'%s' isn't a fingerprint, nickname, or IP address" % arg, *ERROR_FORMAT) + + if fingerprint: + micro_desc = self.controller.get_microdescriptor(fingerprint, None) + server_desc = self.controller.get_server_descriptor(fingerprint, None) + ns_desc = self.controller.get_network_status(fingerprint, None) + + # We'll mostly rely on the router status entry. Either the server + # descriptor or microdescriptor will be missing, so we'll treat them as + # being optional. + + if not ns_desc: + return format("Unable to find consensus information for %s" % fingerprint, *ERROR_FORMAT) + + locale = self.controller.get_info('ip-to-country/%s' % ns_desc.address, None) + locale_label = ' (%s)' % locale if locale else '' + + if server_desc: + exit_policy_label = server_desc.exit_policy.summary() + elif micro_desc: + exit_policy_label = micro_desc.exit_policy.summary() + else: + exit_policy_label = 'Unknown' + + output += '%s (%s)\n' % (ns_desc.nickname, fingerprint) + + output += format('address: ', *BOLD_OUTPUT_FORMAT) + output += '%s:%s%s\n' % (ns_desc.address, ns_desc.or_port, locale_label) + + output += format('published: ', *BOLD_OUTPUT_FORMAT) + output += ns_desc.published.strftime('%H:%M:%S %d/%m/%Y') + '\n' + + if server_desc: + output += format('os: ', *BOLD_OUTPUT_FORMAT) + output += server_desc.platform.decode('utf-8', 'replace') + '\n' + + output += format('version: ', *BOLD_OUTPUT_FORMAT) + output += str(server_desc.tor_version) + '\n' + + output += format('flags: ', *BOLD_OUTPUT_FORMAT) + output += ', '.join(ns_desc.flags) + '\n' + + output += format('exit policy: ', *BOLD_OUTPUT_FORMAT) + output += exit_policy_label + '\n' + + if server_desc: + contact = server_desc.contact + + # clears up some highly common obscuring + + for alias in (' at ', ' AT '): + contact = contact.replace(alias, '@') + + for alias in (' dot ', ' DOT '): + contact = contact.replace(alias, '.') + + output += format('contact: ', *BOLD_OUTPUT_FORMAT) + output += contact + '\n' + + return output.strip() + def run_command(self, command): """ Runs the given command. Requests starting with a '/' are special commands @@ -378,11 +502,13 @@ class ControlInterpretor(object): output = '' if cmd.startswith('/'): - if cmd == "/quit": + if cmd == '/quit': raise stem.SocketClosed() - elif cmd == "/events": + elif cmd == '/events': output = self.do_events(arg) - elif cmd == "/help": + elif cmd == '/info': + output = self.do_info(arg) + elif cmd == '/help': output = self.do_help(arg) else: output = format("'%s' isn't a recognized command" % command, *ERROR_FORMAT) diff --git a/stem/interpretor/settings.cfg b/stem/interpretor/settings.cfg index e93b0e8..9430748 100644 --- a/stem/interpretor/settings.cfg +++ b/stem/interpretor/settings.cfg @@ -16,6 +16,7 @@ help.general |Interpretor commands include: | /help - provides information for interpretor and tor commands/config options | /events - prints events that we've received +| /info - general information for a relay | /quit - shuts down the interpretor | |Tor commands include: @@ -47,6 +48,7 @@ help.help |configuration option. | |Example: +| /help info # provides a description of the '/info' option | /help GETINFO # usage information for tor's GETINFO controller option help.events @@ -54,6 +56,10 @@ help.events |no types are specified then this provides all the messages that we've |received. +help.info +|Provides general information for a relay that's currently in the consensus. +|If no relay is specified then this provides information on ourselves. + help.getinfo |Queries the tor process for information. Options are... |

1 0

[stem/master] Moving msg() helper to base module
by atagar＠torproject.org 06 May '14

06 May '14

commit 407f9537cb0de0ec3c1cf1423b74e16f42abe7f0 Author: Damian Johnson <atagar(a)torproject.org> Date: Thu Apr 17 09:12:08 2014 -0700 Moving msg() helper to base module We'll want our msg() function outside of the commands module so moving it to __init__.py. --- stem/interpretor/__init__.py | 49 +++++++++++++++++++++++++++++++++++++++--- stem/interpretor/commands.py | 43 +----------------------------------- 2 files changed, 47 insertions(+), 45 deletions(-) diff --git a/stem/interpretor/__init__.py b/stem/interpretor/__init__.py index d1a5359..c8cd513 100644 --- a/stem/interpretor/__init__.py +++ b/stem/interpretor/__init__.py @@ -6,15 +6,16 @@ Interactive interpretor for interacting with Tor directly. This adds usability features such as tab completion, history, and IRC-style functions (like /help). """ -__all__ = ['arguments'] +__all__ = ['arguments', 'commands', 'msg'] +import os import sys import stem import stem.connection -import stem.interpretor.arguments -import stem.interpretor.commands import stem.prereq +import stem.util.conf +import stem.util.log from stem.util.term import Attr, Color, format @@ -31,6 +32,9 @@ else: def main(): import readline + import stem.interpretor.arguments + import stem.interpretor.commands + try: args = stem.interpretor.arguments.parse(sys.argv[1:]) except ValueError as exc: @@ -68,3 +72,42 @@ def main(): except (KeyboardInterrupt, EOFError, stem.SocketClosed) as exc: print # move cursor to the following line break + + +def uses_settings(func): + """ + Loads our interpretor's internal settings. This should be treated as a fatal + failure if unsuccessful. + + :raises: **IOError** if we're unable to read or parse our internal + configurations + """ + + config = stem.util.conf.get_config('stem_interpretor') + + if not config.get('settings_loaded', False): + settings_path = os.path.join(os.path.dirname(__file__), 'settings.cfg') + config.load(settings_path) + config.set('settings_loaded', 'true') + + return func + + +@uses_settings +def msg(message, **attr): + """ + Provides the given message. + + :param str message: message handle + :param dict attr: attributes to format the message with + + :returns: **str** that was requested + """ + + config = stem.util.conf.get_config('stem_interpretor') + + try: + return config.get(message).format(**attr) + except: + stem.util.log.notice('BUG: We attempted to use an undefined string resource (%s)' % message) + return '' diff --git a/stem/interpretor/commands.py b/stem/interpretor/commands.py index 2d2d0a5..a4ab317 100644 --- a/stem/interpretor/commands.py +++ b/stem/interpretor/commands.py @@ -2,15 +2,13 @@ Handles making requests and formatting the responses. """ -import os import re import stem import stem.util.connection -import stem.util.conf -import stem.util.log import stem.util.tor_tools +from stem.interpretor import msg from stem.util.term import Attr, Color, format OUTPUT_FORMAT = (Color.BLUE, ) @@ -75,25 +73,6 @@ HELP_OPTIONS = { } -def uses_settings(func): - """ - Loads our interpretor's internal settings. This should be treated as a fatal - failure if unsuccessful. - - :raises: **IOError** if we're unable to read or parse our internal - configurations - """ - - config = stem.util.conf.get_config('stem_interpretor') - - if not config.get('settings_loaded', False): - settings_path = os.path.join(os.path.dirname(__file__), 'settings.cfg') - config.load(settings_path) - config.set('settings_loaded', 'true') - - return func - - def _get_commands(controller): """ Provides commands recognized by tor. @@ -596,23 +575,3 @@ class ControlInterpretor(object): output = format(str(exc), *ERROR_FORMAT) return output - - -@uses_settings -def msg(message, **attr): - """ - Provides the given message. - - :param str message: message handle - :param dict attr: attributes to format the message with - - :returns: **str** that was requested - """ - - config = stem.util.conf.get_config('stem_interpretor') - - try: - return config.get(message).format(**attr) - except: - stem.util.log.notice('BUG: We attempted to use an undefined string resource (%s)' % message) - return ''

1 0

[stem/master] Readline history can screw up the prompt
by atagar＠torproject.org 06 May '14

06 May '14

commit 6945b02706ca7c49bb75447ebc05a6721ae15759 Author: Damian Johnson <atagar(a)torproject.org> Date: Thu Apr 17 09:53:36 2014 -0700 Readline history can screw up the prompt Something between raw_input() and readline history has a bug for color prompts like ours. Certain histories cause our prompt to be widened. Widening our initial prompt with invisiable characters (like resets) seems to mitigate this. And yes, this is quite a hack. :( Steps to repro for python 2.7.1... 1. Start prompt. 2. Type "/help GETINFO version". 3. Press 'up' to render that command. Your prompt should now look screwed up. 4. Press 'down' to return to what should be a blank prompt. You'll still be offset several characters to the right. --- stem/interpretor/__init__.py | 13 ++++++------- stem/interpretor/arguments.py | 3 ++- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/stem/interpretor/__init__.py b/stem/interpretor/__init__.py index 3dce2a0..f1da5d9 100644 --- a/stem/interpretor/__init__.py +++ b/stem/interpretor/__init__.py @@ -13,19 +13,18 @@ import sys import stem import stem.connection -import stem.prereq import stem.util.conf -from stem.util.term import Attr, Color, format +from stem.util.term import RESET, Attr, Color, format -# We can only present a color prompt with python 2.7 or later... +# Our color prompt triggers a bug between raw_input() and readline history, +# where scrolling through history widens our prompt. Widening our prompt via +# invisible characters (like resets) seems to sidestep this bug for short +# inputs. Contrary to the ticket, this still manifests with python 2.7.1... # # http://bugs.python.org/issue12972 -if stem.prereq.is_python_27(): - PROMPT = format(">>> ", Color.GREEN, Attr.BOLD) -else: - PROMPT = ">>> " +PROMPT = format(">>> ", Color.GREEN, Attr.BOLD) + RESET * 10 def main(): diff --git a/stem/interpretor/arguments.py b/stem/interpretor/arguments.py index ff25fb7..c2971b0 100644 --- a/stem/interpretor/arguments.py +++ b/stem/interpretor/arguments.py @@ -84,7 +84,8 @@ def get_help(): :returns: **str** with our usage information """ - return stem.interpretor.msg('msg.help', + return stem.interpretor.msg( + 'msg.help', address = DEFAULT_ARGS['control_address'], port = DEFAULT_ARGS['control_port'], socket = DEFAULT_ARGS['control_socket'],

1 0

[stem/master] Moving --help output to configuration
by atagar＠torproject.org 06 May '14

06 May '14

commit 216a6072ccc5506ac7c00acc6ef618e531d42a23 Author: Damian Johnson <atagar(a)torproject.org> Date: Thu Apr 17 09:27:28 2014 -0700 Moving --help output to configuration It wasn't worth having a config file for just this one string, but now that we have one anyway we might as well use it. This also changes msg() to raise a ValueError so it's less likely that errors where we fail to fetch string resources will go unnoticed. --- stem/interpretor/__init__.py | 8 ++++---- stem/interpretor/arguments.py | 17 ++--------------- stem/interpretor/settings.cfg | 13 +++++++++++++ 3 files changed, 19 insertions(+), 19 deletions(-) diff --git a/stem/interpretor/__init__.py b/stem/interpretor/__init__.py index c8cd513..3dce2a0 100644 --- a/stem/interpretor/__init__.py +++ b/stem/interpretor/__init__.py @@ -15,7 +15,6 @@ import stem import stem.connection import stem.prereq import stem.util.conf -import stem.util.log from stem.util.term import Attr, Color, format @@ -99,9 +98,11 @@ def msg(message, **attr): Provides the given message. :param str message: message handle - :param dict attr: attributes to format the message with + :param dict attr: values to insert into the message :returns: **str** that was requested + + :raises: **ValueError** if string key doesn't exist """ config = stem.util.conf.get_config('stem_interpretor') @@ -109,5 +110,4 @@ def msg(message, **attr): try: return config.get(message).format(**attr) except: - stem.util.log.notice('BUG: We attempted to use an undefined string resource (%s)' % message) - return '' + raise ValueError('We attempted to use an undefined string resource (%s)' % message) diff --git a/stem/interpretor/arguments.py b/stem/interpretor/arguments.py index bd6655d..ff25fb7 100644 --- a/stem/interpretor/arguments.py +++ b/stem/interpretor/arguments.py @@ -8,6 +8,7 @@ Commandline argument parsing for arm. import collections import getopt +import stem.interpretor import stem.util.connection DEFAULT_ARGS = { @@ -27,20 +28,6 @@ OPT_EXPANDED = [ 'help', ] -HELP_OUTPUT = """ -Usage prompt [OPTION] -Interactive interpretor for Tor. - - -i, --interface [ADDRESS:]PORT change control interface from {address}:{port} - -s, --socket SOCKET_PATH attach using unix domain socket if present, - SOCKET_PATH defaults to: {socket} - -h, --help presents this help - -Example: -prompt -i 1643 attach to control port 1643 -prompt -s ~/.tor/socket attach to a control socket in your home directory -""" - def parse(argv): """ @@ -97,7 +84,7 @@ def get_help(): :returns: **str** with our usage information """ - return HELP_OUTPUT.format( + return stem.interpretor.msg('msg.help', address = DEFAULT_ARGS['control_address'], port = DEFAULT_ARGS['control_port'], socket = DEFAULT_ARGS['control_socket'], diff --git a/stem/interpretor/settings.cfg b/stem/interpretor/settings.cfg index 9430748..bb67144 100644 --- a/stem/interpretor/settings.cfg +++ b/stem/interpretor/settings.cfg @@ -6,6 +6,19 @@ msg.multiline_unimplemented_notice Multi-line control options like this are not yet implemented. +msg.help +|Usage prompt [OPTION] +|Interactive interpretor for Tor. +| +| -i, --interface [ADDRESS:]PORT change control interface from {address}:{port} +| -s, --socket SOCKET_PATH attach using unix domain socket if present, +| SOCKET_PATH defaults to: {socket} +| -h, --help presents this help +| +|Example: +|prompt -i 1643 attach to control port 1643 +|prompt -s ~/.tor/socket attach to a control socket in your home directory + help.quit Terminates the interpretor. help.saveconf Writes Tor's current configuration to its torrc. help.postdescriptor Simulates getting a new relay descriptor.

1 0

[stem/master] Unit tests for interpretor argument parsing
by atagar＠torproject.org 06 May '14

06 May '14

commit 0e5cf58a99fe0adec83e06e918cf896019411480 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Apr 19 09:12:16 2014 -0700 Unit tests for interpretor argument parsing Few simple tests for our argument handling, adapted from arm. --- stem/interpretor/arguments.py | 2 +- test/settings.cfg | 1 + test/unit/interpretor/__init__.py | 7 +++++ test/unit/interpretor/arguments.py | 57 ++++++++++++++++++++++++++++++++++++ 4 files changed, 66 insertions(+), 1 deletion(-) diff --git a/stem/interpretor/arguments.py b/stem/interpretor/arguments.py index c2971b0..733da27 100644 --- a/stem/interpretor/arguments.py +++ b/stem/interpretor/arguments.py @@ -2,7 +2,7 @@ # See LICENSE for licensing information """ -Commandline argument parsing for arm. +Commandline argument parsing for our interpretor prompt. """ import collections diff --git a/test/settings.cfg b/test/settings.cfg index f0eb758..684d40a 100644 --- a/test/settings.cfg +++ b/test/settings.cfg @@ -183,6 +183,7 @@ test.unit_tests |test.unit.connection.authentication.TestAuthenticate |test.unit.connection.connect.TestConnect |test.unit.control.controller.TestControl +|test.unit.interpretor.arguments.TestArgumentParsing |test.unit.doctest.TestDocumentation test.integ_tests diff --git a/test/unit/interpretor/__init__.py b/test/unit/interpretor/__init__.py new file mode 100644 index 0000000..e2ad715 --- /dev/null +++ b/test/unit/interpretor/__init__.py @@ -0,0 +1,7 @@ +""" +Unit tests for the stem's interpretor prompt. +""" + +__all__ = [ + "arguments", +] diff --git a/test/unit/interpretor/arguments.py b/test/unit/interpretor/arguments.py new file mode 100644 index 0000000..ab835c4 --- /dev/null +++ b/test/unit/interpretor/arguments.py @@ -0,0 +1,57 @@ +import unittest + +from stem.interpretor.arguments import DEFAULT_ARGS, parse, get_help + + +class TestArgumentParsing(unittest.TestCase): + def test_that_we_get_default_values(self): + args = parse([]) + + for attr in DEFAULT_ARGS: + self.assertEqual(DEFAULT_ARGS[attr], getattr(args, attr)) + + def test_that_we_load_arguments(self): + args = parse(['--interface', '10.0.0.25:80']) + self.assertEqual('10.0.0.25', args.control_address) + self.assertEqual(80, args.control_port) + + args = parse(['--interface', '80']) + self.assertEqual(DEFAULT_ARGS['control_address'], args.control_address) + self.assertEqual(80, args.control_port) + + args = parse(['--socket', '/tmp/my_socket']) + self.assertEqual('/tmp/my_socket', args.control_socket) + + args = parse(['--help']) + self.assertEqual(True, args.print_help) + + def test_examples(self): + args = parse(['-i', '1643']) + self.assertEqual(1643, args.control_port) + + args = parse(['-s', '~/.tor/socket']) + self.assertEqual('~/.tor/socket', args.control_socket) + + def test_that_we_reject_unrecognized_arguments(self): + self.assertRaises(ValueError, parse, ['--blarg', 'stuff']) + + def test_that_we_reject_invalid_interfaces(self): + invalid_inputs = ( + '', + ' ', + 'blarg', + '127.0.0.1', + '127.0.0.1:', + ':80', + '400.0.0.1:80', + '127.0.0.1:-5', + '127.0.0.1:500000', + ) + + for invalid_input in invalid_inputs: + self.assertRaises(ValueError, parse, ['--interface', invalid_input]) + + def test_get_help(self): + help_text = get_help() + self.assertTrue('Interactive interpretor for Tor.' in help_text) + self.assertTrue('change control interface from 127.0.0.1:9051' in help_text)

1 0

[stem/master] Moving base autocompletion commands to config
by atagar＠torproject.org 06 May '14

06 May '14

commit 6ab77cb951c927a899ec80d1afde596bb9226fbd Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Apr 19 12:03:31 2014 -0700 Moving base autocompletion commands to config Perfect thing to get out of our source. :) --- stem/interpretor/__init__.py | 6 +++--- stem/interpretor/commands.py | 27 ++++----------------------- stem/interpretor/settings.cfg | 21 +++++++++++++++++++++ 3 files changed, 28 insertions(+), 26 deletions(-) diff --git a/stem/interpretor/__init__.py b/stem/interpretor/__init__.py index 93e4e6a..59c89c8 100644 --- a/stem/interpretor/__init__.py +++ b/stem/interpretor/__init__.py @@ -64,9 +64,9 @@ def main(): sys.exit(1) with controller: - tab_completer = stem.interpretor.commands.Autocomplete(controller) - readline.parse_and_bind("tab: complete") - readline.set_completer(tab_completer.complete) + autocomplete = stem.interpretor.commands.Autocomplete(controller) + readline.parse_and_bind('tab: complete') + readline.set_completer(autocomplete.complete) readline.set_completer_delims('\n') interpretor = stem.interpretor.commands.ControlInterpretor(controller) diff --git a/stem/interpretor/commands.py b/stem/interpretor/commands.py index a4ab317..4b35955 100644 --- a/stem/interpretor/commands.py +++ b/stem/interpretor/commands.py @@ -8,33 +8,13 @@ import stem import stem.util.connection import stem.util.tor_tools -from stem.interpretor import msg +from stem.interpretor import msg, uses_settings from stem.util.term import Attr, Color, format OUTPUT_FORMAT = (Color.BLUE, ) BOLD_OUTPUT_FORMAT = (Color.BLUE, Attr.BOLD) ERROR_FORMAT = (Attr.BOLD, Color.RED) -TOR_CONTROLLER_COMMANDS = [ - 'SAVECONF', - 'MAPADDRESS', - 'EXTENDCIRCUIT', - 'SETCIRCUITPURPOSE', - 'SETROUTERPURPOSE', - 'ATTACHSTREAM', - #'+POSTDESCRIPTOR', # TODO: needs multi-line support - 'REDIRECTSTREAM', - 'CLOSESTREAM', - 'CLOSECIRCUIT', - 'QUIT', - 'RESOLVE', - 'PROTOCOLINFO', - #'+LOADCONF', # TODO: needs multi-line support - 'TAKEOWNERSHIP', - 'AUTHCHALLENGE', - 'DROPGUARDS', -] - SIGNAL_DESCRIPTIONS = ( ("RELOAD / HUP", "reload our torrc"), ("SHUTDOWN / INT", "gracefully shut down, waiting 30 seconds if we're a relay"), @@ -73,12 +53,13 @@ HELP_OPTIONS = { } -def _get_commands(controller): +@uses_settings +def _get_commands(config, controller): """ Provides commands recognized by tor. """ - commands = list(TOR_CONTROLLER_COMMANDS) + commands = config.get('autocomplete', []) # GETINFO commands diff --git a/stem/interpretor/settings.cfg b/stem/interpretor/settings.cfg index bb67144..da33dbc 100644 --- a/stem/interpretor/settings.cfg +++ b/stem/interpretor/settings.cfg @@ -171,3 +171,24 @@ help.protocolinfo |starting, like Tor's version and controller authentication. This can be done |before authenticating to the control port. +# Autocompletion commands. We dynamically load more, such as GETINFO and +# GETCONF options tor will recognize so this just includes other base commands. + +autocomplete SAVECONF +autocomplete MAPADDRESS +autocomplete EXTENDCIRCUIT +autocomplete SETCIRCUITPURPOSE +autocomplete SETROUTERPURPOSE +autocomplete ATTACHSTREAM +#autocomplete +POSTDESCRIPTOR # TODO: needs multi-line support +autocomplete REDIRECTSTREAM +autocomplete CLOSESTREAM +autocomplete CLOSECIRCUIT +autocomplete QUIT +autocomplete RESOLVE +autocomplete PROTOCOLINFO +#autocomplete +LOADCONF # TODO: needs multi-line support +autocomplete TAKEOWNERSHIP +autocomplete AUTHCHALLENGE +autocomplete DROPGUARDS +

1 0

[stem/master] Caching autocompletion matches
by atagar＠torproject.org 06 May '14

06 May '14

commit 71028da33515673c7f5df55b46e2235833741352 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Apr 19 17:00:16 2014 -0700 Caching autocompletion matches Readline's autocompletion is kinda weird. It uses a function of the form... matches(text, state) ... where the state is the index of the match to be returned. This is probably to match the underlying C readline funcion (ahhh, the world before dynamically allocated lists). Considering that we're calling the match function N+1 times where N is the number of autocompletion matches we might as well cache the results. The autocompleter should have a match function that returns a list of matches anyway. --- stem/interpretor/autocomplete.py | 35 +++++++++++++++++++++++++++++------ 1 file changed, 29 insertions(+), 6 deletions(-) diff --git a/stem/interpretor/autocomplete.py b/stem/interpretor/autocomplete.py index 09c5365..ff61941 100644 --- a/stem/interpretor/autocomplete.py +++ b/stem/interpretor/autocomplete.py @@ -4,6 +4,12 @@ Tab completion for our interpretor prompt. from stem.interpretor import uses_settings +try: + # added in python 3.2 + from functools import lru_cache +except ImportError: + from stem.util.lru_cache import lru_cache + @uses_settings def _get_commands(config, controller): @@ -83,16 +89,33 @@ class Autocompleter(object): def __init__(self, controller): self._commands = _get_commands(controller) + @lru_cache() + def matches(self, text): + """ + Provides autocompletion matches for the given text. + + :param str text: text to check for autocompletion matches with + + :returns: **list** with possible matches + """ + + lowercase_text = text.lower() + return [cmd for cmd in self._commands if cmd.lower().startswith(lowercase_text)] + def complete(self, text, state): """ Provides case insensetive autocompletion options, acting as a functor for the readlines set_completer function. - """ - lowercase_text = text.lower() - prefix_matches = [cmd for cmd in self._commands if cmd.lower().startswith(lowercase_text)] + :param str text: text to check for autocompletion matches with + :param int state: index of result to be provided, readline fetches matches + until this function provides None + + :returns: **str** with the autocompletion match, **None** if eithe none + exists or state is higher than our number of matches + """ - if state < len(prefix_matches): - return prefix_matches[state] - else: + try: + return self.matches(text)[state] + except IndexError: return None

1 0

[stem/master] Moving autocompletion to its own module
by atagar＠torproject.org 06 May '14

06 May '14

commit 278994377919bef35dcf6fef604d7bf5ef3be6da Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Apr 19 16:23:01 2014 -0700 Moving autocompletion to its own module I bundled autocompletion with commands.py because it used one of its globals. However, we've since dropped those bits so this can be nicely moved back to its own file. --- stem/interpretor/__init__.py | 7 +-- stem/interpretor/autocomplete.py | 98 ++++++++++++++++++++++++++++++++++++++ stem/interpretor/commands.py | 93 ------------------------------------ 3 files changed, 102 insertions(+), 96 deletions(-) diff --git a/stem/interpretor/__init__.py b/stem/interpretor/__init__.py index 59c89c8..5e03c2c 100644 --- a/stem/interpretor/__init__.py +++ b/stem/interpretor/__init__.py @@ -6,7 +6,7 @@ Interactive interpretor for interacting with Tor directly. This adds usability features such as tab completion, history, and IRC-style functions (like /help). """ -__all__ = ['arguments', 'commands', 'msg'] +__all__ = ['arguments', 'autocomplete', 'commands', 'msg'] import os import sys @@ -39,6 +39,7 @@ def main(): import readline import stem.interpretor.arguments + import stem.interpretor.autocomplete import stem.interpretor.commands try: @@ -64,9 +65,9 @@ def main(): sys.exit(1) with controller: - autocomplete = stem.interpretor.commands.Autocomplete(controller) + autocompleter = stem.interpretor.autocomplete.Autocompleter(controller) readline.parse_and_bind('tab: complete') - readline.set_completer(autocomplete.complete) + readline.set_completer(autocompleter.complete) readline.set_completer_delims('\n') interpretor = stem.interpretor.commands.ControlInterpretor(controller) diff --git a/stem/interpretor/autocomplete.py b/stem/interpretor/autocomplete.py new file mode 100644 index 0000000..09c5365 --- /dev/null +++ b/stem/interpretor/autocomplete.py @@ -0,0 +1,98 @@ +""" +Tab completion for our interpretor prompt. +""" + +from stem.interpretor import uses_settings + + +@uses_settings +def _get_commands(config, controller): + """ + Provides commands recognized by tor. + """ + + commands = config.get('autocomplete', []) + + # GETINFO commands + + getinfo_options = controller.get_info('info/names', None) + + if getinfo_options: + # Lines are of the form '[option] -- [description]'. This strips '*' from + # options that accept values. + + options = [line.split(' ', 1)[0].rstrip('*') for line in getinfo_options.splitlines()] + + commands += ['GETINFO %s' % opt for opt in options] + else: + commands.append('GETINFO ') + + # GETCONF, SETCONF, and RESETCONF commands + + config_options = controller.get_info('config/names', None) + + if config_options: + # individual options are '[option] [type]' pairs + + entries = [opt.split(' ', 1)[0] for opt in config_options.splitlines()] + + commands += ['GETCONF %s' % opt for opt in entries] + commands += ['SETCONF %s ' % opt for opt in entries] + commands += ['RESETCONF %s' % opt for opt in entries] + else: + commands += ['GETCONF ', 'SETCONF ', 'RESETCONF '] + + # SETEVENT commands + + events = controller.get_info('events/names', None) + + if events: + commands += ['SETEVENTS %s' % event for event in events.split(' ')] + else: + commands.append('SETEVENTS ') + + # USEFEATURE commands + + features = controller.get_info('features/names', None) + + if features: + commands += ['USEFEATURE %s' % feature for feature in features.split(' ')] + else: + commands.append('USEFEATURE ') + + # SIGNAL commands + + signals = controller.get_info('signal/names', None) + + if signals: + commands += ['SIGNAL %s' % signal for signal in signals.split(' ')] + else: + commands.append('SIGNAL ') + + # adds help options for the previous commands + + base_cmd = set([cmd.split(' ')[0].replace('+', '').replace('/', '') for cmd in commands]) + + for cmd in base_cmd: + commands.append('/help ' + cmd) + + return commands + + +class Autocompleter(object): + def __init__(self, controller): + self._commands = _get_commands(controller) + + def complete(self, text, state): + """ + Provides case insensetive autocompletion options, acting as a functor for + the readlines set_completer function. + """ + + lowercase_text = text.lower() + prefix_matches = [cmd for cmd in self._commands if cmd.lower().startswith(lowercase_text)] + + if state < len(prefix_matches): + return prefix_matches[state] + else: + return None diff --git a/stem/interpretor/commands.py b/stem/interpretor/commands.py index 833918f..e5b3e97 100644 --- a/stem/interpretor/commands.py +++ b/stem/interpretor/commands.py @@ -16,99 +16,6 @@ BOLD_OUTPUT_FORMAT = (Color.BLUE, Attr.BOLD) ERROR_FORMAT = (Attr.BOLD, Color.RED) -@uses_settings -def _get_commands(config, controller): - """ - Provides commands recognized by tor. - """ - - commands = config.get('autocomplete', []) - - # GETINFO commands - - getinfo_options = controller.get_info('info/names', None) - - if getinfo_options: - # Lines are of the form '[option] -- [description]'. This strips '*' from - # options that accept values. - - options = [line.split(' ', 1)[0].rstrip('*') for line in getinfo_options.splitlines()] - - commands += ['GETINFO %s' % opt for opt in options] - else: - commands.append('GETINFO ') - - # GETCONF, SETCONF, and RESETCONF commands - - config_options = controller.get_info('config/names', None) - - if config_options: - # individual options are '[option] [type]' pairs - - entries = [opt.split(' ', 1)[0] for opt in config_options.splitlines()] - - commands += ['GETCONF %s' % opt for opt in entries] - commands += ['SETCONF %s ' % opt for opt in entries] - commands += ['RESETCONF %s' % opt for opt in entries] - else: - commands += ['GETCONF ', 'SETCONF ', 'RESETCONF '] - - # SETEVENT commands - - events = controller.get_info('events/names', None) - - if events: - commands += ['SETEVENTS %s' % event for event in events.split(' ')] - else: - commands.append('SETEVENTS ') - - # USEFEATURE commands - - features = controller.get_info('features/names', None) - - if features: - commands += ['USEFEATURE %s' % feature for feature in features.split(' ')] - else: - commands.append('USEFEATURE ') - - # SIGNAL commands - - signals = controller.get_info('signal/names', None) - - if signals: - commands += ['SIGNAL %s' % signal for signal in signals.split(' ')] - else: - commands.append('SIGNAL ') - - # adds help options for the previous commands - - base_cmd = set([cmd.split(' ')[0].replace('+', '').replace('/', '') for cmd in commands]) - - for cmd in base_cmd: - commands.append('/help ' + cmd) - - return commands - - -class Autocomplete(object): - def __init__(self, controller): - self._commands = _get_commands(controller) - - def complete(self, text, state): - """ - Provides case insensetive autocompletion options, acting as a functor for - the readlines set_completer function. - """ - - lowercase_text = text.lower() - prefix_matches = [cmd for cmd in self._commands if cmd.lower().startswith(lowercase_text)] - - if state < len(prefix_matches): - return prefix_matches[state] - else: - return None - - class ControlInterpretor(object): """ Handles issuing requests and providing nicely formed responses, with support

1 0