diff --git a/docs/manuals/core/entities/orchestrating-and-job-execution.md b/docs/manuals/core/entities/orchestrating-and-job-execution.md index 4413b4be7..e7dda9727 100644 --- a/docs/manuals/core/entities/orchestrating-and-job-execution.md +++ b/docs/manuals/core/entities/orchestrating-and-job-execution.md @@ -11,7 +11,9 @@ can run different Taipy services, please refer to the In this section, it is assumed that `my_config.py` module contains a Taipy configuration already implemented. -To execute a scenario, you need to call the `taipy.submit()^` method. It returns a list of created `Job^`s: +To execute a scenario, you need to call the `taipy.submit()^` function. It returns a `Submission^` object containing +the information about the submission of the scenario such as the created `Job^`s representing a `Task^` in +the submitted scenario: ```python linenums="1" import taipy as tp @@ -21,7 +23,7 @@ tp.Core().run() scenario = tp.create_scenario(my_config.monthly_scenario_cfg) -jobs = tp.submit(scenario) +submission = tp.submit(scenario) ``` In line 6, we create a new scenario from a scenario configuration and submit it for execution (line 8). @@ -34,11 +36,11 @@ after the Taipy Core service is started. import taipy as tp import my_config +tp.Core().run() + scenario = tp.create_scenario(my_config.monthly_scenario_cfg) tp.submit(scenario) - -tp.Core().run() ``` !!! note "Another syntax." @@ -76,7 +78,9 @@ is no limit to the wait time. If _wait_ is True and _timeout_ is specified, taipy waits until all the submitted jobs are finished, or the timeout expires (which ever occurred first). -It is also possible to submit a single sequence using the same `taipy.submit()^` method. It returns a list of created `Job^`s: +It is also possible to submit a single sequence using the same `taipy.submit()^` function. It returns +a `Submission^` object containing the information about the submission of the sequence such as the created `Job^`s +representing a `Task^` in the submitted sequence: ```python linenums="1" import taipy as tp @@ -87,7 +91,7 @@ tp.Core().run() scenario = tp.create_scenario(my_config.monthly_scenario_cfg) sequence = scenario.sales_sequence -jobs = tp.submit(sequence) +submission = tp.submit(sequence) ``` In line 5, we retrieve the sequence named `sales_sequence` from the created scenario. In line 7, we submit this @@ -108,7 +112,8 @@ submitting a sequence, you can also use the two parameters _wait_ and _timeout_. sequence.submit() ``` -You can also submit a single task with the same `taipy.submit()^` method. It returns the created `Job^`: +You can also submit a single task with the same `taipy.submit()^` function. It returns a `Submission^` object containing +the information about the submission of the task such as the created `Job^` representing the submitted `Task^`: ```python linenums="1" import taipy as tp @@ -119,7 +124,7 @@ tp.Core().run() scenario = tp.create_scenario(my_config.monthly_scenario_cfg) task = scenario.predicting -job = tp.submit(task) +submission = tp.submit(task) ``` In line 5, we retrieve the task named `predicting` from the created scenario. In line 7, we submit this @@ -139,14 +144,95 @@ task for execution. When submitting a task, you can also use the two parameters task.submit() ``` +# Submission + +Each time a `Scenario^`, a `Sequence^` or a `Task^` is submitted, a new `Submission^` entity is created. + +## Submission attributes + +Here is the list of the `Submission^`'s attributes: + +- *entity_id*: The identifier of the entity that was submitted. +- _id_: The identifier of the `Submission^` entity. +- _jobs_: A list of jobs. +- _properties_: A dictionary of additional properties. +- _creation_date_: The date of this submission's creation. +- _submission_status_: The current status of this submission. +- _version_: The string indicates the application version of the submission to instantiate. + If not provided, the latest version is used. + +## Submission Status + +- `SUBMITTED`: The submission has been submitted for execution but not processed yet by the orchestrator. +- `UNDEFINED`: The submission's jobs have been submitted for execution but got some undefined status changes. +- `PENDING`: The orchestrator has enqueued the submission. It is waiting for an available worker to start executing a first job. + for its execution. +- `BLOCKED`: The submission is blocked by at least one blocked job waiting for its input data nodes to be ready. +- `RUNNING`: The submission has its jobs currently being executed. +- `CANCELED`: The submission has been submitted but its execution has been canceled. +- `FAILED`: The submission has a job that failed during its execution. +- `COMPLETED`: The submission has successfully been executed. + +## Get/Delete Submission + +A `Submission^` object is created when a `Scenario^`, a `Sequence^` or a `Task^` is submitted. + +- You can get the latest submission of a `Scenario^`, a `Sequence^` or a `Task^` with `taipy.get_latest_submission()^`. +- You can retrieve a `Submission^` from its id by using the `taipy.get()^` function. + +A Submission can be deleted using the `taipy.delete()^` function. + +Deleting a Submission can raise a `SubmissionNotDeletedException^` if the `Status^` of the Submission is not `CANCELED`, +`COMPLETED`, `FAILED` or `UNDEFINED`. + +!!! example + + ```python linenums="1" + import taipy as tp + + def double(nb): + return nb * 2 + + print(f'(1) Number of submission: {len(tp.get_submissions())}.') + + # Create a scenario then submit it. + input_data_node_config = tp.configure_data_node("input", default_data=21) + output_data_node_config = tp.configure_data_node("output") + task_config = tp.configure_task("double_task", double) + scenario_config = tp.configure_scenario("my_scenario", [task_config]) + + tp.Core().run() + + scenario = tp.create_scenario(scenario_config) + tp.submit(scenario) + + # Retrieve all submission. + print(f'(2) Number of submissions: {len(tp.get_submissions())}.') + + # Get the latest created submission of the scenario. + tp.get_latest_submission(scenario) + + # Then delete it. + tp.delete(submission) + print(f'(3) Number of submissions: {len(tp.get_submissions())}.') + ``` + +This example will produce the following output: + +``` +(1) Number of submissions: 0. +(2) Number of submissions: 1. +(3) Number of submissions: 0. +``` + # Job -Each time a task is submitted (through a `Scenario^` or a `Sequence^` submission), a new +Each time a task is orchestrated (through a `Scenario^`, a `Sequence^` or a `Task^` submission), a new `Job^` entity is instantiated. ## Job attributes -Here is the list of the job's attributes: +Here is the list of the `Job^`'s attributes: - _task_: The `Task^` of the job. - _force_: The force attribute is `True` if the execution of the job has been forced. diff --git a/docs/relnotes.md b/docs/relnotes.md index a1886a130..99af46cd8 100644 --- a/docs/relnotes.md +++ b/docs/relnotes.md @@ -40,6 +40,8 @@ This is the list of changes to Taipy releases as they were published. The function `taipy.get_latest_submission()^` was also added to retrieve the last submitted entity. For more information, refer to [TODO](). +- `taipy.submit()^`, `Scenario.submit()^`, `Sequence.submit()^` and `Task.submit()^` now return a `Submission^` entity. + - The `modin` exposed type as been deprecated. When used, a fallback on pandas is applied. For more information, refer to [issue #631](https://github.com/Avaiga/taipy/issues/631).