[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Minor tutorial revisions



commit 4b667d253258bc0363c82e81d0689fc0eff416e9
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Sun Mar 23 16:03:19 2014 -0700

    Minor tutorial revisions
    
    Took a quick read through our tutorials. Just minor reordering and rewording.
---
 docs/tutorials/mirror_mirror_on_the_wall.rst |   57 +++++++++++++-------------
 docs/tutorials/to_russia_with_love.rst       |    2 +-
 stem/control.py                              |    2 +-
 3 files changed, 31 insertions(+), 30 deletions(-)

diff --git a/docs/tutorials/mirror_mirror_on_the_wall.rst b/docs/tutorials/mirror_mirror_on_the_wall.rst
index a14e050..918417b 100644
--- a/docs/tutorials/mirror_mirror_on_the_wall.rst
+++ b/docs/tutorials/mirror_mirror_on_the_wall.rst
@@ -6,8 +6,8 @@ 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:`can-i-get-descriptors-from-the-tor-process`
 * :ref:`putting-it-together`
 
 .. _what-is-a-descriptor:
@@ -38,7 +38,7 @@ 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*.
+Tor does*.
 
 The `stem.descriptor.remote <../api/descriptor/remote.html>`_ module downloads
 descriptors from the tor directory authorities and mirrors. **Please show
@@ -59,12 +59,29 @@ Listing the current relays in the Tor network is as easy as...
   except Exception as exc:
     print "Unable to retrieve the consensus: %s" % exc 
 
-.. _can-i-get-descriptors-from-tor:
+.. _where-can-i-get-past-descriptors:
+
+Where can I get past descriptors?
+---------------------------------
+
+Descriptor archives are available on `Tor's metrics site
+<https://metrics.torproject.org/data.html>`_. 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)
+
+.. _can-i-get-descriptors-from-the-tor-process:
 
-Can I get descriptors from Tor?
--------------------------------
+Can I get descriptors from the Tor process?
+-------------------------------------------
 
-If you already have Tor running on your system then it is already getting
+If you already have Tor running on your system then it is already downloading
 descriptors on your behalf. Reusing these is a great way to keep from burdening
 the rest of the Tor network.
 
@@ -102,7 +119,7 @@ the network!
 
   DownloadExtraInfo 1
 
-Now that Tor is happy chugging along up-to-date descriptors are available
+Now that Tor is happy chugging along, up-to-date descriptors are available
 through Tor's control socket...
 
 ::
@@ -124,33 +141,17 @@ through Tor's control socket...
   for desc in parse_file(open("/home/atagar/.tor/cached-consensus")):
     print "found relay %s (%s)" % (desc.nickname, desc.fingerprint)
 
-.. _where-can-i-get-past-descriptors:
-
-Where can I get past descriptors?
----------------------------------
-
-Descriptor archives are available on `Tor's metrics site
-<https://metrics.torproject.org/data.html>`_. 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)
-
 .. _putting-it-together:
 
 Putting it together...
 ----------------------
 
-As discussed above there are three methods for reading descriptors...
+As discussed above there are four methods for reading descriptors...
 
-* With the :class:`~stem.control.Controller` via methods like :func:`~stem.control.Controller.get_server_descriptors` and :func:`~stem.control.Controller.get_network_statuses`.
-* By reading the file directly with :func:`~stem.descriptor.__init__.parse_file`.
-* Reading with the `DescriptorReader <../api/descriptor/reader.html>`_. This is best if you have you want to read everything from a directory or archive.
+* Download descriptors directly with `stem.descriptor.remote <../api/descriptor/remote.html>`_.
+* Read a single file with :func:`~stem.descriptor.__init__.parse_file`.
+* Read multiple files or an archive with the `DescriptorReader <../api/descriptor/reader.html>`_.
+* Requesting them from Tor with :class:`~stem.control.Controller` methods like :func:`~stem.control.Controller.get_server_descriptors` and :func:`~stem.control.Controller.get_network_statuses`.
 
 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
diff --git a/docs/tutorials/to_russia_with_love.rst b/docs/tutorials/to_russia_with_love.rst
index c928c00..e69e828 100644
--- a/docs/tutorials/to_russia_with_love.rst
+++ b/docs/tutorials/to_russia_with_love.rst
@@ -19,7 +19,7 @@ Tor relays are scattered all over the world and, as such, you can pretend to be
 
 Tor makes `configuring your exit locale <https://www.torproject.org/docs/faq.html.en#ChooseEntryExit>`_ easy through the **ExitNodes** torrc option. Note that you don't need a control port (or even Stem) to do this, though they can be useful if you later want to do something more elaborate.
 
-In the following example we're using Stem to `start Tor <../api/process.html>`_, then reading a site through it with `SocksiPy <http://socksipy.sourceforge.net/>`_. This is not always reliable (some relays are lemons) so you may need to run this more than once.
+In the following example we're using Stem to `start Tor <../api/process.html>`_, then read a site through it with `SocksiPy <http://socksipy.sourceforge.net/>`_. This is not always reliable (some relays are lemons) so you may need to run this more than once.
 
 **Do not rely on the following not to leak.** Though it seems to work there may be edge cases that expose your real IP. If you have a suggestion for how to improve this example then please `let me know <https://www.atagar.com/contact/>`_!
 
diff --git a/stem/control.py b/stem/control.py
index 8ea9fe7..bf86135 100644
--- a/stem/control.py
+++ b/stem/control.py
@@ -1482,7 +1482,7 @@ class Controller(BaseController):
     :param list default: items to provide if the query fails
 
     :returns: iterates over
-      :class:`~stem.descriptor.router_status_entry.RouterStatusEntryV3` for
+      :class:`~stem.descriptor.router_status_entry.RouterStatusEntry` for
       relays in the tor network
 
     :raises: :class:`stem.ControllerError` if unable to query tor and no



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits