[GR-26072] Documentation fixes

PullRequest: graalpython/1270

Author: msimacek

README.md

@@ -12,7 +12,7 @@ is made available for experimentation and curious end-users.
 To try it, you can use the bundled releases from
 [www.graalvm.org](https://www.graalvm.org/downloads/). For more information and
 some examples of what you can do with it, check out the
-[reference](https://www.graalvm.org/docs/reference-manual/languages/python/).
+[reference](https://www.graalvm.org/reference-manual/python/).
 
 ### Create a virtual environment
 
@@ -80,7 +80,7 @@ cross-language interop. This will hopefully give you an idea how to use it.
 We are working on a mode that is "mostly compatible" with some of Jython's
 features, minus of course that Jython implements Python 2.7 and we implement
 Python 3.8+. We describe the current status of the compatibility mode
-[here](docs/user/JYTHON.md).
+[here](docs/user/Jython.md).
 
 ### Contributing
 

docs/user/Interoperability.md

@@ -5,23 +5,15 @@ Ruby, and LLVM. GraalVM provides a Python API to interact with other languages
 available on the GraalVM. In fact, GraalVM uses this API internally to
 execute Python C extensions using the LLVM implementation in GraalVM.
 
-You can import the `polyglot` module to interact with other languages.
+You can import the `polyglot` module to interact with other languages. In order
+to use the polyglot functionality, you need to specify `--jvm --polyglot`
+arguments to the `graalpython` executable.
 
 ```python
 import polyglot
 ```
 
-You can import a global value from the entire polyglot scope:
-```python
-imported_polyglot_global = polyglot.import_value("global_name")
-```
-
-This global should then work as expected; accessing attributes assumes it reads
-from the `members` namespace; accessing items is supported both with strings and
-numbers; calling methods on the result tries to do a straight invoke and falls
-back to reading the member and trying to execute it.
-
-You can evaluate some code in another language:
+## Evaluating code in other languages
 ```python
 polyglot.eval(string="1 + 1", language="ruby")
 ```
@@ -36,6 +28,7 @@ If you pass a file, you can also try to rely on the file-based language detectio
 polyglot.eval(path="./my_ruby_file.rb")
 ```
 
+## Exporting and importing values
 To export something from Python to other Polyglot languages so they can import
 it:
 ```python
@@ -51,6 +44,19 @@ def python_method():
     return "Hello from Python!"
 ```
 
+You can import a global value from the entire polyglot scope (exported from
+another language):
+```python
+imported_polyglot_global = polyglot.import_value("global_name")
+```
+
+This global should then work as expected; accessing attributes assumes it reads
+from the `members` namespace; accessing items is supported both with strings and
+numbers; calling methods on the result tries to do a straight invoke and falls
+back to reading the member and trying to execute it.
+
+
+## Examples
 Here is an example of how to use JavaScript regular expression engine to
 match Python strings. Save this code to the `polyglot_example.py` file:
 
@@ -135,7 +141,7 @@ the `java` module:
 ```python
 import java
 BigInteger = java.type("java.math.BigInteger")
-myBigInt = BigInteger(42)
+myBigInt = BigInteger.valueOf(42)
 myBigInt.shiftLeft(128)            # public Java methods can just be called
 myBigInt["not"]()                  # Java method names that are keywords in
                                    # Python can be accessed using "[]"
@@ -144,7 +150,8 @@ print(list(byteArray))             # Java arrays can act like Python lists
 ```
 
 For packages under the `java` package, you can also use the normal Python import
-syntax:
+syntax. This syntax is limited to importing concrete classes, it doesn't work
+on packages, unless in [Jython Compatibility](Jython.md) mode.
 ```python
 import java.util.ArrayList
 from java.util import ArrayList
@@ -179,5 +186,5 @@ print(java.is_function(my_list.add))# prints True, the add method of ArrayList
 print(java.instanceof(my_list, ArrayList)) # prints True
 ```
 
-See the [Polyglot Programming](https://www.graalvm.org/docs/reference-manual/polyglot-programming/) and the [Embed Languages](https://www.graalvm.org/reference-manual/embed-languages/) reference
+See the [Polyglot Programming](https://www.graalvm.org/reference-manual/polyglot-programming/) and the [Embed Languages](https://www.graalvm.org/reference-manual/embed-languages/) reference
 for more information about interoperability with other programming languages.

docs/user/Jython.md

@@ -22,7 +22,10 @@ command line flag on Graal: `--python.EmulateJython`.
 
 ### Importing
 Import statements allow you to import Java classes, but (unlike Jython), only
-packages in the `java` namespace can be directly imported. This will work:
+packages in the `java` namespace can be directly imported. Importing classes
+from packages outside `java` namespace also requires the
+`--python.EmulateJython` option to be active.
+This will work:
 ```
 import java.lang as lang
 ```
@@ -33,7 +36,7 @@ from javax.swing import *
 ```
 Instead, you will have to import one of the classes you are interested in directly:
 ```
-import javax.swing.Window as Window
+import javax.swing.JWindow as JWindow
 ```
 
 ### Basic Object Usage
@@ -47,7 +50,7 @@ methods:
     >>> boundNextInt = rg.nextInt
     >>> rg.nextInt()
     1491444859
-    >>> boundNextInt = rg.nextInt
+    >>> boundNextInt()
     1672896916
 
 ### Java-to-Python Types: Automatic Conversion
@@ -60,18 +63,18 @@ more dynamic approach to matching — Python types emulating `int` or
 example, to use Pandas frames as `double[][]` or NumPy array elements as `int[]`
 when the elements fit into those Java primitive types.
 
-| Java type              | Python type                                                                       |
-|:-----------------------|:----------------------------------------------------------------------------------|
-| null                   | None                                                                              |
-| boolean                | bool                                                                              |
-| byte, short, int, long | int, any object that has an `__int__` method                                      |
-| float                  | float, any object that has a `__float__` method                                   |
-| char                   | str of length 1                                                                   |
-| java.lang.String       | str                                                                               |
-| byte[]                 | bytes, bytearray, wrapped Java array, Python list with only the appropriate types |
-| Java arrays            | Wrapped Java array or Python list with only the appropriate types                 |
-| Java objects           | Wrapped Java object of the appropriate type                                       |
-| java.lang.Object       | Any object                                                                        |
+| Java type                       | Python type                                                                           |
+|:--------------------------------|:--------------------------------------------------------------------------------------|
+| `null`                          | `None`                                                                                |
+| `boolean`                       | `bool`                                                                                |
+| `byte`, `short`, `int` , `long` | `int`, any object that has an `__int__` method                                        |
+| `float`, `double`               | `float`, any object that has a `__float__` method                                     |
+| `char`                          | `str` of length 1                                                                     |
+| `java.lang.String`              | `str`                                                                                 |
+| `byte[]`                        | `bytes`, `bytearray`, wrapped Java array, Python list with only the appropriate types |
+| Java arrays                     | Wrapped Java array or Python list with only the appropriate types                     |
+| Java objects                    | Wrapped Java object of the appropriate type                                           |
+| `java.lang.Object`              | Any object                                                                            |
 
 ### Special Jython Modules
 Any of the special Jython modules are not available. For example, the `jarray`
@@ -85,6 +88,8 @@ The code that only needs to pass a Java array can also use Python types. However
 implicitly, this may entail a copy of the array data, which can be deceiving when
 using Java arrays as output parameters:
 
+    >>> # This example needs the --python.EmulateJython flag for the java.io import
+    >>> import java
     >>> i = java.io.ByteArrayInputStream(b"foobar")
     >>> buf = [0, 0, 0]
     >>> i.read(buf) # buf is automatically converted to a byte[] array
@@ -115,6 +120,8 @@ There is no automatic mapping of the Python syntax for accessing dictionary
 elements to the `java.util` mapping and list classes' ` get`, `set`, or `put`
 methods. To use these mapping and list clases, you must call the Java methods:
 
+    >>> # This example needs the --python.EmulateJython flag for the java.util import
+    >>> import java
     >>> ht = java.util.Hashtable()
     >>> ht.put("foo", "bar")
     >>> ht.get("foo")
@@ -153,6 +160,7 @@ public class PythonHandler extends Handler {
 ```
 Then you can use it like this in Python:
 ```
+# This example needs the --python.EmulateJython flag for the java.util import
 from java.util.logging import LogManager, Logger
 
 class MyHandler():

graalpython/lib-python/3/test/test_isinstance.py

@@ -277,7 +277,7 @@ def blowstack(fxn, arg, compare_to):
     # argument will raise RecursionError eventually.
     tuple_arg = (compare_to,)
     # TODO: GR-23749 revert back when truffle support is in
-    for cnt in range(10000 if sys.implementation.name == "graalpython" else sys.getrecursionlimit()+5):
+    for cnt in range(10000000 if sys.implementation.name == "graalpython" else sys.getrecursionlimit()+5):
         tuple_arg = (tuple_arg,)
         fxn(arg, tuple_arg)