commit d2cd6ccb0c9df470478278e570f732beec973df6 Author: Damian Johnson atagar@torproject.org Date: Sat Oct 27 18:42:32 2012 -0700

Revised API docs for stem.process --- docs/api.rst | 1 + docs/api/process.rst | 5 +++++ docs/contents.rst | 1 + stem/process.py | 34 +++++++++++++++++++++------------- 4 files changed, 28 insertions(+), 13 deletions(-)

diff --git a/docs/api.rst b/docs/api.rst index 223b5bc..c138240 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -9,6 +9,7 @@ Controller * `stem.control <api/control.html>`_ - **Controller used to talk with Tor**. * `stem.connection <api/connection.html>`_ - Connection and authentication to the Tor control port or socket. * `stem.socket <api/socket.html>`_ - Low level control socket used to talk with Tor. + * `stem.process <api/process.html>`_ - Launcher for the Tor process.

* **Types**

diff --git a/docs/api/process.rst b/docs/api/process.rst new file mode 100644 index 0000000..0e87abf --- /dev/null +++ b/docs/api/process.rst @@ -0,0 +1,5 @@ +Tor Process +=========== + +.. automodule:: stem.process + diff --git a/docs/contents.rst b/docs/contents.rst index 6c19f33..03274a4 100644 --- a/docs/contents.rst +++ b/docs/contents.rst @@ -11,6 +11,7 @@ Contents api/control api/connection api/socket + api/process

api/exit_policy api/version diff --git a/stem/process.py b/stem/process.py index 04f787a..25ff88a 100644 --- a/stem/process.py +++ b/stem/process.py @@ -39,19 +39,23 @@ 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.

- Note: Timeout argument does not work on Windows (`ticket + Note: The 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 + :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 + :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 + :raises: **OSError** if we either fail to create the tor process or reached a + timeout without success """

if stem.util.system.is_windows(): @@ -138,19 +142,23 @@ def launch_tor(tor_cmd = "tor", args = None, torrc_path = None, completion_perce

def launch_tor_with_config(config, tor_cmd = "tor", completion_percent = 100, init_msg_handler = None, timeout = DEFAULT_INIT_TIMEOUT): """ - Initializes a tor process, like :func:`stem.process.launch_tor`, but with a + Initializes a tor process, like :func:`~stem.process.launch_tor`, but with a customized configuration. This writes a temporary torrc to disk, launches tor, then deletes the torrc.

- :param dict config: configuration options, such as ``{"ControlPort": "9051"}`` + :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 + :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 + :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 + :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]