
Tor Process
***********

Helper functions for working with tor as a process.

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

**Module Overview:**

   launch_tor             - starts up a tor process
   launch_tor_with_config - starts a tor process with a custom torrc

stem.process.launch_tor(tor_cmd='tor', args=None, torrc_path=None, completion_percent=100, init_msg_handler=None, timeout=90, take_ownership=False, stdin=None)

   Initializes a tor process. This blocks until initialization
   completes or we error out.

   If tor's data directory is missing or stale then bootstrapping will
   include making several requests to the directory authorities which
   can take a little while. Usually this is done in 50 seconds or so,
   but occasionally calls seem to get stuck, taking well over the
   default timeout.

   **To work to must log at NOTICE runlevel to stdout.** It does this
   by default, but if you have a 'Log' entry in your torrc then you'll
   also need 'Log NOTICE stdout'.

   Note: The timeout argument does not work on Windows, and relies on
   the global state of the signal module.

   Parameters:
      * **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**

      * **take_ownership** (*bool*) -- asserts ownership over the tor
        process so it aborts if this python process terminates or a
        "Controller" we establish to it disconnects

      * **stdin** (*str*) -- content to provide on stdin

   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

stem.process.launch_tor_with_config(config, tor_cmd='tor', completion_percent=100, init_msg_handler=None, timeout=90, take_ownership=False)

   Initializes a tor process, like "launch_tor()", but with a
   customized configuration. This writes a temporary torrc to disk,
   launches tor, then deletes the torrc.

   For example...

      tor_process = stem.process.launch_tor_with_config(
        config = {
          'ControlPort': '2778',
          'Log': [
            'NOTICE stdout',
            'ERR file /tmp/tor_error_log',
          ],
        },
      )

   Parameters:
      * **config** (*dict*) -- configuration options, such as
        "{'ControlPort': '9051'}", values can either be a **str** or
        **list of str** if for multiple values

      * **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**

      * **take_ownership** (*bool*) -- asserts ownership over the tor
        process so it aborts if this python process terminates or a
        "Controller" we establish to it disconnects

   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
