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

[stem/master] Added downloadable tutorial for tutorial Tortoise and the Hare
by atagar＠torproject.org 25 May '15

25 May '15

commit a20733062c11b5d68613ec0c17518fb16229bd0f Author: Sambuddha Basu <sambuddhabasu1(a)gmail.com> Date: Mon May 25 07:34:11 2015 +0400 Added downloadable tutorial for tutorial Tortoise and the Hare --- docs/_static/example/event_listening.py | 177 ++++++++++++++++++++++++++++ docs/tutorials/tortoise_and_the_hare.rst | 184 +----------------------------- 2 files changed, 181 insertions(+), 180 deletions(-) diff --git a/docs/_static/example/event_listening.py b/docs/_static/example/event_listening.py new file mode 100644 index 0000000..2e6f026 --- /dev/null +++ b/docs/_static/example/event_listening.py @@ -0,0 +1,177 @@ +import curses +import functools + +from stem.control import EventType, Controller +from stem.util import str_tools + +# colors that curses can handle + +COLOR_LIST = { + "red": curses.COLOR_RED, + "green": curses.COLOR_GREEN, + "yellow": curses.COLOR_YELLOW, + "blue": curses.COLOR_BLUE, + "cyan": curses.COLOR_CYAN, + "magenta": curses.COLOR_MAGENTA, + "black": curses.COLOR_BLACK, + "white": curses.COLOR_WHITE, +} + +GRAPH_WIDTH = 40 +GRAPH_HEIGHT = 8 + +DOWNLOAD_COLOR = "green" +UPLOAD_COLOR = "blue" + +def main(): + with Controller.from_port(port = 9051) as controller: + controller.authenticate() + + try: + # This makes curses initialize and call draw_bandwidth_graph() with a + # reference to the screen, followed by additional arguments (in this + # case just the controller). + + curses.wrapper(draw_bandwidth_graph, controller) + except KeyboardInterrupt: + pass # the user hit ctrl+c + +def draw_bandwidth_graph(stdscr, controller): + window = Window(stdscr) + + # (downloaded, uploaded) tuples for the last 40 seconds + + bandwidth_rates = [(0, 0)] * GRAPH_WIDTH + + # Making a partial that wraps the window and bandwidth_rates with a function + # for Tor to call when it gets a BW event. This causes the 'window' and + # 'bandwidth_rates' to be provided as the first two arguments whenever + # 'bw_event_handler()' is called. + + bw_event_handler = functools.partial(_handle_bandwidth_event, window, bandwidth_rates) + + # Registering this listener with Tor. Tor reports a BW event each second. + + controller.add_event_listener(bw_event_handler, EventType.BW) + + # Pause the main thread until the user hits any key... and no, don't you dare + # ask where the 'any' key is. :P + + stdscr.getch() + +def _handle_bandwidth_event(window, bandwidth_rates, event): + # callback for when tor provides us with a BW event + + bandwidth_rates.insert(0, (event.read, event.written)) + bandwidth_rates = bandwidth_rates[:GRAPH_WIDTH] # truncate old values + _render_graph(window, bandwidth_rates) + +def _render_graph(window, bandwidth_rates): + window.erase() + + download_rates = [entry[0] for entry in bandwidth_rates] + upload_rates = [entry[1] for entry in bandwidth_rates] + + # show the latest values at the top + + label = "Downloaded (%s/s):" % str_tools.size_label(download_rates[0], 1) + window.addstr(0, 1, label, DOWNLOAD_COLOR, curses.A_BOLD) + + label = "Uploaded (%s/s):" % str_tools.size_label(upload_rates[0], 1) + window.addstr(0, GRAPH_WIDTH + 7, label, UPLOAD_COLOR, curses.A_BOLD) + + # draw the graph bounds in KB + + max_download_rate = max(download_rates) + max_upload_rate = max(upload_rates) + + window.addstr(1, 1, "%4i" % (max_download_rate / 1024), DOWNLOAD_COLOR) + window.addstr(GRAPH_HEIGHT, 1, " 0", DOWNLOAD_COLOR) + + window.addstr(1, GRAPH_WIDTH + 7, "%4i" % (max_upload_rate / 1024), UPLOAD_COLOR) + window.addstr(GRAPH_HEIGHT, GRAPH_WIDTH + 7, " 0", UPLOAD_COLOR) + + # draw the graph + + for col in xrange(GRAPH_WIDTH): + col_height = GRAPH_HEIGHT * download_rates[col] / max(max_download_rate, 1) + + for row in xrange(col_height): + window.addstr(GRAPH_HEIGHT - row, col + 6, " ", DOWNLOAD_COLOR, curses.A_STANDOUT) + + col_height = GRAPH_HEIGHT * upload_rates[col] / max(max_upload_rate, 1) + + for row in xrange(col_height): + window.addstr(GRAPH_HEIGHT - row, col + GRAPH_WIDTH + 12, " ", UPLOAD_COLOR, curses.A_STANDOUT) + + window.refresh() + +class Window(object): + """ + Simple wrapper for the curses standard screen object. + """ + + def __init__(self, stdscr): + self._stdscr = stdscr + + # Mappings of names to the curses color attribute. Initially these all + # reference black text, but if the terminal can handle color then + # they're set with that foreground color. + + self._colors = dict([(color, 0) for color in COLOR_LIST]) + + # allows for background transparency + + try: + curses.use_default_colors() + except curses.error: + pass + + # makes the cursor invisible + + try: + curses.curs_set(0) + except curses.error: + pass + + # initializes colors if the terminal can handle them + + try: + if curses.has_colors(): + color_pair = 1 + + for name, foreground in COLOR_LIST.items(): + background = -1 # allows for default (possibly transparent) background + curses.init_pair(color_pair, foreground, background) + self._colors[name] = curses.color_pair(color_pair) + color_pair += 1 + except curses.error: + pass + + def addstr(self, y, x, msg, color = None, attr = curses.A_NORMAL): + # Curses throws an error if we try to draw a message that spans out of the + # window's bounds (... seriously?), so doing our best to avoid that. + + if color is not None: + if color not in self._colors: + recognized_colors = ", ".join(self._colors.keys()) + raise ValueError("The '%s' color isn't recognized: %s" % (color, recognized_colors)) + + attr |= self._colors[color] + + max_y, max_x = self._stdscr.getmaxyx() + + if max_x > x and max_y > y: + try: + self._stdscr.addstr(y, x, msg[:max_x - x], attr) + except: + pass # maybe an edge case while resizing the window + + def erase(self): + self._stdscr.erase() + + def refresh(self): + self._stdscr.refresh() + +if __name__ == '__main__': + main() diff --git a/docs/tutorials/tortoise_and_the_hare.rst b/docs/tutorials/tortoise_and_the_hare.rst index d3f759e..413e149 100644 --- a/docs/tutorials/tortoise_and_the_hare.rst +++ b/docs/tutorials/tortoise_and_the_hare.rst @@ -28,184 +28,8 @@ To do this it listens to **BW events** are events that Tor emits each second saying the number of bytes downloaded and uploaded. -.. code-block:: python - :emphasize-lines: 53-55,62-67 - - import curses - import functools - - from stem.control import EventType, Controller - from stem.util import str_tools - - # colors that curses can handle - - COLOR_LIST = { - "red": curses.COLOR_RED, - "green": curses.COLOR_GREEN, - "yellow": curses.COLOR_YELLOW, - "blue": curses.COLOR_BLUE, - "cyan": curses.COLOR_CYAN, - "magenta": curses.COLOR_MAGENTA, - "black": curses.COLOR_BLACK, - "white": curses.COLOR_WHITE, - } - - GRAPH_WIDTH = 40 - GRAPH_HEIGHT = 8 - - DOWNLOAD_COLOR = "green" - UPLOAD_COLOR = "blue" - - def main(): - with Controller.from_port(port = 9051) as controller: - controller.authenticate() - - try: - # This makes curses initialize and call draw_bandwidth_graph() with a - # reference to the screen, followed by additional arguments (in this - # case just the controller). - - curses.wrapper(draw_bandwidth_graph, controller) - except KeyboardInterrupt: - pass # the user hit ctrl+c - - def draw_bandwidth_graph(stdscr, controller): - window = Window(stdscr) - - # (downloaded, uploaded) tuples for the last 40 seconds - - bandwidth_rates = [(0, 0)] * GRAPH_WIDTH - - # Making a partial that wraps the window and bandwidth_rates with a function - # for Tor to call when it gets a BW event. This causes the 'window' and - # 'bandwidth_rates' to be provided as the first two arguments whenever - # 'bw_event_handler()' is called. - - bw_event_handler = functools.partial(_handle_bandwidth_event, window, bandwidth_rates) - - # Registering this listener with Tor. Tor reports a BW event each second. - - controller.add_event_listener(bw_event_handler, EventType.BW) - - # Pause the main thread until the user hits any key... and no, don't you dare - # ask where the 'any' key is. :P - - stdscr.getch() - - def _handle_bandwidth_event(window, bandwidth_rates, event): - # callback for when tor provides us with a BW event - - bandwidth_rates.insert(0, (event.read, event.written)) - bandwidth_rates = bandwidth_rates[:GRAPH_WIDTH] # truncate old values - _render_graph(window, bandwidth_rates) - - def _render_graph(window, bandwidth_rates): - window.erase() - - download_rates = [entry[0] for entry in bandwidth_rates] - upload_rates = [entry[1] for entry in bandwidth_rates] - - # show the latest values at the top - - label = "Downloaded (%s/s):" % str_tools.size_label(download_rates[0], 1) - window.addstr(0, 1, label, DOWNLOAD_COLOR, curses.A_BOLD) - - label = "Uploaded (%s/s):" % str_tools.size_label(upload_rates[0], 1) - window.addstr(0, GRAPH_WIDTH + 7, label, UPLOAD_COLOR, curses.A_BOLD) - - # draw the graph bounds in KB - - max_download_rate = max(download_rates) - max_upload_rate = max(upload_rates) - - window.addstr(1, 1, "%4i" % (max_download_rate / 1024), DOWNLOAD_COLOR) - window.addstr(GRAPH_HEIGHT, 1, " 0", DOWNLOAD_COLOR) - - window.addstr(1, GRAPH_WIDTH + 7, "%4i" % (max_upload_rate / 1024), UPLOAD_COLOR) - window.addstr(GRAPH_HEIGHT, GRAPH_WIDTH + 7, " 0", UPLOAD_COLOR) - - # draw the graph - - for col in xrange(GRAPH_WIDTH): - col_height = GRAPH_HEIGHT * download_rates[col] / max(max_download_rate, 1) - - for row in xrange(col_height): - window.addstr(GRAPH_HEIGHT - row, col + 6, " ", DOWNLOAD_COLOR, curses.A_STANDOUT) - - col_height = GRAPH_HEIGHT * upload_rates[col] / max(max_upload_rate, 1) - - for row in xrange(col_height): - window.addstr(GRAPH_HEIGHT - row, col + GRAPH_WIDTH + 12, " ", UPLOAD_COLOR, curses.A_STANDOUT) - - window.refresh() - - class Window(object): - """ - Simple wrapper for the curses standard screen object. - """ - - def __init__(self, stdscr): - self._stdscr = stdscr - - # Mappings of names to the curses color attribute. Initially these all - # reference black text, but if the terminal can handle color then - # they're set with that foreground color. - - self._colors = dict([(color, 0) for color in COLOR_LIST]) - - # allows for background transparency - - try: - curses.use_default_colors() - except curses.error: - pass - - # makes the cursor invisible - - try: - curses.curs_set(0) - except curses.error: - pass - - # initializes colors if the terminal can handle them - - try: - if curses.has_colors(): - color_pair = 1 - - for name, foreground in COLOR_LIST.items(): - background = -1 # allows for default (possibly transparent) background - curses.init_pair(color_pair, foreground, background) - self._colors[name] = curses.color_pair(color_pair) - color_pair += 1 - except curses.error: - pass - - def addstr(self, y, x, msg, color = None, attr = curses.A_NORMAL): - # Curses throws an error if we try to draw a message that spans out of the - # window's bounds (... seriously?), so doing our best to avoid that. - - if color is not None: - if color not in self._colors: - recognized_colors = ", ".join(self._colors.keys()) - raise ValueError("The '%s' color isn't recognized: %s" % (color, recognized_colors)) - - attr |= self._colors[color] - - max_y, max_x = self._stdscr.getmaxyx() - - if max_x > x and max_y > y: - try: - self._stdscr.addstr(y, x, msg[:max_x - x], attr) - except: - pass # maybe an edge case while resizing the window - - def erase(self): - self._stdscr.erase() - - def refresh(self): - self._stdscr.refresh() - - if __name__ == '__main__': - main() +.. literalinclude:: /_static/example/event_listening.py + :caption: `[Download] <../_static/example/event_listening.py>`__ + :emphasize-lines: 53-55,62-67 + :language: python

1 0

[stem/master] Added downloadable tutorial for tutorial Over the River and Through the Wood
by atagar＠torproject.org 25 May '15

25 May '15

commit ac1e00b87cb1a587e9ee8d401b674254b0a0122c Author: Sambuddha Basu <sambuddhabasu1(a)gmail.com> Date: Mon May 25 07:50:48 2015 +0400 Added downloadable tutorial for tutorial Over the River and Through the Wood --- docs/_static/example/ephemeral_hidden_services.py | 27 +++++ .../example/get_hidden_service_descriptor.py | 8 ++ docs/_static/example/introduction_points.py | 10 ++ docs/_static/example/running_hidden_service.py | 48 +++++++++ docs/tutorials/over_the_river.rst | 113 +++----------------- 5 files changed, 105 insertions(+), 101 deletions(-) diff --git a/docs/_static/example/ephemeral_hidden_services.py b/docs/_static/example/ephemeral_hidden_services.py new file mode 100644 index 0000000..b3b621b --- /dev/null +++ b/docs/_static/example/ephemeral_hidden_services.py @@ -0,0 +1,27 @@ +from stem.control import Controller +from flask import Flask + +app = Flask(__name__) + + +(a)app.route('/') +def index(): + return "<h1>Hi Grandma!</h1>" + + +print ' * Connecting to tor' + +with Controller.from_port() as controller: + controller.authenticate() + + # Create a hidden service where visitors of port 80 get redirected to local + # port 5000 (this is where Flask runs by default). + + print " * Creating our hidden service in %s" % hidden_service_dir + response = controller.create_ephemeral_hidden_service({80: 5000}, await_publication = True) + print " * Our service is available at %s.onion, press ctrl+c to quit" % response.service_id + + try: + app.run() + finally: + print " * Shutting down our hidden service" diff --git a/docs/_static/example/get_hidden_service_descriptor.py b/docs/_static/example/get_hidden_service_descriptor.py new file mode 100644 index 0000000..baeec1d --- /dev/null +++ b/docs/_static/example/get_hidden_service_descriptor.py @@ -0,0 +1,8 @@ +from stem.control import Controller + +with Controller.from_port(port = 9051) as controller: + controller.authenticate() + + # descriptor of duck-duck-go's hidden service (http://3g2upl4pq6kufc4m.onion) + + print controller.get_hidden_service_descriptor('3g2upl4pq6kufc4m') diff --git a/docs/_static/example/introduction_points.py b/docs/_static/example/introduction_points.py new file mode 100644 index 0000000..3c97e47 --- /dev/null +++ b/docs/_static/example/introduction_points.py @@ -0,0 +1,10 @@ +from stem.control import Controller + +with Controller.from_port(port = 9051) as controller: + controller.authenticate() + desc = controller.get_hidden_service_descriptor('3g2upl4pq6kufc4m') + + print "DuckDuckGo's introduction points are...\n" + + for introduction_point in desc.introduction_points(): + print ' %s:%s => %s' % (introduction_point.address, introduction_point.port, introduction_point.identifier) diff --git a/docs/_static/example/running_hidden_service.py b/docs/_static/example/running_hidden_service.py new file mode 100644 index 0000000..4a4d923 --- /dev/null +++ b/docs/_static/example/running_hidden_service.py @@ -0,0 +1,48 @@ +import os +import shutil + +from stem.control import Controller +from flask import Flask + +app = Flask(__name__) + + +(a)app.route('/') +def index(): + return "<h1>Hi Grandma!</h1>" + + +print ' * Connecting to tor' + +with Controller.from_port() as controller: + controller.authenticate() + + # All hidden services have a directory on disk. Lets put ours in tor's data + # directory. + + hidden_service_dir = os.path.join(controller.get_conf('DataDirectory', '/tmp'), 'hello_world') + + # Create a hidden service where visitors of port 80 get redirected to local + # port 5000 (this is where Flask runs by default). + + print " * Creating our hidden service in %s" % hidden_service_dir + result = controller.create_hidden_service(hidden_service_dir, 80, target_port = 5000) + + # The hostname is only available when we can read the hidden service + # directory. This requires us to be running with the same user as tor. + + if result.hostname: + print " * Our service is available at %s, press ctrl+c to quit" % result.hostname + else: + print " * Unable to determine our service's hostname, probably due to being unable to read the hidden service directory" + + try: + app.run() + finally: + # Shut down the hidden service and clean it off disk. Note that you *don't* + # want to delete the hidden service directory if you'd like to have this + # same *.onion address in the future. + + print " * Shutting down our hidden service" + controller.remove_hidden_service(hidden_service_dir) + shutil.rmtree(hidden_service_dir) diff --git a/docs/tutorials/over_the_river.rst b/docs/tutorials/over_the_river.rst index ed2d039..79e42d0 100644 --- a/docs/tutorials/over_the_river.rst +++ b/docs/tutorials/over_the_river.rst @@ -51,56 +51,9 @@ But with that out of the way lets take a look at a simple `Flask <http://flask.pocoo.org/>`_ example based on one by `Jordan Wright <https://jordan-wright.github.io/blog/2014/10/06/creating-tor-hidden-service…>`_... -:: - - import os - import shutil - - from stem.control import Controller - from flask import Flask - - app = Flask(__name__) - - - @app.route('/') - def index(): - return "<h1>Hi Grandma!</h1>" - - - print ' * Connecting to tor' - - with Controller.from_port() as controller: - controller.authenticate() - - # All hidden services have a directory on disk. Lets put ours in tor's data - # directory. - - hidden_service_dir = os.path.join(controller.get_conf('DataDirectory', '/tmp'), 'hello_world') - - # Create a hidden service where visitors of port 80 get redirected to local - # port 5000 (this is where Flask runs by default). - - print " * Creating our hidden service in %s" % hidden_service_dir - result = controller.create_hidden_service(hidden_service_dir, 80, target_port = 5000) - - # The hostname is only available when we can read the hidden service - # directory. This requires us to be running with the same user as tor. - - if result.hostname: - print " * Our service is available at %s, press ctrl+c to quit" % result.hostname - else: - print " * Unable to determine our service's hostname, probably due to being unable to read the hidden service directory" - - try: - app.run() - finally: - # Shut down the hidden service and clean it off disk. Note that you *don't* - # want to delete the hidden service directory if you'd like to have this - # same *.onion address in the future. - - print " * Shutting down our hidden service" - controller.remove_hidden_service(hidden_service_dir) - shutil.rmtree(hidden_service_dir) +.. literalinclude:: /_static/example/running_hidden_service.py + :caption: `[Download] <../_static/example/running_hidden_service.py>`__ + :language: python Now if we run this... @@ -152,35 +105,9 @@ Stem provides three methods to work with ephemeral hidden services... For example, with a ephemeral service our earlier example becomes as simple as... -:: - - from stem.control import Controller - from flask import Flask - - app = Flask(__name__) - - - @app.route('/') - def index(): - return "<h1>Hi Grandma!</h1>" - - - print ' * Connecting to tor' - - with Controller.from_port() as controller: - controller.authenticate() - - # Create a hidden service where visitors of port 80 get redirected to local - # port 5000 (this is where Flask runs by default). - - print " * Creating our hidden service in %s" % hidden_service_dir - response = controller.create_ephemeral_hidden_service({80: 5000}, await_publication = True) - print " * Our service is available at %s.onion, press ctrl+c to quit" % response.service_id - - try: - app.run() - finally: - print " * Shutting down our hidden service" +.. literalinclude:: /_static/example/ephemeral_hidden_services.py + :caption: `[Download] <../_static/example/ephemeral_hidden_services.py>`__ + :language: python .. _hidden-service-descriptors: @@ -192,16 +119,9 @@ service descriptors**. These contain low level details for establishing connections. Hidden service descriptors are available from the tor process via its :func:`~stem.control.Controller.get_hidden_service_descriptor` method... -:: - - from stem.control import Controller - - with Controller.from_port(port = 9051) as controller: - controller.authenticate() - - # descriptor of duck-duck-go's hidden service (http://3g2upl4pq6kufc4m.onion) - - print controller.get_hidden_service_descriptor('3g2upl4pq6kufc4m') +.. literalinclude:: /_static/example/get_hidden_service_descriptor.py + :caption: `[Download] <../_static/example/get_hidden_service_descriptor.py>`__ + :language: python :: @@ -230,18 +150,9 @@ descriptor's :func:`~stem.descriptor.hidden_service_descriptor.HiddenServiceDescriptor.introduction_points` method. -:: - - from stem.control import Controller - - with Controller.from_port(port = 9051) as controller: - controller.authenticate() - desc = controller.get_hidden_service_descriptor('3g2upl4pq6kufc4m') - - print "DuckDuckGo's introduction points are...\n" - - for introduction_point in desc.introduction_points(): - print ' %s:%s => %s' % (introduction_point.address, introduction_point.port, introduction_point.identifier) +.. literalinclude:: /_static/example/introduction_points.py + :caption: `[Download] <../_static/example/introduction_points.py>`__ + :language: python ::

1 0

[stem/master] Note that Sphinx 1.3 is required in the FAQ
by atagar＠torproject.org 25 May '15

25 May '15

commit 7f4a53548db501e778086f140de7a21b47465cf3 Author: Damian Johnson <atagar(a)torproject.org> Date: Mon May 25 10:09:11 2015 -0700 Note that Sphinx 1.3 is required in the FAQ --- docs/change_log.rst | 1 + docs/conf.py | 2 +- docs/faq.rst | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/change_log.rst b/docs/change_log.rst index 643f5bd..1d801f9 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -52,6 +52,7 @@ The following are only available within Stem's `git repository * **Website** * Example for `custom path selection for circuits <tutorials/to_russia_with_love.html#custom-path-selection>`_ (:trac:`8728`) + * Download link for tutorial examples (:trac:`10411`) .. _version_1.4: diff --git a/docs/conf.py b/docs/conf.py index d888402..b28a67b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -22,7 +22,7 @@ sys.path.append(os.path.abspath('.')) # -- General configuration ----------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = '1.3' # required for the sphinx-apidoc command +needs_sphinx = '1.3' # required for the caption option # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. diff --git a/docs/faq.rst b/docs/faq.rst index 2a4ec83..4d5a9a5 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -545,7 +545,7 @@ example... How do I build the site? ------------------------ -If you have `Sphinx <http://sphinx-doc.org/>`_ version 1.1 or later installed +If you have `Sphinx <http://sphinx-doc.org/>`_ version 1.3 or later installed then building our site is as easy as... ::

1 0

[stem/master] Added downloadable tutorial for tutorial Mirror Mirror on the Wall
by atagar＠torproject.org 25 May '15

25 May '15

commit 34274146840940dfd617baa9ded3181ca82f4c55 Author: Sambuddha Basu <sambuddhabasu1(a)gmail.com> Date: Mon May 25 08:08:10 2015 +0400 Added downloadable tutorial for tutorial Mirror Mirror on the Wall --- docs/_static/example/current_descriptors.py | 9 ++ .../example/descriptor_from_tor_control_socket.py | 7 ++ .../example/descriptor_from_tor_data_directory.py | 4 + docs/_static/example/past_descriptors.py | 5 + docs/_static/example/read_with_parse_file.py | 6 ++ .../example/saving_and_loading_descriptors.py | 7 ++ docs/_static/example/tor_descriptors.py | 32 ++++++ .../_static/example/validate_descriptor_content.py | 4 + docs/tutorials/mirror_mirror_on_the_wall.rst | 114 +++++--------------- 9 files changed, 98 insertions(+), 90 deletions(-) diff --git a/docs/_static/example/current_descriptors.py b/docs/_static/example/current_descriptors.py new file mode 100644 index 0000000..9ddca01 --- /dev/null +++ b/docs/_static/example/current_descriptors.py @@ -0,0 +1,9 @@ +from stem.descriptor.remote import DescriptorDownloader + +downloader = DescriptorDownloader() + +try: + for desc in downloader.get_consensus().run(): + print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) +except Exception as exc: + print "Unable to retrieve the consensus: %s" % exc diff --git a/docs/_static/example/descriptor_from_tor_control_socket.py b/docs/_static/example/descriptor_from_tor_control_socket.py new file mode 100644 index 0000000..202f66e --- /dev/null +++ b/docs/_static/example/descriptor_from_tor_control_socket.py @@ -0,0 +1,7 @@ +from stem.control import Controller + +with Controller.from_port(port = 9051) as controller: + controller.authenticate() + + for desc in controller.get_network_statuses(): + print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) diff --git a/docs/_static/example/descriptor_from_tor_data_directory.py b/docs/_static/example/descriptor_from_tor_data_directory.py new file mode 100644 index 0000000..cdfd78b --- /dev/null +++ b/docs/_static/example/descriptor_from_tor_data_directory.py @@ -0,0 +1,4 @@ +from stem.descriptor import parse_file + +for desc in parse_file('/home/atagar/.tor/cached-consensus'): + print 'found relay %s (%s)' % (desc.nickname, desc.fingerprint) diff --git a/docs/_static/example/past_descriptors.py b/docs/_static/example/past_descriptors.py new file mode 100644 index 0000000..4b3e5cb --- /dev/null +++ b/docs/_static/example/past_descriptors.py @@ -0,0 +1,5 @@ +from stem.descriptor.reader import DescriptorReader + +with DescriptorReader(["/home/atagar/server-descriptors-2013-03.tar"]) as reader: + for desc in reader: + print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) diff --git a/docs/_static/example/read_with_parse_file.py b/docs/_static/example/read_with_parse_file.py new file mode 100644 index 0000000..96ec99e --- /dev/null +++ b/docs/_static/example/read_with_parse_file.py @@ -0,0 +1,6 @@ +from stem.descriptor import parse_file + +server_descriptors = parse_file('/tmp/descriptor_dump', descriptor_type = 'server-descriptor 1.0') + +for relay in server_descriptors: + print relay.fingerprint diff --git a/docs/_static/example/saving_and_loading_descriptors.py b/docs/_static/example/saving_and_loading_descriptors.py new file mode 100644 index 0000000..bb2703e --- /dev/null +++ b/docs/_static/example/saving_and_loading_descriptors.py @@ -0,0 +1,7 @@ +from stem.descriptor.remote import DescriptorDownloader + +downloader = DescriptorDownloader() +server_descriptors = downloader.get_server_descriptors().run() + +with open('/tmp/descriptor_dump', 'wb') as descriptor_file: + descriptor_file.write(''.join(map(str, server_descriptors))) diff --git a/docs/_static/example/tor_descriptors.py b/docs/_static/example/tor_descriptors.py new file mode 100644 index 0000000..2b59ad4 --- /dev/null +++ b/docs/_static/example/tor_descriptors.py @@ -0,0 +1,32 @@ +import sys + +from stem.descriptor.remote import DescriptorDownloader +from stem.util import str_tools + +# provides a mapping of observed bandwidth to the relay nicknames +def get_bw_to_relay(): + bw_to_relay = {} + + downloader = DescriptorDownloader() + + try: + for desc in downloader.get_server_descriptors().run(): + if desc.exit_policy.is_exiting_allowed(): + bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname) + except Exception as exc: + print "Unable to retrieve the server descriptors: %s" % exc + + return bw_to_relay + +# prints the top fifteen relays + +bw_to_relay = get_bw_to_relay() +count = 1 + +for bw_value in sorted(bw_to_relay.keys(), reverse = True): + for nickname in bw_to_relay[bw_value]: + print "%i. %s (%s/s)" % (count, nickname, str_tools.size_label(bw_value, 2)) + count += 1 + + if count > 15: + sys.exit() diff --git a/docs/_static/example/validate_descriptor_content.py b/docs/_static/example/validate_descriptor_content.py new file mode 100644 index 0000000..f6b27a5 --- /dev/null +++ b/docs/_static/example/validate_descriptor_content.py @@ -0,0 +1,4 @@ +from stem.descriptor import parse_file + +for desc in parse_file('/home/atagar/.tor/cached-consensus', validate = True): + print 'found relay %s (%s)' % (desc.nickname, desc.fingerprint) diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst index 9ef620f..ff4c86c 100644 --- a/docs/tutorials/mirror_mirror_on_the_wall.rst +++ b/docs/tutorials/mirror_mirror_on_the_wall.rst @@ -76,17 +76,9 @@ irresponsible script can make Tor worse for everyone. Listing the current relays in the Tor network is as easy as... -:: - - from stem.descriptor.remote import DescriptorDownloader - - downloader = DescriptorDownloader() - - try: - for desc in downloader.get_consensus().run(): - print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) - except Exception as exc: - print "Unable to retrieve the consensus: %s" % exc +.. literalinclude:: /_static/example/current_descriptors.py + :caption: `[Download] <../_static/example/current_descriptors.py>`__ + :language: python .. _where-can-i-get-past-descriptors: @@ -97,13 +89,9 @@ Descriptor archives are available from `CollecTor <https://collector.torproject.org/>`_. These archives can be read with the `DescriptorReader <../api/descriptor/reader.html>`_... -:: - - from stem.descriptor.reader import DescriptorReader - - with DescriptorReader(["/home/atagar/server-descriptors-2013-03.tar"]) as reader: - for desc in reader: - print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) +.. literalinclude:: /_static/example/past_descriptors.py + :caption: `[Download] <../_static/example/past_descriptors.py>`__ + :language: python .. _can-i-get-descriptors-from-the-tor-process: @@ -151,24 +139,15 @@ the network! Now that Tor is happy chugging along, up-to-date descriptors are available through Tor's control socket... -:: - - from stem.control import Controller - - with Controller.from_port(port = 9051) as controller: - controller.authenticate() - - for desc in controller.get_network_statuses(): - print "found relay %s (%s)" % (desc.nickname, desc.fingerprint) +.. literalinclude:: /_static/example/descriptor_from_tor_control_socket.py + :caption: `[Download] <../_static/example/descriptor_from_tor_control_socket.py>`__ + :language: python ... or by reading directly from Tor's data directory... -:: - - from stem.descriptor import parse_file - - for desc in parse_file('/home/atagar/.tor/cached-consensus'): - print 'found relay %s (%s)' % (desc.nickname, desc.fingerprint) +.. literalinclude:: /_static/example/descriptor_from_tor_data_directory.py + :caption: `[Download] <../_static/example/descriptor_from_tor_data_directory.py>`__ + :language: python .. _validating-the-descriptors-content: @@ -195,12 +174,9 @@ if *correctness* or *signature validation* is important then turn it on. Validating is as simple as including **validate = True** in any method that provides descriptors... -:: - - from stem.descriptor import parse_file - - for desc in parse_file('/home/atagar/.tor/cached-consensus', validate = True): - print 'found relay %s (%s)' % (desc.nickname, desc.fingerprint) +.. literalinclude:: /_static/example/validate_descriptor_content.py + :caption: `[Download] <../_static/example/validate_descriptor_content.py>`__ + :language: python .. _saving-and-loading-descriptors: @@ -211,15 +187,9 @@ Tor descriptors are just plaintext documents. As such, if you'd rather not use `Pickle <https://wiki.python.org/moin/UsingPickle>`_ you can persist a descriptor by simply writing it to disk, then reading it back later. -:: - - from stem.descriptor.remote import DescriptorDownloader - - downloader = DescriptorDownloader() - server_descriptors = downloader.get_server_descriptors().run() - - with open('/tmp/descriptor_dump', 'wb') as descriptor_file: - descriptor_file.write(''.join(map(str, server_descriptors))) +.. literalinclude:: /_static/example/saving_and_loading_descriptors.py + :caption: `[Download] <../_static/example/saving_and_loading_descriptors.py>`__ + :language: python Our *server_descriptors* here is a list of :class:`~stem.descriptor.server_descriptor.RelayDescriptor` instances. When we @@ -240,14 +210,9 @@ write it to a file this looks like... We can then read it back with :func:`~stem.descriptor.__init__.parse_file` by telling it the type of descriptors we're reading... -:: - - from stem.descriptor import parse_file - - server_descriptors = parse_file('/tmp/descriptor_dump', descriptor_type = 'server-descriptor 1.0') - - for relay in server_descriptors: - print relay.fingerprint +.. literalinclude:: /_static/example/read_with_parse_file.py + :caption: `[Download] <../_static/example/read_with_parse_file.py>`__ + :language: python For an example of doing this with a consensus document `see here <examples/persisting_a_consensus.html>`_. @@ -268,40 +233,9 @@ Now lets say you want to figure out who the *biggest* exit relays are. You could use any of the methods above, but for this example we'll use `stem.descriptor.remote <../api/descriptor/remote.html>`_... -:: - - import sys - - from stem.descriptor.remote import DescriptorDownloader - from stem.util import str_tools - - # provides a mapping of observed bandwidth to the relay nicknames - def get_bw_to_relay(): - bw_to_relay = {} - - downloader = DescriptorDownloader() - - try: - for desc in downloader.get_server_descriptors().run(): - if desc.exit_policy.is_exiting_allowed(): - bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname) - except Exception as exc: - print "Unable to retrieve the server descriptors: %s" % exc - - return bw_to_relay - - # prints the top fifteen relays - - bw_to_relay = get_bw_to_relay() - count = 1 - - for bw_value in sorted(bw_to_relay.keys(), reverse = True): - for nickname in bw_to_relay[bw_value]: - print "%i. %s (%s/s)" % (count, nickname, str_tools.size_label(bw_value, 2)) - count += 1 - - if count > 15: - sys.exit() +.. literalinclude:: /_static/example/tor_descriptors.py + :caption: `[Download] <../_static/example/tor_descriptors.py>`__ + :language: python ::

1 0

[stem/master] Downloadable tutorial examples
by atagar＠torproject.org 25 May '15

25 May '15

commit 2a0110cc6fc682cdbf56cac100ce228e2b6b0699 Merge: 3b2a31b 7f4a535 Author: Damian Johnson <atagar(a)torproject.org> Date: Mon May 25 10:11:47 2015 -0700 Downloadable tutorial examples Moving our tutorial's examples to _static/examples/*, and adding them via a literalinclude directive. Advantages are... * We now have a '[Download]' link to... well, download it! * Now that we've isolated the example scripts we can exercise these with our tests (rather than duplicating the code there). https://trac.torproject.org/projects/tor/ticket/10411 Nice work, Sambuddha! docs/_static/example/client_usage_using_pycurl.py | 54 ++++ .../_static/example/client_usage_using_socksipy.py | 25 ++ docs/_static/example/compare_flags.py | 41 +++ docs/_static/example/current_descriptors.py | 9 + docs/_static/example/custom_path_selection.py | 79 ++++++ .../example/descriptor_from_tor_control_socket.py | 7 + .../example/descriptor_from_tor_data_directory.py | 4 + docs/_static/example/ephemeral_hidden_services.py | 27 ++ docs/_static/example/event_listening.py | 177 +++++++++++++ docs/_static/example/exit_used.py | 35 +++ .../example/get_hidden_service_descriptor.py | 8 + docs/_static/example/hello_world.py | 9 + docs/_static/example/introduction_points.py | 10 + docs/_static/example/list_circuits.py | 21 ++ docs/_static/example/outdated_relays.py | 19 ++ docs/_static/example/past_descriptors.py | 5 + docs/_static/example/persisting_a_consensus.py | 8 + .../persisting_a_consensus_with_parse_file.py | 10 + docs/_static/example/read_with_parse_file.py | 6 + docs/_static/example/reading_twitter.py | 87 +++++++ docs/_static/example/running_hidden_service.py | 48 ++++ .../example/saving_and_loading_descriptors.py | 7 + docs/_static/example/tor_descriptors.py | 32 +++ docs/_static/example/utilities.py | 28 +++ .../_static/example/validate_descriptor_content.py | 4 + .../example/votes_by_bandwidth_authorities.py | 29 +++ docs/_static/style.css | 7 + docs/_templates/layout.html | 2 + docs/change_log.rst | 1 + docs/conf.py | 2 +- docs/faq.rst | 2 +- docs/tutorials/east_of_the_sun.rst | 33 +-- docs/tutorials/examples/compare_flags.rst | 46 +--- docs/tutorials/examples/exit_used.rst | 40 +-- docs/tutorials/examples/list_circuits.rst | 26 +- docs/tutorials/examples/outdated_relays.rst | 24 +- docs/tutorials/examples/persisting_a_consensus.rst | 28 +-- .../examples/votes_by_bandwidth_authorities.rst | 34 +-- docs/tutorials/mirror_mirror_on_the_wall.rst | 114 ++------- docs/tutorials/over_the_river.rst | 113 +-------- docs/tutorials/the_little_relay_that_could.rst | 14 +- docs/tutorials/to_russia_with_love.rst | 265 +------------------- docs/tutorials/tortoise_and_the_hare.rst | 184 +------------- 43 files changed, 880 insertions(+), 844 deletions(-)

1 0

[stem/master] Added downloadable tutotial for tutorial East of the Sun & West of the Moon
by atagar＠torproject.org 25 May '15

25 May '15

commit 9886aeef2abc9de64bd00c62339b58eee0d8bc7b Author: Sambuddha Basu <sambuddhabasu1(a)gmail.com> Date: Mon May 25 08:12:01 2015 +0400 Added downloadable tutotial for tutorial East of the Sun & West of the Moon --- docs/_static/example/utilities.py | 28 ++++++++++++++++++++++++++++ docs/tutorials/east_of_the_sun.rst | 33 +++------------------------------ 2 files changed, 31 insertions(+), 30 deletions(-) diff --git a/docs/_static/example/utilities.py b/docs/_static/example/utilities.py new file mode 100644 index 0000000..460f6ff --- /dev/null +++ b/docs/_static/example/utilities.py @@ -0,0 +1,28 @@ +import sys + +from stem.util.connection import get_connections, system_resolvers +from stem.util.system import pid_by_name + +resolvers = system_resolvers() + +if not resolvers: + print "Stem doesn't support any connection resolvers on our platform." + sys.exit(1) + +picked_resolver = resolvers[0] # lets just opt for the first +print "Our platform supports connection resolution via: %s (picked %s)" % (', '.join(resolvers), picked_resolver) + +tor_pids = pid_by_name('tor', multiple = True) + +if not tor_pids: + print "Unable to get tor's pid. Is it running?" + sys.exit(1) +elif len(tor_pids) > 1: + print "You're running %i instances of tor, picking the one with pid %i" % (len(tor_pids), tor_pids[0]) +else: + print "Tor is running with pid %i" % tor_pids[0] + +print "\nConnections:\n" + +for conn in get_connections(picked_resolver, process_pid = tor_pids[0], process_name = 'tor'): + print " %s:%s => %s:%s" % (conn.local_address, conn.local_port, conn.remote_address, conn.remote_port) diff --git a/docs/tutorials/east_of_the_sun.rst b/docs/tutorials/east_of_the_sun.rst index 13ede2d..f577df9 100644 --- a/docs/tutorials/east_of_the_sun.rst +++ b/docs/tutorials/east_of_the_sun.rst @@ -33,36 +33,9 @@ but likely also a violation of wiretap laws. With that out of the way, how do you look up this information? Below is a simple script that dumps Tor's present connections. -:: - - import sys - - from stem.util.connection import get_connections, system_resolvers - from stem.util.system import pid_by_name - - resolvers = system_resolvers() - - if not resolvers: - print "Stem doesn't support any connection resolvers on our platform." - sys.exit(1) - - picked_resolver = resolvers[0] # lets just opt for the first - print "Our platform supports connection resolution via: %s (picked %s)" % (', '.join(resolvers), picked_resolver) - - tor_pids = pid_by_name('tor', multiple = True) - - if not tor_pids: - print "Unable to get tor's pid. Is it running?" - sys.exit(1) - elif len(tor_pids) > 1: - print "You're running %i instances of tor, picking the one with pid %i" % (len(tor_pids), tor_pids[0]) - else: - print "Tor is running with pid %i" % tor_pids[0] - - print "\nConnections:\n" - - for conn in get_connections(picked_resolver, process_pid = tor_pids[0], process_name = 'tor'): - print " %s:%s => %s:%s" % (conn.local_address, conn.local_port, conn.remote_address, conn.remote_port) +.. literalinclude:: /_static/example/utilities.py + :caption: `[Download] <../_static/example/utilities.py>`__ + :language: python ::

1 0

[stem/master] Added downloadable tutorial examples
by atagar＠torproject.org 25 May '15

25 May '15

commit 1a26c5f654e783b649611b457149168105593e9a Author: Sambuddha Basu <sambuddhabasu1(a)gmail.com> Date: Mon May 25 08:31:59 2015 +0400 Added downloadable tutorial examples --- docs/_static/example/compare_flags.py | 41 +++++++++++++++++ docs/_static/example/exit_used.py | 35 +++++++++++++++ docs/_static/example/list_circuits.py | 21 +++++++++ docs/_static/example/outdated_relays.py | 19 ++++++++ docs/_static/example/persisting_a_consensus.py | 8 ++++ .../persisting_a_consensus_with_parse_file.py | 10 +++++ .../example/votes_by_bandwidth_authorities.py | 29 ++++++++++++ docs/tutorials/examples/compare_flags.rst | 46 ++------------------ docs/tutorials/examples/exit_used.rst | 40 ++--------------- docs/tutorials/examples/list_circuits.rst | 26 ++--------- docs/tutorials/examples/outdated_relays.rst | 24 ++-------- docs/tutorials/examples/persisting_a_consensus.rst | 28 +++--------- .../examples/votes_by_bandwidth_authorities.rst | 34 ++------------- 13 files changed, 184 insertions(+), 177 deletions(-) diff --git a/docs/_static/example/compare_flags.py b/docs/_static/example/compare_flags.py new file mode 100644 index 0000000..a668e11 --- /dev/null +++ b/docs/_static/example/compare_flags.py @@ -0,0 +1,41 @@ +from stem.descriptor import DocumentHandler, remote + +# Query all authority votes asynchronously. + +downloader = remote.DescriptorDownloader(document_handler = DocumentHandler.DOCUMENT) +queries = {} + +for name, authority in remote.get_authorities().items(): + if authority.v3ident is None: + continue # authority doens't vote if it lacks a v3ident + + queries[name] = downloader.get_vote(authority) + +# Wait for the votes to finish being downloaded, this produces a dictionary of +# authority nicknames to their vote. + +votes = dict((name, query.run()[0]) for (name, query) in queries.items()) + +# Get a superset of all the fingerprints in all the votes. + +all_fingerprints = set() + +for vote in votes.values(): + all_fingerprints.update(vote.routers.keys()) + +# Finally, compare moria1's votes to maatuska. + +for fingerprint in all_fingerprints: + moria1_vote = votes['moria1'].routers.get(fingerprint) + maatuska_vote = votes['maatuska'].routers.get(fingerprint) + + if not moria1_vote and not maatuska_vote: + print "both moria1 and maatuska haven't voted about %s" % fingerprint + elif not moria1_vote: + print "moria1 hasn't voted about %s" % fingerprint + elif not maatuska_vote: + print "maatuska hasn't voted about %s" % fingerprint + elif 'Running' in moria1_vote.flags and 'Running' not in maatuska_vote.flags: + print "moria1 has the Running flag but maatuska doesn't: %s" % fingerprint + elif 'Running' in maatuska_vote.flags and 'Running' not in moria1_vote.flags: + print "maatuska has the Running flag but moria1 doesn't: %s" % fingerprint diff --git a/docs/_static/example/exit_used.py b/docs/_static/example/exit_used.py new file mode 100644 index 0000000..7ecd19a --- /dev/null +++ b/docs/_static/example/exit_used.py @@ -0,0 +1,35 @@ +import functools + +from stem import StreamStatus +from stem.control import EventType, Controller + +def main(): + print "Tracking requests for tor exits. Press 'enter' to end." + print + + with Controller.from_port() as controller: + controller.authenticate() + + stream_listener = functools.partial(stream_event, controller) + controller.add_event_listener(stream_listener, EventType.STREAM) + + raw_input() # wait for user to press enter + + +def stream_event(controller, event): + if event.status == StreamStatus.SUCCEEDED and event.circ_id: + circ = controller.get_circuit(event.circ_id) + + exit_fingerprint = circ.path[-1][0] + exit_relay = controller.get_network_status(exit_fingerprint) + + print "Exit relay for our connection to %s" % (event.target) + print " address: %s:%i" % (exit_relay.address, exit_relay.or_port) + print " fingerprint: %s" % exit_relay.fingerprint + print " nickname: %s" % exit_relay.nickname + print " locale: %s" % controller.get_info("ip-to-country/%s" % exit_relay.address, 'unknown') + print + + +if __name__ == '__main__': + main() diff --git a/docs/_static/example/list_circuits.py b/docs/_static/example/list_circuits.py new file mode 100644 index 0000000..61fdd5e --- /dev/null +++ b/docs/_static/example/list_circuits.py @@ -0,0 +1,21 @@ +from stem import CircStatus +from stem.control import Controller + +with Controller.from_port(port = 9051) as controller: + controller.authenticate() + + for circ in sorted(controller.get_circuits()): + if circ.status != CircStatus.BUILT: + continue + + print + print "Circuit %s (%s)" % (circ.id, circ.purpose) + + for i, entry in enumerate(circ.path): + div = '+' if (i == len(circ.path) - 1) else '|' + fingerprint, nickname = entry + + desc = controller.get_network_status(fingerprint, None) + address = desc.address if desc else 'unknown' + + print " %s- %s (%s, %s)" % (div, fingerprint, nickname, address) diff --git a/docs/_static/example/outdated_relays.py b/docs/_static/example/outdated_relays.py new file mode 100644 index 0000000..a78c6ee --- /dev/null +++ b/docs/_static/example/outdated_relays.py @@ -0,0 +1,19 @@ +from stem.descriptor.remote import DescriptorDownloader +from stem.version import Version + +downloader = DescriptorDownloader() +count, with_contact = 0, 0 + +print "Checking for outdated relays..." +print + +for desc in downloader.get_server_descriptors(): + if desc.tor_version < Version('0.2.3.0'): + count += 1 + + if desc.contact: + print ' %-15s %s' % (desc.tor_version, desc.contact.decode("utf-8", "replace")) + with_contact += 1 + +print +print "%i outdated relays found, %i had contact information" % (count, with_contact) diff --git a/docs/_static/example/persisting_a_consensus.py b/docs/_static/example/persisting_a_consensus.py new file mode 100644 index 0000000..55b17bd --- /dev/null +++ b/docs/_static/example/persisting_a_consensus.py @@ -0,0 +1,8 @@ +from stem.descriptor import DocumentHandler +from stem.descriptor.remote import DescriptorDownloader + +downloader = DescriptorDownloader() +consensus = downloader.get_consensus(document_handler = DocumentHandler.DOCUMENT).run()[0] + +with open('/tmp/descriptor_dump', 'w') as descriptor_file: + descriptor_file.write(str(consensus)) diff --git a/docs/_static/example/persisting_a_consensus_with_parse_file.py b/docs/_static/example/persisting_a_consensus_with_parse_file.py new file mode 100644 index 0000000..bbec73a --- /dev/null +++ b/docs/_static/example/persisting_a_consensus_with_parse_file.py @@ -0,0 +1,10 @@ +from stem.descriptor import DocumentHandler, parse_file + +consensus = next(parse_file( + '/tmp/descriptor_dump', + descriptor_type = 'network-status-consensus-3 1.0', + document_handler = DocumentHandler.DOCUMENT, +)) + +for fingerprint, relay in consensus.routers.items(): + print "%s: %s" % (fingerprint, relay.nickname) diff --git a/docs/_static/example/votes_by_bandwidth_authorities.py b/docs/_static/example/votes_by_bandwidth_authorities.py new file mode 100644 index 0000000..e957be5 --- /dev/null +++ b/docs/_static/example/votes_by_bandwidth_authorities.py @@ -0,0 +1,29 @@ +from stem.descriptor import remote + +# request votes from all the bandwidth authorities + +queries = {} +downloader = remote.DescriptorDownloader() + +for authority in remote.get_authorities().values(): + if authority.is_bandwidth_authority: + queries[authority.nickname] = downloader.query( + '/tor/status-vote/current/authority', + endpoints = [(authority.address, authority.dir_port)], + ) + +for authority_name, query in queries.items(): + try: + print "Getting %s's vote from %s:" % (authority_name, query.download_url) + + measured, unmeasured = 0, 0 + + for desc in query.run(): + if desc.measured: + measured += 1 + else: + unmeasured += 1 + + print ' %i measured entries and %i unmeasured' % (measured, unmeasured) + except Exception as exc: + print " failed to get the vote (%s)" % exc diff --git a/docs/tutorials/examples/compare_flags.rst b/docs/tutorials/examples/compare_flags.rst index 07a4126..3ea6143 100644 --- a/docs/tutorials/examples/compare_flags.rst +++ b/docs/tutorials/examples/compare_flags.rst @@ -7,49 +7,9 @@ Comparing Directory Authority Flags Compares the votes of two directory authorities, in this case moria1 and maatuska, with a special interest in the 'Running' flag. -:: - - from stem.descriptor import DocumentHandler, remote - - # Query all authority votes asynchronously. - - downloader = remote.DescriptorDownloader(document_handler = DocumentHandler.DOCUMENT) - queries = {} - - for name, authority in remote.get_authorities().items(): - if authority.v3ident is None: - continue # authority doens't vote if it lacks a v3ident - - queries[name] = downloader.get_vote(authority) - - # Wait for the votes to finish being downloaded, this produces a dictionary of - # authority nicknames to their vote. - - votes = dict((name, query.run()[0]) for (name, query) in queries.items()) - - # Get a superset of all the fingerprints in all the votes. - - all_fingerprints = set() - - for vote in votes.values(): - all_fingerprints.update(vote.routers.keys()) - - # Finally, compare moria1's votes to maatuska. - - for fingerprint in all_fingerprints: - moria1_vote = votes['moria1'].routers.get(fingerprint) - maatuska_vote = votes['maatuska'].routers.get(fingerprint) - - if not moria1_vote and not maatuska_vote: - print "both moria1 and maatuska haven't voted about %s" % fingerprint - elif not moria1_vote: - print "moria1 hasn't voted about %s" % fingerprint - elif not maatuska_vote: - print "maatuska hasn't voted about %s" % fingerprint - elif 'Running' in moria1_vote.flags and 'Running' not in maatuska_vote.flags: - print "moria1 has the Running flag but maatuska doesn't: %s" % fingerprint - elif 'Running' in maatuska_vote.flags and 'Running' not in moria1_vote.flags: - print "maatuska has the Running flag but moria1 doesn't: %s" % fingerprint +.. literalinclude:: /_static/example/compare_flags.py + :caption: `[Download] <../../_static/example/compare_flags.py>`__ + :language: python :: diff --git a/docs/tutorials/examples/exit_used.rst b/docs/tutorials/examples/exit_used.rst index 26a9a63..095cd3c 100644 --- a/docs/tutorials/examples/exit_used.rst +++ b/docs/tutorials/examples/exit_used.rst @@ -11,43 +11,9 @@ out what exit you're using? Here's a simple script that prints information about the exits used to service the requests going through Tor... -:: - - import functools - - from stem import StreamStatus - from stem.control import EventType, Controller - - def main(): - print "Tracking requests for tor exits. Press 'enter' to end." - print - - with Controller.from_port() as controller: - controller.authenticate() - - stream_listener = functools.partial(stream_event, controller) - controller.add_event_listener(stream_listener, EventType.STREAM) - - raw_input() # wait for user to press enter - - - def stream_event(controller, event): - if event.status == StreamStatus.SUCCEEDED and event.circ_id: - circ = controller.get_circuit(event.circ_id) - - exit_fingerprint = circ.path[-1][0] - exit_relay = controller.get_network_status(exit_fingerprint) - - print "Exit relay for our connection to %s" % (event.target) - print " address: %s:%i" % (exit_relay.address, exit_relay.or_port) - print " fingerprint: %s" % exit_relay.fingerprint - print " nickname: %s" % exit_relay.nickname - print " locale: %s" % controller.get_info("ip-to-country/%s" % exit_relay.address, 'unknown') - print - - - if __name__ == '__main__': - main() +.. literalinclude:: /_static/example/exit_used.py + :caption: `[Download] <../../_static/example/exit_used.py>`__ + :language: python Now if you make a request over Tor... diff --git a/docs/tutorials/examples/list_circuits.rst b/docs/tutorials/examples/list_circuits.rst index 800b945..298089b 100644 --- a/docs/tutorials/examples/list_circuits.rst +++ b/docs/tutorials/examples/list_circuits.rst @@ -7,29 +7,9 @@ List Circuits Tor creates new circuits and tears down old ones on your behalf, so how can you get information about circuits Tor currently has available? -:: - - from stem import CircStatus - from stem.control import Controller - - with Controller.from_port(port = 9051) as controller: - controller.authenticate() - - for circ in sorted(controller.get_circuits()): - if circ.status != CircStatus.BUILT: - continue - - print - print "Circuit %s (%s)" % (circ.id, circ.purpose) - - for i, entry in enumerate(circ.path): - div = '+' if (i == len(circ.path) - 1) else '|' - fingerprint, nickname = entry - - desc = controller.get_network_status(fingerprint, None) - address = desc.address if desc else 'unknown' - - print " %s- %s (%s, %s)" % (div, fingerprint, nickname, address) +.. literalinclude:: /_static/example/list_circuits.py + :caption: `[Download] <../../_static/example/list_circuits.py>`__ + :language: python :: diff --git a/docs/tutorials/examples/outdated_relays.rst b/docs/tutorials/examples/outdated_relays.rst index 283b94f..e7d4cb2 100644 --- a/docs/tutorials/examples/outdated_relays.rst +++ b/docs/tutorials/examples/outdated_relays.rst @@ -8,27 +8,9 @@ Time marches on. Tor makes new releases, and at some point needs to drop support for old ones. Below is the script we used on :trac:`9476` to reach out to relay operators that needed to upgrade. -:: - - from stem.descriptor.remote import DescriptorDownloader - from stem.version import Version - - downloader = DescriptorDownloader() - count, with_contact = 0, 0 - - print "Checking for outdated relays..." - print - - for desc in downloader.get_server_descriptors(): - if desc.tor_version < Version('0.2.3.0'): - count += 1 - - if desc.contact: - print ' %-15s %s' % (desc.tor_version, desc.contact.decode("utf-8", "replace")) - with_contact += 1 - - print - print "%i outdated relays found, %i had contact information" % (count, with_contact) +.. literalinclude:: /_static/example/outdated_relays.py + :caption: `[Download] <../../_static/example/outdated_relays.py>`__ + :language: python :: diff --git a/docs/tutorials/examples/persisting_a_consensus.rst b/docs/tutorials/examples/persisting_a_consensus.rst index d9c681b..6e51fe7 100644 --- a/docs/tutorials/examples/persisting_a_consensus.rst +++ b/docs/tutorials/examples/persisting_a_consensus.rst @@ -30,16 +30,9 @@ So how do we get it? Just tell Stem that's what you want. The :class:`~stem.descriptor.__init__.DocumentHandler` tells Stem how to read the consensus. For example, to write the consensus simply do the following... -:: - - from stem.descriptor import DocumentHandler - from stem.descriptor.remote import DescriptorDownloader - - downloader = DescriptorDownloader() - consensus = downloader.get_consensus(document_handler = DocumentHandler.DOCUMENT).run()[0] - - with open('/tmp/descriptor_dump', 'w') as descriptor_file: - descriptor_file.write(str(consensus)) +.. literalinclude:: /_static/example/persisting_a_consensus.py + :caption: `[Download] <../../_static/example/persisting_a_consensus.py>`__ + :language: python Our *consensus* here is the current :class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`. The @@ -58,15 +51,6 @@ Our *consensus* here is the current You can then read it back with :func:`~stem.descriptor.__init__.parse_file`... -:: - - from stem.descriptor import DocumentHandler, parse_file - - consensus = next(parse_file( - '/tmp/descriptor_dump', - descriptor_type = 'network-status-consensus-3 1.0', - document_handler = DocumentHandler.DOCUMENT, - )) - - for fingerprint, relay in consensus.routers.items(): - print "%s: %s" % (fingerprint, relay.nickname) +.. literalinclude:: /_static/example/persisting_a_consensus_with_parse_file.py + :caption: `[Download] <../../_static/example/persisting_a_consensus_with_parse_file.py>`__ + :language: python diff --git a/docs/tutorials/examples/votes_by_bandwidth_authorities.rst b/docs/tutorials/examples/votes_by_bandwidth_authorities.rst index c413c96..df78ca2 100644 --- a/docs/tutorials/examples/votes_by_bandwidth_authorities.rst +++ b/docs/tutorials/examples/votes_by_bandwidth_authorities.rst @@ -16,37 +16,9 @@ more complicated than that, but that's the general idea. Bandwidth authorities include their measurements in their votes. The following gets their current votes then prints how many relays it had a measurement for. -:: - - from stem.descriptor import remote - - # request votes from all the bandwidth authorities - - queries = {} - downloader = remote.DescriptorDownloader() - - for authority in remote.get_authorities().values(): - if authority.is_bandwidth_authority: - queries[authority.nickname] = downloader.query( - '/tor/status-vote/current/authority', - endpoints = [(authority.address, authority.dir_port)], - ) - - for authority_name, query in queries.items(): - try: - print "Getting %s's vote from %s:" % (authority_name, query.download_url) - - measured, unmeasured = 0, 0 - - for desc in query.run(): - if desc.measured: - measured += 1 - else: - unmeasured += 1 - - print ' %i measured entries and %i unmeasured' % (measured, unmeasured) - except Exception as exc: - print " failed to get the vote (%s)" % exc +.. literalinclude:: /_static/example/votes_by_bandwidth_authorities.py + :caption: `[Download] <../../_static/example/votes_by_bandwidth_authorities.py>`__ + :language: python ::

1 0

[translation/torbutton-abouttorproperties_completed] Update translations for torbutton-abouttorproperties_completed
by translation＠torproject.org 25 May '15

25 May '15

commit 8cfcde386214ebebea175603d60cb5313590eef6 Author: Translation commit bot <translation(a)torproject.org> Date: Mon May 25 14:17:01 2015 +0000 Update translations for torbutton-abouttorproperties_completed --- nl/abouttor.properties | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/nl/abouttor.properties b/nl/abouttor.properties new file mode 100644 index 0000000..63c49fa --- /dev/null +++ b/nl/abouttor.properties @@ -0,0 +1,21 @@ +# Copyright (c) 2014, The Tor Project, Inc. +# See LICENSE for licensing information. +# vim: set sw=2 sts=2 ts=8 et: + +aboutTor.searchSP.privacy=<a href="%1$S">Veilig</a> zoeken met <a href="%2$S">Startpage</a>. +# The following string is a link which replaces %1$S above. +aboutTor.searchSP.privacy.link=https://startpage.com/ned/protect-privacy.html +# The following string is a link which replaces %2$S above. +aboutTor.searchSP.search.link=https://startpage.com/ + +aboutTor.searchDDG.privacy=<a href="%1$S">Veilig</a> zoeken met <a href="%2$S">DuckDuckGo</a>. +# The following string is a link which replaces %1$S above. +aboutTor.searchDDG.privacy.link=https://duckduckgo.com/privacy.html +# The following string is a link which replaces %2$S above. +aboutTor.searchDDG.search.link=https://duckduckgo.com/ + +aboutTor.searchDC.privacy=<a href="%1$S">Veilig</a> zoeken met <a href="%2$S">Disconnect.me</a>. +# The following string is a link which replaces %1$S above. +aboutTor.searchDC.privacy.link=https://disconnect.me/privacy +# The following string is a link which replaces %2$S above. +aboutTor.searchDC.search.link=https://search.disconnect.me/

1 0

[translation/torbutton-abouttorproperties] Update translations for torbutton-abouttorproperties
by translation＠torproject.org 25 May '15

25 May '15

commit 3426bc9ee463473e9b7308dbd86eb0e0da4cf3f9 Author: Translation commit bot <translation(a)torproject.org> Date: Mon May 25 14:16:57 2015 +0000 Update translations for torbutton-abouttorproperties --- nl/abouttor.properties | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/nl/abouttor.properties b/nl/abouttor.properties index d68e8c1..63c49fa 100644 --- a/nl/abouttor.properties +++ b/nl/abouttor.properties @@ -2,19 +2,19 @@ # See LICENSE for licensing information. # vim: set sw=2 sts=2 ts=8 et: -aboutTor.searchSP.privacy=Search <a href="%1$S">securely</a> with <a href="%2$S">Startpage</a>. +aboutTor.searchSP.privacy=<a href="%1$S">Veilig</a> zoeken met <a href="%2$S">Startpage</a>. # The following string is a link which replaces %1$S above. aboutTor.searchSP.privacy.link=https://startpage.com/ned/protect-privacy.ht… # The following string is a link which replaces %2$S above. aboutTor.searchSP.search.link=https://startpage.com/ -aboutTor.searchDDG.privacy=Search <a href="%1$S">securely</a> with <a href="%2$S">DuckDuckGo</a>. +aboutTor.searchDDG.privacy=<a href="%1$S">Veilig</a> zoeken met <a href="%2$S">DuckDuckGo</a>. # The following string is a link which replaces %1$S above. aboutTor.searchDDG.privacy.link=https://duckduckgo.com/privacy.html # The following string is a link which replaces %2$S above. aboutTor.searchDDG.search.link=https://duckduckgo.com/ -aboutTor.searchDC.privacy=Search <a href="%1$S">securely</a> with <a href="%2$S">Disconnect.me</a>. +aboutTor.searchDC.privacy=<a href="%1$S">Veilig</a> zoeken met <a href="%2$S">Disconnect.me</a>. # The following string is a link which replaces %1$S above. aboutTor.searchDC.privacy.link=https://disconnect.me/privacy # The following string is a link which replaces %2$S above.

1 0

[translation/torbutton-aboutdialogdtd_completed] Update translations for torbutton-aboutdialogdtd_completed
by translation＠torproject.org 25 May '15

25 May '15

commit 4ccff2bf713918ab1358e8fea0f397506be71dd4 Author: Translation commit bot <translation(a)torproject.org> Date: Mon May 25 14:16:53 2015 +0000 Update translations for torbutton-aboutdialogdtd_completed --- nl/aboutdialog.dtd | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/nl/aboutdialog.dtd b/nl/aboutdialog.dtd new file mode 100644 index 0000000..b97f2b1 --- /dev/null +++ b/nl/aboutdialog.dtd @@ -0,0 +1,19 @@ +<!ENTITY project.start "&brandShortName; wordt ontwikkeld door"> + +<!ENTITY project.tpoLink "het &vendorShortName;"> +<!ENTITY project.end ", een non-profit die zich inzet om uw privacy en vrijheid online te verdedigen."> + +<!ENTITY help.start "Wilt u meehelpen?"> + +<!ENTITY help.donateLink "Doneer"> +<!ENTITY help.or "of"> + +<!ENTITY help.getInvolvedLink "doe mee"> +<!ENTITY help.end "!"> + +<!ENTITY bottomLinks.questions "Vragen?"> + +<!ENTITY bottomLinks.grow "Help het Tor-netwerk te groeien."> + +<!ENTITY bottomLinks.license "Licentie-informatie"> +<!ENTITY tor.TrademarkStatement "'Tor' en het 'Ui-logo' zijn geregistreerde handelsmerken van het Tor Project, Inc.">

1 0