|
| 1 | +from __future__ import annotations |
| 2 | + |
| 3 | +from typing import List, overload |
| 4 | + |
| 5 | +from . import resources, urls |
| 6 | + |
| 7 | + |
| 8 | +class Task(resources.Resource): |
| 9 | + @property |
| 10 | + def id(self) -> str: |
| 11 | + """The task identifier. |
| 12 | +
|
| 13 | + Returns |
| 14 | + ------- |
| 15 | + str |
| 16 | + """ |
| 17 | + return self["id"] |
| 18 | + |
| 19 | + @property |
| 20 | + def is_finished(self) -> bool: |
| 21 | + """The task state. |
| 22 | +
|
| 23 | + If True, the task has completed. The task may have exited successfully |
| 24 | + or have failed. Inspect the error_code to determine if the task finished |
| 25 | + successfully or not. |
| 26 | +
|
| 27 | + Returns |
| 28 | + ------- |
| 29 | + bool |
| 30 | + """ |
| 31 | + return self.get("finished", False) |
| 32 | + |
| 33 | + @property |
| 34 | + def output(self) -> List[str]: |
| 35 | + """Process output. |
| 36 | +
|
| 37 | + The process output produced by the task. |
| 38 | +
|
| 39 | + Returns |
| 40 | + ------- |
| 41 | + List[str] |
| 42 | + """ |
| 43 | + return self["output"] |
| 44 | + |
| 45 | + @property |
| 46 | + def error_code(self) -> int | None: |
| 47 | + """The error code. |
| 48 | +
|
| 49 | + The error code produced by the task. A non-zero value represent an |
| 50 | + error. A zero value represents no error. |
| 51 | +
|
| 52 | + Returns |
| 53 | + ------- |
| 54 | + int | None |
| 55 | + Non-zero value indicates an error. |
| 56 | + """ |
| 57 | + return self["code"] if self.is_finished else None |
| 58 | + |
| 59 | + @property |
| 60 | + def error_message(self) -> str | None: |
| 61 | + """The error message. |
| 62 | +
|
| 63 | + Returns |
| 64 | + ------- |
| 65 | + str | None |
| 66 | + Human readable error message, or None on success or not finished. |
| 67 | + """ |
| 68 | + return self.get("error") if self.is_finished else None |
| 69 | + |
| 70 | + @property |
| 71 | + def result(self) -> dict | None: |
| 72 | + """The task result. |
| 73 | +
|
| 74 | + Returns |
| 75 | + ------- |
| 76 | + dict | None |
| 77 | + """ |
| 78 | + return self.get("result") |
| 79 | + |
| 80 | + # CRUD Methods |
| 81 | + |
| 82 | + @overload |
| 83 | + def update(self, first: int, wait: int, **kwargs) -> None: |
| 84 | + """Update the task. |
| 85 | +
|
| 86 | + Parameters |
| 87 | + ---------- |
| 88 | + first : int, default 0 |
| 89 | + Line to start output on. |
| 90 | + wait : int, default 0 |
| 91 | + Maximum number of seconds to wait for the task to complete. |
| 92 | + """ |
| 93 | + ... |
| 94 | + |
| 95 | + @overload |
| 96 | + def update(self, *args, **kwargs) -> None: |
| 97 | + """Update the task.""" |
| 98 | + ... |
| 99 | + |
| 100 | + def update(self, *args, **kwargs) -> None: |
| 101 | + """Update the task. |
| 102 | +
|
| 103 | + See Also |
| 104 | + -------- |
| 105 | + task.wait_for : Wait for the task to complete. |
| 106 | +
|
| 107 | + Notes |
| 108 | + ----- |
| 109 | + When waiting for a task to complete, one should consider utilizing `task.wait_for`. |
| 110 | +
|
| 111 | + Examples |
| 112 | + -------- |
| 113 | + >>> task.output |
| 114 | + [ |
| 115 | + "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua." |
| 116 | + ] |
| 117 | + >>> task.update() |
| 118 | + >>> task.output |
| 119 | + [ |
| 120 | + "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.", |
| 121 | + "Pretium aenean pharetra magna ac placerat vestibulum lectus mauris." |
| 122 | + ] |
| 123 | + """ |
| 124 | + params = dict(*args, **kwargs) |
| 125 | + path = f"v1/tasks/{self.id}" |
| 126 | + url = urls.append(self.config.url, path) |
| 127 | + response = self.session.get(url, params=params) |
| 128 | + result = response.json() |
| 129 | + super().update(**result) |
| 130 | + |
| 131 | + def wait_for(self) -> None: |
| 132 | + """Wait for the task to finish. |
| 133 | +
|
| 134 | + Examples |
| 135 | + -------- |
| 136 | + >>> task.wait_for() |
| 137 | + None |
| 138 | + """ |
| 139 | + while not self.is_finished: |
| 140 | + self.update() |
| 141 | + |
| 142 | + |
| 143 | +class Tasks(resources.Resources): |
| 144 | + @overload |
| 145 | + def get(self, id: str, first: int, wait: int) -> Task: |
| 146 | + """Get a task. |
| 147 | +
|
| 148 | + Parameters |
| 149 | + ---------- |
| 150 | + id : str |
| 151 | + Task identifier. |
| 152 | + first : int, default 0 |
| 153 | + Line to start output on. |
| 154 | + wait : int, default 0 |
| 155 | + Maximum number of seconds to wait for the task to complete. |
| 156 | +
|
| 157 | + Returns |
| 158 | + ------- |
| 159 | + Task |
| 160 | + """ |
| 161 | + ... |
| 162 | + |
| 163 | + @overload |
| 164 | + def get(self, id: str, *args, **kwargs) -> Task: |
| 165 | + """Get a task. |
| 166 | +
|
| 167 | + Parameters |
| 168 | + ---------- |
| 169 | + id : str |
| 170 | + Task identifier. |
| 171 | +
|
| 172 | + Returns |
| 173 | + ------- |
| 174 | + Task |
| 175 | + """ |
| 176 | + ... |
| 177 | + |
| 178 | + def get(self, id: str, *args, **kwargs) -> Task: |
| 179 | + """Get a task. |
| 180 | +
|
| 181 | + Parameters |
| 182 | + ---------- |
| 183 | + id : str |
| 184 | + Task identifier. |
| 185 | +
|
| 186 | + Returns |
| 187 | + ------- |
| 188 | + Task |
| 189 | + """ |
| 190 | + params = dict(*args, **kwargs) |
| 191 | + path = f"v1/tasks/{id}" |
| 192 | + url = urls.append(self.config.url, path) |
| 193 | + response = self.session.get(url, params=params) |
| 194 | + result = response.json() |
| 195 | + return Task(self.config, self.session, **result) |
0 commit comments