Cauldron User’s API

Users need to only know a few things about the workings of Cauldron:

1. Select an appropriate backend.
2. Configure the backend, if necessary.
3. Activate the backend first in any code which might import KTL API tools.
4. Optionally use Cauldron-style imports in your code.

Selecting a backend

Selecting a backend is fairly easy. Currently, there are three available backends:

• local, which uses in-process methods to communicate between clients and dispatchers. This is the appropraite backend for testing environments, but has no ability to do any inter-process communication.
• zmq, which uses zmq sockets to provide the keyword communication. This is a good backend to use if you are testing multiple components or inter-process communication.
• ktl or DFW, which uses the real KTL API in the Lick or Keck software environment. This is the backend to use with production code.

Your backend should be something that you chose once per python invocation. It is not easy, nor recommended, to switch backends within a given process. New backends are relatively easy to implement in a minimal form (simple, synchronous reads and writes), and you can learn about this in Cauldron Backends.

Configuring the backend

Backends which require configuration get their configuration values from an ini-style configuration document. If the default configuration values are not acceptable, you should provide a configuration file via Cauldron.config.read_configuration():

from Cauldron.config import read_configuration
read_configuration("my_cauldron_config.cfg")

For more information, see Configuring Cauldron.

Activate the backend

Before using any KTL API calls, you must activate the backend via use():

from Cauldron import use
use("local")

If you want to use regular KTL imports in your code, you must also call install(). install() overrides ktl and DFW at runtime, so that when you run code like from DFW import Service, you will recieve the Cauldron version of Service, not the pure KTL version.:

from Cauldron import install
install()

Warning

Using install() performs a runtime hack in sys.modules that might be unstable. For this reason, unless you have an existing codebase that you absolutely cannot change, you should use Cauldron-style imports.

If you do not call install(), you’ll have to use Cauldron-style imports. This is the pre

Cauldron-style imports

When writing code which uses the KTL backend, use a Cauldron-style import to ensure that you recieve the Cauldron version of the KTL API:

from Cauldron import ktl
ktl.write('myservice', 'somekeyword', 10)

This will ensure that the backend is set up correctly before allowing you to import ktl or DFW. If you try to import ktl or DFW before you have selected a backend, using Cauldron-style imports will raise an ImportError.

Using Cauldron with a test-suite

If you wish to use Cauldron with a test suite, it can be desirable to select and start a backend at the invocation of each test. This will flush out persistent keyword values from some backends, and will test that the KTL API is started in the correct order. However, Cauldron will try to prevent the user from selecting a backend while one is already in use. To get around this problem, you can use teardown() to remove the Cauldron backend:

from Cauldron import use, teardown
use("local")
teardown()
use("zmq") # +DOCTEST: SKIP

API Reference

Cauldron.api Module

This module handles the API for the system, registering backends and using them.

Functions

install()	Install the Cauldron modules in the global namespace, so that they will intercept root-level imports.
use(name)	Activae a KTL backend in Cauldron.
teardown()	Remove the Cauldron setup from the sys.modules cache, and prepare for another call to use().
use_strict_xml()	Use strict XML settings.

Classes

APISetting(name, value)

A setting which locks with the API use() calls.

Class Inheritance Diagram