Skip to content

Commit 632770f

Browse files
olyagplolyagpl
committed
Proofread and update python docs following general conventions. Part 2
1 parent c287c6f commit 632770f

File tree

3 files changed

+167
-223
lines changed

3 files changed

+167
-223
lines changed

‎docs/user/Jython.md

Lines changed: 73 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
# Jython Compatibility
22

3-
Full Jython compatibility is not a goal of this project. One major reason for
4-
this is that most Jython code that uses Java integration will be based on a
5-
stable Jython release, and these only come in Python 2.x versions. The GraalVM
6-
implementation of Python, in contrast, is only targeting Python 3.x.
3+
Most Jython code that uses Java integration will be based on a
4+
stable Jython release, and these only come in Python 2.x versions.
5+
GraalVM's Python runtime, in contrast, is only targeting Python 3.x.
6+
Thus, GraalVM does not provide full compatibility with these earlier 2.x versions of Jython.
77

8-
Nonetheless, there are certain features of Jython's Java integration that we can
9-
offer similarly. Here is an example:
8+
Nonetheless, there are certain features of Jython's Java integration that we can offer similarly.
9+
Here is an example:
1010

1111
>>> import java.awt as awt
1212
>>> win = awt.Frame()
@@ -16,80 +16,77 @@ offer similarly. Here is an example:
1616
'java.awt.Dimension[width=200,height=200]'
1717
>>> win.show()
1818

19-
This example works exactly the same on both Jython and Python on GraalVM. Some
20-
features of Jython are more expensive at runtime, and thus are hidden behind a
21-
command line flag on Graal: `--python.EmulateJython`.
19+
This example works exactly the same on both Jython and Python on GraalVM.
20+
Some features of Jython are more expensive at runtime, and thus are hidden behind a
21+
command line flag on GraalVM: `--python.EmulateJython`.
22+
23+
## Import Java Classes
2224

23-
### Importing
2425
Import statements allow you to import Java classes, but (unlike Jython), only
25-
packages in the `java` namespace can be directly imported. Importing classes
26-
from packages outside `java` namespace also requires the
27-
`--python.EmulateJython` option to be active.
28-
This will work:
29-
```
26+
packages in the `java` namespace can be directly imported.
27+
28+
For example, this will work:
29+
```python
3030
import java.lang as lang
3131
```
3232
But this will not:
33-
```
33+
```python
3434
import javax.swing as swing
3535
from javax.swing import *
3636
```
3737
Instead, you will have to import one of the classes you are interested in directly:
38+
```python
39+
import javax.swing.Window as Window
3840
```
39-
import javax.swing.JWindow as JWindow
40-
```
4141

42-
### Basic Object Usage
42+
## Basic Object Usage
43+
4344
Constructing and working with Java objects and classes is done with natural
4445
Python syntax. The methods of Java objects can also be retrieved and passed
45-
around as first class objects (bound to their instance) the same as Python
46+
around as first class objects (bound to their instance), the same as Python
4647
methods:
4748

4849
>>> from java.util import Random
4950
>>> rg = Random(99)
5051
>>> boundNextInt = rg.nextInt
5152
>>> rg.nextInt()
5253
1491444859
53-
>>> boundNextInt()
54+
>>> boundNextInt = rg.nextInt
5455
1672896916
5556

56-
### Java-to-Python Types: Automatic Conversion
57-
Method overloads are resolved by matching the Python arguments in a best-effort
58-
manner to the available parameter types. This is also when data conversion
59-
happens. The goal here is to make using Java from Python as smooth as
60-
possible. The matching we do here is similar to Jython, but Graal Python uses a
61-
more dynamic approach to matching — Python types emulating `int` or
62-
`float` are also converted to the appropriate Java types. This allows, for
63-
example, to use Pandas frames as `double[][]` or NumPy array elements as `int[]`
64-
when the elements fit into those Java primitive types.
65-
66-
| Java type | Python type |
67-
|:--------------------------------|:--------------------------------------------------------------------------------------|
68-
| `null` | `None` |
69-
| `boolean` | `bool` |
70-
| `byte`, `short`, `int` , `long` | `int`, any object that has an `__int__` method |
71-
| `float`, `double` | `float`, any object that has a `__float__` method |
72-
| `char` | `str` of length 1 |
73-
| `java.lang.String` | `str` |
74-
| `byte[]` | `bytes`, `bytearray`, wrapped Java array, Python list with only the appropriate types |
75-
| Java arrays | Wrapped Java array or Python list with only the appropriate types |
76-
| Java objects | Wrapped Java object of the appropriate type |
77-
| `java.lang.Object` | Any object |
78-
79-
### Special Jython Modules
80-
Any of the special Jython modules are not available. For example, the `jarray`
81-
module on Jython allows construction of primitive Java arrays. This can be
82-
achieved as follows on GraalPython:
57+
## Java-to-Python Types: Automatic Conversion
58+
59+
Method overloads are resolved by matching the Python arguments in a best-effort manner to the available parameter types.
60+
This also happens during when data conversion.
61+
The goal here is to make using Java from Python as smooth as possible.
62+
The matching allowed here is similar to Jython, but GraalVM's Python implementation uses a more dynamic approach to matching — Python types emulating `int` or `float` are also converted to the appropriate Java types.
63+
This allows, for example, to use Pandas frames as `double[][]` or NumPy array elements as `int[]` when the elements fit into those Java primitive types.
64+
65+
| Java type | Python type |
66+
|:-----------------------|:----------------------------------------------------------------------------------|
67+
| null | None |
68+
| boolean | bool |
69+
| byte, short, int, long | int, any object that has an `__int__` method |
70+
| float | float, any object that has a `__float__` method |
71+
| char | str of length 1 |
72+
| java.lang.String | str |
73+
| byte[] | bytes, bytearray, wrapped Java array, Python list with only the appropriate types |
74+
| Java arrays | Wrapped Java array or Python list with only the appropriate types |
75+
| Java objects | Wrapped Java object of the appropriate type |
76+
| java.lang.Object | Any object |
77+
78+
## Special Jython Modules
79+
80+
None of the special Jython modules are available, but many of those modules functions can still be achieved.
81+
For example, the `jarray` module on Jython allows construction of primitive Java arrays.
82+
This can beachieved as follows on GraalVM's Python runtime:
8383

8484
>>> import java
8585
>>> java.type("int[]")(10)
8686

87-
The code that only needs to pass a Java array can also use Python types. However,
88-
implicitly, this may entail a copy of the array data, which can be deceiving when
89-
using Java arrays as output parameters:
87+
The code that only needs to pass a Java array can also use Python types.
88+
However, implicitly, this may entail a copy of the array data, which can be deceiving when using Java arrays as output parameters:
9089

91-
>>> # This example needs the --python.EmulateJython flag for the java.io import
92-
>>> import java
9390
>>> i = java.io.ByteArrayInputStream(b"foobar")
9491
>>> buf = [0, 0, 0]
9592
>>> i.read(buf) # buf is automatically converted to a byte[] array
@@ -102,9 +99,9 @@ using Java arrays as output parameters:
10299
>>> jbuf
103100
[98, 97, 122]
104101

105-
### Exceptions from Java
106-
Catching all kinds of Java exceptions comes with a performance penalty and is
107-
only enabled with the `--python.EmulateJython` flag.
102+
## Exceptions from Java
103+
104+
Catching all kinds of Java exceptions comes with a performance penalty and is only enabled with the `--python.EmulateJython` option.
108105

109106
>>> import java
110107
>>> v = java.util.Vector()
@@ -115,27 +112,27 @@ only enabled with the `--python.EmulateJython` flag.
115112
...
116113
7 >= 0
117114

118-
### Java Collections
115+
## Java Collections
116+
119117
There is no automatic mapping of the Python syntax for accessing dictionary
120118
elements to the `java.util` mapping and list classes' ` get`, `set`, or `put`
121119
methods. To use these mapping and list clases, you must call the Java methods:
122120

123-
>>> # This example needs the --python.EmulateJython flag for the java.util import
124-
>>> import java
125121
>>> ht = java.util.Hashtable()
126122
>>> ht.put("foo", "bar")
127123
>>> ht.get("foo")
128124
'bar'
129125

130126
The Python-style iteration of Java `java.util.Enumerable`,
131127
`java.util.Iterator`, or `java.lang.Iterable` is not supported. For these, you will have to use a
132-
`while` loop and use the `hasNext()` and `next()` (or equivalent) methods.
128+
`while` loop and use the `hasNext()` and `next()` (or equivalent) methods. <!---this doesn't want an example?--->
133129

134-
### No Inheriting from Java
135-
Python classes cannot inherit from Java classes. A workaround can be to create a
136-
flexible subclass in Java, compile it and use delegation instead. Take this
137-
example:
138-
```
130+
## Inheritance from Java
131+
132+
Python classes cannot inherit from Java classes.
133+
A workaround can be to create a flexible subclass in Java, compile it, and use delegation instead.
134+
Take this example:
135+
```java
139136
import java.util.logging.Handler;
140137

141138
public class PythonHandler extends Handler {
@@ -159,8 +156,7 @@ public class PythonHandler extends Handler {
159156
}
160157
```
161158
Then you can use it like this in Python:
162-
```
163-
# This example needs the --python.EmulateJython flag for the java.util import
159+
```python
164160
from java.util.logging import LogManager, Logger
165161

166162
class MyHandler():
@@ -173,14 +169,13 @@ LogManager.getLogManager().addLogger(Logger('my.python.logger', None, MyHandler(
173169

174170
## Embedding Python into Java
175171

176-
The other way to use Jython is to embed it into Java applications. Where above,
177-
Graal Python offered some measure of compatibility with existing Jython code, we
178-
do not offer any in this case. Existing code using Jython depends directly on
179-
the Jython package (for example, in the Maven configuration), because the Java
180-
code has references to Jython internal classes such as `PythonInterpreter`.
181-
182-
For Graal Python, no dependency other than on the [GraalVM SDK](https://mvnrepository.com/artifact/org.graalvm.sdk/graal-sdk) is
183-
required. There are no APIs particular to Python that are exposed, and
184-
everything is done through the GraalVM API. Important to know is that as long as
185-
your application is executed on a GraalVM with the Python language installed,
186-
you can embed Python in your programs. For more detail, refer to the [Embed Languages](https://www.graalvm.org/reference-manual/embed-languages/) reference.
172+
The other way to use Jython is to embed it into Java applications.
173+
Where above GraalVM's Python runtime offered some measure of compatibility with existing Jython code, nothing is offered in this case.
174+
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`.
175+
176+
For GraalVM's Python runtime, no dependency other than on the [GraalVM SDK](https://mvnrepository.com/artifact/org.graalvm.sdk/graal-sdk) is required.
177+
There are no APIs particular to Python that are exposed, and everything is done through the GraalVM API.
178+
179+
It is important to note that as long as your application is executed on GraalVM with the Python language installed,
180+
you can embed Python in your programs.
181+
For more details, refer to the [Embed Languages](https://www.graalvm.org/docs/reference-manual/embed-languages/#Function_Python) guide.

‎docs/user/Packages.md

Lines changed: 18 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,40 @@
11
# Installing Supported Packages
22

3-
### Create a virtual environment
4-
The best way of using the GraalVM implementation of Python is out of a virtual
5-
environment. This generates wrapper scripts and makes the implementation usable
6-
from shell as standard Python interpreter. To do so execute the following from a
7-
GraalVM installation:
3+
## Create a Virtual Environment
84

5+
The best way of using GraalVM's Python runtime is from a virtual environment.
6+
This generates wrapper scripts and makes the implementation usable from shell as the standard Python interpreter.
7+
To create the virtual environment with GraalVM:
98
```shell
109
graalpython -m venv <venv-dir>
1110
```
1211

1312
To activate the environment in your shell session call:
14-
1513
```shell
1614
source <venv-dir>/bin/activate
1715
```
1816

19-
### Using ginstall
20-
At the moment not enough of the standard library is implemented to run the
21-
standard package installers for many packages. As a convenience, a
22-
simple module to install packages is provided (including
23-
potential patches required for those packages). Try the following to find out
24-
more:
25-
17+
### Using `ginstall`
18+
At the moment, there are not enough standard libraries implemented to run the standard package installers for many packages.
19+
As a convenience, a simple module to install packages is provided (including potential patches required for those packages).
20+
Try the following to find out more:
2621
```shell
2722
graalpython -m ginstall --help
2823
```
2924

3025
As a slightly more exciting example, try:
31-
32-
```shell
26+
```sehll
3327
graalpython -m ginstall install numpy
3428
```
3529

36-
If all goes well (also consider native dependencies of NumPy), you should be
37-
able to `import numpy` afterwards.
30+
If all goes well (also consider native dependencies of NumPy), you should be able to `import numpy` afterwards.
31+
32+
The support for more extensions is a high priority.
33+
The GraalVM team is actively working to enable support for the Python C API, as well as to make extensions such as NumPy, SciPy, Scikit-learn, Pandas, Tensorflow, and alike, work.
34+
Other extensions might currently work, but they are not actively tested.
35+
Note that to try extensions on GraalVM's Python runtime, you have to download, build, and install them manually for now.
3836

39-
Support for more extensions is a high priority. The work is actively done
40-
to enable support for the Python C API, to make extensions such as NumPy, SciPy,
41-
Scikit-learn, Pandas, Tensorflow and the like work. Some other extensions might
42-
also already work, but they are not actively tested. Note that to try extensions
43-
with GraalVM Python implementation, you have to download, build and install them manually
44-
for now.
37+
### Using `pip`
4538

46-
### Using PIP
47-
The pip package installer is available and working in a `venv`, but there is no
48-
support for SSL yet. That means you can install packages from PyPI if you use an
49-
HTTP mirror and you can install local packages.
39+
The `pip` package installer is available and working in a `venv`, but there is no support for SSL yet.
40+
This means you can install packages from PyPI if you use an HTTP mirror, and you can install local packages.

0 commit comments

Comments
 (0)