Document that we now give foreign objects a Python class corresponding to their interop traits

Author: eregon

CHANGELOG.md

@@ -7,12 +7,17 @@ language runtime. The main focus is on user-observable behavior of the engine.
 * Updated developer metadata of Maven artifacts.
 * Added gradle plugin for polyglot embedding of Python packages into Java.
 * When calling a method on a foreign object in Python code, Python methods are now prioritized over foreign members.
+* Added `polyglot.register_interop_type` and `@polyglot.interop_type` to define custom Python methods for a given foreign class/type. See [the documentation](https://github.com/oracle/graalpython/blob/master/docs/user/Interoperability.md#the-interoperability-extension-api) for more information.
+* Foreign objects are now given a Python class corresponding to their interop traits.
+** Foreign lists now inherit from Python `list`, foreign dictionaries from `dict`, foreign iterators from `iterator`, foreign exceptions from `BaseException` and foreign none/null from `NoneType`.
+** This means all Python methods of these types are available on the corresponding foreign objects, which behave as close as possible as if they were Python objects.
+** See [the documentation](https://github.com/oracle/graalpython/blob/master/docs/user/Interoperability.md#interacting-with-foreign-objects-from-python-scripts) for more information.
 
 ## Version 24.1.0
 * GraalPy is now considered stable for pure Python workloads. While many workloads involving native extension modules work, we continue to consider them experimental. You can use the command-line option `--python.WarnExperimentalFeatures` to enable warnings for such modules at runtime. In Java embeddings the warnings are enabled by default and you can suppress them by setting the context option 'python.WarnExperimentalFeatures' to 'false'.
 * Update to Python 3.11.7.
 * We now provide intrinsified `_pickle` module also in the community version.
-* `polyglot.eval` now raises more meaningful exceptions. Unavaliable languages raise `ValueError`. Exceptions from the polyglot language are raised directly as interop objects (typed as `polyglot.ForeignException`). The shortcut for executing python files without specifying language has been removed, use regular `eval` for executing Python code.
+* `polyglot.eval` now raises more meaningful exceptions. Unavailable languages raise `ValueError`. Exceptions from the polyglot language are raised directly as interop objects (typed as `polyglot.ForeignException`). The shortcut for executing python files without specifying language has been removed, use regular `eval` for executing Python code.
 * In Jython emulation mode we now magically fall back to calling Java getters or setters when using Python attribute access for non-visible properties. This can help migrating away from Jython if you relied on this behavior. 
 * The option `python.EmulateJython` to enable Jython emulation is now marked as stable, and can thus be relied upon in production.
 * Fixed parsing of pyvenv.cfg according to PEP 405, which is required to use [uv](https://github.com/astral-sh/uv?tab=readme-ov-file#uv) generated venvs with GraalPy.
@@ -33,7 +38,7 @@ language runtime. The main focus is on user-observable behavior of the engine.
 * Add option `python.InitialLocale` to change the default locale. If not set, then Java Locale#getDefault is used.
 * `multiprocessing` module now uses the `spawn` method (creates new processes) by default. The formerly default method that uses threads and multiple Truffle contexts can be selected using `multiprocessing.set_start_method('graalpy')`.
 * `polyglot` module: add API to redefine Truffle interop messages for external / user defined types. For more details see [The Truffle Interoperability Extension API](docs/user/Interoperability.md).
-*Adding integration with jBang (https://www.jbang.dev/)
+* Adding integration with jBang (https://www.jbang.dev/)
 ** running example via `jbang hello@oracle/graalpython` or `jbang hello@oracle/graalpython "print(1*4)"`
 ** creating new script via: `jbang init --template=graalpy@oracle/graalpython myscript.java`
 ** creating new script with local maven repo for testing: `jbang init --template=graalpy_local_repo@oracle/graalpython -Dpath_to_local_repo=/absolute/path/to/local/maven/repository myscript.java'

docs/user/Interoperability.md

@@ -42,7 +42,7 @@ In addition to the `type` built-in method, the `java` module exposes the followi
 
 Built-in                 | Specification
 ---                      | ---
-`instanceof(obj, class)` | returns `True` if `obj` is an instance of `class` (`class` must be a foreign object class)
+`instanceof(obj, class)` | returns `True` if `obj` is an instance of `class` (`class` must be a foreign object class)
 `is_function(obj)`       | returns `True` if `obj` is a Java host language function wrapped using interop
 `is_object(obj)`         | returns `True` if `obj` if the argument is Java host language object wrapped using interop
 `is_symbol(obj)`         | returns `True` if `obj` if the argument is a Java host symbol, representing the constructor and static members of a Java class, as obtained by `java.type`
@@ -59,6 +59,43 @@ assert java.instanceof(my_list, ArrayList)
 
 See [Polyglot Programming](https://github.com/oracle/graal/blob/master/docs/reference-manual/polyglot-programming.md) and [Embed Languages](https://github.com/oracle/graal/blob/master/docs/reference-manual/embedding/embed-languages.md) for more information about interoperability with other programming languages.
 
+## Interacting with foreign objects from Python scripts
+
+Foreign objects are given a Python class corresponding to their interop traits:
+
+```python
+from java.util import ArrayList, HashMap
+type(ArrayList()).mro() # => [<class 'polyglot.ForeignList'>, <class 'list'>, <class 'foreign'>, <class 'object'>]
+type(HashMap()).mro() # => [<class 'polyglot.ForeignDict'>, <class 'dict'>, <class 'foreign'>, <class 'object'>]
+```
+
+This means all Python methods of these types are available on the corresponding foreign objects, which behave as close as possible as if they were Python objects:
+
+```python
+from java.util import ArrayList, HashMap
+l = ArrayList()
+l.append(1) # l: [1]
+l.extend([2, 3]) # l: [1, 2, 3]
+l.add(4) # l: [1, 2, 3, 4] # we can still call Java methods, this is calling ArrayList#add
+l[1:3] # => [2, 3]
+l.pop(1) # => 2; l: [1, 3, 4]
+l.insert(1, 2) # l: [1, 2, 3, 4]
+l == [1, 2, 3, 4] # True
+
+h = HashMap()
+h[1] = 2 # h: {1: 2}
+h.setdefault(3, 4) # h: {1: 2, 3: 4}
+h |= {3: 6} # {1: 2, 3: 6}
+h == {1: 2, 3: 6} # True
+```
+
+Specifically:
+* Foreign lists inherit from Python `list`
+* Foreign dictionaries inherit from `dict`
+* Foreign iterators inherit from `iterator`
+* Foreign exceptions inherit from `BaseException`
+* Foreign none/null inherit from `NoneType`
+
 ## Interacting with other dynamic languages from Python scripts
 
 More general, non-JVM specific interactions with other languages from Python scripts are achieved via the _polyglot_ API.

graalpython/com.oracle.graal.python/src/com/oracle/graal/python/builtins/objects/iterator/IteratorBuiltins.java

@@ -465,7 +465,7 @@ static int foreign(Object self,
                         @Bind("this") Node inliningTarget,
                         @Cached IsForeignObjectNode isForeignObjectNode,
                         @CachedLibrary(limit = "getCallSiteInlineCacheMaxDepth()") InteropLibrary interop,
-                        @Cached(inline = false) GilNode gil) {
+                        @Cached GilNode gil) {
             gil.release(true);
             try {
                 return interop.hasIteratorNextElement(self) ? 1 : 0;