# sbws.util package

## Submodules

### sbws.util.config module

Util functions to manage sbws configuration files.

`sbws.util.config.``configure_logging`(args, conf)

`sbws.util.config.``get_config`(args)

  Get ConfigParser interpolating all configuration files.

`sbws.util.config.``validate_config`(conf)

  Checks the given conf for bad values or bad combinations of values. If there’s something wrong, returns False and a list of error messages. Otherwise, return True and an empty list

### sbws.util.filelock module

class `sbws.util.filelock.``DirectoryLock`(dname)

  Bases: `sbws.util.filelock._FLock`

  Holds a lock on a file in dname so that other sbws processes/threads won’t try to read/write while we are reading/writing in this directory.

      >>> with DirectoryLock(dname):
      >>>     # do some reading/writing in dname
      >>> # no longer have the lock

  Note: The directory must already exist.

  Parameters

    dname (str) – Name of directory for which we want to obtain a lock

class `sbws.util.filelock.``FileLock`(fname)

  Bases: `sbws.util.filelock._FLock`

  Holds a lock on fname so that other sbws processes/threads won’t try to read/write while we are reading/writing this file.

      >>> with FileLock(fname):
      >>>     # do some reading/writing of fname
      >>> # no longer have the lock

  Parameters

    fname (str) – Name of the file for which we want to obtain a lock

### sbws.util.parser module

`sbws.util.parser.``create_parser`()

### sbws.util.state module

class `sbws.util.state.``State`(fname)

  Bases: `object`

  json wrapper to read a json file every time it gets a key and to write to the file every time a key is set.

  Every time a key is got or set, the file is locked, to atomically access and update the file across threads and across processes.

      >>> state = State('foo.state')
      >>> # state == {}

      >>> state['linux'] = True
      >>> # 'foo.state' now exists on disk with the JSON for {'linux': True}

      >>> # We read 'foo.state' from disk in order to get the most up-to-date
      >>> #     state info. Pretend another process has updated 'linux' to be
      >>> #     False
      >>> state['linux']
      >>> # returns False

      >>> # Pretend another process has added the user's age to the state file.
      >>> #     As before, we read the state file from disk for the most
      >>> #     up-to-date info.
      >>> state['age']
      >>> # Returns 14

      >>> # We now set their name. We read the state file first, set the option,
      >>> #     and then write it out.
      >>> state['name'] = 'John'

      >>> # We can do many of the same things with a State object as with a dict
      >>> for key in state: print(key)
      >>> # Prints 'linux', 'age', and 'name'

  `count`(k)

    Returns the length if the key value is a list or the sum of number if the key value is a list of list or the key value or None if the state doesn’t have the key.

  `get`(key, d=None)

    Implements a dictionary `get` method reading and locking a json file.

### sbws.util.stem module

`sbws.util.stem.``add_event_listener`(controller, func, event)

`sbws.util.stem.``attach_stream_to_circuit_listener`(controller, circ_id)

  Returns a function that should be given to add_event_listener(). It looks for newly created streams and attaches them to the given circ_id

`sbws.util.stem.``circuit_str`(controller, circ_id)

`sbws.util.stem.``get_socks_info`(controller)

  Returns the first SocksPort Tor is configured to listen on, in the form of an (address, port) tuple

`sbws.util.stem.``init_controller`(conf)

`sbws.util.stem.``is_bootstrapped`(c)

`sbws.util.stem.``is_torrc_starting_point_set`(tor_controller)

  Verify that the tor controller has the correct configuration.

  When connecting to a tor controller that has not been launched by sbws, it should have been configured to work with sbws.

`sbws.util.stem.``launch_or_connect_to_tor`(conf)

`sbws.util.stem.``launch_tor`(conf)

`sbws.util.stem.``only_relays_with_bandwidth`(controller, relays, min_bw=None, max_bw=None)

  Given a list of relays, only return those that optionally have above min_bw and optionally have below max_bw, inclusively. If neither min_bw nor max_bw are given, essentially just returns the input list of relays.

`sbws.util.stem.``parse_user_torrc_config`(torrc, torrc_text)

  Parse the user configuration torrc text call extra_lines to a dictionary suitable to use with stem and return a new torrc dictionary that merges that dictionary with the existing torrc. Example:

      [tor]
      extra_lines =
          Log debug file /tmp/tor-debug.log
          NumCPUs 1

`sbws.util.stem.``remove_event_listener`(controller, func)

`sbws.util.stem.``set_torrc_options_can_fail`(controller)

  Set options that can fail, at runtime.

  They can be set at launch, but since the may fail because they are not supported in some Tor versions, it’s easier to try one by one at runtime and ignore the ones that fail.

`sbws.util.stem.``set_torrc_runtime_options`(controller)

  Set torrc options at runtime.

`sbws.util.stem.``set_torrc_starting_point`(controller)

  Set the torrc starting point options.

### sbws.util.userquery module

`sbws.util.userquery.``query_yes_no`(question, default='yes')

  Ask a yes/no question via input() and return the user’s answer.

  Parameters

    - question (str) – Prompt given to the user.

    - default (str) – The assumed answer if th user just hits Enter. It must be `'yes'` (the default if no default is given), `'no'`, or `None` (meaning an answer is required from the user).

  Returns

    `True` if we ended up with a ‘yes’ answer, otherwise `False`.

## Module contents