[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

[tor-commits] [stem/master] Converting stem.process to reStructuredText



commit 6651e8304a3cee2ffed344371c830a6014853201
Author: Damian Johnson <atagar@xxxxxxxxxxxxxx>
Date:   Sun Jun 3 15:38:38 2012 -0700

    Converting stem.process to reStructuredText
---
 docs/conf.py    |    4 +++
 docs/index.rst  |    7 ++++-
 stem/process.py |   72 +++++++++++++++++++++---------------------------------
 3 files changed, 38 insertions(+), 45 deletions(-)

diff --git a/docs/conf.py b/docs/conf.py
index c7510c1..d07c0cc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -28,6 +28,10 @@ needs_sphinx = '1.1' # required for the sphinx-apidoc command
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode']
 
+autoclass_content = 'both'
+autodoc_member_order = 'groupwise'
+autodoc_default_flags = ['members', 'show-inheritance', 'undoc-members']
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
diff --git a/docs/index.rst b/docs/index.rst
index 3141b2e..6cf06ea 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,7 +8,10 @@ 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/>`_.
 
-Contents:
+:mod:`stem.process`
+-------------------
+
+Used for launching Tor and managing the process.
 
 .. toctree::
    :maxdepth: 2
@@ -20,3 +23,5 @@ Indices and tables
 * :ref:`modindex`
 * :ref:`search`
 
+*Last updated:* |today|
+
diff --git a/stem/process.py b/stem/process.py
index e004faf..0224e3e 100644
--- a/stem/process.py
+++ b/stem/process.py
@@ -1,8 +1,11 @@
 """
 Helper functions for working with tor as a process.
 
-launch_tor             - starts up a tor process
-launch_tor_with_config - starts a tor process with a custom torrc
+:NO_TORRC:
+  when provided as a torrc_path tor is ran with a blank configuration
+
+:DEFAULT_INIT_TIMEOUT:
+  number of seconds before we time out our attempt to start a tor instance
 """
 
 import re
@@ -13,13 +16,8 @@ import subprocess
 
 import stem.util.system
 
-# number of seconds before we time out our attempt to start a tor instance
-DEFAULT_INIT_TIMEOUT = 90
-
-# special parameter that can be set for the torrc_path to run with a blank
-# configuration
-
 NO_TORRC = "<no torrc>"
+DEFAULT_INIT_TIMEOUT = 90
 
 def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_percent = 100, init_msg_handler = None, timeout = DEFAULT_INIT_TIMEOUT):
   """
@@ -31,26 +29,19 @@ def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_perce
   while. Usually this is done in 50 seconds or so, but occasionally calls seem
   to get stuck, taking well over the default timeout.
   
-  Our timeout argument does not work on Windows...
-  https://trac.torproject.org/projects/tor/ticket/5783
-  
-  Arguments:
-    tor_cmd (str)              - command for starting tor
-    args (list)                - additional arguments for tor
-    torrc_path (str)           - location of the torrc for us to use
-    completion_percent (int)   - percent of bootstrap completion at which
-                                 this'll return
-    init_msg_handler (functor) - optional functor that will be provided with
-                                 tor's initialization stdout as we get it
-    timeout (int)              - time after which the attempt to start tor is
-                                 aborted, no timeouts are applied if None
-  
-  Returns:
-    subprocess.Popen instance for the tor subprocess
-  
-  Raises:
-    OSError if we either fail to create the tor process or reached a timeout
-    without success
+  Note: Timeout argument does not work on Windows (`ticket
+  <https://trac.torproject.org/5783>`_)
+  
+  :param str tor_cmd: command for starting tor
+  :param list args: additional arguments for tor
+  :param str torrc_path: location of the torrc for us to use
+  :param int completion_percent: percent of bootstrap completion at which this'll return
+  :param functor init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it
+  :param int timeout: time after which the attempt to start tor is aborted, no timeouts are applied if None
+  
+  :returns: subprocess.Popen instance for the tor subprocess
+  
+  :raises: OSError if we either fail to create the tor process or reached a timeout without success
   """
   
   if stem.util.system.is_windows():
@@ -124,22 +115,15 @@ def launch_tor_with_config(config, tor_cmd = "tor", completion_percent = 100, in
   configuration. This writes a temporary torrc to disk, launches tor, then
   deletes the torrc.
   
-  Arguments:
-    config (dict)              - configuration options, such as ("ControlPort": "9051")
-    tor_cmd (str)              - command for starting tor
-    completion_percent (int)   - percent of bootstrap completion at which
-                                 this'll return
-    init_msg_handler (functor) - optional functor that will be provided with
-                                 tor's initialization stdout as we get it
-    timeout (int)              - time after which the attempt to start tor is
-                                 aborted, no timeouts are applied if None
-  
-  Returns:
-    subprocess.Popen instance for the tor subprocess
-  
-  Raises:
-    OSError if we either fail to create the tor process or reached a timeout
-    without success
+  :param dict config: configuration options, such as ``{"ControlPort": "9051"}``
+  :param str tor_cmd: command for starting tor
+  :param int completion_percent: percent of bootstrap completion at which this'll return
+  :param functor init_msg_handler: optional functor that will be provided with tor's initialization stdout as we get it
+  :param int timeout: time after which the attempt to start tor is aborted, no timeouts are applied if None
+  
+  :returns: subprocess.Popen instance for the tor subprocess
+  
+  :raises: OSError if we either fail to create the tor process or reached a timeout without success
   """
   
   torrc_path = tempfile.mkstemp(prefix = "torrc-", text = True)[1]



_______________________________________________
tor-commits mailing list
tor-commits@xxxxxxxxxxxxxxxxxxxx
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-commits