prefect-client 2.20.4__py3-none-any.whl → 3.0.0__py3-none-any.whl

prefect/utilities/urls.py

@@ -0,0 +1,195 @@
+import inspect
+import urllib.parse
+from typing import Any, Literal, Optional, Union
+from uuid import UUID
+
+from pydantic import BaseModel
+
+from prefect import settings
+from prefect.blocks.core import Block
+from prefect.events.schemas.automations import Automation
+from prefect.events.schemas.events import ReceivedEvent, Resource
+from prefect.futures import PrefectFuture
+from prefect.logging.loggers import get_logger
+from prefect.variables import Variable
+
+logger = get_logger("utilities.urls")
+
+# The following objects are excluded from UI URL generation because we lack a
+# directly-addressable URL:
+#   worker
+#   artifact
+#   variable
+#   saved-search
+UI_URL_FORMATS = {
+    "flow": "flows/flow/{obj_id}",
+    "flow-run": "runs/flow-run/{obj_id}",
+    "task-run": "runs/task-run/{obj_id}",
+    "block": "blocks/block/{obj_id}",
+    "block-document": "blocks/block/{obj_id}",
+    "work-pool": "work-pools/work-pool/{obj_id}",
+    "work-queue": "work-queues/work-queue/{obj_id}",
+    "concurrency-limit": "concurrency-limits/concurrency-limit/{obj_id}",
+    "deployment": "deployments/deployment/{obj_id}",
+    "automation": "automations/automation/{obj_id}",
+    "received-event": "events/event/{occurred}/{obj_id}",
+}
+
+# The following objects are excluded from API URL generation because we lack a
+# directly-addressable URL:
+#   worker
+#   artifact
+#   saved-search
+#   received-event
+API_URL_FORMATS = {
+    "flow": "flows/{obj_id}",
+    "flow-run": "flow_runs/{obj_id}",
+    "task-run": "task_runs/{obj_id}",
+    "variable": "variables/name/{obj_id}",
+    "block": "blocks/{obj_id}",
+    "work-pool": "work_pools/{obj_id}",
+    "work-queue": "work_queues/{obj_id}",
+    "concurrency-limit": "concurrency_limits/{obj_id}",
+    "deployment": "deployments/{obj_id}",
+    "automation": "automations/{obj_id}",
+}
+
+URLType = Literal["ui", "api"]
+RUN_TYPES = {"flow-run", "task-run"}
+
+
+def convert_class_to_name(obj: Any) -> str:
+    """
+    Convert CamelCase class name to dash-separated lowercase name
+    """
+    cls = obj if inspect.isclass(obj) else obj.__class__
+    name = cls.__name__
+    return "".join(["-" + i.lower() if i.isupper() else i for i in name]).lstrip("-")
+
+
+def url_for(
+    obj: Union[
+        PrefectFuture,
+        Block,
+        Variable,
+        Automation,
+        Resource,
+        ReceivedEvent,
+        BaseModel,
+        str,
+    ],
+    obj_id: Optional[Union[str, UUID]] = None,
+    url_type: URLType = "ui",
+    default_base_url: Optional[str] = None,
+) -> Optional[str]:
+    """
+    Returns the URL for a Prefect object.
+
+    Pass in a supported object directly or provide an object name and ID.
+
+    Args:
+        obj (Union[PrefectFuture, Block, Variable, Automation, Resource, ReceivedEvent, BaseModel, str]):
+            A Prefect object to get the URL for, or its URL name and ID.
+        obj_id (Union[str, UUID], optional):
+            The UUID of the object.
+        url_type (Literal["ui", "api"], optional):
+            Whether to return the URL for the UI (default) or API.
+        default_base_url (str, optional):
+            The default base URL to use if no URL is configured.
+
+    Returns:
+        Optional[str]: The URL for the given object or None if the object is not supported.
+
+    Examples:
+        url_for(my_flow_run)
+        url_for(obj=my_flow_run)
+        url_for("flow-run", obj_id="123e4567-e89b-12d3-a456-426614174000")
+    """
+    if isinstance(obj, PrefectFuture):
+        name = "task-run"
+    elif isinstance(obj, Block):
+        name = "block"
+    elif isinstance(obj, Automation):
+        name = "automation"
+    elif isinstance(obj, ReceivedEvent):
+        name = "received-event"
+    elif isinstance(obj, Resource):
+        if obj.id.startswith("prefect."):
+            name = obj.id.split(".")[1]
+        else:
+            logger.debug(f"No URL known for resource with ID: {obj.id}")
+            return None
+    elif isinstance(obj, str):
+        name = obj
+    else:
+        name = convert_class_to_name(obj)
+
+    # Can't do an isinstance check here because the client build
+    # doesn't have access to that server schema.
+    if name == "work-queue-with-status":
+        name = "work-queue"
+
+    if url_type != "ui" and url_type != "api":
+        raise ValueError(f"Invalid URL type: {url_type}. Use 'ui' or 'api'.")
+
+    if url_type == "ui" and name not in UI_URL_FORMATS:
+        logger.debug("No UI URL known for this object: %s", name)
+        return None
+    elif url_type == "api" and name not in API_URL_FORMATS:
+        logger.debug("No API URL known for this object: %s", name)
+        return None
+
+    if isinstance(obj, str) and not obj_id:
+        raise ValueError(
+            "If passing an object name, you must also provide an object ID."
+        )
+
+    base_url = (
+        settings.PREFECT_UI_URL.value()
+        if url_type == "ui"
+        else settings.PREFECT_API_URL.value()
+    )
+    base_url = base_url or default_base_url
+
+    if not base_url:
+        logger.debug(
+            f"No URL found for the Prefect {'UI' if url_type == 'ui' else 'API'}, "
+            f"and no default base path provided."
+        )
+        return None
+
+    if not obj_id:
+        # We treat PrefectFuture as if it was the underlying task run,
+        # so we need to check the object type here instead of name.
+        if isinstance(obj, PrefectFuture):
+            obj_id = getattr(obj, "task_run_id", None)
+        elif name == "block":
+            # Blocks are client-side objects whose API representation is a
+            # BlockDocument.
+            obj_id = obj._block_document_id
+        elif name in ("variable", "work-pool"):
+            obj_id = obj.name
+        elif isinstance(obj, Resource):
+            obj_id = obj.id.rpartition(".")[2]
+        else:
+            obj_id = getattr(obj, "id", None)
+        if not obj_id:
+            logger.debug(
+                "An ID is required to build a URL, but object did not have one: %s", obj
+            )
+            return ""
+
+    url_format = (
+        UI_URL_FORMATS.get(name) if url_type == "ui" else API_URL_FORMATS.get(name)
+    )
+
+    if isinstance(obj, ReceivedEvent):
+        url = url_format.format(
+            occurred=obj.occurred.strftime("%Y-%m-%d"), obj_id=obj_id
+        )
+    else:
+        url = url_format.format(obj_id=obj_id)
+
+    if not base_url.endswith("/"):
+        base_url += "/"
+    return urllib.parse.urljoin(base_url, url)

prefect/utilities/visualization.py

@@ -1,6 +1,7 @@
 """
 Utilities for working with Flow.visualize()
 """
+
 from functools import partial
 from typing import Any, List, Optional
 

prefect/variables.py

@@ -1,9 +1,11 @@
 from typing import List, Optional
 
-from prefect._internal.compatibility.deprecated import deprecated_callable
+from prefect._internal.compatibility.migration import getattr_migration
 from prefect.client.schemas.actions import VariableCreate as VariableRequest
 from prefect.client.schemas.actions import VariableUpdate as VariableUpdateRequest
 from prefect.client.utilities import get_or_create_client
+from prefect.exceptions import ObjectNotFound
+from prefect.types import StrictVariableValue
 from prefect.utilities.asyncutils import sync_compatible
 
 
@@ -23,92 +25,109 @@ class Variable(VariableRequest):
     async def set(
         cls,
         name: str,
-        value: str,
+        value: StrictVariableValue,
         tags: Optional[List[str]] = None,
         overwrite: bool = False,
-    ) -> Optional[str]:
+    ) -> "Variable":
         """
-        Sets a new variable. If one exists with the same name, user must pass `overwrite=True`
-        ```
-            from prefect.variables import Variable
+        Sets a new variable. If one exists with the same name, must pass `overwrite=True`
 
-            @flow
-            def my_flow():
-                var = Variable.set(name="my_var",value="test_value", tags=["hi", "there"], overwrite=True)
-        ```
-        or
-        ```
+        Returns the newly set variable object.
+
+        Args:
+            - name: The name of the variable to set.
+            - value: The value of the variable to set.
+            - tags: An optional list of strings to associate with the variable.
+            - overwrite: Whether to overwrite the variable if it already exists.
+
+        Example:
+            Set a new variable and overwrite it if it already exists.
+            ```
             from prefect.variables import Variable
 
             @flow
-            async def my_flow():
-                var = await Variable.set(name="my_var",value="test_value", tags=["hi", "there"], overwrite=True)
-        ```
+            def my_flow():
+                Variable.set(name="my_var",value="test_value", tags=["hi", "there"], overwrite=True)
+            ```
         """
         client, _ = get_or_create_client()
-        variable = await client.read_variable_by_name(name)
-        var_dict = {"name": name, "value": value}
-        var_dict["tags"] = tags or []
-        if variable:
+        variable_exists = await client.read_variable_by_name(name)
+        var_dict = {"name": name, "value": value, "tags": tags or []}
+
+        if variable_exists:
             if not overwrite:
                 raise ValueError(
-                    "You are attempting to save a variable with a name that is already in use. If you would like to overwrite the values that are saved, then call .set with `overwrite=True`."
+                    f"Variable {name!r} already exists. Use `overwrite=True` to update it."
                 )
-            var = VariableUpdateRequest(**var_dict)
-            await client.update_variable(variable=var)
+            await client.update_variable(variable=VariableUpdateRequest(**var_dict))
             variable = await client.read_variable_by_name(name)
         else:
-            var = VariableRequest(**var_dict)
-            variable = await client.create_variable(variable=var)
+            variable = await client.create_variable(
+                variable=VariableRequest(**var_dict)
+            )
 
-        return variable if variable else None
+        return variable
 
     @classmethod
     @sync_compatible
-    async def get(cls, name: str, default: Optional[str] = None) -> Optional[str]:
+    async def get(
+        cls,
+        name: str,
+        default: StrictVariableValue = None,
+    ) -> StrictVariableValue:
         """
-        Get a variable by name. If doesn't exist return the default.
-        ```
+        Get a variable's value by name.
+
+        If the variable does not exist, return the default value.
+
+        Args:
+            - name: The name of the variable value to get.
+            - default: The default value to return if the variable does not exist.
+
+        Example:
+            Get a variable's value by name.
+            ```python
+            from prefect import flow
             from prefect.variables import Variable
 
             @flow
             def my_flow():
                 var = Variable.get("my_var")
-        ```
-        or
-        ```
+            ```
+        """
+        client, _ = get_or_create_client()
+        variable = await client.read_variable_by_name(name)
+
+        return variable.value if variable else default
+
+    @classmethod
+    @sync_compatible
+    async def unset(cls, name: str) -> bool:
+        """
+        Unset a variable by name.
+
+        Args:
+            - name: The name of the variable to unset.
+
+        Returns `True` if the variable was deleted, `False` if the variable did not exist.
+
+        Example:
+            Unset a variable by name.
+            ```python
+            from prefect import flow
             from prefect.variables import Variable
 
             @flow
-            async def my_flow():
-                var = await Variable.get("my_var")
-        ```
+            def my_flow():
+                Variable.unset("my_var")
+            ```
         """
         client, _ = get_or_create_client()
-        variable = await client.read_variable_by_name(name)
-        return variable if variable else default
+        try:
+            await client.delete_variable_by_name(name=name)
+            return True
+        except ObjectNotFound:
+            return False
 
 
-@deprecated_callable(start_date="Apr 2024")
-@sync_compatible
-async def get(name: str, default: Optional[str] = None) -> Optional[str]:
-    """
-    Get a variable by name. If doesn't exist return the default.
-    ```
-        from prefect import variables
-
-        @flow
-        def my_flow():
-            var = variables.get("my_var")
-    ```
-    or
-    ```
-        from prefect import variables
-
-        @flow
-        async def my_flow():
-            var = await variables.get("my_var")
-    ```
-    """
-    variable = await Variable.get(name)
-    return variable.value if variable else default
+__getattr__ = getattr_migration(__name__)

prefect/workers/__init__.py

@@ -1,2 +1 @@
 from .process import ProcessWorker
-from .block import BlockWorker