[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[tor-commits] [stem/master] Added downloadable tutorial examples
commit 1a26c5f654e783b649611b457149168105593e9a
Author: Sambuddha Basu <sambuddhabasu1@xxxxxxxxx>
Date: Mon May 25 08:31:59 2015 +0400
Added downloadable tutorial examples
---
docs/_static/example/compare_flags.py | 41 +++++++++++++++++
docs/_static/example/exit_used.py | 35 +++++++++++++++
docs/_static/example/list_circuits.py | 21 +++++++++
docs/_static/example/outdated_relays.py | 19 ++++++++
docs/_static/example/persisting_a_consensus.py | 8 ++++
.../persisting_a_consensus_with_parse_file.py | 10 +++++
.../example/votes_by_bandwidth_authorities.py | 29 ++++++++++++
docs/tutorials/examples/compare_flags.rst | 46 ++------------------
docs/tutorials/examples/exit_used.rst | 40 ++---------------
docs/tutorials/examples/list_circuits.rst | 26 ++---------
docs/tutorials/examples/outdated_relays.rst | 24 ++--------
docs/tutorials/examples/persisting_a_consensus.rst | 28 +++---------
.../examples/votes_by_bandwidth_authorities.rst | 34 ++-------------
13 files changed, 184 insertions(+), 177 deletions(-)
diff --git a/docs/_static/example/compare_flags.py b/docs/_static/example/compare_flags.py
new file mode 100644
index 0000000..a668e11
--- /dev/null
+++ b/docs/_static/example/compare_flags.py
@@ -0,0 +1,41 @@
+from stem.descriptor import DocumentHandler, remote
+
+# Query all authority votes asynchronously.
+
+downloader = remote.DescriptorDownloader(document_handler = DocumentHandler.DOCUMENT)
+queries = {}
+
+for name, authority in remote.get_authorities().items():
+ if authority.v3ident is None:
+ continue # authority doens't vote if it lacks a v3ident
+
+ queries[name] = downloader.get_vote(authority)
+
+# Wait for the votes to finish being downloaded, this produces a dictionary of
+# authority nicknames to their vote.
+
+votes = dict((name, query.run()[0]) for (name, query) in queries.items())
+
+# Get a superset of all the fingerprints in all the votes.
+
+all_fingerprints = set()
+
+for vote in votes.values():
+ all_fingerprints.update(vote.routers.keys())
+
+# Finally, compare moria1's votes to maatuska.
+
+for fingerprint in all_fingerprints:
+ moria1_vote = votes['moria1'].routers.get(fingerprint)
+ maatuska_vote = votes['maatuska'].routers.get(fingerprint)
+
+ if not moria1_vote and not maatuska_vote:
+ print "both moria1 and maatuska haven't voted about %s" % fingerprint
+ elif not moria1_vote:
+ print "moria1 hasn't voted about %s" % fingerprint
+ elif not maatuska_vote:
+ print "maatuska hasn't voted about %s" % fingerprint
+ elif 'Running' in moria1_vote.flags and 'Running' not in maatuska_vote.flags:
+ print "moria1 has the Running flag but maatuska doesn't: %s" % fingerprint
+ elif 'Running' in maatuska_vote.flags and 'Running' not in moria1_vote.flags:
+ print "maatuska has the Running flag but moria1 doesn't: %s" % fingerprint
diff --git a/docs/_static/example/exit_used.py b/docs/_static/example/exit_used.py
new file mode 100644
index 0000000..7ecd19a
--- /dev/null
+++ b/docs/_static/example/exit_used.py
@@ -0,0 +1,35 @@
+import functools
+
+from stem import StreamStatus
+from stem.control import EventType, Controller
+
+def main():
+ print "Tracking requests for tor exits. Press 'enter' to end."
+ print
+
+ with Controller.from_port() as controller:
+ controller.authenticate()
+
+ stream_listener = functools.partial(stream_event, controller)
+ controller.add_event_listener(stream_listener, EventType.STREAM)
+
+ raw_input() # wait for user to press enter
+
+
+def stream_event(controller, event):
+ if event.status == StreamStatus.SUCCEEDED and event.circ_id:
+ circ = controller.get_circuit(event.circ_id)
+
+ exit_fingerprint = circ.path[-1][0]
+ exit_relay = controller.get_network_status(exit_fingerprint)
+
+ print "Exit relay for our connection to %s" % (event.target)
+ print " address: %s:%i" % (exit_relay.address, exit_relay.or_port)
+ print " fingerprint: %s" % exit_relay.fingerprint
+ print " nickname: %s" % exit_relay.nickname
+ print " locale: %s" % controller.get_info("ip-to-country/%s" % exit_relay.address, 'unknown')
+ print
+
+
+if __name__ == '__main__':
+ main()
diff --git a/docs/_static/example/list_circuits.py b/docs/_static/example/list_circuits.py
new file mode 100644
index 0000000..61fdd5e
--- /dev/null
+++ b/docs/_static/example/list_circuits.py
@@ -0,0 +1,21 @@
+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)
diff --git a/docs/_static/example/outdated_relays.py b/docs/_static/example/outdated_relays.py
new file mode 100644
index 0000000..a78c6ee
--- /dev/null
+++ b/docs/_static/example/outdated_relays.py
@@ -0,0 +1,19 @@
+from stem.descriptor.remote import DescriptorDownloader
+from stem.version import Version
+
+downloader = DescriptorDownloader()
+count, with_contact = 0, 0
+
+print "Checking for outdated relays..."
+print
+
+for desc in downloader.get_server_descriptors():
+ if desc.tor_version < Version('0.2.3.0'):
+ count += 1
+
+ if desc.contact:
+ print ' %-15s %s' % (desc.tor_version, desc.contact.decode("utf-8", "replace"))
+ with_contact += 1
+
+print
+print "%i outdated relays found, %i had contact information" % (count, with_contact)
diff --git a/docs/_static/example/persisting_a_consensus.py b/docs/_static/example/persisting_a_consensus.py
new file mode 100644
index 0000000..55b17bd
--- /dev/null
+++ b/docs/_static/example/persisting_a_consensus.py
@@ -0,0 +1,8 @@
+from stem.descriptor import DocumentHandler
+from stem.descriptor.remote import DescriptorDownloader
+
+downloader = DescriptorDownloader()
+consensus = downloader.get_consensus(document_handler = DocumentHandler.DOCUMENT).run()[0]
+
+with open('/tmp/descriptor_dump', 'w') as descriptor_file:
+ descriptor_file.write(str(consensus))
diff --git a/docs/_static/example/persisting_a_consensus_with_parse_file.py b/docs/_static/example/persisting_a_consensus_with_parse_file.py
new file mode 100644
index 0000000..bbec73a
--- /dev/null
+++ b/docs/_static/example/persisting_a_consensus_with_parse_file.py
@@ -0,0 +1,10 @@
+from stem.descriptor import DocumentHandler, parse_file
+
+consensus = next(parse_file(
+ '/tmp/descriptor_dump',
+ descriptor_type = 'network-status-consensus-3 1.0',
+ document_handler = DocumentHandler.DOCUMENT,
+))
+
+for fingerprint, relay in consensus.routers.items():
+ print "%s: %s" % (fingerprint, relay.nickname)
diff --git a/docs/_static/example/votes_by_bandwidth_authorities.py b/docs/_static/example/votes_by_bandwidth_authorities.py
new file mode 100644
index 0000000..e957be5
--- /dev/null
+++ b/docs/_static/example/votes_by_bandwidth_authorities.py
@@ -0,0 +1,29 @@
+from stem.descriptor import remote
+
+# request votes from all the bandwidth authorities
+
+queries = {}
+downloader = remote.DescriptorDownloader()
+
+for authority in remote.get_authorities().values():
+ if authority.is_bandwidth_authority:
+ queries[authority.nickname] = downloader.query(
+ '/tor/status-vote/current/authority',
+ endpoints = [(authority.address, authority.dir_port)],
+ )
+
+for authority_name, query in queries.items():
+ try:
+ print "Getting %s's vote from %s:" % (authority_name, query.download_url)
+
+ measured, unmeasured = 0, 0
+
+ for desc in query.run():
+ if desc.measured:
+ measured += 1
+ else:
+ unmeasured += 1
+
+ print ' %i measured entries and %i unmeasured' % (measured, unmeasured)
+ except Exception as exc:
+ print " failed to get the vote (%s)" % exc
diff --git a/docs/tutorials/examples/compare_flags.rst b/docs/tutorials/examples/compare_flags.rst
index 07a4126..3ea6143 100644
--- a/docs/tutorials/examples/compare_flags.rst
+++ b/docs/tutorials/examples/compare_flags.rst
@@ -7,49 +7,9 @@ Comparing Directory Authority Flags
Compares the votes of two directory authorities, in this case moria1 and
maatuska, with a special interest in the 'Running' flag.
-::
-
- from stem.descriptor import DocumentHandler, remote
-
- # Query all authority votes asynchronously.
-
- downloader = remote.DescriptorDownloader(document_handler = DocumentHandler.DOCUMENT)
- queries = {}
-
- for name, authority in remote.get_authorities().items():
- if authority.v3ident is None:
- continue # authority doens't vote if it lacks a v3ident
-
- queries[name] = downloader.get_vote(authority)
-
- # Wait for the votes to finish being downloaded, this produces a dictionary of
- # authority nicknames to their vote.
-
- votes = dict((name, query.run()[0]) for (name, query) in queries.items())
-
- # Get a superset of all the fingerprints in all the votes.
-
- all_fingerprints = set()
-
- for vote in votes.values():
- all_fingerprints.update(vote.routers.keys())
-
- # Finally, compare moria1's votes to maatuska.
-
- for fingerprint in all_fingerprints:
- moria1_vote = votes['moria1'].routers.get(fingerprint)
- maatuska_vote = votes['maatuska'].routers.get(fingerprint)
-
- if not moria1_vote and not maatuska_vote:
- print "both moria1 and maatuska haven't voted about %s" % fingerprint
- elif not moria1_vote:
- print "moria1 hasn't voted about %s" % fingerprint
- elif not maatuska_vote:
- print "maatuska hasn't voted about %s" % fingerprint
- elif 'Running' in moria1_vote.flags and 'Running' not in maatuska_vote.flags:
- print "moria1 has the Running flag but maatuska doesn't: %s" % fingerprint
- elif 'Running' in maatuska_vote.flags and 'Running' not in moria1_vote.flags:
- print "maatuska has the Running flag but moria1 doesn't: %s" % fingerprint
+.. literalinclude:: /_static/example/compare_flags.py
+ :caption: `[Download] <../../_static/example/compare_flags.py>`__
+ :language: python
::
diff --git a/docs/tutorials/examples/exit_used.rst b/docs/tutorials/examples/exit_used.rst
index 26a9a63..095cd3c 100644
--- a/docs/tutorials/examples/exit_used.rst
+++ b/docs/tutorials/examples/exit_used.rst
@@ -11,43 +11,9 @@ out what exit you're using?
Here's a simple script that prints information about the exits used to service
the requests going through Tor...
-::
-
- import functools
-
- from stem import StreamStatus
- from stem.control import EventType, Controller
-
- def main():
- print "Tracking requests for tor exits. Press 'enter' to end."
- print
-
- with Controller.from_port() as controller:
- controller.authenticate()
-
- stream_listener = functools.partial(stream_event, controller)
- controller.add_event_listener(stream_listener, EventType.STREAM)
-
- raw_input() # wait for user to press enter
-
-
- def stream_event(controller, event):
- if event.status == StreamStatus.SUCCEEDED and event.circ_id:
- circ = controller.get_circuit(event.circ_id)
-
- exit_fingerprint = circ.path[-1][0]
- exit_relay = controller.get_network_status(exit_fingerprint)
-
- print "Exit relay for our connection to %s" % (event.target)
- print " address: %s:%i" % (exit_relay.address, exit_relay.or_port)
- print " fingerprint: %s" % exit_relay.fingerprint
- print " nickname: %s" % exit_relay.nickname
- print " locale: %s" % controller.get_info("ip-to-country/%s" % exit_relay.address, 'unknown')
- print
-
-
- if __name__ == '__main__':
- main()
+.. literalinclude:: /_static/example/exit_used.py
+ :caption: `[Download] <../../_static/example/exit_used.py>`__
+ :language: python
Now if you make a request over Tor...
diff --git a/docs/tutorials/examples/list_circuits.rst b/docs/tutorials/examples/list_circuits.rst
index 800b945..298089b 100644
--- a/docs/tutorials/examples/list_circuits.rst
+++ b/docs/tutorials/examples/list_circuits.rst
@@ -7,29 +7,9 @@ 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)
+.. literalinclude:: /_static/example/list_circuits.py
+ :caption: `[Download] <../../_static/example/list_circuits.py>`__
+ :language: python
::
diff --git a/docs/tutorials/examples/outdated_relays.rst b/docs/tutorials/examples/outdated_relays.rst
index 283b94f..e7d4cb2 100644
--- a/docs/tutorials/examples/outdated_relays.rst
+++ b/docs/tutorials/examples/outdated_relays.rst
@@ -8,27 +8,9 @@ Time marches on. Tor makes new releases, and at some point needs to drop
support for old ones. Below is the script we used on :trac:`9476` to reach out
to relay operators that needed to upgrade.
-::
-
- from stem.descriptor.remote import DescriptorDownloader
- from stem.version import Version
-
- downloader = DescriptorDownloader()
- count, with_contact = 0, 0
-
- print "Checking for outdated relays..."
- print
-
- for desc in downloader.get_server_descriptors():
- if desc.tor_version < Version('0.2.3.0'):
- count += 1
-
- if desc.contact:
- print ' %-15s %s' % (desc.tor_version, desc.contact.decode("utf-8", "replace"))
- with_contact += 1
-
- print
- print "%i outdated relays found, %i had contact information" % (count, with_contact)
+.. literalinclude:: /_static/example/outdated_relays.py
+ :caption: `[Download] <../../_static/example/outdated_relays.py>`__
+ :language: python
::
diff --git a/docs/tutorials/examples/persisting_a_consensus.rst b/docs/tutorials/examples/persisting_a_consensus.rst
index d9c681b..6e51fe7 100644
--- a/docs/tutorials/examples/persisting_a_consensus.rst
+++ b/docs/tutorials/examples/persisting_a_consensus.rst
@@ -30,16 +30,9 @@ So how do we get it? Just tell Stem that's what you want. The
:class:`~stem.descriptor.__init__.DocumentHandler` tells Stem how to read the
consensus. For example, to write the consensus simply do the following...
-::
-
- from stem.descriptor import DocumentHandler
- from stem.descriptor.remote import DescriptorDownloader
-
- downloader = DescriptorDownloader()
- consensus = downloader.get_consensus(document_handler = DocumentHandler.DOCUMENT).run()[0]
-
- with open('/tmp/descriptor_dump', 'w') as descriptor_file:
- descriptor_file.write(str(consensus))
+.. literalinclude:: /_static/example/persisting_a_consensus.py
+ :caption: `[Download] <../../_static/example/persisting_a_consensus.py>`__
+ :language: python
Our *consensus* here is the current
:class:`~stem.descriptor.networkstatus.NetworkStatusDocumentV3`. The
@@ -58,15 +51,6 @@ Our *consensus* here is the current
You can then read it back with :func:`~stem.descriptor.__init__.parse_file`...
-::
-
- from stem.descriptor import DocumentHandler, parse_file
-
- consensus = next(parse_file(
- '/tmp/descriptor_dump',
- descriptor_type = 'network-status-consensus-3 1.0',
- document_handler = DocumentHandler.DOCUMENT,
- ))
-
- for fingerprint, relay in consensus.routers.items():
- print "%s: %s" % (fingerprint, relay.nickname)
+.. literalinclude:: /_static/example/persisting_a_consensus_with_parse_file.py
+ :caption: `[Download] <../../_static/example/persisting_a_consensus_with_parse_file.py>`__
+ :language: python
diff --git a/docs/tutorials/examples/votes_by_bandwidth_authorities.rst b/docs/tutorials/examples/votes_by_bandwidth_authorities.rst
index c413c96..df78ca2 100644
--- a/docs/tutorials/examples/votes_by_bandwidth_authorities.rst
+++ b/docs/tutorials/examples/votes_by_bandwidth_authorities.rst
@@ -16,37 +16,9 @@ more complicated than that, but that's the general idea.
Bandwidth authorities include their measurements in their votes. The following
gets their current votes then prints how many relays it had a measurement for.
-::
-
- from stem.descriptor import remote
-
- # request votes from all the bandwidth authorities
-
- queries = {}
- downloader = remote.DescriptorDownloader()
-
- for authority in remote.get_authorities().values():
- if authority.is_bandwidth_authority:
- queries[authority.nickname] = downloader.query(
- '/tor/status-vote/current/authority',
- endpoints = [(authority.address, authority.dir_port)],
- )
-
- for authority_name, query in queries.items():
- try:
- print "Getting %s's vote from %s:" % (authority_name, query.download_url)
-
- measured, unmeasured = 0, 0
-
- for desc in query.run():
- if desc.measured:
- measured += 1
- else:
- unmeasured += 1
-
- print ' %i measured entries and %i unmeasured' % (measured, unmeasured)
- except Exception as exc:
- print " failed to get the vote (%s)" % exc
+.. literalinclude:: /_static/example/votes_by_bandwidth_authorities.py
+ :caption: `[Download] <../../_static/example/votes_by_bandwidth_authorities.py>`__
+ :language: python
::
_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits