or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

context-management.mdengine-language-management.mdindex.mdjava-python-interop.mdsecurity-access-control.mdsource-management.mdvalue-operations.md
tile.json

tessl/maven-org-graalvm-polyglot--python

GraalVM Polyglot API for embedding and executing Python code within Java applications.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.graalvm.polyglot/python@23.1.x

To install, run

npx @tessl/cli install tessl/maven-org-graalvm-polyglot--python@23.1.0

index.mddocs/

GraalVM Polyglot API for Python

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.

Package Information

  • Package Name: org.graalvm.polyglot
  • Package Type: maven
  • Language: Java
  • Installation: Add dependency to your Maven/Gradle project:
<dependency>
    <groupId>org.graalvm.polyglot</groupId>
    <artifactId>polyglot</artifactId>
    <version>23.1.3</version>
</dependency>

Core Imports

import org.graalvm.polyglot.Context;
import org.graalvm.polyglot.Engine;
import org.graalvm.polyglot.Value;
import org.graalvm.polyglot.Source;
import org.graalvm.polyglot.HostAccess;
import org.graalvm.polyglot.PolyglotException;

Basic Usage

import org.graalvm.polyglot.Context;
import org.graalvm.polyglot.Value;

// Create a context for Python execution
try (Context context = Context.create("python")) {
    // Evaluate Python code
    Value result = context.eval("python", "2 + 3");
    int sum = result.asInt(); // 5
    
    // Execute Python functions
    context.eval("python", 
        "def greet(name):\n" +
        "    return f'Hello, {name}!'"
    );
    
    Value greetFunction = context.getBindings("python").getMember("greet");
    Value greeting = greetFunction.execute("Alice");
    String message = greeting.asString(); // "Hello, Alice!"
    
    // Work with Python objects
    context.eval("python",
        "class Person:\n" +
        "    def __init__(self, name, age):\n" +
        "        self.name = name\n" +
        "        self.age = age\n" +
        "    def get_info(self):\n" +
        "        return f'{self.name} is {self.age} years old'"
    );
    
    Value personClass = context.getBindings("python").getMember("Person");
    Value person = personClass.newInstance("Bob", 30);
    Value info = person.getMember("get_info").execute();
    System.out.println(info.asString()); // "Bob is 30 years old"
}

Architecture

The GraalVM Polyglot API is built around several key components:

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

Capabilities

Context Management

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

public final class Context implements AutoCloseable {
    public static Context create(String... permittedLanguages);
    public static Builder newBuilder(String... permittedLanguages);
    public Value eval(String languageId, CharSequence source);
    public Value eval(Source source);
    public void close();
}

Context Management

Value Operations

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

public final class Value {
    // Type checking
    public boolean isNull();
    public boolean isNumber();
    public boolean isString();
    public boolean isBoolean();
    
    // Conversion methods
    public boolean asBoolean();
    public int asInt();
    public long asLong();
    public double asDouble();
    public String asString();
    public <T> T asHostObject();
    
    // Object member access
    public boolean hasMembers();
    public Value getMember(String key);
    public void putMember(String key, Object value);
    public Set<String> getMemberKeys();
    
    // Array operations
    public boolean hasArrayElements();
    public Value getArrayElement(long index);
    public void setArrayElement(long index, Object value);
    public long getArraySize();
    
    // Execution
    public boolean canExecute();
    public Value execute(Object... arguments);
    public boolean canInstantiate();
    public Value newInstance(Object... arguments);
}

Value Operations

Source Management

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

public final class Source {
    public static Builder newBuilder(String language, CharSequence characters, String name);
    public static Source create(String language, CharSequence source);
    public static String findLanguage(File file);
    public String getLanguage();
    public String getName();
    public CharSequence getCharacters();
}

Source Management

Security and Access Control

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

public final class HostAccess {
    public static final HostAccess EXPLICIT;
    public static final HostAccess ALL;
    public static final HostAccess NONE;
    public static final HostAccess CONSTRAINED;
    public static Builder newBuilder();
}

public enum SandboxPolicy {
    TRUSTED, CONSTRAINED, ISOLATED, UNTRUSTED
}

Security and Access Control

Java-Python Interoperability

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

// Core proxy interfaces
public interface ProxyObject extends Proxy {
    Object getMember(String key);
    Object getMemberKeys();
    boolean hasMember(String key);
    void putMember(String key, Value value);
}

public interface ProxyArray extends Proxy {
    Object get(long index);
    void set(long index, Value value);
    long getSize();
}

public interface ProxyExecutable extends Proxy {
    Object execute(Value... arguments);
}

Java-Python Interoperability

Engine and Language Management

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

public final class Engine implements AutoCloseable {
    public static Engine create();
    public static Builder newBuilder();
    public Map<String, Language> getLanguages();
    public Map<String, Instrument> getInstruments();
    public String getVersion();
    public void close();
}

public final class Language {
    public String getId();
    public String getName();
    public String getVersion();
    public Set<String> getMimeTypes();
    public boolean isInteractive();
}

Engine and Language Management

Types

// Core builder interfaces
public static final class Context.Builder {
    public Builder allowHostAccess(HostAccess config);
    public Builder allowPolyglotAccess(PolyglotAccess config);
    public Builder allowIO(IOAccess config);
    public Builder sandbox(SandboxPolicy policy);
    public Builder option(String key, String value);
    public Context build();
}

public static final class Engine.Builder {
    public Builder allowExperimentalOptions(boolean enabled);
    public Builder option(String key, String value);
    public Engine build();
}

// Exception handling
public final class PolyglotException extends RuntimeException {
    public boolean isGuestException();
    public boolean isHostException();
    public boolean isSyntaxError();
    public boolean isIncompleteSource();
    public SourceSection getSourceLocation();
}

// Source section for error reporting
public final class SourceSection {
    public boolean isAvailable();
    public Source getSource();
    public int getStartLine();
    public int getEndLine();
    public CharSequence getCharacters();
}