Client — hermes 0.1 documentation

# Client

class `hermes.client.` `Client`(dsn, watch_path=None, failover_files=None)

  Bases: `hermes.log.LoggerMixin`, `multiprocessing.process.Process`, `watchdog.events.FileSystemEventHandler`

  Responsible for Listener and Processor components. Provides functions to start/stop both itself and its components. In addition, it is also capable of receiving file-system events via the ‘watchdog’ library.

  General procedure:

  > 1. Starts both the Process and Listener components.
  > 2. Listen and act upon exit/error notifications from components
  > 3. Listen for file-system events and acts accordingly.

  To make the client listen for Postgres ‘recovery.conf, recovery.done’ events:

      from hermes.client import Client

      dsn = {'database': 'example_db',
             'host': '127.0.0.1',
             'port': 5432,
             'user': 'example',
             'password': 'example'}

      watch_path = '/var/lib/postgresql/9.4/main/'
      failover_files = ['recovery.done', 'recovery.conf']

      client = Client(dsn, watch_path, failover_files)

      # Add processor and listener
      ...

      # Start the client
      client.start()

  Or, if you decide you don’t want to use a file watcher, then you can omit those parameters. However, the Client will still perform master/slave checks if a problem is encountered:

      from hermes.client import Client

      dsn = {'database': 'example_db',
             'host': '127.0.0.1',
             'port': 5432,
             'user': 'example',
             'password': 'example'}

      client = Client(dsn)

      # Add processor and listener
      ...

      # Start the client
      client.start()

  Parameters: | dsn – A Postgres-compatible DSN dictionary watch_path – The directory to monitor for filechanges. If None, then file monitoring is disabled. failover_files – A list of files which, when modified, will cause the client to call `execute_role_based_procedure()`

  `add_listener`(listener)

    Parameters: | listener – A `Component` object which will listen for notifications from Postgres and pass an event down a queue.
    Raises: | `InvalidConfigurationException` if the provided listener is not a subclass of `Component`

  `add_processor`(processor)

    Parameters: | processor – A `Component` object which will receive notifications and run the `execute()` method.
    Raises: | `InvalidConfigurationException` if the provided processor is not a subclass of `Component`

  `execute_role_based_procedure`()

    Starts or stops components based on the role (Master/Slave) of the Postgres host.

    Implements a binary exponential backoff up to 32 seconds if it encounters a FATAL connection error.

  `on_any_event`(event)

    Listens to an event passed by ‘watchdog’ and checks the current master/slave status

    Parameters: | event – A `FileSystemEvent`

    object passed by ‘watchdog’ indicating an event change within the specified directory.

  `run`()

    Performs a `select()` on the components’ error queue. When a notification is detected, the client will log the message and then calculate if the Postgres server is still a Master - if not, the components are shutdown.

  `start`()

    Starts the Client, its Components and the directory observer

    Raises: | `InvalidConfigurationException`