[tor-commits] [stem/master] Rewrite 'Where can I get the current descriptors?' tutorial entry

[atagar at torproject.org]

commit d37f292d9f7dc401eef743c5cc611490c8767d60
Author: Damian Johnson <atagar at 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',
     })]