commit 6651e8304a3cee2ffed344371c830a6014853201 Author: Damian Johnson atagar@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]