[GR-25265] Merge Python Reference documentation from graalvm.org with Python User documentation.

PullRequest: graalpython/1163

Author: olyagpl

docs/user/FAQ.md

@@ -1,61 +1,58 @@
 # Frequently Asked Questions
 
-### Does module/package XYZ work on GraalPython?
+### Does module/package XYZ work on GraalVM's Python implementation?
 
-It depends, but is currently unlikely. Our first goal with GraalPython was to
-show that we can run NumPy and related packages using the managed GraalVM LLVM
-implementation. Now that we have done so we are hard at work to improve the
-number of passing CPython unittests. We are also beginning to track our
-compatibility with popular PyPI packages and expect to increase our coverage
-there soon.
+It depends, but is currently unlikely. The first goal with the GraalVM Python implementation was to
+show that NumPy and related packages can run using the managed GraalVM LLVM
+implementation. Now the GraalVM team continue to improve the
+number of passing CPython unittests and to track the compatibility with popular PyPI packages.
 
-### Can GraalPython replace my Jython use case?
+### Can the GraalVM Python implementation replace my Jython use case?
 
-We hope it can, but there are some caveats, like Python code subclassing Java
+It can, but there are some caveats, like Python code subclassing Java
 classes or use through the `javax.script.ScriptEngine` not being
-supported. Please see our [migration document](./JYTHON) for details.
+supported. See the [Jython Compatibility](Jython.md) guide for details.
 
-### Do I need to compile and run native modules as LLVM bitcode to use GraalPython?
+### Do I need to compile and run native modules as LLVM bitcode to use GraalVM's Python implementation?
 
 If you want to run C extensions or use certain built-in features, yes, you need
-to build the module with GraalPython and then it will run using the GraalVM LLVM
-runtime. However, many of the core features of Python (including e.g. large
-parts of the `os` API) are implemented in pure Java and many standard library
-modules and packages work without running any LLVM bitcode. So even though
-GraalPython depends on GraalVM LLVM, for many use cases you can disallow native
-modules entirely.
+to build the module with GraalVM's Python and then it will run using the GraalVM
+LLVM runtime. However, many of the core features of Python (including e.g.,
+large parts of the `os` API) are implemented in pure Java and many standard
+library modules and packages work without running any LLVM bitcode. So even
+though GraalVM's Python depends on the GraalVM LLVM runtime, for many use cases
+you can disallow native modules entirely.
 
-### Can I use GraalVM sandboxing features with GraalPython?
+### Can I use GraalVM sandboxing features with GraalVM's Python implementation?
 
-Yes! As an embedder, you can selectively disable features. As an example, you
+Yes, you can. As an embedder, you can selectively disable features. For example, you
 can disable native code execution or filesystem access. If you are a user of
-GraalVM Enterprise Edition, you will also find that the managed execution mode
+Oracle GraalVM Enterprise Edition, you will also find that the managed execution mode
 for LLVM fully works for running extensions such as NumPy in a safer manner.
 
 ### Do all the GraalVM polyglot features work?
 
-We are doing our best to ensure the polyglot features of GraalVM work as a
+The team is continuously working to ensure all polyglot features of GraalVM work as a
 Python user would expect. There are still many cases where expectations are
-unclear or where multiple behaviors are imaginable. We are actively looking at
-use cases and are continuously evolving the implementation to provide the most
-convenient and least surprising behavior.
+unclear or where multiple behaviours are imaginable. The team is actively looking at
+use cases and are continuously evolving the Python implementation to provide the most
+convenient and least surprising behaviour.
 
-### What is the performance I can expect from GraalPython?
+### What is the performance I can expect from GraalVM's Python implementation?
 
 For pure Python code, performance after warm-up can be expected to be around 5-6
 times faster than CPython 3.8 (or 6-7x faster than Jython). For native
-extensions running as LLVM bitcode, we are currently slower than CPython - you
+extensions running as LLVM bitcode, CPython is currently slower -- you
 can expect to see between 0.1x and 0.5x performance.
 
-### I heard languages with JIT compilers have slow startup. Is that true for GraalPython?
+### I heard languages with JIT compilers have slow startup. Is that true for GraalVM's Python?
 
-It depends. When you use the GraalVM native image feature with GraalPython or
-use the GraalPython launcher in GraalVM its startup is competitive with
-CPython. In any case, both with native image or when running on JVM we first
+It depends. When you use the [GraalVM Native Image](https://www.graalvm.org/docs/reference-manual/graalvm-native-image/) feature with Python or
+use the `graalpython` launcher of GraalVM, its startup is competitive with
+CPython. In any case, both with Native Image or when running on JVM you first
 need to warm up to reach peak performance. This is a complicated story in
 itself, but in general it can take a while (a minute or two) after you have
-reached and are running your core workload. We are continuously working on
-improving this.
+reached and are running your core workload.
 
 ### Can I share warmed up code between multiple Python contexts?
 

docs/user/POLYGLOT.md renamed to docs/user/Interoperability.md

@@ -1,5 +1,10 @@
 # Interoperability
 
+GraalVM supports several other programming languages, including JavaScript, R,
+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.
 
 ```python
@@ -46,6 +51,85 @@ def python_method():
     return "Hello from Python!"
 ```
 
+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:
+
+```python
+import polyglot
+
+re = polyglot.eval(string="RegExp()", language="js")
+
+pattern = re.compile(".*(?:we have (?:a )?matching strings?(?:[!\\?] )?)(.*)")
+
+if pattern.exec("This string does not match"):
+    raise SystemError("that shouldn't happen")
+
+md = pattern.exec("Look, we have matching strings! This string was matched by Graal.js")
+if not md:
+    raise SystemError("this should have matched")
+
+print("Here is what we found: '%s'" % md[1])
+```
+
+To run it, pass the `--jvm --polyglot` options to `graalpython` binary:
+```shell
+$ graalpython --jvm --polyglot polyglot_example.py
+```
+
+This example matches Python strings using the JavaScript regular expression object
+and Python reads the captured group from the JavaScript result and prints: `Here
+is what we found: 'This string was matched by Graal.js'`.
+
+As a more complex example, we can read a file using R, process the data in
+Python, and use R again to display the resulting data image, using both R and
+Python libraries in conjunction. To run it, first install the
+required R library:
+```shell
+$ R -e 'install.packages("https://www.rforge.net/src/contrib/jpeg_0.1-8.tar.gz", repos=NULL)'
+```
+
+This example also uses [image_magix.py](http://graalvm.org/docs/examples/image_magix.py) and works
+on a JPEG image input (you can try with [this image](https://www.graalvm.org/resources/img/python_demo_picture.jpg)). These files have to be in the same folder the script below is located in and executed from.
+
+```python
+import polyglot
+import sys
+import time
+sys.path.insert(0, ".")
+from image_magix import Image
+
+load_jpeg = polyglot.eval(string="""function(file.name) {
+    library(jpeg)
+    jimg <- readJPEG(file.name)
+    jimg <- jimg*255
+    jimg
+}""", language="R")
+
+raw_data = load_jpeg("python_demo_picture.jpg")
+
+# the dimensions are R attributes; define function to access them
+getDim = polyglot.eval(string="function(v, pos) dim(v)[[pos]]", language="R")
+
+# Create object of Python class 'Image' with loaded JPEG data
+image = Image(getDim(raw_data, 2), getDim(raw_data, 1), raw_data)
+
+# Run Sobel filter
+result = image.sobel()
+
+draw = polyglot.eval(string="""function(processedImgObj) {
+    require(grDevices)
+    require(grid)
+    mx <- matrix(processedImgObj$`@data`/255, nrow=processedImgObj$`@height`, ncol=processedImgObj$`@width`)
+    grDevices:::awt()
+    grid.raster(mx, height=unit(nrow(mx),"points"))
+}""", language="R")
+
+draw(result)
+time.sleep(10)
+```
+
+## Java Interoperability
+
 Finally, to interoperate with Java (only when running on the JVM), you can use
 the `java` module:
 ```python
@@ -94,3 +178,6 @@ print(java.is_object(ArrayList))    # prints True, symbols are also host objects
 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/docs/reference-manual/embed-languages/#Function_Python) reference
+for more information about interoperability with other programming languages.

docs/user/JYTHON.md renamed to docs/user/Jython.md

@@ -1,4 +1,4 @@
-# About Jython Compatibility
+# Jython Compatibility
 
 Full Jython compatibility is not a goal of this project. One major reason for
 this is that most Jython code that uses Java integration will be based on a
@@ -21,23 +21,22 @@ features of Jython are more expensive at runtime, and thus are hidden behind a
 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. So this works:
-
-    import java.lang as lang
-
-But this doesn't:
-
-    import javax.swing as swing
-    from javax.swing import *
-
-Instead, you'll have to import one of the classes you're interested in directly:
-
-    import javax.swing.Window as Window
+packages in the `java` namespace can be directly imported. This will work:
+```
+import java.lang as lang
+```
+But this will not:
+```
+import javax.swing as swing
+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
+```
 
 ### Basic Object Usage
-
 Constructing and working with Java objects and classes is done with natural
 Python syntax. The methods of Java objects can also be retrieved and passed
 around as first class objects (bound to their instance) the same as Python
@@ -52,7 +51,6 @@ methods:
     1672896916
 
 ### Java-to-Python Types: Automatic Conversion
-
 Method overloads are resolved by matching the Python arguments in a best-effort
 manner to the available parameter types. This is also when data conversion
 happens. The goal here is to make using Java from Python as smooth as
@@ -76,16 +74,15 @@ when the elements fit into those Java primitive types.
 | java.lang.Object       | Any object                                                                        |
 
 ### Special Jython Modules
-
-We do not offer any of the special Jython modules. For example, the `jarray`
+Any of the special Jython modules are not available. For example, the `jarray`
 module on Jython allows construction of primitive Java arrays. This can be
 achieved as follows on GraalPython:
 
     >>> import java
     >>> java.type("int[]")(10)
 
-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
+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:
 
     >>> i = java.io.ByteArrayInputStream(b"foobar")
@@ -101,8 +98,7 @@ using Java arrays as output parameters:
     [98, 97, 122]
 
 ### Exceptions from Java
-
-Catching all kinds of Java exceptions comes with a performance penalty, and is
+Catching all kinds of Java exceptions comes with a performance penalty and is
 only enabled with the `--python.EmulateJython` flag.
 
     >>> import java
@@ -115,7 +111,6 @@ only enabled with the `--python.EmulateJython` flag.
     7 >= 0
 
 ### Java Collections
-
 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:
@@ -125,48 +120,48 @@ methods. To use these mapping and list clases, you must call the Java methods:
     >>> ht.get("foo")
     'bar'
 
-We also do not support Python-style iteration of Java `java.util.Enumerable`,
-`java.util.Iterator`, or `java.lang.Iterable`. For these, you'll have to use a
+The Python-style iteration of Java `java.util.Enumerable`,
+`java.util.Iterator`, or `java.lang.Iterable`  is not supported. For these, you will have to use a
 `while` loop and use the `hasNext()` and `next()` (or equivalent) methods.
 
 ### No Inheriting from Java
-
 Python classes cannot inherit from Java classes. A workaround can be to create a
-flexible subclass in Java, compile it, and use delegation instead. Take this
+flexible subclass in Java, compile it and use delegation instead. Take this
 example:
+```
+import java.util.logging.Handler;
 
-    import java.util.logging.Handler;
-
-    public class PythonHandler extends Handler {
-        private final Value pythonDelegate;
-
-        public PythonHandler(Value pythonDelegate) {
-            this.pythonDelegate = pythonDelegate;
-        }
+public class PythonHandler extends Handler {
+    private final Value pythonDelegate;
 
-        public void publish(LogRecord record) {
-            pythonDelegate.invokeMember("publish", record);
-        }
+    public PythonHandler(Value pythonDelegate) {
+        this.pythonDelegate = pythonDelegate;
+    }
 
-        public void flush() {
-            pythonDelegate.invokeMember("flush");
-        }
+    public void publish(LogRecord record) {
+        pythonDelegate.invokeMember("publish", record);
+    }
 
-        public void close() {
-            pythonDelegate.invokeMember("close");
-        }
+    public void flush() {
+        pythonDelegate.invokeMember("flush");
     }
 
+    public void close() {
+        pythonDelegate.invokeMember("close");
+    }
+}
+```
 Then you can use it like this in Python:
+```
+from java.util.logging import LogManager, Logger
 
-    from java.util.logging import LogManager, Logger
-
-    class MyHandler():
-        def publish(self, logRecord): print("[python]", logRecord.toString())​
-        def flush(): pass​
-        def close(): pass
-    ​
-    LogManager.getLogManager().addLogger(Logger('my.python.logger', None, MyHandler()))
+class MyHandler():
+    def publish(self, logRecord): print("[python]", logRecord.toString())​
+    def flush(): pass​
+    def close(): pass
+​
+LogManager.getLogManager().addLogger(Logger('my.python.logger', None, MyHandler()))
+```
 
 ## Embedding Python into Java
 
@@ -176,11 +171,8 @@ do not offer any in this case. Existing code using Jython depends directly on
 the Jython package (for example, in the Maven configuration), because the Java
 code has references to Jython internal classes such as `PythonInterpreter`.
 
-For Graal Python, no dependency other than on the [GraalVM
-SDK](https://mvnrepository.com/artifact/org.graalvm.sdk/graal-sdk) is
+For Graal Python, no dependency other than on the [GraalVM SDK](https://mvnrepository.com/artifact/org.graalvm.sdk/graal-sdk) is
 required. There are no APIs particular to Python that are exposed, and
 everything is done through the GraalVM API. Important to know is that as long as
 your application is executed on a GraalVM with the Python language installed,
-you can embed Python in your programs. Please refer to [our embedding
-documentation](https://www.graalvm.org/docs/reference-manual/embed/#Function_Python)
-for more details.
+you can embed Python in your programs. For more detail, refer to the [Embed Languages](https://www.graalvm.org/docs/reference-manual/embed-languages/#Function_Python) reference.