alt.hst.api.session Module#

HyperStudy Python APIs

class HstMessageWriter(*_unused_args: Any, **_unused_kwargs: Any)#

Bases: object

Default implementation of a custom message writer that can be registered with HyperStudy. This class can be used as a base class for custom message writers. It can be instantiated and registered using registerMessageWriter or used as a context manager, in which case registration and unregistration is handled automatically.

Note

This is not meant to be used as a logging utility. It serves as a sink for log messages coming from HyperStudy.

Example - Simple custom message writer.#

class CustomWriter(HstMessageWriter):
    def write(self, number, message, messageType):
        print(f"{number}: {message}")

with CustomWriter() as writer:
    study = getSession().getStudyList().add()

__enter__() → HstMessageWriter#

Implementation of object.__enter__ method so this class can be used as a context manager.

Returns:: The message writer instance.
Return type:: HstMessageWriter

__exit__(exc_type: Type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None) → None#

Implementation of object.__exit__ method so this class can be used as a context manager. If an exception caused the context to exit, then the parameters describe that exception.

Parameters:

exc_type (Optional[Type[BaseException]]) – The exception type.
exc_val (Optional[BaseException]) – The exception value.
exc_tb (Optional[TracebackType]) – The exception traceback.

formatMessage(number: int, message: str, messageType: int) → str#

Format a message for logging. This can be overridden to provide different message formats for custom writers.

Parameters:

number (int) – The current message count.
message (str) – The message to format.
messageType –
The type of message to post.
- MESSAGE_TYPE_ERROR (0): An error message.
- MESSAGE_TYPE_INFO (1): An information message.
- MESSAGE_TYPE_VERBOSE (2): A verbose message.
- MESSAGE_TYPE_WARNING (3): A warning message.
- MESSAGE_TYPE_TIMING (4): A timing message.

write(number: int, message: str, messageType: int) → None#

Write a log message. This will be called anytime a message is logged in HyperStudy. This method can be overridden to send log messages to different outputs.

Parameters:

number (int) – The current message count.
message (str) – The message to post.
messageType (int) –
The type of message to post.
- MESSAGE_TYPE_ERROR (0) An error message.
- MESSAGE_TYPE_INFO (1) An information message.
- MESSAGE_TYPE_VERBOSE (2) A verbose message.
- MESSAGE_TYPE_WARNING (3) A warning message.
- MESSAGE_TYPE_TIMING (4) A timing message.

MESSAGE_TYPE_ERROR: Final[int] = 0#

MESSAGE_TYPE_INFO: Final[int] = 1#

MESSAGE_TYPE_TIMING: Final[int] = 4#

MESSAGE_TYPE_VERBOSE: Final[int] = 2#

MESSAGE_TYPE_WARNING: Final[int] = 3#

class MessageService(msgWrap: hstapi.HstMsgWrap)#

Bases: object

A service for logging and showing dialogs in HyperStudy.

Warning

This class should not be instantiated directly. Use getMessageService to get an instance.

dialog(strMsg: str, dlgType: int = 0, strDetail: str = '') → int#

Show a message dialog.

Parameters:

strMsg (str) – The message to show.
dlgType (int) –
The type of dialog to show.
- DIALOG_TYPE_INFO (0) An information dialog.
- DIALOG_TYPE_WARNING (1) A warning dialog.
- DIALOG_TYPE_ERROR (2) An error dialog.
- HST_DIALOG_HELP (3) A help dialog.
- DIALOG_TYPE_YESNO (4) An info dialog with Yes and No butons.
- DIALOG_TYPE_YESNO_WARNING (5) A warning dialog with Yes, No, and Cancel buttons.
- DIALOG_TYPE_YESNOCANCEL (6) An info dialog with Yes, No, and Cancel buttons.
- DIALOG_TYPE_YESNOCANCEL_WARNING (7) A warning dialog with Yes, No, and Cancel buttons.
- DIALOG_TYPE_OKCANCEL (8) An info dialog with Ok and Cancel buttons.
- DIALOG_TYPE_OKCANCEL_WARNING (9) A warning dialog with Ok and Cancel buttons.
strDetail (str) – Additional detail to show in the dialog.

Returns:

The result of the dialog.

DIALOG_RESULT_UNDEFINED (-2)
DIALOG_RESULT_CANCEL (-1)
DIALOG_RESULT_NO (0)
DIALOG_RESULT_YES (1)
DIALOG_RESULT_OK (2)

Return type:

int

postError(strMsg: str) → None#

Post an error message.

Parameters:: strMsg (str) – The message to post.

postInfo(strMsg: str) → None#

Post an info message.

Parameters:: strMsg (str) – The message to post.

postVerbose(strMsg: str, level: int = 0) → None#

Post a verbose info message. These messages will only show if the application’s verbose level is greater or equal to the given level.

Parameters:

strMsg (str) – The message to post.
level (int) – The verbosity level required for the message to post.

postVerboseWarning(strMsg: str) → None#

Post a verbose warning message. These messages will only show if the application’s verbose level is greater or equal to the given level.

Parameters:: strMsg – The message to post.

postWarning(strMsg: str) → None#

Post a warning message.

Parameters:: strMsg (str) – The message to post.

registerMessageWriter(messageWriter: HstMessageWriter) → bool#

Register a new message writer to route log messages.

Parameters:: messageWriter (HstMessageWriter) – The message writer to register.
Returns:: True if the writer was registered, False otherwise.
Return type:: bool

unregisterMessageWriter(messageWriter: HstMessageWriter) → bool#

Unregister an existing message writer.

Parameters:: messageWriter (HstMessageWriter) – The message writer to unregister.
Returns:: True if the writer was unregistered, False otherwise.
Return type:: bool

DIALOG_RESULT_CANCEL = -1#

DIALOG_RESULT_NO = 0#

DIALOG_RESULT_OK = 2#

DIALOG_RESULT_UNDEFINED = -2#

DIALOG_RESULT_YES = 1#

DIALOG_TYPE_ERROR = 2#

DIALOG_TYPE_INFO = 0#

DIALOG_TYPE_OKCANCEL = 8#

DIALOG_TYPE_OKCANCEL_WARNING = 9#

DIALOG_TYPE_WARNING = 1#

DIALOG_TYPE_YESNO = 4#

DIALOG_TYPE_YESNOCANCEL = 6#

DIALOG_TYPE_YESNOCANCEL_WARNING = 7#

DIALOG_TYPE_YESNO_WARNING = 5#

HST_DIALOG_HELP = 3#

PYTHON_CONSOLE_OUTPUT_STDERR = 2#

PYTHON_CONSOLE_OUTPUT_STDOUT = 1#

getCurrentUtilityContext() → HstUtilityContext#

Access to the current user interface context. This is only used in the GUI.

Example - Use the utility context to get the current Approach.#

utilityContext = getCurrentUtilityContext()
currentApproach = utilityContext.getApproach()

Returns:: The current user interface context.
Return type:: hstutilitycontext.HstUtility

getMessageService() → MessageService#

Get a MessageService instance that can be used for logging and showing dialogs.

Example - Post an information message.#

messageService = getMessageService()
messageService.postInfo("This is an information message.")

Returns:: The MessageService instance.
Return type:: MessageService

getSession() → Session#

Get the HyperStudy Session instance.

Returns:: The HyperStudy Session instance.
Return type:: api_objects.Session

getStudy() → Study#

Get the first Study from the Study list.

Returns:: The first Study from the Study list.
Return type:: api_objects.Study
Raises:: Exception – If no Studies are loaded.

getStudyList() → StudyList#

Get the list of all Study Items. This list should usually only have 1 Item.

Returns:: The list of all Study Items.
Return type:: api_objects.StudyList

openStudyArchive(archivePath: str) → Study#

Open a study archive.

Parameters:: archivePath (str) – The path to the Study archive.
Returns:: The Study object.
Return type:: api_objects.Study
Raises:: RuntimeError – If the Study archive could not be opened.

openStudyFile(filePath: str) → Study#

Open a study file.

Parameters:: filePath (str) – The path to the Study file.
Returns:: The Study object.
Return type:: api_objects.Study
Raises:: RuntimeError – If the Study file could not be opened.