feat: Add cancellation support for Spanner queries

[lmeyerov]

Summary

Add the ability to cancel in-flight Spanner queries when using graphistry.spanner().

Motivation

When integrating pygraphistry with systems that support background task cancellation (like GraphistryGPT), there's currently no way to cancel a running Spanner query. Long-running Spanner queries can block resources and should be interruptible.

Proposed API

Add an optional callback parameter that receives a cancel function:

def spanner(query, instance, database, on_cancel_ready=None):
    """
    Args:
        query: SQL query string
        instance: Spanner instance name
        database: Spanner database name
        on_cancel_ready: Optional callback that receives a cancel function.
                        Called before query execution starts.
    """
    client = get_spanner_client(instance, database)
    result_set = None
    
    def cancel():
        if result_set:
            result_set.close()
    
    if on_cancel_ready:
        on_cancel_ready(cancel)
    
    result_set = client.execute_sql(query)
    return result_set_to_dataframe(result_set)

Usage Example

import graphistry

def register_cancel(cancel_fn):
    # Store cancel_fn for later use (e.g., in a task manager)
    task_manager.register_canceler(cancel_fn)

df = graphistry.spanner(
    "SELECT * FROM large_table",
    instance="my-instance",
    database="my-db",
    on_cancel_ready=register_cancel
)

Implementation Notes

• Spanner's StreamedResultSet (from execute_sql()) supports .close() to stop streaming
• The callback pattern allows the caller to decide how to store/use the cancel function
• Need to handle the case where cancel is called before result_set is assigned

Related

• Sister issue: feat: Add cancellation support for Kusto queries #920 (Kusto cancellation support)
• This is part of a broader effort to add cancellation support across data source integrations in GraphistryGPT.