Custom implementations of standard java interfaces (e.g. Map.Entry) are not fully functional in python

[novos40]

Describe the bug
Custom Map.Entry java implementation can not be unpacked in python. I did not do testing with standard java collection classes as we're not using them due to they limited capabilities and inefficient design. I suspect, however, that they might exhibit similar problem

To Reproduce
Create java object implementing Map interface and map.items() method so it can mimic python dict API
Observe that the following code does not work in python

for key,val in map.items():
    ...

while the following works

for ent in map.items():
    key = ent.getKey()
    val = ent.getValue()
    ...

Expected behavior
Standard java interfaces should be recognized in terms of packing/unpacking capabilities
AND/OR
It should be clearly documented which additional functions must be implemented.

From the error messages I can guess that implementing iterator on entry might solve the problem as it complains that it can't unpack non-iterable object.

Environment (please complete the following information):
Multiple: Windows, Linux, MacOS
Multiple: python v3+
Multiple java 8, java 21+
JEP v4.2.2
OSGi container

Additional context
We're doing deep python/java integration in a highly dynamic and high performance environment. For example: a request can be forwarded from java to a python application. In turn, python may invoke java methods which, in turn, may instantiate new python objects, embed them into a java data structure and return this data structure with those objects back to python. Neither java nor python must be aware that they are working with foreign objects because the same code can be used to work with native objects and any mix-and-match to an arbitrary nesting depth.
To that end, since we're using custom java collection classes anyway, we can implement python-related functions (e.g. map.items() on java Map) and vise versa, create python classes so they can be used in java. Also we can inject python constructors (as java lambdas) to java components so they can create python objects without explicit knowledge about object origin. The only thing both java and python should care is that those objects implement java APIs on java side and python APIs on python side.
So far we were quite successful with GraalVM, but due to limited python modules compatibility it would be nice to have the same with JEP

[bsteffensmeier]

Any Java object which implements the java.util.Map interface will automatically get an items() method added in Python and the result can be iterated just like a dict as shown below at an interactive jep interpreter:

>>> from java.util import HashMap
>>> map = HashMap()
>>> map["key1"] = "value1"
>>> map["key2"] = "value2"
>>> for k,v in map.items():
...   print(k, v)
... 
key1 value1
key2 value2

Jep adds the items() method to the Python class for the java.util.Map interface. Since your class extends java.util.Map your items() method is overriding the one Jep added. Since you are not returning a list of something that Python can unpack, your unpack operation is not working. If you return a List<Object[]> or a List<List> then it should unpack.

For documentation I will refer you to the Python documentation. Writing a Java class to duck type a Python class should not be much different than writing a Python class to duck type a Python class. The items() method usually returns a sequence of tuples, since Java doesn't have tuples I think a List<Object[]> is a straightforward conversion.