[GR-71196] Tech writer run through

PullRequest: graalpython/4088

Author: ban-mi

docs/site/_config.yml

@@ -1,7 +1,7 @@
 baseurl: "/python"
 url: "https://graalvm.org"
 github: "oracle/graalpython"
-language_version: 25.0.0
+language_version: 25.0.1
 name: GraalPy
 
 permalink: pretty

docs/user/Native-Images-with-Python.md

@@ -1,92 +1,68 @@
 # Native Executables with Python
 
-GraalPy supports GraalVM Native Image to generate native binaries of Java applications that use GraalPy.
+GraalPy supports GraalVM Native Image to generate native binaries of Java applications that embed Python code.
 
 ## Quickstart
 
-If you started with the [Maven archetype](README.md), the generated _pom.xml_ makes it easy to generate a native executable using the [Maven plugin for Native Image building](https://graalvm.github.io/native-build-tools/latest/maven-plugin.html).
+If you started with the [Maven archetype](README.md), the generated _pom.xml_ file already includes the necessary configuration for creating a native executable using the [Maven plugin for Native Image building](https://graalvm.github.io/native-build-tools/latest/maven-plugin.html).
 
 To build the application, run:
+
 ```bash
 mvn -Pnative package
 ```
-The command packages the project and creates a native executable.
 
-Take a look at the generated files _pom.xml_ and _Main.java_.
-They are documented to explain how Python resources are included in the resulting binary.
-The generated project should be viewed as a starting point.
-It includes the entire Python standard library, so the Python code can invoke all of the standard library code.
-The resources can be manually pruned to reduce the included Python libraries to the necessary amount, reducing both the size of the package and the time to start up.
-This Java example demonstrates some useful default options for the Python context, but other settings may be desirable to further control what the Python code is allowed to do.
+This command packages the project and creates a native executable.
 
-## Reducing Binary Size
+The generated _pom.xml_ and _Main.java_ files explain how Python resources are included in the resulting binary.
+The generated project serves as a starting point and includes the entire Python standard library by default, allowing your Python code to use any standard library modules.
+You can manually remove unused Python libraries to reduce both the executable size and startup time.
+The created example demonstrates useful default options for the Python context, but you can adjust these settings to control what your Python code can access.
 
-Python is a large language.
-"Batteries included" has long been a core tenet of CPython.
-As a compatible replacement, GraalPy includes most of those "batteries" as well.
-This can result in significant increases in binary size when including GraalPy in a Java application.
-
-Only you as the developer know your specific embedding scenario.
-The defaults may include much more than needed for any specific application.
-An embedded Python-in-Java application usually has more limited use cases for the Python interpreter than the full GraalPy distribution, and often you can know ahead of time whether certain features are needed.
-Some features (for example, cryptographic algorithms or socket access) may even be undesirable to include in some cases.
-Thus, when embedding GraalPy in a Java application, the binary size can be reduced and security improved by excluding components of the Python language.
-
-### Excluding Python Components
-
-GraalPy defines a few system properties that can be passed on the `native-image` command line to exclude aspects of the language.
-The options can, when taken together, reduce the size of the executable by around 20%.
-These are:
-
-* `python.WithoutSSL=true` - This option removes the `ssl` module.
-  If no secure network access or certificate checking is required, this removes Java's SSL classes and the BouncyCastle library.
-* `python.WithoutDigest=true` - This option removes the `_md5`, `_sha1`, `_sha256`, `_sha512`, `_sha3`, and `_hashlib` modules.
-  This removes the direct usages of `java.security.MessageDigest` and `javax.crypto.Mac` from GraalPy.
-* `python.WithoutPlatformAccess=true` - This removes the `signal` and `subprocess` modules, removes accesses to process properties such as the Unix UID and GID, or setting the Java default time zone.
-  This has no significant impact on binary size, but if these are unwanted capabilities that are dynamically disabled with context options anyway, they can also be removed ahead of time.
-* `python.WithoutCompressionLibraries=true` - This removes the `zlib`, `lzma`, `bzip2`, and `zipimporter` modules and related classes.
-  These modules have both native and pure Java implementations (the former for performance, the latter for better sandboxing); however, if they are not needed, they can be removed entirely.
-* `python.WithoutNativePosix=true` - The default `os` module backend is a pure Java implementation when GraalPy is embedded rather than run via its launcher.
-  The native POSIX backend of GraalPy is recommended only for 100% compatibility with CPython's POSIX interfaces, and if not used, can be removed from the build with this option.
-* `python.WithoutJavaInet=true` - The Java implementation of Python's `socket` module is based on Java's networking classes.
-  If network access is denied for an embedding scenario, this option can reduce the binary size further.
-* `python.AutomaticAsyncActions=false` - Signal handling, Python weak reference callbacks, and cleaning up native resources is usually achieved automatically by spawning GraalPy daemon threads that submit safepoint actions to the Python main thread.
-  This uses an `ExecutorService` with a thread pool.
-  If you want to disallow such extra threads or avoid pulling in `ExecutorService` and related classes, then set this property to `false` and retrieve the `PollPythonAsyncActions` object from the context's polyglot bindings.
-  This object is executable and can be used to trigger Python asynchronous actions at the locations you desire.
+## Reducing Binary Size
 
+Python is a feature-rich language with an extensive standard library.
+This can result in large native executables when embedding GraalPy in Java applications.
+You can significantly reduce the size by excluding components your application doesn't need by considering what your Python code actually uses.
 
 ### Removing Pre-initialized Python Heap
 
-Another useful option to reduce the size of the native executable is to omit a pre-initialized Python context from the executable.
-By default, a default Python context is already pre-initialized and ready for immediate execution.
-This can lead to slightly improved startup, at the cost of including a few thousand Python objects in the binary.
-In embedded applications that use a custom polyglot engine to allow context sharing, the pre-initialized context cannot be used at all, and including those objects is wasted.
-The pre-initialized heap can be omitted by passing the following to the `native-image` command:
+By default, GraalPy includes a pre-initialized Python context in the executable for faster startup.
+Disabling this reduces the binary size by about 15MiB.
+You should remove this if:
+- You are creating more than one context
+- Binary size is more important than a slight startup delay
+
+To remove the pre-initialized heap, add this flag to your build configuration:
 
 ```bash
--Dimage-build-time.PreinitializeContexts=
+-Dpolyglot.image-build-time.PreinitializeContexts=
 ```
 
 ### Disabling Runtime Compilation of Python Code
 
-If binary size is significantly more important than execution speed (which may be the case if all Python scripts are expected to be short running, perform a lot of I/O, or scripts are rarely executed more than once), it may make sense to disable JIT compilation entirely.
+If binary size is significantly more important than execution speed, you can disable JIT compilation entirely.
+This will reduce binary size by around 40%.
+You should use this if:
+
+- Your Python scripts are very short-running
+- Performance is not critical
+- Your scripts spend most time on I/O operations
+
 Be aware that this may significantly impact your Python performance, so be sure to test the runtime behavior of your actual use cases when choosing to use this option.
+
 This can be achieved by passing the following options:
 
 ```bash
--Dtruffle.TruffleRuntime=com.oracle.truffle.api.impl.DefaultTruffleRuntime \
+-Dtruffle.TruffleRuntime=com.oracle.truffle.api.impl.DefaultTruffleRuntime
 -Dpolyglot.engine.WarnInterpreterOnly=false
 ```
 
 ### Summary
 
-Combining all of these approaches can halve the size of the GraalPy binary.
-Every embedded application is different and the code pulled in by the rest of the Java code also matters, so combinations of these options should be tried to determine which effect they have in a specific instance.
+Combining these approaches can reduce the binary size by 50% or more.
+Since every application is different, experiment with different combinations to find what works best for your specific use case.
 
 ## Shipping Python Packages
 
 Our Maven archetype by default is set up to include all needed Python files in the native binary itself, so the image is self-contained.
-
-In custom embeddings, the Python standard library is copied next to the native image.
-When moving the native image, the standard library folder needs to be kept next to it.