Class GraalPyResources

java.lang.Object
org.graalvm.python.embedding.GraalPyResources
public final class GraalPyResources extends Object
This class provides utilities related to Python resources used in GraalPy embedding scenarios which can be of the following kind:
  • Python application files
  • Third-party Python packages

Resource files can be embedded and distributed in an application file or made available from an external directory.

Virtual Filesystem

If the resource files are part of an application file (jar file or a native image executable), then at runtime they will be accessed as standard Java resources through GraalPy VirtualFileSystem. This will be transparent to Python code running in GraalPy so that it can use standard Python IO to access those files.

In order to make this work, it is necessary for those embedded resources to have their root directory set to /org.graalvm.python.vfs which in python code will be mapped to the virtual filesystem mount point, by default /graalpy_vfs. Refer to VirtualFileSystem.Builder documentation for more details.

External Directory

As an alternative to Java resources with the Virtual Filesystem, it is also possible to configure the GraalPy context to use an external directory, which is not embedded as a Java resource into the resulting application. Python code will access the files directly from the real filesystem.

Conventions

The factory methods in GraalPyResources rely on the following conventions:

  • ${resources_root}/src: used for Python application files. This directory will be configured as the default search path for Python module files (equivalent to PYTHONPATH environment variable).
  • ${resources_root}/venv: used for the Python virtual environment holding installed third-party Python packages. The Context will be configured as if it is executed from this virtual environment. Notably packages installed in this virtual environment will be automatically available for importing.
where ${resources_root} is either the resource root /org.graalvm.python.vfs or an external directory.

Example creating a GraalPy context configured for the usage with a VirtualFileSystem: 

 VirtualFileSystem.Builder builder = VirtualFileSystem.newBuilder();
 builder.unixMountPoint("/python-resources");
 VirtualFileSystem vfs = builder.build();
 try (Context context = GraalPyResources.contextBuilder(vfs).build()) {
     context.eval("python", "for line in open('/python-resources/data.txt').readlines(): print(line)");
 } catch (PolyglotException e) {
     if (e.isExit()) {
         System.exit(e.getExitStatus());
     } else {
         throw e;
     }
 }
In this example we:
  • create a VirtualFileSystem configured to have the root /python-resources
  • create a GraalPy context preconfigured with that VirtualFileSystem
  • use the context to invoke a python snippet reading a resource file

GraalPy context instances created by factory methods in this class are preconfigured with some particular resource paths:

  • ${resources_root}/venv - is reserved for a python virtual environment holding third-party packages. The context will be configured as if it were executed from this virtual environment. Notably packages installed in this virtual environment will be automatically available for importing.
  • ${resources_root}/src - is reserved for python application files - e.g. python sources. GraalPy context will be configured to see those files as if set in PYTHONPATH environment variable.
    • where ${resources_root} is either an external directory or the virtual filesystem resource root /org.graalvm.python.vfs.

    Example creating a GraalPy context configured for the usage with an external resource directory: 

     try (Context context = GraalPyResources.contextBuilder(Path.of("python-resources")).build()) {
     context.eval("python", "import mymodule; mymodule.print_hello_world()");
 } catch (PolyglotException e) {
     if (e.isExit()) {
         System.exit(e.getExitStatus());
     } else {
         throw e;
     }
 }
    In this example we:
    • create a GraalPy context which is preconfigured with GraalPy resources in an external resource directory
    • use the context to import the python module mymodule, which should be either located in python-resources/src or in a python package installed in python-resources/venv (python virtual environment)

    For more examples on how to use this class refer to GraalPy Demos and Guides.
    Since:
    24.2.0
    See Also:

    • Method Summary

      Modifier and Type
      Method
      Description
      static org.graalvm.polyglot.Context.Builder
      contextBuilder()
      Creates a GraalPy context builder preconfigured with a VirtualFileSystem and other GraalPy and polyglot Context configuration options optimized for the usage of the Python virtual environment contained in the virtual filesystem.
      static org.graalvm.polyglot.Context.Builder
      contextBuilder(Path externalResourcesDirectory)
      Creates a GraalPy context preconfigured with GraalPy and polyglot Context configuration options for use with resources located in an external directory in real filesystem.
      static org.graalvm.polyglot.Context.Builder
      contextBuilder(VirtualFileSystem vfs)
      Creates a GraalPy context builder preconfigured with the given VirtualFileSystem and other GraalPy and polygot Context configuration options optimized for the usage of the Python virtual environment contained in the virtual filesystem.
      static org.graalvm.polyglot.Context
      createContext()
      Creates a GraalPy context preconfigured with a VirtualFileSystem and other GraalPy and polyglot Context configuration options optimized for the usage of the Python virtual environment contained in the virtual filesystem.
      static void
      extractVirtualFileSystemResources(VirtualFileSystem vfs, Path externalResourcesDirectory)
      Extract Python resources which are distributed as part of a jar file or a native image executable into a directory.
      static Path
      getNativeExecutablePath()
      Determines a native executable path if running in ImageInfo.inImageRuntimeCode().

      Methods inherited from class java.lang.Object

      clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Details

      • createContext

        public static org.graalvm.polyglot.Context createContext()
        Creates a GraalPy context preconfigured with a VirtualFileSystem and other GraalPy and polyglot Context configuration options optimized for the usage of the Python virtual environment contained in the virtual filesystem.

        Following resource paths are preconfigured:

        • /org.graalvm.python.vfs/venv - is set as the python virtual environment location
        • /org.graalvm.python.vfs/src - is set as the python sources location

        When the virtual filesystem is located in other than the default resource directory, org.graalvm.python.vfs, i.e., using Maven or Gradle option resourceDirectory, use contextBuilder(VirtualFileSystem) and VirtualFileSystem.Builder.resourceDirectory(String) when building the VirtualFileSystem.

        Returns:
        a new Context instance
        Since:
        24.2.0

      • contextBuilder

        public static org.graalvm.polyglot.Context.Builder contextBuilder()
        Creates a GraalPy context builder preconfigured with a VirtualFileSystem and other GraalPy and polyglot Context configuration options optimized for the usage of the Python virtual environment contained in the virtual filesystem.

        Following resource paths are preconfigured:

        • /org.graalvm.python.vfs/venv - is set as the python virtual environment location
        • /org.graalvm.python.vfs/src - is set as the python sources location

        Example creating a GraalPy context and overriding the verbose option. 
         Context.Builder builder = GraalPyResources.contextBuilder().option("python.VerboseFlag", "true");
 try (Context context = builder.build()) {
     context.eval("python", "print('hello world')");
 } catch (PolyglotException e) {
     if (e.isExit()) {
         System.exit(e.getExitStatus());
     } else {
         throw e;
     }
 }

        When the virtual filesystem is located in other than the default resource directory, org.graalvm.python.vfs, i.e., using Maven or Gradle option resourceDirectory, use contextBuilder(VirtualFileSystem) and VirtualFileSystem.Builder.resourceDirectory(String) when building the VirtualFileSystem.

        Returns:
        a new Context.Builder instance
        Since:
        24.2.0
        See Also:

      • contextBuilder

        public static org.graalvm.polyglot.Context.Builder contextBuilder(VirtualFileSystem vfs)
        Creates a GraalPy context builder preconfigured with the given VirtualFileSystem and other GraalPy and polygot Context configuration options optimized for the usage of the Python virtual environment contained in the virtual filesystem.

        Following resource paths are preconfigured:

        • /org.graalvm.python.vfs/venv - is set as the python virtual environment location
        • /org.graalvm.python.vfs/src - is set as the python sources location

        Example creating a GraalPy context configured for the usage with a virtual FileSystem: 

         VirtualFileSystem.Builder vfsBuilder = VirtualFileSystem.newBuilder();
 vfsBuilder.unixMountPoint("/python-resources");
 VirtualFileSystem vfs = vfsBuilder.build();
 Context.Builder ctxBuilder = GraalPyResources.contextBuilder(vfs);
 try (Context context = ctxBuilder.build()) {
     context.eval("python", "for line in open('/python-resources/data.txt').readlines(): print(line)");
 } catch (PolyglotException e) {
     if (e.isExit()) {
         System.exit(e.getExitStatus());
     } else {
         throw e;
     }
 }
        In this example we:
        • create a VirtualFileSystem configured to have the root /python-resources
        • create a GraalPy context preconfigured with that VirtualFileSystem
        • use the context to invoke a python snippet reading a resource file

        Parameters:
        vfs - the VirtualFileSystem to be used with the created Context
        Returns:
        a new Context.Builder instance
        Since:
        24.2.0
        See Also:

      • contextBuilder

        public static org.graalvm.polyglot.Context.Builder contextBuilder(Path externalResourcesDirectory)
        Creates a GraalPy context preconfigured with GraalPy and polyglot Context configuration options for use with resources located in an external directory in real filesystem.

        Following resource paths are preconfigured:

        • ${externalResourcesDirectory}/venv - is set as the python virtual environment location
        • ${externalResourcesDirectory}/src - is set as the python sources location

        Example 

         Context.Builder builder = GraalPyResources.contextBuilder(Path.of("python-resources"));
 try (Context context = builder.build()) {
     context.eval("python", "import mymodule; mymodule.print_hello_world()");
 } catch (PolyglotException e) {
     if (e.isExit()) {
         System.exit(e.getExitStatus());
     } else {
         throw e;
     }
 }
        In this example we:
        • create a GraalPy context which is preconfigured with GraalPy resources in an external resource directory
        • use the context to import the python module mymodule, which should be either located in python-resources/src or in a python package installed in /python/venv (python virtual environment)

        Parameters:
        externalResourcesDirectory - the root directory with GraalPy specific embedding resources
        Returns:
        a new Context.Builder instance
        Since:
        24.2.0

      • getNativeExecutablePath

        public static Path getNativeExecutablePath()
        Determines a native executable path if running in ImageInfo.inImageRuntimeCode().

        Example creating a GraalPy context precofigured with an external resource directory located next to a native image executable. 

         Path resourcesDir = GraalPyResources.getNativeExecutablePath().getParent().resolve("python-resources");
 try (Context context = GraalPyResources.contextBuilder(resourcesDir).build()) {
     context.eval("python", "print('hello world')");
 }

        Returns:
        the native executable path if it could be retrieved, otherwise null.
        Since:
        24.2.0
        See Also:

      • extractVirtualFileSystemResources

        public static void extractVirtualFileSystemResources(VirtualFileSystem vfs, Path externalResourcesDirectory) throws IOException
        Extract Python resources which are distributed as part of a jar file or a native image executable into a directory. This can be useful to manage and ship resources with the Maven workflow, but use them (cached) from the real filesystem for better compatibility.

        The structure of the created resource directory will stay the same like the embedded Python resources structure:

        • ${externalResourcesDirectory}/venv - the python virtual environment location
        • ${externalResourcesDirectory}/src - the python sources location

        Example 

         Path resourcesDir = Path.of(System.getProperty("user.home"), ".cache", "my.java.python.app.resources");
 VirtualFileSystem vfs = VirtualFileSystem.newBuilder().build();
 GraalPyResources.extractVirtualFileSystemResources(vfs, resourcesDir);
 try (Context context = GraalPyResources.contextBuilder(resourcesDir).build()) {
     context.eval("python", "print('hello world')");
 }

        Parameters:
        vfs - the VirtualFileSystem from which resources are to be extracted
        externalResourcesDirectory - the target directory to extract the resources to
        Throws:
        IOException - if resources isn't a directory
        Since:
        24.2.0
        See Also: