prefect-client 3.0.0rc1__py3-none-any.whl → 3.0.0rc3__py3-none-any.whl

prefect/utilities/callables.py

@@ -44,11 +44,23 @@ def get_call_parameters(
     apply_defaults: bool = True,
 ) -> Dict[str, Any]:
     """
-    Bind a call to a function to get parameter/value mapping. Default values on the
-    signature will be included if not overridden.
-
-    Raises a ParameterBindError if the arguments/kwargs are not valid for the function
+    Bind a call to a function to get parameter/value mapping. Default values on
+    the signature will be included if not overridden.
+
+    If the function has a `__prefect_self__` attribute, it will be included as
+    the first parameter. This attribute is set when Prefect decorates a bound
+    method, so this approach allows Prefect to work with bound methods in a way
+    that is consistent with how Python handles them (i.e. users don't have to
+    pass the instance argument to the method) while still making the implicit self
+    argument visible to all of Prefect's parameter machinery (such as cache key
+    functions).
+
+    Raises a ParameterBindError if the arguments/kwargs are not valid for the
+    function
     """
+    if hasattr(fn, "__prefect_self__"):
+        call_args = (fn.__prefect_self__,) + call_args
+
     try:
         bound_signature = inspect.signature(fn).bind(*call_args, **call_kwargs)
     except TypeError as exc:
@@ -456,7 +468,14 @@ def _generate_signature_from_source(
         (
             node
             for node in ast.walk(parsed_code)
-            if isinstance(node, ast.FunctionDef) and node.name == func_name
+            if isinstance(
+                node,
+                (
+                    ast.FunctionDef,
+                    ast.AsyncFunctionDef,
+                ),
+            )
+            and node.name == func_name
         ),
         None,
     )
@@ -464,6 +483,26 @@ def _generate_signature_from_source(
         raise ValueError(f"Function {func_name} not found in source code")
     parameters = []
 
+    # Handle annotations for positional only args e.g. def func(a, /, b, c)
+    for arg in func_def.args.posonlyargs:
+        name = arg.arg
+        annotation = arg.annotation
+        if annotation is not None:
+            try:
+                ann_code = compile(ast.Expression(annotation), "<string>", "eval")
+                annotation = eval(ann_code, namespace)
+            except Exception as e:
+                logger.debug("Failed to evaluate annotation for %s: %s", name, e)
+                annotation = inspect.Parameter.empty
+        else:
+            annotation = inspect.Parameter.empty
+
+        param = inspect.Parameter(
+            name, inspect.Parameter.POSITIONAL_ONLY, annotation=annotation
+        )
+        parameters.append(param)
+
+    # Determine the annotations for args e.g. def func(a: int, b: str, c: float)
     for arg in func_def.args.args:
         name = arg.arg
         annotation = arg.annotation
@@ -486,6 +525,7 @@ def _generate_signature_from_source(
         )
         parameters.append(param)
 
+    # Handle default values for args e.g. def func(a=1, b="hello", c=3.14)
     defaults = [None] * (
         len(func_def.args.args) - len(func_def.args.defaults)
     ) + func_def.args.defaults
@@ -501,6 +541,42 @@ def _generate_signature_from_source(
                 default = None  # Set to None if evaluation fails
             parameters[parameters.index(param)] = param.replace(default=default)
 
+    # Handle annotations for keyword only args e.g. def func(*, a: int, b: str)
+    for kwarg in func_def.args.kwonlyargs:
+        name = kwarg.arg
+        annotation = kwarg.annotation
+        if annotation is not None:
+            try:
+                ann_code = compile(ast.Expression(annotation), "<string>", "eval")
+                annotation = eval(ann_code, namespace)
+            except Exception as e:
+                logger.debug("Failed to evaluate annotation for %s: %s", name, e)
+                annotation = inspect.Parameter.empty
+        else:
+            annotation = inspect.Parameter.empty
+
+        param = inspect.Parameter(
+            name, inspect.Parameter.KEYWORD_ONLY, annotation=annotation
+        )
+        parameters.append(param)
+
+    # Handle default values for keyword only args e.g. def func(*, a=1, b="hello")
+    defaults = [None] * (
+        len(func_def.args.kwonlyargs) - len(func_def.args.kw_defaults)
+    ) + func_def.args.kw_defaults
+    for param, default in zip(parameters[-len(func_def.args.kwonlyargs) :], defaults):
+        if default is not None:
+            try:
+                def_code = compile(ast.Expression(default), "<string>", "eval")
+                default = eval(def_code, namespace)
+            except Exception as e:
+                logger.debug(
+                    "Failed to evaluate default value for %s: %s", param.name, e
+                )
+                default = None
+            parameters[parameters.index(param)] = param.replace(default=default)
+
+    # Handle annotations for varargs and kwargs e.g. def func(*args: int, **kwargs: str)
     if func_def.args.vararg:
         parameters.append(
             inspect.Parameter(
@@ -512,7 +588,7 @@ def _generate_signature_from_source(
             inspect.Parameter(func_def.args.kwarg.arg, inspect.Parameter.VAR_KEYWORD)
         )
 
-    # Handle return annotation
+    # Handle return annotation e.g. def func() -> int
     return_annotation = func_def.returns
     if return_annotation is not None:
         try:
@@ -544,7 +620,14 @@ def _get_docstring_from_source(source_code: str, func_name: str) -> Optional[str
         (
             node
             for node in ast.walk(parsed_code)
-            if isinstance(node, ast.FunctionDef) and node.name == func_name
+            if isinstance(
+                node,
+                (
+                    ast.FunctionDef,
+                    ast.AsyncFunctionDef,
+                ),
+            )
+            and node.name == func_name
         ),
         None,
     )

prefect/utilities/dockerutils.py

@@ -41,7 +41,9 @@ def python_version_micro() -> str:
 
 
 def get_prefect_image_name(
-    prefect_version: str = None, python_version: str = None, flavor: str = None
+    prefect_version: Optional[str] = None,
+    python_version: Optional[str] = None,
+    flavor: Optional[str] = None,
 ) -> str:
     """
     Get the Prefect image name matching the current Prefect and Python versions.
@@ -138,7 +140,7 @@ def build_image(
     dockerfile: str = "Dockerfile",
     tag: Optional[str] = None,
     pull: bool = False,
-    platform: str = None,
+    platform: Optional[str] = None,
     stream_progress_to: Optional[TextIO] = None,
     **kwargs,
 ) -> str:
@@ -209,7 +211,7 @@ class ImageBuilder:
         self,
         base_image: str,
         base_directory: Path = None,
-        platform: str = None,
+        platform: Optional[str] = None,
         context: Path = None,
     ):
         """Create an ImageBuilder

prefect/utilities/engine.py

@@ -786,6 +786,17 @@ def resolve_to_final_result(expr, context):
         raise StopVisiting()
 
     if isinstance(expr, NewPrefectFuture):
+        upstream_task_run = context.get("current_task_run")
+        upstream_task = context.get("current_task")
+        if (
+            upstream_task
+            and upstream_task_run
+            and expr.task_run_id == upstream_task_run.id
+        ):
+            raise ValueError(
+                f"Discovered a task depending on itself. Raising to avoid a deadlock. Please inspect the inputs and dependencies of {upstream_task.name}."
+            )
+
         expr.wait()
         state = expr.state
     elif isinstance(expr, State):

prefect/utilities/filesystem.py

@@ -1,12 +1,13 @@
 """
 Utilities for working with file systems
 """
+
 import os
 import pathlib
 import threading
 from contextlib import contextmanager
 from pathlib import Path, PureWindowsPath
-from typing import Union
+from typing import Optional, Union
 
 import fsspec
 import pathspec
@@ -32,7 +33,7 @@ def create_default_ignore_file(path: str) -> bool:
 
 
 def filter_files(
-    root: str = ".", ignore_patterns: list = None, include_dirs: bool = True
+    root: str = ".", ignore_patterns: Optional[list] = None, include_dirs: bool = True
 ) -> set:
     """
     This function accepts a root directory path and a list of file patterns to ignore, and returns
@@ -40,9 +41,7 @@ def filter_files(
 
     The specification matches that of [.gitignore files](https://git-scm.com/docs/gitignore).
     """
-    if ignore_patterns is None:
-        ignore_patterns = []
-    spec = pathspec.PathSpec.from_lines("gitwildmatch", ignore_patterns)
+    spec = pathspec.PathSpec.from_lines("gitwildmatch", ignore_patterns or [])
     ignored_files = {p.path for p in spec.match_tree_entries(root)}
     if include_dirs:
         all_files = {p.path for p in pathspec.util.iter_tree_entries(root)}

prefect/utilities/importtools.py

@@ -378,7 +378,16 @@ def safe_load_namespace(source_code: str):
     """
     parsed_code = ast.parse(source_code)
 
-    namespace = {}
+    namespace = {"__name__": "prefect_safe_namespace_loader"}
+
+    # Remove the body of the if __name__ == "__main__": block from the AST to prevent
+    # execution of guarded code
+    new_body = []
+    for node in parsed_code.body:
+        if _is_main_block(node):
+            continue
+        new_body.append(node)
+    parsed_code.body = new_body
 
     # Walk through the AST and find all import statements
     for node in ast.walk(parsed_code):
@@ -412,11 +421,11 @@ def safe_load_namespace(source_code: str):
             except ImportError as e:
                 logger.debug("Failed to import from %s: %s", node.module, e)
 
-    # Handle local class definitions
+    # Handle local definitions
     for node in ast.walk(parsed_code):
-        if isinstance(node, (ast.ClassDef, ast.FunctionDef)):
+        if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.Assign)):
             try:
-                # Compile and execute each class and function definition locally
+                # Compile and execute each class and function definition and assignment
                 code = compile(
                     ast.Module(body=[node], type_ignores=[]),
                     filename="<ast>",
@@ -424,5 +433,25 @@ def safe_load_namespace(source_code: str):
                 )
                 exec(code, namespace)
             except Exception as e:
-                logger.debug("Failed to compile class definition: %s", e)
+                logger.debug("Failed to compile: %s", e)
     return namespace
+
+
+def _is_main_block(node: ast.AST):
+    """
+    Check if the node is an `if __name__ == "__main__":` block.
+    """
+    if isinstance(node, ast.If):
+        try:
+            # Check if the condition is `if __name__ == "__main__":`
+            if (
+                isinstance(node.test, ast.Compare)
+                and isinstance(node.test.left, ast.Name)
+                and node.test.left.id == "__name__"
+                and isinstance(node.test.comparators[0], ast.Constant)
+                and node.test.comparators[0].value == "__main__"
+            ):
+                return True
+        except AttributeError:
+            pass
+    return False

prefect/utilities/services.py

@@ -2,7 +2,7 @@ import sys
 from collections import deque
 from traceback import format_exception
 from types import TracebackType
-from typing import Callable, Coroutine, Deque, Tuple
+from typing import Callable, Coroutine, Deque, Optional, Tuple
 
 import anyio
 import httpx
@@ -22,7 +22,7 @@ async def critical_service_loop(
     backoff: int = 1,
     printer: Callable[..., None] = print,
     run_once: bool = False,
-    jitter_range: float = None,
+    jitter_range: Optional[float] = None,
 ):
     """
     Runs the given `workload` function on the specified `interval`, while being

prefect/utilities/urls.py

@@ -0,0 +1,195 @@
+import inspect
+import urllib.parse
+from typing import Any, Literal, Optional, Union
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from prefect import settings
+from prefect.blocks.core import Block
+from prefect.events.schemas.automations import Automation
+from prefect.events.schemas.events import ReceivedEvent, Resource
+from prefect.futures import PrefectFuture
+from prefect.logging.loggers import get_logger
+from prefect.variables import Variable
+
+logger = get_logger("utilities.urls")
+
+# The following objects are excluded from UI URL generation because we lack a
+# directly-addressable URL:
+#   worker
+#   artifact
+#   variable
+#   saved-search
+UI_URL_FORMATS = {
+    "flow": "flows/flow/{obj_id}",
+    "flow-run": "runs/flow-run/{obj_id}",
+    "task-run": "runs/task-run/{obj_id}",
+    "block": "blocks/block/{obj_id}",
+    "block-document": "blocks/block/{obj_id}",
+    "work-pool": "work-pools/work-pool/{obj_id}",
+    "work-queue": "work-queues/work-queue/{obj_id}",
+    "concurrency-limit": "concurrency-limits/concurrency-limit/{obj_id}",
+    "deployment": "deployments/deployment/{obj_id}",
+    "automation": "automations/automation/{obj_id}",
+    "received-event": "events/event/{occurred}/{obj_id}",
+}
+
+# The following objects are excluded from API URL generation because we lack a
+# directly-addressable URL:
+#   worker
+#   artifact
+#   saved-search
+#   received-event
+API_URL_FORMATS = {
+    "flow": "flows/{obj_id}",
+    "flow-run": "flow_runs/{obj_id}",
+    "task-run": "task_runs/{obj_id}",
+    "variable": "variables/name/{obj_id}",
+    "block": "blocks/{obj_id}",
+    "work-pool": "work_pools/{obj_id}",
+    "work-queue": "work_queues/{obj_id}",
+    "concurrency-limit": "concurrency_limits/{obj_id}",
+    "deployment": "deployments/{obj_id}",
+    "automation": "automations/{obj_id}",
+}
+
+URLType = Literal["ui", "api"]
+RUN_TYPES = {"flow-run", "task-run"}
+
+
+def convert_class_to_name(obj: Any) -> str:
+    """
+    Convert CamelCase class name to dash-separated lowercase name
+    """
+    cls = obj if inspect.isclass(obj) else obj.__class__
+    name = cls.__name__
+    return "".join(["-" + i.lower() if i.isupper() else i for i in name]).lstrip("-")
+
+
+def url_for(
+    obj: Union[
+        PrefectFuture,
+        Block,
+        Variable,
+        Automation,
+        Resource,
+        ReceivedEvent,
+        BaseModel,
+        str,
+    ],
+    obj_id: Optional[Union[str, UUID]] = None,
+    url_type: URLType = "ui",
+    default_base_url: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Returns the URL for a Prefect object.
+
+    Pass in a supported object directly or provide an object name and ID.
+
+    Args:
+        obj (Union[PrefectFuture, Block, Variable, Automation, Resource, ReceivedEvent, BaseModel, str]):
+            A Prefect object to get the URL for, or its URL name and ID.
+        obj_id (Union[str, UUID], optional):
+            The UUID of the object.
+        url_type (Literal["ui", "api"], optional):
+            Whether to return the URL for the UI (default) or API.
+        default_base_url (str, optional):
+            The default base URL to use if no URL is configured.
+
+    Returns:
+        Optional[str]: The URL for the given object or None if the object is not supported.
+
+    Examples:
+        url_for(my_flow_run)
+        url_for(obj=my_flow_run)
+        url_for("flow-run", obj_id="123e4567-e89b-12d3-a456-426614174000")
+    """
+    if isinstance(obj, PrefectFuture):
+        name = "task-run"
+    elif isinstance(obj, Block):
+        name = "block"
+    elif isinstance(obj, Automation):
+        name = "automation"
+    elif isinstance(obj, ReceivedEvent):
+        name = "received-event"
+    elif isinstance(obj, Resource):
+        if obj.id.startswith("prefect."):
+            name = obj.id.split(".")[1]
+        else:
+            logger.warning(f"No URL known for resource with ID: {obj.id}")
+            return None
+    elif isinstance(obj, str):
+        name = obj
+    else:
+        name = convert_class_to_name(obj)
+
+    # Can't do an isinstance check here because the client build
+    # doesn't have access to that server schema.
+    if name == "work-queue-with-status":
+        name = "work-queue"
+
+    if url_type != "ui" and url_type != "api":
+        raise ValueError(f"Invalid URL type: {url_type}. Use 'ui' or 'api'.")
+
+    if url_type == "ui" and name not in UI_URL_FORMATS:
+        logger.error("No UI URL known for this object: %s", name)
+        return None
+    elif url_type == "api" and name not in API_URL_FORMATS:
+        logger.error("No API URL known for this object: %s", name)
+        return None
+
+    if isinstance(obj, str) and not obj_id:
+        raise ValueError(
+            "If passing an object name, you must also provide an object ID."
+        )
+
+    base_url = (
+        settings.PREFECT_UI_URL.value()
+        if url_type == "ui"
+        else settings.PREFECT_API_URL.value()
+    )
+    base_url = base_url or default_base_url
+
+    if not base_url:
+        logger.warning(
+            f"No URL found for the Prefect {'UI' if url_type == 'ui' else 'API'}, "
+            f"and no default base path provided."
+        )
+        return None
+
+    if not obj_id:
+        # We treat PrefectFuture as if it was the underlying task run,
+        # so we need to check the object type here instead of name.
+        if isinstance(obj, PrefectFuture):
+            obj_id = getattr(obj, "task_run_id", None)
+        elif name == "block":
+            # Blocks are client-side objects whose API representation is a
+            # BlockDocument.
+            obj_id = obj._block_document_id
+        elif name in ("variable", "work-pool"):
+            obj_id = obj.name
+        elif isinstance(obj, Resource):
+            obj_id = obj.id.rpartition(".")[2]
+        else:
+            obj_id = getattr(obj, "id", None)
+        if not obj_id:
+            logger.error(
+                "An ID is required to build a URL, but object did not have one: %s", obj
+            )
+            return ""
+
+    url_format = (
+        UI_URL_FORMATS.get(name) if url_type == "ui" else API_URL_FORMATS.get(name)
+    )
+
+    if isinstance(obj, ReceivedEvent):
+        url = url_format.format(
+            occurred=obj.occurred.strftime("%Y-%m-%d"), obj_id=obj_id
+        )
+    else:
+        url = url_format.format(obj_id=obj_id)
+
+    if not base_url.endswith("/"):
+        base_url += "/"
+    return urllib.parse.urljoin(base_url, url)

prefect/utilities/visualization.py

@@ -1,6 +1,7 @@
 """
 Utilities for working with Flow.visualize()
 """
+
 from functools import partial
 from typing import Any, List, Optional
 

prefect/variables.py

@@ -1,5 +1,6 @@
 from typing import List, Optional, Union
 
+from prefect._internal.compatibility.migration import getattr_migration
 from prefect.client.schemas.actions import VariableCreate as VariableRequest
 from prefect.client.schemas.actions import VariableUpdate as VariableUpdateRequest
 from prefect.client.schemas.objects import Variable as VariableResponse
@@ -28,17 +29,19 @@ class Variable(VariableRequest):
         value: StrictVariableValue,
         tags: Optional[List[str]] = None,
         overwrite: bool = False,
+        as_object: bool = False,
     ):
         """
-        Sets a new variable. If one exists with the same name, user must pass `overwrite=True`
+        Sets a new variable. If one exists with the same name, must pass `overwrite=True`
 
-        Returns `True` if the variable was created or updated
+        Returns the newly set value. If `as_object=True`, return the full Variable object
 
         Args:
             - name: The name of the variable to set.
             - value: The value of the variable to set.
             - tags: An optional list of strings to associate with the variable.
             - overwrite: Whether to overwrite the variable if it already exists.
+            - as_object: Whether to return the full Variable object.
 
         Example:
             Set a new variable and overwrite it if it already exists.
@@ -51,17 +54,22 @@ class Variable(VariableRequest):
             ```
         """
         client, _ = get_or_create_client()
-        variable = await client.read_variable_by_name(name)
+        variable_exists = await client.read_variable_by_name(name)
         var_dict = {"name": name, "value": value, "tags": tags or []}
-        if variable:
+
+        if variable_exists:
             if not overwrite:
                 raise ValueError(
-                    "You are attempting to set a variable with a name that is already in use. "
-                    "If you would like to overwrite it, pass `overwrite=True`."
+                    f"Variable {name!r} already exists. Use `overwrite=True` to update it."
                 )
             await client.update_variable(variable=VariableUpdateRequest(**var_dict))
+            variable = await client.read_variable_by_name(name)
         else:
-            await client.create_variable(variable=VariableRequest(**var_dict))
+            variable = await client.create_variable(
+                variable=VariableRequest(**var_dict)
+            )
+
+        return variable if as_object else variable.value
 
     @classmethod
     @sync_compatible
@@ -96,10 +104,8 @@ class Variable(VariableRequest):
         """
         client, _ = get_or_create_client()
         variable = await client.read_variable_by_name(name)
-        if as_object:
-            return variable
 
-        return variable.value if variable else default
+        return variable if as_object else (variable.value if variable else default)
 
     @classmethod
     @sync_compatible
@@ -129,3 +135,6 @@ class Variable(VariableRequest):
             return True
         except ObjectNotFound:
             return False
+
+
+__getattr__ = getattr_migration(__name__)

prefect/workers/base.py

@@ -8,6 +8,8 @@ import anyio
 import anyio.abc
 import pendulum
 from pydantic import BaseModel, Field, PrivateAttr, field_validator
+from pydantic.json_schema import GenerateJsonSchema
+from typing_extensions import Literal
 
 import prefect
 from prefect._internal.compatibility.experimental import (
@@ -42,8 +44,10 @@ from prefect.exceptions import (
 from prefect.logging.loggers import PrefectLogAdapter, flow_run_logger, get_logger
 from prefect.plugins import load_prefect_collections
 from prefect.settings import (
+    PREFECT_API_URL,
     PREFECT_EXPERIMENTAL_WARN,
     PREFECT_EXPERIMENTAL_WARN_ENHANCED_CANCELLATION,
+    PREFECT_TEST_MODE,
     PREFECT_WORKER_HEARTBEAT_SECONDS,
     PREFECT_WORKER_PREFETCH_SECONDS,
     get_current_settings,
@@ -106,12 +110,22 @@ class BaseJobConfiguration(BaseModel):
     def _coerce_command(cls, v):
         return return_v_or_none(v)
 
+    @field_validator("env", mode="before")
+    @classmethod
+    def _coerce_env(cls, v):
+        return {k: str(v) if v is not None else None for k, v in v.items()}
+
     @staticmethod
     def _get_base_config_defaults(variables: dict) -> dict:
         """Get default values from base config for all variables that have them."""
         defaults = dict()
         for variable_name, attrs in variables.items():
-            if "default" in attrs:
+            # We remote `None` values because we don't want to use them in templating.
+            # The currently logic depends on keys not existing to populate the correct value
+            # in some cases.
+            # Pydantic will provide default values if the keys are missing when creating
+            # a configuration class.
+            if "default" in attrs and attrs.get("default") is not None:
                 defaults[variable_name] = attrs["default"]
 
         return defaults
@@ -323,6 +337,33 @@ class BaseVariables(BaseModel):
         ),
     )
 
+    @classmethod
+    def model_json_schema(
+        cls,
+        by_alias: bool = True,
+        ref_template: str = "#/definitions/{model}",
+        schema_generator: Type[GenerateJsonSchema] = GenerateJsonSchema,
+        mode: Literal["validation", "serialization"] = "validation",
+    ) -> Dict[str, Any]:
+        """TODO: stop overriding this method - use GenerateSchema in ConfigDict instead?"""
+        schema = super().model_json_schema(
+            by_alias, ref_template, schema_generator, mode
+        )
+
+        # ensure backwards compatibility by copying $defs into definitions
+        if "$defs" in schema:
+            schema["definitions"] = schema.pop("$defs")
+
+        # we aren't expecting these additional fields in the schema
+        if "additionalProperties" in schema:
+            schema.pop("additionalProperties")
+
+        for _, definition in schema.get("definitions", {}).items():
+            if "additionalProperties" in definition:
+                definition.pop("additionalProperties")
+
+        return schema
+
 
 class BaseWorkerResult(BaseModel, abc.ABC):
     identifier: str
@@ -511,6 +552,10 @@ class BaseWorker(abc.ABC):
         self._limiter = (
             anyio.CapacityLimiter(self._limit) if self._limit is not None else None
         )
+
+        if not PREFECT_TEST_MODE and not PREFECT_API_URL.value():
+            raise ValueError("`PREFECT_API_URL` must be set to start a Worker.")
+
         self._client = get_client()
         await self._client.__aenter__()
         await self._runs_task_group.__aenter__()