# 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`

  State allows one to atomically access and update a simple state file on disk across threads and across processes.

  To put it blunty, due to limited developer time and his inability to quickly find a way to safely access and update more complex data types (namely, collections like list, set, and dict), you may only store simple types of data as enumerated in _ALLOWED_TYPES. Keys must be strings.

  Data is stored as JSON on disk in the provided file file.

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

  `get`(key)

### 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`(port=None, path=None, set_custom_stream_settings=True)

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

`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.``remove_event_listener`(controller, func)

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