commit d37f292d9f7dc401eef743c5cc611490c8767d60 Author: Damian Johnson <atagar@torproject.org> Date: Thu Sep 6 17:27:18 2018 -0700 Rewrite 'Where can I get the current descriptors?' tutorial entry At first I planned to just add an ORPort example, but on reflection this tutorial section could do with more extensive cleanup. --- docs/_static/example/current_descriptors.py | 2 +- docs/change_log.rst | 2 +- docs/tutorials/mirror_mirror_on_the_wall.rst | 36 +++++++++++++++++++--------- test/unit/tutorial.py | 2 +- 4 files changed, 28 insertions(+), 14 deletions(-) diff --git a/docs/_static/example/current_descriptors.py b/docs/_static/example/current_descriptors.py index 44c9ac3a..7d44c664 100644 --- a/docs/_static/example/current_descriptors.py +++ b/docs/_static/example/current_descriptors.py @@ -1,7 +1,7 @@ import stem.descriptor.remote try: - for desc in stem.descriptor.remote.get_consensus().run(): + for desc in stem.descriptor.remote.get_consensus(): 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/change_log.rst b/docs/change_log.rst index 89a13738..9331890c 100644 --- a/docs/change_log.rst +++ b/docs/change_log.rst @@ -53,7 +53,7 @@ The following are only available within Stem's `git repository * Added a timeout argument to :class:`~stem.control.Controller` methods that could await a response (:trac:`26056`) * Stacktrace if :func:`stem.connection.connect` had a string port argument * More reliable ExitPolicy resolution (:trac:`25739`) - * More reliable caching during configuration changes, especially in multiple-controller situations (:trac:`25821`) + * Fixed cache invalidation when another contorller calls SETCONF (:trac:`25821`) * :func:`~stem.control.COntroller.create_hidden_service` failed when creating services with v2 options (:trac:`27446`) * :func:`~stem.control.Controller.get_info` commonly raised :class:`stem.ProtocolError` when it should provide :class:`stem.OperationFailed` * :func:`~stem.control.Controller.get_microdescriptors` reads descriptors from the control port if available (:spec:`b5396d5`) diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst index 4f020f32..eed4c65c 100644 --- a/docs/tutorials/mirror_mirror_on_the_wall.rst +++ b/docs/tutorials/mirror_mirror_on_the_wall.rst @@ -67,22 +67,36 @@ and so belong to the first camp. Where can I get the current descriptors? ---------------------------------------- -To work Tor needs to have up-to-date information about relays within the -network. As such getting current descriptors is easy: *just download it like -Tor does*. +To work Tor needs up-to-date relay information. As such getting the current +descriptors is easy: *just download it like Tor does*. -The `stem.descriptor.remote <../api/descriptor/remote.html>`_ module downloads -descriptors from the tor directory authorities and mirrors. **Please show -some restraint when doing this**! This adds load to the network, and hence an -irresponsible script can make Tor worse for everyone. - -Listing the current relays in the Tor network is as easy as... +Every tor relay provides an **ORPort** and many provide a **DirPort** as well +which can both be downloaded from using Stem's `stem.descriptor.remote +<../api/descriptor/remote.html>`_ module. Listing relays for instance is as +easy as... .. literalinclude:: /_static/example/current_descriptors.py :language: python -If you want to see what the raw descriptors look like you can also curl this -information from the DirPort of directory authorities and mirrors... +**Please remember that Tor is a shared resource!** If you're going to +contribute much load please consider `running a relay +<https://www.torproject.org/docs/tor-doc-relay.html.en>`_ to offset your use. + +**ORPorts** communicate through the `tor protocol +<https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt>`_, and can be +downloaded from by specifying it as the endpoint... + +.. literalinclude:: /_static/example/descriptor_from_orport.py + :language: python + +**DirPorts** by contrast are simpler and specially designed to offer descriptor +information, but not all relays offer one. If no endpoint is specified we +default to downloading from the DirPorts of tor's directory authorities. + +If you would like to see what raw descriptors look like try curling a relay's +DirPort. Section 6.2 of `tor's directory specification +<https://gitweb.torproject.org/torspec.git/tree/dir-spec.txt>`_ lists the +urls you can try. :: diff --git a/test/unit/tutorial.py b/test/unit/tutorial.py index 662f1db4..c74b1912 100644 --- a/test/unit/tutorial.py +++ b/test/unit/tutorial.py @@ -128,7 +128,7 @@ class TestTutorial(unittest.TestCase): @patch('sys.stdout', new_callable = StringIO) @patch('stem.descriptor.remote.DescriptorDownloader') def test_mirror_mirror_on_the_wall_1(self, downloader_mock, stdout_mock): - downloader_mock().get_consensus().run.return_value = [RouterStatusEntryV2.create({ + downloader_mock().get_consensus.return_value = [RouterStatusEntryV2.create({ 'r': 'caerSidi p1aag7VwarGxqctS7/fS0y5FU+s oQZFLYe9e4A7bOkWKR7TaNxb0JE 2012-08-06 11:19:31 71.35.150.29 9001 0', })]