groundhog-hpc 0.5.5__py3-none-any.whl → 0.5.7__py3-none-any.whl

groundhog_hpc/configuration/resolver.py

@@ -19,6 +19,7 @@ PEP 723 metadata sets sharable defaults, decorators customize per-function,
 and call-time overrides allow runtime changes.
 """
 
+import logging
 from pathlib import Path
 from typing import Any
 
@@ -26,14 +27,16 @@ from groundhog_hpc.configuration.defaults import DEFAULT_USER_CONFIG
 from groundhog_hpc.configuration.models import EndpointConfig, EndpointVariant
 from groundhog_hpc.configuration.pep723 import read_pep723
 
+logger = logging.getLogger(__name__)
+
 
 def _merge_endpoint_configs(
     base_endpoint_config: dict, override_config: dict | None = None
 ) -> dict:
-    """Merge endpoint configurations, ensuring worker_init commands are combined.
+    """Merge endpoint configurations, ensuring worker_init and endpoint_setup commands are combined.
 
-    The worker_init field is special-cased: if both configs provide it, they are
-    concatenated with the base's worker_init executed first, followed by the override's.
+    The worker_init and endpoint_setup fields are special-cased: if both configs provide them, they are
+    concatenated with the base's commands executed first, followed by the override's.
     All other fields from override_config simply replace fields from base_endpoint_config.
 
     Args:
@@ -44,10 +47,10 @@ def _merge_endpoint_configs(
         A new merged configuration dict
 
     Example:
-        >>> base = {"worker_init": "pip install uv"}
-        >>> override = {"worker_init": "module load gcc", "cores": 4}
+        >>> base = {"worker_init": "pip install uv", "endpoint_setup": "module load gcc"}
+        >>> override = {"worker_init": "module load python", "endpoint_setup": "module load cuda", "cores": 4}
         >>> _merge_endpoint_configs(base, override)
-        {'worker_init': 'pip install uv\\nmodule load gcc', 'cores': 4}
+        {'worker_init': 'pip install uv\\nmodule load python', 'endpoint_setup': 'module load gcc\\nmodule load cuda', 'cores': 4}
     """
     if not override_config:
         return base_endpoint_config.copy()
@@ -62,6 +65,13 @@ def _merge_endpoint_configs(
         override_init = override_config.pop("worker_init")
         merged["worker_init"] = f"{base_init.strip()}\n{override_init.strip()}\n"
 
+    # Special handling for endpoint_setup: prepend base to override
+    if "endpoint_setup" in override_config and "endpoint_setup" in base_endpoint_config:
+        base_setup = base_endpoint_config["endpoint_setup"]
+        # pop endpoint_setup so update doesn't clobber concatenated value
+        override_setup = override_config.pop("endpoint_setup")
+        merged["endpoint_setup"] = f"{base_setup.strip()}\n{override_setup.strip()}\n"
+
     merged.update(override_config)
     return merged
 
@@ -80,7 +90,7 @@ class ConfigResolver:
     5. Call-time config (.remote(user_endpoint_config={...}))
 
     Special handling:
-    - worker_init commands are concatenated (not replaced) across all layers
+    - worker_init and endpoint_setup commands are concatenated (not replaced) across all layers
     - endpoint field in PEP 723 config can override the endpoint UUID
     - Variants inherit from their base configuration
 
@@ -132,9 +142,12 @@ class ConfigResolver:
             ValidationError: If any config level has invalid fields (e.g., negative walltime)
         """
 
+        logger.debug(f"Resolving config for endpoint: {endpoint_name}")
+
         # Layer 1: Start with DEFAULT_USER_CONFIG
         config = DEFAULT_USER_CONFIG.copy()
         base_name, *variant_path = endpoint_name.split(".")
+        logger.debug(f"Starting with DEFAULT_USER_CONFIG: {config}")
 
         # Layer 2-3: walk base[.variant[.sub]] path hierarchically
         metadata: dict = self._load_pep723_metadata()
@@ -142,8 +155,11 @@ class ConfigResolver:
             metadata.get("tool", {}).get("hog", {}).get(base_name, {}).copy()
         )
         if base_variant:
+            logger.debug(f"Found base config for '{base_name}': {base_variant}")
             EndpointConfig.model_validate(base_variant)
             config["endpoint"] = base_variant.pop("endpoint")
+        else:
+            logger.debug(f"No PEP 723 config found for '{base_name}'")
 
         def _merge_variant_path(
             variant_names: list[str], current_variant: dict, accumulated_config: dict
@@ -164,12 +180,18 @@ class ConfigResolver:
                     + variant_path[: len(variant_path) - len(remaining_names)]
                 )
                 if next_variant is None:
+                    logger.error(f"Variant '{next_name}' not found in '{path_so_far}'")
                     raise ValueError(f"Variant {next_name} not found in {path_so_far}")
                 else:
+                    logger.error(
+                        f"Variant '{next_name}' in '{path_so_far}' is not a valid variant "
+                        f"(expected dict, got {type(next_variant).__name__})"
+                    )
                     raise ValueError(
                         f"Variant {next_name} in {path_so_far} is not a valid variant "
                         f"(expected dict, got {type(next_variant).__name__})"
                     )
+            logger.debug(f"Merging variant '{next_name}' config: {next_variant}")
             return _merge_variant_path(
                 remaining_names, next_variant, accumulated_config
             )
@@ -177,16 +199,22 @@ class ConfigResolver:
         config = _merge_variant_path(variant_path, base_variant, config)
 
         # Layer 4: Merge decorator config
+        if decorator_config:
+            logger.debug(f"Merging decorator config: {decorator_config}")
         config = _merge_endpoint_configs(config, decorator_config)
 
         # Layer 5: Call-time overrides
+        if call_time_config:
+            logger.debug(f"Merging call-time config: {call_time_config}")
         config = _merge_endpoint_configs(config, call_time_config)
 
         # Layer 5 1/2: we want to ensure uv is installed *after* any user
         # worker_init, e.g. activating a conda env, which might impact the
         # templated shell command's ability to `uv.find_uv_bin()`
-        uv_init_config = {"worker_init": "pip show -qq uv || pip install uv"}
+        uv_init_config = {"worker_init": "pip show -qq uv || pip install uv || true"}
         config = _merge_endpoint_configs(config, uv_init_config)
+
+        logger.debug(f"Final resolved config: {config}")
         return config
 
     def _load_pep723_metadata(self) -> dict[str, Any]:

groundhog_hpc/console.py

@@ -173,7 +173,7 @@ def _get_status_display(
         display.append(")", style="dim")
 
     display.append(" | ", style="dim")
-    display.append(spinner.render(current_time))
+    display.append(spinner.render(current_time))  # type: ignore[arg-type]
 
     return display
 

groundhog_hpc/decorators.py

@@ -7,21 +7,24 @@ orchestration.
 
 import functools
 import inspect
-import warnings
+import logging
 from types import FunctionType
 from typing import Any, Callable
 
 from groundhog_hpc.function import Function, Method
 from groundhog_hpc.harness import Harness
 
+logger = logging.getLogger(__name__)
+
 
 def harness() -> Callable[[FunctionType], Harness]:
     """Decorator to mark a function as a local orchestrator harness.
 
     Harness functions:
+
     - Must be called via the CLI: `hog run script.py harness_name`
     - Cannot accept any arguments
-    - Can call .remote() or .submit() on @hog.function decorated functions
+    - Can call `.remote()` or `.submit()` on `@hog.function`-decorated functions
 
     Returns:
         A decorator function that wraps the harness
@@ -45,28 +48,29 @@ def harness() -> Callable[[FunctionType], Harness]:
 
 def function(
     endpoint: str | None = None,
-    walltime: int | None = None,
     **user_endpoint_config: Any,
 ) -> Callable[[FunctionType], Function]:
     """Decorator to mark a function for remote execution on Globus Compute.
 
     Decorated functions can be:
-    - Called locally: func(args)
-    - Called remotely (blocking): func.remote(args)
-    - Submitted asynchronously: func.submit(args)
+
+    - Called locally: `func(args)`
+    - Called remotely (blocking): `func.remote(args)`
+    - Submitted asynchronously: `func.submit(args)`
+    - Called locally in an isolated environment: `func.local(args)`
 
     Args:
-        endpoint: Globus Compute endpoint UUID
-        walltime: Maximum execution time in seconds
+        endpoint: Globus Compute endpoint UUID or named endpoint from
+            `[tool.hog.<name>]` PEP 723 metadata
         **user_endpoint_config: Options to pass through to the Executor as
-            user_endpoint_config (e.g. account, partition, etc)
+            user_endpoint_config (e.g. account, partition, walltime, etc)
 
     Returns:
         A decorator function that wraps the function as a Function instance
 
     Example:
         ```python
-        @hog.function(endpoint="my-remote-endpoint-uuid", walltime=300)
+        @hog.function(endpoint="my-remote-endpoint-uuid", account='my-account')
         def train_model(data):
             # This runs on the remote HPC cluster
             model = train(data)
@@ -81,7 +85,7 @@ def function(
     """
 
     def decorator(func: FunctionType) -> Function:
-        wrapper = Function(func, endpoint, walltime, **user_endpoint_config)
+        wrapper = Function(func, endpoint, **user_endpoint_config)
         functools.update_wrapper(wrapper, func)
         return wrapper
 
@@ -90,24 +94,24 @@ def function(
 
 def method(
     endpoint: str | None = None,
-    walltime: int | None = None,
     **user_endpoint_config: Any,
 ) -> Callable[[FunctionType], Method]:
     """Decorator to mark a class method for remote execution on Globus Compute.
 
-    Similar to @hog.function() but designed for use as class methods. Provides
-    staticmethod-like semantics - the decorated method does not receive self.
+    Analogous to `@hog.function()` but for use with class methods. Provides
+    staticmethod-like semantics - the decorated method does not receive self or cls.
 
     Decorated methods can be:
-    - Called locally: MyClass.method(args) or obj.method(args)
-    - Called remotely (blocking): obj.method.remote(args)
-    - Submitted asynchronously: obj.method.submit(args)
+
+    - Called locally: `MyClass.method(args)` or `obj.method(args)`
+    - Called remotely (blocking): `MyClass.method.remote(args)`
+    - Submitted asynchronously: `MyClass.method.submit(args)`
+    - Called locally in an isolated environment: `MyClass.method.local(args)`
 
     Args:
         endpoint: Globus Compute endpoint UUID
-        walltime: Maximum execution time in seconds
         **user_endpoint_config: Options to pass through to the Executor as
-            user_endpoint_config (e.g. account, partition, etc)
+            user_endpoint_config (e.g. account, partition, walltime, etc)
 
     Returns:
         A decorator function that wraps the function as a Method instance
@@ -129,15 +133,13 @@ def method(
         sig = inspect.signature(func)
         params = list(sig.parameters.keys())
         if params and params[0] in ("self", "cls"):
-            warnings.warn(
+            logger.warning(
                 f"Method '{func.__name__}' has first parameter '{params[0]}', "
                 f"but @hog.method provides staticmethod-like semantics and will not "
-                f"pass the instance or class. Consider removing '{params[0]}' from the signature.",
-                UserWarning,
-                stacklevel=2,
+                f"pass the instance or class. Consider removing '{params[0]}' from the signature."
             )
 
-        wrapper = Method(func, endpoint, walltime, **user_endpoint_config)
+        wrapper = Method(func, endpoint, **user_endpoint_config)
         functools.update_wrapper(wrapper, func)
         return wrapper
 

groundhog_hpc/function.py

@@ -10,6 +10,7 @@ as defaults but overridden when calling .remote() or .submit().
 """
 
 import inspect
+import logging
 import os
 import sys
 import tempfile
@@ -30,6 +31,8 @@ from groundhog_hpc.future import GroundhogFuture
 from groundhog_hpc.serialization import deserialize_stdout, serialize
 from groundhog_hpc.utils import prefix_output
 
+logger = logging.getLogger(__name__)
+
 if TYPE_CHECKING:
     import globus_compute_sdk
 
@@ -44,22 +47,22 @@ class Function:
     """Wrapper that enables a Python function to be executed remotely on Globus Compute.
 
     Decorated functions can be called in four ways:
-    1. Direct call: func(*args) - executes locally (regular python call)
-    2. Remote call: func.remote(*args) - executes remotely and blocks until complete
-    3. Async submit: func.submit(*args) - executes remotely and returns a Future
-    4. Local subprocess: func.local(*args) - executes locally in a separate process
+
+    1. Direct call: `func(*args)` - executes locally (regular python call)
+    2. Remote call: `func.remote(*args)` - executes remotely and blocks until complete
+    3. Async submit: `func.submit(*args)` - executes remotely and returns a GroundhogFuture
+    4. Local subprocess: `func.local(*args)` - executes locally in a separate process
 
     Attributes:
-        endpoint: Default Globus Compute endpoint UUID or None to use resolved config
-        walltime: Default walltime in seconds for remote execution or None to use resolved config
-        default_user_endpoint_config: Default endpoint configuration (e.g., worker_init)
+        endpoint: Default Globus Compute endpoint UUID or named endpoint from
+            `[tool.hog.<name>]` PEP 723 metadata, or None to use resolved config
+        default_user_endpoint_config: Default endpoint configuration (e.g., worker_init, walltime)
     """
 
     def __init__(
         self,
         func: FunctionType,
         endpoint: str | None = None,
-        walltime: int | None = None,
         **user_endpoint_config: Any,
     ) -> None:
         """Initialize a Function wrapper.
@@ -67,19 +70,22 @@ class Function:
         Args:
             func: The Python function to wrap
             endpoint: Globus Compute endpoint UUID or named endpoint from `[tool.hog.<name>]` PEP 723
-            walltime: Maximum execution time in seconds (can also be set in config)
             **user_endpoint_config: Additional endpoint configuration to pass to
-                Globus Compute Executor (e.g., worker_init commands)
+                Globus Compute Executor (e.g., worker_init commands, walltime)
         """
         self._script_path: str | None = None
         self.endpoint: str | None = endpoint
-        self.walltime: int | None = walltime
         self.default_user_endpoint_config: dict[str, Any] = user_endpoint_config
 
-        self._local_function: FunctionType = func
+        # ShellFunction walltime - always None here to prevent conflicts with a
+        # 'walltime' endpoint config, but the attribute exists as an escape
+        # hatch if users need to set it after the function's been created
+        self.walltime: int | float | None = None
+
+        self._wrapped_function: FunctionType = func
         self._config_resolver: ConfigResolver | None = None
 
-    def __call__(self, *args, **kwargs) -> Any:
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
         """Execute the function locally (not remotely).
 
         Args:
@@ -89,7 +95,7 @@ class Function:
         Returns:
             The result of the local function execution
         """
-        return self._local_function(*args, **kwargs)
+        return self._wrapped_function(*args, **kwargs)
 
     def _get_available_endpoints_from_pep723(self) -> list[str]:
         """Get list of endpoint names defined in PEP 723 [tool.hog.*] sections."""
@@ -103,7 +109,6 @@ class Function:
         self,
         *args: Any,
         endpoint: str | None = None,
-        walltime: int | None = None,
         user_endpoint_config: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> GroundhogFuture:
@@ -111,8 +116,8 @@ class Function:
 
         Args:
             *args: Positional arguments to pass to the function
-            endpoint: Globus Compute endpoint UUID (overrides decorator default)
-            walltime: Maximum execution time in seconds (overrides decorator default)
+            endpoint: Globus Compute endpoint UUID (or named endpoint from
+                `[tool.hog.<name>]` PEP 723 metadata). Replaces decorator default.
             user_endpoint_config: Endpoint configuration dict (merged with decorator default)
             **kwargs: Keyword arguments to pass to the function
 
@@ -125,21 +130,22 @@ class Function:
             PayloadTooLargeError: If serialized arguments exceed 10MB
         """
         # Check if module has been marked as safe for .remote() calls
-        module = sys.modules.get(self._local_function.__module__)
+        module = sys.modules.get(self._wrapped_function.__module__)
         if not getattr(module, "__groundhog_imported__", False):
+            logger.error(
+                f"Import safety check failed for module '{self._wrapped_function.__module__}'"
+            )
             raise ModuleImportError(
-                self._local_function.__name__, "submit", self._local_function.__module__
+                self._wrapped_function.__name__,
+                "submit",
+                self._wrapped_function.__module__,
             )
 
+        logger.debug(f"Preparing to submit function '{self.name}'")
         endpoint = endpoint or self.endpoint
 
         decorator_config = self.default_user_endpoint_config.copy()
-        if self.walltime is not None:
-            decorator_config["walltime"] = self.walltime
-
         call_time_config = user_endpoint_config.copy() if user_endpoint_config else {}
-        if walltime is not None:
-            call_time_config["walltime"] = walltime
 
         # merge all config sources
         config = self.config_resolver.resolve(
@@ -158,15 +164,22 @@ class Function:
             available_endpoints = self._get_available_endpoints_from_pep723()
             if available_endpoints:
                 endpoints_str = ", ".join(f"'{e}'" for e in available_endpoints)
+                logger.error(f"No endpoint specified. Available: {endpoints_str}")
                 raise ValueError(
                     f"No endpoint specified. Available endpoints found in config: {endpoints_str}. "
                     f"Call with endpoint=<name>, or specify a function default endpoint in decorator."
                 )
             else:
+                logger.error("No endpoint specified and none found in config")
                 raise ValueError("No endpoint specified")
 
+        logger.debug(
+            f"Serializing {len(args)} args and {len(kwargs)} kwargs for '{self.name}'"
+        )
         payload = serialize((args, kwargs), use_proxy=False, proxy_threshold_mb=None)
-        shell_function = script_to_submittable(self.script_path, self.name, payload)
+        shell_function = script_to_submittable(
+            self.script_path, self.name, payload, walltime=self.walltime
+        )
 
         future: GroundhogFuture = submit_to_executor(
             UUID(endpoint),
@@ -182,7 +195,6 @@ class Function:
         self,
         *args: Any,
         endpoint: str | None = None,
-        walltime: int | None = None,
         user_endpoint_config: dict[str, Any] | None = None,
         **kwargs: Any,
     ) -> Any:
@@ -193,8 +205,8 @@ class Function:
 
         Args:
             *args: Positional arguments to pass to the function
-            endpoint: Globus Compute endpoint UUID (overrides decorator default)
-            walltime: Maximum execution time in seconds (overrides decorator default)
+            endpoint: Globus Compute endpoint UUID (or named endpoint from
+                `[tool.hog.<name>]` PEP 723 metadata). Replaces decorator default.
             user_endpoint_config: Endpoint configuration dict (merged with decorator default)
             **kwargs: Keyword arguments to pass to the function
 
@@ -207,15 +219,17 @@ class Function:
             PayloadTooLargeError: If serialized arguments exceed 10MB
             RemoteExecutionError: If remote execution fails (non-zero exit code)
         """
+        logger.debug(f"Calling remote execution for '{self.name}'")
         future = self.submit(
             *args,
             endpoint=endpoint,
-            walltime=walltime,
             user_endpoint_config=user_endpoint_config,
             **kwargs,
         )
         display_task_status(future)
-        return future.result()
+        result = future.result()
+        logger.debug(f"Remote execution of '{self.name}' completed successfully")
+        return result
 
     def local(self, *args: Any, **kwargs: Any) -> Any:
         """Execute the function locally in an isolated subprocess.
@@ -233,12 +247,18 @@ class Function:
             LocalExecutionError: If local execution fails (non-zero exit code)
         """
         # Check if module has been marked as safe for .local() calls
-        module = sys.modules.get(self._local_function.__module__)
+        module = sys.modules.get(self._wrapped_function.__module__)
         if not getattr(module, "__groundhog_imported__", False):
+            logger.error(
+                f"Import safety check failed for module '{self._wrapped_function.__module__}'"
+            )
             raise ModuleImportError(
-                self._local_function.__name__, "local", self._local_function.__module__
+                self._wrapped_function.__name__,
+                "local",
+                self._wrapped_function.__module__,
             )
 
+        logger.debug(f"Executing function '{self.name}' in local subprocess")
         with prefix_output(prefix="[local]", prefix_color="blue"):
             # Create ShellFunction just like we do for remote execution
             payload = serialize((args, kwargs), proxy_threshold_mb=1.0)
@@ -254,6 +274,9 @@ class Function:
                 assert not isinstance(result, dict)
 
                 if result.returncode != 0:
+                    logger.error(
+                        f"Local subprocess failed with exit code {result.returncode}"
+                    )
                     if result.stderr:
                         print(result.stderr, file=sys.stderr)
                     if result.stdout:
@@ -266,12 +289,16 @@ class Function:
                 try:
                     user_stdout, deserialized_result = deserialize_stdout(result.stdout)
                 except DeserializationError as e:
+                    logger.error(f"Failed to deserialize local result: {e}")
                     if result.stderr:
                         print(result.stderr, file=sys.stderr)
                     if e.user_output:
                         print(e.user_output)
                     raise
                 else:
+                    logger.debug(
+                        f"Local execution of '{self.name}' completed successfully"
+                    )
                     if result.stderr:
                         print(result.stderr, file=sys.stderr)
                     if user_stdout:
@@ -297,7 +324,7 @@ class Function:
             return self._script_path
 
         try:
-            source_file = inspect.getfile(self._local_function)
+            source_file = inspect.getfile(self._wrapped_function)
             self._script_path = str(Path(source_file).resolve())
             return self._script_path
         except (TypeError, OSError) as e:
@@ -315,13 +342,13 @@ class Function:
 
     @property
     def name(self) -> str:
-        return self._local_function.__qualname__
+        return self._wrapped_function.__qualname__
 
 
 class Method(Function):
-    """Descriptor variant of Function for use as class methods.
+    """Minimal descriptor variant of Function for use as class methods.
 
-    Provides staticmethod-like semantics (no self) with remote execution.
+    Provides staticmethod-like semantics (no `self`/`cls`) with remote execution.
     """
 
     def __get__(self, obj, objtype=None):

groundhog_hpc/future.py

@@ -22,16 +22,16 @@ else:
 
 class GroundhogFuture(Future):
     """A Future that deserializes stdout for its .result(), but still allows
-    access to the raw ShellResult.
+    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)
+    but preserves access to the original `ShellResult` (with stdout, stderr, returncode)
     via the .shell_result property.
 
     Attributes:
         task_id: Globus Compute task ID (set when the future completes)
-        endpoint: UUID of the endpoint where the task was submitted
-        user_endpoint_config: Configuration dict used for the endpoint
+        endpoint: The endpoint where the task was submitted
+        user_endpoint_config: Resolved configuration dict used for the endpoint
         function_name: Name of the function being executed
     """
 
@@ -48,9 +48,9 @@ class GroundhogFuture(Future):
         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
+        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:
@@ -69,7 +69,7 @@ class GroundhogFuture(Future):
 
     @property
     def shell_result(self) -> ShellResult:
-        """Access the raw ShellResult with stdout, stderr, returncode.
+        """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
@@ -93,7 +93,45 @@ class GroundhogFuture(Future):
 
     @property
     def task_id(self) -> str | None:
-        return self._original_future.task_id
+        """The Globus Compute task ID for this future.
+
+        Returns the task ID from the underlying Globus Compute future, which may
+        not be populated immediately.
+        """
+        return self._original_future.task_id  # type: ignore[attr-defined]
+
+    @property
+    def endpoint(self) -> str | None:
+        """The endpoint where this task was submitted."""
+        return self._endpoint
+
+    @endpoint.setter
+    def endpoint(self, value: str | None) -> None:
+        self._endpoint = value
+
+    @property
+    def user_endpoint_config(self) -> dict[str, Any] | None:
+        """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`.
+        """
+        return self._user_endpoint_config
+
+    @user_endpoint_config.setter
+    def user_endpoint_config(self, value: dict[str, Any] | None) -> None:
+        self._user_endpoint_config = value
+
+    @property
+    def function_name(self) -> str | None:
+        """The name of the function being executed."""
+        return self._function_name
+
+    @function_name.setter
+    def function_name(self, value: str | None) -> None:
+        self._function_name = value
 
 
 def _truncate_payload_in_cmd(cmd: str, max_length: int = 100) -> str:
@@ -123,7 +161,7 @@ def _truncate_payload_in_cmd(cmd: str, max_length: int = 100) -> str:
 
 
 def _process_shell_result(shell_result: ShellResult) -> tuple[str | None, Any]:
-    """Process a ShellResult by checking for errors and deserializing the result payload.
+    """Process a `ShellResult` by checking for errors and deserializing the result payload.
 
     The stdout contains two parts separated by "__GROUNDHOG_RESULT__":
     1. User output (from the .stdout file) - returned as first element of tuple