Cauldron Internals

This section documents a few internal features of the Cauldron API. The Types API Reference explains how Cauldron provides type-spcific Keyword classes in a backend-independent way. The API Setup Functions provides a collection of setup and teardown functions, as well as backend-specific implementations of Keyword and Service classes. API Entry Points describes the correct way to enable new or third-party backends with Cauldron. Utilities are small pieces of code which are not specific to Cauldron, but which are widely used. Of particular note is Callbacks which provides a way to maintain weak-references to callback functions, and a quick way to call a set of callback functions with identical arguments.

Types API Reference

Cauldron uses a few root-level modules to reduce code repetition between clients and dispatchers, where the code is reasonably symmetric. For example, KTL Keywords are typed, and the typing interface is implemented for Cauldron in the Cauldron.types module, which provides specialized keyword functionality for various KTL Keyword types. These types are exposed in the main Cauldron._ktl.Keyword and Cauldron._DFW.Keyword modules to the user once a backend has been selected.

Cauldron.types Module

Keywords can have differing python types. The types provide validation and sanitization for keyword values.

In the KTL python API, keyword types are implemented separately for clients and dispatchers. In this module, a single class heirarchy is implemented for clients and dispatchers. Keyword types override parent class methods to provide the necessary behavior, though at a minimum, Keyword types simply set the _type class attribute to a python type.

Functions

dispatcher_keyword(cls)	A decorator to mark classes which should also be exposed in the DFW.Keyword module.
client_keyword(cls)	A decorator to mark classes which should also be exposed in the ktl.Keyword module.

Classes

KeywordType	A base class for all subclasses of KTL Keyword which implement a type specialization.
Basic	The base class for KTL and DFW keywords.
Keyword	An alias for Basic
Boolean	A boolean-valued keyword.
Double	A numerical value keyword.
Float	A numerical value keyword.
Integer	An integer value keyword.
Enumerated	An enumerated keyword, which uses an integer as the underlying datatype.
Mask	The base class for KTL and DFW keywords.
String	An ASCII valued keyword, implemented identically to Basic.
IntegerArray	The base class for KTL and DFW keywords.
FloatArray	The base class for KTL and DFW keywords.
DoubleArray	The base class for KTL and DFW keywords.
ClientKeywordType	Keyword type for ktl clients.
DispatcherKeywordType	Keyword type for dispatchers.

Class Inheritance Diagram

Cauldron.exc Module

Exceptions and warnings.

Classes

NoWriteNecessary	Raised to cancel a keyword write in progress.
CauldronWarning	A base class for all Cauldron warnings.
CauldronException	A base class to collect Cauldron Exceptions & Warnings.
CauldronAPINotImplemented	Exception raised when an API feature is not implemented.
ServiceNotStarted	Exception raised when starting a client which requires a dispatcher, and the dispatcher has not started.

Class Inheritance Diagram

KTL API Features

KTL API features which depend only on the base classes ClientService, ClientKeyword, DispatcherService and DispatcherKeyword can be implemented inside the private _ktl and _DFW modules, which provide the implementation for the KTL API. The only exception are subclasses of ClientKeyword or DispatcherKeyword, which should be implemented in Cauldron.types, and should use the dispatcher_keyword() and client_keyword() decorators in Cauldron.types.

Within these special hidden modules, you may use relative imports to import the implemented Keyword and Service classes, and those imports will work correctly to find the concrete implementations which belong to your backend of choice. To setup additional features of the KTL API which depend on runtime state, you can use the setup API functions.

API Setup Functions

Cauldron backends are registered to make themselves known to the system. registry has two module-level registries, client and dispatcher, both instances of Registry, which are used to track Keyword and Service implementations for each backend, as well as setup and teardown functions. The various methods of Registry which are suffixed with _for are decorators which can mark a class or function as part of a Cauldron backend.

Cauldron.registry Module

A registry of setup and teardown functions for dispatchers and clients.

Functions

keys()	Keys available in both registries.
teardown()	Teardown both the client and dispatcher.

Classes

Registry(name[, doc, modname])

A registry of setup and teardown functions.

Class Inheritance Diagram

API Entry Points

Cauldron uses setuptools Entry Points to seamlessly connect backends to the central Cauldron API. Each entry point is a python object which should either be a module or a function. The modules or functions are resolved at runtime and called to register a new backend with Cauldron. Cauldron backends are registered in the Cauldron.backend entry point. The built-in backends are registered using this method. For example, the local backend entry point is specified as:

local = Cauldron.local:setup_local_backend

Utilities

Cauldron.utils.callbacks Module

Utilities for callback functions

Classes

WeakMethod(meth[, callback])	A weak reference to a method.
Callbacks(*args)	A list of callback functions.

Class Inheritance Diagram

Cauldron.utils.helpers Module

Functions

api_not_implemented(func)	A decorator to correctly set the API not implemented.
api_not_required(func)	A decorator to mark a function as implementing a not-required API
api_required(func)	A decorator to mark a function as abstract and requiring a backend implementation.