[GR-57413] Cleanup of exposed embedding APIs.

PullRequest: graalpython/3633

Author: tomasstupka

CHANGELOG.md

@@ -21,6 +21,11 @@ language runtime. The main focus is on user-observable behavior of the engine.
 * Remove experimental `SetupLLVMLibraryPaths` option. It was used to pre-set library path for LLVM toolchain's libc++. The path can still be set manually.
 * Added `GRAALPY_VERSION` and `GRAALPY_VERSION_NUM` C macros
 * Added experimental `python.IsolateNativeModules` option to allow loading native extensions multiple times in different contexts. See [the documentation](https://github.com/oracle/graalpython/blob/master/docs/user/Native-Extensions.md) for more information.
+* GraalPy Embedding:
+  * Introduced new types: KeywordArguments and PositionalArguments, in the GraalPy Embedding library (org.graalvm.python:python-embedding), to support directly passing [keyword and positional arguments](https://docs.python.org/3/glossary.html#term-argument) from Java to Python.
+  * Deprecated the org.graalvm.python.embedding.util API package and added new equivalents to org.graalvm.python.embedding
+  * Maven and Gradle plugins do not embed Python home into the generated virtual filesystem. Instead, the handling of language home for any Truffle language, including GraalPy, for the GraalVM Native Image build can be controlled by new Native Image options +H:IncludeLanguageResources and +H:CopyLanguageResources. By default, the whole Python home is embedded into the native executable. In the case of JVM deployment, the language home is embedded in the GraalPy artifacts at Mavencentral.
+  * Removed deprecated methods in VirtualFileSystem
 
 ## Version 24.1.0
 * GraalPy is now considered stable for pure Python workloads. While many workloads involving native extension modules work, we continue to consider them experimental. You can use the command-line option `--python.WarnExperimentalFeatures` to enable warnings for such modules at runtime. In Java embeddings the warnings are enabled by default and you can suppress them by setting the context option 'python.WarnExperimentalFeatures' to 'false'.

docs/user/README.md

@@ -147,7 +147,7 @@ In order to distribute the resulting application for other systems, follow these
       package interop;
    
       import org.graalvm.polyglot.*;
-      import org.graalvm.python.embedding.utils.GraalPyResources;
+      import org.graalvm.python.embedding.GraalPyResources;
    
       class App {
       ...

graalpython/com.oracle.graal.python.test.integration/src/com/oracle/graal/python/test/integration/interop/ArgumentsTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2024, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0

graalpython/com.oracle.graal.python.test.integration/src/org/graalvm/python/embedding/utils/test/integration/GraalPyResourcesTests.java renamed to graalpython/com.oracle.graal.python.test.integration/src/org/graalvm/python/embedding/test/integration/GraalPyResourcesTests.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2024, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -38,11 +38,11 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-package org.graalvm.python.embedding.utils.test.integration;
+package org.graalvm.python.embedding.test.integration;
 
 import org.graalvm.polyglot.Engine;
-import org.graalvm.python.embedding.utils.GraalPyResources;
-import org.graalvm.python.embedding.utils.VirtualFileSystem;
+import org.graalvm.python.embedding.GraalPyResources;
+import org.graalvm.python.embedding.VirtualFileSystem;
 import org.junit.Test;
 
 import java.nio.file.Path;

graalpython/com.oracle.graal.python.test.integration/src/org/graalvm/python/embedding/test/integration/GraalPyResourcesUtilsTests.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright (c) 2024, 2025, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * The Universal Permissive License (UPL), Version 1.0
+ *
+ * Subject to the condition set forth below, permission is hereby granted to any
+ * person obtaining a copy of this software, associated documentation and/or
+ * data (collectively the "Software"), free of charge and under any and all
+ * copyright rights in the Software, and any and all patent rights owned or
+ * freely licensable by each licensor hereunder covering either (i) the
+ * unmodified Software as contributed to or provided by such licensor, or (ii)
+ * the Larger Works (as defined below), to deal in both
+ *
+ * (a) the Software, and
+ *
+ * (b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+ * one is included with the Software each a "Larger Work" to which the Software
+ * is contributed by such licensors),
+ *
+ * without restriction, including without limitation the rights to copy, create
+ * derivative works of, display, perform, and distribute the Software and make,
+ * use, sell, offer for sale, import, export, have made, and have sold the
+ * Software and the Larger Work(s), and to sublicense the foregoing rights on
+ * either these or other terms.
+ *
+ * This license is subject to the following condition:
+ *
+ * The above copyright notice and either this complete permission notice or at a
+ * minimum a reference to the UPL must be included in all copies or substantial
+ * portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+package org.graalvm.python.embedding.test.integration;
+
+import org.graalvm.polyglot.Engine;
+import org.graalvm.python.embedding.utils.GraalPyResources;
+import org.graalvm.python.embedding.utils.VirtualFileSystem;
+import org.junit.Test;
+
+import java.nio.file.Path;
+
+/**
+ * Siple copy of GraalPyResourcesTests to test also the deprecated
+ * org.graalvm.python.embedding.utils pkg
+ */
+public class GraalPyResourcesUtilsTests {
+
+    @Test
+    public void sharedEngine() {
+        // simply check if we are able to create a context with a shared engine
+        Engine sharedEngine = Engine.newBuilder().build();
+        GraalPyResources.contextBuilder().engine(sharedEngine).build().close();
+        GraalPyResources.contextBuilder().engine(sharedEngine).build().close();
+        GraalPyResources.contextBuilder(Path.of("test")).engine(sharedEngine).build().close();
+        GraalPyResources.contextBuilder(VirtualFileSystem.newBuilder().build()).engine(sharedEngine).build().close();
+    }
+}

graalpython/com.oracle.graal.python.test.integration/src/org/graalvm/python/embedding/utils/test/integration/VirtualFileSystemIntegrationTest.java renamed to graalpython/com.oracle.graal.python.test.integration/src/org/graalvm/python/embedding/test/integration/VirtualFileSystemIntegrationTest.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2023, 2024, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2023, 2025, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * The Universal Permissive License (UPL), Version 1.0
@@ -39,16 +39,16 @@
  * SOFTWARE.
  */
 
-package org.graalvm.python.embedding.utils.test.integration;
+package org.graalvm.python.embedding.test.integration;
 
 import org.graalvm.polyglot.Context;
 import org.graalvm.polyglot.Context.Builder;
 import org.graalvm.polyglot.HostAccess;
 import org.graalvm.polyglot.PolyglotException;
 import org.graalvm.polyglot.Value;
 import org.graalvm.polyglot.io.IOAccess;
-import org.graalvm.python.embedding.utils.GraalPyResources;
-import org.graalvm.python.embedding.utils.VirtualFileSystem;
+import org.graalvm.python.embedding.GraalPyResources;
+import org.graalvm.python.embedding.VirtualFileSystem;
 import org.junit.Test;
 
 import java.io.BufferedReader;