Keygrabber Python module

The keygrabber module provides two primary functions: it provides routines used to retrieve records from the history database and it implements the KTL keywords provided by keygrabber when its internal KTL service is enabled.

Retrieving data

keygrabber.columnar(keywords, begin=None, end=None, accept=None, mangle=False)

Retrieve a data set and render it in columnar format, with one row for each keyword broadcast. Rows will be collapsed to the nearest millisecond.

If accept is set, it should be a function that accepts a row as its sole argument, and returns True if the row should be included as a valid data point.

If mangle is set to True, the timestamps in the first column will be pre-mangled so that gnuplot (which only interprets UNIX timestamps as UTC) will render the times in the local time zone.

The results from columnar() are straightforward to feed into a csv.writer() instance.

keygrabber.retrieve(keywords, begin=None, end=None, prime=True, dict=True, snap=False)

Retrieve all available records corresponding to the requested keywords as of a given time range. keywords is expected to be a dictionary, with KTL service names as keys, and the keyed value a list of keyword names. The begin and end arguments are UNIX timestamps, and will be extended by one millisecond to avoid problems with floating point inequalities. If begin is not specified, all records up to end will be returned; if end is not specified, all records after begin will be returned. If neither begin nor end is specified, all records for that service+keyword combination will be returned. If prime is True (the default) and begin is specified, the most recent record before begin will be included in the results.

If dict is False, the results will be returned as a list of lists, as is typical for the fetchall() method of a pgdb cursor instance. The columns are as follows: service, keyword, time, binvalue, ascvalue, repeated, discarded. If dict is True (the default), each result in the sequential list will be a dictionary instead of a list, with the column names as keys.

Results are sorted first by timestamp, then by service, and lastly by keyword.

keygrabber.snapshot(keywords, time, dict=True)

Retreive a snapshot of keyword values corresponding to the timestamp time. See retrieve() for an explanation of the arguments.

keygrabber.tally(keywords, begin, end=None, binning=None)

Return a per-keyword tally of how long each individual keyword in the specified keywords had a particular value. The results will be returned as a dictionary, with each keyword as a key; each value in that dictionary will likewise be a dictionary, but instead keyed by the value of the keyword itself. If binning is specified, numeric results will be binned to the nearest round value; for example, if 0.1 is specified, numeric values will be binned to the nearest 0.1; if 10, the nearest 10. The remainder of the arguments are interpreted the same way as they are for retrieve().

Other internal functions

keygrabber.datahost(service)

Return the hostname on which the keygrabber data is stored for service. This information could then be used when instantiating a sql.Handler instance.

keygrabber.services(handler, dict=True)

Determine which services have data available on the datahost of interest– specified implicitly by passing in a working sql.Handler instance as the first argument.

keygrabber.startService(main)

If the configuration specifies a KTL service, start a DFW backend instance to run the service.

keygrabber.version()

Return a version number for this module. The version number is computed by multiplying the major CVS revision of each individual component by 1,000, directly adding the minor version, and summing the results. SVN revision numbers are strictly added.