o
    u]-b                     @   s   d Z ddlZddlZddlZddlZddlmZ zddlm	Z	 W n e
y/   ddlm	Z	 Y nw i ZG dd deZdddZd	d
 ZdddZdd ZdddZG dd deZdS )aJ  
Handlers for text configuration files. Configurations are simple string to
string mappings, with the configuration files using the following rules...

* the key/value is separated by a space
* anything after a '#' is ignored as a comment
* excess whitespace is trimmed
* empty lines are ignored
* multi-line values can be defined by following the key with lines starting
  with a '|'

For instance...

::

  # This is my sample config
  user.name Galen
  user.password yabba1234 # here's an inline comment
  user.notes takes a fancy to pepperjack cheese
  blankEntry.example

  msg.greeting
  |Multi-line message exclaiming of the
  |wonder and awe that is pepperjack!

... would be loaded as...

::

  config = {
    'user.name': 'Galen',
    'user.password': 'yabba1234',
    'user.notes': 'takes a fancy to pepperjack cheese',
    'blankEntry.example': '',
    'msg.greeting': 'Multi-line message exclaiming of the\nwonder and awe that is pepperjack!',
  }

Configurations are managed via the :class:`~stem.util.conf.Config` class. The
:class:`~stem.util.conf.Config` can be be used directly with its
:func:`~stem.util.conf.Config.get` and :func:`~stem.util.conf.Config.set`
methods, but usually modules will want a local dictionary with just the
configurations that it cares about.

To do this use the :func:`~stem.util.conf.config_dict` function. For example...

::

  import getpass
  from stem.util import conf, connection

  def config_validator(key, value):
    if key == 'timeout':
      # require at least a one second timeout
      return max(1, value)
    elif key == 'endpoint':
      if not connection.is_valid_ipv4_address(value):
        raise ValueError("'%s' isn't a valid IPv4 address" % value)
    elif key == 'port':
      if not connection.is_valid_port(value):
        raise ValueError("'%s' isn't a valid port" % value)
    elif key == 'retries':
      # negative retries really don't make sense
      return max(0, value)

  CONFIG = conf.config_dict('ssh_login', {
    'username': getpass.getuser(),
    'password': '',
    'timeout': 10,
    'endpoint': '263.12.8.0',
    'port': 22,
    'reconnect': False,
    'retries': 3,
  }, config_validator)

There's several things going on here so lets take it step by step...

* The :func:`~stem.util.conf.config_dict` provides a dictionary that's bound
  to a given configuration. If the "ssh_proxy_config" configuration changes
  then so will the contents of CONFIG.

* The dictionary we're passing to :func:`~stem.util.conf.config_dict` provides
  two important pieces of information: default values and their types. See the
  Config's :func:`~stem.util.conf.Config.get` method for how these type
  inferences work.

* The config_validator is a hook we're adding to make sure CONFIG only gets
  values we think are valid. In this case it ensures that our timeout value
  is at least one second, and rejects endpoints or ports that are invalid.

Now lets say our user has the following configuration file...

::

  username waddle_doo
  password jabberwocky
  timeout -15
  port 9000000
  retries lots
  reconnect true
  logging debug

... and we load it as follows...

::

  >>> from stem.util import conf
  >>> our_config = conf.get_config('ssh_login')
  >>> our_config.load('/home/atagar/user_config')
  >>> print CONFIG  # doctest: +SKIP
  {
    "username": "waddle_doo",
    "password": "jabberwocky",
    "timeout": 1,
    "endpoint": "263.12.8.0",
    "port": 22,
    "reconnect": True,
    "retries": 3,
  }

Here's an expanation of what happened...

* the username, password, and reconnect attributes took the values in the
  configuration file

* the 'config_validator' we added earlier allows for a minimum timeout of one
  and rejected the invalid port (with a log message)

* we weren't able to convert the retries' "lots" value to an integer so it kept
  its default value and logged a warning

* the user didn't supply an endpoint so that remained unchanged

* our CONFIG didn't have a 'logging' attribute so it was ignored

**Module Overview:**

::

  config_dict - provides a dictionary that's kept in sync with our config
  get_config - singleton for getting configurations
  uses_settings - provides an annotation for functions that use configurations
  parse_enum_csv - helper funcion for parsing confguration entries for enums

  Config - Custom configuration
    |- load - reads a configuration file
    |- save - writes the current configuration to a file
    |- clear - empties our loaded configuration contents
    |- add_listener - notifies the given listener when an update occurs
    |- clear_listeners - removes any attached listeners
    |- keys - provides keys in the loaded configuration
    |- set - sets the given key/value pair
    |- unused_keys - provides keys that have never been requested
    |- get - provides the value for a given key, with type inference
    +- get_value - provides the value for a given key as a string
    N)log)OrderedDictc                   @   s   e Zd Zdd Zdd ZdS )_SyncListenerc                 C   s   || _ || _d S N)config_dictinterceptor)selfr   r    r	   0/usr/lib/python3/dist-packages/stem/util/conf.py__init__   s   
z_SyncListener.__init__c                 C   sZ   || j v r+||| j | }|| j | krd S | jr$| ||}|r$|}|| j |< d S d S r   )r   getr   )r   configkeyZ	new_valueZinterceptor_valuer	   r	   r
   update   s   
z_SyncListener.updateN)__name__
__module____qualname__r   r   r	   r	   r	   r
   r      s    r   c                 C   s   t | }|t||j |S )aW  
  Makes a dictionary that stays synchronized with a configuration.

  This takes a dictionary of 'config_key => default_value' mappings and
  changes the values to reflect our current configuration. This will leave
  the previous values alone if...

  * we don't have a value for that config_key
  * we can't convert our value to be the same type as the default_value

  If a handler is provided then this is called just prior to assigning new
  values to the config_dict. The handler function is expected to accept the
  (key, value) for the new values and return what we should actually insert
  into the dictionary. If this returns None then the value is updated as
  normal.

  For more information about how we convert types see our
  :func:`~stem.util.conf.Config.get` method.

  **The dictionary you get from this is manged by the Config class and should
  be treated as being read-only.**

  :param str handle: unique identifier for a config instance
  :param dict conf_mappings: config key/value mappings used as our defaults
  :param functor handler: function referred to prior to assigning values
  )
get_configadd_listenerr   r   )handleZconf_mappingsZhandlerZselected_configr	   r	   r
   r      s   r   c                 C   s   | t vr	t t | < t |  S )z
  Singleton constructor for configuration file instances. If a configuration
  already exists for the handle then it's returned. Otherwise a fresh instance
  is constructed.

  :param str handle: unique identifier used to access this config instance
  )CONFSConfig)r   r	   r	   r
   r      s   	
r   Tc                    s6   t |  s js  d _ fdd}|S )a  
  Provides a function that can be used as a decorator for other functions that
  require settings to be loaded. Functions with this decorator will be provided
  with the configuration as its 'config' keyword argument.

  .. versionchanged:: 1.3.0
     Omits the 'config' argument if the funcion we're decorating doesn't accept
     it.

  ::

    uses_settings = stem.util.conf.uses_settings('my_app', '/path/to/settings.cfg')

    @uses_settings
    def my_function(config):
      print 'hello %s!' % config.get('username', '')

  :param str handle: hande for the configuration
  :param str path: path where the configuration should be loaded from
  :param bool lazy_load: loads the configuration file when the decorator is
    used if true, otherwise it's loaded right away

  :returns: **function** that can be used as a decorator to provide the
    configuration

  :raises: **IOError** if we fail to read the configuration file, if
    **lazy_load** is true then this arises when we use the decorator
  Tc                    s    fdd}|S )Nc                     sJ   r j s  d _ dtjv r| d i|S | i |S )NTr   )_settings_loadedloadinspectZ
getargspecargs)r   kwargs)r   func	lazy_loadpathr	   r
   wrapped  s   

z1uses_settings.<locals>.decorator.<locals>.wrappedr	   )r   r    r   r   r   )r   r
   	decorator  s   
z uses_settings.<locals>.decorator)r   r   r   )r   r   r   r"   r	   r!   r
   uses_settings   s   

r#   c                 C   s   t | ||dd S )a  
  Provides the enumeration value for a given key. This is a case insensitive
  lookup and raises an exception if the enum key doesn't exist.

  :param str key: configuration key being looked up
  :param str value: value to be parsed
  :param stem.util.enum.Enum enumeration: enumeration the values should be in

  :returns: enumeration value

  :raises: **ValueError** if the **value** isn't among the enumeration keys
     r   )parse_enum_csv)r   valueenumerationr	   r	   r
   
parse_enum*  s   r(   c                 C   s:  dd | dD }|dgkrg S |du rnUt|tr+t||kr*td| ||f n@t|trat|dkra|\}}|durMt||k rMtd| ||f |dur`t||kr`td	| ||f n
td
|t|f g }dd t| D }t|}	|D ]}
|
|v r|	|	|
|
  q~td|
| d|f |S )a  
  Parses a given value as being a comma separated listing of enumeration keys,
  returning the corresponding enumeration values. This is intended to be a
  helper for config handlers. The checks this does are case insensitive.

  The **count** attribute can be used to make assertions based on the number of
  values. This can be...

  * None to indicate that there's no restrictions.
  * An int to indicate that we should have this many values.
  * An (int, int) tuple to indicate the range that values can be in. This range
    is inclusive and either can be None to indicate the lack of a lower or
    upper bound.

  :param str key: configuration key being looked up
  :param str value: value to be parsed
  :param stem.util.enum.Enum enumeration: enumeration the values should be in
  :param int,tuple count: validates that we have this many items

  :returns: list with the enumeration values

  :raises: **ValueError** if the count assertion fails or the **value** entries
    don't match the enumeration keys
  c                 S   s   g | ]}|   qS r	   )upperstrip).0valr	   r	   r
   
<listcomp>U  s    z"parse_enum_csv.<locals>.<listcomp>, NzGConfig entry '%s' is expected to be %i comma separated values, got '%s'   zHConfig entry '%s' must have at least %i comma separated values, got '%s'zFConfig entry '%s' can have at most %i comma separated values, got '%s'zBThe count must be None, an int, or two value tuple. Got '%s' (%s)'c                 S   s   g | ]}|  qS r	   )r)   )r+   kr	   r	   r
   r-   k  s    zKThe '%s' entry of config entry '%s' wasn't in the enumeration (expected %s)z, )split
isinstanceintlen
ValueErrortupletypelistkeysappendindexjoin)r   r&   r'   countvaluesZminimumZmaximumresultZ	enum_keysZenum_valuesr,   r	   r	   r
   r%   ;  s2   

r%   c                   @   s|   e Zd ZdZdd ZdddZddd	Zd
d ZdddZdd Z	dd Z
dd ZdddZdddZd ddZdd ZdS )!r   aQ	  
  Handler for easily working with custom configurations, providing persistence
  to and from files. All operations are thread safe.

  **Example usage:**

  User has a file at '/home/atagar/myConfig' with...

  ::

    destination.ip 1.2.3.4
    destination.port blarg

    startup.run export PATH=$PATH:~/bin
    startup.run alias l=ls

  And they have a script with...

  ::

    from stem.util import conf

    # Configuration values we'll use in this file. These are mappings of
    # configuration keys to the default values we'll use if the user doesn't
    # have something different in their config file (or it doesn't match this
    # type).

    ssh_config = conf.config_dict('ssh_login', {
      'login.user': 'atagar',
      'login.password': 'pepperjack_is_awesome!',
      'destination.ip': '127.0.0.1',
      'destination.port': 22,
      'startup.run': [],
    })

    # Makes an empty config instance with the handle of 'ssh_login'. This is
    # a singleton so other classes can fetch this same configuration from
    # this handle.

    user_config = conf.get_config('ssh_login')

    # Loads the user's configuration file, warning if this fails.

    try:
      user_config.load("/home/atagar/myConfig")
    except IOError as exc:
      print "Unable to load the user's config: %s" % exc

    # This replace the contents of ssh_config with the values from the user's
    # config file if...
    #
    # * the key is present in the config file
    # * we're able to convert the configuration file's value to the same type
    #   as what's in the mapping (see the Config.get() method for how these
    #   type inferences work)
    #
    # For instance in this case...
    #
    # * the login values are left alone because they aren't in the user's
    #   config file
    #
    # * the 'destination.port' is also left with the value of 22 because we
    #   can't turn "blarg" into an integer
    #
    # The other values are replaced, so ssh_config now becomes...
    #
    # {'login.user': 'atagar',
    #  'login.password': 'pepperjack_is_awesome!',
    #  'destination.ip': '1.2.3.4',
    #  'destination.port': 22,
    #  'startup.run': ['export PATH=$PATH:~/bin', 'alias l=ls']}
    #
    # Information for what values fail to load and why are reported to
    # 'stem.util.log'.

    .. versionchanged:: 1.7.0
       Class can now be used as a dictionary.
  c                 C   s0   d | _ t | _g | _t | _t | _d| _	d S NF)
_pathr   	_contents
_listeners	threadingRLock_contents_lockset_requested_keysr   r   r	   r	   r
   r     s   

zConfig.__init__NTc                 C   s  |r|| _ n| j stdtj| j r7t| j D ]\}}}|D ]}|dr)q!| tj|| q!qdS t	| j d}|
 }W d   n1 sLw   Y  | j |r|d}	|rc|	dnd}
|
dkro|	d|
 }	|	 }	|	rd|	v r|	dd	\}}| || d
 nAg }|r|d  dr|d d	d }|d}|| |r|d  ds|r| |	d|d
 n| |	dd
 |sWW d   dS W d   dS 1 sw   Y  dS )a'  
    Reads in the contents of the given path, adding its configuration values
    to our current contents. If the path is a directory then this loads each
    of the files, recursively.

    .. versionchanged:: 1.3.0
       Added support for directories.

    .. versionchanged:: 1.3.0
       Added the **commenting** argument.

    .. versionchanged:: 1.6.0
       Avoid loading vim swap files.

    :param str path: file or directory path to be loaded, this uses the last
      loaded path if not provided
    :param bool commenting: ignore line content after a '#' if **True**, read
      otherwise

    :raises:
      * **IOError** if we fail to read the file (it doesn't exist, insufficient
        permissions, etc)
      * **ValueError** if no path was provided and we've never been provided one
    z.Unable to load configuration: no path providedz.swpNrr   # r$   F|
r/   )rB   r6   osr   isdirwalkendswithr   r=   open	readlinesrG   popfindr*   r2   rH   lstrip
startswithrstripr;   )r   r   Z
commentingrootdirnames	filenamesfilenameZconfig_fileZread_contentslineZcomment_startr   r&   Zmultiline_bufferZcontentr	   r	   r
   r     sN   




"zConfig.loadc              	   C   s   |r|| _ n| j std| jb tjtj| j s&ttj| j  t| j d.}| 	 D ]!}| j
|ddD ]}d|v rHd|dd }|d||f  q:q1W d   n1 s]w   Y  W d   dS W d   dS 1 suw   Y  dS )	aa  
    Saves configuration contents to disk. If a path is provided then it
    replaces the configuration location that we track.

    :param str path: location to be saved to

    :raises:
      * **IOError** if we fail to save the file (insufficient permissions, etc)
      * **ValueError** if no path was provided and we've never been provided one
    z.Unable to save configuration: no path providedwT)multiplerP   z
|z%s %s
N)rB   r6   rG   rQ   r   existsdirnamemakedirsrU   r:   	get_valuereplacewrite)r   r   Zoutput_file	entry_keyZentry_valuer	   r	   r
   save   s&   "zConfig.savec                 C   s>   | j  | j  t | _W d   dS 1 sw   Y  dS )z[
    Drops the configuration contents and reverts back to a blank, unloaded
    state.
    N)rG   rC   clearrH   rI   rJ   r	   r	   r
   rk   >  s   

"zConfig.clearc                 C   sd   | j % | j| |r|  D ]}|| | qW d   dS W d   dS 1 s+w   Y  dS )a8  
    Registers the function to be notified of configuration updates. Listeners
    are expected to be functors which accept (config, key).

    :param functor listener: function to be notified when our configuration is changed
    :param bool backfill: calls the function with our current values if **True**
    N)rG   rD   r;   r:   )r   listenerZbackfillr   r	   r	   r
   r   H  s   	"zConfig.add_listenerc                 C   s
   g | _ dS )z)
    Removes all attached listeners.
    N)rD   rJ   r	   r	   r
   clear_listenersX  s   
zConfig.clear_listenersc                 C   s   t | j S )z
    Provides all keys in the currently loaded configuration.

    :returns: **list** if strings for the configuration keys we've loaded
    )r9   rC   r:   rJ   r	   r	   r
   r:   _  s   zConfig.keysc                 C   s   t |  | jS )a?  
    Provides the configuration keys that have never been provided to a caller
    via :func:`~stem.util.conf.config_dict` or the
    :func:`~stem.util.conf.Config.get` and
    :func:`~stem.util.conf.Config.get_value` methods.

    :returns: **set** of configuration keys we've loaded but have never been requested
    )rH   r:   
differencerI   rJ   r	   r	   r
   unused_keysh  s   
zConfig.unused_keysc                 C   sF  | j  tj rtnt}|du r|r|| jv r| j|= nd	 nZt|t|frH|s6|| jv r6| j| 	| n|g| j|< | j
D ]}|| | q?nAt|ttfrq|s`|| jv r`| j|  |7  < n|| j|< | j
D ]}|| | qhn tdt| W d   dS W d   dS W d   dS W d   dS 1 sw   Y  dS )a  
    Appends the given key/value configuration mapping, behaving the same as if
    we'd loaded this from a configuration file.

    .. versionchanged:: 1.5.0
       Allow removal of values by overwriting with a **None** value.

    :param str key: key for the configuration mapping
    :param str,list value: value we're setting the mapping to
    :param bool overwrite: replaces the previous value if **True**, otherwise
      the values are appended
    Nz[Config.set() only accepts str (bytes or unicode), list, or tuple. Provided value was a '%s')rG   stemZprereqZis_python_3strZunicoderC   r3   bytesr;   rD   r9   r7   r6   r8   )r   r   r&   Z	overwriteZunicode_typerl   r	   r	   r
   rH   t  s:   



"z
Config.setc           	      C   s  t |tttf}| |||}||kr|S t |tr=| dkr$d}|S | dkr.d}|S td|t	|f  |}|S t |t
r_zt
|}W |S  ty^   td||f  |}Y |S w t |trzt|}W |S  ty   td||f  |}Y |S w t |trt|}|S t |trt|}|S t |trt }|D ] }d|v r|dd	\}}| || < qtd
||f  q|}|S )al  
    Fetches the given configuration, using the key and default value to
    determine the type it should be. Recognized inferences are:

    * **default is a boolean => boolean**

      * values are case insensitive
      * provides the default if the value isn't "true" or "false"

    * **default is an integer => int**

      * provides the default if the value can't be converted to an int

    * **default is a float => float**

      * provides the default if the value can't be converted to a float

    * **default is a list => list**

      * string contents for all configuration values with this key

    * **default is a tuple => tuple**

      * string contents for all configuration values with this key

    * **default is a dictionary => dict**

      * values without "=>" in them are ignored
      * values are split into key/value pairs on "=>" with extra whitespace
        stripped

    :param str key: config setting to be fetched
    :param default object: value provided if no such key exists or fails to be converted

    :returns: given configuration value with its type inferred with the above rules
    trueTZfalseFzAConfig entry '%s' is expected to be a boolean, defaulting to '%s'zBConfig entry '%s' is expected to be an integer, defaulting to '%i'z?Config entry '%s' is expected to be a float, defaulting to '%f'z=>r$   zPIgnoring invalid %s config entry (expected a mapping, but "%s" was missing "=>"))r3   r9   r7   dictrf   boollowerr   debugrq   r4   r6   floatr   r2   r*   )	r   r   defaultZis_multivaluer,   Zval_mapentryri   Z	entry_valr	   r	   r
   r     s^   &
 






z
Config.getFc                 C   s   | j A || jv r+| j| |r| j| W  d   S | j| d W  d   S d| }t|tjd||f  |W  d   S 1 sGw   Y  dS )a  
    This provides the current value associated with a given key.

    :param str key: config setting to be fetched
    :param object default: value provided if no such key exists
    :param bool multiple: provides back a list of all values if **True**,
      otherwise this returns the last loaded configuration value

    :returns: **str** or **list** of string configuration values associated
      with the given key, providing the default if no such key exists
    NrM   z$stem.util.conf.missing_config_key_%sz/config entry '%s' not found, defaulting to '%s')rG   rC   rI   addr   Zlog_onceZTRACE)r   r   ry   rb   Z
message_idr	   r	   r
   rf     s   
	$zConfig.get_valuec                 C   s4   | j  | j| W  d    S 1 sw   Y  d S r   )rG   rC   )r   r   r	   r	   r
   __getitem__  s   $zConfig.__getitem__)NTr   TrA   )r   r   r   __doc__r   r   rj   rk   r   rm   r:   ro   rH   r   rf   r|   r	   r	   r	   r
   r   w  s    O

K

	

)
Pr   r   r}   )r~   r   rQ   rE   Zstem.prereqrp   Z	stem.utilr   collectionsr   ImportErrorZstem.util.ordereddictr   objectr   r   r   r#   r(   r%   r   r	   r	   r	   r
   <module>   s(    
!
4
<