0
# GraalVM Polyglot API for Python
1

2
The GraalVM Polyglot API provides a comprehensive framework for embedding and executing Python code within Java applications. It enables seamless interoperability between Python and Java, allowing you to evaluate Python scripts, manipulate Python objects, and exchange data between the two languages with full type safety and security controls.
3

4
## Package Information
5

6
- **Package Name**: org.graalvm.polyglot
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency to your Maven/Gradle project:
10

11
```xml
12
<dependency>
13
    <groupId>org.graalvm.polyglot</groupId>
14
    <artifactId>polyglot</artifactId>
15
    <version>23.1.3</version>
16
</dependency>
17
```
18

19
## Core Imports
20

21
```java
22
import org.graalvm.polyglot.Context;
23
import org.graalvm.polyglot.Engine;
24
import org.graalvm.polyglot.Value;
25
import org.graalvm.polyglot.Source;
26
import org.graalvm.polyglot.HostAccess;
27
import org.graalvm.polyglot.PolyglotException;
28
```
29

30
## Basic Usage
31

32
```java
33
import org.graalvm.polyglot.Context;
34
import org.graalvm.polyglot.Value;
35

36
// Create a context for Python execution
37
try (Context context = Context.create("python")) {
38
    // Evaluate Python code
39
    Value result = context.eval("python", "2 + 3");
40
    int sum = result.asInt(); // 5
41
    
42
    // Execute Python functions
43
    context.eval("python", 
44
        "def greet(name):\n" +
45
        "    return f'Hello, {name}!'"
46
    );
47
    
48
    Value greetFunction = context.getBindings("python").getMember("greet");
49
    Value greeting = greetFunction.execute("Alice");
50
    String message = greeting.asString(); // "Hello, Alice!"
51
    
52
    // Work with Python objects
53
    context.eval("python",
54
        "class Person:\n" +
55
        "    def __init__(self, name, age):\n" +
56
        "        self.name = name\n" +
57
        "        self.age = age\n" +
58
        "    def get_info(self):\n" +
59
        "        return f'{self.name} is {self.age} years old'"
60
    );
61
    
62
    Value personClass = context.getBindings("python").getMember("Person");
63
    Value person = personClass.newInstance("Bob", 30);
64
    Value info = person.getMember("get_info").execute();
65
    System.out.println(info.asString()); // "Bob is 30 years old"
66
}
67
```
68

69
## Architecture
70

71
The GraalVM Polyglot API is built around several key components:
72

73
- **Context**: Isolated execution environment for guest languages with configurable security policies
74
- **Engine**: Shared runtime for multiple contexts, managing language implementations and instruments
75
- **Value**: Universal wrapper providing language-agnostic access to any object from any supported language
76
- **Source**: Abstraction for source code that can be parsed from strings, files, URLs, or streams
77
- **Security Framework**: Comprehensive access control through HostAccess, PolyglotAccess, and SandboxPolicy
78
- **Proxy System**: Bidirectional interoperability interfaces enabling Java objects to masquerade as guest language objects
79

80
## Capabilities
81

82
### Context Management
83

84
Core functionality for creating and managing Python execution contexts with full lifecycle control and security configuration.
85

86
```java { .api }
87
public final class Context implements AutoCloseable {
88
    public static Context create(String... permittedLanguages);
89
    public static Builder newBuilder(String... permittedLanguages);
90
    public Value eval(String languageId, CharSequence source);
91
    public Value eval(Source source);
92
    public void close();
93
}
94
```
95

96
[Context Management](./context-management.md)
97

98
### Value Operations
99

100
Universal value wrapper providing type-safe access to Python objects, with comprehensive type checking, conversion, and manipulation capabilities.
101

102
```java { .api }
103
public final class Value {
104
    // Type checking
105
    public boolean isNull();
106
    public boolean isNumber();
107
    public boolean isString();
108
    public boolean isBoolean();
109
    
110
    // Conversion methods
111
    public boolean asBoolean();
112
    public int asInt();
113
    public long asLong();
114
    public double asDouble();
115
    public String asString();
116
    public <T> T asHostObject();
117
    
118
    // Object member access
119
    public boolean hasMembers();
120
    public Value getMember(String key);
121
    public void putMember(String key, Object value);
122
    public Set<String> getMemberKeys();
123
    
124
    // Array operations
125
    public boolean hasArrayElements();
126
    public Value getArrayElement(long index);
127
    public void setArrayElement(long index, Object value);
128
    public long getArraySize();
129
    
130
    // Execution
131
    public boolean canExecute();
132
    public Value execute(Object... arguments);
133
    public boolean canInstantiate();
134
    public Value newInstance(Object... arguments);
135
}
136
```
137

138
[Value Operations](./value-operations.md)
139

140
### Source Management
141

142
Comprehensive source code handling supporting multiple input formats, automatic language detection, and metadata management.
143

144
```java { .api }
145
public final class Source {
146
    public static Builder newBuilder(String language, CharSequence characters, String name);
147
    public static Source create(String language, CharSequence source);
148
    public static String findLanguage(File file);
149
    public String getLanguage();
150
    public String getName();
151
    public CharSequence getCharacters();
152
}
153
```
154

155
[Source Management](./source-management.md)
156

157
### Security and Access Control
158

159
Advanced security framework providing fine-grained control over host access, inter-language evaluation, and resource usage with multiple sandbox levels.
160

161
```java { .api }
162
public final class HostAccess {
163
    public static final HostAccess EXPLICIT;
164
    public static final HostAccess ALL;
165
    public static final HostAccess NONE;
166
    public static final HostAccess CONSTRAINED;
167
    public static Builder newBuilder();
168
}
169

170
public enum SandboxPolicy {
171
    TRUSTED, CONSTRAINED, ISOLATED, UNTRUSTED
172
}
173
```
174

175
[Security and Access Control](./security-access-control.md)
176

177
### Java-Python Interoperability
178

179
Proxy interfaces enabling seamless bidirectional communication between Java and Python, supporting all major Python data types and programming constructs.
180

181
```java { .api }
182
// Core proxy interfaces
183
public interface ProxyObject extends Proxy {
184
    Object getMember(String key);
185
    Object getMemberKeys();
186
    boolean hasMember(String key);
187
    void putMember(String key, Value value);
188
}
189

190
public interface ProxyArray extends Proxy {
191
    Object get(long index);
192
    void set(long index, Value value);
193
    long getSize();
194
}
195

196
public interface ProxyExecutable extends Proxy {
197
    Object execute(Value... arguments);
198
}
199
```
200

201
[Java-Python Interoperability](./java-python-interop.md)
202

203
### Engine and Language Management
204

205
Engine lifecycle management and language discovery, providing shared runtime capabilities and language metadata access.
206

207
```java { .api }
208
public final class Engine implements AutoCloseable {
209
    public static Engine create();
210
    public static Builder newBuilder();
211
    public Map<String, Language> getLanguages();
212
    public Map<String, Instrument> getInstruments();
213
    public String getVersion();
214
    public void close();
215
}
216

217
public final class Language {
218
    public String getId();
219
    public String getName();
220
    public String getVersion();
221
    public Set<String> getMimeTypes();
222
    public boolean isInteractive();
223
}
224
```
225

226
[Engine and Language Management](./engine-language-management.md)
227

228
## Types
229

230
```java { .api }
231
// Core builder interfaces
232
public static final class Context.Builder {
233
    public Builder allowHostAccess(HostAccess config);
234
    public Builder allowPolyglotAccess(PolyglotAccess config);
235
    public Builder allowIO(IOAccess config);
236
    public Builder sandbox(SandboxPolicy policy);
237
    public Builder option(String key, String value);
238
    public Context build();
239
}
240

241
public static final class Engine.Builder {
242
    public Builder allowExperimentalOptions(boolean enabled);
243
    public Builder option(String key, String value);
244
    public Engine build();
245
}
246

247
// Exception handling
248
public final class PolyglotException extends RuntimeException {
249
    public boolean isGuestException();
250
    public boolean isHostException();
251
    public boolean isSyntaxError();
252
    public boolean isIncompleteSource();
253
    public SourceSection getSourceLocation();
254
}
255

256
// Source section for error reporting
257
public final class SourceSection {
258
    public boolean isAvailable();
259
    public Source getSource();
260
    public int getStartLine();
261
    public int getEndLine();
262
    public CharSequence getCharacters();
263
}
264
```