prefect-client 2.16.6__py3-none-any.whl → 2.16.7__py3-none-any.whl

prefect/events/schemas/events.py

@@ -0,0 +1,285 @@
+import copy
+from collections import defaultdict
+from typing import (
+    Any,
+    Dict,
+    Iterable,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    Tuple,
+    Union,
+    cast,
+)
+from uuid import UUID, uuid4
+
+import pendulum
+from pydantic import Field, root_validator, validator
+
+from prefect._internal.pydantic import HAS_PYDANTIC_V2
+from prefect._internal.schemas.bases import PrefectBaseModel
+from prefect._internal.schemas.fields import DateTimeTZ
+from prefect.logging import get_logger
+from prefect.settings import (
+    PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE,
+    PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES,
+)
+
+if HAS_PYDANTIC_V2:
+    from pydantic.v1 import Field, root_validator, validator
+else:
+    from pydantic import Field, root_validator, validator
+
+from .labelling import Labelled
+
+logger = get_logger(__name__)
+
+
+class Resource(Labelled):
+    """An observable business object of interest to the user"""
+
+    @root_validator(pre=True)
+    def enforce_maximum_labels(cls, values: Dict[str, Any]):
+        labels = values.get("__root__")
+        if not isinstance(labels, dict):
+            return values
+
+        if len(labels) > PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE.value():
+            raise ValueError(
+                "The maximum number of labels per resource "
+                f"is {PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE.value()}"
+            )
+
+        return values
+
+    @root_validator(pre=True)
+    def requires_resource_id(cls, values: Dict[str, Any]):
+        labels = values.get("__root__")
+        if not isinstance(labels, dict):
+            return values
+
+        labels = cast(Dict[str, str], labels)
+
+        if "prefect.resource.id" not in labels:
+            raise ValueError("Resources must include the prefect.resource.id label")
+        if not labels["prefect.resource.id"]:
+            raise ValueError("The prefect.resource.id label must be non-empty")
+
+        return values
+
+    @property
+    def id(self) -> str:
+        return self["prefect.resource.id"]
+
+    @property
+    def name(self) -> Optional[str]:
+        return self.get("prefect.resource.name")
+
+
+class RelatedResource(Resource):
+    """A Resource with a specific role in an Event"""
+
+    @root_validator(pre=True)
+    def requires_resource_role(cls, values: Dict[str, Any]):
+        labels = values.get("__root__")
+        if not isinstance(labels, dict):
+            return values
+
+        labels = cast(Dict[str, str], labels)
+
+        if "prefect.resource.role" not in labels:
+            raise ValueError(
+                "Related Resources must include the prefect.resource.role label"
+            )
+        if not labels["prefect.resource.role"]:
+            raise ValueError("The prefect.resource.role label must be non-empty")
+
+        return values
+
+    @property
+    def role(self) -> str:
+        return self["prefect.resource.role"]
+
+
+class Event(PrefectBaseModel):
+    """The client-side view of an event that has happened to a Resource"""
+
+    occurred: DateTimeTZ = Field(
+        default_factory=lambda: pendulum.now("UTC"),
+        description="When the event happened from the sender's perspective",
+    )
+    event: str = Field(
+        description="The name of the event that happened",
+    )
+    resource: Resource = Field(
+        description="The primary Resource this event concerns",
+    )
+    related: List[RelatedResource] = Field(
+        default_factory=list,
+        description="A list of additional Resources involved in this event",
+    )
+    payload: Dict[str, Any] = Field(
+        default_factory=dict,
+        description="An open-ended set of data describing what happened",
+    )
+    id: UUID = Field(
+        default_factory=uuid4,
+        description="The client-provided identifier of this event",
+    )
+    follows: Optional[UUID] = Field(
+        None,
+        description=(
+            "The ID of an event that is known to have occurred prior to this one. "
+            "If set, this may be used to establish a more precise ordering of causally-"
+            "related events when they occur close enough together in time that the "
+            "system may receive them out-of-order."
+        ),
+    )
+
+    @property
+    def involved_resources(self) -> Sequence[Resource]:
+        return [self.resource] + list(self.related)
+
+    @property
+    def resource_in_role(self) -> Mapping[str, RelatedResource]:
+        """Returns a mapping of roles to the first related resource in that role"""
+        return {related.role: related for related in reversed(self.related)}
+
+    @property
+    def resources_in_role(self) -> Mapping[str, Sequence[RelatedResource]]:
+        """Returns a mapping of roles to related resources in that role"""
+        resources: Dict[str, List[RelatedResource]] = defaultdict(list)
+        for related in self.related:
+            resources[related.role].append(related)
+        return resources
+
+    @validator("related")
+    def enforce_maximum_related_resources(cls, value: List[RelatedResource]):
+        if len(value) > PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value():
+            raise ValueError(
+                "The maximum number of related resources "
+                f"is {PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES.value()}"
+            )
+
+        return value
+
+    def find_resource_label(self, label: str) -> Optional[str]:
+        """Finds the value of the given label in this event's resource or one of its
+        related resources.  If the label starts with `related:<role>:`, search for the
+        first matching label in a related resource with that role."""
+        directive, _, related_label = label.rpartition(":")
+        directive, _, role = directive.partition(":")
+        if directive == "related":
+            for related in self.related:
+                if related.role == role:
+                    return related.get(related_label)
+        return self.resource.get(label)
+
+
+class ReceivedEvent(Event):
+    """The server-side view of an event that has happened to a Resource after it has
+    been received by the server"""
+
+    class Config:
+        orm_mode = True
+
+    received: DateTimeTZ = Field(
+        ...,
+        description="When the event was received by Prefect Cloud",
+    )
+
+
+def matches(expected: str, value: Optional[str]) -> bool:
+    """Returns true if the given value matches the expected string, which may
+    include wildcards"""
+    if value is None:
+        return False
+
+    # TODO: handle wildcards/globs better than this
+    if expected.endswith("*"):
+        return value.startswith(expected[:-1])
+
+    return value == expected
+
+
+class ResourceSpecification(PrefectBaseModel):
+    """A specification that may match zero, one, or many resources, used to target or
+    select a set of resources in a query or automation.  A resource must match at least
+    one value of all of the provided labels"""
+
+    __root__: Dict[str, Union[str, List[str]]]
+
+    def matches_every_resource(self) -> bool:
+        return len(self) == 0
+
+    def matches_every_resource_of_kind(self, prefix: str) -> bool:
+        if self.matches_every_resource():
+            return True
+
+        if len(self.__root__) == 1:
+            if resource_id := self.__root__.get("prefect.resource.id"):
+                values = [resource_id] if isinstance(resource_id, str) else resource_id
+                return any(value == f"{prefix}.*" for value in values)
+
+        return False
+
+    def includes(self, candidates: Iterable[Resource]) -> bool:
+        if self.matches_every_resource():
+            return True
+
+        for candidate in candidates:
+            if self.matches(candidate):
+                return True
+
+        return False
+
+    def matches(self, resource: Resource) -> bool:
+        for label, expected in self.items():
+            value = resource.get(label)
+            if not any(matches(candidate, value) for candidate in expected):
+                return False
+        return True
+
+    def items(self) -> Iterable[Tuple[str, List[str]]]:
+        return [
+            (label, [value] if isinstance(value, str) else value)
+            for label, value in self.__root__.items()
+        ]
+
+    def __contains__(self, key: str) -> bool:
+        return self.__root__.__contains__(key)
+
+    def __getitem__(self, key: str) -> List[str]:
+        value = self.__root__[key]
+        if not value:
+            return []
+        if not isinstance(value, list):
+            value = [value]
+        return value
+
+    def pop(
+        self, key: str, default: Optional[Union[str, List[str]]] = None
+    ) -> Optional[List[str]]:
+        value = self.__root__.pop(key, default)
+        if not value:
+            return []
+        if not isinstance(value, list):
+            value = [value]
+        return value
+
+    def get(
+        self, key: str, default: Optional[Union[str, List[str]]] = None
+    ) -> Optional[List[str]]:
+        value = self.__root__.get(key, default)
+        if not value:
+            return []
+        if not isinstance(value, list):
+            value = [value]
+        return value
+
+    def __len__(self) -> int:
+        return len(self.__root__)
+
+    def deepcopy(self) -> "ResourceSpecification":
+        return ResourceSpecification(__root__=copy.deepcopy(self.__root__))

prefect/events/schemas/labelling.py

@@ -0,0 +1,106 @@
+from typing import Dict, Iterable, Iterator, List, Optional, Tuple
+
+from prefect._internal.schemas.bases import PrefectBaseModel
+
+
+class LabelDiver:
+    """The LabelDiver supports templating use cases for any Labelled object, by
+    presenting the labels as a graph of objects that may be accessed by attribute.  For
+    example:
+
+        diver = LabelDiver({
+            'hello.world': 'foo',
+            'hello.world.again': 'bar'
+        })
+
+        assert str(diver.hello.world) == 'foo'
+        assert str(diver.hello.world.again) == 'bar'
+
+    """
+
+    _value: str
+    _divers: Dict[str, "LabelDiver"]
+    _labels: Dict[str, str]
+
+    def __init__(self, labels: Dict[str, str], value: str = ""):
+        self._labels = labels.copy()
+        self._value = value
+
+        divers: Dict[str, Dict[str, str]] = {}
+        values: Dict[str, str] = {}
+
+        for key, value in labels.items():
+            head, _, tail = key.partition(".")
+            if tail:
+                if head not in divers:
+                    divers[head] = {}
+
+                divers[head][tail] = labels[key]
+            else:
+                values[head] = value
+
+        # start with keys that had sub-divers...
+        self._divers: Dict[str, LabelDiver] = {
+            k: LabelDiver(v, value=values.pop(k, "")) for k, v in divers.items()
+        }
+        # ...then mix in any remaining keys that _only_ had values
+        self._divers.update(**{k: LabelDiver({}, value=v) for k, v in values.items()})
+
+    def __str__(self) -> str:
+        return self._value or ""
+
+    def __repr__(self) -> str:
+        return f"LabelDiver(divers={self._divers!r}, value={self._value!r})"
+
+    def __len__(self) -> int:
+        return len(self._labels)
+
+    def __iter__(self) -> Iterator[Tuple[str, str]]:
+        return iter(self._labels.items())
+
+    def __getitem__(self, key: str) -> str:
+        return self._labels[key]
+
+    def __getattr__(self, name: str) -> "LabelDiver":
+        if name.startswith("_"):
+            raise AttributeError
+
+        try:
+            return self._divers[name]
+        except KeyError:
+            raise AttributeError
+
+
+class Labelled(PrefectBaseModel, extra="ignore"):
+    """An object defined by string labels and values"""
+
+    __root__: Dict[str, str]
+
+    def keys(self) -> Iterable[str]:
+        return self.__root__.keys()
+
+    def items(self) -> Iterable[Tuple[str, str]]:
+        return self.__root__.items()
+
+    def __getitem__(self, label: str) -> str:
+        return self.__root__[label]
+
+    def __setitem__(self, label: str, value: str) -> str:
+        self.__root__[label] = value
+        return value
+
+    def __contains__(self, key: str) -> bool:
+        return key in self.__root__
+
+    def get(self, label: str, default: Optional[str] = None) -> Optional[str]:
+        return self.__root__.get(label, default)
+
+    def as_label_value_array(self) -> List[Dict[str, str]]:
+        return [{"label": label, "value": value} for label, value in self.items()]
+
+    @property
+    def labels(self) -> LabelDiver:
+        return LabelDiver(self.__root__)
+
+    def has_all_labels(self, labels: Dict[str, str]) -> bool:
+        return all(self.__root__.get(label) == value for label, value in labels.items())

prefect/events/utilities.py

@@ -7,7 +7,7 @@ import pendulum
 from prefect._internal.schemas.fields import DateTimeTZ
 
 from .clients import AssertingEventsClient, PrefectCloudEventsClient
-from .schemas import Event, RelatedResource
+from .schemas.events import Event, RelatedResource
 from .worker import EventsWorker, emit_events_to_cloud
 
 TIGHT_TIMING = timedelta(minutes=5)
@@ -40,7 +40,7 @@ def emit_event(
 
     Returns:
         The event that was emitted if worker is using a client that emit
-        events, otherwise None.
+        events, otherwise None
     """
     if not emit_events_to_cloud():
         return None

prefect/events/worker.py

@@ -11,7 +11,7 @@ from prefect.utilities.context import temporary_context
 
 from .clients import EventsClient, NullEventsClient, PrefectCloudEventsClient
 from .related import related_resources_from_run_context
-from .schemas import Event
+from .schemas.events import Event
 
 
 def emit_events_to_cloud() -> bool:

prefect/filesystems.py

@@ -18,8 +18,12 @@ if HAS_PYDANTIC_V2:
 else:
     from pydantic import Field, SecretStr, validator
 
+from prefect._internal.schemas.validators import (
+    stringify_path,
+    validate_basepath,
+    validate_github_access_token,
+)
 from prefect.blocks.core import Block
-from prefect.exceptions import InvalidRepositoryURLError
 from prefect.utilities.asyncutils import run_sync_in_worker_thread, sync_compatible
 from prefect.utilities.compat import copytree
 from prefect.utilities.filesystem import filter_files
@@ -97,9 +101,7 @@ class LocalFileSystem(WritableFileSystem, WritableDeploymentStorage):
 
     @validator("basepath", pre=True)
     def cast_pathlib(cls, value):
-        if isinstance(value, Path):
-            return str(value)
-        return value
+        return stringify_path(value)
 
     def _resolve_path(self, path: str) -> Path:
         # Only resolve the base path at runtime, default to the current directory
@@ -280,23 +282,7 @@ class RemoteFileSystem(WritableFileSystem, WritableDeploymentStorage):
 
     @validator("basepath")
     def check_basepath(cls, value):
-        scheme, netloc, _, _, _ = urllib.parse.urlsplit(value)
-
-        if not scheme:
-            raise ValueError(f"Base path must start with a scheme. Got {value!r}.")
-
-        if not netloc:
-            raise ValueError(
-                f"Base path must include a location after the scheme. Got {value!r}."
-            )
-
-        if scheme == "file":
-            raise ValueError(
-                "Base path scheme cannot be 'file'. Use `LocalFileSystem` instead for"
-                " local file access."
-            )
-
-        return value
+        return validate_basepath(value)
 
     def _resolve_path(self, path: str) -> str:
         base_scheme, base_netloc, base_urlpath, _, _ = urllib.parse.urlsplit(
@@ -945,22 +931,7 @@ class GitHub(ReadableDeploymentStorage):
 
     @validator("access_token")
     def _ensure_credentials_go_with_https(cls, v: str, values: dict) -> str:
-        """Ensure that credentials are not provided with 'SSH' formatted GitHub URLs.
-
-        Note: validates `access_token` specifically so that it only fires when
-        private repositories are used.
-        """
-        if v is not None:
-            if urllib.parse.urlparse(values["repository"]).scheme != "https":
-                raise InvalidRepositoryURLError(
-                    "Crendentials can only be used with GitHub repositories "
-                    "using the 'HTTPS' format. You must either remove the "
-                    "credential if you wish to use the 'SSH' format and are not "
-                    "using a private repository, or you must change the repository "
-                    "URL to the 'HTTPS' format. "
-                )
-
-        return v
+        return validate_github_access_token(v, values)
 
     def _create_repo_url(self) -> str:
         """Format the URL provided to the `git clone` command.

prefect/flows.py

@@ -75,7 +75,7 @@ from prefect.client.schemas.objects import Flow as FlowSchema
 from prefect.client.schemas.objects import FlowRun, MinimalDeploymentSchedule
 from prefect.client.schemas.schedules import SCHEDULE_TYPES
 from prefect.context import PrefectObjectRegistry, registry_from_script
-from prefect.events.schemas import DeploymentTrigger
+from prefect.events import DeploymentTriggerTypes
 from prefect.exceptions import (
     MissingFlowError,
     ObjectNotFound,
@@ -618,7 +618,7 @@ class Flow(Generic[P, R]):
         schedule: Optional[SCHEDULE_TYPES] = None,
         is_schedule_active: Optional[bool] = None,
         parameters: Optional[dict] = None,
-        triggers: Optional[List[DeploymentTrigger]] = None,
+        triggers: Optional[List[DeploymentTriggerTypes]] = None,
         description: Optional[str] = None,
         tags: Optional[List[str]] = None,
         version: Optional[str] = None,
@@ -748,7 +748,7 @@ class Flow(Generic[P, R]):
         schedules: Optional[List["FlexibleScheduleList"]] = None,
         schedule: Optional[SCHEDULE_TYPES] = None,
         is_schedule_active: Optional[bool] = None,
-        triggers: Optional[List[DeploymentTrigger]] = None,
+        triggers: Optional[List[DeploymentTriggerTypes]] = None,
         parameters: Optional[dict] = None,
         description: Optional[str] = None,
         tags: Optional[List[str]] = None,
@@ -962,7 +962,7 @@ class Flow(Generic[P, R]):
         schedules: Optional[List[MinimalDeploymentSchedule]] = None,
         schedule: Optional[SCHEDULE_TYPES] = None,
         is_schedule_active: Optional[bool] = None,
-        triggers: Optional[List[DeploymentTrigger]] = None,
+        triggers: Optional[List[DeploymentTriggerTypes]] = None,
         parameters: Optional[dict] = None,
         description: Optional[str] = None,
         tags: Optional[List[str]] = None,

prefect/infrastructure/kubernetes.py

@@ -8,7 +8,6 @@ For upgrade instructions, see https://docs.prefect.io/latest/guides/upgrade-guid
 """
 import copy
 import enum
-import json
 import math
 import os
 import shlex
@@ -23,6 +22,13 @@ from prefect._internal.compatibility.deprecated import (
     deprecated_class,
 )
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
+from prefect._internal.schemas.validators import (
+    cast_k8s_job_customizations,
+    set_default_image,
+    set_default_namespace,
+    validate_k8s_job_compatible_values,
+    validate_k8s_job_required_components,
+)
 
 if HAS_PYDANTIC_V2:
     from pydantic.v1 import Field, root_validator, validator
@@ -35,7 +41,6 @@ from prefect.blocks.kubernetes import KubernetesClusterConfig
 from prefect.exceptions import InfrastructureNotAvailable, InfrastructureNotFound
 from prefect.infrastructure.base import Infrastructure, InfrastructureResult
 from prefect.utilities.asyncutils import run_sync_in_worker_thread, sync_compatible
-from prefect.utilities.dockerutils import get_prefect_image_name
 from prefect.utilities.hashing import stable_hash
 from prefect.utilities.importtools import lazy_import
 from prefect.utilities.pydantic import JsonPatch
@@ -188,74 +193,25 @@ class KubernetesJob(Infrastructure):
 
     @validator("job")
     def ensure_job_includes_all_required_components(cls, value: KubernetesManifest):
-        patch = JsonPatch.from_diff(value, cls.base_job_manifest())
-        missing_paths = sorted([op["path"] for op in patch if op["op"] == "add"])
-        if missing_paths:
-            raise ValueError(
-                "Job is missing required attributes at the following paths: "
-                f"{', '.join(missing_paths)}"
-            )
-        return value
+        return validate_k8s_job_required_components(cls, value)
 
     @validator("job")
     def ensure_job_has_compatible_values(cls, value: KubernetesManifest):
-        patch = JsonPatch.from_diff(value, cls.base_job_manifest())
-        incompatible = sorted(
-            [
-                f"{op['path']} must have value {op['value']!r}"
-                for op in patch
-                if op["op"] == "replace"
-            ]
-        )
-        if incompatible:
-            raise ValueError(
-                "Job has incompatible values for the following attributes: "
-                f"{', '.join(incompatible)}"
-            )
-        return value
+        return validate_k8s_job_compatible_values(cls, value)
 
     @validator("customizations", pre=True)
     def cast_customizations_to_a_json_patch(
         cls, value: Union[List[Dict], JsonPatch, str]
     ) -> JsonPatch:
-        if isinstance(value, list):
-            return JsonPatch(value)
-        elif isinstance(value, str):
-            try:
-                return JsonPatch(json.loads(value))
-            except json.JSONDecodeError as exc:
-                raise ValueError(
-                    f"Unable to parse customizations as JSON: {value}. Please make sure"
-                    " that the provided value is a valid JSON string."
-                ) from exc
-        return value
+        return cast_k8s_job_customizations(cls, value)
 
     @root_validator
     def default_namespace(cls, values):
-        job = values.get("job")
-
-        namespace = values.get("namespace")
-        job_namespace = job["metadata"].get("namespace") if job else None
-
-        if not namespace and not job_namespace:
-            values["namespace"] = "default"
-
-        return values
+        return set_default_namespace(values)
 
     @root_validator
     def default_image(cls, values):
-        job = values.get("job")
-        image = values.get("image")
-        job_image = (
-            job["spec"]["template"]["spec"]["containers"][0].get("image")
-            if job
-            else None
-        )
-
-        if not image and not job_image:
-            values["image"] = get_prefect_image_name()
-
-        return values
+        return set_default_image(values)
 
     # Support serialization of the 'JsonPatch' type
     class Config:

prefect/infrastructure/provisioners/__init__.py

@@ -9,6 +9,7 @@ import rich.console
 
 _provisioners = {
     "cloud-run:push": CloudRunPushProvisioner,
+    "cloud-run-v2:push": CloudRunPushProvisioner,
     "azure-container-instance:push": ContainerInstancePushProvisioner,
     "ecs:push": ElasticContainerServicePushProvisioner,
     "modal:push": ModalPushProvisioner,

prefect/pydantic/__init__.py

@@ -0,0 +1,4 @@
+from .main import BaseModel, PrefectBaseModel
+
+
+__all__ = ["BaseModel", "PrefectBaseModel"]

prefect/pydantic/main.py

@@ -0,0 +1,15 @@
+import typing
+
+from prefect._internal.pydantic._compat import BaseModel
+
+
+class PrefectBaseModel(BaseModel):
+    def _reset_fields(self) -> typing.Set[str]:
+        """
+        A set of field names that are reset when the PrefectBaseModel is copied.
+        These fields are also disregarded for equality comparisons.
+        """
+        return set()
+
+
+__all__ = ["BaseModel", "PrefectBaseModel"]

prefect/runner/runner.py

@@ -80,7 +80,7 @@ from prefect.deployments.runner import (
 )
 from prefect.deployments.schedules import FlexibleScheduleList
 from prefect.engine import propose_state
-from prefect.events.schemas import DeploymentTrigger
+from prefect.events import DeploymentTriggerTypes
 from prefect.exceptions import (
     Abort,
 )
@@ -232,7 +232,7 @@ class Runner:
         schedule: Optional[SCHEDULE_TYPES] = None,
         is_schedule_active: Optional[bool] = None,
         parameters: Optional[dict] = None,
-        triggers: Optional[List[DeploymentTrigger]] = None,
+        triggers: Optional[List[DeploymentTriggerTypes]] = None,
         description: Optional[str] = None,
         tags: Optional[List[str]] = None,
         version: Optional[str] = None,