[tor-commits] [stem/master] Adding remote descriptor fetching to our tutorials

[atagar at torproject.org]

commit d5c02be90b3a9d200773e4e128303bd4cee062a8
Author: Damian Johnson <atagar at torproject.org>
Date:   Mon Aug 26 09:22:50 2013 -0700

    Adding remote descriptor fetching to our tutorials
    
    Replacing the "Where can I get the current descriptors?" subsection with an
    example using the remote descriptor fetching module. This is the simplest way
    for our users to get descriptor data without the headache of piggybacking on a
    tor instance.
---
 docs/tutorials/mirror_mirror_on_the_wall.rst |   32 +++++++++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst
index 02a4433..5b86ba0 100644
--- a/docs/tutorials/mirror_mirror_on_the_wall.rst
+++ b/docs/tutorials/mirror_mirror_on_the_wall.rst
@@ -6,6 +6,7 @@ with what they are and where to get them then you may want to skip to the end.
 
 * :ref:`what-is-a-descriptor`
 * :ref:`where-can-i-get-the-current-descriptors`
+* :ref:`can-i-get-descriptors-from-tor`
 * :ref:`where-can-i-get-past-descriptors`
 * :ref:`putting-it-together`
 
@@ -36,7 +37,36 @@ 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 run tor*.
+network. As such getting 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...
+
+::
+
+  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 
+
+.. _can-i-get-descriptors-from-tor:
+
+Can I get descriptors from Tor?
+-------------------------------
+
+If you already have tor running on your system then it is already getting
+descriptors on your behalf. Reusing these is a great way to keep from burdening
+the rest of the tor network.
 
 Tor only gets the descriptors that it needs by default, so if you're scripting
 against tor you may want to set some of the following in your `torrc