prefect-client 3.4.0__py3-none-any.whl → 3.4.1__py3-none-any.whl

prefect/server/api/workers.py

@@ -3,7 +3,7 @@ Routes for interacting with work queue objects.
 """
 
 from typing import TYPE_CHECKING, List, Optional
-from uuid import UUID, uuid4
+from uuid import UUID
 
 import sqlalchemy as sa
 from fastapi import (
@@ -20,6 +20,7 @@ from sqlalchemy.ext.asyncio import AsyncSession
 import prefect.server.api.dependencies as dependencies
 import prefect.server.models as models
 import prefect.server.schemas as schemas
+from prefect._internal.uuid7 import uuid7
 from prefect.server.api.validation import validate_job_variable_defaults_for_work_pool
 from prefect.server.database import PrefectDBInterface, provide_database_interface
 from prefect.server.models.deployments import mark_deployments_ready
@@ -184,7 +185,7 @@ async def create_work_pool(
             )
 
             await emit_work_pool_status_event(
-                event_id=uuid4(),
+                event_id=uuid7(),
                 occurred=now("UTC"),
                 pre_update_work_pool=None,
                 work_pool=model,

prefect/task_runners.py

@@ -21,6 +21,7 @@ from typing import (
 
 from typing_extensions import ParamSpec, Self, TypeVar
 
+from prefect._internal.uuid7 import uuid7
 from prefect.client.schemas.objects import TaskRunInput
 from prefect.exceptions import MappingLengthMismatch, MappingMissingIterable
 from prefect.futures import (
@@ -290,7 +291,7 @@ class ThreadPoolTaskRunner(TaskRunner[PrefectConcurrentFuture[R]]):
         from prefect.context import FlowRunContext
         from prefect.task_engine import run_task_async, run_task_sync
 
-        task_run_id = uuid.uuid4()
+        task_run_id = uuid7()
         cancel_event = threading.Event()
         self._cancel_events[task_run_id] = cancel_event
         context = copy_context()

prefect/tasks.py

@@ -32,6 +32,7 @@ from uuid import UUID, uuid4
 from typing_extensions import Literal, ParamSpec, Self, TypeAlias, TypeIs
 
 import prefect.states
+from prefect._internal.uuid7 import uuid7
 from prefect.cache_policies import DEFAULT, NO_CACHE, CachePolicy
 from prefect.client.orchestration import get_client
 from prefect.client.schemas import TaskRun
@@ -953,7 +954,7 @@ class Task(Generic[P, R]):
                 if flow_run_context and flow_run_context.flow_run
                 else None
             )
-            task_run_id = id or uuid4()
+            task_run_id = id or uuid7()
             state = prefect.states.Pending(
                 state_details=StateDetails(
                     task_run_id=task_run_id,
@@ -1551,7 +1552,7 @@ class Task(Generic[P, R]):
             validated_state=task_run.state,
         )
 
-        if task_run_url := url_for(task_run):
+        if get_current_settings().ui_url and (task_run_url := url_for(task_run)):
             logger.info(
                 f"Created task run {task_run.name!r}. View it in the UI at {task_run_url!r}"
             )

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

@@ -697,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]",
@@ -866,16 +885,19 @@ class BaseWorker(abc.ABC, Generic[C, V, R]):
         try:
             # Call the implementation-specific run method with the constructed configuration. This is where the
             # rubber meets the road.
-            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}."
-                    ),
-                )
+            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(

{prefect_client-3.4.0.dist-info → prefect_client-3.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prefect-client
-Version: 3.4.0
+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
@@ -60,6 +60,7 @@ 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.9.0,>=0.7.3; python_version >= '3.13'