[GR-52892] Better documentation for embedding Python in a Java application.

[dboggs95]

Describe the issue When I look in the documentation for Java+Python my very first question after getting my project set up is "How do I get my Python dependencies (not the polyglot jars, the actual libraries I'm going to call inside python, like ONNX) installed? Do I put them in Gradle? Can I add a dependencies file? Can I do it in the Java code?" And I can't find any answers.

This is the closest I got: https://www.graalvm.org/latest/reference-manual/python/Python-Runtime/#installing-graalpy

I don't understand how that helps me do anything in Java. That looks like it's standalone Python using GraalVM. I read here I don't need that for running python in Java: https://github.com/oracle/graal/issues/6852

I do see in your docs how to run plain Python code in Java, but I see absolutely nothing about adding dependencies. You need a landing page that has everything--it's headache inducing digging all over Git issues and the internet for this information and finding only half of it.

It needs to be complete: Step 1: Install required minimal version of GraalVM for your OS (I think 21 is required for Windows based on a Git issue I saw somewhere). Step 2: Do this to enable GraalPy in your Java program (Polyglot jars). Step 3: Do this to get Python dependencies (like ONNX) available in Java. Step 4: Start Python context. Here is a list of valid configurations and what they do. Step 5: Execute a py script like this. Step 6: Execute an individual py method like this. Here is how to get the result back on the Java side. Step 7: Run on SVM. Step 8: Compile native (something tells me this part gets more complicated once I have Python dependencies).

Steps to reproduce the issue n/a

Describe GraalVM and your environment:

• GraalVM version: I think I'm using 23.1. I can't tell. It's whatever comes with JDK21.
• JDK major version: 21
• OS: Windows
• Architecture: AMD64

More details n/a

[olyagpl]

hi @dboggs95, We completely overhauled the GraalPy documentation and it's online since March 19. You are interested in a setting up a project, please check the Java/Maven integration is on the main page. Using a Maven archetype is what you need. With Maven you can add additional features to manage Python virtual environments, like we say on the website:

The project uses the GraalVM SDK Polyglot API with additional features to manage Python virtual environments and integrate Python package dependencies with a Maven workflow. The Java code and the pom.xml file are heavily documented and the generated code describes available features. (If you do not wish to use Maven, the archetype Java code also provides guidance to create a custom embedding.)

We might extend the website documentation soon, but for now, it's all in the archetype. The Gradle support is still under development, planned for autumn.

[olyagpl]

Here is a related discussion that you might want to check: https://github.com/oracle/graalpython/issues/389

[dboggs95]

hi @dboggs95, We completely overhauled the GraalPy documentation and it's online since March 19. You are interested in a setting up a project, please check the Java/Maven integration is on the main page. Using a Maven archetype is what you need. With Maven you can add additional features to manage Python virtual environments, like we say on the website:

The project uses the GraalVM SDK Polyglot API with additional features to manage Python virtual environments and integrate Python package dependencies with a Maven workflow. The Java code and the pom.xml file are heavily documented and the generated code describes available features. (If you do not wish to use Maven, the archetype Java code also provides guidance to create a custom embedding.)

We might extend the website documentation soon, but for now, it's all in the archetype. The Gradle support is still under development, planned for autumn.

Thanks for the quick response.

I'm looking in the Javadocs linked in that paragraph, but it's way too generic to figure out how to do this. I don't see anything about importing a python package. I'm assuming it should be under Context, but I don't see anything there either.

[ajh123]

/off topic @dboggs95

The Gradle support is still under development, planned for autumn.

Is there a public beta for the gradle plugin?

[olyagpl]

@timfel should have a better insight about the Gradle support.

[timfel]

hi @dboggs95, We completely overhauled the GraalPy documentation and it's online since March 19. You are interested in a setting up a project, please check the Java/Maven integration is on the main page. Using a Maven archetype is what you need. With Maven you can add additional features to manage Python virtual environments, like we say on the website:

The project uses the GraalVM SDK Polyglot API with additional features to manage Python virtual environments and integrate Python package dependencies with a Maven workflow. The Java code and the pom.xml file are heavily documented and the generated code describes available features. (If you do not wish to use Maven, the archetype Java code also provides guidance to create a custom embedding.)

We might extend the website documentation soon, but for now, it's all in the archetype. The Gradle support is still under development, planned for autumn.

Thanks for the quick response.

I'm looking in the Javadocs linked in that paragraph, but it's way too generic to figure out how to do this. I don't see anything about importing a python package. I'm assuming it should be under Context, but I don't see anything there either.

There are no Javadocs online, just create the Maven project with the archetype, the docs are in the source code of the Java files and the pom.xml - the pom.xml also is where you declare packages to install

[timfel]

/off topic @dboggs95

The Gradle support is still under development, planned for autumn.

Is there a public beta for the gradle plugin?

There's no working Gradle plugin code anywhere at this point. As soon as we have anything, it will appear on the master branch in this repository.