prefect-client 2.19.7__tar.gz → 2.19.9__tar.gz

{prefect-client-2.19.7/src/prefect_client.egg-info → prefect-client-2.19.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: prefect-client
-Version: 2.19.7
+Version: 2.19.9
 Summary: Workflow orchestration and management.
 Home-page: https://www.prefect.io
 Author: Prefect Technologies, Inc.

{prefect-client-2.19.7 → prefect-client-2.19.9}/requirements-client.txt

@@ -6,7 +6,7 @@ coolname >= 1.0.4, < 3.0.0
 croniter >= 1.0.12, < 3.0.0
 fsspec >= 2022.5.0
 graphviz >= 0.20.1
-griffe >= 0.20.0
+griffe >= 0.20.0, <0.48.0
 httpcore >=1.0.5, < 2.0.0
 httpx[http2] >= 0.23, != 0.23.2
 importlib_metadata >= 4.4; python_version < '3.10'

{prefect-client-2.19.7 → prefect-client-2.19.9}/requirements.txt

@@ -9,7 +9,7 @@ cryptography >= 36.0.1
 dateparser >= 1.1.1, < 2.0.0
 docker >= 4.0
 graphviz >= 0.20.1
-griffe >= 0.20.0
+griffe >= 0.20.0, <0.48.0
 jinja2 >= 3.0.0, < 4.0.0
 jinja2-humanize-extension >= 0.4.0
 humanize >= 4.9.0

{prefect-client-2.19.7 → prefect-client-2.19.9}/setup.cfg

@@ -52,6 +52,7 @@ filterwarnings =
 	ignore::ResourceWarning
 	ignore::pytest.PytestUnraisableExceptionWarning
 	ignore::pluggy.PluggyTeardownRaisedWarning
+	ignore::prefect._internal.compatibility.deprecated.PrefectDeprecationWarning
 
 [mypy]
 plugins = 

{prefect-client-2.19.7 → prefect-client-2.19.9}/src/prefect/client/schemas/objects.py

@@ -17,6 +17,7 @@ import pendulum
 
 from prefect._internal.compatibility.deprecated import (
     DeprecatedInfraOverridesField,
+    deprecated_class,
 )
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
 from prefect.types import NonNegativeInteger, PositiveInteger
@@ -917,6 +918,10 @@ class Flow(ObjectBaseModel):
         return raise_on_name_with_banned_characters(v)
 
 
+@deprecated_class(
+    start_date="Jun 2024",
+    help="Will be removed in Prefect 3 in favor of prefect.client.schemas.actions.DeploymentScheduleCreate",
+)
 class MinimalDeploymentSchedule(PrefectBaseModel):
     schedule: SCHEDULE_TYPES = Field(
         default=..., description="The schedule for the deployment."

{prefect-client-2.19.7 → prefect-client-2.19.9}/src/prefect/deployments/deployments.py

@@ -238,12 +238,17 @@ async def run_deployment(
     return flow_run
 
 
+@deprecated_callable(
+    start_date="Jun 2024",
+    help="Will be moved in Prefect 3 to prefect.flows:load_flow_from_flow_run",
+)
 @inject_client
 async def load_flow_from_flow_run(
     flow_run: FlowRun,
     client: PrefectClient,
     ignore_storage: bool = False,
     storage_base_path: Optional[str] = None,
+    use_placeholder_flow: bool = True,
 ) -> Flow:
     """
     Load a flow from the location/script provided in a deployment's storage document.
@@ -270,7 +275,7 @@ async def load_flow_from_flow_run(
             f"Importing flow code from module path {deployment.entrypoint}"
         )
         flow = await run_sync_in_worker_thread(
-            load_flow_from_entrypoint, deployment.entrypoint
+            load_flow_from_entrypoint, deployment.entrypoint, use_placeholder_flow
         )
         return flow
 
@@ -314,7 +319,9 @@ async def load_flow_from_flow_run(
             ).absolute()
     run_logger.debug(f"Importing flow code from '{import_path}'")
 
-    flow = await run_sync_in_worker_thread(load_flow_from_entrypoint, str(import_path))
+    flow = await run_sync_in_worker_thread(
+        load_flow_from_entrypoint, str(import_path), use_placeholder_flow
+    )
 
     return flow
 

{prefect-client-2.19.7 → prefect-client-2.19.9}/src/prefect/engine.py

@@ -113,7 +113,10 @@ from typing_extensions import Literal
 import prefect
 import prefect.context
 import prefect.plugins
-from prefect._internal.compatibility.deprecated import deprecated_parameter
+from prefect._internal.compatibility.deprecated import (
+    deprecated_callable,
+    deprecated_parameter,
+)
 from prefect._internal.compatibility.experimental import experimental_parameter
 from prefect._internal.concurrency.api import create_call, from_async, from_sync
 from prefect._internal.concurrency.calls import get_current_call
@@ -417,9 +420,12 @@ async def retrieve_flow_then_begin_flow_run(
 
     try:
         flow = (
-            load_flow_from_entrypoint(entrypoint)
+            # We do not want to use a placeholder flow at runtime
+            load_flow_from_entrypoint(entrypoint, use_placeholder_flow=False)
             if entrypoint
-            else await load_flow_from_flow_run(flow_run, client=client)
+            else await load_flow_from_flow_run(
+                flow_run, client=client, use_placeholder_flow=False
+            )
         )
     except Exception:
         message = (
@@ -975,6 +981,10 @@ async def orchestrate_flow_run(
     return state
 
 
+@deprecated_callable(
+    start_date="Jun 2024",
+    help="Will be moved in Prefect 3 to prefect.flow_runs:pause_flow_run",
+)
 @overload
 async def pause_flow_run(
     wait_for_input: None = None,
@@ -987,6 +997,10 @@ async def pause_flow_run(
     ...
 
 
+@deprecated_callable(
+    start_date="Jun 2024",
+    help="Will be moved in Prefect 3 to prefect.flow_runs:pause_flow_run",
+)
 @overload
 async def pause_flow_run(
     wait_for_input: Type[T],
@@ -1095,6 +1109,10 @@ async def pause_flow_run(
         )
 
 
+@deprecated_callable(
+    start_date="Jun 2024",
+    help="Will be moved in Prefect 3 to prefect.flow_runs:_in_process_pause",
+)
 @inject_client
 async def _in_process_pause(
     timeout: int = 3600,
@@ -1190,6 +1208,10 @@ async def _in_process_pause(
     raise FlowPauseTimeout("Flow run was paused and never resumed.")
 
 
+@deprecated_callable(
+    start_date="Jun 2024",
+    help="Will be moved in Prefect 3 to prefect.flow_runs.pause_flow_run.",
+)
 @inject_client
 async def _out_of_process_pause(
     flow_run_id: UUID,
@@ -1212,6 +1234,10 @@ async def _out_of_process_pause(
         raise RuntimeError(response.details.reason)
 
 
+@deprecated_callable(
+    start_date="Jun 2024",
+    help="Will be moved in Prefect 3 to prefect.flow_runs:suspend_flow_run",
+)
 @overload
 async def suspend_flow_run(
     wait_for_input: None = None,
@@ -1343,6 +1369,10 @@ async def suspend_flow_run(
         raise Pause()
 
 
+@deprecated_callable(
+    start_date="Jun 2024",
+    help="Will be moved in Prefect 3 to prefect.flow_runs:resume_flow_run",
+)
 @sync_compatible
 async def resume_flow_run(flow_run_id, run_input: Optional[Dict] = None):
     """
@@ -1375,6 +1405,7 @@ def enter_task_run_engine(
     return_type: EngineReturnType,
     task_runner: Optional[BaseTaskRunner],
     mapped: bool,
+    entering_from_task_run: Optional[bool] = False,
 ) -> Union[PrefectFuture, Awaitable[PrefectFuture], TaskRun]:
     """Sync entrypoint for task calls"""
 
@@ -1402,14 +1433,20 @@ def enter_task_run_engine(
     if flow_run_context.timeout_scope and flow_run_context.timeout_scope.cancel_called:
         raise TimeoutError("Flow run timed out")
 
+    call_arguments = {
+        "task": task,
+        "flow_run_context": flow_run_context,
+        "parameters": parameters,
+        "wait_for": wait_for,
+        "return_type": return_type,
+        "task_runner": task_runner,
+    }
+
+    if not mapped:
+        call_arguments["entering_from_task_run"] = entering_from_task_run
+
     begin_run = create_call(
-        begin_task_map if mapped else get_task_call_return_value,
-        task=task,
-        flow_run_context=flow_run_context,
-        parameters=parameters,
-        wait_for=wait_for,
-        return_type=return_type,
-        task_runner=task_runner,
+        begin_task_map if mapped else get_task_call_return_value, **call_arguments
     )
 
     if task.isasync and (
@@ -1536,6 +1573,7 @@ async def get_task_call_return_value(
     return_type: EngineReturnType,
     task_runner: Optional[BaseTaskRunner],
     extra_task_inputs: Optional[Dict[str, Set[TaskRunInput]]] = None,
+    entering_from_task_run: Optional[bool] = False,
 ):
     extra_task_inputs = extra_task_inputs or {}
 
@@ -1546,6 +1584,7 @@ async def get_task_call_return_value(
         wait_for=wait_for,
         task_runner=task_runner,
         extra_task_inputs=extra_task_inputs,
+        entering_from_task_run=entering_from_task_run,
     )
     if return_type == "future":
         return future
@@ -1564,12 +1603,14 @@ async def create_task_run_future(
     wait_for: Optional[Iterable[PrefectFuture]],
     task_runner: Optional[BaseTaskRunner],
     extra_task_inputs: Dict[str, Set[TaskRunInput]],
+    entering_from_task_run: Optional[bool] = False,
 ) -> PrefectFuture:
     # Default to the flow run's task runner
     task_runner = task_runner or flow_run_context.task_runner
 
     # Generate a name for the future
     dynamic_key = _dynamic_key_for_task_run(flow_run_context, task)
+
     task_run_name = (
         f"{task.name}-{dynamic_key}"
         if flow_run_context and flow_run_context.flow_run
@@ -1604,8 +1645,9 @@ async def create_task_run_future(
         )
     )
 
-    # Track the task run future in the flow run context
-    flow_run_context.task_run_futures.append(future)
+    if not entering_from_task_run:
+        # Track the task run future in the flow run context
+        flow_run_context.task_run_futures.append(future)
 
     if task_runner.concurrency_type == TaskConcurrencyType.SEQUENTIAL:
         await future._wait()

{prefect-client-2.19.7 → prefect-client-2.19.9}/src/prefect/exceptions.py

@@ -178,7 +178,10 @@ class ParameterTypeError(PrefectException):
 
     @classmethod
     def from_validation_error(cls, exc: ValidationError) -> Self:
-        bad_params = [f'{".".join(err["loc"])}: {err["msg"]}' for err in exc.errors()]
+        bad_params = [
+            f'{".".join(str(item) for item in err["loc"])}: {err["msg"]}'
+            for err in exc.errors()
+        ]
         msg = "Flow run received invalid parameters:\n - " + "\n - ".join(bad_params)
         return cls(msg)
 

{prefect-client-2.19.7 → prefect-client-2.19.9}/src/prefect/flows.py

@@ -28,6 +28,8 @@ from typing import (
     List,
     NoReturn,
     Optional,
+    Set,
+    Tuple,
     Type,
     TypeVar,
     Union,
@@ -75,6 +77,7 @@ from prefect.exceptions import (
     MissingFlowError,
     ObjectNotFound,
     ParameterTypeError,
+    ScriptError,
     UnspecifiedFlowError,
 )
 from prefect.filesystems import ReadableDeploymentStorage
@@ -1647,6 +1650,7 @@ def load_flow_from_script(path: str, flow_name: str = None) -> Flow:
 
 def load_flow_from_entrypoint(
     entrypoint: str,
+    use_placeholder_flow: bool = True,
 ) -> Flow:
     """
     Extract a flow object from a script at an entrypoint by running all of the code in the file.
@@ -1654,6 +1658,9 @@ def load_flow_from_entrypoint(
     Args:
         entrypoint: a string in the format `<path_to_script>:<flow_func_name>` or a module path
             to a flow function
+        use_placeholder_flow: If True, a placeholder flow will be used if the entrypoint
+            cannot be loaded for any reason (e.g. dependencies are missing). If False, an
+            exception will be raised.
 
     Returns:
         The flow object from the script
@@ -1677,6 +1684,17 @@ def load_flow_from_entrypoint(
             raise MissingFlowError(
                 f"Flow function with name {func_name!r} not found in {path!r}. "
             ) from exc
+        except ScriptError as exc:
+            # If the flow has dependencies that are not installed in the current
+            # environment, fallback to loading the flow via AST parsing. The
+            # drawback of this approach is that we're unable to actually load the
+            # function, so we create a placeholder flow that will re-raise this
+            # exception when called.
+
+            if use_placeholder_flow:
+                flow = load_placeholder_flow(entrypoint=entrypoint, raises=exc)
+            else:
+                raise
 
         if not isinstance(flow, Flow):
             raise MissingFlowError(
@@ -1802,24 +1820,138 @@ async def serve(
     await runner.start()
 
 
-def load_flow_argument_from_entrypoint(
-    entrypoint: str, arg: str = "name"
-) -> Optional[str]:
+def load_placeholder_flow(entrypoint: str, raises: Exception):
     """
-    Extract a flow argument from an entrypoint string.
+    Load a placeholder flow that is initialized with the same arguments as the
+    flow specified in the entrypoint. If called the flow will raise `raises`.
 
-    Loads the source code of the entrypoint and extracts the flow argument from the
-    `flow` decorator.
+    This is useful when a flow can't be loaded due to missing dependencies or
+    other issues but the base metadata defining the flow is still needed.
 
     Args:
-        entrypoint: a string in the format `<path_to_script>:<flow_func_name>` or a module path
-            to a flow function
+        entrypoint: a string in the format `<path_to_script>:<flow_func_name>`
+          or a module path to a flow function
+        raises: an exception to raise when the flow is called
+    """
+
+    def _base_placeholder():
+        raise raises
+
+    def sync_placeholder_flow(*args, **kwargs):
+        _base_placeholder()
+
+    async def async_placeholder_flow(*args, **kwargs):
+        _base_placeholder()
+
+    placeholder_flow = (
+        async_placeholder_flow
+        if is_entrypoint_async(entrypoint)
+        else sync_placeholder_flow
+    )
+
+    arguments = load_flow_arguments_from_entrypoint(entrypoint)
+    arguments["fn"] = placeholder_flow
+
+    return Flow(**arguments)
+
+
+def load_flow_arguments_from_entrypoint(
+    entrypoint: str, arguments: Optional[Union[List[str], Set[str]]] = None
+) -> Dict[str, Any]:
+    """
+    Extract flow arguments from an entrypoint string.
+
+    Loads the source code of the entrypoint and extracts the flow arguments
+    from the `flow` decorator.
+
+    Args:
+        entrypoint: a string in the format `<path_to_script>:<flow_func_name>`
+          or a module path to a flow function
+    """
+
+    func_def, source_code = _entrypoint_definition_and_source(entrypoint)
+
+    if arguments is None:
+        # If no arguments are provided default to known arguments that are of
+        # built-in types.
+        arguments = {
+            "name",
+            "version",
+            "retries",
+            "retry_delay_seconds",
+            "description",
+            "timeout_seconds",
+            "validate_parameters",
+            "persist_result",
+            "cache_result_in_memory",
+            "log_prints",
+        }
+
+    result = {}
+
+    for decorator in func_def.decorator_list:
+        if (
+            isinstance(decorator, ast.Call)
+            and getattr(decorator.func, "id", "") == "flow"
+        ):
+            for keyword in decorator.keywords:
+                if keyword.arg not in arguments:
+                    continue
+
+                if isinstance(keyword.value, ast.Constant):
+                    # Use the string value of the argument
+                    result[keyword.arg] = str(keyword.value.value)
+                    continue
+
+                # if the arg value is not a raw str (i.e. a variable or expression),
+                # then attempt to evaluate it
+                namespace = safe_load_namespace(source_code)
+                literal_arg_value = ast.get_source_segment(source_code, keyword.value)
+                cleaned_value = (
+                    literal_arg_value.replace("\n", "") if literal_arg_value else ""
+                )
+
+                try:
+                    evaluated_value = eval(cleaned_value, namespace)  # type: ignore
+                    result[keyword.arg] = str(evaluated_value)
+                except Exception as e:
+                    logger.info(
+                        "Failed to parse @flow argument: `%s=%s` due to the following error. Ignoring and falling back to default behavior.",
+                        keyword.arg,
+                        literal_arg_value,
+                        exc_info=e,
+                    )
+                    # ignore the decorator arg and fallback to default behavior
+                    continue
+
+    if "name" in arguments and "name" not in result:
+        # If no matching decorator or keyword argument for `name' is found
+        # fallback to the function name.
+        result["name"] = func_def.name.replace("_", "-")
+
+    return result
+
+
+def is_entrypoint_async(entrypoint: str) -> bool:
+    """
+    Determine if the function specified in the entrypoint is asynchronous.
+
+    Args:
+        entrypoint: A string in the format `<path_to_script>:<func_name>` or
+          a module path to a function.
 
     Returns:
-        The flow argument value
+        True if the function is asynchronous, False otherwise.
     """
+    func_def, _ = _entrypoint_definition_and_source(entrypoint)
+    return isinstance(func_def, ast.AsyncFunctionDef)
+
+
+def _entrypoint_definition_and_source(
+    entrypoint: str,
+) -> Tuple[Union[ast.FunctionDef, ast.AsyncFunctionDef], str]:
     if ":" in entrypoint:
-        # split by the last colon once to handle Windows paths with drive letters i.e C:\path\to\file.py:do_stuff
+        # Split by the last colon once to handle Windows paths with drive letters i.e C:\path\to\file.py:do_stuff
         path, func_name = entrypoint.rsplit(":", maxsplit=1)
         source_code = Path(path).read_text()
     else:
@@ -1828,6 +1960,7 @@ def load_flow_argument_from_entrypoint(
         if not spec or not spec.origin:
             raise ValueError(f"Could not find module {path!r}")
         source_code = Path(spec.origin).read_text()
+
     parsed_code = ast.parse(source_code)
     func_def = next(
         (
@@ -1844,42 +1977,8 @@ def load_flow_argument_from_entrypoint(
         ),
         None,
     )
+
     if not func_def:
         raise ValueError(f"Could not find flow {func_name!r} in {path!r}")
-    for decorator in func_def.decorator_list:
-        if (
-            isinstance(decorator, ast.Call)
-            and getattr(decorator.func, "id", "") == "flow"
-        ):
-            for keyword in decorator.keywords:
-                if keyword.arg == arg:
-                    if isinstance(keyword.value, ast.Constant):
-                        return (
-                            keyword.value.value
-                        )  # Return the string value of the argument
-
-                    # if the arg value is not a raw str (i.e. a variable or expression),
-                    # then attempt to evaluate it
-                    namespace = safe_load_namespace(source_code)
-                    literal_arg_value = ast.get_source_segment(
-                        source_code, keyword.value
-                    )
-                    try:
-                        evaluated_value = eval(literal_arg_value, namespace)  # type: ignore
-                    except Exception as e:
-                        logger.info(
-                            "Failed to parse @flow argument: `%s=%s` due to the following error. Ignoring and falling back to default behavior.",
-                            arg,
-                            literal_arg_value,
-                            exc_info=e,
-                        )
-                        # ignore the decorator arg and fallback to default behavior
-                        break
-                    return str(evaluated_value)
-
-    if arg == "name":
-        return func_name.replace(
-            "_", "-"
-        )  # If no matching decorator or keyword argument is found
 
-    return None
+    return func_def, source_code

{prefect-client-2.19.7 → prefect-client-2.19.9}/src/prefect/runner/server.py

@@ -202,7 +202,7 @@ def _build_generic_endpoint_for_flows(
 
         try:
             flow = load_flow_from_entrypoint(body.entrypoint)
-        except (MissingFlowError, ScriptError, ModuleNotFoundError):
+        except (FileNotFoundError, MissingFlowError, ScriptError, ModuleNotFoundError):
             return JSONResponse(
                 status_code=status.HTTP_404_NOT_FOUND,
                 content={"message": "Flow not found"},

{prefect-client-2.19.7 → prefect-client-2.19.9}/src/prefect/tasks.py

@@ -6,7 +6,6 @@ Module containing the base workflow task class and decorator - for most use case
 
 import datetime
 import inspect
-import os
 from copy import copy
 from functools import partial, update_wrapper
 from typing import (
@@ -76,6 +75,8 @@ P = ParamSpec("P")  # The parameters of the task
 
 logger = get_logger("tasks")
 
+NUM_CHARS_DYNAMIC_KEY: int = 8
+
 
 def task_input_hash(
     context: "TaskRunContext", arguments: Dict[str, Any]
@@ -125,6 +126,28 @@ def exponential_backoff(backoff_factor: float) -> Callable[[int], List[float]]:
     return retry_backoff_callable
 
 
+def _generate_task_key(fn: Callable[..., Any]) -> str:
+    """Generate a task key based on the function name and source code.
+    We may eventually want some sort of top-level namespace here to
+    disambiguate tasks with the same function name in different modules,
+    in a more human-readable way, while avoiding relative import problems (see #12337).
+    As long as the task implementations are unique (even if named the same), we should
+    not have any collisions.
+    Args:
+        fn: The function to generate a task key for.
+    """
+    if not hasattr(fn, "__qualname__"):
+        return to_qualified_name(type(fn))
+
+    qualname = fn.__qualname__.split(".")[-1]
+
+    code_hash = (
+        h[:NUM_CHARS_DYNAMIC_KEY] if (h := hash_objects(fn.__code__)) else "unknown"
+    )
+
+    return f"{qualname}-{code_hash}"
+
+
 @PrefectObjectRegistry.register_instances
 class Task(Generic[P, R]):
     """
@@ -292,17 +315,7 @@ class Task(Generic[P, R]):
 
         self.tags = set(tags if tags else [])
 
-        if not hasattr(self.fn, "__qualname__"):
-            self.task_key = to_qualified_name(type(self.fn))
-        else:
-            try:
-                task_origin_hash = hash_objects(
-                    self.name, os.path.abspath(inspect.getsourcefile(self.fn))
-                )
-            except TypeError:
-                task_origin_hash = "unknown-source-file"
-
-            self.task_key = f"{self.fn.__qualname__}-{task_origin_hash}"
+        self.task_key = _generate_task_key(self.fn)
 
         self.cache_key_fn = cache_key_fn
         self.cache_expiration = cache_expiration
@@ -685,6 +698,7 @@ class Task(Generic[P, R]):
                 return_type=return_type,
                 client=get_client(),
             )
+        entering_from_task_run = bool(TaskRunContext.get())
 
         return enter_task_run_engine(
             self,
@@ -693,6 +707,7 @@ class Task(Generic[P, R]):
             task_runner=SequentialTaskRunner(),
             return_type=return_type,
             mapped=False,
+            entering_from_task_run=entering_from_task_run,
         )
 
     @overload

{prefect-client-2.19.7 → prefect-client-2.19.9}/src/prefect/utilities/asyncutils.py

@@ -261,14 +261,14 @@ def sync_compatible(async_fn: T) -> T:
     """
 
     @wraps(async_fn)
-    def coroutine_wrapper(*args, **kwargs):
+    def coroutine_wrapper(*args, _sync: Optional[bool] = None, **kwargs):
         from prefect._internal.concurrency.api import create_call, from_sync
         from prefect._internal.concurrency.calls import get_current_call, logger
         from prefect._internal.concurrency.event_loop import get_running_loop
         from prefect._internal.concurrency.threads import get_global_loop
         from prefect.settings import PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT
 
-        if PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT:
+        if PREFECT_EXPERIMENTAL_DISABLE_SYNC_COMPAT or _sync is False:
             return async_fn(*args, **kwargs)
 
         global_thread_portal = get_global_loop()
@@ -276,12 +276,17 @@ def sync_compatible(async_fn: T) -> T:
         current_call = get_current_call()
         current_loop = get_running_loop()
 
-        if current_thread.ident == global_thread_portal.thread.ident:
+        if (
+            current_thread.ident == global_thread_portal.thread.ident
+            and _sync is not True
+        ):
             logger.debug(f"{async_fn} --> return coroutine for internal await")
             # In the prefect async context; return the coro for us to await
             return async_fn(*args, **kwargs)
-        elif in_async_main_thread() and (
-            not current_call or is_async_fn(current_call.fn)
+        elif (
+            in_async_main_thread()
+            and (not current_call or is_async_fn(current_call.fn))
+            and _sync is not True
         ):
             # In the main async context; return the coro for them to await
             logger.debug(f"{async_fn} --> return coroutine for user await")