WriteTopic

class lsst.ts.salobj.topics.WriteTopic(*, salinfo: SalInfo, attr_name: str, min_seq_num: int | None = 1, max_seq_num: int = 2147483647, initial_seq_num: int | None = None)

Bases: BaseTopic

Base class for topics that are written.

This includes controller events, controller telemetry, remote commands and ackcmd writers.

Parameters:

salinfoSalInfo

SAL component information

attr_namestr

Topic name with attribute prefix. The prefix must be one of: cmd_, evt_, tel_, or (only for the ackcmd topic) ack_.

min_seq_numint or None, optional

Minimum value for the private_seqNum field. The default is 1. If None then private_seqNum is not set; this is needed for the ackcmd writer, which sets the field itself.

max_seq_numint, optional

Maximum value for private_seqNum, inclusive. The default is the maximum allowed positive value (private_seqNum is a 4-byte signed int). Ignored if min_seq_num is None.

initial_seq_numint, optional

Initial sequence number; if None use min_seq_num.

Attributes:

isopenbool

Is this instance open? True until close or basic_close is called.

default_force_outputbool

Default value for the force_output argument of write.

Plus the attributes of:

BaseTopic

Attributes Summary

DataType	The type (class) for a message of this topic.
attr_name	Get the salobj topic attribute name, e.g.
data	Internally cached message.
has_data	Has data ever been set?
sal_name	Get the SAL topic name, e.g.

Methods Summary

basic_close()	A synchronous and possibly less thorough version of close.
close()	Shut down and release resources.
set(**kwargs)	Set one or more fields of message data self.data.
set_write(*[, force_output])	Set zero or more fields of self.data and write if any field changed or if output forced.
write()	Write the current data and return a copy of the data written.

Attributes Documentation

DataType

The type (class) for a message of this topic.

When you read or write a message for this topic you are reading or writing an instance of DataType.

Notes

The preferred way to set data and write a message for a topic is:

• RemoteCommand.set_start to start a command.

• CommandEvent.set_write to write an event.

• CommandTelemetry.set_write to write a telemetry message.

attr_name

Get the salobj topic attribute name, e.g. evt_summaryState.

data

Internally cached message.

Raises:

TypeError

If data is not an instance of DataType

Notes

Do not assume the data will be constant. You can make a copy using copy.copy(data).

has_data

Has data ever been set?

Note: a value of true means at least one field has been set, not that all fields have been set.

sal_name

Get the SAL topic name, e.g. logevent_summaryState.

Methods Documentation

basic_close() → None

A synchronous and possibly less thorough version of close.

Intended for exit handlers and constructor error handlers.

async close() → None

Shut down and release resources.

Intended to be called by SalInfo.close(), since that tracks all topics.

set(**kwargs: Any) → bool

Set one or more fields of message data self.data.

This is useful when accumulating data for a topic in different bits of code. Have each bit of code call set to set the fields it knows about. Have the last bit of code call write to set the remaining fields and write the completed message.

If you have all the information for a topic in one place, it is simpler to call set_write to set all of the fields and write the message.

Parameters:

**kwargsdict [str, any]

Dict of field name: new value for that field:

• Any key whose value is None is checked for existence, but the value of the field is not changed.

• If the field being set is an array then the value must be an array of the same length.

Returns:

did_changebool

True if self.data was changed, or if this was the first call to set.

Raises:

AttributeError

If the topic does not have the specified field.

ValueError

If the field cannot be set to the specified value.

Notes

If one or more fields cannot be set, the message data may be partially updated.

async set_write(*, force_output: bool | None = None, **kwargs: Any) → SetWriteResult

Set zero or more fields of self.data and write if any field changed or if output forced.

Parameters:

force_outputbool, optional

If True then write the event, even if no fields have changed. If None (the default), use the class default, which is True for all except ControllerEvent. (The default value is given by class constant default_force_output).

**kwargsdict [str, any]

The remaining keyword arguments are field name = new value for that field. See set for more information about values.

Returns:

resultSetWriteResult

The resulting data and some flags.

Notes

The reason there are separate set_write and write methods is that write reliably writes the data, whereas the event version of set_write only writes the data if kwargs changes it, or if force_output is true.

async write() → BaseMsgType

Write the current data and return a copy of the data written.

Returns:

dataself.DataType

The data that was written. This can be useful to avoid race conditions (as found in RemoteCommand).

Raises:

RuntimeError

If not running.