commit 4b667d253258bc0363c82e81d0689fc0eff416e9 Author: Damian Johnson atagar@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