Cauldron User’s API¶
Users need to only know a few things about the workings of
- Select an appropriate backend.
- Configure the backend, if necessary.
- Activate the backend first in any code which might import KTL API tools.
- 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.
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
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
from Cauldron import use use("local")
If you want to use regular KTL imports in your code, you must also call
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()
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.
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
DFW. If you try to import
DFW before you have selected a backend, using Cauldron-style imports will raise an
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
from Cauldron import use, teardown use("local") teardown() use("zmq") # +DOCTEST: SKIP
This module handles the API for the system, registering backends and using them.
||Install the Cauldron modules in the global namespace, so that they will intercept root-level imports.|
||Activae a KTL backend in Cauldron.|
||Remove the Cauldron setup from the sys.modules cache, and prepare for another call to
||Use strict XML settings.|
Class Inheritance Diagram¶