[tor-commits] [stem/master] Converting stem.process to reStructuredText
atagar at torproject.org
atagar at torproject.org
Wed Jun 6 04:30:17 UTC 2012
commit 6651e8304a3cee2ffed344371c830a6014853201
Author: Damian Johnson <atagar at torproject.org>
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]
More information about the tor-commits
mailing list