Procedural KTL Python

The procedural KTL Python functions implement the original API created in the earliest stages of development on KTL Python. Since then, additional top-level functions were added when necessary to provide new functionality for the object-oriented interface, and it was considered desirable for that same functionality to be exposed via the procedural interface.

Service and keyword manipulation

ktl.cache(service=None, keyword=None)

Return a cached Service or Keyword instance depending on the arguments. A keyword can be specified in service.keyword notation; if a service and a keyword are both specified, the keyword name will be looked up in the appropriate Service instance. If a keyword is not specified, the requested Service instance will be returned.

The same Service or Keyword instance will always be returned upon multiple invocations of cache().

When called with no arguments the full cache of Service isntances will be returned.

Note

The first Service instance created for a given KTL service will never be garbage-collected, and is the instance returned by cache(). The cache can only be cleared by calling purge(); very few applications should need to exercise this functionality.

ktl.close(service, *ignored, **also_ignored)

close() is deprecated, and takes no action. In order to satisfy legacy code, close() always returns True.

Deprecated since version 3.0.

ktl.convert(service, keyword, binary=None, ascii=None)

For a given service and keyword, request a translation for either a KTL binary representation to its KTL ascii representation, or the other way around. You cannot simultaneously specify both binary and ascii values. The return result is the translated value.

ktl.heartbeat(service, keyword)

Designate keyword as a heartbeat keyword for service. See Service.heartbeat() for further details.

ktl.listen(*ignored, **also_ignored)

listen() is deprecated, and takes no action.

Deprecated since version 1.28: KTL Python’s background threads start

automatically, there is no need to explicitly start (or stop) them.

ktl.monitor(service, keyword, callback, data, binary=False)

Subscribe to broadcasts for the designated keyword in the designated service; the callback function will be registered as a handler for all broadcasts. When callback is invoked, the data parameter will be passed to the callback; by default, the keyword value passed to the callback will be the ascii representation; set binary to True to instead receive the binary representation.

See the Callbacks with monitor() section of the Example usage document.

ktl.open(service, *ignored, **also_ignored)

open() is deprecated, and takes no necessary actions. To honor the intent of the caller, open() will ensure that a cached Service instance is available for immediate use. In order to satisfy legacy code, open() always returns True.

Deprecated since version 3.0.

ktl.purge()

purge() clears the internal cache of Service instances (see cache()). This exists for the benefit of the unit test suite which needs to confirm appropriate behavior when deallocating a Service instance.

Warning

There should never be a circumstance where a normal client application needs to invoke purge().

ktl.read(service, keyword, binary=False, both=False, timeout=None)

Perform a ktl_read() operation for the designated keyword in the designated service. read() is a wrapper to Keyword.read(); refer to Keyword.read() for a description of the other arguments.

ktl.subscribe(service, keyword)

Alias for monitor().

ktl.waitFor(expression, timeout=None, service=None, case=False)

Wait for a given expression to be True; see the documentation on Expressions in KTL Python for syntax details. If timeout expires while the expression remains False, waitFor() will return False. If service is specified, it should be a Service instance that will be used to retrieve any Keyword instances used in the expression; if service is specified as a string, a cached Service instance will be used.

ktl.waitfor(expression, timeout=None)

Alias for waitFor().

ktl.write(service, keyword, value, wait=True, binary=False, timeout=None)

Perform a ktl_write() operation for the designated keyword in the designated service. write() is a wrapper to Keyword.write(); refer to Keyword.write() for a description of the other arguments.

Service and keyword metadata

ktl.fdset(service)

Return a tuple of the file descriptors (as numbers) in active use by the designated service.

ktl.keywords(service)

Return a tuple of the keyword names available in the designated service.

ktl.range(service, keyword)

Return a dictionary with keys ‘minimum’ and ‘maximum’ for the designated keyword in the designated service. If the keyword has no range available, a ktlError will be raised; if only one of the minimum or maximum is not set, that specific value will be set to None in the dictionary.

ktl.servers(service, keyword)

Return a tuple of server (dispatcher) names used to implement the designated keyword in the designated service.

ktl.type(service, keyword)

Return the KTL type of the designated keyword in the designated service. The return value will be a string, and will be one of:

'KTL_FLOAT' 'KTL_INT' 'KTL_STRING' 'KTL_BOOLEAN' 'KTL_FLOAT_ARRAY' 'KTL_INT_ARRAY' 'KTL_DOUBLE' 'KTL_DOUBLE_ARRAY' 'KTL_ENUM' 'KTL_ENUMM' 'KTL_MASK'

The KTL_DATATYPE dictionary contains a map between integer and string values for the set of KTL data types.

ktl.units(service, keyword)

Return the description of the units associated with the designated keyword in the designated service. If no such information is available, return None.

Only the units for the ascii representation will be returned. While some KTL client implementations do allow for different units between binary and ascii representations, the fundamental KTL/C interface is not equipped to provide that information.

Logging and reporting

ktl.log()

Log message with the given severity. The message can be any string; severity is expected to be one of: ktl.LOG_NONE ktl.LOG_ERROR ktl.LOG_WARN ktl.LOG_NOTICE ktl.LOG_INFO ktl.LOG_DEBUG

ktl.logger(destination='not specified')

Assign a method to be used for logging. Valid values for destination are the strings ‘stderr’ or ‘stdout’, or a Python object with a .write() method. One particularly useful example of the latter is an open file object.

Whether or not a new destination is specified, the active logger mechanism will be returned.

ktl.loglevel(level=None)

Set the log level to level, an integer expected to be one of:

ktl.LOG_NONE ktl.LOG_ERROR ktl.LOG_WARN ktl.LOG_NOTICE ktl.LOG_INFO ktl.LOG_DEBUG

Whether or not a new level is specified, the current log level will be returned.

ktl.debug(switch)

Turn debug logging on by setting switch to 1; turn it off again by setting switch to 0.

Deprecated since version 1.7: Use loglevel() instead.

ktl.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.