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

prefect/results.py

@@ -1,10 +1,10 @@
 import abc
+import inspect
 import uuid
 from functools import partial
 from typing import (
     TYPE_CHECKING,
     Any,
-    Awaitable,
     Callable,
     Dict,
     Generic,
@@ -16,20 +16,29 @@ from typing import (
 )
 from uuid import UUID
 
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    PrivateAttr,
+    ValidationError,
+    model_serializer,
+    model_validator,
+)
+from pydantic_core import PydanticUndefinedType
+from pydantic_extra_types.pendulum_dt import DateTime
 from typing_extensions import ParamSpec, Self
 
 import prefect
-from prefect._internal.pydantic import HAS_PYDANTIC_V2
 from prefect.blocks.core import Block
 from prefect.client.utilities import inject_client
-from prefect.exceptions import MissingResult
+from prefect.exceptions import MissingContextError, SerializationError
 from prefect.filesystems import (
     LocalFileSystem,
-    ReadableFileSystem,
     WritableFileSystem,
 )
 from prefect.logging import get_logger
-from prefect.serializers import Serializer
+from prefect.serializers import PickleSerializer, Serializer
 from prefect.settings import (
     PREFECT_DEFAULT_RESULT_STORAGE_BLOCK,
     PREFECT_LOCAL_STORAGE_PATH,
@@ -41,13 +50,6 @@ from prefect.utilities.annotations import NotSet
 from prefect.utilities.asyncutils import sync_compatible
 from prefect.utilities.pydantic import get_dispatch_key, lookup_type, register_base_type
 
-if HAS_PYDANTIC_V2:
-    import pydantic.v1 as pydantic
-
-else:
-    import pydantic
-
-
 if TYPE_CHECKING:
     from prefect import Flow, Task
     from prefect.client.orchestration import PrefectClient
@@ -66,426 +68,555 @@ logger = get_logger("results")
 P = ParamSpec("P")
 R = TypeVar("R")
 
+_default_storages: Dict[Tuple[str, str], WritableFileSystem] = {}
+
 
 @sync_compatible
-async def get_default_result_storage() -> ResultStorage:
+async def get_default_result_storage() -> WritableFileSystem:
     """
     Generate a default file system for result storage.
     """
-    return (
-        await Block.load(PREFECT_DEFAULT_RESULT_STORAGE_BLOCK.value())
-        if PREFECT_DEFAULT_RESULT_STORAGE_BLOCK.value() is not None
-        else LocalFileSystem(basepath=PREFECT_LOCAL_STORAGE_PATH.value())
-    )
+    default_block = PREFECT_DEFAULT_RESULT_STORAGE_BLOCK.value()
 
+    if default_block is not None:
+        return await resolve_result_storage(default_block)
 
-_default_task_scheduling_storages: Dict[Tuple[str, str], WritableFileSystem] = {}
+    # otherwise, use the local file system
+    basepath = PREFECT_LOCAL_STORAGE_PATH.value()
+    return LocalFileSystem(basepath=str(basepath))
 
 
-async def get_or_create_default_task_scheduling_storage() -> ResultStorage:
+@sync_compatible
+async def resolve_result_storage(
+    result_storage: ResultStorage,
+) -> WritableFileSystem:
     """
-    Generate a default file system for autonomous task parameter/result storage.
+    Resolve one of the valid `ResultStorage` input types into a saved block
+    document id and an instance of the block.
     """
-    default_storage_name, storage_path = cache_key = (
-        PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK.value(),
-        PREFECT_LOCAL_STORAGE_PATH.value(),
-    )
-
-    async def get_storage():
-        try:
-            return await Block.load(default_storage_name)
-        except ValueError as e:
-            if "Unable to find" not in str(e):
-                raise e
-
-        block_type_slug, name = default_storage_name.split("/")
-        if block_type_slug == "local-file-system":
-            block = LocalFileSystem(basepath=storage_path)
-        else:
-            raise Exception(
-                "The default task storage block does not exist, but it is of type "
-                f"'{block_type_slug}' which cannot be created implicitly.  Please create "
-                "the block manually."
-            )
+    from prefect.client.orchestration import get_client
 
-        try:
-            await block.save(name, overwrite=False)
-            return block
-        except ValueError as e:
-            if "already in use" not in str(e):
-                raise e
+    client = get_client()
+    if isinstance(result_storage, Block):
+        storage_block = result_storage
 
-        return await Block.load(default_storage_name)
+        if storage_block._block_document_id is not None:
+            # Avoid saving the block if it already has an identifier assigned
+            storage_block_id = storage_block._block_document_id
+        else:
+            storage_block_id = None
+    elif isinstance(result_storage, str):
+        storage_block = await Block.load(result_storage, client=client)
+        storage_block_id = storage_block._block_document_id
+        assert storage_block_id is not None, "Loaded storage blocks must have ids"
+    else:
+        raise TypeError(
+            "Result storage must be one of the following types: 'UUID', 'Block', "
+            f"'str'. Got unsupported type {type(result_storage).__name__!r}."
+        )
 
-    try:
-        return _default_task_scheduling_storages[cache_key]
-    except KeyError:
-        storage = await get_storage()
-        _default_task_scheduling_storages[cache_key] = storage
-        return storage
+    return storage_block
 
 
-def get_default_result_serializer() -> ResultSerializer:
+def resolve_serializer(serializer: ResultSerializer) -> Serializer:
     """
-    Generate a default file system for result storage.
+    Resolve one of the valid `ResultSerializer` input types into a serializer
+    instance.
     """
-    return PREFECT_RESULTS_DEFAULT_SERIALIZER.value()
+    if isinstance(serializer, Serializer):
+        return serializer
+    elif isinstance(serializer, str):
+        return Serializer(type=serializer)
+    else:
+        raise TypeError(
+            "Result serializer must be one of the following types: 'Serializer', "
+            f"'str'. Got unsupported type {type(serializer).__name__!r}."
+        )
 
 
-def get_default_persist_setting() -> bool:
+async def get_or_create_default_task_scheduling_storage() -> ResultStorage:
     """
-    Return the default option for result persistence (False).
+    Generate a default file system for background task parameter/result storage.
     """
-    return PREFECT_RESULTS_PERSIST_BY_DEFAULT.value()
+    default_block = PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK.value()
 
+    if default_block is not None:
+        return await Block.load(default_block)
 
-def flow_features_require_result_persistence(flow: "Flow") -> bool:
-    """
-    Returns `True` if the given flow uses features that require its result to be
-    persisted.
-    """
-    if not flow.cache_result_in_memory:
-        return True
-    return False
+    # otherwise, use the local file system
+    basepath = PREFECT_LOCAL_STORAGE_PATH.value()
+    return LocalFileSystem(basepath=basepath)
 
 
-def flow_features_require_child_result_persistence(flow: "Flow") -> bool:
+def get_default_result_serializer() -> Serializer:
     """
-    Returns `True` if the given flow uses features that require child flow and task
-    runs to persist their results.
+    Generate a default file system for result storage.
     """
-    if flow and flow.retries:
-        return True
-    return False
+    return resolve_serializer(PREFECT_RESULTS_DEFAULT_SERIALIZER.value())
 
 
-def task_features_require_result_persistence(task: "Task") -> bool:
+def get_default_persist_setting() -> bool:
     """
-    Returns `True` if the given task uses features that require its result to be
-    persisted.
+    Return the default option for result persistence (False).
     """
-    if task.cache_key_fn:
-        return True
-    if not task.cache_result_in_memory:
-        return True
-    return False
+    return PREFECT_RESULTS_PERSIST_BY_DEFAULT.value()
 
 
-def _format_user_supplied_storage_key(key):
+def _format_user_supplied_storage_key(key: str) -> str:
     # Note here we are pinning to task runs since flow runs do not support storage keys
     # yet; we'll need to split logic in the future or have two separate functions
     runtime_vars = {key: getattr(prefect.runtime, key) for key in dir(prefect.runtime)}
     return key.format(**runtime_vars, parameters=prefect.runtime.task_run.parameters)
 
 
-class ResultFactory(pydantic.BaseModel):
+class ResultStore(BaseModel):
     """
     A utility to generate `Result` types.
     """
 
-    persist_result: bool
-    cache_result_in_memory: bool
-    serializer: Serializer
-    storage_block_id: Optional[uuid.UUID]
-    storage_block: WritableFileSystem
-    storage_key_fn: Callable[[], str]
+    result_storage: Optional[WritableFileSystem] = Field(default=None)
+    persist_result: bool = Field(default_factory=get_default_persist_setting)
+    cache_result_in_memory: bool = Field(default=True)
+    serializer: Serializer = Field(default_factory=get_default_result_serializer)
+    storage_key_fn: Callable[[], str] = Field(default=DEFAULT_STORAGE_KEY_FN)
 
-    @classmethod
-    @inject_client
-    async def default_factory(cls, client: "PrefectClient" = None, **kwargs):
+    @property
+    def result_storage_block_id(self) -> Optional[UUID]:
+        if self.result_storage is None:
+            return None
+        return self.result_storage._block_document_id
+
+    @sync_compatible
+    async def update_for_flow(self, flow: "Flow") -> Self:
         """
-        Create a new result factory with default options.
+        Create a new result store for a flow with updated settings.
 
-        Keyword arguments may be provided to override defaults. Null keys will be
-        ignored.
+        Args:
+            flow: The flow to update the result store for.
+
+        Returns:
+            An updated result store.
         """
-        # Remove any null keys so `setdefault` can do its magic
-        for key, value in tuple(kwargs.items()):
-            if value is None:
-                kwargs.pop(key)
+        update = {}
+        if flow.result_storage is not None:
+            update["result_storage"] = await resolve_result_storage(flow.result_storage)
+        if flow.result_serializer is not None:
+            update["serializer"] = resolve_serializer(flow.result_serializer)
+        if flow.persist_result is not None:
+            update["persist_result"] = flow.persist_result
+        if flow.cache_result_in_memory is not None:
+            update["cache_result_in_memory"] = flow.cache_result_in_memory
+        if self.result_storage is None and update.get("result_storage") is None:
+            update["result_storage"] = await get_default_result_storage()
+        return self.model_copy(update=update)
 
-        # Apply defaults
-        kwargs.setdefault("result_storage", await get_default_result_storage())
-        kwargs.setdefault("result_serializer", get_default_result_serializer())
-        kwargs.setdefault("persist_result", get_default_persist_setting())
-        kwargs.setdefault("cache_result_in_memory", True)
-        kwargs.setdefault("storage_key_fn", DEFAULT_STORAGE_KEY_FN)
+    @sync_compatible
+    async def update_for_task(self: Self, task: "Task") -> Self:
+        """
+        Create a new result store for a task.
 
-        return await cls.from_settings(**kwargs, client=client)
+        Args:
+            task: The task to update the result store for.
 
-    @classmethod
-    @inject_client
-    async def from_flow(
-        cls: Type[Self], flow: "Flow", client: "PrefectClient" = None
-    ) -> Self:
-        """
-        Create a new result factory for a flow.
-        """
-        from prefect.context import FlowRunContext
-
-        ctx = FlowRunContext.get()
-        if ctx:
-            # This is a child flow run
-            return await cls.from_settings(
-                result_storage=flow.result_storage or ctx.result_factory.storage_block,
-                result_serializer=flow.result_serializer
-                or ctx.result_factory.serializer,
-                persist_result=(
-                    flow.persist_result
-                    if flow.persist_result is not None
-                    # !! Child flows persist their result by default if the it or the
-                    #    parent flow uses a feature that requires it
-                    else (
-                        flow_features_require_result_persistence(flow)
-                        or flow_features_require_child_result_persistence(ctx.flow)
-                        or get_default_persist_setting()
-                    )
-                ),
-                cache_result_in_memory=flow.cache_result_in_memory,
-                storage_key_fn=DEFAULT_STORAGE_KEY_FN,
-                client=client,
-            )
-        else:
-            # This is a root flow run
-            # Pass the flow settings up to the default which will replace nulls with
-            # our default options
-            return await cls.default_factory(
-                client=client,
-                result_storage=flow.result_storage,
-                result_serializer=flow.result_serializer,
-                persist_result=(
-                    flow.persist_result
-                    if flow.persist_result is not None
-                    # !! Flows persist their result by default if uses a feature that
-                    #    requires it
-                    else (
-                        flow_features_require_result_persistence(flow)
-                        or get_default_persist_setting()
-                    )
-                ),
-                cache_result_in_memory=flow.cache_result_in_memory,
-                storage_key_fn=DEFAULT_STORAGE_KEY_FN,
+        Returns:
+            An updated result store.
+        """
+        update = {}
+        if task.result_storage is not None:
+            update["result_storage"] = await resolve_result_storage(task.result_storage)
+        if task.result_serializer is not None:
+            update["serializer"] = resolve_serializer(task.result_serializer)
+        if task.persist_result is not None:
+            update["persist_result"] = task.persist_result
+        if task.cache_result_in_memory is not None:
+            update["cache_result_in_memory"] = task.cache_result_in_memory
+        if task.result_storage_key is not None:
+            update["storage_key_fn"] = partial(
+                _format_user_supplied_storage_key, task.result_storage_key
             )
+        if self.result_storage is None and update.get("result_storage") is None:
+            update["result_storage"] = await get_default_result_storage()
+        return self.model_copy(update=update)
 
-    @classmethod
-    @inject_client
-    async def from_task(
-        cls: Type[Self], task: "Task", client: "PrefectClient" = None
-    ) -> Self:
+    @sync_compatible
+    async def _read(self, key: str) -> "ResultRecord":
         """
-        Create a new result factory for a task.
+        Read a result record from storage.
+
+        This is the internal implementation. Use `read` or `aread` for synchronous and
+        asynchronous result reading respectively.
+
+        Args:
+            key: The key to read the result record from.
+
+        Returns:
+            A result record.
         """
-        from prefect.context import FlowRunContext
+        if self.result_storage is None:
+            self.result_storage = await get_default_result_storage()
 
-        ctx = FlowRunContext.get()
+        content = await self.result_storage.read_path(f"{key}")
+        return ResultRecord.deserialize(content)
 
-        if ctx and ctx.autonomous_task_run:
-            return await cls.from_autonomous_task(task, client=client)
+    def read(self, key: str) -> "ResultRecord":
+        """
+        Read a result record from storage.
 
-        return await cls._from_task(task, get_default_result_storage, client=client)
+        Args:
+            key: The key to read the result record from.
 
-    @classmethod
-    @inject_client
-    async def from_autonomous_task(
-        cls: Type[Self], task: "Task[P, R]", client: "PrefectClient" = None
-    ) -> Self:
+        Returns:
+            A result record.
         """
-        Create a new result factory for an autonomous task.
+        return self._read(key=key, _sync=True)
+
+    async def aread(self, key: str) -> "ResultRecord":
         """
-        return await cls._from_task(
-            task, get_or_create_default_task_scheduling_storage, client=client
-        )
+        Read a result record from storage.
 
-    @classmethod
-    @inject_client
-    async def _from_task(
-        cls: Type[Self],
-        task: "Task",
-        default_storage_getter: Callable[[], Awaitable[ResultStorage]],
-        client: "PrefectClient" = None,
-    ) -> Self:
-        from prefect.context import FlowRunContext
-
-        ctx = FlowRunContext.get()
-
-        result_storage = task.result_storage or (
-            ctx.result_factory.storage_block
-            if ctx and ctx.result_factory
-            else await default_storage_getter()
-        )
-        result_serializer = task.result_serializer or (
-            ctx.result_factory.serializer
-            if ctx and ctx.result_factory
-            else get_default_result_serializer()
-        )
-        persist_result = (
-            task.persist_result
-            if task.persist_result is not None
-            # !! Tasks persist their result by default if their parent flow uses a
-            #    feature that requires it or the task uses a feature that requires it
-            else (
-                (
-                    flow_features_require_child_result_persistence(ctx.flow)
-                    if ctx
-                    else False
-                )
-                or task_features_require_result_persistence(task)
-                or get_default_persist_setting()
-            )
-        )
+        Args:
+            key: The key to read the result record from.
 
-        cache_result_in_memory = task.cache_result_in_memory
-
-        return await cls.from_settings(
-            result_storage=result_storage,
-            result_serializer=result_serializer,
-            persist_result=persist_result,
-            cache_result_in_memory=cache_result_in_memory,
-            client=client,
-            storage_key_fn=(
-                partial(_format_user_supplied_storage_key, task.result_storage_key)
-                if task.result_storage_key is not None
-                else DEFAULT_STORAGE_KEY_FN
-            ),
-        )
+        Returns:
+            A result record.
+        """
+        return await self._read(key=key, _sync=False)
 
-    @classmethod
-    @inject_client
-    async def from_settings(
-        cls: Type[Self],
-        result_storage: ResultStorage,
-        result_serializer: ResultSerializer,
-        persist_result: bool,
-        cache_result_in_memory: bool,
-        storage_key_fn: Callable[[], str],
-        client: "PrefectClient",
-    ) -> Self:
-        storage_block_id, storage_block = await cls.resolve_storage_block(
-            result_storage, client=client, persist_result=persist_result
-        )
-        serializer = cls.resolve_serializer(result_serializer)
+    @sync_compatible
+    async def _write(
+        self,
+        obj: Any,
+        key: Optional[str] = None,
+        expiration: Optional[DateTime] = None,
+    ):
+        """
+        Write a result to storage.
 
-        return cls(
-            storage_block=storage_block,
-            storage_block_id=storage_block_id,
-            serializer=serializer,
-            persist_result=persist_result,
-            cache_result_in_memory=cache_result_in_memory,
-            storage_key_fn=storage_key_fn,
+        This is the internal implementation. Use `write` or `awrite` for synchronous and
+        asynchronous result writing respectively.
+
+        Args:
+            key: The key to write the result record to.
+            obj: The object to write to storage.
+            expiration: The expiration time for the result record.
+        """
+        if self.result_storage is None:
+            self.result_storage = await get_default_result_storage()
+        key = key or self.storage_key_fn()
+
+        record = ResultRecord(
+            result=obj,
+            metadata=ResultRecordMetadata(
+                serializer=self.serializer, expiration=expiration, storage_key=key
+            ),
         )
+        await self.apersist_result_record(record)
 
-    @staticmethod
-    async def resolve_storage_block(
-        result_storage: ResultStorage,
-        client: "PrefectClient",
-        persist_result: bool = True,
-    ) -> Tuple[Optional[uuid.UUID], WritableFileSystem]:
-        """
-        Resolve one of the valid `ResultStorage` input types into a saved block
-        document id and an instance of the block.
-        """
-        if isinstance(result_storage, Block):
-            storage_block = result_storage
-
-            if storage_block._block_document_id is not None:
-                # Avoid saving the block if it already has an identifier assigned
-                storage_block_id = storage_block._block_document_id
-            else:
-                if persist_result:
-                    # TODO: Overwrite is true to avoid issues where the save collides with
-                    # a previously saved document with a matching hash
-                    storage_block_id = await storage_block._save(
-                        is_anonymous=True, overwrite=True, client=client
-                    )
-                else:
-                    # a None-type UUID on unpersisted storage should not matter
-                    # since the ID is generated on the server
-                    storage_block_id = None
-        elif isinstance(result_storage, str):
-            storage_block = await Block.load(result_storage, client=client)
-            storage_block_id = storage_block._block_document_id
-            assert storage_block_id is not None, "Loaded storage blocks must have ids"
-        else:
-            raise TypeError(
-                "Result storage must be one of the following types: 'UUID', 'Block', "
-                f"'str'. Got unsupported type {type(result_storage).__name__!r}."
-            )
+    def write(self, key: str, obj: Any, expiration: Optional[DateTime] = None):
+        """
+        Write a result to storage.
 
-        return storage_block_id, storage_block
+        Handles the creation of a `ResultRecord` and its serialization to storage.
 
-    @staticmethod
-    def resolve_serializer(serializer: ResultSerializer) -> Serializer:
+        Args:
+            key: The key to write the result record to.
+            obj: The object to write to storage.
+            expiration: The expiration time for the result record.
         """
-        Resolve one of the valid `ResultSerializer` input types into a serializer
-        instance.
+        return self._write(obj=obj, key=key, expiration=expiration, _sync=True)
+
+    async def awrite(self, key: str, obj: Any, expiration: Optional[DateTime] = None):
         """
-        if isinstance(serializer, Serializer):
-            return serializer
-        elif isinstance(serializer, str):
-            return Serializer(type=serializer)
-        else:
-            raise TypeError(
-                "Result serializer must be one of the following types: 'Serializer', "
-                f"'str'. Got unsupported type {type(serializer).__name__!r}."
-            )
+        Write a result to storage.
+
+        Args:
+            key: The key to write the result record to.
+            obj: The object to write to storage.
+            expiration: The expiration time for the result record.
+        """
+        return await self._write(obj=obj, key=key, expiration=expiration, _sync=False)
 
     @sync_compatible
-    async def create_result(self, obj: R) -> Union[R, "BaseResult[R]"]:
+    async def _persist_result_record(self, result_record: "ResultRecord"):
+        """
+        Persist a result record to storage.
+
+        Args:
+            result_record: The result record to persist.
+        """
+        if self.result_storage is None:
+            self.result_storage = await get_default_result_storage()
+
+        await self.result_storage.write_path(
+            result_record.metadata.storage_key, content=result_record.serialize()
+        )
+
+    def persist_result_record(self, result_record: "ResultRecord"):
+        """
+        Persist a result record to storage.
+
+        Args:
+            result_record: The result record to persist.
+        """
+        return self._persist_result_record(result_record=result_record, _sync=True)
+
+    async def apersist_result_record(self, result_record: "ResultRecord"):
         """
-        Create a result type for the given object.
+        Persist a result record to storage.
 
-        If persistence is disabled, the object is wrapped in an `UnpersistedResult` and
-        returned.
+        Args:
+            result_record: The result record to persist.
+        """
+        return await self._persist_result_record(
+            result_record=result_record, _sync=False
+        )
 
-        If persistence is enabled:
-        - Bool and null types are converted into `LiteralResult`.
-        - Other types are serialized, persisted to storage, and a reference is returned.
+    @sync_compatible
+    async def create_result(
+        self,
+        obj: R,
+        key: Optional[str] = None,
+        expiration: Optional[DateTime] = None,
+    ) -> Union[R, "BaseResult[R]"]:
+        """
+        Create a `PersistedResult` for the given object.
         """
         # Null objects are "cached" in memory at no cost
         should_cache_object = self.cache_result_in_memory or obj is None
 
-        if not self.persist_result:
-            return await UnpersistedResult.create(obj, cache_object=should_cache_object)
+        if key:
+
+            def key_fn():
+                return key
+
+            storage_key_fn = key_fn
+        else:
+            storage_key_fn = self.storage_key_fn
 
-        if type(obj) in LITERAL_TYPES:
-            return await LiteralResult.create(obj)
+        if self.result_storage is None:
+            self.result_storage = await get_default_result_storage()
 
         return await PersistedResult.create(
             obj,
-            storage_block=self.storage_block,
-            storage_block_id=self.storage_block_id,
-            storage_key_fn=self.storage_key_fn,
+            storage_block=self.result_storage,
+            storage_block_id=self.result_storage_block_id,
+            storage_key_fn=storage_key_fn,
             serializer=self.serializer,
             cache_object=should_cache_object,
+            expiration=expiration,
+            serialize_to_none=not self.persist_result,
         )
 
+    # TODO: These two methods need to find a new home
+
     @sync_compatible
     async def store_parameters(self, identifier: UUID, parameters: Dict[str, Any]):
-        assert (
-            self.storage_block_id is not None
-        ), "Unexpected storage block ID. Was it persisted?"
-        data = self.serializer.dumps(parameters)
-        blob = PersistedResultBlob(serializer=self.serializer, data=data)
-        await self.storage_block.write_path(
-            f"parameters/{identifier}", content=blob.to_bytes()
+        record = ResultRecord(
+            result=parameters,
+            metadata=ResultRecordMetadata(
+                serializer=self.serializer, storage_key=str(identifier)
+            ),
+        )
+        await self.result_storage.write_path(
+            f"parameters/{identifier}", content=record.serialize()
         )
 
     @sync_compatible
     async def read_parameters(self, identifier: UUID) -> Dict[str, Any]:
-        assert (
-            self.storage_block_id is not None
-        ), "Unexpected storage block ID. Was it persisted?"
-        blob = PersistedResultBlob.parse_raw(
-            await self.storage_block.read_path(f"parameters/{identifier}")
+        record = ResultRecord.deserialize(
+            await self.result_storage.read_path(f"parameters/{identifier}")
+        )
+        return record.result
+
+
+def get_current_result_store() -> ResultStore:
+    """
+    Get the current result store.
+    """
+    from prefect.context import get_run_context
+
+    try:
+        run_context = get_run_context()
+    except MissingContextError:
+        result_store = ResultStore()
+    else:
+        result_store = run_context.result_store
+    return result_store
+
+
+class ResultRecordMetadata(BaseModel):
+    """
+    Metadata for a result record.
+    """
+
+    storage_key: Optional[str] = Field(
+        default=None
+    )  # optional for backwards compatibility
+    expiration: Optional[DateTime] = Field(default=None)
+    serializer: Serializer = Field(default_factory=PickleSerializer)
+    prefect_version: str = Field(default=prefect.__version__)
+
+    def dump_bytes(self) -> bytes:
+        """
+        Serialize the metadata to bytes.
+
+        Returns:
+            bytes: the serialized metadata
+        """
+        return self.model_dump_json(serialize_as_any=True).encode()
+
+    @classmethod
+    def load_bytes(cls, data: bytes) -> "ResultRecordMetadata":
+        """
+        Deserialize metadata from bytes.
+
+        Args:
+            data: the serialized metadata
+
+        Returns:
+            ResultRecordMetadata: the deserialized metadata
+        """
+        return cls.model_validate_json(data)
+
+
+class ResultRecord(BaseModel, Generic[R]):
+    """
+    A record of a result.
+    """
+
+    metadata: ResultRecordMetadata
+    result: R
+
+    @property
+    def expiration(self) -> Optional[DateTime]:
+        return self.metadata.expiration
+
+    @property
+    def serializer(self) -> Serializer:
+        return self.metadata.serializer
+
+    def serialize_result(self) -> bytes:
+        try:
+            data = self.serializer.dumps(self.result)
+        except Exception as exc:
+            extra_info = (
+                'You can try a different serializer (e.g. result_serializer="json") '
+                "or disabling persistence (persist_result=False) for this flow or task."
+            )
+            # check if this is a known issue with cloudpickle and pydantic
+            # and add extra information to help the user recover
+
+            if (
+                isinstance(exc, TypeError)
+                and isinstance(self.result, BaseModel)
+                and str(exc).startswith("cannot pickle")
+            ):
+                try:
+                    from IPython import get_ipython
+
+                    if get_ipython() is not None:
+                        extra_info = inspect.cleandoc(
+                            """
+                            This is a known issue in Pydantic that prevents
+                            locally-defined (non-imported) models from being
+                            serialized by cloudpickle in IPython/Jupyter
+                            environments. Please see
+                            https://github.com/pydantic/pydantic/issues/8232 for
+                            more information. To fix the issue, either: (1) move
+                            your Pydantic class definition to an importable
+                            location, (2) use the JSON serializer for your flow
+                            or task (`result_serializer="json"`), or (3)
+                            disable result persistence for your flow or task
+                            (`persist_result=False`).
+                            """
+                        ).replace("\n", " ")
+                except ImportError:
+                    pass
+            raise SerializationError(
+                f"Failed to serialize object of type {type(self.result).__name__!r} with "
+                f"serializer {self.serializer.type!r}. {extra_info}"
+            ) from exc
+
+        return data
+
+    @model_validator(mode="before")
+    @classmethod
+    def coerce_old_format(cls, value: Any):
+        if isinstance(value, dict):
+            if "data" in value:
+                value["result"] = value.pop("data")
+            if "metadata" not in value:
+                value["metadata"] = {}
+            if "expiration" in value:
+                value["metadata"]["expiration"] = value.pop("expiration")
+            if "serializer" in value:
+                value["metadata"]["serializer"] = value.pop("serializer")
+            if "prefect_version" in value:
+                value["metadata"]["prefect_version"] = value.pop("prefect_version")
+        return value
+
+    def serialize_metadata(self) -> bytes:
+        return self.metadata.dump_bytes()
+
+    def serialize(
+        self,
+    ) -> bytes:
+        """
+        Serialize the record to bytes.
+
+        Returns:
+            bytes: the serialized record
+
+        """
+        return (
+            self.model_copy(update={"result": self.serialize_result()})
+            .model_dump_json(serialize_as_any=True)
+            .encode()
+        )
+
+    @classmethod
+    def deserialize(cls, data: bytes) -> "ResultRecord[R]":
+        """
+        Deserialize a record from bytes.
+
+        Args:
+            data: the serialized record
+
+        Returns:
+            ResultRecord: the deserialized record
+        """
+        instance = cls.model_validate_json(data)
+        if isinstance(instance.result, bytes):
+            instance.result = instance.serializer.loads(instance.result)
+        elif isinstance(instance.result, str):
+            instance.result = instance.serializer.loads(instance.result.encode())
+        return instance
+
+    @classmethod
+    def deserialize_from_result_and_metadata(
+        cls, result: bytes, metadata: bytes
+    ) -> "ResultRecord[R]":
+        """
+        Deserialize a record from separate result and metadata bytes.
+
+        Args:
+            result: the result
+            metadata: the serialized metadata
+
+        Returns:
+            ResultRecord: the deserialized record
+        """
+        result_record_metadata = ResultRecordMetadata.load_bytes(metadata)
+        return cls(
+            metadata=result_record_metadata,
+            result=result_record_metadata.serializer.loads(result),
         )
-        return self.serializer.loads(blob.data)
 
 
 @register_base_type
-class BaseResult(pydantic.BaseModel, abc.ABC, Generic[R]):
+class BaseResult(BaseModel, abc.ABC, Generic[R]):
+    model_config = ConfigDict(extra="forbid")
     type: str
-    artifact_type: Optional[str]
-    artifact_description: Optional[str]
 
     def __init__(self, **data: Any) -> None:
         type_string = get_dispatch_key(self) if type(self) != BaseResult else "__base__"
@@ -497,12 +628,12 @@ class BaseResult(pydantic.BaseModel, abc.ABC, Generic[R]):
             try:
                 subcls = lookup_type(cls, dispatch_key=kwargs["type"])
             except KeyError as exc:
-                raise pydantic.ValidationError(errors=[exc], model=cls)
+                raise ValidationError(errors=[exc], model=cls)
             return super().__new__(subcls)
         else:
             return super().__new__(cls)
 
-    _cache: Any = pydantic.PrivateAttr(NotSet)
+    _cache: Any = PrivateAttr(NotSet)
 
     def _cache_object(self, obj: Any) -> None:
         self._cache = obj
@@ -524,79 +655,10 @@ class BaseResult(pydantic.BaseModel, abc.ABC, Generic[R]):
     ) -> "BaseResult[R]":
         ...
 
-    class Config:
-        extra = "forbid"
-
     @classmethod
     def __dispatch_key__(cls, **kwargs):
-        return cls.__fields__.get("type").get_default()
-
-
-class UnpersistedResult(BaseResult):
-    """
-    Result type for results that are not persisted outside of local memory.
-    """
-
-    type = "unpersisted"
-
-    @sync_compatible
-    async def get(self) -> R:
-        if self.has_cached_object():
-            return self._cache
-
-        raise MissingResult("The result was not persisted and is no longer available.")
-
-    @classmethod
-    @sync_compatible
-    async def create(
-        cls: "Type[UnpersistedResult]",
-        obj: R,
-        cache_object: bool = True,
-    ) -> "UnpersistedResult[R]":
-        description = f"Unpersisted result of type `{type(obj).__name__}`"
-        result = cls(
-            artifact_type="result",
-            artifact_description=description,
-        )
-        # Only store the object in local memory, it will not be sent to the API
-        if cache_object:
-            result._cache_object(obj)
-        return result
-
-
-class LiteralResult(BaseResult):
-    """
-    Result type for literal values like `None`, `True`, `False`.
-
-    These values are stored inline and JSON serialized when sent to the Prefect API.
-    They are not persisted to external result storage.
-    """
-
-    type = "literal"
-    value: Any
-
-    def has_cached_object(self) -> bool:
-        # This result type always has the object cached in memory
-        return True
-
-    @sync_compatible
-    async def get(self) -> R:
-        return self.value
-
-    @classmethod
-    @sync_compatible
-    async def create(
-        cls: "Type[LiteralResult]",
-        obj: R,
-    ) -> "LiteralResult[R]":
-        if type(obj) not in LITERAL_TYPES:
-            raise TypeError(
-                f"Unsupported type {type(obj).__name__!r} for result literal. Expected"
-                f" one of: {', '.join(type_.__name__ for type_ in LITERAL_TYPES)}"
-            )
-
-        description = f"Result with value `{obj}` persisted to Prefect."
-        return cls(value=obj, artifact_type="result", artifact_description=description)
+        default = cls.model_fields.get("type").get_default()
+        return cls.__name__ if isinstance(default, PydanticUndefinedType) else default
 
 
 class PersistedResult(BaseResult):
@@ -604,47 +666,75 @@ class PersistedResult(BaseResult):
     Result type which stores a reference to a persisted result.
 
     When created, the user's object is serialized and stored. The format for the content
-    is defined by `PersistedResultBlob`. This reference contains metadata necessary for retrieval
+    is defined by `ResultRecord`. This reference contains metadata necessary for retrieval
     of the object, such as a reference to the storage block and the key where the
     content was written.
     """
 
-    type = "reference"
+    type: str = "reference"
 
     serializer_type: str
-    storage_block_id: uuid.UUID
     storage_key: str
+    storage_block_id: Optional[uuid.UUID] = None
+    expiration: Optional[DateTime] = None
+    serialize_to_none: bool = False
+
+    _persisted: bool = PrivateAttr(default=False)
+    _should_cache_object: bool = PrivateAttr(default=True)
+    _storage_block: WritableFileSystem = PrivateAttr(default=None)
+    _serializer: Serializer = PrivateAttr(default=None)
+
+    @model_serializer(mode="wrap")
+    def serialize_model(self, handler, info):
+        if self.serialize_to_none:
+            return None
+        return handler(self, info)
+
+    def _cache_object(
+        self,
+        obj: Any,
+        storage_block: WritableFileSystem = None,
+        serializer: Serializer = None,
+    ) -> None:
+        self._cache = obj
+        self._storage_block = storage_block
+        self._serializer = serializer
 
-    _should_cache_object: bool = pydantic.PrivateAttr(default=True)
+    @inject_client
+    async def _get_storage_block(self, client: "PrefectClient") -> WritableFileSystem:
+        if self._storage_block is not None:
+            return self._storage_block
+        elif self.storage_block_id is not None:
+            block_document = await client.read_block_document(self.storage_block_id)
+            self._storage_block = Block._from_block_document(block_document)
+        else:
+            self._storage_block = await get_default_result_storage()
+        return self._storage_block
 
     @sync_compatible
     @inject_client
-    async def get(self, client: "PrefectClient") -> R:
+    async def get(
+        self, ignore_cache: bool = False, client: "PrefectClient" = None
+    ) -> R:
         """
         Retrieve the data and deserialize it into the original object.
         """
-
-        if self.has_cached_object():
+        if self.has_cached_object() and not ignore_cache:
             return self._cache
 
-        blob = await self._read_blob(client=client)
-        obj = blob.serializer.loads(blob.data)
+        result_store_kwargs = {}
+        if self._serializer:
+            result_store_kwargs["serializer"] = resolve_serializer(self._serializer)
+        storage_block = await self._get_storage_block(client=client)
+        result_store = ResultStore(result_storage=storage_block, **result_store_kwargs)
+
+        record = await result_store.aread(self.storage_key)
+        self.expiration = record.expiration
 
         if self._should_cache_object:
-            self._cache_object(obj)
+            self._cache_object(record.result)
 
-        return obj
-
-    @inject_client
-    async def _read_blob(self, client: "PrefectClient") -> "PersistedResultBlob":
-        assert (
-            self.storage_block_id is not None
-        ), "Unexpected storage block ID. Was it persisted?"
-        block_document = await client.read_block_document(self.storage_block_id)
-        storage_block: ReadableFileSystem = Block._from_block_document(block_document)
-        content = await storage_block.read_path(self.storage_key)
-        blob = PersistedResultBlob.parse_raw(content)
-        return blob
+        return record.result
 
     @staticmethod
     def _infer_path(storage_block, key) -> str:
@@ -658,16 +748,55 @@ class PersistedResult(BaseResult):
         if hasattr(storage_block, "_remote_file_system"):
             return storage_block._remote_file_system._resolve_path(key)
 
+    @sync_compatible
+    @inject_client
+    async def write(self, obj: R = NotSet, client: "PrefectClient" = None) -> None:
+        """
+        Write the result to the storage block.
+        """
+
+        if self._persisted or self.serialize_to_none:
+            # don't double write or overwrite
+            return
+
+        # load objects from a cache
+
+        # first the object itself
+        if obj is NotSet and not self.has_cached_object():
+            raise ValueError("Cannot write a result that has no object cached.")
+        obj = obj if obj is not NotSet else self._cache
+
+        # next, the storage block
+        storage_block = await self._get_storage_block(client=client)
+
+        # finally, the serializer
+        serializer = self._serializer
+        if serializer is None:
+            # this could error if the serializer requires kwargs
+            serializer = Serializer(type=self.serializer_type)
+
+        result_store = ResultStore(result_storage=storage_block, serializer=serializer)
+        await result_store.awrite(
+            obj=obj, key=self.storage_key, expiration=self.expiration
+        )
+
+        self._persisted = True
+
+        if not self._should_cache_object:
+            self._cache = NotSet
+
     @classmethod
     @sync_compatible
     async def create(
         cls: "Type[PersistedResult]",
         obj: R,
         storage_block: WritableFileSystem,
-        storage_block_id: uuid.UUID,
         storage_key_fn: Callable[[], str],
         serializer: Serializer,
+        storage_block_id: Optional[uuid.UUID] = None,
         cache_object: bool = True,
+        expiration: Optional[DateTime] = None,
+        serialize_to_none: bool = False,
     ) -> "PersistedResult[R]":
         """
         Create a new result reference from a user's object.
@@ -675,95 +804,39 @@ class PersistedResult(BaseResult):
         The object will be serialized and written to the storage block under a unique
         key. It will then be cached on the returned result.
         """
-        assert (
-            storage_block_id is not None
-        ), "Unexpected storage block ID. Was it persisted?"
-        data = serializer.dumps(obj)
-        blob = PersistedResultBlob(serializer=serializer, data=data)
-
         key = storage_key_fn()
         if not isinstance(key, str):
             raise TypeError(
                 f"Expected type 'str' for result storage key; got value {key!r}"
             )
-
-        await storage_block.write_path(key, content=blob.to_bytes())
-
-        description = f"Result of type `{type(obj).__name__}`"
         uri = cls._infer_path(storage_block, key)
-        if uri:
-            if isinstance(storage_block, LocalFileSystem):
-                description += f" persisted to: `{uri}`"
-            else:
-                description += f" persisted to [{uri}]({uri})."
-        else:
-            description += f" persisted with storage block `{storage_block_id}`."
+
+        # in this case we store an absolute path
+        if storage_block_id is None and uri is not None:
+            key = str(uri)
 
         result = cls(
             serializer_type=serializer.type,
             storage_block_id=storage_block_id,
             storage_key=key,
-            artifact_type="result",
-            artifact_description=description,
+            expiration=expiration,
+            serialize_to_none=serialize_to_none,
         )
 
-        if cache_object:
-            # Attach the object to the result so it's available without deserialization
-            result._cache_object(obj)
-
         object.__setattr__(result, "_should_cache_object", cache_object)
+        # we must cache temporarily to allow for writing later
+        # the cache will be removed on write
+        result._cache_object(obj, storage_block=storage_block, serializer=serializer)
 
         return result
 
-
-class PersistedResultBlob(pydantic.BaseModel):
-    """
-    The format of the content stored by a persisted result.
-
-    Typically, this is written to a file as bytes.
-    """
-
-    serializer: Serializer
-    data: bytes
-    prefect_version: str = pydantic.Field(default=prefect.__version__)
-
-    def to_bytes(self) -> bytes:
-        return self.json().encode()
-
-
-class UnknownResult(BaseResult):
-    """
-    Result type for unknown results. Typically used to represent the result
-    of tasks that were forced from a failure state into a completed state.
-
-    The value for this result is always None and is not persisted to external
-    result storage, but orchestration treats the result the same as persisted
-    results when determining orchestration rules, such as whether to rerun a
-    completed task.
-    """
-
-    type = "unknown"
-    value: None
-
-    def has_cached_object(self) -> bool:
-        # This result type always has the object cached in memory
-        return True
-
-    @sync_compatible
-    async def get(self) -> R:
-        return self.value
-
-    @classmethod
-    @sync_compatible
-    async def create(
-        cls: "Type[UnknownResult]",
-        obj: R = None,
-    ) -> "UnknownResult[R]":
-        if obj is not None:
-            raise TypeError(
-                f"Unsupported type {type(obj).__name__!r} for unknown result. "
-                "Only None is supported."
-            )
-
-        description = "Unknown result persisted to Prefect."
-        return cls(value=obj, artifact_type="result", artifact_description=description)
+    def __eq__(self, other):
+        if not isinstance(other, PersistedResult):
+            return False
+        return (
+            self.type == other.type
+            and self.serializer_type == other.serializer_type
+            and self.storage_key == other.storage_key
+            and self.storage_block_id == other.storage_block_id
+            and self.expiration == other.expiration
+        )