mstrio > python_execution > task

enum mstrio.python_execution.task.ActiveState(value)

Bases: Enum

Valid values are as follows:

INACTIVE = <ActiveState.INACTIVE: 0>

ACTIVE = <ActiveState.ACTIVE: 1>

UNKNOWN = <ActiveState.UNKNOWN: 2>

class mstrio.python_execution.task.LastRunData(status, time_triggered, trigger_user, message=None, time_finished=None, node=None)

Bases: Dictable

Data class representing the last run information of a Planned Task.

Parameters:

• status (TaskRunStatus)

• time_triggered (datetime | str)

• trigger_user (User)

• message (str | None)

• time_finished (datetime | str | None)

• node (Node | str | None)

enum TaskRunStatus(value)

Bases: AutoName

Valid values are as follows:

RESERVE = TaskRunStatus.RESERVE

RUNNING = TaskRunStatus.RUNNING

FAILED = TaskRunStatus.FAILED

SUCCESS = TaskRunStatus.SUCCESS

TIMEOUT = TaskRunStatus.TIMEOUT

The Enum and its members also have the following methods:

classmethod has_value(value)

classmethod bulk_from_dict(source_list, connection=None, to_snake_case=True, with_missing_value=False)

Creates multiple objects from a list of dictionaries. For each dictionary provided the keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in the object’s _FROM_DICT_MAP.

Parameters:

• cls (T) – Class (type) of the objects that should be created.

• source_list (List[Dict[str, Any]]) – A list of dictionaries from which the objects will be constructed.

• connection (Connection, optional) – A MSTR Connection object. Defaults to None.

• to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

• with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

A list of objects of type T.

Return type:

T

classmethod from_dict(source, connection=None, to_snake_case=True, with_missing_value=False)

Creates an object from a dictionary. The dictionary’s keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in _FROM_DICT_MAP.

Parameters:

• cls (T) – Class (type) of an object that should be created.

• source (Dict[str, Any]) – A dictionary from which an object will be constructed.

• connection (Connection, optional) – A MSTR Connection object. Defaults to None.

• to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

• with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

An object of type T.

Return type:

T

to_dict(camel_case=True, whitelist_keys=None, skip_private_keys=False)

Converts an object to a dictionary excluding object’s private properties. When converting the object to a dictionary, the object’s attributes become the dictionary’s keys and are in camel case by default Attribute values stored as objects are automatically converted to non-/ primitive data structures.

Parameters:

• camel_case (bool, optional) – Set to True if attribute names should be converted from snake case to camel case. Defaults to True.

• whitelist_keys (list[str], optional) – List of keys to include in the resulting dictionary. If None, all keys (except hidden ones) are included. Defaults to None.

• skip_private_keys (bool, optional) – If True, skips private keys in final dict representation.

Returns:

A dictionary representation of object’s attributes and values.

By default, the dictionary keys are in camel case.

Return type:

dict

message: str | None = None

node: Node | str | None = None

status: TaskRunStatus

time_finished: datetime | str | None = None

time_triggered: datetime | str

trigger_user: User

class mstrio.python_execution.task.Task(connection, schedule=None, id=None, name=None)

Bases: EntityBase

Class representing a Planned Task entity in Strategy.

A Planned Task is a scheduled execution of a Script within a specific Schedule.

Parameters:

• connection (Connection)

• schedule (Schedule | str | None)

• id (str | None)

• name (str | None)

classmethod bulk_from_dict(source_list, connection=None, to_snake_case=True, with_missing_value=False)

Creates multiple objects from a list of dictionaries. For each dictionary provided the keys in camel case are changed to object’s attribute names (by default in snake case) and dict values are composed to their proper data types such as Enums, list of Enums etc. as specified in the object’s _FROM_DICT_MAP.

Parameters:

• cls (T) – Class (type) of the objects that should be created.

• source_list (List[Dict[str, Any]]) – A list of dictionaries from which the objects will be constructed.

• connection (Connection, optional) – A MSTR Connection object. Defaults to None.

• to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case. Defaults to True.

• with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

A list of objects of type T.

Return type:

T

classmethod create(connection, name, schedule, script, variables_answers=None, active=True, expiration=None, expiration_time_zone=None, execute_on_creation=False)

Create a new Task object.

Parameters:

• connection (Connection) – Strategy connection object returned by connection.Connection().

• name (str) – Name of the task.

• schedule (Schedule | str) – Schedule object, ID or name.

• script (Script | str) – Script object, ID or name.

• variables_answers (VariablesAnswers | None, optional) – Variables answers to be used when executing the script. Defaults to None, meaning none of the prompts in the Script are prompted or there is no Variables used. Can be either a list of VariableAnswer class instances, FlagKeepDefaultAnswer flags or a dict with shape: {“variable-id-or-name”: “answer-value”, …}.

• active (ActiveState | int | bool, optional) – Whether the task is active. Defaults to True.

• expiration (date | str | None, optional) – Expiration date of the task. Defaults to None.

• expiration_time_zone (UnixTimeZone | str | None, optional) – Timezone for the expiration date. Defaults to None.

• execute_on_creation (bool, optional) – If True, the task will be executed immediately after creation. Defaults to False.

Returns:

The created Task object.

Return type:

Task

classmethod from_dict(source, connection, to_snake_case=True, with_missing_value=False)

Overrides Dictable.from_dict() to instantiate an object from

a dictionary without calling any additional getters.

Parameters:

• cls – Class (type) of an object that should be created.

• source (dict[str, Any]) – a dictionary from which an object will be constructed.

• connection (Connection) – A Strategy Connection object.

• to_snake_case (bool, optional) – Set to True if attribute names should be converted from camel case to snake case, default True.

• with_missing_value (bool) – (bool, optional): If True, class attributes possible to fetch and missing in source will be set as MissingValue objects.

Returns:

An instance of the cls class.

classmethod to_csv(objects, name, path=None, properties=None)

Exports MSTR objects to a csv file.

Optionally, saves only the object properties specified in the properties parameter.

Parameters:

• objects (T | list[T]) – List of objects of the same type that

• exported. (will be)

• name (str) – The name of the csv file ending with ‘.csv’

• path (Optional[str], optional) – A path to the directory where the file will be saved. Defaults to None.

• properties (Optional[list[str]], optional) – A list of object’s attribute names that should be included in the exported file. Defaults to None.

Raises:

• TypeError – If objects is not of type T or list of type T

• objects. –

Return type:

None

__init__(connection, schedule=None, id=None, name=None)

Initialize a Task object.

Note

Planned Task is directly coupled with the Schedule so it can be uniquely identified only with a reference to such. When not provided, all of the schedules will be searched for the Task existence.

Also, connection needs to have selected a Project where the Task is stored.

Parameters:

• connection (Connection) – Strategy connection object returned by connection.Connection().

• schedule (Schedule | str, optional) – Schedule object, ID or name.

• id (str, optional) – ID of the task.

• name (str, optional) – Name of the task.

activate(expiration=None, expiration_time_zone=None, remove_expiration_data=False)

Activate the task.

Note

Optionally, you can set an expiration date and time zone for the task at the same time.

Parameters:

• expiration (date | str | None, optional) – Expiration date for the task.

• expiration_time_zone (UnixTimeZone | str | None, optional) – Time zone for the expiration date.

• remove_expiration_data (bool, optional) – If True, removes the expiration date and time zone from the task. Defaults to False.

Raises:

ValueError – If both expiration data and remove_expiration_data are provided.

Return type:

None

alter(name=None, schedule=None, active=None, script=None, variables_answers=None, expiration=None, expiration_time_zone=None, remove_expiration_data=False)

Alter the properties of the task.

Parameters:

• name (str | None, optional) – New name for the task.

• schedule (Schedule | str | None, optional) – New schedule for the task. Can be a Schedule object or its ID or name.

• active (ActiveState | int | bool | None, optional) – New active state for the task.

• script (Script | str | None, optional) – New script for the task. Can be a Script object or its ID or name.

• variables_answers (VariablesAnswers | None, optional) – New variables answers for the script.

• expiration (date | str | None, optional) – New expiration date for the task.

• expiration_time_zone (UnixTimeZone | str | None, optional) – New time zone for the expiration date.

• remove_expiration_data (bool, optional) – If True, removes the expiration date and time zone from the task. Defaults to False.

Raises:

ValueError – If both expiration data and remove_expiration_data are provided.

Return type:

None

deactivate()

Deactivate the task.

Return type:

None

delete(force=False)

Delete the task.

Parameters:

force (bool, optional) – If True, deletes the task without asking for confirmation. Defaults to False.

Returns:

True if the task was deleted, False otherwise.

Return type:

bool

execute(block_until_done=False, raise_on_execution_failure=False)

Execute the task.

Parameters:

• block_until_done (bool, optional) – If True, waits for the task’s execution to finish before returning. Defaults to False.

• raise_on_execution_failure (bool, optional) – If True, raises an exception if the task’s execution fails. Defaults to False. Ignored if block_until_done is False.

Returns:

The last run data of the task if

block_until_done is True, otherwise None.

Return type:

LastRunData | None

Raises:

• ScriptSetupError – If the task is already being executed.

• ScriptExecutionError – If there is an unexpected error while executing the task.

fetch(attr=None)

Fetch the latest object’s state from the I-Server.

Note

This method can overwrite local changes made to the object.

Parameters:

• attr (Optional[str]) – Attribute name to be fetched. If not specified

• dictionary. (it will use all getters specified in _API_GETTERS)

• None. (Defaults to)

Raises:

ValueError – If attr cannot be fetched.

Return type:

None

is_active()

Returns True if the task is active, False otherwise.

Return type:

bool

list_properties(excluded_properties=None)

Fetches all attributes from the server and converts all properties of the object to a dictionary.

Parameters:

excluded_properties (list[str], optional) – A list of object properties that should be excluded from the dict. Defaults to None.

Returns:

A dictionary which keys are object’s attribute names, and

which values are object’s attribute values.

Return type:

dict

print()

Pretty Print all properties of the object.

Return type:

None

to_dataframe()

Converts all properties of the object to a dataframe.

Returns:

A DataFrame object containing object properties.

Return type:

DataFrame

to_dict(camel_case=True, whitelist_keys=None, skip_private_keys=False)

Converts an object to a dictionary excluding object’s private properties. When converting the object to a dictionary, the object’s attributes become the dictionary’s keys and are in camel case by default Attribute values stored as objects are automatically converted to non-/ primitive data structures.

Parameters:

• camel_case (bool, optional) – Set to True if attribute names should be converted from snake case to camel case. Defaults to True.

• whitelist_keys (list[str], optional) – List of keys to include in the resulting dictionary. If None, all keys (except hidden ones) are included. Defaults to None.

• skip_private_keys (bool, optional) – If True, skips private keys in final dict representation.

Returns:

A dictionary representation of object’s attributes and values.

By default, the dictionary keys are in camel case.

Return type:

dict

update_properties()

Save compatible local changes of the object attributes to the I-Server. Changes are retrieved from the self._altered_properties dictionary. After the process of update has finished, self._altered_properties is cleared. For this method to work properly, you must override the _alter_properties() method in a subclass.

Raises:

requests.HTTPError – If I-Server raises exception

Return type:

None

wait_for_execution_finish(interval=None)

Wait for the task’s execution to finish.

Parameters:

interval (int | None, optional) – Time in seconds to wait between polling the task’s status. Defaults to None, which uses the global configuration delay.

Returns:

The last run data of the task.

Return type:

LastRunData

Raises:

• ScriptSetupError – If the task has not been executed yet.

• ScriptExecutionError – If there is an unexpected error while fetching the last run status.

property active: ActiveState

property connection: Connection

An object representation of Strategy connection specific to the object.

property date_created: datetime

property date_modified: datetime

property expiration: date | None

property expiration_time_zone: UnixTimeZone | str | None

property folder_id: str | None

property id: str

The object’s id.

property last_run: LastRunData | None

property owner: User

property project_id: str

property schedule: Schedule

property schedule_id: str

property script: Script

property type: ObjectTypes

The object’s type.

property variables_answers: VariablesAnswers

mstrio.python_execution.task.list_tasks(connection, schedule=None, limit=None, to_dictionary=False, **filters)

Get a list of Planned Tasks.

Parameters:

• connection (Connection) – Strategy connection object returned by connection.Connection().

• schedule (Schedule | str | None, optional) – Schedule object, ID or name to filter tasks by.

• limit (int, optional) – Maximum number of tasks to return.

• to_dictionary (bool, optional) – If True returns dicts, by default (False) returns Task objects.

• **filters – Available filter parameters: [‘id’, ‘type’, ‘active’, ‘name’, ‘date_created’, ‘date_modified’, ‘script’].

Returns:

List of tasks as dicts or as

Task objects.

Return type:

list[dict] | list[Task]