prefect-client 3.2.12__py3-none-any.whl → 3.2.14__py3-none-any.whl

prefect/_build_info.py

@@ -1,5 +1,5 @@
 # Generated by versioningit
-__version__ = "3.2.12"
-__build_date__ = "2025-03-10 16:35:36.997425+00:00"
-__git_commit__ = "826eb1a7423831a2eeb6541909ef35ecca17fde7"
+__version__ = "3.2.14"
+__build_date__ = "2025-03-21 15:55:26.682402+00:00"
+__git_commit__ = "775b957d124ecd8cc3f0005e45019f1f9e855973"
 __dirty__ = False

prefect/client/orchestration/_flow_runs/client.py

@@ -46,6 +46,9 @@ class FlowRunClient(BaseClient):
         tags: "Iterable[str] | None" = None,
         parent_task_run_id: "UUID | None" = None,
         state: "State[R] | None" = None,
+        work_pool_name: str | None = None,
+        work_queue_name: str | None = None,
+        job_variables: dict[str, Any] | None = None,
     ) -> "FlowRun":
         """
         Create a flow run for a flow.
@@ -59,7 +62,10 @@ class FlowRunClient(BaseClient):
             parent_task_run_id: if a subflow run is being created, the placeholder task
                 run identifier in the parent flow
             state: The initial state for the run. If not provided, defaults to
-                `Scheduled` for now. Should always be a `Scheduled` type.
+                `Pending`.
+            work_pool_name: The name of the work pool to run the flow run in.
+            work_queue_name: The name of the work queue to place the flow run in.
+            job_variables: The job variables to use when setting up flow run infrastructure.
 
         Raises:
             httpx.RequestError: if the Prefect API does not successfully create a run for any reason
@@ -100,7 +106,16 @@ class FlowRunClient(BaseClient):
             ),
         )
 
-        flow_run_create_json = flow_run_create.model_dump(mode="json")
+        if work_pool_name is not None:
+            flow_run_create.work_pool_name = work_pool_name
+        if work_queue_name is not None:
+            flow_run_create.work_queue_name = work_queue_name
+        if job_variables is not None:
+            flow_run_create.job_variables = job_variables
+
+        flow_run_create_json = flow_run_create.model_dump(
+            mode="json", exclude_unset=True
+        )
         response = self.request("POST", "/flow_runs/", json=flow_run_create_json)
 
         flow_run = FlowRun.model_validate(response.json())
@@ -480,6 +495,9 @@ class FlowRunAsyncClient(BaseAsyncClient):
         tags: "Iterable[str] | None" = None,
         parent_task_run_id: "UUID | None" = None,
         state: "State[R] | None" = None,
+        work_pool_name: str | None = None,
+        work_queue_name: str | None = None,
+        job_variables: dict[str, Any] | None = None,
     ) -> "FlowRun":
         """
         Create a flow run for a flow.
@@ -493,7 +511,10 @@ class FlowRunAsyncClient(BaseAsyncClient):
             parent_task_run_id: if a subflow run is being created, the placeholder task
                 run identifier in the parent flow
             state: The initial state for the run. If not provided, defaults to
-                `Scheduled` for now. Should always be a `Scheduled` type.
+                `Pending`.
+            work_pool_name: The name of the work pool to run the flow run in.
+            work_queue_name: The name of the work queue to place the flow run in.
+            job_variables: The job variables to use when setting up flow run infrastructure.
 
         Raises:
             httpx.RequestError: if the Prefect API does not successfully create a run for any reason
@@ -534,7 +555,16 @@ class FlowRunAsyncClient(BaseAsyncClient):
             ),
         )
 
-        flow_run_create_json = flow_run_create.model_dump(mode="json")
+        if work_pool_name is not None:
+            flow_run_create.work_pool_name = work_pool_name
+        if work_queue_name is not None:
+            flow_run_create.work_queue_name = work_queue_name
+        if job_variables is not None:
+            flow_run_create.job_variables = job_variables
+
+        flow_run_create_json = flow_run_create.model_dump(
+            mode="json", exclude_unset=True
+        )
         response = await self.request("POST", "/flow_runs/", json=flow_run_create_json)
 
         flow_run = FlowRun.model_validate(response.json())

prefect/client/schemas/actions.py

@@ -23,6 +23,7 @@ from prefect._internal.schemas.validators import (
 from prefect.client.schemas.objects import (
     StateDetails,
     StateType,
+    WorkPoolStorageConfiguration,
 )
 from prefect.client.schemas.schedules import (
     SCHEDULE_TYPES,
@@ -443,6 +444,9 @@ class FlowRunCreate(ActionBaseModel):
     idempotency_key: Optional[str] = Field(default=None)
 
     labels: KeyValueLabelsField = Field(default_factory=dict)
+    work_pool_name: Optional[str] = Field(default=None)
+    work_queue_name: Optional[str] = Field(default=None)
+    job_variables: Optional[dict[str, Any]] = Field(default=None)
 
 
 class DeploymentFlowRunCreate(ActionBaseModel):
@@ -684,6 +688,10 @@ class WorkPoolCreate(ActionBaseModel):
     concurrency_limit: Optional[NonNegativeInteger] = Field(
         default=None, description="A concurrency limit for the work pool."
     )
+    storage_configuration: WorkPoolStorageConfiguration = Field(
+        default_factory=WorkPoolStorageConfiguration,
+        description="A storage configuration for the work pool.",
+    )
 
 
 class WorkPoolUpdate(ActionBaseModel):
@@ -693,6 +701,10 @@ class WorkPoolUpdate(ActionBaseModel):
     is_paused: Optional[bool] = Field(default=None)
     base_job_template: Optional[dict[str, Any]] = Field(default=None)
     concurrency_limit: Optional[int] = Field(default=None)
+    storage_configuration: Optional[WorkPoolStorageConfiguration] = Field(
+        default=None,
+        description="A storage configuration for the work pool.",
+    )
 
 
 class WorkQueueCreate(ActionBaseModel):

prefect/client/schemas/objects.py

@@ -1445,6 +1445,19 @@ class Agent(ObjectBaseModel):
     )
 
 
+class WorkPoolStorageConfiguration(PrefectBaseModel):
+    """A work pool storage configuration"""
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(extra="forbid")
+
+    bundle_upload_step: Optional[dict[str, Any]] = Field(
+        default=None, description="The bundle upload step for the work pool."
+    )
+    bundle_execution_step: Optional[dict[str, Any]] = Field(
+        default=None, description="The bundle execution step for the work pool."
+    )
+
+
 class WorkPool(ObjectBaseModel):
     """An ORM representation of a work pool"""
 
@@ -1469,6 +1482,11 @@ class WorkPool(ObjectBaseModel):
         default=None, description="The current status of the work pool."
     )
 
+    storage_configuration: WorkPoolStorageConfiguration = Field(
+        default_factory=WorkPoolStorageConfiguration,
+        description="The storage configuration for the work pool.",
+    )
+
     # this required field has a default of None so that the custom validator
     # below will be called and produce a more helpful error message. Because
     # the field metadata is attached via an annotation, the default is hidden

prefect/deployments/runner.py

@@ -676,15 +676,7 @@ class RunnerDeployment(BaseModel):
                     try:
                         module = importlib.import_module(mod_name)
                         flow_file = getattr(module, "__file__", None)
-                    except ModuleNotFoundError as exc:
-                        # 16458 adds an identifier to the module name, so checking
-                        # for "__prefect_loader__" (2 underscores) will not match
-                        if "__prefect_loader_" in str(exc):
-                            raise ValueError(
-                                "Cannot create a RunnerDeployment from a flow that has been"
-                                " loaded from an entrypoint. To deploy a flow via"
-                                " entrypoint, use RunnerDeployment.from_entrypoint instead."
-                            )
+                    except ModuleNotFoundError:
                         raise ValueError(no_file_location_error)
                     if not flow_file:
                         raise ValueError(no_file_location_error)

prefect/docker/docker_image.py

@@ -64,7 +64,8 @@ class DockerImage:
     def build(self) -> None:
         full_image_name = self.reference
         build_kwargs = self.build_kwargs.copy()
-        build_kwargs["context"] = Path.cwd()
+        if "context" not in build_kwargs:
+            build_kwargs["context"] = Path.cwd()
         build_kwargs["tag"] = full_image_name
         build_kwargs["pull"] = build_kwargs.get("pull", True)
 

prefect/flow_engine.py

@@ -707,7 +707,11 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                 except Exception:
                     # regular exceptions are caught and re-raised to the user
                     raise
-                except (Abort, Pause):
+                except (Abort, Pause) as exc:
+                    if getattr(exc, "state", None):
+                        # we set attribute explicitly because
+                        # internals will have already called the state change API
+                        self.flow_run.state = exc.state
                     raise
                 except GeneratorExit:
                     # Do not capture generator exits as crashes
@@ -722,9 +726,7 @@ class FlowRunEngine(BaseFlowRunEngine[P, R]):
                         repr(self.state) if PREFECT_DEBUG_MODE else str(self.state)
                     )
                     self.logger.log(
-                        level=logging.INFO
-                        if self.state.is_completed()
-                        else logging.ERROR,
+                        level=logging.INFO,
                         msg=f"Finished in state {display_state}",
                     )
 
@@ -1277,7 +1279,11 @@ class AsyncFlowRunEngine(BaseFlowRunEngine[P, R]):
                 except Exception:
                     # regular exceptions are caught and re-raised to the user
                     raise
-                except (Abort, Pause):
+                except (Abort, Pause) as exc:
+                    if getattr(exc, "state", None):
+                        # we set attribute explicitly because
+                        # internals will have already called the state change API
+                        self.flow_run.state = exc.state
                     raise
                 except GeneratorExit:
                     # Do not capture generator exits as crashes

prefect/flow_runs.py

@@ -454,7 +454,7 @@ async def suspend_flow_run(
 
     if suspending_current_flow_run:
         # Exit this process so the run can be resubmitted later
-        raise Pause()
+        raise Pause(state=state)
 
 
 @sync_compatible

prefect/flows.py

@@ -1046,10 +1046,9 @@ class Flow(Generic[P, R]):
         if not name:
             name = self.name
         else:
-            # Handling for my_flow.serve(__file__)
-            # Will set name to name of file where my_flow.serve() without the extension
-            # Non filepath strings will pass through unchanged
-            name = Path(name).stem
+            # Only strip extension if it is a file path
+            if (p := Path(name)).is_file():
+                name = p.stem
 
         runner = Runner(name=name, pause_on_shutdown=pause_on_shutdown, limit=limit)
         deployment_id = runner.add_flow(

prefect/logging/loggers.py

@@ -146,10 +146,11 @@ def get_run_logger(
             **kwargs,
         )
     elif (
-        get_logger("prefect.flow_run").disabled
-        and get_logger("prefect.task_run").disabled
+        get_logger("prefect.flow_runs").disabled
+        and get_logger("prefect.task_runs").disabled
     ):
         logger = logging.getLogger("null")
+        logger.disabled = True
     else:
         raise MissingContextError("There is no active flow or task run context.")
 
@@ -280,9 +281,9 @@ def disable_run_logger():
     """
     Gets both `prefect.flow_run` and `prefect.task_run` and disables them
     within the context manager. Upon exiting the context manager, both loggers
-    are returned to its original state.
+    are returned to their original state.
     """
-    with disable_logger("prefect.flow_run"), disable_logger("prefect.task_run"):
+    with disable_logger("prefect.flow_runs"), disable_logger("prefect.task_runs"):
         yield
 
 

prefect/results.py

@@ -552,7 +552,11 @@ class ResultStore(BaseModel):
         if self.result_storage_block_id is None and (
             _resolve_path := getattr(self.result_storage, "_resolve_path", None)
         ):
-            return str(_resolve_path(key))
+            path_key = _resolve_path(key)
+            if path_key is not None:
+                return str(_resolve_path(key))
+            else:
+                return key
         return key
 
     @sync_compatible
@@ -684,7 +688,9 @@ class ResultStore(BaseModel):
 
         if self.result_storage_block_id is None:
             if _resolve_path := getattr(self.result_storage, "_resolve_path", None):
-                key = str(_resolve_path(key))
+                path_key = _resolve_path(key)
+                if path_key is not None:
+                    key = str(_resolve_path(key))
 
         return ResultRecord(
             result=obj,
@@ -773,7 +779,7 @@ class ResultStore(BaseModel):
                 )
                 else Path(".").resolve()
             )
-            base_key = str(Path(key).relative_to(basepath))
+            base_key = key if basepath is None else str(Path(key).relative_to(basepath))
         else:
             base_key = key
         if (

prefect/runner/__init__.py

@@ -1,2 +1,4 @@
 from .runner import Runner
 from .submit import submit_to_runner, wait_for_submitted_runs
+
+__all__ = ["Runner", "submit_to_runner", "wait_for_submitted_runs"]

prefect/runner/runner.py

@@ -1425,7 +1425,7 @@ class Runner:
             )
             status_code = process.returncode
         except Exception as exc:
-            if not task_status._future.done():
+            if not task_status._future.done():  # type: ignore
                 # This flow run was being submitted and did not start successfully
                 run_logger.exception(
                     f"Failed to start process for flow run '{flow_run.id}'."

prefect/runner/server.py

@@ -1,5 +1,7 @@
+from __future__ import annotations
+
 import uuid
-from typing import TYPE_CHECKING, Any, Callable, Coroutine, Hashable, Optional, Tuple
+from typing import TYPE_CHECKING, Any, Callable, Coroutine, Hashable, Optional
 
 import uvicorn
 from fastapi import APIRouter, FastAPI, HTTPException, status
@@ -33,7 +35,7 @@ if TYPE_CHECKING:
 
 from pydantic import BaseModel
 
-logger: "logging.Logger" = get_logger("webserver")
+logger: "logging.Logger" = get_logger("runner.webserver")
 
 RunnableEndpoint = Literal["deployment", "flow", "task"]
 
@@ -45,7 +47,7 @@ class RunnerGenericFlowRunRequest(BaseModel):
 
 
 def perform_health_check(
-    runner: "Runner", delay_threshold: Optional[int] = None
+    runner: "Runner", delay_threshold: int | None = None
 ) -> Callable[..., JSONResponse]:
     if delay_threshold is None:
         delay_threshold = (
@@ -57,6 +59,9 @@ def perform_health_check(
         now = DateTime.now("utc")
         poll_delay = (now - runner.last_polled).total_seconds()
 
+        if TYPE_CHECKING:
+            assert delay_threshold is not None
+
         if poll_delay > delay_threshold:
             return JSONResponse(
                 status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
@@ -120,7 +125,7 @@ async def _build_endpoint_for_deployment(
 
 async def get_deployment_router(
     runner: "Runner",
-) -> Tuple[APIRouter, dict[Hashable, Any]]:
+) -> tuple[APIRouter, dict[Hashable, Any]]:
     router = APIRouter()
     schemas: dict[Hashable, Any] = {}
     async with get_client() as client:
@@ -216,14 +221,14 @@ def _build_generic_endpoint_for_flows(
         # Verify that the flow we're loading is a subflow this runner is
         # managing
         if not _flow_in_schemas(flow, schemas):
-            runner._logger.warning(
+            logger.warning(
                 f"Flow {flow.name} is not directly managed by the runner. Please "
                 "include it in the runner's served flows' import namespace."
             )
         # Verify that the flow we're loading hasn't changed since the webserver
         # was started
         if _flow_schema_changed(flow, schemas):
-            runner._logger.warning(
+            logger.warning(
                 "A change in flow parameters has been detected. Please "
                 "restart the runner."
             )
@@ -291,7 +296,7 @@ async def build_server(runner: "Runner") -> FastAPI:
     return webserver
 
 
-def start_webserver(runner: "Runner", log_level: Optional[str] = None) -> None:
+def start_webserver(runner: "Runner", log_level: str | None = None) -> None:
     """
     Run a FastAPI server for a runner.
 

prefect/runner/storage.py

@@ -6,7 +6,6 @@ from copy import deepcopy
 from pathlib import Path
 from typing import (
     Any,
-    Dict,
     Optional,
     Protocol,
     TypedDict,
@@ -16,7 +15,7 @@ from typing import (
 from urllib.parse import urlparse, urlsplit, urlunparse
 from uuid import uuid4
 
-import fsspec
+import fsspec  # pyright: ignore[reportMissingTypeStubs]
 from anyio import run_process
 from pydantic import SecretStr
 
@@ -79,7 +78,7 @@ class RunnerStorage(Protocol):
 
 class GitCredentials(TypedDict, total=False):
     username: str
-    access_token: Union[str, Secret[str]]
+    access_token: str | Secret[str]
 
 
 class GitRepository:
@@ -117,12 +116,12 @@ class GitRepository:
     def __init__(
         self,
         url: str,
-        credentials: Union[GitCredentials, Block, Dict[str, Any], None] = None,
-        name: Optional[str] = None,
-        branch: Optional[str] = None,
+        credentials: Union[GitCredentials, Block, dict[str, Any], None] = None,
+        name: str | None = None,
+        branch: str | None = None,
         include_submodules: bool = False,
-        pull_interval: Optional[int] = 60,
-        directories: Optional[str] = None,
+        pull_interval: int | None = 60,
+        directories: list[str] | None = None,
     ):
         if credentials is None:
             credentials = {}
@@ -198,7 +197,7 @@ class GitRepository:
     @property
     def _git_config(self) -> list[str]:
         """Build a git configuration to use when running git commands."""
-        config = {}
+        config: dict[str, str] = {}
 
         # Submodules can be private. The url in .gitmodules
         # will not include the credentials, we need to
@@ -220,7 +219,7 @@ class GitRepository:
             result = await run_process(
                 ["git", "config", "--get", "core.sparseCheckout"], cwd=self.destination
             )
-            return result.strip().lower() == "true"
+            return result.stdout.decode().strip().lower() == "true"
         except Exception:
             return False
 
@@ -243,8 +242,7 @@ class GitRepository:
                 cwd=str(self.destination),
             )
             existing_repo_url = None
-            if result.stdout is not None:
-                existing_repo_url = _strip_auth_from_url(result.stdout.decode().strip())
+            existing_repo_url = _strip_auth_from_url(result.stdout.decode().strip())
 
             if existing_repo_url != self._url:
                 raise ValueError(
@@ -255,7 +253,7 @@ class GitRepository:
             # Sparsely checkout the repository if directories are specified and the repo is not in sparse-checkout mode already
             if self._directories and not await self.is_sparsely_checked_out():
                 await run_process(
-                    ["git", "sparse-checkout", "set"] + self._directories,
+                    ["git", "sparse-checkout", "set", *self._directories],
                     cwd=self.destination,
                 )
 
@@ -323,7 +321,7 @@ class GitRepository:
         if self._directories:
             self._logger.debug("Will add %s", self._directories)
             await run_process(
-                ["git", "sparse-checkout", "set"] + self._directories,
+                ["git", "sparse-checkout", "set", *self._directories],
                 cwd=self.destination,
             )
 
@@ -343,7 +341,7 @@ class GitRepository:
         )
 
     def to_pull_step(self) -> dict[str, Any]:
-        pull_step = {
+        pull_step: dict[str, Any] = {
             "prefect.deployments.steps.git_clone": {
                 "repository": self._url,
                 "branch": self._branch,
@@ -357,13 +355,14 @@ class GitRepository:
             pull_step["prefect.deployments.steps.git_clone"]["credentials"] = (
                 f"{{{{ {self._credentials.get_block_placeholder()} }}}}"
             )
-        elif isinstance(self._credentials, dict):
-            if isinstance(self._credentials.get("access_token"), Secret):
+        elif isinstance(self._credentials, dict):  # pyright: ignore[reportUnnecessaryIsInstance]
+            if isinstance(
+                access_token := self._credentials.get("access_token"), Secret
+            ):
                 pull_step["prefect.deployments.steps.git_clone"]["credentials"] = {
                     **self._credentials,
                     "access_token": (
-                        "{{"
-                        f" {self._credentials['access_token'].get_block_placeholder()} }}}}"
+                        f"{{{{ {access_token.get_block_placeholder()} }}}}"
                     ),
                 }
             elif self._credentials.get("access_token") is not None:
@@ -455,10 +454,10 @@ class RemoteStorage:
 
         def replace_blocks_with_values(obj: Any) -> Any:
             if isinstance(obj, Block):
-                if hasattr(obj, "get"):
-                    return obj.get()
+                if get := getattr(obj, "get", None):
+                    return get()
                 if hasattr(obj, "value"):
-                    return obj.value
+                    return getattr(obj, "value")
                 else:
                     return obj.model_dump()
             return obj
@@ -467,7 +466,7 @@ class RemoteStorage:
             self._settings, replace_blocks_with_values, return_data=True
         )
 
-        return fsspec.filesystem(scheme, **settings_with_block_values)
+        return fsspec.filesystem(scheme, **settings_with_block_values)  # pyright: ignore[reportUnknownMemberType] missing type stubs
 
     def set_base_path(self, path: Path) -> None:
         self._storage_base_path = path
@@ -513,7 +512,7 @@ class RemoteStorage:
         try:
             await from_async.wait_for_call_in_new_thread(
                 create_call(
-                    self._filesystem.get,
+                    self._filesystem.get,  # pyright: ignore[reportUnknownArgumentType, reportUnknownMemberType] missing type stubs
                     remote_path,
                     str(self.destination),
                     recursive=True,
@@ -580,18 +579,14 @@ class BlockStorageAdapter:
         self._block = block
         self._pull_interval = pull_interval
         self._storage_base_path = Path.cwd()
-        if not isinstance(block, Block):
+        if not isinstance(block, Block):  # pyright: ignore[reportUnnecessaryIsInstance]
             raise TypeError(
                 f"Expected a block object. Received a {type(block).__name__!r} object."
             )
         if not hasattr(block, "get_directory"):
             raise ValueError("Provided block must have a `get_directory` method.")
 
-        self._name = (
-            f"{block.get_block_type_slug()}-{block._block_document_name}"
-            if block._block_document_name
-            else str(uuid4())
-        )
+        self._name = f"{block.get_block_type_slug()}-{getattr(block, '_block_document_name', uuid4())}"
 
     def set_base_path(self, path: Path) -> None:
         self._storage_base_path = path
@@ -610,11 +605,11 @@ class BlockStorageAdapter:
         await self._block.get_directory(local_path=str(self.destination))
 
     def to_pull_step(self) -> dict[str, Any]:
-        # Give blocks the change to implement their own pull step
+        # Give blocks the chance to implement their own pull step
         if hasattr(self._block, "get_pull_step"):
-            return self._block.get_pull_step()
+            return getattr(self._block, "get_pull_step")()
         else:
-            if not self._block._block_document_name:
+            if getattr(self._block, "_block_document_name", None) is None:
                 raise BlockNotSavedError(
                     "Block must be saved with `.save()` before it can be converted to a"
                     " pull step."
@@ -622,7 +617,7 @@ class BlockStorageAdapter:
             return {
                 "prefect.deployments.steps.pull_with_block": {
                     "block_type_slug": self._block.get_block_type_slug(),
-                    "block_document_name": self._block._block_document_name,
+                    "block_document_name": getattr(self._block, "_block_document_name"),
                 }
             }
 
@@ -723,7 +718,9 @@ def create_storage_from_source(
         return LocalStorage(path=source, pull_interval=pull_interval)
 
 
-def _format_token_from_credentials(netloc: str, credentials: dict) -> str:
+def _format_token_from_credentials(
+    netloc: str, credentials: dict[str, Any] | GitCredentials
+) -> str:
     """
     Formats the credentials block for the git provider.
 
@@ -736,7 +733,10 @@ def _format_token_from_credentials(netloc: str, credentials: dict) -> str:
     token = credentials.get("token") if credentials else None
     access_token = credentials.get("access_token") if credentials else None
 
-    user_provided_token = access_token or token or password
+    user_provided_token: str | Secret[str] | None = access_token or token or password
+
+    if isinstance(user_provided_token, Secret):
+        user_provided_token = user_provided_token.get()
 
     if not user_provided_token:
         raise ValueError(
@@ -787,7 +787,7 @@ def _strip_auth_from_url(url: str) -> str:
 
     # Construct a new netloc without the auth info
     netloc = parsed.hostname
-    if parsed.port:
+    if parsed.port and netloc:
         netloc += f":{parsed.port}"
 
     # Build the sanitized URL