From 5330329bfb230b4aa299b881299bdd85ddec4d26 Mon Sep 17 00:00:00 2001 From: Olga Gupalo Date: Mon, 29 Jun 2026 13:58:37 +0300 Subject: [PATCH] Update docs for changes introduced in GraalPy 25.1.3 --- docs/user/Embedding-Build-Tools.md | 2 +- docs/user/Embedding-Getting-Started.md | 32 +++++++++++++++++++------ docs/user/Interoperability.md | 6 ++++- docs/user/Performance.md | 5 +++- docs/user/Python-on-JVM.md | 12 ++++++++++ docs/user/Standalone-Getting-Started.md | 18 +++++++------- 6 files changed, 56 insertions(+), 19 deletions(-) diff --git a/docs/user/Embedding-Build-Tools.md b/docs/user/Embedding-Build-Tools.md index 0526fb473b..158b17554c 100644 --- a/docs/user/Embedding-Build-Tools.md +++ b/docs/user/Embedding-Build-Tools.md @@ -252,7 +252,7 @@ Add the plugin configuration to your _build.gradle_ file: ```groovy plugins { - id 'org.graalvm.python' version '25.0.3' + id 'org.graalvm.python' version '25.1.3' } graalPy { diff --git a/docs/user/Embedding-Getting-Started.md b/docs/user/Embedding-Getting-Started.md index e97c96ec07..b200f1ea00 100644 --- a/docs/user/Embedding-Getting-Started.md +++ b/docs/user/Embedding-Getting-Started.md @@ -16,7 +16,7 @@ The fastest way to get started is with GraalPy's Maven archetype, which generate mvn archetype:generate \ -DarchetypeGroupId=org.graalvm.python \ -DarchetypeArtifactId=graalpy-archetype-polyglot-app \ - -DarchetypeVersion=25.0.3 + -DarchetypeVersion=25.1.3 ``` This generates the following project structure: @@ -87,8 +87,8 @@ If you prefer Gradle, here is how to set up a new project with GraalPy embedding - Include the GraalPy support and the [GraalVM Polyglot API](https://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) in the `dependencies` section: ```gradle - implementation("org.graalvm.polyglot:polyglot:25.0.3") - implementation("org.graalvm.python:python-embedding:25.0.3") + implementation("org.graalvm.polyglot:polyglot:25.1.3") + implementation("org.graalvm.python:python-embedding:25.1.3") ``` 3. Replace the _App.java_ content with this simple Python embedding example: @@ -134,7 +134,7 @@ Add the Python embedding dependency and GraalPy Maven plugin configuration to yo org.graalvm.python python-embedding - 25.0.3 + 25.1.3 @@ -143,7 +143,7 @@ Add the Python embedding dependency and GraalPy Maven plugin configuration to yo org.graalvm.python graalpy-maven-plugin - 25.0.3 + 25.1.3 @@ -169,11 +169,11 @@ Add the GraalPy Gradle plugin and configure dependencies in _app/build.gradle_: plugins { id "java" id "application" - id "org.graalvm.python" version "25.0.3" + id "org.graalvm.python" version "25.1.3" } dependencies { - implementation("org.graalvm.python:python-embedding:25.0.3") + implementation("org.graalvm.python:python-embedding:25.1.3") } graalPy { @@ -205,6 +205,24 @@ class App { For complete plugin configuration options, deployment strategies, and dependency management, see [Embedding Build Tools](Embedding-Build-Tools.md). +### Supporting Legacy Private Keys + +BouncyCastle is optional for GraalPy embeddings. Add the following dependency only if the application must load legacy version 0 or 1 RSA, DSA, or EC private keys: + +```xml + + org.graalvm.python + python-bouncycastle-support + 25.1.3 + +``` + +For Gradle, use `implementation("org.graalvm.python:python-bouncycastle-support:25.1.3")`. + +### Configuring Individual Sources + +Embeddings can set options on an individual `Source` without changing the entire context. Set `python.Optimize` to `0`, `1`, or `2` to select the optimization level for a source. Set `python.NewGlobals=true` to execute a source with a fresh globals dictionary instead of the main module globals. + ## Other Build Systems (Ant, CMake, Makefile) If you are using build systems like Ant, Makefiles, or CMake that do not directly support Maven dependencies, you can still use GraalPy. diff --git a/docs/user/Interoperability.md b/docs/user/Interoperability.md index be5d011c21..fc7d2a13d4 100644 --- a/docs/user/Interoperability.md +++ b/docs/user/Interoperability.md @@ -211,7 +211,7 @@ If you're using Maven with GraalPy, add the JavaScript dependency to your _pom.x org.graalvm.polyglot js - 25.0.3 + 25.1.3 ``` @@ -343,6 +343,8 @@ Types not listed in the table below have no special interpretation in Python. | `array` | ForeignList, `list` | An `array` behaves like a Python `list`. Just like Python lists, the size must fit into a 32-bit signed integer. | | `boolean` | ForeignBoolean, ForeignNumber | `boolean` behaves like Python booleans, including the fact that in Python, all booleans are also integers (`1` and `0` for `true` and `false`, respectively). | | `buffer` | ForeignObject | Buffers work like Python buffer objects (such as those used with `memoryview`) to avoid copying data. | +| `date` | ForeignDate, `date` | A foreign date behaves like `datetime.date` and provides the corresponding Python methods. | +| `date` and `time` | ForeignDateTime, `datetime` | A foreign object with both traits behaves like `datetime.datetime`. | | `exception` | ForeignException, `BaseException` | An `exception` can be caught in a generic `except` clause. | | `executable` | ForeignExecutable | An `executable` object can be executed as a function, but never with keyword arguments. | | `hash` | ForeignDict, `dict` | A `hash` behaves like a Python `dict`, with any "hashable" object as a key. "Hashable" follows Python semantics: generally every interop type with an identity is deemed "hashable". | @@ -354,6 +356,8 @@ Types not listed in the table below have no special interpretation in Python. | `null` | ForeignNone, `NoneType` | `null` behaves like Python `None`. All interop null values (including JavaScript `undefined` and `null`) are treated as `None` in Python. | | `number` | ForeignNumber | `number` behaves like Python numbers (`int` and `float`). Foreign ranges are imported in some places such as typed arrays. | | `string` | ForeignString, `str` | Behaves in the same way as a Python string. | +| `time` | ForeignTime, `time` | A foreign time behaves like `datetime.time` and provides the corresponding Python methods. | +| `time zone` | ForeignTimeZone, `tzinfo` | A foreign time zone behaves like `datetime.tzinfo`. | Foreign numbers inherit from `polyglot.ForeignNumber` and not `int` or `float` because `InteropLibrary` has currently no way to differentiate integers and floats. diff --git a/docs/user/Performance.md b/docs/user/Performance.md index 7d9c1e0dc3..a8d982b589 100644 --- a/docs/user/Performance.md +++ b/docs/user/Performance.md @@ -27,6 +27,10 @@ The GraalPy launcher provides `-X jit=0|1|2` presets for common startup-heavy an These presets are launcher conveniences that expand to engine options. They can still be combined with explicit `--engine.*` options when more detailed tuning is needed. +### Native Standalone Memory Usage + +On Linux, the GraalPy native standalone uses a lower-footprint garbage collection configuration by default. This reduces resident set size for many workloads, but may increase startup and warmup time and may reduce performance for some workloads. + ## Code Loading Performance and Footprint It takes time to parse Python code so when using GraalPy to embed another language in Python, observe the general advice for embedding Graal languages related to [code caching](https://www.graalvm.org/latest/reference-manual/embed-languages/#code-caching-across-multiple-contexts). @@ -116,4 +120,3 @@ The developer can also effectively disable the creation of _.pyc_ files by disab If _.pyc_ files are not readable, their location is not writable. If the _.pyc_ files' serialization data or magic numbers are corrupted in any way, the deserialization fails and GraalPy parses the _.py_ source code file again. This comes with a minor performance hit *only* for the parsing of modules, which should not be significant for most applications (provided the application performs actual work in addition to loading Python code). - diff --git a/docs/user/Python-on-JVM.md b/docs/user/Python-on-JVM.md index 374e9cdad4..594c31eb2d 100644 --- a/docs/user/Python-on-JVM.md +++ b/docs/user/Python-on-JVM.md @@ -355,6 +355,18 @@ assert issubclass(PythonLevel, Level) assert PythonLevel.parse("INFO").getName() == "INFO" ``` +Java classes that declare generic parameters can be parameterized in Python type annotations and inherited from using the same subscription syntax as Python generic classes: + +```python +from java.util.function import Function + +class StringFunction(Function[str, str], new_style=True): + def apply(self, value: str) -> str: + return value.upper() +``` + +The type arguments provide Python typing information; they do not add run-time Java type checks. + ## Embedding Python into Java If you were embedding Jython in Java applications, there were two main approaches that need different migration paths: diff --git a/docs/user/Standalone-Getting-Started.md b/docs/user/Standalone-Getting-Started.md index 2d08458f6d..139f297b6f 100644 --- a/docs/user/Standalone-Getting-Started.md +++ b/docs/user/Standalone-Getting-Started.md @@ -50,11 +50,11 @@ The easiest way to install GraalPy on Linux is to use [Pyenv](https://github.com # Update pyenv to include latest GraalPy versions (if needed) pyenv update -# Install GraalPy 25.0.3 -pyenv install graalpy-25.0.3 +# Install GraalPy 25.1.3 +pyenv install graalpy-25.1.3 # Use GraalPy for the current shell session -pyenv shell graalpy-25.0.3 +pyenv shell graalpy-25.1.3 ``` #### Manual Installation (Linux) @@ -76,11 +76,11 @@ pyenv shell graalpy-25.0.3 Using Pyenv (recommended): ```bash -# Install GraalPy 25.0.3 -pyenv install graalpy-25.0.3 +# Install GraalPy 25.1.3 +pyenv install graalpy-25.1.3 # Use GraalPy for the current shell session -pyenv shell graalpy-25.0.3 +pyenv shell graalpy-25.1.3 ``` #### Manual Installation (macOS) @@ -92,7 +92,7 @@ pyenv shell graalpy-25.0.3 ```bash sudo xattr -r -d com.apple.quarantine /path/to/graalpy # For example: - sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-25.0.3 + sudo xattr -r -d com.apple.quarantine ~/.pyenv/versions/graalpy-25.1.3 ``` 3. Extract and add it to your `PATH` environment variable: @@ -129,10 +129,10 @@ The recommended way to use GraalPy is with [venv](https://docs.python.org/3/libr ```bash # Create a virtual environment -graalpy -m venv ~/.virtualenvs/graalpy-25.0.3 +graalpy -m venv ~/.virtualenvs/graalpy-25.1.3 # Activate the environment -source ~/.virtualenvs/graalpy-25.0.3/bin/activate +source ~/.virtualenvs/graalpy-25.1.3/bin/activate ``` ### Installing Packages