upgrade

Makefile

@@ -1,5 +1,10 @@
 LOCAL_DOCTEST=/usr/local/bin/toxcore_run_doctest3.bash
 DOCTEST=${LOCAL_DOCTEST}
+MOD=stem_examples
+
+
+check::
+	sh python3.sh -c "import ${MOD}"
 
 lint::
 	sh .pylint.sh
@@ -7,6 +12,15 @@ lint::
 rsync::
 	bash .rsync.sh
 
+pyi::
+	echo FixMe
+
 doctest:
 	export PYTHONPATH=${PWD}
-	${DOCTEST} stem_examples.txt
+	${DOCTEST} ${MOD].txt
+
+veryclean:: clean
+	rm -rf build dist __pycache__ .pylint.err .pylint.out
+
+clean::
+	find . -name \*~ -delete

README.md

@@ -1,6 +1,90 @@
-# stem_examples
+## stem_examples
+
+Examples of using the Python stem library to query the state of a running tor.
+
+You can set TOR_CONTROLLER_PASSWORD in the environment if your tor control port
+requires a password.
+
+* check_digests
+* compare_flags
+* exit_used
+* introduction_points
+* list_circuits
+* mappaddress
+* outdated_relays
+* relay_connections
+* tor_bootstrap_check
+
+### check_digests
+
+### compare_flags 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.
+
+https://stem.torproject.org/tutorials/examples/compare_flags.html
+
+### exit_used Exit Used
+
+Determine The Exit You're Using
 
-stem examples
 https://stem.torproject.org/tutorials/examples/exit_used.html
-http://vt5hknv6sblkgf22.onion/tutorials/examples/list_circuits.html
-http://vt5hknv6sblkgf22.onion/tutorials/examples/relay_connections.html
+
+### introduction_points Introduction Points
+
+This script tests if you can reach a hidden service, passed as an onion address
+as an argument. If no argument is given, 3 common onion sites are tested:
+Facebook, DuckDuckGo, and .
+
+https://stem.torproject.org/tutorials/over_the_river.html
+
+### list_circuits 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?
+https://stem.torproject.org/tutorials/examples/list_circuits.html
+
+### mappaddress
+
+### outdated_relays List Outdated Relays
+
+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 ticket 9476
+to reach out to relay operators that needed to upgrade.
+
+https://stem.torproject.org/tutorials/examples/outdated_relays.html
+
+### relay_connections Connection Summary
+
+The following provides a summary of your relay's inbound and outbound connections.
+
+To use this you must set DisableDebuggerAttachment 0 in your
+torrc. Otherwise connection information will be unavailable.
+
+https://stem.torproject.org/tutorials/examples/relay_connections.html
+
+### Download Tor Descriptors
+
+Tor relays provide a mirror for the tor relay descriptors it has
+cached. These are available from its ORPort using Tor's wire protocol,
+and optionally with http as well from a DirPort.
+
+https://stem.torproject.org/tutorials/examples/download_descriptor.html
+
+### Votes by Bandwidth Authorities
+
+Tor takes into account a relay's throughput when picking a route through the Tor network for its circuits. That is to say large, fast relays receive more traffic than small ones since they can better service the load.
+
+To determine a relay's throughput special authorities, called bandwidth authorities,
+take periodic measurements using them. The lifecycle of new Tor relays
+is a bit more complicated than that, butthat'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.
+
+https://stem.torproject.org/tutorials/examples/votes_by_bandwidth_authorities.html
+
+## tor_bootstrap_check
+
+A script by adrelanos@riseup.net to check what percentage of boostrapping
+tor is at.

src/stem_examples/Makefile

@@ -0,0 +1,24 @@
+PYTHON_EXE_MSYS=/usr/local/bin/python3.sh
+PYLINT_EXE_MSYS=/usr/local/bin/toxcore_pylint3.bash
+
+lint.phantompy::
+	${PYLINT_EXE_MSYS} lookupdns.py qasync_phantompy.py phantompy.py support_phantompy.py 
+
+lint.badexits::
+	${PYLINT_EXE_MSYS} exclude_badExits.py  \
+		support_onions.py trustor_poc.py 
+	isort -c -diff exclude_badExits.py \
+		support_onions.py trustor_poc.py 
+
+lint::
+	sh .pylint.sh
+
+refresh:: ../../exclude_badExits.md
+
+../../exclude_badExits.md::
+	${PYTHON_EXE_MSYS} -c \
+		'import exclude_badExits; print(exclude_badExits.__doc__)' > $@
+	echo "\n## Usage \n\`\`\`\n" >> $@
+	${PYTHON_EXE_MSYS} exclude_badExits.py --help \
+		| sed -e '/^[^uo ]/d' >> $@
+	echo "\n\`\`\`\n" >> $@

src/stem_examples/exit_used.py.dst

@@ -0,0 +1,38 @@
+# -*-mode: python; py-indent-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
+
+#http://vt5hknv6sblkgf22.onion/tutorials/examples/exit_used.html
+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()

src/stem_examples/introduction_points.py.dst

@@ -0,0 +1,11 @@
+from stem.control import Controller
+
+with Controller.from_port(port = 9051) as controller:
+  controller.authenticate()
+  desc = controller.get_hidden_service_descriptor('3g2upl4pq6kufc4m')
+
+  print("DuckDuckGo's introduction points are...\n")
+
+  for introduction_point in desc.introduction_points():
+    print('  %s:%s => %s' % (introduction_point.address, introduction_point.port, introduction_point.identifier))
+# http://vt5hknv6sblkgf22.onion/tutorials/over_the_river.html

src/stem_examples/list_circuits.py.dst

@@ -0,0 +1,25 @@
+# -*-mode: python; py-indent-offset: 2; indent-tabs-mode: nil; coding: utf-8-unix -*-
+
+# http://vt5hknv6sblkgf22.onion/tutorials/examples/list_circuits.html
+from stem import CircStatus
+from stem.control import Controller
+
+# port(port = 9051)
+with Controller.from_socket_file(path='/var/run/tor/control') 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))

src/stem_examples/outdated_relays.py

@@ -1,3 +1,4 @@
+import sys
 
 from stem.descriptor.remote import DescriptorDownloader
 from stem.version import Version