Skip to content

Commit c287c6f

Browse files
olyagplolyagpl
committed
Proofread and update python docs following general conventions
1 parent 59b08ed commit c287c6f

File tree

3 files changed

+108
-141
lines changed

3 files changed

+108
-141
lines changed

‎docs/user/FAQ.md

Lines changed: 30 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,62 +1,49 @@
1-
# Frequently Asked Questions
1+
## Frequently Asked Questions
22

3-
### Does module/package XYZ work on GraalVM's Python implementation?
3+
### Does module/package XYZ work on GraalVM's Python runtime?
44

5-
It depends, but is currently unlikely. The first goal with the GraalVM Python implementation was to
6-
show that NumPy and related packages can run using the managed GraalVM LLVM
7-
implementation. Now the GraalVM team continue to improve the
8-
number of passing CPython unittests and to track the compatibility with popular PyPI packages.
5+
It depends, but is currently unlikely.
6+
The first goal with GraalVM's Python implementation was to show that NumPy and related packages can run using the managed GraalVM LLVM runtime.
7+
The GraalVM team continues to improve the number of passing CPython unittests, and to track the compatibility with popular PyPI packages.
98

109
### Can the GraalVM Python implementation replace my Jython use case?
1110

12-
It can, but there are some caveats, like Python code subclassing Java
13-
classes or use through the `javax.script.ScriptEngine` not being
14-
supported. See the [Jython Compatibility](Jython.md) guide for details.
11+
It can, but there are some caveats, like Python code subclassing Java classes or use through the `javax.script.ScriptEngine` not being supported.
12+
See the [Jython Compatibility](Jython.md) guide for details.
1513

16-
### Do I need to compile and run native modules as LLVM bitcode to use GraalVM's Python implementation?
14+
### Do I need to compile and run native modules as LLVM bitcode to use on GraalVM's Python runtime?
1715

18-
If you want to run C extensions or use certain built-in features, yes, you need
19-
to build the module with GraalVM's Python and then it will run using the GraalVM
20-
LLVM runtime. However, many of the core features of Python (including e.g.,
21-
large parts of the `os` API) are implemented in pure Java and many standard
22-
library modules and packages work without running any LLVM bitcode. So even
23-
though GraalVM's Python depends on the GraalVM LLVM runtime, for many use cases
16+
If you want to run C extensions or use certain built-in features, yes, you need to build the module with GraalVM's Python implementation, and then it will run using the GraalVM LLVM runtime.
17+
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.
18+
So even though the Python implementation depends on the GraalVM LLVM runtime, for many use cases
2419
you can disallow native modules entirely.
2520

26-
### Can I use GraalVM sandboxing features with GraalVM's Python implementation?
21+
### Can I use the GraalVM sandboxing features with Python?
2722

28-
Yes, you can. As an embedder, you can selectively disable features. For example, you
29-
can disable native code execution or filesystem access. If you are a user of
30-
Oracle GraalVM Enterprise Edition, you will also find that the managed execution mode
31-
for LLVM fully works for running extensions such as NumPy in a safer manner.
23+
Yes, you can.
24+
As an embedder, you can selectively disable features.
25+
For example, you can disable native code execution or filesystem access.
26+
Also, GraalVM's managed execution mode for LLVM fully works for running extensions such as NumPy in a safer manner.
3227

33-
### Do all the GraalVM polyglot features work?
28+
### Do all the GraalVM polyglot features work with Python?
3429

35-
The team is continuously working to ensure all polyglot features of GraalVM work as a
36-
Python user would expect. There are still many cases where expectations are
37-
unclear or where multiple behaviours are imaginable. The team is actively looking at
38-
use cases and are continuously evolving the Python implementation to provide the most
30+
The team is continuously working to ensure all polyglot features of GraalVM work as a Python user would expect.
31+
There are still many cases where expectations are unclear or where multiple behaviors are imaginable.
32+
The team is actively looking at use cases and continuously evolving the Python implementation to provide the most
3933
convenient and least surprising behaviour.
4034

41-
### What is the performance I can expect from GraalVM's Python implementation?
35+
### What performance can I expect from GraalVM's Python runtime?
4236

43-
For pure Python code, performance after warm-up can be expected to be around 5-6
44-
times faster than CPython 3.8 (or 6-7x faster than Jython). For native
45-
extensions running as LLVM bitcode, CPython is currently slower -- you
46-
can expect to see between 0.1x and 0.5x performance.
37+
For the 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).
38+
For native extensions running as LLVM bitcode, CPython is currently slower -- you can expect to see between 0.1x and 0.5x performance.
4739

48-
### I heard languages with JIT compilers have slow startup. Is that true for GraalVM's Python?
40+
### I heard languages with JIT compilers have slow startup. Is that true for GraalVM's Python runtime?
4941

50-
It depends. When you use the [GraalVM Native Image](https://www.graalvm.org/reference-manual/native-image/) feature with Python or
51-
use the `graalpython` launcher of GraalVM, its startup is competitive with
52-
CPython. In any case, both with Native Image or when running on JVM you first
53-
need to warm up to reach peak performance. This is a complicated story in
54-
itself, but in general it can take a while (a minute or two) after you have
55-
reached and are running your core workload.
42+
It depends.
43+
When you use [Native Image](https://www.graalvm.org/reference-manual/native-image/) with Python, or the `graalpython` launcher of GraalVM, startup is competitive with CPython.
44+
In any case, both with Native Image or when running on the 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.
5645

57-
### Can I share warmed up code between multiple Python contexts?
46+
### Can I share warmed-up code between multiple Python contexts?
5847

59-
Yes, this works, and you will find that starting up multiple contexts in the
60-
same engine and running the same or similar code in them will get increasingly
61-
faster, because the compiled code is shared across contexts. However, the peak
62-
performance in this setup is currently lower than in the single context case.
48+
Yes, this works, and you will find that starting up multiple contexts in the same engine, and running the same or similar code in them will get increasingly faster, because the compiled code is shared across contexts.
49+
However, the peak performance in this setup is currently lower than in the single context case.

‎docs/user/Interoperability.md

Lines changed: 52 additions & 59 deletions
Original file line numberDiff line numberDiff line change
@@ -1,65 +1,57 @@
11
# Interoperability
22

3-
GraalVM supports several other programming languages, including JavaScript, R,
4-
Ruby, and LLVM. GraalVM provides a Python API to interact with other languages
5-
available on the GraalVM. In fact, GraalVM uses this API internally to
6-
execute Python C extensions using the LLVM implementation in GraalVM.
7-
8-
You can import the `polyglot` module to interact with other languages. In order
9-
to use the polyglot functionality, you need to specify `--jvm --polyglot`
10-
arguments to the `graalpython` executable.
3+
Since GraalVM supports several other programming languages including JavaScript, R,
4+
Ruby, and those that compile to LLVM bitcode, it also provides a Python API to interact with them.
5+
In fact, GraalVM uses this API internally to execute Python C extensions using the GraalVM LLVM runtime.
116

7+
You can import the `polyglot` module to interact with other languages:
128
```python
139
import polyglot
1410
```
1511

16-
## Evaluating code in other languages
12+
You can import a global value from the entire polyglot scope:
13+
```python
14+
imported_polyglot_global = polyglot.import_value("global_name")
15+
```
16+
17+
This global value should then work as expected:
18+
* Accessing attributes assumes it reads from the `members` namespace.
19+
* Accessing items is supported both with strings and numbers.
20+
* Calling methods on the result tries to do a straight invoke and falls
21+
back to reading the member and trying to execute it.
22+
23+
You can evaluate some inlined code from another language:
1724
```python
1825
polyglot.eval(string="1 + 1", language="ruby")
1926
```
2027

21-
It also works with the path to a file:
28+
You can evaluate some code from a file, by passing the path to it:
2229
```python
2330
polyglot.eval(path="./my_ruby_file.rb", language="ruby")
2431
```
2532

26-
If you pass a file, you can also try to rely on the file-based language detection:
33+
If you pass a file, you can also rely on the file-based language detection:
2734
```python
2835
polyglot.eval(path="./my_ruby_file.rb")
2936
```
3037

31-
## Exporting and importing values
32-
To export something from Python to other Polyglot languages so they can import
38+
You can export some oblect from Python to other supported languages so they can import
3339
it:
3440
```python
3541
foo = object()
3642
polyglot.export_value(foo, name="python_foo")
3743
```
3844

39-
The export function can be used as a decorator, in this case the function name
40-
is used as the globally exported name:
45+
The export function can be used as a decorator.
46+
In this case the function name is used as the globally exported name:
4147
```python
4248
@polyglot.export_value
4349
def python_method():
4450
return "Hello from Python!"
4551
```
4652

47-
You can import a global value from the entire polyglot scope (exported from
48-
another language):
49-
```python
50-
imported_polyglot_global = polyglot.import_value("global_name")
51-
```
52-
53-
This global should then work as expected; accessing attributes assumes it reads
54-
from the `members` namespace; accessing items is supported both with strings and
55-
numbers; calling methods on the result tries to do a straight invoke and falls
56-
back to reading the member and trying to execute it.
57-
58-
59-
## Examples
60-
Here is an example of how to use JavaScript regular expression engine to
53+
Here is an example of how to use the JavaScript regular expression engine to
6154
match Python strings. Save this code to the `polyglot_example.py` file:
62-
6355
```python
6456
import polyglot
6557

@@ -77,26 +69,23 @@ if not md:
7769
print("Here is what we found: '%s'" % md[1])
7870
```
7971

80-
To run it, pass the `--jvm --polyglot` options to `graalpython` binary:
72+
To run it, pass the `--jvm --polyglot` option to the `graalpython` launcher:
8173
```shell
8274
graalpython --jvm --polyglot polyglot_example.py
8375
```
8476

85-
This example matches Python strings using the JavaScript regular expression object
86-
and Python reads the captured group from the JavaScript result and prints: `Here
87-
is what we found: 'This string was matched by Graal.js'`.
77+
This program matches Python strings using the JavaScript regular expression object.
78+
Python reads the captured group from the JavaScript result and prints:
79+
*Here is what we found: 'This string was matched by Graal.js'*.
8880

89-
As a more complex example, we can read a file using R, process the data in
90-
Python, and use R again to display the resulting data image, using both R and
91-
Python libraries in conjunction. To run it, first install the
92-
required R library:
81+
As a more complex example, see how you can read a file using R, process the data in Python, and use R again to display the resulting data image, using both the R and Python libraries in conjunction.
82+
To run this example, first install the required R library:
9383
```shell
9484
R -e 'install.packages("https://www.rforge.net/src/contrib/jpeg_0.1-8.tar.gz", repos=NULL)'
9585
```
9686

9787
This example also uses [image_magix.py](http://graalvm.org/docs/examples/image_magix.py) and works
98-
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.
99-
88+
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 that the script below is located in and executed from.
10089
```python
10190
import polyglot
10291
import sys
@@ -136,36 +125,36 @@ time.sleep(10)
136125

137126
## Java Interoperability
138127

139-
Finally, to interoperate with Java (only when running on the JVM), you can use
140-
the `java` module:
128+
Finally, to interoperate with Java (only when running on the JVM), you can use the `java` module:
141129
```python
142130
import java
143131
BigInteger = java.type("java.math.BigInteger")
144-
myBigInt = BigInteger.valueOf(42)
145-
myBigInt.shiftLeft(128) # public Java methods can just be called
146-
myBigInt["not"]() # Java method names that are keywords in
147-
# Python can be accessed using "[]"
132+
myBigInt = BigInteger(42)
133+
myBigInt.shiftLeft(128)
134+
# public Java methods can just be called
135+
myBigInt["not"]()
136+
# Java method names that are keywords in Python can be accessed using "[]"
148137
byteArray = myBigInt.toByteArray()
149-
print(list(byteArray)) # Java arrays can act like Python lists
138+
# Java arrays can act like Python lists
139+
print(list(byteArray))
150140
```
151141

152142
For packages under the `java` package, you can also use the normal Python import
153-
syntax. This syntax is limited to importing concrete classes, it doesn't work
154-
on packages, unless in [Jython Compatibility](Jython.md) mode.
143+
syntax:
155144
```python
156145
import java.util.ArrayList
157146
from java.util import ArrayList
158147

159-
# these are the same class
160148
java.util.ArrayList == ArrayList
161149

162150
al = ArrayList()
163151
al.add(1)
164152
al.add(12)
165-
print(al) # prints [1, 12]
153+
print(al)
154+
# prints [1, 12]
166155
```
167156

168-
In addition to the `type` builtin method, the `java` module, exposes the following
157+
In addition to the `type` builtin method, the `java` module exposes the following
169158
methods as well:
170159

171160
Builtin | Specification
@@ -179,12 +168,16 @@ Builtin | Specification
179168
import java
180169
ArrayList = java.type('java.util.ArrayList')
181170
my_list = ArrayList()
182-
print(java.is_symbol(ArrayList)) # prints True
183-
print(java.is_symbol(my_list)) # prints False, my_list is not a Java host symbol
184-
print(java.is_object(ArrayList)) # prints True, symbols are also host objects
185-
print(java.is_function(my_list.add))# prints True, the add method of ArrayList
186-
print(java.instanceof(my_list, ArrayList)) # prints True
171+
print(java.is_symbol(ArrayList))
172+
# prints True
173+
print(java.is_symbol(my_list))
174+
# prints False, my_list is not a Java host symbol
175+
print(java.is_object(ArrayList))
176+
# prints True, symbols are also host objects
177+
print(java.is_function(my_list.add))
178+
# prints True, the add method of ArrayList
179+
print(java.instanceof(my_list, ArrayList))
180+
# prints True
187181
```
188182

189-
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
190-
for more information about interoperability with other programming languages.
183+
See [Polyglot Programming](https://www.graalvm.org/docs/reference-manual/polyglot-programming/) and [Embed Languages](https://www.graalvm.org/reference-manual/embed-languages/) for more information about interoperability with other programming languages.

0 commit comments

Comments
 (0)