Config Data Classes

Overview

ska_tmc_common.v4.ska_device_config groups the settings that TMC component managers need into a small hierarchy of dataclasses instead of long, error-prone constructor argument lists. A component manager takes a single config object, and every config class in the hierarchy is built by inheriting only the fields that class actually needs:

TimeoutConfig – timeout and polling-period settings shared by every TMC component manager.
TelmodelConfig – Telescope Model source/path settings.
BaseTmcComponentManagerConfig – settings common to both node and leaf node component managers (extends TimeoutConfig).
TmcComponentManagerConfig – adds the node-specific settings (component) on top of BaseTmcComponentManagerConfig.
TmcLeafNodeConfig – the leaf node specific config, also extending BaseTmcComponentManagerConfig.

1. TimeoutConfig

class ska_tmc_common.v4.ska_device_config.TimeoutConfig(*, proxy_timeout: int = 50, adapter_timeout: float = 2.0, command_timeout: float = 30.0, event_subscription_check_period: float = 1.0, liveliness_check_period: float = 1.0)

Configuration for timeouts in TMC components.

proxy_timeout: int = 50

adapter_timeout: float = 2.0

command_timeout: float = 30.0

event_subscription_check_period: float = 1.0

liveliness_check_period: float = 1.0

2. TelmodelConfig

class ska_tmc_common.v4.ska_device_config.TelmodelConfig(*, telmodel_source: str, telmodel_path: str)

Configuration for the Telmodel in TMC components.

telmodel_source: str

telmodel_path: str

3. BaseTmcComponentManagerConfig

class ska_tmc_common.v4.ska_device_config.BaseTmcComponentManagerConfig(*, proxy_timeout: int = 50, adapter_timeout: float = 2.0, command_timeout: float = 30.0, event_subscription_check_period: float = 1.0, liveliness_check_period: float = 1.0, logger: logging.Logger = <Mock name='mock()' id='131989254439168'>, liveliness_probe_type: LivelinessProbeType = LivelinessProbeType.NONE, event_manager_enabled: bool = False, communication_state_callback: Optional[Callable] = None, component_state_callback: Optional[Callable] = None, input_parameter: Optional[InputParameter] = None)

Common configuration shared by all TMC component managers.

This dataclass mirrors the BaseTmcComponentManager and groups the settings that every TMC component manager (node as well as leaf node) requires, such as the logger, liveliness probe type, event manager flag, communication/component state callbacks, input parameter and the various timeouts.

logger: logging.Logger = <Mock name='mock()' id='131989254439168'>

liveliness_probe_type: LivelinessProbeType = 0

event_manager_enabled: bool = False

communication_state_callback: Callable | None = None

component_state_callback: Callable | None = None

input_parameter: InputParameter | None = None

4. TmcComponentManagerConfig

class ska_tmc_common.v4.ska_device_config.TmcComponentManagerConfig(*, proxy_timeout: int = 50, adapter_timeout: float = 2.0, command_timeout: float = 30.0, event_subscription_check_period: float = 1.0, liveliness_check_period: float = 1.0, logger: logging.Logger = <Mock name='mock()' id='131989254439168'>, liveliness_probe_type: LivelinessProbeType = LivelinessProbeType.MULTI_DEVICE, event_manager_enabled: bool = True, communication_state_callback: Optional[Callable] = None, component_state_callback: Optional[Callable] = None, input_parameter: Optional[InputParameter] = None, component: Optional[TmcComponent] = None)

Configuration for the TmcComponentManager (TMC node component). Extends BaseTmcComponentManagerConfig with the managed component, and overrides the liveliness probe type and event manager flag defaults to the values used by the node.

component: TmcComponent | None = None

liveliness_probe_type: LivelinessProbeType = 2

event_manager_enabled: bool = True

5. TmcLeafNodeConfig

class ska_tmc_common.v4.ska_device_config.TmcLeafNodeConfig(*, proxy_timeout: int = 50, adapter_timeout: float = 2.0, command_timeout: float = 30.0, event_subscription_check_period: float = 1.0, liveliness_check_period: float = 1.0, logger: logging.Logger = <Mock name='mock()' id='131989254439168'>, liveliness_probe_type: LivelinessProbeType = LivelinessProbeType.NONE, event_manager_enabled: bool = True, communication_state_callback: Optional[Callable] = None, component_state_callback: Optional[Callable] = None, input_parameter: Optional[InputParameter] = None)

Configuration for the TmcLeafNodeComponentManager. Extends BaseTmcComponentManagerConfig, which already carries the adapter and command timeouts via TimeoutConfig, with the settings that are specific to the TMC leaf node component manager.

event_manager_enabled: bool = True

Guidelines: Adding or Changing Fields

These dataclasses are constructed by every downstream repository that uses ska-tmc-common, so a field added carelessly here becomes a breaking change several repositories away. Before adding or changing a field:

Put the field in the narrowest class that needs it. Shared timeouts belong on TimeoutConfig; node-only or leaf-only settings belong on TmcComponentManagerConfig or TmcLeafNodeConfig respectively. Don’t widen a base class just to save one subclass a line – it forces every other subclass to carry a field it doesn’t use.
Always use @dataclass(kw_only=True). Every class in this module is keyword-only. This means adding a new field never shifts the positional meaning of existing fields, so existing call sites that construct a config with keyword arguments keep working unchanged.
Give new fields a default whenever possible. A field without a default forces every downstream constructor call to be updated immediately. Only leave a field without a default (like TelmodelConfig.telmodel_source) when there genuinely is no safe value to assume.
Never use a mutable default directly. Use field(default_factory=...) for anything mutable (dict, list, another dataclass instance). A bare = [] or = {} is shared across every instance of the class.
Watch out for circular imports. Some fields need to reference types defined in modules that import this one back (e.g. TmcComponent). Keep from __future__ import annotations at the top of the module and import those types only under if TYPE_CHECKING: – the annotation is still valid for type checkers and documentation, but no runtime import cycle is created.
Treat a default-value change like an API change, not a tweak. Changing an existing field’s default (or its type, e.g. an int timeout becoming a float to allow sub-second precision) silently changes behaviour for every downstream repository that doesn’t override it explicitly. Call this out clearly in the changelog entry rather than folding it into an unrelated commit.
Document units and constraints in the field’s docstring or an inline comment. A dataclass field carries no context of its own – state explicitly whether a timeout is in seconds, whether None is a valid value and what it means, etc.
Keep this page and CHANGELOG.rst up to date. These config classes are part of the public API surface once exported; treat adding, renaming or removing a field the same way you’d treat changing a public method signature.