haive.core.persistence.utils
============================

.. py:module:: haive.core.persistence.utils

.. autoapi-nested-parse::

   Utility functions for the Haive persistence system.

   This module provides helper functions for working with checkpointers and their
   associated resources. It includes utilities for connection pool management,
   serialization/deserialization of metadata, and other common operations needed
   across different persistence implementations.

   The utilities are designed to be used by the persistence system internals and
   generally aren't intended to be used directly by application code. They provide
   consistent behavior across different checkpointer implementations and handle
   edge cases and error conditions gracefully.



Functions
---------

.. autoapisummary::

   haive.core.persistence.utils.deserialize_metadata
   haive.core.persistence.utils.ensure_async_pool_open
   haive.core.persistence.utils.ensure_pool_open
   haive.core.persistence.utils.register_thread
   haive.core.persistence.utils.register_thread_async
   haive.core.persistence.utils.serialize_metadata


Module Contents
---------------

.. py:function:: deserialize_metadata(metadata_str)

   Deserialize metadata from JSON string to dictionary.

   :param metadata_str: JSON string containing serialized metadata

   :returns: Deserialized metadata dictionary
   :rtype: Dict[str, Any]


.. py:function:: ensure_async_pool_open(checkpointer)
   :async:


   Ensure that an async PostgreSQL connection pool is properly opened.

   This asynchronous function checks if an async checkpointer has an associated
   connection pool and ensures that it's properly opened. It handles different
   async pool implementations and versions, checking appropriate attributes and
   calling the async open method if needed.

   The function is particularly important for async contexts, where proper
   connection management is critical for maintaining good performance and
   resource utilization. It prevents errors from closed or unopened pools
   in async code.

   :param checkpointer: The async checkpointer instance to check for a connection pool

   :returns:

             The opened async connection pool if one was found and
                 opened, None otherwise
   :rtype: Optional[Any]

   .. note::

      This function gracefully handles the case where the async PostgreSQL
      dependencies are not available, making it safe to call even if the
      async database modules are not installed.

   .. rubric:: Examples

   async def prepare_checkpointer(checkpointer):
       # Ensure the pool is open before using it
       pool = await ensure_async_pool_open(checkpointer)
       if pool:
           print("Pool is ready for use")
       # Continue with checkpointer operations...


.. py:function:: ensure_pool_open(checkpointer)

   Ensure that a PostgreSQL connection pool is properly opened.

   This function checks if a checkpointer has an associated connection pool
   and ensures that it's properly opened. It handles different pool
   implementations and versions, checking appropriate attributes and calling
   the open method if needed.

   The function is used to ensure that connection pools are ready for use
   before attempting database operations, preventing errors from closed
   or unopened pools.

   :param checkpointer: The checkpointer instance to check for a connection pool

   :returns:

             The opened connection pool if one was found and opened,
                 None otherwise
   :rtype: Optional[Any]

   .. note::

      This function gracefully handles the case where psycopg_pool is not
      available, making it safe to call even if the PostgreSQL dependencies
      are not installed.


.. py:function:: register_thread(checkpointer, thread_id, metadata = None)

   Register a thread in the PostgreSQL database if needed.


.. py:function:: register_thread_async(checkpointer, thread_id, metadata = None)
   :async:


   Register a thread in the PostgreSQL database asynchronously.


.. py:function:: serialize_metadata(metadata)

   Serialize metadata dictionary to JSON string.

   :param metadata: Dictionary containing metadata to serialize

   :returns: JSON string representation of the metadata
   :rtype: str