Skip to content

Commit d2a08cf

Browse files
SowasvonbotSowasvonbot
committed
revert most of the changes introduced by my formatter
1 parent c296052 commit d2a08cf

File tree

1 file changed

+37
-62
lines changed

1 file changed

+37
-62
lines changed

‎docs/user/Interoperability.md

Lines changed: 37 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -4,29 +4,23 @@ toc_group: python
44
link_title: Interoperability
55
permalink: /reference-manual/python/Interoperability/
66
---
7-
87
# Interoperability
98

10-
Besides being primarily recommended to use in your Java application, GraalPy can interoperate with other Graal
11-
languages (languages implemented on
12-
the [Truffle framework](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/)).
13-
This means that you can use the objects and functions provided by those other languages directly from your Python
14-
scripts.
9+
Besides being primarily recommended to use in your Java application, GraalPy can interoperate with other Graal languages (languages implemented on the [Truffle framework](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/)).
10+
This means that you can use the objects and functions provided by those other languages directly from your Python scripts.
1511

1612
## Interacting with Java from Python scripts
1713

1814
Java is the host language of the JVM and runs the GraalPy interpreter itself.
1915
To interoperate with Java from Python scripts, use the `java` module:
20-
2116
```python
2217
import java
23-
2418
BigInteger = java.type("java.math.BigInteger")
2519
myBigInt = BigInteger.valueOf(42)
2620
# a public Java methods can just be called
27-
myBigInt.shiftLeft(128) # returns a <JavaObject[java.math.BigInteger] at ...>
21+
myBigInt.shiftLeft(128) # returns a <JavaObject[java.math.BigInteger] at ...>
2822
# Java method names that are keywords in Python must be accessed using `getattr`
29-
getattr(myBigInt, "not")() # returns a <JavaObject[java.math.BigInteger] at ...>
23+
getattr(myBigInt, "not")() # returns a <JavaObject[java.math.BigInteger] at ...>
3024
byteArray = myBigInt.toByteArray()
3125
# Java arrays can act like Python lists
3226
assert len(byteArray) == 1 and byteArray[0] == 42
@@ -37,11 +31,9 @@ For plain Python users, the `java` module is only available when running on the
3731
</aside>
3832

3933
To import packages from the `java` namespace, you can also use the conventional Python import syntax:
40-
4134
```python
4235
import java.util.ArrayList
4336
from java.util import ArrayList
44-
4537
assert java.util.ArrayList == ArrayList
4638

4739
al = ArrayList()
@@ -52,12 +44,12 @@ assert list(al) == [1, 12]
5244

5345
In addition to the `type` built-in method, the `java` module exposes the following methods:
5446

55-
Built-in | Specification
56-
--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------
57-
`instanceof(obj, class)` | returns `True` if `obj` is an instance of `class` (`class` must be a foreign object class)
58-
`is_function(obj)` | returns `True` if `obj` is a Java host language function wrapped using interop
59-
`is_object(obj)` | returns `True` if `obj` if the argument is Java host language object wrapped using interop
60-
`is_symbol(obj)` | returns `True` if `obj` if the argument is a Java host symbol, representing the constructor and static members of a Java class, as obtained by `java.type`
47+
Built-in | Specification
48+
--- | ---
49+
`instanceof(obj, class)` | returns `True` if `obj` is an instance of `class` (`class` must be a foreign object class)
50+
`is_function(obj)` | returns `True` if `obj` is a Java host language function wrapped using interop
51+
`is_object(obj)` | returns `True` if `obj` if the argument is Java host language object wrapped using interop
52+
`is_symbol(obj)` | returns `True` if `obj` if the argument is a Java host symbol, representing the constructor and static members of a Java class, as obtained by `java.type`
6153

6254
```python
6355
ArrayList = java.type('java.util.ArrayList')
@@ -69,26 +61,18 @@ assert java.is_function(my_list.add)
6961
assert java.instanceof(my_list, ArrayList)
7062
```
7163

72-
See [Polyglot Programming](https://github.com/oracle/graal/blob/master/docs/reference-manual/polyglot-programming.md)
73-
and [Embed Languages](https://github.com/oracle/graal/blob/master/docs/reference-manual/embedding/embed-languages.md)
74-
for more information about interoperability with other programming languages.
64+
See [Polyglot Programming](https://github.com/oracle/graal/blob/master/docs/reference-manual/polyglot-programming.md) and [Embed Languages](https://github.com/oracle/graal/blob/master/docs/reference-manual/embedding/embed-languages.md) for more information about interoperability with other programming languages.
7565

7666
## Interacting with other dynamic languages from Python scripts
7767

78-
More general, non-JVM specific interactions with other languages from Python scripts are achieved via the _polyglot_
79-
API.
80-
This includes all interactions with dynamic languages supported via
81-
the [Truffle framework](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/),
82-
including JavaScript and Ruby.
68+
More general, non-JVM specific interactions with other languages from Python scripts are achieved via the _polyglot_ API.
69+
This includes all interactions with dynamic languages supported via the [Truffle framework](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/), including JavaScript and Ruby.
8370

8471
### Installing other dynamic languages
8572

8673
Other languages can be included by using their respective Maven dependencies in the same manner as GraalPy.
87-
For example, if you have already configured a Maven project with GraalPy, add the following dependency to gain access to
88-
JavaScript:
89-
74+
For example, if you have already configured a Maven project with GraalPy, add the following dependency to gain access to JavaScript:
9075
```xml
91-
9276
<dependency>
9377
<groupId>org.graalvm.polyglot</groupId>
9478
<artifactId>js</artifactId>
@@ -128,14 +112,13 @@ libexec/graalpy-polyglot-get js
128112
Math = polyglot.import_value("JSMath")
129113
```
130114

131-
This global value should then work as expected:
115+
This global value should then work as expected:
132116
* Accessing attributes reads from the *polyglot members* namespace:
133117
```python
134118
assert Math.E == 2.718281828459045
135119
```
136120

137-
* Calling a method on the result attempts to do a straight `invoke` and falls back to reading the member and trying
138-
to execute it.
121+
* Calling a method on the result attempts to do a straight `invoke` and falls back to reading the member and trying to execute it.
139122
```python
140123
assert Math.toString() == "[object Math]"
141124
```
@@ -158,21 +141,18 @@ libexec/graalpy-polyglot-get js
158141
assert "Graal.js" in md[1]
159142
```
160143

161-
This program matches Python strings using the JavaScript regular expression object. Python reads the captured group
162-
from the JavaScript result and checks for a substring in it.
144+
This program matches Python strings using the JavaScript regular expression object. Python reads the captured group from the JavaScript result and checks for a substring in it.
163145

164146
## Exporting Python Objects to other Languages
165147

166-
The `polyglot` module can be used to expose Python objects to JVM languages and other Graal languages (languages
167-
implemented on
168-
the [Truffle framework](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/)).
148+
The `polyglot` module can be used to expose Python objects to JVM languages and other Graal languages (languages implemented on the [Truffle framework](https://www.graalvm.org/latest/graalvm-as-a-platform/language-implementation-framework/)).
169149

170150
1. You can export some object from Python to other languages so they can import it:
171151
```python
172152
import ssl
173153
polyglot.export_value(value=ssl, name="python_ssl")
174154
```
175-
155+
176156
Then use it in (for example) from JavaScript code:
177157
```js
178158
Polyglot.import('python_ssl).get_server_certificate(["oracle.com", 443])
@@ -207,24 +187,21 @@ the [Truffle framework](https://www.graalvm.org/latest/graalvm-as-a-platform/lan
207187
208188
## Mapping Types between Python and Other Languages
209189
210-
The interop protocol defines different "types" which can overlap in all kinds of ways and have restrictions on how they
211-
can interact with Python.
190+
The interop protocol defines different "types" which can overlap in all kinds of ways and have restrictions on how they can interact with Python.
212191
213192
### Interop Types to Python
214193
215194
Most importantly and upfront: all foreign objects passed into Python have the Python type `foreign`.
216195
There is no emulation of (for example) objects that are of interop type "boolean" to have the Python type `bool`.
217-
This is because interop types can overlap in ways that the Python built-in types cannot, and we have yet to define which
218-
type should take precedence and such situations.
196+
This is because interop types can overlap in ways that the Python built-in types cannot, and we have yet to define which type should take precedence and such situations.
219197
We do expect to change this in the future, however.
220-
For now, the `foreign` type defines all of the Python special methods for type conversion that are used throughout the
221-
interpreter (methods such as `__add__`, `__int__`, `__str__`, `__getitem__`, and so on)
198+
For now, the `foreign` type defines all of the Python special methods for type conversion that are used throughout the interpreter (methods such as `__add__`, `__int__`, `__str__`, `__getitem__`, and so on)
222199
and these try to "do the right thing" based on the interop type (or raise an exception).
223200
224201
Types not listed in the table below have no special interpretation in Python.
225202
226-
| Interop Type | Python Interpretation |
227-
|:---------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
203+
| Interop Type | Python Interpretation |
204+
|:--------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
228205
| `null` | `null` is like `None`. Important to know: interop `null` values are all identical to `None`. JavaScript defines two "null-like" values; `undefined` and `null`, which are *not* identical, but when passed to Python, they are treated so. |
229206
| `boolean` | `boolean` behaves like Python booleans, including the fact that in Python, all booleans are also integers (1 and 0 for true and false, respectively). |
230207
| `number` | `number` Behaves like Python numbers. Python only has one integer and one floating point type, but ranges are imported in some places such as typed arrays. |
@@ -238,12 +215,12 @@ Types not listed in the table below have no special interpretation in Python.
238215
| `exception` | An `exception` can be caught in a generic `except` clause. |
239216
| `MetaObject` | Meta objects can be used in subtype and `isinstance` checks. |
240217
| `executable` | An `executable` object can be executed as a function, but never with keyword arguments. |
241-
| `instantiable` | An `instantiable` object can be called just like a Python type, but never with keyword arguments. |
218+
| `instantiable` | An `instantiable` object can be called just like a Python type, but never with keyword arguments. |
242219

243220
### Python to Interop Types
244221

245-
| Interop Type | Python Interpretation |
246-
|:---------------|:------------------------------------------------------------------------------------------------------------------------------------------------------|
222+
| Interop Type | Python Interpretation |
223+
|:--------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
247224
| `null` | Only `None`. |
248225
| `boolean` | Only subtypes of Python `bool`. Note that in contrast to Python semantics, Python `bool` is *never* also an interop number. |
249226
| `number` | Only subtypes of `int` and `float`. |
@@ -260,20 +237,18 @@ Types not listed in the table below have no special interpretation in Python.
260237

261238
## The Interoperability Extension API
262239

263-
It is possible to extend the interoperability protocol directly from Python via a simple API defined in the `polyglot`
264-
module.
265-
The purpose of this API is to enable custom / user defined types to take part in the interop ecosystem.
266-
This is particularly useful for external types which are not compatible by default with the interop protocol.
267-
An example in this sense are the `numpy` numeric types (for example, `numpy.int32`) which are not supported by default
268-
by the interop protocol.
240+
It is possible to extend the interoperability protocol directly from Python via a simple API defined in the `polyglot` module.
241+
The purpose of this API is to enable custom / user defined types to take part in the interop ecosystem.
242+
This is particularly useful for external types which are not compatible by default with the interop protocol.
243+
An example in this sense are the `numpy` numeric types (for example, `numpy.int32`) which are not supported by default by the interop protocol.
269244

270-
### The API
245+
### The API
271246

272-
| Function | Description |
273-
|:--------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
274-
| register_interop_behavior | Takes the receiver **type** as first argument. The remainder keyword arguments correspond to the [respective interop messages](#supported-messages). Not All interop messages are supported. |
275-
| get_registered_interop_behavior | Takes the receiver **type** as first argument. Returns the list of extended interop messages for the given type. |
276-
| @interop_behavior | Class decorator, takes the receiver **type** as only argument. The interop messages are extended via **static** methods defined in the decorated class (supplier). |
247+
| Function | Description |
248+
|:--------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
249+
| register_interop_behavior | Takes the receiver **type** as first argument. The remainder keyword arguments correspond to the respective interop messages. Not All interop messages are supported. |
250+
| get_registered_interop_behavior | Takes the receiver **type** as first argument. Returns the list of extended interop messages for the given type. |
251+
| @interop_behavior | Class decorator, takes the receiver **type** as only argument. The interop messages are extended via **static** methods defined in the decorated class (supplier). |
277252
| register_interop_type | Takes a `foreign class` and `python class` as positional arguments and `allow_method_overwrites` as optional argument (default: `False`). Every instance of foreign class is then treated as an instance of the given python class. |
278253
| @interop_type | Class decorator, takes the `foreign class` and optionally `allow_method_overwrites` as arguments. The instances of foreign class will be treated as an instance of the annotated python class. |
279254

0 commit comments

Comments
 (0)