GroundhogFuture

The GroundhogFuture class is a Future subclass that automatically deserializes results from remote execution while preserving access to raw shell execution metadata.

GroundhogFuture Class

GroundhogFuture(original_future)

Bases: Future

A Future that deserializes stdout for its .result(), but still allows access to the raw ShellResult.

This future automatically deserializes the payload when .result() is called, but preserves access to the original ShellResult (with stdout, stderr, returncode) via the .shell_result property.

Attributes:

Name	Type	Description
task_id	str | None	Globus Compute task ID (set when the future completes)
endpoint	str | None	The endpoint where the task was submitted
user_endpoint_config	dict[str, Any] | None	Resolved configuration dict used for the endpoint
function_name	str | None	Name of the function being executed

Wrap a Globus Compute future with automatic deserialization.

Parameters:

Name	Type	Description	Default
original_future	Future	The original Future returned by Globus Compute Executor	required

Source code in src/groundhog_hpc/future.py

def __init__(self, original_future: Future) -> None:
    """Wrap a Globus Compute future with automatic deserialization.

    Args:
        original_future: The original Future returned by Globus Compute Executor
    """
    super().__init__()
    self._original_future: Future = original_future
    self._shell_result: ShellResult | None = None
    self._task_id: str | None = None
    self._user_stdout: str | None = None

    # set after created in Function.submit, useful for invocation logs etc
    self._endpoint: str | None = None
    self._user_endpoint_config: dict[str, Any] | None = None
    self._function_name: str | None = None

    def callback(fut: Future) -> None:
        try:
            # Get and cache the ShellResult
            shell_result = fut.result()
            self._shell_result = shell_result

            # Process and deserialize
            user_stdout, deserialized_result = _process_shell_result(shell_result)
            self._user_stdout = user_stdout
            self.set_result(deserialized_result)
        except Exception as e:
            self.set_exception(e)

    original_future.add_done_callback(callback)

shell_result property

Access the raw Globus Compute ShellResult with stdout, stderr, returncode.

This property provides access to the underlying shell execution metadata, which can be useful for debugging, logging, or inspecting stderr output even when the execution succeeded.

user_stdout property

Access the parsed user stdout (separate from serialized result).

This is the stdout output from the user's code, not including the serialized result payload. Returns None if no user output was present.

task_id property

The Globus Compute task ID for this future.

Returns the task ID from the underlying Globus Compute future, which may not be populated immediately.

endpoint property writable

The endpoint where this task was submitted.

user_endpoint_config property writable

The endpoint configuration used for this task submission.

Set by Function.submit() when the task is created. Contains configuration like account, partition, walltime, etc. Useful for debugging, since this is the final resolved config that was actually passed to the Executor.

function_name property writable

The name of the function being executed.