YamcsClient¶

class yamcs.client.YamcsClient(address: str, *, tls: bool = False, tls_verify: bool | str = True, credentials: Credentials | None = None, user_agent: str | None = None, keep_alive: bool = True, on_token_update: Callable[[Credentials], None] | None = None)¶

Bases: object

Client for accessing core Yamcs resources.

Parameters:

• address – The address of Yamcs in the format ‘hostname:port’

• tls – Whether TLS encryption is expected

• tls_verify – Whether server certificate verification is enabled (only applicable if tls=True). As an alternative to a boolean value, this option may be set to a path containing the appropriate TLS CA certificate bundle.

• credentials – Credentials for when the server is secured

• user_agent – Optionally override the default user agent

• keep_alive –

  Automatically renew the client session. If disabled, the session will terminate after about 30 minutes of inactivity.

  This property is only considered when accessing a server that requires authentication.

close()¶

Close this client session

compact_rdb_column_family(tablespace: str, cf: str, dbpath: str | None = None)¶

Compact a RocksDB column family.

Parameters:

• tablespace – RocksDB tablespace name

• cf – Column family name

• dbpath – Optional path under the tablespace root.

create_event_subscription(instance: str, on_data: Callable[[Event], None], filter: str | None = None, timeout: float = 60) → WebSocketSubscriptionFuture¶

Create a new subscription for receiving events of an instance.

This method returns a future, then returns immediately. Stop the subscription by canceling the future.

Parameters:

• instance – A Yamcs instance name

• on_data – Function that gets called on each Event.

• filter –

  Filter query applied to returned events. Allows for both text and field search.

  Added in version 1.10.1: Compatible with Yamcs v5.10.2 onwards

• timeout – The amount of seconds to wait for the request to complete.

Returns:

Future that can be used to manage the background websocket subscription.

create_instance(name: str, template: str, args: Mapping[str, Any] | None = None, labels: Mapping[str, str] | None = None)¶

Create a new instance based on an existing template. This method blocks until the instance is fully started.

Parameters:

• instance – A Yamcs instance name.

• template – The name of an existing template.

create_link_subscription(instance: str, on_data: Callable[[List[Link]], None] | None = None, timeout: float = 60) → LinkSubscription¶

Create a new subscription for receiving data link updates of an instance.

This method returns a future, then returns immediately. Stop the subscription by canceling the future.

Parameters:

• instance – A Yamcs instance name.

• on_data – Function that gets called with Link updates. Each update contains state of all links.

• timeout – The amount of seconds to wait for the request to complete.

Returns:

Future that can be used to manage the background websocket subscription.

create_time_subscription(instance: str, on_data: Callable[[datetime], None] | None = None, timeout: float = 60) → TimeSubscription¶

Create a new subscription for receiving time updates of an instance. Time updates are emitted at 1Hz.

This method returns a future, then returns immediately. Stop the subscription by canceling the future.

Parameters:

• instance – A Yamcs instance name

• on_data – Function that gets called with datetime updates.

• timeout – The amount of seconds to wait for the request to complete.

Returns:

Future that can be used to manage the background websocket subscription.

delete_processor(instance: str, processor: str)¶

Delete a processor.

Parameters:

• instance – A Yamcs instance name.

• processor – A processor name within that instance.

static from_environment()¶

Create a YamcsClient, initialized from environment variables.

This recognizes the following environment variables:

YAMCS_URL

Yamcs server URL

YAMCS_API_KEY

Yamcs API key (currently only assigned to script activities)

get_archive(instance: str) → ArchiveClient¶

Return an object for working with the Archive of the specified instance.

Parameters:

instance – A Yamcs instance name.

get_auth_info() → AuthInfo¶

Returns general authentication information. This operation does not require authenticating and is useful to test if a server requires authentication or not.

get_file_transfer_client(instance: str) → FileTransferClient¶

Return an object for working with file transfers on a specified instance.

Parameters:

instance – A Yamcs instance name.

get_link(instance: str, link: str) → LinkClient¶

Return an object for working with a specific Yamcs link.

Parameters:

• instance – A Yamcs instance name.

• link – A link name within that instance.

get_mdb(instance: str) → MDBClient¶

Return an object for working with the MDB of the specified instance.

Parameters:

instance – A Yamcs instance name.

get_processor(instance: str, processor: str) → ProcessorClient¶

Return an object for working with a specific Yamcs processor.

Parameters:

• instance – A Yamcs instance name.

• processor – A processor name within that instance.

get_server_info() → ServerInfo¶

Return general server info.

get_storage_client() → StorageClient¶

Return an object for working with object storage

get_tco_client(instance: str, service: str) → TCOClient¶

Return an object for Time Correlation API calls on a specified service.

Parameters:

• instance – A Yamcs instance name.

• service – Target service name.

get_time(instance) → datetime | None¶

Return the current mission time for the specified instance.

get_timeline_client(instance: str) → TimelineClient¶

Return an object for working with Yamcs timeline items

Parameters:

instance – A Yamcs instance name.

get_user_info() → UserInfo¶

Get information on the authenticated user.

list_instance_templates() → Iterable[InstanceTemplate]¶

List the available instance templates.

list_instances() → Iterable[Instance]¶

Lists the instances.

Instances are returned in lexicographical order.

list_links(instance: str) → Iterable[Link]¶

Lists the data links visible to this client.

Data links are returned in random order.

Parameters:

instance – A Yamcs instance name.

list_processors(instance: str | None = None) → Iterable[Processor]¶

Lists the processors.

Processors are returned in lexicographical order.

Parameters:

instance – A Yamcs instance name.

list_rdb_tablespaces() → Iterable[RdbTablespace]¶

Lists RocksDB tablespaces.

list_services(instance: str) → Iterable[Service]¶

List the services for an instance.

Parameters:

instance – A Yamcs instance name.

load_parameter_values(instance: str, data: Iterator[Mapping[str, 'ValueUpdate']], stream: str = 'pp_dump', chunk_size: int = 32768) → LoadParameterValuesResult¶

Load an indefinite amount of parameter values into Yamcs.

Added in version 1.9.1: Compatible with Yamcs 5.8.8 onwards

Parameters:

• instance – Yamcs instance name

• data – Generator that yields batches of parameter values, keyed by parameter name.

• stream – Stream where to send the parameters to.

• chunk_size – HTTP chunk size. Multiple updates are grouped in chunks of about this size.

restart_instance(instance: str)¶

Restarts a single instance.

Parameters:

instance – A Yamcs instance name.

send_event(instance: str, message: str, event_type: str | None = None, time: datetime | None = None, severity: str | None = 'info', source: str | None = None, sequence_number: int | None = None, extra: Mapping[str, str] | None = None)¶

Post a new event.

Parameters:

• instance – A Yamcs instance name.

• message – Event message.

• event_type – Type of event.

• severity – The severity level of the event. One of info, watch, warning, distress, critical or severe. Defaults to info.

• time – Time of the event. If unspecified, defaults to mission time.

• source – Source of the event. Useful for grouping events in the archive. When unset this defaults to User.

• event_type – Event type.

• sequence_number – Sequence number of this event. This is used to determine unicity of events at the same time and coming from the same source. If not set Yamcs will automatically assign a sequential number as if every submitted event is unique.

• extra –

  Extra event properties.

  Added in version 1.8.4: Compatible with Yamcs 5.7.3 onwards

start_instance(instance: str)¶

Starts a single instance.

Parameters:

instance – A Yamcs instance name.

start_service(instance: str, service: str)¶

Starts a single service.

Parameters:

• instance – A Yamcs instance name.

• service – The name of the service.

stop_instance(instance: str)¶

Stops a single instance.

Parameters:

instance – A Yamcs instance name.

stop_service(instance: str, service: str)¶

Stops a single service.

Parameters:

• instance – A Yamcs instance name.

• service – The name of the service.

class yamcs.client.TimeSubscription(manager)¶

Bases: WebSocketSubscriptionFuture

Local object providing access to time updates.

A subscription object stores the last time info.

Initializes the future. Should not be called by clients.

time: datetime | None¶

The last time info.

class yamcs.client.LinkSubscription(manager)¶

Bases: WebSocketSubscriptionFuture

Local object providing access to data link updates.

A subscription object stores the last link info for each link.

Initializes the future. Should not be called by clients.

get_link(name: str) → Link | None¶

Returns the latest link state.

Parameters:

name – Identifying name of the data link

list_links() → List[Link]¶

Returns a snapshot of all links.