[tor-commits] [stem/master] Minor tutorial revisions
atagar at torproject.org
atagar at torproject.org
Mon Mar 24 05:36:54 UTC 2014
commit 4b667d253258bc0363c82e81d0689fc0eff416e9
Author: Damian Johnson <atagar at torproject.org>
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
More information about the tor-commits
mailing list