ODA Helper Module

The ODA Helper module offers simple functions which interact with the API, allowing users not to worry about building and handling HTTP requests. So far, it offers functions for specific use cases, rather than acting as a general client library.

As use cases for the ODA expand, we may generalise this helper module. For now we are happy with a lightweight module that is simple to change and provides the required functionality.

Execution Blocks

For example, the ODA offers a custom API for Execution Blocks, so they can be created and updated during telescope operation without operators needing to know the internal ODA details. See the REST API documentation for more.

Generally, it is expected that the create_eb function will be called at the start of a session, and function calls where the request/response should be stored in the ExecutionBlock should be decorated with @capture_request_response. For more context on Execution Blocks, see the section in the Scripting documentation

To view the ExecutionBlock in the ODA, the ODA CLI can be used perform queries (see ODA Command Line Interface (CLI)). Alternatively, the ODA REST API could be used directly.

Module Functions

This helper module is intended to be imported when sending commands to the telescope, for example during a Jupyter notebook session or SB driven observing from the OET.

It provides functionality for specific use cases of interactions with the ODA. As use cases expand, we may look to generalise this. However, for now we are happy to keep it as lightweight as possible. It is imported into the ska-oso-scripting package so users can import it from that namespace.

ska_db_oda.client.oda_helper.capture_request_response(fn: Callable) → Callable[source]

A decorator function which will record requests and responses sent to the telescope in an Execution Block within the ODA. It will send individual request_response objects to the ODA PATCH /ebs/<eb_id>/request_response API over HTTP, containing the decorated function name, the arguments and the return value, as well as timestamps.

Important: the function assumes two environment variables are set:

  • ODA_URL: the location of a running instance of the ODA, eg https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/v1/

  • EB_ID: the identifier of the ExecutionBlock to update. The create_eb function from this module should have already been called during execution, which will set this variable.

The decorator is designed such that it does not block execution of commands if there is a problem with the ODA connection, or the environment variables are not set. Instead, a warning message is logged and execution allowed to continue. Also, any errors raised by the decorated function will not be changed, they will just be recorded in the ODA and reraised.

The standard OSO Scripting functions are decorated using this function, so will automatically record request/responses. To record other function calls in an Execution Block, either use this decorator in your source code:

from ska_db_oda.client.ebclient import capture_request_response

@capture_request_response
def my_function_to_record(args):
    ...

or use at runtime when calling the function:

from ska_db_oda.client.ebclient import capture_request_response

capture_request_response(my_function_to_record)(args)
ska_db_oda.client.oda_helper.create_eb(sbi_ref: str | None = None) → str[source]

Calls the ODA POST /ebs API to create an ‘empty’ ExecutionBlock in the ODA, ready to be updated with request/responses from telescope operation.

This function will also set the EB_ID environment variable to the value of the eb_id returned from the create request, so it can be used by subsequent calls to capture_request_response during the same session.

Important: the ODA_URL environment variables must be set to a running instance of the ODA, eg https://k8s.stfc.skao.int/staging-ska-db-oda/oda/api/v1/

Parameters:

sbi_ref – the identifier of the SBInstance that the created ExecutionBlock should be linked to

Returns:

The eb_id generated from SKUID that is persisted in the ODA

Raises:

  • KeyError – if the ODA_URL variable is not set

  • ConnectionError – if the ODA requests raises an error or returns a status code other than 200

ska_db_oda.client.oda_helper.save(sbd: ska_oso_pdm.entities.common.sb_definition.SBDefinition) → ska_oso_pdm.entities.common.sb_definition.SBDefinition[source]

Persists the entity in the ODA. If the identifier field (e.g. sbd_id for an SBDefinition) is not present in the object, a new version entity will be created with an identifier fetched from SKUID. If the identifier field is present then the version of that identifier in the ODA will be updated, if it exists.

NOTE: this function assumes the ODA_URL environment variable is set to a running instance of the ODA

Parameters:

sbd – an SBDefinition to be persisted

Returns:

the entity as it has been persisted in the ODA, with identifiers and metadata

Raises:

  • KeyError – if ODA_URL is not set or if the identifier is given on the object, but it is not found in the ODA

  • ConnectionError – captures all errors and other responses from the ODA, including serialisation issues