prefect-client 2.16.9__py3-none-any.whl → 2.17.0__py3-none-any.whl

prefect/blocks/notifications.py

@@ -77,7 +77,7 @@ class AppriseNotificationBlock(AbstractAppriseNotificationBlock, ABC):
         default=...,
         title="Webhook URL",
         description="Incoming webhook URL used to send notifications.",
-        example="https://hooks.example.com/XXX",
+        examples=["https://hooks.example.com/XXX"],
     )
 
 
@@ -105,7 +105,7 @@ class SlackWebhook(AppriseNotificationBlock):
         default=...,
         title="Webhook URL",
         description="Slack incoming webhook URL used to send notifications.",
-        example="https://hooks.slack.com/XXX",
+        examples=["https://hooks.slack.com/XXX"],
     )
 
 
@@ -131,9 +131,9 @@ class MicrosoftTeamsWebhook(AppriseNotificationBlock):
         ...,
         title="Webhook URL",
         description="The Teams incoming webhook URL used to send notifications.",
-        example=(
+        examples=[
             "https://your-org.webhook.office.com/webhookb2/XXX/IncomingWebhook/YYY/ZZZ"
-        ),
+        ],
     )
 
 
@@ -222,7 +222,7 @@ class PagerDutyWebHook(AbstractAppriseNotificationBlock):
     custom_details: Optional[Dict[str, str]] = Field(
         default=None,
         description="Additional details to include as part of the payload.",
-        example='{"disk_space_left": "145GB"}',
+        examples=['{"disk_space_left": "145GB"}'],
     )
 
     def block_initialization(self) -> None:
@@ -283,14 +283,14 @@ class TwilioSMS(AbstractAppriseNotificationBlock):
     from_phone_number: str = Field(
         default=...,
         description="The valid Twilio phone number to send the message from.",
-        example="18001234567",
+        examples=["18001234567"],
     )
 
     to_phone_numbers: List[str] = Field(
         default=...,
         description="A list of valid Twilio phone number(s) to send the message to.",
         # not wrapped in brackets because of the way UI displays examples; in code should be ["18004242424"]
-        example="18004242424",
+        examples=["18004242424"],
     )
 
     def block_initialization(self) -> None:
@@ -366,7 +366,7 @@ class OpsgenieWebhook(AbstractAppriseNotificationBlock):
             "A comma-separated list of tags you can associate with your Opsgenie"
             " message."
         ),
-        example='["tag1", "tag2"]',
+        examples=['["tag1", "tag2"]'],
     )
 
     priority: Optional[str] = Field(
@@ -388,7 +388,7 @@ class OpsgenieWebhook(AbstractAppriseNotificationBlock):
     details: Optional[Dict[str, str]] = Field(
         default=None,
         description="Additional details composed of key/values pairs.",
-        example='{"key1": "value1", "key2": "value2"}',
+        examples=['{"key1": "value1", "key2": "value2"}'],
     )
 
     def block_initialization(self) -> None:
@@ -445,7 +445,7 @@ class MattermostWebhook(AbstractAppriseNotificationBlock):
     hostname: str = Field(
         default=...,
         description="The hostname of your Mattermost server.",
-        example="Mattermost.example.com",
+        examples=["Mattermost.example.com"],
     )
 
     token: SecretStr = Field(
@@ -617,7 +617,7 @@ class CustomWebhookNotificationBlock(NotificationBlock):
     url: str = Field(
         title="Webhook URL",
         description="The webhook URL.",
-        example="https://hooks.slack.com/XXX",
+        examples=["https://hooks.slack.com/XXX"],
     )
 
     method: Literal["GET", "POST", "PUT", "PATCH", "DELETE"] = Field(
@@ -631,10 +631,10 @@ class CustomWebhookNotificationBlock(NotificationBlock):
         default=None,
         title="JSON Data",
         description="Send json data as payload.",
-        example=(
+        examples=[
             '{"text": "{{subject}}\\n{{body}}", "title": "{{name}}", "token":'
             ' "{{tokenFromSecrets}}"}'
-        ),
+        ],
     )
     form_data: Optional[Dict[str, str]] = Field(
         default=None,
@@ -642,10 +642,10 @@ class CustomWebhookNotificationBlock(NotificationBlock):
         description=(
             "Send form data as payload. Should not be used together with _JSON Data_."
         ),
-        example=(
+        examples=[
             '{"text": "{{subject}}\\n{{body}}", "title": "{{name}}", "token":'
             ' "{{tokenFromSecrets}}"}'
-        ),
+        ],
     )
 
     headers: Optional[Dict[str, str]] = Field(None, description="Custom headers.")
@@ -659,7 +659,7 @@ class CustomWebhookNotificationBlock(NotificationBlock):
         default_factory=lambda: SecretDict(dict()),
         title="Custom Secret Values",
         description="A dictionary of secret values to be substituted in other configs.",
-        example='{"tokenFromSecrets":"SomeSecretToken"}',
+        examples=['{"tokenFromSecrets":"SomeSecretToken"}'],
     )
 
     def _build_request_args(self, body: str, subject: Optional[str]):
@@ -753,14 +753,14 @@ class SendgridEmail(AbstractAppriseNotificationBlock):
     sender_email: str = Field(
         title="Sender email id",
         description="The sender email id.",
-        example="test-support@gmail.com",
+        examples=["test-support@gmail.com"],
     )
 
     to_emails: List[str] = Field(
         default=...,
         title="Recipient emails",
         description="Email ids of all recipients.",
-        example='"recipient1@gmail.com"',
+        examples=['"recipient1@gmail.com"'],
     )
 
     def block_initialization(self) -> None:

prefect/blocks/webhook.py

@@ -36,7 +36,7 @@ class Webhook(Block):
         default=...,
         title="Webhook URL",
         description="The webhook URL.",
-        example="https://hooks.slack.com/XXX",
+        examples=["https://hooks.slack.com/XXX"],
     )
 
     headers: SecretDict = Field(

prefect/client/base.py

@@ -27,6 +27,8 @@ from httpx import HTTPStatusError, Request, Response
 from prefect._vendor.starlette import status
 from typing_extensions import Self
 
+import prefect
+from prefect.client import constants
 from prefect.client.schemas.objects import CsrfToken
 from prefect.exceptions import PrefectHTTPStatusError
 from prefect.logging import get_logger
@@ -199,6 +201,11 @@ class PrefectHttpxClient(httpx.AsyncClient):
 
         super().__init__(*args, **kwargs)
 
+        user_agent = (
+            f"prefect/{prefect.__version__} (API {constants.SERVER_API_VERSION})"
+        )
+        self.headers["User-Agent"] = user_agent
+
     async def _send_with_retry(
         self,
         request: Request,

prefect/client/orchestration.py

@@ -20,6 +20,9 @@ import httpcore
 import httpx
 import pendulum
 
+from prefect._internal.compatibility.deprecated import (
+    handle_deprecated_infra_overrides_parameter,
+)
 from prefect._internal.compatibility.experimental import (
     EXPERIMENTAL_WARNING,
     ExperimentalFeature,
@@ -68,6 +71,8 @@ from prefect.client.schemas.actions import (
     LogCreate,
     TaskRunCreate,
     TaskRunUpdate,
+    VariableCreate,
+    VariableUpdate,
     WorkPoolCreate,
     WorkPoolUpdate,
     WorkQueueCreate,
@@ -1588,12 +1593,13 @@ class PrefectClient:
         path: str = None,
         entrypoint: str = None,
         infrastructure_document_id: UUID = None,
-        infra_overrides: Optional[Dict[str, Any]] = None,
+        infra_overrides: Optional[Dict[str, Any]] = None,  # for backwards compat
         parameter_openapi_schema: Optional[Dict[str, Any]] = None,
         is_schedule_active: Optional[bool] = None,
         paused: Optional[bool] = None,
         pull_steps: Optional[List[dict]] = None,
         enforce_parameter_schema: Optional[bool] = None,
+        job_variables: Optional[Dict[str, Any]] = None,
     ) -> UUID:
         """
         Create a deployment.
@@ -1608,6 +1614,10 @@ class PrefectClient:
                 used for the deployed flow
             infrastructure_document_id: an reference to the infrastructure block document
                 to use for this deployment
+            job_variables: A dictionary of dot delimited infrastructure overrides that
+                will be applied at runtime; for example `env.CONFIG_KEY=config_value` or
+                `namespace='prefect'`. This argument was previously named `infra_overrides`.
+                Both arguments are supported for backwards compatibility.
 
         Raises:
             httpx.RequestError: if the deployment was not created for any reason
@@ -1615,6 +1625,7 @@ class PrefectClient:
         Returns:
             the ID of the deployment in the backend
         """
+        jv = handle_deprecated_infra_overrides_parameter(job_variables, infra_overrides)
 
         deployment_create = DeploymentCreate(
             flow_id=flow_id,
@@ -1629,7 +1640,7 @@ class PrefectClient:
             entrypoint=entrypoint,
             manifest_path=manifest_path,  # for backwards compat
             infrastructure_document_id=infrastructure_document_id,
-            infra_overrides=infra_overrides or {},
+            job_variables=jv,
             parameter_openapi_schema=parameter_openapi_schema,
             is_schedule_active=is_schedule_active,
             paused=paused,
@@ -1706,7 +1717,7 @@ class PrefectClient:
             parameters=deployment.parameters,
             storage_document_id=deployment.storage_document_id,
             infrastructure_document_id=deployment.infrastructure_document_id,
-            infra_overrides=deployment.infra_overrides,
+            job_variables=deployment.job_variables,
             enforce_parameter_schema=deployment.enforce_parameter_schema,
         )
 
@@ -2926,11 +2937,40 @@ class PrefectClient:
             else:
                 raise
 
+    async def create_variable(self, variable: VariableCreate) -> Variable:
+        """
+        Creates an variable with the provided configuration.
+
+        Args:
+            variable: Desired configuration for the new variable.
+        Returns:
+            Information about the newly created variable.
+        """
+        response = await self._client.post(
+            "/variables/",
+            json=variable.dict(json_compatible=True, exclude_unset=True),
+        )
+        return Variable(**response.json())
+
+    async def update_variable(self, variable: VariableUpdate) -> None:
+        """
+        Updates a variable with the provided configuration.
+
+        Args:
+            variable: Desired configuration for the updated variable.
+        Returns:
+            Information about the updated variable.
+        """
+        await self._client.patch(
+            f"/variables/name/{variable.name}",
+            json=variable.dict(json_compatible=True, exclude_unset=True),
+        )
+
     async def read_variable_by_name(self, name: str) -> Optional[Variable]:
         """Reads a variable by name. Returns None if no variable is found."""
         try:
             response = await self._client.get(f"/variables/name/{name}")
-            return pydantic.parse_obj_as(Variable, response.json())
+            return Variable(**response.json())
         except httpx.HTTPStatusError as e:
             if e.response.status_code == status.HTTP_404_NOT_FOUND:
                 return None

prefect/client/schemas/actions.py

@@ -4,6 +4,7 @@ from uuid import UUID, uuid4
 
 import jsonschema
 
+from prefect._internal.compatibility.deprecated import DeprecatedInfraOverridesField
 from prefect._internal.pydantic import HAS_PYDANTIC_V2
 
 if HAS_PYDANTIC_V2:
@@ -62,7 +63,7 @@ class StateCreate(ActionBaseModel):
 
     type: StateType
     name: Optional[str] = Field(default=None)
-    message: Optional[str] = Field(default=None, example="Run started")
+    message: Optional[str] = Field(default=None, examples=["Run started"])
     state_details: StateDetails = Field(default_factory=StateDetails)
     data: Union["BaseResult[R]", "DataDocument[R]", Any] = Field(
         default=None,
@@ -73,12 +74,12 @@ class FlowCreate(ActionBaseModel):
     """Data used by the Prefect REST API to create a flow."""
 
     name: str = Field(
-        default=..., description="The name of the flow", example="my-flow"
+        default=..., description="The name of the flow", examples=["my-flow"]
     )
     tags: List[str] = Field(
         default_factory=list,
         description="A list of flow tags",
-        example=["tag-1", "tag-2"],
+        examples=[["tag-1", "tag-2"]],
     )
 
 
@@ -88,7 +89,7 @@ class FlowUpdate(ActionBaseModel):
     tags: List[str] = Field(
         default_factory=list,
         description="A list of flow tags",
-        example=["tag-1", "tag-2"],
+        examples=[["tag-1", "tag-2"]],
     )
 
 
@@ -110,7 +111,7 @@ class DeploymentScheduleUpdate(ActionBaseModel):
     )
 
 
-class DeploymentCreate(ActionBaseModel):
+class DeploymentCreate(DeprecatedInfraOverridesField, ActionBaseModel):
     """Data used by the Prefect REST API to create a deployment."""
 
     @root_validator(pre=True)
@@ -144,7 +145,7 @@ class DeploymentCreate(ActionBaseModel):
     work_pool_name: Optional[str] = Field(
         default=None,
         description="The name of the deployment's work pool.",
-        example="my-work-pool",
+        examples=["my-work-pool"],
     )
     storage_document_id: Optional[UUID] = Field(None)
     infrastructure_document_id: Optional[UUID] = Field(None)
@@ -153,11 +154,14 @@ class DeploymentCreate(ActionBaseModel):
     path: Optional[str] = Field(None)
     version: Optional[str] = Field(None)
     entrypoint: Optional[str] = Field(None)
-    infra_overrides: Optional[Dict[str, Any]] = Field(None)
+    job_variables: Optional[Dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Overrides to apply to flow run infrastructure at runtime.",
+    )
 
     def check_valid_configuration(self, base_job_template: dict):
         """Check that the combination of base_job_template defaults
-        and infra_overrides conforms to the specified schema.
+        and job_variables conforms to the specified schema.
         """
         variables_schema = deepcopy(base_job_template.get("variables"))
 
@@ -172,10 +176,10 @@ class DeploymentCreate(ActionBaseModel):
                     if "default" in v and k in required:
                         required.remove(k)
 
-            jsonschema.validate(self.infra_overrides, variables_schema)
+            jsonschema.validate(self.job_variables, variables_schema)
 
 
-class DeploymentUpdate(ActionBaseModel):
+class DeploymentUpdate(DeprecatedInfraOverridesField, ActionBaseModel):
     """Data used by the Prefect REST API to update a deployment."""
 
     @root_validator(pre=True)
@@ -199,10 +203,13 @@ class DeploymentUpdate(ActionBaseModel):
     work_pool_name: Optional[str] = Field(
         default=None,
         description="The name of the deployment's work pool.",
-        example="my-work-pool",
+        examples=["my-work-pool"],
     )
     path: Optional[str] = Field(None)
-    infra_overrides: Optional[Dict[str, Any]] = Field(None)
+    job_variables: Optional[Dict[str, Any]] = Field(
+        default_factory=dict,
+        description="Overrides to apply to flow run infrastructure at runtime.",
+    )
     entrypoint: Optional[str] = Field(None)
     manifest_path: Optional[str] = Field(None)
     storage_document_id: Optional[UUID] = Field(None)
@@ -216,7 +223,7 @@ class DeploymentUpdate(ActionBaseModel):
 
     def check_valid_configuration(self, base_job_template: dict):
         """Check that the combination of base_job_template defaults
-        and infra_overrides conforms to the specified schema.
+        and job_variables conforms to the specified schema.
         """
         variables_schema = deepcopy(base_job_template.get("variables"))
 
@@ -232,7 +239,7 @@ class DeploymentUpdate(ActionBaseModel):
                         required.remove(k)
 
         if variables_schema is not None:
-            jsonschema.validate(self.infra_overrides, variables_schema)
+            jsonschema.validate(self.job_variables, variables_schema)
 
 
 class FlowRunUpdate(ActionBaseModel):
@@ -605,10 +612,10 @@ class FlowRunNotificationPolicyCreate(ActionBaseModel):
             " Valid variables include:"
             f" {listrepr(sorted(objects.FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS), sep=', ')}"
         ),
-        example=(
+        examples=[
             "Flow run {flow_run_name} with id {flow_run_id} entered state"
             " {flow_run_state_name}."
-        ),
+        ],
     )
 
     @validator("message_template")
@@ -656,13 +663,13 @@ class VariableCreate(ActionBaseModel):
     name: str = Field(
         default=...,
         description="The name of the variable",
-        example="my_variable",
+        examples=["my_variable"],
         max_length=objects.MAX_VARIABLE_NAME_LENGTH,
     )
     value: str = Field(
         default=...,
         description="The value of the variable",
-        example="my-value",
+        examples=["my-value"],
         max_length=objects.MAX_VARIABLE_VALUE_LENGTH,
     )
     tags: Optional[List[str]] = Field(default=None)
@@ -677,13 +684,13 @@ class VariableUpdate(ActionBaseModel):
     name: Optional[str] = Field(
         default=None,
         description="The name of the variable",
-        example="my_variable",
+        examples=["my_variable"],
         max_length=objects.MAX_VARIABLE_NAME_LENGTH,
     )
     value: Optional[str] = Field(
         default=None,
         description="The value of the variable",
-        example="my-value",
+        examples=["my-value"],
         max_length=objects.MAX_VARIABLE_NAME_LENGTH,
     )
     tags: Optional[List[str]] = Field(default=None)