You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The GraalPy **Maven** and **Gradle** plugins provide functionality to manage Python related resources typically
10
+
The GraalPy **Maven** and **Gradle** plugins provide functionality to manage Python related resources
11
11
required for embedding Python code in Java-based applications:
12
-
13
12
-*Python application files* provided by the user, for example, Python sources which are part of the project.
14
-
-*Third-party Python packages*: installed by the plugin during the build according to the plugin configuration.
13
+
-*Third-party Python packages* installed by the plugin during the build according to the plugin configuration.
15
14
-*The Python standard library*, which is necessary to make Native Image generated executables self-contained.
16
15
17
-
Apart from physically managing and deploying those files, it is also necessary to make them available in Python
18
-
at runtime by configuring the **GraalPy Context** in your Java code accordingly. [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) provides
19
-
factory methods to create a Context preconfigured for accessing Python embedding relevant resources with
20
-
a **Virtual Filesystem** or from a dedicated **external directory**.
16
+
Apart from physically managing and deploying those files, it is also necessary to make them available in Python at runtime by configuring the **GraalPy Context** in your Java code accordingly.
17
+
The [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) API provides factory methods to create a Context preconfigured for accessing Python, embedding relevant resources with a **Virtual Filesystem** or from a dedicated **external directory**.
21
18
22
19
## Deployment
23
20
24
-
There are two modes how to deploy the resources: as Java resources using the Virtual Filesystem
25
-
to access them in Python, or as an external directory.
21
+
There are two modes how to deploy the resources: as Java resources using the Virtual Filesystem to access them in Python, or as an external directory.
26
22
27
23
### Virtual Filesystem
28
24
29
25
The Python related resources are embedded in the application file, either in JAR or Native Image generated
30
-
executable, as standard Java resources. The GraalPy Virtual Filesystem accesses resource files as standard
31
-
Java resources and makes them available to Python code running in GraalPy. This is transparent to the Python code,
32
-
which can use standard Python IO to access those files.
26
+
executable, as standard Java resources.
27
+
The GraalPy Virtual Filesystem accesses resource files as standard Java resources and makes them available to Python code running in GraalPy.
28
+
This is transparent to the Python code, which can use standard Python IO to access those files.
33
29
34
30
Java resource files in a Maven or Gradle project are typically located in dedicated resources directories.
35
-
All resources subdirectories named `org.graalvm.python.vfs` are merged and mapped to a configurable
36
-
virtual filesystem mount point at the Python side, by default `/graalpy_vfs`. For example,
37
-
a Python file with the real filesystem path
38
-
`${project_resources_directory}/org.graalvm.python.vfs/src/foo/bar.py` will be accessible as
39
-
`/graalpy_vfs/src/foo/bar.py` in Python.
31
+
All resources subdirectories named _org.graalvm.python.vfs_ are merged and mapped to a configurable Virtual Filesystem mount point at the Python side, by default `/graalpy_vfs`.
32
+
For example, a Python file with the real filesystem path `${project_resources_directory}/org.graalvm.python.vfs/src/foo/bar.py` will be accessible as `/graalpy_vfs/src/foo/bar.py` in Python.
40
33
41
34
Use the following [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java)
42
35
factory methods to create GraalPy Context preconfigured for the use of the Virtual Filesystem:
As an alternative to Java resources with the Virtual Filesystem, it is also possible to configure the Maven
51
-
or Gradle plugin to manage the contents of an external directory, which will **not be embedded** as Java resource
52
-
into the resulting application. The user is then responsible for the deployment of such directory. Python code
53
-
will access the files directly from the real filesystem.
54
-
55
-
Use the following [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java)
56
-
factory methods to create GraalPy Context preconfigured for the use of an external directory:
42
+
As an alternative to Java resources with the Virtual Filesystem, it is also possible to configure the Maven or Gradle plugin to manage the contents of an external directory, which will **not be embedded** as a Java resource into the resulting application.
43
+
A user is then responsible for the deployment of such directory.
44
+
Python code will access the files directly from the real filesystem.
57
45
46
+
Use the following [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) factory methods to create GraalPy Context preconfigured for the use of an external directory:
58
47
*`GraalPyResources.createContextBuilder(Path)`
59
48
60
49
## Conventions
61
50
62
-
The factory methods in [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) rely on the following conventions, where the `${root}` is either
63
-
the external directory, or the Virtual System mount point on the Python side and
64
-
`${project_resources_directory}/org.graalvm.python.vfs` on the real filesystem:
65
-
66
-
-`${root}/src`: used for Python application files. This directory will be configured as the default
67
-
search path for Python module files (equivalent of `PYTHONPATH` environment variable).
68
-
-`${root}/venv`: used for the Python virtual environment holding installed third-party Python packages.
69
-
The Context will be configured as if it were executed from this virtual environment. Notably packages installed in this
51
+
The factory methods in [GraalPyResources](https://github.com/oracle/graalpython/blob/master/graalpython/org.graalvm.python.embedding/src/org/graalvm/python/embedding/utils/GraalPyResources.java) rely on the following conventions, where the `${root}` is either an external directory, or a Virtual System mount point on the Python side and `${project_resources_directory}/org.graalvm.python.vfs` on the real filesystem:
52
+
-`${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).
53
+
-`${root}/venv`: used for the Python virtual environment holding installed third-party Python packages.
54
+
The Context will be configured as if it is executed from this virtual environment. Notably packages installed in this
70
55
virtual environment will be automatically available for importing.
71
-
-`${root}/home`: used for the Python standard library (equivalent of`PYTHONHOME` environment variable).
56
+
-`${root}/home`: used for the Python standard library (equivalent to`PYTHONHOME` environment variable).
72
57
73
-
The Maven or Gradle plugin will fully manage the contents of the `vevn` and `home` subdirectories.
58
+
The Maven or Gradle plugin will fully manage the contents of the `venv` and `home` subdirectories.
74
59
Any manual changes in these directories will be overridden by the plugin during the build.
75
-
76
-
-`${root}/venv`: the plugin creates virtual environment and installs required packages according
77
-
to the plugin configuration in `pom.xml` or `build.gradle`.
60
+
-`${root}/venv`: the plugin creates a virtual environment and installs required packages according to the plugin configuration in _pom.xml_ or _build.gradle_.
78
61
-`${root}/home`: the plugin copies the required (also configurable) parts of the Python standard library into this directory.
79
62
By default, the full standard library is used.
80
63
81
-
The `src` subdirectory is left to be manually populated by the user with custom Python scripts or modules.
64
+
The _src_ subdirectory is left to be manually populated by the user with custom Python scripts or modules.
82
65
83
66
## GraalPy Maven Plugin Configuration
84
67
@@ -92,77 +75,79 @@ Add the plugin configuration in the `configuration` block of `graalpy-maven-plug
92
75
...
93
76
</configuration>
94
77
...
78
+
</plugin>
95
79
```
96
-
97
80
The **packages** element declares a list of third-party Python packages to be downloaded and installed by the plugin.
98
-
- The Python packages and their versions are specified as if used with `pip`.
99
-
```xml
100
-
<configuration>
101
-
<packages>
102
-
<package>termcolor==2.2</package>
103
-
...
104
-
</packages>
105
-
...
106
-
</configuration>
107
-
```
81
+
- The Python packages and their versions are specified as if used with `pip`:
82
+
```xml
83
+
<configuration>
84
+
<packages>
85
+
<package>termcolor==2.2</package>
86
+
...
87
+
</packages>
88
+
...
89
+
</configuration>
90
+
```
108
91
- The **pythonHome** subsection declares what parts of the standard library should be deployed.
109
92
110
93
Each `include` and `exclude` element is interpreted as a Java-like regular expression specifying which file paths should be included or excluded.
111
-
112
-
```xml
113
-
<configuration>
114
-
<pythonHome>
115
-
<includes>
116
-
<include>.*</include>
117
-
...
118
-
</includes>
119
-
<excludes>
120
-
<exclude></exclude>
121
-
...
122
-
</excludes>
123
-
</pythonHome>
124
-
...
125
-
</configuration>
126
-
```
127
-
- If the **pythonResourcesDirectory** element is specified, then the given directory is used
128
-
as [external directory](#external-directory) and no Java resources are embedded.
94
+
```xml
95
+
<configuration>
96
+
<pythonHome>
97
+
<includes>
98
+
<include>.*</include>
99
+
...
100
+
</includes>
101
+
<excludes>
102
+
<exclude></exclude>
103
+
...
104
+
</excludes>
105
+
</pythonHome>
106
+
...
107
+
</configuration>
108
+
```
109
+
- If the **pythonResourcesDirectory** element is specified, then the given directory is used as an [external directory](#external-directory) and no Java resources are embedded.
129
110
Remember to use the appropriate `GraalPyResources` API to create the Context.
Add the plugin configuration in the `GraalPy` block in the _build.gradle_ file:
120
+
Add the plugin configuration in the `GraalPy` block in the _build.gradle_ file.
140
121
The **packages** element declares a list of third-party Python packages to be downloaded and installed by the plugin.
141
122
- The Python packages and their versions are specified as if used with `pip`.
142
-
```
143
-
GraalPy {
144
-
packages = ["termcolor==2.2"]
145
-
...
146
-
}
147
-
```
148
-
-the**pythonHome** subsection declares what parts of the standard library should be deployed.
123
+
```
124
+
graalPy {
125
+
packages = ["termcolor==2.2"]
126
+
...
127
+
}
128
+
```
129
+
-The**pythonHome** subsection declares what parts of the standard library should be deployed.
149
130
150
131
Each element in the `includes` and `excludes` list is interpreted as a Java-like regular expression specifying which file paths should be included or excluded.
151
-
```
152
-
GraalPy {
153
-
pythonHome {
154
-
includes = [".*"]
155
-
excludes = []
132
+
```
133
+
graalPy {
134
+
pythonHome {
135
+
includes = [".*"]
136
+
excludes = []
137
+
}
138
+
...
156
139
}
157
-
...
158
-
}
159
-
```
160
-
- If the **pythonResourcesDirectory** element is specified, then the given directory is used
161
-
as [external directory](#external-directory) and no Java resources are embedded.
162
-
Remember to use the appropriate `GraalPyResources` API to create the Context.
- If the **pythonResourcesDirectory** element is specified, then the given directory is used as an [external directory](#external-directory) and no Java resources are embedded.
142
+
Remember to use the appropriate `GraalPyResources` API to create the Context.
0 commit comments