prefect-client 2.14.10__py3-none-any.whl → 2.14.11__py3-none-any.whl

prefect/input/actions.py

@@ -0,0 +1,88 @@
+from typing import TYPE_CHECKING, Any, Optional
+from uuid import UUID
+
+import orjson
+
+from prefect.client.utilities import inject_client
+from prefect.context import FlowRunContext
+from prefect.exceptions import PrefectHTTPStatusError
+from prefect.utilities.asyncutils import sync_compatible
+
+if TYPE_CHECKING:
+    from prefect.client.orchestration import PrefectClient
+
+
+def _ensure_flow_run_id(flow_run_id: Optional[UUID] = None) -> UUID:
+    if flow_run_id:
+        return flow_run_id
+
+    context = FlowRunContext.get()
+    if context is None or context.flow_run is None:
+        raise RuntimeError("Must either provide a flow run ID or be within a flow run.")
+
+    return context.flow_run.id
+
+
+@sync_compatible
+@inject_client
+async def create_flow_run_input(
+    key: str,
+    value: Any,
+    flow_run_id: Optional[UUID] = None,
+    client: "PrefectClient" = None,
+):
+    """
+    Create a new flow run input. The given `value` will be serialized to JSON
+    and stored as a flow run input value.
+
+    Args:
+        - key (str): the flow run input key
+        - value (Any): the flow run input value
+        - flow_run_id (UUID): the, optional, flow run ID. If not given will
+          default to pulling the flow run ID from the current context.
+    """
+    flow_run_id = _ensure_flow_run_id(flow_run_id)
+
+    await client.create_flow_run_input(
+        flow_run_id=flow_run_id, key=key, value=orjson.dumps(value).decode()
+    )
+
+
+@sync_compatible
+@inject_client
+async def read_flow_run_input(
+    key: str, flow_run_id: Optional[UUID] = None, client: "PrefectClient" = None
+) -> Any:
+    """Read a flow run input.
+
+    Args:
+        - key (str): the flow run input key
+        - flow_run_id (UUID): the flow run ID
+    """
+    flow_run_id = _ensure_flow_run_id(flow_run_id)
+
+    try:
+        value = await client.read_flow_run_input(flow_run_id=flow_run_id, key=key)
+    except PrefectHTTPStatusError as exc:
+        if exc.response.status_code == 404:
+            return None
+        raise
+    else:
+        return orjson.loads(value)
+
+
+@sync_compatible
+@inject_client
+async def delete_flow_run_input(
+    key: str, flow_run_id: Optional[UUID] = None, client: "PrefectClient" = None
+):
+    """Delete a flow run input.
+
+    Args:
+        - flow_run_id (UUID): the flow run ID
+        - key (str): the flow run input key
+    """
+
+    flow_run_id = _ensure_flow_run_id(flow_run_id)
+
+    await client.delete_flow_run_input(flow_run_id=flow_run_id, key=key)

prefect/input/run_input.py

@@ -0,0 +1,107 @@
+from typing import TYPE_CHECKING, Any, Dict, Literal, Optional, Type, TypeVar, Union
+from uuid import UUID
+
+import pydantic
+
+from prefect._internal.pydantic import HAS_PYDANTIC_V2
+from prefect.input.actions import create_flow_run_input, read_flow_run_input
+from prefect.utilities.asyncutils import sync_compatible
+
+if TYPE_CHECKING:
+    from prefect.states import State
+
+
+if HAS_PYDANTIC_V2:
+    from prefect._internal.pydantic.v2_schema import create_v2_schema
+
+
+T = TypeVar("T", bound="RunInput")
+KeysetNames = Union[Literal["response"], Literal["schema"]]
+Keyset = Dict[KeysetNames, str]
+
+
+def keyset_from_paused_state(state: "State") -> Keyset:
+    """
+    Get the keyset for the given Paused state.
+
+    Args:
+        - state (State): the state to get the keyset for
+    """
+
+    if not state.is_paused():
+        raise RuntimeError(f"{state.type.value!r} is unsupported.")
+
+    return keyset_from_base_key(
+        f"{state.name.lower()}-{str(state.state_details.pause_key)}"
+    )
+
+
+def keyset_from_base_key(base_key: str) -> Keyset:
+    """
+    Get the keyset for the given base key.
+
+    Args:
+        - base_key (str): the base key to get the keyset for
+
+    Returns:
+        - Dict[str, str]: the keyset
+    """
+    return {
+        "response": f"{base_key}-response",
+        "schema": f"{base_key}-schema",
+    }
+
+
+class RunInput(pydantic.BaseModel):
+    class Config:
+        extra = "forbid"
+
+    title: str = "Run is asking for input"
+    description: Optional[str] = None
+
+    @classmethod
+    @sync_compatible
+    async def save(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):
+        """
+        Save the run input response to the given key.
+
+        Args:
+            - keyset (Keyset): the keyset to save the input for
+            - flow_run_id (UUID, optional): the flow run ID to save the input for
+        """
+
+        if HAS_PYDANTIC_V2:
+            schema = create_v2_schema(cls.__name__, model_base=cls)
+        else:
+            schema = cls.schema(by_alias=True)
+
+        await create_flow_run_input(
+            key=keyset["schema"], value=schema, flow_run_id=flow_run_id
+        )
+
+    @classmethod
+    @sync_compatible
+    async def load(cls, keyset: Keyset, flow_run_id: Optional[UUID] = None):
+        """
+        Load the run input response from the given key.
+
+        Args:
+            - keyset (Keyset): the keyset to load the input for
+            - flow_run_id (UUID, optional): the flow run ID to load the input for
+        """
+        value = await read_flow_run_input(keyset["response"], flow_run_id=flow_run_id)
+        return cls(**value)
+
+    @classmethod
+    def with_initial_data(cls: Type[T], **kwargs: Any) -> Type[T]:
+        """
+        Create a new `RunInput` subclass with the given initial data as field
+        defaults.
+
+        Args:
+            - kwargs (Any): the initial data
+        """
+        fields = {}
+        for key, value in kwargs.items():
+            fields[key] = (type(value), value)
+        return pydantic.create_model(cls.__name__, **fields, __base__=cls)

prefect/runner/runner.py

@@ -204,6 +204,7 @@ class Runner:
         cron: Optional[str] = None,
         rrule: Optional[str] = None,
         schedule: Optional[SCHEDULE_TYPES] = None,
+        is_schedule_active: Optional[bool] = None,
         parameters: Optional[dict] = None,
         triggers: Optional[List[DeploymentTrigger]] = None,
         description: Optional[str] = None,
@@ -227,6 +228,9 @@ class Runner:
             rrule: An rrule schedule of when to execute runs of this flow.
             schedule: A schedule object of when to execute runs of this flow. Used for
                 advanced scheduling options like timezone.
+            is_schedule_active: Whether or not to set the schedule for this deployment as active. If
+                not provided when creating a deployment, the schedule will be set as active. If not
+                provided when updating a deployment, the schedule's activation will not be changed.
             triggers: A list of triggers that should kick of a run of this flow.
             parameters: A dictionary of default parameter values to pass to runs of this flow.
             description: A description for the created deployment. Defaults to the flow's
@@ -249,6 +253,7 @@ class Runner:
             cron=cron,
             rrule=rrule,
             schedule=schedule,
+            is_schedule_active=is_schedule_active,
             triggers=triggers,
             parameters=parameters,
             description=description,

prefect/runner/server.py

@@ -1,15 +1,26 @@
+from typing import TYPE_CHECKING, Any, Dict, Optional, Tuple
+
 import pendulum
 import uvicorn
-from prefect._vendor.fastapi import APIRouter, FastAPI, status
+from prefect._vendor.fastapi import APIRouter, FastAPI, HTTPException, status
 from prefect._vendor.fastapi.responses import JSONResponse
 
+from prefect.client.orchestration import get_client
+from prefect.runner.utils import inject_schemas_into_openapi
 from prefect.settings import (
+    PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS,
     PREFECT_RUNNER_POLL_FREQUENCY,
     PREFECT_RUNNER_SERVER_HOST,
     PREFECT_RUNNER_SERVER_LOG_LEVEL,
     PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE,
     PREFECT_RUNNER_SERVER_PORT,
 )
+from prefect.utilities.asyncutils import sync_compatible
+from prefect.utilities.validation import validate_values_conform_to_schema
+
+if TYPE_CHECKING:
+    from prefect.deployments import Deployment
+    from prefect.runner import Runner
 
 
 def perform_health_check(runner, delay_threshold: int = None) -> JSONResponse:
@@ -49,12 +60,61 @@ def shutdown(runner) -> int:
     return _shutdown
 
 
-def start_webserver(
-    runner,
-    log_level: str = None,
-) -> None:
+async def _build_endpoint_for_deployment(deployment: "Deployment"):
+    async def _create_flow_run_for_deployment(
+        body: Optional[Dict[Any, Any]] = None
+    ) -> JSONResponse:
+        body = body or {}
+        if deployment.enforce_parameter_schema and deployment.parameter_openapi_schema:
+            try:
+                validate_values_conform_to_schema(
+                    body, deployment.parameter_openapi_schema
+                )
+            except ValueError as exc:
+                raise HTTPException(
+                    status.HTTP_400_BAD_REQUEST,
+                    detail=f"Error creating flow run: {exc}",
+                )
+
+        async with get_client() as client:
+            flow_run = await client.create_flow_run_from_deployment(
+                deployment_id=deployment.id, parameters=body
+            )
+        return JSONResponse(
+            status_code=status.HTTP_201_CREATED,
+            content={"flow_run_id": str(flow_run.id)},
+        )
+
+    return _create_flow_run_for_deployment
+
+
+@sync_compatible
+async def get_deployment_router(
+    runner: "Runner",
+) -> Tuple[APIRouter, Dict[str, Dict]]:
+    from prefect import get_client
+
+    router = APIRouter()
+    schemas = {}
+    async with get_client() as client:
+        for deployment_id in runner._deployment_ids:
+            deployment = await client.read_deployment(deployment_id)
+            router.add_api_route(
+                f"/deployment/{deployment.id}/run",
+                await _build_endpoint_for_deployment(deployment),
+                methods=["POST"],
+            )
+
+            # Used for updating the route schemas later on
+            schemas[deployment.name] = deployment.parameter_openapi_schema
+            schemas[deployment.id] = deployment.name
+    return router, schemas
+
+
+@sync_compatible
+async def build_server(runner: "Runner") -> FastAPI:
     """
-    Run a FastAPI server for a runner.
+    Build a FastAPI server for a runner.
 
     Args:
         runner (Runner): the runner this server interacts with and monitors
@@ -68,11 +128,35 @@ def start_webserver(
     )
     router.add_api_route("/run_count", run_count(runner=runner), methods=["GET"])
     router.add_api_route("/shutdown", shutdown(runner=runner), methods=["POST"])
-
     webserver.include_router(router)
 
+    if PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS.value():
+        deployments_router, deployment_schemas = await get_deployment_router(runner)
+        webserver.include_router(deployments_router)
+
+        def customize_openapi():
+            if webserver.openapi_schema:
+                return webserver.openapi_schema
+
+            openapi_schema = inject_schemas_into_openapi(webserver, deployment_schemas)
+            webserver.openapi_schema = openapi_schema
+            return webserver.openapi_schema
+
+        webserver.openapi = customize_openapi
+
+    return webserver
+
+
+def start_webserver(runner: "Runner", log_level: Optional[str] = None) -> None:
+    """
+    Run a FastAPI server for a runner.
+
+    Args:
+        runner (Runner): the runner this server interacts with and monitors
+        log_level (str): the log level to use for the server
+    """
     host = PREFECT_RUNNER_SERVER_HOST.value()
     port = PREFECT_RUNNER_SERVER_PORT.value()
     log_level = log_level or PREFECT_RUNNER_SERVER_LOG_LEVEL.value()
-
+    webserver = build_server(runner)
     uvicorn.run(webserver, host=host, port=port, log_level=log_level)

prefect/runner/utils.py

@@ -0,0 +1,92 @@
+from copy import deepcopy
+from typing import Any, Dict
+
+from prefect._vendor.fastapi import FastAPI
+from prefect._vendor.fastapi.openapi.utils import get_openapi
+
+from prefect import __version__ as PREFECT_VERSION
+
+
+def inject_schemas_into_openapi(
+    webserver: FastAPI, deployment_schemas: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Augments the webserver's OpenAPI schema with additional schemas from deployments.
+
+    Args:
+        webserver: The FastAPI instance representing the webserver.
+        deployment_schemas: A dictionary of deployment schemas to integrate.
+
+    Returns:
+        The augmented OpenAPI schema dictionary.
+    """
+    openapi_schema = get_openapi(
+        title="FastAPI Prefect Runner", version=PREFECT_VERSION, routes=webserver.routes
+    )
+
+    augmented_schema = merge_definitions(deployment_schemas, openapi_schema)
+    return update_refs_to_components(augmented_schema)
+
+
+def merge_definitions(
+    deployment_schemas: Dict[str, Any], openapi_schema: Dict[str, Any]
+) -> Dict[str, Any]:
+    """
+    Integrates definitions from deployment schemas into the OpenAPI components.
+
+    Args:
+        deployment_schemas: A dictionary of deployment-specific schemas.
+        openapi_schema: The base OpenAPI schema to update.
+    """
+    openapi_schema_copy = deepcopy(openapi_schema)
+    components = openapi_schema_copy.setdefault("components", {}).setdefault(
+        "schemas", {}
+    )
+    for definitions in deployment_schemas.values():
+        if "definitions" in definitions:
+            for def_name, def_schema in definitions["definitions"].items():
+                def_schema_copy = deepcopy(def_schema)
+                update_refs_in_schema(def_schema_copy, "#/components/schemas/")
+                components[def_name] = def_schema_copy
+    return openapi_schema_copy
+
+
+def update_refs_in_schema(schema_item: Any, new_ref: str) -> None:
+    """
+    Recursively replaces `$ref` with a new reference base in a schema item.
+
+    Args:
+        schema_item: A schema or part of a schema to update references in.
+        new_ref: The new base string to replace in `$ref` values.
+    """
+    if isinstance(schema_item, dict):
+        if "$ref" in schema_item:
+            schema_item["$ref"] = schema_item["$ref"].replace("#/definitions/", new_ref)
+        for value in schema_item.values():
+            update_refs_in_schema(value, new_ref)
+    elif isinstance(schema_item, list):
+        for item in schema_item:
+            update_refs_in_schema(item, new_ref)
+
+
+def update_refs_to_components(openapi_schema: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Updates all `$ref` fields in the OpenAPI schema to reference the components section.
+
+    Args:
+        openapi_schema: The OpenAPI schema to modify `$ref` fields in.
+    """
+    for path_item in openapi_schema.get("paths", {}).values():
+        for operation in path_item.values():
+            schema = (
+                operation.get("requestBody", {})
+                .get("content", {})
+                .get("application/json", {})
+                .get("schema", {})
+            )
+            update_refs_in_schema(schema, "#/components/schemas/")
+
+    for definition in openapi_schema.get("definitions", {}).values():
+        update_refs_in_schema(definition, "#/components/schemas/")
+
+    return openapi_schema

prefect/settings.py

@@ -773,12 +773,6 @@ PREFECT_LOCAL_STORAGE_PATH = Setting(
 )
 """The path to a block storage directory to store things in."""
 
-PREFECT_DEFAULT_RESULT_STORAGE_BLOCK = Setting(
-    str,
-    default=None,
-)
-"""The `block-type/block-document` slug of a block to use as the default result storage."""
-
 PREFECT_MEMO_STORE_PATH = Setting(
     Path,
     default=Path("${PREFECT_HOME}") / "memo_store.toml",
@@ -939,12 +933,12 @@ PREFECT_TASK_INTROSPECTION_WARN_THRESHOLD = Setting(
     default=10.0,
 )
 """
-Threshold time in seconds for logging a warning if task parameter introspection 
+Threshold time in seconds for logging a warning if task parameter introspection
 exceeds this duration. Parameter introspection can be a significant performance hit
 when the parameter is a large collection object, e.g. a large dictionary or DataFrame,
-and each element needs to be inspected. See `prefect.utilities.annotations.quote` 
+and each element needs to be inspected. See `prefect.utilities.annotations.quote`
 for more details.
-Defaults to `10.0`. 
+Defaults to `10.0`.
 Set to `0` to disable logging the warning.
 """
 
@@ -1338,6 +1332,16 @@ PREFECT_EXPERIMENTAL_WARN_DEPLOYMENT_STATUS = Setting(bool, default=False)
 Whether or not to warn when deployment status is used.
 """
 
+PREFECT_EXPERIMENTAL_FLOW_RUN_INPUT = Setting(bool, default=False)
+"""
+Whether or not to enable flow run input.
+"""
+
+PREFECT_EXPERIMENTAL_WARN_FLOW_RUN_INPUT = Setting(bool, default=True)
+"""
+Whether or not to enable flow run input.
+"""
+
 PREFECT_RUNNER_PROCESS_LIMIT = Setting(int, default=5)
 """
 Maximum number of processes a runner will execute in parallel.
@@ -1394,6 +1398,11 @@ PREFECT_WORKER_WEBSERVER_PORT = Setting(int, default=8080)
 The port the worker's webserver should bind to.
 """
 
+PREFECT_EXPERIMENTAL_ENABLE_EXTRA_RUNNER_ENDPOINTS = Setting(bool, default=False)
+"""
+Whether or not to enable experimental worker webserver endpoints.
+"""
+
 PREFECT_EXPERIMENTAL_ENABLE_ARTIFACTS = Setting(bool, default=True)
 """
 Whether or not to enable experimental Prefect artifacts.
@@ -1416,11 +1425,27 @@ Whether or not to warn when the experimental workspace dashboard is enabled.
 
 # Defaults -----------------------------------------------------------------------------
 
+PREFECT_DEFAULT_RESULT_STORAGE_BLOCK = Setting(
+    str,
+    default=None,
+)
+"""The `block-type/block-document` slug of a block to use as the default result storage."""
+
 PREFECT_DEFAULT_WORK_POOL_NAME = Setting(str, default=None)
 """
 The default work pool to deploy to.
 """
 
+PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE = Setting(
+    str,
+    default=None,
+)
+"""
+The default Docker namespace to use when building images.
+
+Can be either an organization/username or a registry URL with an organization/username.
+"""
+
 # Deprecated settings ------------------------------------------------------------------
 
 

prefect/utilities/dockerutils.py

@@ -506,6 +506,37 @@ def parse_image_tag(name: str) -> Tuple[str, Optional[str]]:
     return image_name, tag
 
 
+def split_repository_path(repository_path: str) -> Tuple[Optional[str], str]:
+    """
+    Splits a Docker repository path into its namespace and repository components.
+
+    Args:
+        repository_path: The Docker repository path to split.
+
+    Returns:
+        Tuple[Optional[str], str]: A tuple containing the namespace and repository components.
+            - namespace (Optional[str]): The Docker namespace, combining the registry and organization. None if not present.
+            - repository (Optionals[str]): The repository name.
+    """
+    parts = repository_path.split("/", 2)
+
+    # Check if the path includes a registry and organization or just organization/repository
+    if len(parts) == 3 or (len(parts) == 2 and ("." in parts[0] or ":" in parts[0])):
+        # Namespace includes registry and organization
+        namespace = "/".join(parts[:-1])
+        repository = parts[-1]
+    elif len(parts) == 2:
+        # Only organization/repository provided, so namespace is just the first part
+        namespace = parts[0]
+        repository = parts[1]
+    else:
+        # No namespace provided
+        namespace = None
+        repository = parts[0]
+
+    return namespace, repository
+
+
 def format_outlier_version_name(version: str):
     """
     Formats outlier docker version names to pass `packaging.version.parse` validation

prefect/utilities/processutils.py

@@ -6,7 +6,6 @@ import sys
 from contextlib import asynccontextmanager
 from dataclasses import dataclass
 from functools import partial
-from io import TextIOBase
 from typing import (
     IO,
     Any,
@@ -299,7 +298,11 @@ async def consume_process_output(
 
 async def stream_text(source: TextReceiveStream, *sinks: TextSink):
     wrapped_sinks = [
-        anyio.wrap_file(sink) if isinstance(sink, TextIOBase) else sink
+        (
+            anyio.wrap_file(sink)
+            if hasattr(sink, "write") and hasattr(sink, "flush")
+            else sink
+        )
         for sink in sinks
     ]
     async for item in source:

prefect/utilities/validation.py

@@ -0,0 +1,63 @@
+import jsonschema
+
+from prefect.utilities.collections import remove_nested_keys
+
+
+def validate_schema(schema: dict):
+    """
+    Validate that the provided schema is a valid json schema.
+
+    Args:
+        schema: The schema to validate.
+
+    Raises:
+        ValueError: If the provided schema is not a valid json schema.
+
+    """
+    try:
+        if schema is not None:
+            # Most closely matches the schemas generated by pydantic
+            jsonschema.Draft4Validator.check_schema(schema)
+    except jsonschema.SchemaError as exc:
+        raise ValueError(
+            "The provided schema is not a valid json schema. Schema error:"
+            f" {exc.message}"
+        ) from exc
+
+
+def validate_values_conform_to_schema(
+    values: dict, schema: dict, ignore_required: bool = False
+):
+    """
+    Validate that the provided values conform to the provided json schema.
+
+    Args:
+        values: The values to validate.
+        schema: The schema to validate against.
+        ignore_required: Whether to ignore the required fields in the schema. Should be
+            used when a partial set of values is acceptable.
+
+    Raises:
+        ValueError: If the parameters do not conform to the schema.
+
+    """
+    if ignore_required:
+        schema = remove_nested_keys(["required"], schema)
+
+    try:
+        if schema is not None and values is not None:
+            jsonschema.validate(values, schema)
+    except jsonschema.ValidationError as exc:
+        if exc.json_path == "$":
+            error_message = "Validation failed."
+        else:
+            error_message = (
+                f"Validation failed for field {exc.json_path.replace('$.', '')!r}."
+            )
+        error_message += f" Failure reason: {exc.message}"
+        raise ValueError(error_message) from exc
+    except jsonschema.SchemaError as exc:
+        raise ValueError(
+            "The provided schema is not a valid json schema. Schema error:"
+            f" {exc.message}"
+        ) from exc

prefect/workers/utilities.py

@@ -43,7 +43,6 @@ async def get_default_base_job_template_for_infrastructure_type(
     async with get_collections_metadata_client() as collections_client:
         try:
             worker_metadata = await collections_client.read_worker_metadata()
-
             for collection in worker_metadata.values():
                 for worker in collection.values():
                     if worker.get("type") == infra_type:

{prefect_client-2.14.10.dist-info → prefect_client-2.14.11.dist-info}/METADATA

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