Utils Package — pynag 0.8.5 documentation

### Navigation

- index
- modules |
- previous |
- pynag 0.8.5 documentation »
- The pynag module »

# Utils Package

## `Utils` Package

Misc utility classes and helper functions for pynag

This module contains misc classes and conveninence functions that are used throughout the pynag library.

class `pynag.Utils.` `AttributeList`(value=None)

  Bases: `object`

  Parse a list of nagios attributes (e. contact_groups) into a parsable format.

  This makes it handy to mangle with nagios attribute values that are in a comma seperated format.

  Typical comma-seperated format in nagios configuration files looks something like this:

      contact_groups     +group1,group2,group3

  Example:

      >>> i = AttributeList('+group1,group2,group3')
      >>> i.operator
      +
      >>> i.fields
      ['group1', 'group2', 'group3']

      # if your data is already in a list format you can use it directly:
      >>> i = AttributeList(['group1', 'group2', 'group3'])
      >>> i.fields
      ['group1', 'group2', 'group3']

      # white spaces will be stripped from all fields
      >>> i = AttributeList('+group1, group2')
      >>> i
      +group1,group2
      >>> i.fields
      ['group1', 'group2']

  `append`(object)

    Same as list.append():

    Args:
      object: Item to append into self.fields (typically a string)
    Example:

          >>> i = AttributeList('group1,group2,group3')
          >>> i.append('group5')
          >>> i.fields
          ['group1', 'group2', 'group3', 'group5']

  `count`(value)

    Same as list.count()

    Args:
      value: Any object that might exist in self.fields (string)
    Returns:
      The number of occurances that ‘value’ has in self.fields
    Example:

          >>> i = AttributeList('group1,group2,group3')
          >>> i.count('group3')
          1

  `extend`(iterable)

    Same as list.extend()

    Args:
      iterable: Any iterable that list.extend() supports
    Example:

          >>> i = AttributeList('group1,group2,group3')
          >>> i.extend(['group4', 'group5'])
          >>> i.fields
          ['group1', 'group2', 'group3', 'group4', 'group5']

  `index`(value, start=0, stop=None)

    Same as list.index()

    Args:
      value: object to look for in self.fields start: start at this index point stop: stop at this index point
    Returns:
      The index of ‘value’ (integer)
    Examples:

          >>> i = AttributeList('group1,group2,group3')
          >>> i.index('group2')
          1
          >>> i.index('group3', 2, 5)
          2

  `insert`(index, object)

    Same as list.insert()

    Args:
      object: Any object that will be inserted into self.fields (usually a string)
    Example:

          >>> i = AttributeList('group1,group2,group3')
          >>> i.insert(1, 'group4')
          >>> i.fields
          ['group1', 'group4', 'group2', 'group3']

  `remove`(value)

    Same as list.remove()

    Args:
      value: The object that is to be removed
    Examples:

          >>> i = AttributeList('group1,group2,group3')
          >>> i.remove('group3')
          >>> i.fields
          ['group1', 'group2']

  `reverse`()

    Same as list.reverse()

    Examples:

          >>> i = AttributeList('group1,group2,group3')
          >>> i.reverse()
          >>> i.fields
          ['group3', 'group2', 'group1']

  `sort`()

    Same as list.sort()

    Examples:

          >>> i = AttributeList('group3,group1,group2')
          >>> i.sort()
          >>> print(i.fields)
          ['group1', 'group2', 'group3']

class `pynag.Utils.` `GitRepo`(directory, auto_init=True, author_name='Pynag User', author_email=None)

  Bases: `object`

  `add`(filename)

    Run git add on filename

    Arguments:
      filename (str): name of one file to add,
    Returns:
      str. The stdout from “git add” shell command.
  `commit`(message='commited by pynag', filelist=None, author=None)

    Commit files with “git commit”

    Arguments:

    > message (str): Message used for the git commit

    > filelist (list of strings): List of filenames to commit (if None,
    >   then commit all files in the repo)
    > author (str): Author to use for git commit. If any is specified,
    >   overwrite self.author_name and self.author_email

    Returns:

    > stdout from the “git commit” shell command.

  `diff`(commit_id_or_filename=None)

    Returns diff (as outputted by “git diff”) for filename or commit id.

    If commit_id_or_filename is not specified. show diff against all uncommited files.

    Arguments:
      commit_id_or_filename (str): git commit id or file to diff with
    Returns:
      str. git diff for filename or commit id
    Raises:
      PynagError: Invalid commit id or filename was given
  `get_uncommited_files`()

    Returns a list of files that are have unstaged changes

    Returns:
      List. All files that have unstaged changes.
  `get_valid_commits`()

    Returns a list of all commit ids from git log

    Returns:
      List of all valid commit hashes
  `init`()

    Initilizes a new git repo (i.e. run “git init”)

  `is_dirty`(filename)

    Returns True if filename needs to be committed to git

    Arguments:

    > filename (str): file to check

  `is_up_to_date`()

    Returns True if all files in git repo are fully commited

    Returns:

      bool. Git repo is up-to-date

      > True – All files are commited

      > False – At least one file is not commited

  `log`(**kwargs)

    Returns a log of previous commits. Log is is a list of dict objects.

    Any arguments provided will be passed directly to pynag.Utils.grep() to filter the results.

    Arguments:
      kwargs: Arguments passed to pynag.Utils.grep()
    Returns:
      List of dicts. Log of previous commits.
    Examples:
      self.log(author_name=’nagiosadmin’) self.log(comment__contains=’localhost’)
  `pre_save`(object_definition, message)

    Commits object_definition.get_filename() if it has any changes. This function is called by `pynag.Model.EventHandlers` before calling `pynag.Utils.GitRepo.save()`

    Arguments:

    > object_definition (pynag.Model.ObjectDefinition): object to commit changes

    > message (str): git commit message as specified in `git commit -m`

    A message from the authors:
      “Since this is still here, either i forgot to remove it, or because it is here for backwards compatibility, palli”
  `revert`(commit)

    Revert some existing commits works like “git revert”

  `save`(object_definition, message)

    Commits object_definition.get_filename() if it has any changes. This function is called by `pynag.Model.EventHandlers`

    Arguments:

    > object_definition (pynag.Model.ObjectDefinition): object to commit changes

    > message (str): git commit message as specified in `git commit -m`

  `show`(commit_id)

    Returns output from “git show” for a specified commit_id

    Arguments:
      commit_id (str): Commit id of the commit to display (`git show`)
    Returns:
      str. Output of `git show commit_id`
    Raises:
      PynagError: Invalid commit_id was given
  `write`(object_definition, message)

    This method is called whenever `pynag.Model.EventHandlers` is called.

    Arguments

    > object_definition (pynag.Model.ObjectDefinition): Object to write to file.

    > message (str): git commit message as specified in `git commit -m`

class `pynag.Utils.` `PerfData`(perfdatastring='')

  Bases: `object`

  Data Structure for a nagios perfdata string with multiple perfdata metric

  Example string:

      >>> perf = PerfData("load1=10 load2=10 load3=20 'label with spaces'=5")
      >>> perf.metrics
      ['load1'=10;;;;, 'load2'=10;;;;, 'load3'=20;;;;, 'label with spaces'=5;;;;]
      >>> for i in perf.metrics: print("%s %s" % (i.label, i.value))
      load1 10
      load2 10
      load3 20
      label with spaces 5

  `add_perfdatametric`(perfdatastring='', label='', value='', warn='', crit='', min='', max='', uom='')

    Add a new perfdatametric to existing list of metrics.

    Arguments:

    > perfdatastring (str): Complete perfdata string

    > label (str): Label section of the perfdata string

    > value (str): Value section of the perfdata string

    > warn (str): WARNING threshold

    > crit (str): CRITICAL threshold

    > min (str): Minimal value of control

    > max (str): Maximal value of control

    > uom (str): Measure unit (octets, bits/s, volts, ...)

    Example:

        >>> s = PerfData()
        >>> s.add_perfdatametric("a=1")
        >>> s.add_perfdatametric(label="utilization",value="10",uom="%")

  `get_perfdatametric`(metric_name)

    Get one specific perfdatametric

    Arguments:
      metric_name (str): Name of the metric to return

    Example:

        >>> s = PerfData("cpu=90% memory=50% disk_usage=20%")
        >>> my_metric = s.get_perfdatametric('cpu')
        >>> my_metric.label, my_metric.value
        ('cpu', '90')

  `is_valid`()

    Returns True if the every metric in the string is valid

    Example usage:

        >>> PerfData("load1=10 load2=10 load3=20").is_valid()
        True
        >>> PerfData("10b").is_valid()
        False
        >>> PerfData("load1=").is_valid()
        False
        >>> PerfData("load1=10 10").is_valid()
        False

  `reconsile_thresholds`()

    Convert all thresholds in new_threshold_syntax to the standard one

class `pynag.Utils.` `PerfDataMetric`(perfdatastring='', label='', value='', warn='', crit='', min='', max='', uom='')

  Bases: `object`

  Data structure for one single Nagios Perfdata Metric

  Attributes:

  > perfdatastring (str): Complete perfdata string

  > label (str): Label section of the perfdata string

  > value (str): Value section of the perfdata string

  > warn (str): WARNING threshold

  > crit (str): CRITICAL threshold

  > min (str): Minimal value of control

  > max (str): Maximal value of control

  > uom (str): Measure unit (octets, bits/s, volts, ...)

  `crit` = ''

    str CRITICAL threshold

  `get_dict`()

    Returns a dictionary which contains this class’ attributes.

    Returned dict example:

        {
            'label': self.label,
            'value': self.value,
            'uom': self.uom,
            'warn': self.warn,
            'crit': self.crit,
            'min': self.min,
            'max': self.max,
        }

  `get_status`()

    Return nagios-style exit code (int 0-3) by comparing

    Example:

    self.value with self.warn and self.crit

        >>> PerfDataMetric("label1=10;20;30").get_status()
        0
        >>> PerfDataMetric("label2=25;20;30").get_status()
        1
        >>> PerfDataMetric("label3=35;20;30").get_status()
        2

    Invalid metrics always return unknown

        >>> PerfDataMetric("label3=35;invalid_metric").get_status()
        3

  `is_valid`()

    Returns True if all Performance data is valid. Otherwise False

    Example Usage:

        >>> PerfDataMetric("load1=2").is_valid()
        True
        >>> PerfDataMetric("load1").is_valid()
        False
        >>> PerfDataMetric('').is_valid()
        False
        >>> PerfDataMetric('invalid_value=invalid').is_valid()
        False
        >>> PerfDataMetric('invalid_min=0;0;0;min;0').is_valid()
        False
        >>> PerfDataMetric('invalid_min=0;0;0;0;max').is_valid()
        False
        >>> PerfDataMetric('label with spaces=0').is_valid()
        False
        >>> PerfDataMetric("'label with spaces=0'").is_valid()
        False

  `label` = ''

    str. Label section of the perfdata string

  `max` = ''

    str. Maximal value of control

  `min` = ''

    str. Minimal value of control

  `reconsile_thresholds`()

    Convert threshold from new threshold syntax to current one, for backwards compatibility

  `split_value_and_uom`(value)

    Example:

    get value=”10M” and return (10,”M”)

        >>> p = PerfDataMetric()
        >>> p.split_value_and_uom( "10" )
        ('10', '')
        >>> p.split_value_and_uom( "10c" )
        ('10', 'c')
        >>> p.split_value_and_uom( "10B" )
        ('10', 'B')
        >>> p.split_value_and_uom( "10MB" )
        ('10', 'MB')
        >>> p.split_value_and_uom( "10KB" )
        ('10', 'KB')
        >>> p.split_value_and_uom( "10TB" )
        ('10', 'TB')
        >>> p.split_value_and_uom( "10%" )
        ('10', '%')
        >>> p.split_value_and_uom( "10s" )
        ('10', 's')
        >>> p.split_value_and_uom( "10us" )
        ('10', 'us')
        >>> p.split_value_and_uom( "10ms" )
        ('10', 'ms')

  `uom` = ''

    str. Measure unit (octets, bits/s, volts, ...)

  `value` = ''

    str. Value section of the perfdata string

  `warn` = ''

    str. WARNING threshold

class `pynag.Utils.` `PluginOutput`(stdout)

  This class parses a typical stdout from a nagios plugin

  It splits the output into the following fields:

  - Summary
  - Long Output
  - Perfdata

  Attributes:

  > summary (str): Summary returned by the plugin check

  > long_output (str)

  > perfdata (str): Data returned by the plugin as a string

  > parsed_perfdata: perfdata parsed and split

  Example Usage:

      >>> p = PluginOutput("Everything is ok | load1=15 load2=10")
      >>> p.summary
      'Everything is ok '
      >>> p.long_output
      ''
      >>> p.perfdata
      'load1=15 load2=10'
      >>> p.parsed_perfdata.metrics
      ['load1'=15;;;;, 'load2'=10;;;;]

  `long_output` = None
  `parsed_perfdata` = None

    Perfdata parsed and split

  `perfdata` = None

    str. Data returned by the plugin as a string

  `summary` = None

    str. Summary returned by the plugin check

exception `pynag.Utils.` `PynagError`(message, errorcode=None, errorstring=None, *args, **kwargs)

  Bases: `exceptions.Exception`

  The default pynag exception.

  Exceptions raised within the pynag library should aim to inherit this one.

`pynag.Utils.` `cache_only`(func)

class `pynag.Utils.` `defaultdict`(default_factory=None, *a, **kw)

  Bases: `dict`

  This is an alternative implementation of collections.defaultdict.

  Used as a fallback if using python 2.4 or older.

  Usage:

      try:
          from collections import defaultdict
      except ImportError:
          from pynag.Utils import defaultdict

  `copy`()

`pynag.Utils.` `grep`(objects, **kwargs)

  Returns all the elements from array that match the keywords in **kwargs

  See documentation for pynag.Model.ObjectDefinition.objects.filter() for example how to use this.

  Arguments:

  > objects (list of dict): list to be searched

  > kwargs (str): Any search argument provided will be checked against every dict

  Examples:

      array = [
      {'host_name': 'examplehost', 'state':0},
      {'host_name': 'example2', 'state':1},
      ]
      grep_dict(array, state=0)
      # should return [{'host_name': 'examplehost', 'state':0},]

`pynag.Utils.` `grep_to_livestatus`(*args, **kwargs)

  Converts from pynag style grep syntax to livestatus filter syntax.

  Example:

      >>> grep_to_livestatus(host_name='test')
      ['Filter: host_name = test']
      >>> grep_to_livestatus(service_description__contains='serv')
      ['Filter: service_description ~ serv']
      >>> grep_to_livestatus(service_description__isnot='serv')
      ['Filter: service_description != serv']
      >>> grep_to_livestatus(service_description__contains=['serv','check'])
      ['Filter: service_description ~ serv']
      >>> grep_to_livestatus(service_description__contains='foo', contacts__has_field='admin')
      ['Filter: contacts >= admin', 'Filter: service_description ~ foo']
      >>> grep_to_livestatus(service_description__has_field='foo')
      ['Filter: service_description >= foo']
      >>> grep_to_livestatus(service_description__startswith='foo')
      ['Filter: service_description ~ ^foo']
      >>> grep_to_livestatus(service_description__endswith='foo')
      ['Filter: service_description ~ foo$']

`pynag.Utils.` `reconsile_threshold`(threshold_range)

  Take threshold string as and normalize it to the format supported by plugin development team

  The input (usually a string in the form of ‘the new threshold syntax’) is a string in the form of x..y

  The output will be a compatible string in the older nagios plugin format @x:y

  Examples:

      >>> reconsile_threshold("0..5")
      '@0:5'
      >>> reconsile_threshold("inf..5")
      '5:'
      >>> reconsile_threshold("5..inf")
      '~:5'
      >>> reconsile_threshold("inf..inf")
      '@~:'
      >>> reconsile_threshold("^0..5")
      '0:5'
      >>> reconsile_threshold("10..20")
      '@10:20'
      >>> reconsile_threshold("10..inf")
      '~:10'

`pynag.Utils.` `runCommand`(command, raise_error_on_fail=False, shell=True, env=None)

  Run command from the shell prompt. Wrapper around subprocess.

  Arguments:
    command (str): string containing the command line to run raise_error_on_fail (bool): Raise PynagError if returncode > 0
  Returns:
    string: stdout/stderr of the command run
  Raises:
    PynagError if returncode > 0

`pynag.Utils.` `send_nsca`(code, message, nscahost, hostname=None, service=None, nscabin='send_nsca', nscaconf=None)

  Send data via send_nsca for passive service checks

  Arguments:

  > code (int): Return code of plugin.

  > message (str): Message to pass back.

  > nscahost (str): Hostname or IP address of NSCA server.

  > hostname (str): Hostname the check results apply to.

  > service (str): Service the check results apply to.

  > nscabin (str): Location of send_nsca binary. If none specified whatever
  >   is in the path will be used.

  > nscaconf (str): Location of the NSCA configuration to use if any.

  Returns:

  > [result,stdout,stderr] of the command being run

`pynag.Utils.` `synchronized`(lock)

  Synchronization decorator

  Use this to make a multi-threaded method synchronized and thread-safe.

  Use the decorator like so:

      @pynag.Utils.synchronized(pynag.Utils.rlock)

### Navigation

- index
- modules |
- previous |
- pynag 0.8.5 documentation »
- The pynag module »