Script Helper Module

The Script Helper module provides simple functions for scripting use cases to interact directly with the ODA database, defining the simplest interface a user needs to perform the action without having to create a UnitOfWork directly.

Execution Blocks

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

Helper module for common functionality used in observing scripts.

These functions connect directly to a database using the UnitOfWork so require PG_ environment variables to be set.

ska_db_oda.script_helper.capture_request_response(fn)

Append the request_response from the decorated function to the current ExecutionBlock.

Uses the EB_ID environment variable to look up the target ExecutionBlock. Any persistence failures are logged and do not block execution of the decorated function.

Return type:

Callable

ska_db_oda.script_helper.create_eb(telescope, sbi_ref=None)

Create an “empty” ExecutionBlock in the ODA database.

The created identifier is written to the EB_ID environment variable so subsequent capture_request_response calls can associate records with the same ExecutionBlock.

Parameters:

• telescope (TelescopeType) – telescope from which this EB originates

• sbi_ref (Optional[str]) – SBInstance identifier to associate with the created ExecutionBlock

Return type:

str

Returns:

persisted ExecutionBlock identifier

Raises:

ConnectionError – if database persistence fails or no identifier is returned

ska_db_oda.script_helper.save(sbd)

Persist an SBDefinition entity in the ODA database.

If the identifier field (sbd_id) is not present in the object, a new SBDefinition will be created. If the identifier field is present, the version of that identifier in the database will be updated.

Parameters:

sbd (SBDefinition) – an SBDefinition to be persisted

Return type:

SBDefinition

Returns:

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

Raises:

ConnectionError – if database persistence fails