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, close_output=True, 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 or when outside
   the main thread, and relies on the global state of the signal
   module.

   Changed in version 1.6.0: Allowing the timeout argument to be a
   float.

   Changed in version 1.7.0: Added the **close_output** argument.

   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

      * **close_output** (*bool*) – closes tor’s stdout and stderr
        streams when bootstrapping is complete if true

      * **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, close_output=True)

   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',
          ],
        },
      )

   Changed in version 1.7.0: Added the **close_output** argument.

   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

      * **close_output** (*bool*) – closes tor’s stdout and stderr
        streams when bootstrapping is complete if true

   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
