[tor-commits] [stem/master] Moving tutorial to dedicated page
atagar at torproject.org
atagar at torproject.org
Mon Oct 15 16:17:05 UTC 2012
commit 8c767d35514ca345d051c94246668e97151d1c73
Author: Damian Johnson <atagar at torproject.org>
Date: Sun Oct 14 18:09:09 2012 -0700
Moving tutorial to dedicated page
Beginning of my grand scheme to make stem's front page a simple listing of its
sections (tutorial, API, release notes, download, etc).
Moved the tutorial to its own page with a summary of the tutorials listed at
the top. The tutorial is linked from the main page by an image link.
---
docs/_static/buttons/tutorial.png | Bin 0 -> 12908 bytes
docs/_static/buttons/unused/tutorial.xcf | Bin 0 -> 32568 bytes
docs/index.rst | 122 +---------------------------
docs/tutorial.rst | 129 ++++++++++++++++++++++++++++++
4 files changed, 133 insertions(+), 118 deletions(-)
diff --git a/docs/_static/buttons/tutorial.png b/docs/_static/buttons/tutorial.png
new file mode 100644
index 0000000..65e0f38
Binary files /dev/null and b/docs/_static/buttons/tutorial.png differ
diff --git a/docs/_static/buttons/unused/tutorial.xcf b/docs/_static/buttons/unused/tutorial.xcf
new file mode 100644
index 0000000..5e9afed
Binary files /dev/null and b/docs/_static/buttons/unused/tutorial.xcf differ
diff --git a/docs/index.rst b/docs/index.rst
index 35806d2..5cc754c 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,124 +3,8 @@ Welcome to Stem!
Stem is a python controller library for `Tor <https://www.torproject.org/>`_. Like its predecessor, `TorCtl <https://www.torproject.org/getinvolved/volunteer.html.en#project-torctl>`_, it uses Tor's `control protocol <https://gitweb.torproject.org/torspec.git/blob/HEAD:/control-spec.txt>`_ to help developers program against the Tor process, enabling them to build things similar to `Vidalia <https://www.torproject.org/getinvolved/volunteer.html.en#project-vidalia>`_ and `arm <http://www.atagar.com/arm/>`_.
-Getting started with any new library can be rather daunting, so lets get our feet wet by jumping straight in with a tutorial...
-
-The Little Relay that Could
----------------------------
-
-Lets say you just set up your very first `Tor relay <https://www.torproject.org/docs/tor-doc-relay.html.en>`_. Thank you! Now you want to write a script that tells you how much it is being used.
-
-First, for any script we write to be able to talk with our relay it'll need to have a control port available. This is a port that's usually only available on localhost and protected by either a password or authentication cookie.
-
-Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for the following configuration options...
-
-::
-
- # This provides a port for the script we write to talk to. If you set this
- # then be sure to also have either set the CookieAuthentication flag *or*
- # provide a HashedControlPassword!
-
- ControlPort 9051
-
- # This will make Tor write an authentication cookie file. Anything that can
- # read that file can connect to Tor. If you're going to run this script with
- # the same user as Tor then this is the easiest method of authentication to
- # use.
-
- CookieAuthentication 1
-
- # Alternatively we can authenticate with a password. To set a password first
- # get its hash...
- #
- # % tor --hash-password "my_password"
- # 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
- #
- # ... and use that for the HashedControlPassword in our torrc.
-
- HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
-
-You'll need to restart Tor or issue a SIGHUP for these new settings to take effect. Now lets write a script that tells us how many bytes Tor has sent and received...
-
-::
-
- from stem.control import Controller
-
- controller = Controller.from_port(control_port = 9051)
- controller.authenticate() # provide the password here if you set one
-
- bytes_read = controller.get_info("traffic/read")
- bytes_written = controller.get_info("traffic/written")
-
- print "My Tor relay has read %s bytes and written %s." % (bytes_read, bytes_written)
- controller.close()
-
-::
-
- % python example.py
- My Tor relay has read 33406 bytes and written 29649.
-
-Congratulations! You've just written your first controller script.
-
-Mirror Mirror on the Wall
--------------------------
-
-A script that tells us our contributed bandwidth is neat and all, but now lets figure out who the *biggest* exit relays are.
-
-Information about the Tor relay network come from documents called **descriptors**. Descriptors can come from a few things...
-
-1. The Tor control port with GETINFO options like **desc/all-recent** and **ns/all**.
-2. Files in Tor's data directory, like **cached-descriptors** and **cached-consensus**.
-3. The descriptor archive on `Tor's metrics site <https://metrics.torproject.org/data.html>`_.
-
-We've already used the control port, so for this example we'll use the cached files directly. First locate Tor's data directory. If your torrc has a DataDirectory line then that's the spot. If not then check Tor's man page for the default location.
-
-Tor has several descriptor types. For bandwidth information we'll go to the server descriptors, which are located in the **cached-descriptors** file. These have somewhat infrequently changing information published by the relays themselves.
-
-To read this file we'll use the :class:`~stem.descriptor.reader.DescriptorReader`, a class designed to read descriptor files. The **cached-descriptors** is full of server descriptors, so the reader will provide us with :class:`~stem.descriptor.server_descriptor.RelayDescriptor` instances (a :class:`~stem.descriptor.server_descriptor.ServerDescriptor` subclass for relays).
-
-::
-
- import sys
- from stem.descriptor.reader import DescriptorReader
-
- bw_to_relay = {} # mapping of observed bandwidth to the relay nicknames
-
- with DescriptorReader(["/home/atagar/.tor/cached-descriptors"]) as reader:
- for desc in reader:
- if desc.exit_policy.is_exiting_allowed():
- bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
-
- sorted_bw = sorted(bw_to_relay.keys(), reverse = True)
-
- # prints the top fifteen relays
-
- count = 1
- for bw_value in sorted_bw:
- for nickname in bw_to_relay[bw_value]:
- print "%i. %s (%i bytes/s)" % (count, nickname, bw_value)
- count += 1
-
- if count > 15:
- sys.exit()
-
-::
-
- % python example.py
- 1. herngaard (42939655 bytes/s)
- 2. chaoscomputerclub19 (42402911 bytes/s)
- 3. chaoscomputerclub18 (41967097 bytes/s)
- 4. chaoscomputerclub20 (40882989 bytes/s)
- 5. wannabe (40514411 bytes/s)
- 6. dorrisdeebrown (40349829 bytes/s)
- 7. manning2 (40057719 bytes/s)
- 8. chaoscomputerclub21 (38701399 bytes/s)
- 9. TorLand1 (37983627 bytes/s)
- 10. bolobolo1 (37676580 bytes/s)
- 11. manning1 (37117034 bytes/s)
- 12. gorz (35760527 bytes/s)
- 13. ndnr1 (26595129 bytes/s)
- 14. politkovskaja2 (26149682 bytes/s)
- 15. wau (25929953 bytes/s)
+.. image:: /_static/buttons/tutorial.png
+ :target: tutorial.html
:mod:`stem.connection`
----------------------
@@ -174,3 +58,5 @@ Indices and tables
*Last updated:* |today|
+
+
diff --git a/docs/tutorial.rst b/docs/tutorial.rst
new file mode 100644
index 0000000..9cb1414
--- /dev/null
+++ b/docs/tutorial.rst
@@ -0,0 +1,129 @@
+Tutorial
+========
+
+Getting started with any new library can be rather daunting, so lets get our feet wet by jumping straight in with a tutorial...
+
+* :ref:`the-little-relay-that-could` - Hello world with the control port.
+* :ref:`mirror-mirror-on-the-wall` - Querying information about the Tor network.
+
+.. _the-little-relay-that-could:
+
+The Little Relay that Could
+---------------------------
+
+Lets say you just set up your very first `Tor relay <https://www.torproject.org/docs/tor-doc-relay.html.en>`_. Thank you! Now you want to write a script that tells you how much it is being used.
+
+First, for any script we write to be able to talk with our relay it'll need to have a control port available. This is a port that's usually only available on localhost and protected by either a password or authentication cookie.
+
+Look at your `torrc <https://www.torproject.org/docs/faq.html.en#torrc>`_ for the following configuration options...
+
+::
+
+ # This provides a port for the script we write to talk to. If you set this
+ # then be sure to also have either set the CookieAuthentication flag *or*
+ # provide a HashedControlPassword!
+
+ ControlPort 9051
+
+ # This will make Tor write an authentication cookie file. Anything that can
+ # read that file can connect to Tor. If you're going to run this script with
+ # the same user as Tor then this is the easiest method of authentication to
+ # use.
+
+ CookieAuthentication 1
+
+ # Alternatively we can authenticate with a password. To set a password first
+ # get its hash...
+ #
+ # % tor --hash-password "my_password"
+ # 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
+ #
+ # ... and use that for the HashedControlPassword in our torrc.
+
+ HashedControlPassword 16:E600ADC1B52C80BB6022A0E999A7734571A451EB6AE50FED489B72E3DF
+
+You'll need to restart Tor or issue a SIGHUP for these new settings to take effect. Now lets write a script that tells us how many bytes Tor has sent and received...
+
+::
+
+ from stem.control import Controller
+
+ controller = Controller.from_port(control_port = 9051)
+ controller.authenticate() # provide the password here if you set one
+
+ bytes_read = controller.get_info("traffic/read")
+ bytes_written = controller.get_info("traffic/written")
+
+ print "My Tor relay has read %s bytes and written %s." % (bytes_read, bytes_written)
+ controller.close()
+
+::
+
+ % python example.py
+ My Tor relay has read 33406 bytes and written 29649.
+
+Congratulations! You've just written your first controller script.
+
+.. _mirror-mirror-on-the-wall:
+
+Mirror Mirror on the Wall
+-------------------------
+
+A script that tells us our contributed bandwidth is neat and all, but now lets figure out who the *biggest* exit relays are.
+
+Information about the Tor relay network come from documents called **descriptors**. Descriptors can come from a few things...
+
+1. The Tor control port with GETINFO options like **desc/all-recent** and **ns/all**.
+2. Files in Tor's data directory, like **cached-descriptors** and **cached-consensus**.
+3. The descriptor archive on `Tor's metrics site <https://metrics.torproject.org/data.html>`_.
+
+We've already used the control port, so for this example we'll use the cached files directly. First locate Tor's data directory. If your torrc has a DataDirectory line then that's the spot. If not then check Tor's man page for the default location.
+
+Tor has several descriptor types. For bandwidth information we'll go to the server descriptors, which are located in the **cached-descriptors** file. These have somewhat infrequently changing information published by the relays themselves.
+
+To read this file we'll use the :class:`~stem.descriptor.reader.DescriptorReader`, a class designed to read descriptor files. The **cached-descriptors** is full of server descriptors, so the reader will provide us with :class:`~stem.descriptor.server_descriptor.RelayDescriptor` instances (a :class:`~stem.descriptor.server_descriptor.ServerDescriptor` subclass for relays).
+
+::
+
+ import sys
+ from stem.descriptor.reader import DescriptorReader
+
+ bw_to_relay = {} # mapping of observed bandwidth to the relay nicknames
+
+ with DescriptorReader(["/home/atagar/.tor/cached-descriptors"]) as reader:
+ for desc in reader:
+ if desc.exit_policy.is_exiting_allowed():
+ bw_to_relay.setdefault(desc.observed_bandwidth, []).append(desc.nickname)
+
+ sorted_bw = sorted(bw_to_relay.keys(), reverse = True)
+
+ # prints the top fifteen relays
+
+ count = 1
+ for bw_value in sorted_bw:
+ for nickname in bw_to_relay[bw_value]:
+ print "%i. %s (%i bytes/s)" % (count, nickname, bw_value)
+ count += 1
+
+ if count > 15:
+ sys.exit()
+
+::
+
+ % python example.py
+ 1. herngaard (42939655 bytes/s)
+ 2. chaoscomputerclub19 (42402911 bytes/s)
+ 3. chaoscomputerclub18 (41967097 bytes/s)
+ 4. chaoscomputerclub20 (40882989 bytes/s)
+ 5. wannabe (40514411 bytes/s)
+ 6. dorrisdeebrown (40349829 bytes/s)
+ 7. manning2 (40057719 bytes/s)
+ 8. chaoscomputerclub21 (38701399 bytes/s)
+ 9. TorLand1 (37983627 bytes/s)
+ 10. bolobolo1 (37676580 bytes/s)
+ 11. manning1 (37117034 bytes/s)
+ 12. gorz (35760527 bytes/s)
+ 13. ndnr1 (26595129 bytes/s)
+ 14. politkovskaja2 (26149682 bytes/s)
+ 15. wau (25929953 bytes/s)
+
More information about the tor-commits
mailing list