[or-cvs] pythondoc from bear for our example controller

[arma at seul.org]

Update of /home2/or/cvsroot/control/python
In directory moria:/home/arma/work/onion/cvs/control/python

Modified Files:
	TorExample.py 
Log Message:
pythondoc from bear for our example controller


Index: TorExample.py
===================================================================
RCS file: /home2/or/cvsroot/control/python/TorExample.py,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -d -r1.9 -r1.10
--- TorExample.py	17 Jul 2005 22:00:16 -0000	1.9
+++ TorExample.py	17 Jul 2005 23:08:42 -0000	1.10
@@ -7,7 +7,37 @@
 import sys
 from TorCtl import *
 
+"""
+Tor Control Client Example
+A very basic demonstration of using the TorCtl module to communicate and control
+a Tor server.
+
+Usage:
+  TorExample.py <parameters> <command list>
+
+Parameters:
+  --host <hostname>:<port#>  defaults to "localhost:9100"
+  --verbose | -v             turn on verbose messages
+  
+Commands:
+  set_config <config key>=<config value> [<config key>=<config value> ...]
+  get_config <config key> [<config key> ...]
+  get_info   <info key> [<info key> ...]
+  listen     <event name>
+  signal     <signal name>
+  auth_demo  <auth token>
+  
+For example, to listen for any error messages do:
+
+  python TorExample listen ERR
+"""
+
 def getConnection(daemon=1):
+    """
+    getConnection tries to open a socket to the tor server.
+    If a socket is established, and the daemon paramter is True (the default),
+    a thread is spawned to handle the communcation between us and the tor server.
+    """
     hostport = "localhost:9100"
     verbose = 0
     while sys.argv[1][0] == '-':
@@ -36,6 +66,11 @@
     return conn
 
 def run():
+    """
+    Locate the member function named on the command line and call it.
+    The function is located by pre-pending 'run_' to the parameter
+    and looking for that named item in the python globals() list.
+    """
     if len(sys.argv)<2:
         print "No command given. Finished."
         return
@@ -51,6 +86,11 @@
         print "Request failed: %s"%e
 
 def run_set_config():
+    """
+    walk thru the config key=value pairs present on the command line
+    and pass them to the tor server.  If the --save option is present,
+    tell the tor server to flush the config to disk
+    """
     conn = getConnection()
     if sys.argv[1] == '--save':
         save = 1
@@ -65,6 +105,9 @@
         conn.save_conf()
 
 def run_get_config():
+    """
+    pass the given configuration key names to the tor server and receive their current values
+    """
     conn = getConnection()
     opts = conn.get_option(sys.argv[1:])
     for k,v in opts:
@@ -72,6 +115,9 @@
         print "VALUE:",v
 
 def run_get_info():
+    """
+    pass the given info key names to the tor server and receive their current values
+    """
     conn = getConnection()
     opts = conn.get_info(sys.argv[1:])
     for k in sys.argv[1:]:
@@ -79,12 +125,21 @@
         print "VALUE:",opts.get(k)
 
 def run_listen():
+    """
+    pass to the tor server the given event name to listen for
+    NOTE: after this command the example client will just loop
+    and print any passed event items - you will have to kill it
+    in order to stop it
+    """
     conn = getConnection(daemon=0)
     events = []
     conn.set_event_handler(DebugEventHandler())
     conn.set_events(sys.argv[1:])
 
 def run_signal():
+    """
+    pass to the tor server the given signal
+    """
     conn = getConnection()
     if len(sys.argv)<2:
         print "Syntax: signal [signal]"
@@ -92,6 +147,9 @@
     conn.send_signal(sys.argv[1])
 
 def run_authdemo():
+    """
+    connect to the tor server and authenticate
+    """
     conn = getConnection()
     conn.close()
     #XXXX