
Configuration Classes
*********************


TorConfig
=========

class class txtorcon.TorConfig(control=None)

   Bases: "object"

   This class abstracts out Tor's config so that you don't have to
   realize things like: in order to successfully set multiple listen
   addresses, you must put them all (and the or-ports) in one SETCONF
   call.

   Also, it gives easy access to all the configuration options
   present. This is loaded at "bootstrap" time (when all values are
   loaded) providing attribute-based access thereafter. If you set an
   item AND we're bootstrapped to a Tor, THEN that valud is NOT
   reflected in Tor until you do save() -- and neither is it reflected
   in the TorConfig instance until that time. So, you might get
   slightly confusing behavior like: "config.SOCKSPort=1234; print
   config.SOCKSPort" which will still print 9050 or whatever the
   original value is. (TODO is this really a good idea? Especially
   since we "need" the other behavior for "build config from scratch"
   use-case)

   You may also use this class to construct a configuration from
   scratch (e.g. to give to "txtorcon.launch_tor()"). In this case,
   values are reflected right away. (If we're not bootstrapped to a
   Tor, this is the mode).

   Note that you do not need to call save() if you're just using
   TorConfig to create a .torrc file or for input to launch_tor().

   This listens for CONF_CHANGED events to update the cached data in
   the event other controllers (etc) changed it.

   FIXME: when is CONF_CHANGED introduced in Tor? Can we do anything
   like it for prior versions?

   FIXME:

      * HiddenServiceOptions is special: GETCONF on it returns

      several (well, two) values. Besides adding the two keys 'by
      hand' do we need to do anything special? Can't we just depend on
      users doing 'conf.hiddenservicedir = foo' AND
      'conf.hiddenserviceport = bar' before a save() ?

      * once I determine a value is default, is there any way to
        actually get what this value is?

   config = None

      Current configuration, by keys.

   unsaved = None

      Configuration that has been changed since last save().

   parsers = None

      Instances of the parser classes, subclasses of TorConfigType

   get_type(name)

      return the type of a config key.

      Param:
         name the key

      FIXME can we do something more-clever than this for client code
      to determine what sort of thing a key is?

   bootstrap(*args)

   do_post_bootstrap(*args)

   needs_save()

   mark_unsaved(name)

   save()

      Save any outstanding items. This returns a Deferred which will
      errback if Tor was unhappy with anything, or callback with this
      TorConfig object on success.

   create_torrc()
