Add dir() support for ProxyObject via remote introspection

Implements __dir__() on ProxyObject to enable runtime introspection
of remote objects. This allows users to call dir() on proxy objects
to discover available attributes and methods.

Key changes:
- Added get_attributes() method to ScriptSyntax interface
- PythonSyntax: Returns dir(obj) - delegates to object's __dir__
- GroovySyntax: Returns methods and properties from metaClass
- ProxyObject.__dir__(): Executes get_attributes() script on worker
  and returns the result

Implementation notes:
- No caching - each dir() call performs a round-trip to the worker
- Returns all attributes (including private ones) as determined by
  the remote object's own dir() implementation
- Works for both Python and Groovy workers

Test added:
- test_proxy_dir: Verifies dir() works on custom classes and
  built-in objects like datetime

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: ctrueden

src/appose/syntax.py

@@ -108,6 +108,21 @@ def invoke_method(
         """
         ...
 
+    @abstractmethod
+    def get_attributes(self, object_var_name: str) -> str:
+        """
+        Generate a script expression to retrieve the list of attributes of an object.
+
+        This is used by proxy objects to implement __dir__() for runtime introspection.
+
+        Args:
+            object_var_name: The name of the variable referencing the object.
+
+        Returns:
+            A script expression that evaluates to a list of attribute names.
+        """
+        ...
+
 
 class PythonSyntax(ScriptSyntax):
     """
@@ -139,6 +154,11 @@ def invoke_method(
         # Python method invocation: object.method(arg0, arg1, ...)
         return f"{object_var_name}.{method_name}({', '.join(arg_var_names)})"
 
+    def get_attributes(self, object_var_name: str) -> str:
+        # Return all attributes from dir(), including private ones.
+        # Let the object's __dir__ implementation decide what to expose.
+        return f"dir({object_var_name})"
+
 
 class GroovySyntax(ScriptSyntax):
     """
@@ -171,6 +191,11 @@ def invoke_method(
         # Groovy method invocation: object.method(arg0, arg1, ...)
         return f"{object_var_name}.{method_name}({', '.join(arg_var_names)})"
 
+    def get_attributes(self, object_var_name: str) -> str:
+        # Return all method names and property names from the object's metaclass.
+        # Groovy's metaClass provides runtime introspection.
+        return f"({object_var_name}.metaClass.methods*.name + {object_var_name}.metaClass.properties*.name).unique()"
+
 
 # All known script syntax implementations.
 _SYNTAXES: list[ScriptSyntax] = [

src/appose/util/proxy.py

@@ -127,4 +127,16 @@ def __call__(self, *args):
             except Exception as e:
                 raise RuntimeError(str(e)) from e
 
+        def __dir__(self):
+            # Query the remote object for its attributes via introspection.
+            syntax.validate(self._service)
+            script = self._service._syntax.get_attributes(self._var)
+
+            try:
+                task = self._service.task(script, queue=self._queue)
+                task.wait_for()
+                return task.result()
+            except Exception as e:
+                raise RuntimeError(str(e)) from e
+
     return ProxyObject(service, var, queue)  # type: ignore

tests/test_syntax.py

@@ -277,3 +277,53 @@ def __call__(self, x):
 
         # Access a field on the callable object
         assert callable_obj.offset == 100
+
+
+def test_proxy_dir():
+    """Test that dir() works on proxy objects."""
+    env = appose.system()
+    with env.python() as service:
+        maybe_debug(service)
+
+        # Create a custom class with known attributes
+        obj = service.task("""
+class TestClass:
+    def __init__(self):
+        self.field1 = 42
+        self.field2 = "hello"
+
+    def method1(self):
+        return "method1"
+
+    def method2(self, x):
+        return x * 2
+
+TestClass()
+""").wait_for().result()
+
+        # Get dir() output
+        attrs = dir(obj)
+
+        # Should be a list
+        assert isinstance(attrs, list)
+
+        # Should contain our custom attributes
+        assert "field1" in attrs
+        assert "field2" in attrs
+        assert "method1" in attrs
+        assert "method2" in attrs
+
+        # Should also contain standard object attributes
+        assert "__init__" in attrs
+        assert "__class__" in attrs
+
+        # Test with a built-in object (datetime)
+        dt = service.task("import datetime\ndatetime.datetime(2024, 1, 15)").wait_for().result()
+        dt_attrs = dir(dt)
+
+        assert isinstance(dt_attrs, list)
+        assert "year" in dt_attrs
+        assert "month" in dt_attrs
+        assert "day" in dt_attrs
+        assert "isoformat" in dt_attrs
+        assert "replace" in dt_attrs