[tor-commits] [stem/master] Adding an example for listing circuit information

[atagar at torproject.org]

commit 55f062fa9770319cf92fdd0d4439a554593a24b8
Author: Damian Johnson <atagar at torproject.org>
Date:   Wed Mar 26 09:57:55 2014 -0700

    Adding an example for listing circuit information
    
    This is an adapted from of the 'How do I get information about my exits?' FAQ
    entry I recently removed. Unlike that example, this provides information about
    the full circuit rather than just the last hop.
---
 docs/contents.rst                                 |    1 +
 docs/tutorials/double_double_toil_and_trouble.rst |    4 ++
 docs/tutorials/examples/list_circuits.rst         |   49 +++++++++++++++++++++
 3 files changed, 54 insertions(+)

diff --git a/docs/contents.rst b/docs/contents.rst
index 4d79639..9555673 100644
--- a/docs/contents.rst
+++ b/docs/contents.rst
@@ -14,6 +14,7 @@ Contents
 
    tutorials/examples/compare_flags
    tutorials/examples/exit_used
+   tutorials/examples/list_circuits
    tutorials/examples/outdated_relays
 
    change_log
diff --git a/docs/tutorials/double_double_toil_and_trouble.rst b/docs/tutorials/double_double_toil_and_trouble.rst
index 7e39eb8..64b2a3c 100644
--- a/docs/tutorials/double_double_toil_and_trouble.rst
+++ b/docs/tutorials/double_double_toil_and_trouble.rst
@@ -56,6 +56,10 @@ Scripts
 Client Usage
 ------------
 
+* `List Circuits <examples/list_circuits.html>`_
+
+  List the path Tor uses for its present circuits.
+
 * `Determine The Exit You're Using <examples/exit_used.html>`_
 
   Tells you the exit used for each Tor connection.
diff --git a/docs/tutorials/examples/list_circuits.rst b/docs/tutorials/examples/list_circuits.rst
new file mode 100644
index 0000000..9f4fb93
--- /dev/null
+++ b/docs/tutorials/examples/list_circuits.rst
@@ -0,0 +1,49 @@
+List Circuits
+=============
+
+Tor creates new circuits and tears down old ones on your behalf, so how can you
+get information about circuits Tor currently has available?
+
+::
+
+  from stem import CircStatus
+  from stem.control import Controller
+
+  with Controller.from_port(port = 9051) as controller:
+    controller.authenticate()
+
+    for circ in sorted(controller.get_circuits()):
+      if circ.status != CircStatus.BUILT:
+        continue
+
+      print
+      print "Circuit %s (%s)" % (circ.id, circ.purpose)
+
+      for i, entry in enumerate(circ.path):
+        div = '+' if (i == len(circ.path) - 1) else '|'
+        fingerprint, nickname = entry
+
+        desc = controller.get_network_status(fingerprint, None)
+        address = desc.address if desc else 'unknown'
+
+        print " %s- %s (%s, %s)" % (div, fingerprint, nickname, address)
+
+::
+
+  % python list_circuits.py 
+
+  Circuit 4 (GENERAL)
+   |- B1FA7D51B8B6F0CB585D944F450E7C06EDE7E44C (ByTORAndTheSnowDog, 173.209.180.61)
+   |- 0DD9935C5E939CFA1E07B8DDA6D91C1A2A9D9338 (afo02, 87.238.194.176)
+   +- DB3B1CFBD3E4D97B84B548ADD5B9A31451EEC4CC (edwardsnowden3, 109.163.234.10)
+
+  Circuit 6 (GENERAL)
+   |- B1FA7D51B8B6F0CB585D944F450E7C06EDE7E44C (ByTORAndTheSnowDog, 173.209.180.61)
+   |- EC01CB4766BADC1611678555CE793F2A7EB2D723 (sprockets, 46.165.197.96)
+   +- 9EA317EECA56BDF30CAEB208A253FB456EDAB1A0 (bolobolo1, 96.47.226.20)
+
+  Circuit 10 (GENERAL)
+   |- B1FA7D51B8B6F0CB585D944F450E7C06EDE7E44C (ByTORAndTheSnowDog, 173.209.180.61)
+   |- 00C2C2A16AEDB51D5E5FB7D6168FC66B343D822F (ph3x, 86.59.119.83)
+   +- 65242C91BFF30F165DA4D132C81A9EBA94B71D62 (torexit16, 176.67.169.171)
+