README.md 2.59 KB
Newer Older
Daniel Eggert's avatar
Daniel Eggert committed
1
## dasf-progress-api
Adam Sasin's avatar
Adam Sasin committed
2

Daniel Eggert's avatar
Daniel Eggert committed
3
4
5
6
7
8
Progress api for DASF modules based on python. Developed and tested with Python 3.8

### Scope
This library is part of the Data Analytics Software Framework DASF (https://git.geomar.de/digital-earth/dasf), 
which was developed by the GFZ Potsdam (https://www.gfz-potsdam.de)
in the Digital Earth project (https://www.digitalearth-hgf.de/).
Adam Sasin's avatar
Adam Sasin committed
9

Daniel Eggert's avatar
Daniel Eggert committed
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
### Usage

A progress report is stored in a tree structure. So there will be one 'root' report instance containing multiple 'sub-reports'.

The root report will be initialized directly. The contructor demands a `send_handler` argument, so we need to create one first. 
The `dasf-messaging-python` module provides a ready to use implementation for the `send_handler` via the `ProgressSendHandler` class.
In order to instantiate the send handler you need to pass the `PulsarMessageConsumer` that is used to receive the request that is monitored,
as well as the corresponding request message. You might add additional message properties via the `msg_props` dictionary.

```python
from demessaging.progress_send_handler import ProgressSendHandler

send_handler=ProgressSendHandler(pulsar=self.__pulsar,
                                 request_msg=request_msg,
                                 msg_props={'additional': 'some addtional property'})
```

Once we have a `send_handler` we can use it to create the 'root' progress report for the request.
In case we already know how many steps (sub-reports) there are going to be on the next level, we can pass it via the optional `steps` argument.

```python
root_report = ProgressReport(step_message="Label/message of the root report",
                                 send_handler=send_handler,
                                 steps=2)
```

Once we have the root report instance we create new subreports for it via the `create_subreport` method. 
Each created report is published automatically upon creation and completion.

Daniel Eggert's avatar
Daniel Eggert committed
39
```python
Daniel Eggert's avatar
Daniel Eggert committed
40
41
42
43
44
45
46
47
48
49
50
51
52
# create a subreport
sub_report = root_report.create_subreport(step_message="Calculating something")

# execute some logic
# ...

# mark the sub-report as compelte
sub_report.complete()
```

All sub-reports are again instances of `ProgressReport`, so you can create more sub-reports for each.

#### error handling
Daniel Eggert's avatar
Daniel Eggert committed
53
For now there is no distinct error flag in the report. 
Daniel Eggert's avatar
Daniel Eggert committed
54
55
But you can update the `step_message` prop before marking it as complete to indicate an error.

Daniel Eggert's avatar
Daniel Eggert committed
56
```python
Daniel Eggert's avatar
Daniel Eggert committed
57
58
59
60
61
62
63
# some code that raises an exception
# ...
except Exception as e:
    error = str(e)
    progress_report.step_message = "error '{msg}': {err}".format(msg=progress_report.step_message, err=error)
    progress_report.complete()
```