prefect-client 3.3.8.dev4__py3-none-any.whl → 3.4.1__py3-none-any.whl

prefect/types/__init__.py

@@ -1,13 +1,21 @@
 from __future__ import annotations
 
 from functools import partial
-from typing import Annotated, Any, Dict, List, Optional, Set, TypeVar, Union
+from typing import Annotated, Any, Optional, TypeVar, Union, cast
+from uuid import UUID
 from typing_extensions import Literal
 import orjson
 import pydantic
 
-
 from ._datetime import DateTime, Date
+from .names import (
+    Name,
+    NameOrEmpty,
+    NonEmptyishName,
+    BANNED_CHARACTERS,
+    WITHOUT_BANNED_CHARACTERS,
+    MAX_VARIABLE_NAME_LENGTH,
+)
 from pydantic import (
     BeforeValidator,
     Field,
@@ -21,7 +29,6 @@ from zoneinfo import available_timezones
 
 T = TypeVar("T")
 
-MAX_VARIABLE_NAME_LENGTH = 255
 MAX_VARIABLE_VALUE_LENGTH = 5000
 
 NonNegativeInteger = Annotated[int, Field(ge=0)]
@@ -39,37 +46,14 @@ TimeZone = Annotated[
 ]
 
 
-BANNED_CHARACTERS = ["/", "%", "&", ">", "<"]
-
-WITHOUT_BANNED_CHARACTERS = r"^[^" + "".join(BANNED_CHARACTERS) + "]+$"
-Name = Annotated[str, Field(pattern=WITHOUT_BANNED_CHARACTERS)]
-
-WITHOUT_BANNED_CHARACTERS_EMPTY_OK = r"^[^" + "".join(BANNED_CHARACTERS) + "]*$"
-NameOrEmpty = Annotated[str, Field(pattern=WITHOUT_BANNED_CHARACTERS_EMPTY_OK)]
-
-
-def non_emptyish(value: str) -> str:
-    if not value.strip("' \""):
-        raise ValueError("name cannot be an empty string")
-
-    return value
-
-
-NonEmptyishName = Annotated[
-    str,
-    Field(pattern=WITHOUT_BANNED_CHARACTERS),
-    BeforeValidator(non_emptyish),
-]
-
-
 VariableValue = Union[
     StrictStr,
     StrictInt,
     StrictBool,
     StrictFloat,
     None,
-    Dict[str, Any],
-    List[Any],
+    dict[str, Any],
+    list[Any],
 ]
 
 
@@ -100,24 +84,24 @@ def cast_none_to_empty_dict(value: Any) -> dict[str, Any]:
 
 
 KeyValueLabels = Annotated[
-    Dict[str, Union[StrictBool, StrictInt, StrictFloat, str]],
+    dict[str, Union[StrictBool, StrictInt, StrictFloat, str]],
     BeforeValidator(cast_none_to_empty_dict),
 ]
 
 
 ListOfNonEmptyStrings = Annotated[
-    List[str],
+    list[str],
     BeforeValidator(lambda x: [str(s) for s in x if str(s).strip()]),
 ]
 
 
-class SecretDict(pydantic.Secret[Dict[str, Any]]):
+class SecretDict(pydantic.Secret[dict[str, Any]]):
     pass
 
 
 def validate_set_T_from_delim_string(
-    value: Union[str, T, Set[T], None], type_: type[T], delim: str | None = None
-) -> Set[T]:
+    value: Union[str, T, set[T], None], type_: Any, delim: str | None = None
+) -> set[T]:
     """
     "no-info" before validator useful in scooping env vars
 
@@ -131,20 +115,20 @@ def validate_set_T_from_delim_string(
     delim = delim or ","
     if isinstance(value, str):
         return {T_adapter.validate_strings(s.strip()) for s in value.split(delim)}
-    errors = []
+    errors: list[pydantic.ValidationError] = []
     try:
         return {T_adapter.validate_python(value)}
     except pydantic.ValidationError as e:
         errors.append(e)
     try:
-        return TypeAdapter(Set[type_]).validate_python(value)
+        return TypeAdapter(set[type_]).validate_python(value)
     except pydantic.ValidationError as e:
         errors.append(e)
     raise ValueError(f"Invalid set[{type_}]: {errors}")
 
 
 ClientRetryExtraCodes = Annotated[
-    Union[str, StatusCode, Set[StatusCode], None],
+    Union[str, StatusCode, set[StatusCode], None],
     BeforeValidator(partial(validate_set_T_from_delim_string, type_=StatusCode)),
 ]
 
@@ -170,11 +154,15 @@ KeyValueLabelsField = Annotated[
 
 
 __all__ = [
+    "BANNED_CHARACTERS",
+    "WITHOUT_BANNED_CHARACTERS",
     "ClientRetryExtraCodes",
     "Date",
     "DateTime",
     "LogLevel",
     "KeyValueLabelsField",
+    "MAX_VARIABLE_NAME_LENGTH",
+    "MAX_VARIABLE_VALUE_LENGTH",
     "NonNegativeInteger",
     "PositiveInteger",
     "ListOfNonEmptyStrings",

prefect/types/names.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import re
+from functools import partial
+from typing import Annotated, overload
+
+from pydantic import AfterValidator, BeforeValidator, Field
+
+LOWERCASE_LETTERS_NUMBERS_AND_DASHES_ONLY_REGEX = "^[a-z0-9-]*$"
+LOWERCASE_LETTERS_NUMBERS_AND_UNDERSCORES_REGEX = "^[a-z0-9_]*$"
+LOWERCASE_LETTERS_NUMBERS_AND_DASHES_OR_UNDERSCORES_REGEX = "^[a-z0-9-_]*$"
+
+
+@overload
+def raise_on_name_alphanumeric_dashes_only(
+    value: str, field_name: str = ...
+) -> str: ...
+
+
+@overload
+def raise_on_name_alphanumeric_dashes_only(
+    value: None, field_name: str = ...
+) -> None: ...
+
+
+def raise_on_name_alphanumeric_dashes_only(
+    value: str | None, field_name: str = "value"
+) -> str | None:
+    if value is not None and not bool(
+        re.match(LOWERCASE_LETTERS_NUMBERS_AND_DASHES_ONLY_REGEX, value)
+    ):
+        raise ValueError(
+            f"{field_name} must only contain lowercase letters, numbers, and dashes."
+        )
+    return value
+
+
+@overload
+def raise_on_name_alphanumeric_underscores_only(
+    value: str, field_name: str = ...
+) -> str: ...
+
+
+@overload
+def raise_on_name_alphanumeric_underscores_only(
+    value: None, field_name: str = ...
+) -> None: ...
+
+
+def raise_on_name_alphanumeric_underscores_only(
+    value: str | None, field_name: str = "value"
+) -> str | None:
+    if value is not None and not re.match(
+        LOWERCASE_LETTERS_NUMBERS_AND_UNDERSCORES_REGEX, value
+    ):
+        raise ValueError(
+            f"{field_name} must only contain lowercase letters, numbers, and"
+            " underscores."
+        )
+    return value
+
+
+def raise_on_name_alphanumeric_dashes_underscores_only(
+    value: str, field_name: str = "value"
+) -> str:
+    if not re.match(LOWERCASE_LETTERS_NUMBERS_AND_DASHES_OR_UNDERSCORES_REGEX, value):
+        raise ValueError(
+            f"{field_name} must only contain lowercase letters, numbers, and"
+            " dashes or underscores."
+        )
+    return value
+
+
+BANNED_CHARACTERS = ["/", "%", "&", ">", "<"]
+
+WITHOUT_BANNED_CHARACTERS = r"^[^" + "".join(BANNED_CHARACTERS) + "]+$"
+Name = Annotated[str, Field(pattern=WITHOUT_BANNED_CHARACTERS)]
+
+WITHOUT_BANNED_CHARACTERS_EMPTY_OK = r"^[^" + "".join(BANNED_CHARACTERS) + "]*$"
+NameOrEmpty = Annotated[str, Field(pattern=WITHOUT_BANNED_CHARACTERS_EMPTY_OK)]
+
+
+def non_emptyish(value: str) -> str:
+    if not value.strip("' \""):
+        raise ValueError("name cannot be an empty string")
+
+    return value
+
+
+NonEmptyishName = Annotated[
+    str,
+    Field(pattern=WITHOUT_BANNED_CHARACTERS),
+    BeforeValidator(non_emptyish),
+]
+
+
+### specific names
+
+BlockDocumentName = Annotated[
+    Name,
+    AfterValidator(
+        partial(
+            raise_on_name_alphanumeric_dashes_only, field_name="Block document name"
+        )
+    ),
+]
+
+
+BlockTypeSlug = Annotated[
+    str,
+    AfterValidator(
+        partial(raise_on_name_alphanumeric_dashes_only, field_name="Block type slug")
+    ),
+]
+
+ArtifactKey = Annotated[
+    str,
+    AfterValidator(
+        partial(raise_on_name_alphanumeric_dashes_only, field_name="Artifact key")
+    ),
+]
+
+MAX_VARIABLE_NAME_LENGTH = 255
+
+
+VariableName = Annotated[
+    str,
+    AfterValidator(
+        partial(
+            raise_on_name_alphanumeric_dashes_underscores_only,
+            field_name="Variable name",
+        )
+    ),
+    Field(
+        max_length=MAX_VARIABLE_NAME_LENGTH,
+        description="The name of the variable",
+        examples=["my_variable"],
+    ),
+]

prefect/utilities/dockerutils.py

@@ -495,10 +495,11 @@ def parse_image_tag(name: str) -> tuple[str, Optional[str]]:
     """
     Parse Docker Image String
 
-    - If a tag exists, this function parses and returns the image registry and tag,
+    - If a tag or digest exists, this function parses and returns the image registry and tag/digest,
       separately as a tuple.
       - Example 1: 'prefecthq/prefect:latest' -> ('prefecthq/prefect', 'latest')
       - Example 2: 'hostname.io:5050/folder/subfolder:latest' -> ('hostname.io:5050/folder/subfolder', 'latest')
+      - Example 3: 'prefecthq/prefect@sha256:abc123' -> ('prefecthq/prefect', 'sha256:abc123')
     - Supports parsing Docker Image strings that follow Docker Image Specification v1.1.0
       - Image building tools typically enforce this standard
 
@@ -506,26 +507,35 @@ def parse_image_tag(name: str) -> tuple[str, Optional[str]]:
         name (str): Name of Docker Image
 
     Return:
-        tuple: image registry, image tag
+        tuple: image registry, image tag/digest
     """
     tag = None
     name_parts = name.split("/")
-    # First handles the simplest image names (DockerHub-based, index-free, potentionally with a tag)
-    # - Example: simplename:latest
+
+    # First handles the simplest image names (DockerHub-based, index-free, potentially with a tag or digest)
+    # - Example: simplename:latest or simplename@sha256:abc123
     if len(name_parts) == 1:
-        if ":" in name_parts[0]:
+        if "@" in name_parts[0]:
+            image_name, tag = name_parts[0].split("@")
+        elif ":" in name_parts[0]:
             image_name, tag = name_parts[0].split(":")
+
         else:
             image_name = name_parts[0]
     else:
         # 1. Separates index (hostname.io or prefecthq) from path:tag (folder/subfolder:latest or prefect:latest)
-        # 2. Separates path and tag (if tag exists)
-        # 3. Reunites index and path (without tag) as image name
+        # 2. Separates path and tag/digest (if exists)
+        # 3. Reunites index and path (without tag/digest) as image name
         index_name = name_parts[0]
         image_path = "/".join(name_parts[1:])
-        if ":" in image_path:
+
+        if "@" in image_path:
+            image_path, tag = image_path.split("@")
+        elif ":" in image_path:
             image_path, tag = image_path.split(":")
+
         image_name = f"{index_name}/{image_path}"
+
     return image_name, tag
 
 

prefect/utilities/importtools.py

@@ -145,17 +145,19 @@ def import_object(import_path: str) -> Any:
     - module.object
     - module:object
     - /path/to/script.py:object
+    - module:object.method
+    - /path/to/script.py:object.method
 
     This function is not thread safe as it modifies the 'sys' module during execution.
     """
     if ".py:" in import_path:
-        script_path, object_name = import_path.rsplit(":", 1)
+        script_path, object_path = import_path.rsplit(":", 1)
         module = load_script_as_module(script_path)
     else:
         if ":" in import_path:
-            module_name, object_name = import_path.rsplit(":", 1)
+            module_name, object_path = import_path.rsplit(":", 1)
         elif "." in import_path:
-            module_name, object_name = import_path.rsplit(".", 1)
+            module_name, object_path = import_path.rsplit(".", 1)
         else:
             raise ValueError(
                 f"Invalid format for object import. Received {import_path!r}."
@@ -163,7 +165,13 @@ def import_object(import_path: str) -> Any:
 
         module = load_module(module_name)
 
-    return getattr(module, object_name)
+    # Handle nested object/method access
+    parts = object_path.split(".")
+    obj = module
+    for part in parts:
+        obj = getattr(obj, part)
+
+    return obj
 
 
 class DelayedImportErrorModule(ModuleType):

prefect/workers/base.py

@@ -55,6 +55,7 @@ from prefect.exceptions import (
     Abort,
     ObjectNotFound,
 )
+from prefect.filesystems import LocalFileSystem
 from prefect.futures import PrefectFlowRunFuture
 from prefect.logging.loggers import (
     PrefectLogAdapter,
@@ -696,6 +697,25 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
             "Workers must implement a method for running submitted flow runs"
         )
 
+    async def _initiate_run(
+        self,
+        flow_run: "FlowRun",
+        configuration: C,
+    ) -> None:
+        """
+        This method is called by the worker to initiate a flow run and should return as
+        soon as possible.
+
+        This method is used in `.submit` to allow non-blocking submission of flows. For
+        workers that wait for completion in their `run` method, this method should be
+        implemented to return immediately.
+
+        If this method is not implemented, `.submit` will fall back to the `.run` method.
+        """
+        raise NotImplementedError(
+            "This worker has not implemented `_initiate_run`. Please use `run` instead."
+        )
+
     async def submit(
         self,
         flow: "Flow[..., FR]",
@@ -722,15 +742,6 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
         if self._runs_task_group is None:
             raise RuntimeError("Worker not properly initialized")
 
-        from prefect.results import get_result_store
-
-        current_result_store = get_result_store()
-        if current_result_store.result_storage is None and flow.result_storage is None:
-            self._logger.warning(
-                f"Flow {flow.name!r} has no result storage configured. Please configure "
-                "result storage for the flow if you want to retrieve the result for the flow run."
-            )
-
         flow_run = await self._runs_task_group.start(
             partial(
                 self._submit_adhoc_run,
@@ -766,6 +777,32 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
                 "work-pool storage configure`."
             )
 
+        from prefect.results import aresolve_result_storage, get_result_store
+
+        current_result_store = get_result_store()
+        # Check result storage and use the work pool default if needed
+        if (
+            current_result_store.result_storage is None
+            or isinstance(current_result_store.result_storage, LocalFileSystem)
+            and flow.result_storage is None
+        ):
+            if (
+                self.work_pool.storage_configuration.default_result_storage_block_id
+                is None
+            ):
+                self._logger.warning(
+                    f"Flow {flow.name!r} has no result storage configured. Please configure "
+                    "result storage for the flow if you want to retrieve the result for the flow run."
+                )
+            else:
+                # Use the work pool's default result storage block for the flow run to ensure the caller can retrieve the result
+                flow = flow.with_options(
+                    result_storage=await aresolve_result_storage(
+                        self.work_pool.storage_configuration.default_result_storage_block_id
+                    ),
+                    persist_result=True,
+                )
+
         bundle_key = str(uuid.uuid4())
         upload_command = convert_step_to_command(
             self.work_pool.storage_configuration.bundle_upload_step,
@@ -778,8 +815,9 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
 
         job_variables = (job_variables or {}) | {"command": " ".join(execute_command)}
         parameters = parameters or {}
-        parent_task_run = None
 
+        # Create a parent task run if this is a child flow run to ensure it shows up as a child flow in the UI
+        parent_task_run = None
         if flow_run_ctx := FlowRunContext.get():
             parent_task = Task[Any, Any](
                 name=flow.name,
@@ -821,6 +859,8 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
 
         bundle = create_bundle_for_flow_run(flow=flow, flow_run=flow_run)
 
+        # Write the bundle to a temporary directory so it can be uploaded to the bundle storage
+        # via the upload command
         with tempfile.TemporaryDirectory() as temp_dir:
             await (
                 anyio.Path(temp_dir)
@@ -843,16 +883,21 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
         logger.debug("Successfully uploaded execution bundle")
 
         try:
-            result = await self.run(flow_run, configuration)
-
-            if result.status_code != 0:
-                await self._propose_crashed_state(
-                    flow_run,
-                    (
-                        "Flow run infrastructure exited with non-zero status code"
-                        f" {result.status_code}."
-                    ),
-                )
+            # Call the implementation-specific run method with the constructed configuration. This is where the
+            # rubber meets the road.
+            try:
+                await self._initiate_run(flow_run, configuration)
+            except NotImplementedError:
+                result = await self.run(flow_run, configuration)
+
+                if result.status_code != 0:
+                    await self._propose_crashed_state(
+                        flow_run,
+                        (
+                            "Flow run infrastructure exited with non-zero status code"
+                            f" {result.status_code}."
+                        ),
+                    )
         except Exception as exc:
             # This flow run was being submitted and did not start successfully
             logger.exception(
@@ -1128,7 +1173,7 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
                 if self._limiter:
                     self._limiter.acquire_on_behalf_of_nowait(flow_run.id)
             except anyio.WouldBlock:
-                self._logger.info(
+                self._logger.debug(
                     f"Flow run limit reached; {self.limiter.borrowed_tokens} flow runs"
                     " in progress."
                 )

{prefect_client-3.3.8.dev4.dist-info → prefect_client-3.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.3.8.dev4
+Version: 3.4.1
 Summary: Workflow orchestration and management.
 Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
 Project-URL: Documentation, https://docs.prefect.io
@@ -40,7 +40,7 @@ Requires-Dist: jsonpatch<2.0,>=1.32
 Requires-Dist: jsonschema<5.0.0,>=4.0.0
 Requires-Dist: opentelemetry-api<2.0.0,>=1.27.0
 Requires-Dist: orjson<4.0,>=3.7
-Requires-Dist: packaging<24.3,>=21.3
+Requires-Dist: packaging<25.1,>=21.3
 Requires-Dist: pathspec>=0.8.0
 Requires-Dist: pendulum<4,>=3.0.0; python_version < '3.13'
 Requires-Dist: prometheus-client>=0.20.0
@@ -60,9 +60,10 @@ Requires-Dist: sniffio<2.0.0,>=1.3.0
 Requires-Dist: toml>=0.10.0
 Requires-Dist: typing-extensions<5.0.0,>=4.10.0
 Requires-Dist: ujson<6.0.0,>=5.8.0
+Requires-Dist: uuid7>=0.1.0
 Requires-Dist: uvicorn!=0.29.0,>=0.14.0
 Requires-Dist: websockets<16.0,>=13.0
-Requires-Dist: whenever<0.8.0,>=0.7.3; python_version >= '3.13'
+Requires-Dist: whenever<0.9.0,>=0.7.3; python_version >= '3.13'
 Provides-Extra: notifications
 Requires-Dist: apprise<2.0.0,>=1.1.0; extra == 'notifications'
 Description-Content-Type: text/markdown