|
| 1 | +"""Cloud examples interface for fetching and copying Flow360 examples""" |
| 2 | + |
| 3 | +from __future__ import annotations |
| 4 | + |
| 5 | +import difflib |
| 6 | +import time |
| 7 | +from typing import List, Optional, Tuple |
| 8 | + |
| 9 | +import pydantic as pd_v2 |
| 10 | + |
| 11 | +from flow360.cloud.flow360_requests import CopyExampleRequest |
| 12 | +from flow360.cloud.responses import ( |
| 13 | + CopyExampleResponse, |
| 14 | + ExampleItem, |
| 15 | + ExamplesListResponse, |
| 16 | +) |
| 17 | +from flow360.cloud.rest_api import RestApi |
| 18 | +from flow360.component.interfaces import ProjectInterface |
| 19 | +from flow360.environment import Env |
| 20 | +from flow360.exceptions import Flow360Error, Flow360ValueError, Flow360WebError |
| 21 | +from flow360.log import log |
| 22 | + |
| 23 | + |
| 24 | +def find_example_by_name(query_name: str, examples: List[ExampleItem]) -> Tuple[ExampleItem, float]: |
| 25 | + """ |
| 26 | + Find the best matching example by name using fuzzy string matching. |
| 27 | +
|
| 28 | + Parameters |
| 29 | + ---------- |
| 30 | + query_name : str |
| 31 | + The name to search for (case-insensitive, handles typos). |
| 32 | + examples : List[ExampleItem] |
| 33 | + List of available examples to search through. |
| 34 | +
|
| 35 | + Returns |
| 36 | + ------- |
| 37 | + Tuple[ExampleItem, float] |
| 38 | + The best matching example and its similarity score (0.0 to 1.0). |
| 39 | +
|
| 40 | + Raises |
| 41 | + ------ |
| 42 | + Flow360ValueError |
| 43 | + If no examples are provided or no match is found. |
| 44 | + """ |
| 45 | + if not examples: |
| 46 | + raise Flow360ValueError("No examples available to search.") |
| 47 | + |
| 48 | + query_lower = query_name.lower().strip() |
| 49 | + best_match = None |
| 50 | + best_score = 0.0 |
| 51 | + |
| 52 | + for example in examples: |
| 53 | + example_title_lower = example.title.lower() |
| 54 | + score = difflib.SequenceMatcher(None, query_lower, example_title_lower).ratio() |
| 55 | + |
| 56 | + if score > best_score: |
| 57 | + best_score = score |
| 58 | + best_match = example |
| 59 | + |
| 60 | + if best_match is None or best_score < 0.3: |
| 61 | + available_names = [ex.title for ex in examples] |
| 62 | + raise Flow360ValueError( |
| 63 | + f"No matching example found for '{query_name}'. " |
| 64 | + f"Available examples: {', '.join(available_names[:5])}" |
| 65 | + + (f" (and {len(available_names) - 5} more)" if len(available_names) > 5 else "") |
| 66 | + ) |
| 67 | + |
| 68 | + return best_match, best_score |
| 69 | + |
| 70 | + |
| 71 | +def fetch_examples() -> List[ExampleItem]: |
| 72 | + """ |
| 73 | + Fetch available examples from the cloud. |
| 74 | +
|
| 75 | + Returns |
| 76 | + ------- |
| 77 | + List[ExampleItem] |
| 78 | + List of available example items. |
| 79 | + """ |
| 80 | + api = RestApi("public/v2/examples") |
| 81 | + resp = api.get() |
| 82 | + if resp is None: |
| 83 | + return [] |
| 84 | + try: |
| 85 | + response_model = ExamplesListResponse(**resp if isinstance(resp, dict) else {"data": resp}) |
| 86 | + return response_model.data |
| 87 | + except (pd_v2.ValidationError, TypeError, ValueError) as e: |
| 88 | + log.warning(f"Failed to parse examples response: {e}") |
| 89 | + return [] |
| 90 | + |
| 91 | + |
| 92 | +def show_available_examples() -> None: |
| 93 | + """ |
| 94 | + Display available examples in a formatted table. |
| 95 | +
|
| 96 | + Shows a list of pre-executed project examples that can be copied and visited |
| 97 | + on the Flow360 web interface. |
| 98 | + """ |
| 99 | + examples = fetch_examples() |
| 100 | + if not examples: |
| 101 | + log.info("No examples available.") |
| 102 | + return |
| 103 | + |
| 104 | + examples_url = Env.current.get_web_real_url("examples") |
| 105 | + log.info(f"These examples are pre-executed projects that can be visited on {examples_url}") |
| 106 | + log.info("") |
| 107 | + |
| 108 | + title_width = max(len(e.title) for e in examples) |
| 109 | + id_width = max(len(e.id) for e in examples) |
| 110 | + |
| 111 | + header = f"{'#':>3} {'Title'.ljust(title_width)} {'Example ID'.ljust(id_width)} Tags" |
| 112 | + table_string = "" |
| 113 | + table_string += header + "\n" |
| 114 | + table_string += "-" * len(header) + "\n" |
| 115 | + |
| 116 | + for idx, ex in enumerate(examples): |
| 117 | + title = ex.title |
| 118 | + example_id = ex.id |
| 119 | + tags = ", ".join(ex.tags) |
| 120 | + table_string += ( |
| 121 | + f"{idx+1:>3} {title.ljust(title_width)} {example_id.ljust(id_width)} {tags}\n" |
| 122 | + ) |
| 123 | + |
| 124 | + log.info(table_string) |
| 125 | + |
| 126 | + |
| 127 | +def _get_project_copy_status(project_id: str) -> Optional[str]: |
| 128 | + """ |
| 129 | + Get the copy status of a project. |
| 130 | +
|
| 131 | + Parameters |
| 132 | + ---------- |
| 133 | + project_id : str |
| 134 | + Project ID to check. |
| 135 | +
|
| 136 | + Returns |
| 137 | + ------- |
| 138 | + Optional[str] |
| 139 | + Copy status of the project, or None if not available. |
| 140 | + """ |
| 141 | + try: |
| 142 | + project_api = RestApi(ProjectInterface.endpoint, id=project_id) |
| 143 | + info = project_api.get() |
| 144 | + if isinstance(info, dict): |
| 145 | + return info.get("copyStatus") |
| 146 | + except Flow360Error: |
| 147 | + pass |
| 148 | + return None |
| 149 | + |
| 150 | + |
| 151 | +def _wait_for_copy_completion(project_id: str, timeout_minutes: int = 30) -> None: |
| 152 | + """ |
| 153 | + Wait for the copy operation to complete. |
| 154 | +
|
| 155 | + Parameters |
| 156 | + ---------- |
| 157 | + project_id : str |
| 158 | + Project ID to monitor. |
| 159 | + timeout_minutes : int |
| 160 | + Maximum time to wait in minutes. |
| 161 | +
|
| 162 | + Raises |
| 163 | + ------ |
| 164 | + TimeoutError |
| 165 | + If the copy operation doesn't complete within the timeout period. |
| 166 | + """ |
| 167 | + update_every_seconds = 2 |
| 168 | + start_time = time.time() |
| 169 | + max_dots = 30 |
| 170 | + |
| 171 | + with log.status() as status_logger: |
| 172 | + while True: |
| 173 | + copy_status = _get_project_copy_status(project_id) |
| 174 | + if copy_status is not None and copy_status != "copying": |
| 175 | + break |
| 176 | + |
| 177 | + elapsed = time.time() - start_time |
| 178 | + dot_count = int((elapsed // update_every_seconds) % max_dots) |
| 179 | + status_logger.update(f"Copying example{'.' * dot_count}") |
| 180 | + |
| 181 | + if time.time() - start_time > timeout_minutes * 60: |
| 182 | + raise TimeoutError( |
| 183 | + f"Timeout: Copy operation did not finish within {timeout_minutes} minutes." |
| 184 | + ) |
| 185 | + |
| 186 | + time.sleep(update_every_seconds) |
| 187 | + |
| 188 | + |
| 189 | +def copy_example(example_id: str, wait_for_completion: bool = True) -> str: |
| 190 | + """ |
| 191 | + Copy an example from the cloud and return the created project ID. |
| 192 | +
|
| 193 | + Parameters |
| 194 | + ---------- |
| 195 | + example_id : str |
| 196 | + ID of the example to copy. |
| 197 | + wait_for_completion : bool |
| 198 | + Whether to wait for the copy operation to complete before returning. |
| 199 | + Default is True (blocking). |
| 200 | +
|
| 201 | + Returns |
| 202 | + ------- |
| 203 | + str |
| 204 | + Project ID of the newly created project. |
| 205 | +
|
| 206 | + Raises |
| 207 | + ------ |
| 208 | + Flow360WebError |
| 209 | + If the example cannot be copied or the response format is unexpected. |
| 210 | + TimeoutError |
| 211 | + If wait_for_completion is True and the copy doesn't finish within timeout. |
| 212 | + """ |
| 213 | + request = CopyExampleRequest(source_example_id=example_id) |
| 214 | + example_api = RestApi("v2/examples") |
| 215 | + resp = example_api.post(request.dict(), method="copy") |
| 216 | + if not isinstance(resp, dict): |
| 217 | + raise Flow360WebError(f"Unexpected response format when copying example {example_id}") |
| 218 | + response_model = CopyExampleResponse(**resp) |
| 219 | + project_id = response_model.id |
| 220 | + |
| 221 | + if wait_for_completion: |
| 222 | + copy_status = _get_project_copy_status(project_id) |
| 223 | + if copy_status is None or copy_status == "copying": |
| 224 | + if copy_status == "copying": |
| 225 | + log.info( |
| 226 | + f"Copy operation started for project {project_id}. Waiting for completion..." |
| 227 | + ) |
| 228 | + else: |
| 229 | + log.info( |
| 230 | + f"Copy operation initiated for project {project_id}. " |
| 231 | + "Waiting for completion (status unknown, assuming in progress)..." |
| 232 | + ) |
| 233 | + _wait_for_copy_completion(project_id) |
| 234 | + log.info("Copy operation completed successfully.") |
| 235 | + |
| 236 | + return project_id |
0 commit comments