Support environments declared inline, a la PEP 723

A script can now declare its environment in a "# /// script" metadata
block, including the [tool.pixi.*] extensions of "pixi run --script",
so that it stands alone, and can use conda packages such as CUDA.

Appose builds environments in directories of its own rather than in
pixi's script cache, so the metadata is translated into an equivalent
pyproject.toml, mirroring pixi's own translation and its list of
supported [tool.pixi.*] keys.

The StarDist template now declares its environment inline, since
templates open as unsaved scripts, which cannot refer to a file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: ctrueden

GAPS.md

@@ -154,6 +154,44 @@ worker, every such output leaked one block.
   nothing checks directly that blocks are freed. A shared memory pool in
   Appose core (planned) would make ownership explicit.
 
+## Inline environments
+
+**Now:** `InlineMetadata` translates a PEP 723 block into a `pyproject.toml`
+for Appose's pixi builder: `requires-python` and `dependencies` move into
+`[project]`, `[tool.*]` tables are kept, and `[tool.pixi.workspace]` gains
+`channels = ["conda-forge"]` and the running platform if it lacks them, since
+a pixi workspace requires both. This mirrors pixi's own `inline_pyproject`,
+including its list of allowed `[tool.pixi.*]` keys, so a script accepted here
+also runs with `pixi run --script`.
+
+**Gaps:**
+
+- **Relative paths.** pixi resolves relative paths in script metadata (e.g.
+  an editable `path` dependency) from the script's directory. Here they
+  resolve from the environment directory, so they break. Rewriting them to
+  absolute paths is possible, but meaningless for scripts inside a JAR.
+- **Lock files.** A `<script>.pixi.lock` sidecar, as written by
+  `pixi lock --script`, is ignored; each environment is locked afresh.
+- **Unsaved scripts.** An inline environment is named after its script's
+  path. Unsaved scripts (e.g. new from a template) have none, so they are
+  named by a hash of the metadata instead. Editing the metadata of an unsaved
+  script therefore creates a new environment and worker, and the old worker
+  keeps running until the application exits.
+- **The generated file is not readable by Appose's scheme detection.** Its
+  TOML uses dotted keys (`project.name = ...`), while Appose's line-based
+  detection looks for `[project]`. The engine passes the scheme explicitly.
+  In Appose core, inline metadata should be a scheme of its own, so any
+  Appose user can build from a script.
+
+## Environment files inside JARs
+
+**Now:** `#@script(env="...")` is resolved against the script's file path.
+Scripts inside a JAR have no such file, so they cannot use environment files.
+Resolving the reference as a URL relative to the script's own URL (e.g.
+`jar:file:...!/scripts/env.toml`) would fix that, while keeping a script and
+its environment from the same origin, but it has not been done. Inline
+environments avoid the problem.
+
 ## Not yet tried
 
 - **Real Fiji GUI.** All tests are headless. The build and run tasks have not
@@ -168,7 +206,7 @@ worker, every such output leaked one block.
 
 | Class | Destination |
 | --- | --- |
-| `BuildListener`, `LazyEnvironment`, `ResidentWorker` | Appose core |
+| `BuildListener`, `InlineMetadata`, `LazyEnvironment`, `ResidentWorker` | Appose core |
 | `ResidentWorkerService`, `SciJavaTasks` | `scijava/scijava-appose` |
 | `NDArrayToImgConverter`, `RAIToNDArrayConverter`, ImageJ2 dependencies | `fiji/fiji-appose` |
 

README.md

@@ -15,7 +15,10 @@ from the Script Editor or menus of ImageJ2/Fiji like any other script.
 
 ```python
 #!appose-python
-#@script(env="myenv.toml")
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["appose", "scipy"]
+# ///
 
 #@ Img image
 #@ double sigma
@@ -29,24 +32,61 @@ blurred = gaussian_filter(image, sigma)
 
 * The `#!appose-python` line selects this script language, rather than
   another language handling `.py` files, such as Jython.
-* The `env` attribute points to an environment configuration file, resolved
-  relative to the script's location. Any format Appose supports works:
-  `pixi.toml`, `environment.yml`, `requirements.txt` or `pyproject.toml`.
-  An optional `scheme` attribute (e.g. `scheme="pixi.toml"`) sets the format
-  explicitly, which is useful when the file name does not reveal it.
+* The `# /// script` block declares the script's Python environment; see
+  below.
 * The environment must include the `appose` Python package, plus `numpy` if
   the script uses images.
 
 See the `StarDist_cellcast.py` template for a complete example.
 
 ## Environments
 
+A script declares its environment in one of two ways.
+
+**Inline**, with a [PEP 723](https://packaging.python.org/en/latest/specifications/inline-script-metadata/)
+metadata block, as above. `requires-python` selects the Python version, and
+`dependencies` lists packages from PyPI. The `[tool.pixi.*]` extensions of
+[`pixi run --script`](https://pixi.sh/latest/python/scripts/) are supported
+too, so conda packages are available, e.g. to get CUDA libraries from
+conda-forge:
+
+```python
+# /// script
+# requires-python = ">=3.12"
+# dependencies = ["appose"]
+#
+# [tool.pixi.dependencies]
+# pytorch-gpu = "*"
+#
+# [tool.pixi.system-requirements]
+# cuda = "12"
+# ///
+```
+
+If `[tool.pixi.workspace]` does not say otherwise, packages come from
+conda-forge, for the platform the script runs on. Inline environments are the
+way to go for scripts that must stand alone, such as templates.
+
+**In a file**, named by the `env` attribute of the `#@script` directive:
+
+```python
+#@script(env="myenv.toml")
+```
+
+The file is resolved relative to the script's location. Any format Appose
+supports works: `pixi.toml`, `environment.yml`, `requirements.txt` or
+`pyproject.toml`. An optional `scheme` attribute (e.g. `scheme="pixi.toml"`)
+sets the format explicitly, which is useful when the file name does not reveal
+it. Scripts that share a file share an environment.
+
+A script cannot do both.
+
 The environment is built the first time a script needs it, which may take a
 while. Afterward, it is reused, both within the running application and across
 restarts. Environments are stored in the Appose environments directory
-(`~/.local/share/appose` by default), named after the configuration file.
-Scripts that share a configuration file share an environment. Editing the file
-causes the environment to be updated on the next run.
+(`~/.local/share/appose` by default), named after the file declaring them: the
+environment file, or the script itself for inline environments. Editing the
+declaration causes the environment to be updated on the next run.
 
 Builds appear in the application's task list, with their progress, so a
 long first build does not look like a hang.

pom.xml

@@ -108,6 +108,15 @@
 		</dependency>
 
 		<!-- Third-party dependencies -->
+		<dependency>
+			<groupId>com.fasterxml.jackson.core</groupId>
+			<artifactId>jackson-databind</artifactId>
+		</dependency>
+		<dependency>
+			<groupId>com.fasterxml.jackson.dataformat</groupId>
+			<artifactId>jackson-dataformat-toml</artifactId>
+			<version>${jackson.version}</version>
+		</dependency>
 		<dependency>
 			<groupId>com.fifesoft</groupId>
 			<artifactId>rsyntaxtextarea</artifactId>

src/main/java/org/scijava/plugins/scripting/appose/python/ApposePythonScriptEngine.java

@@ -70,6 +70,7 @@
 import org.scijava.log.Logger;
 import org.scijava.module.ModuleItem;
 import org.scijava.plugin.Parameter;
+import org.scijava.plugins.scripting.appose.python._internal.InlineMetadata;
 import org.scijava.plugins.scripting.appose.python._internal.ResidentWorker;
 import org.scijava.plugins.scripting.appose.python._internal.ResidentWorkerService;
 import org.scijava.plugins.scripting.appose.python._internal.SciJavaTasks;
@@ -156,7 +157,7 @@ public Object eval(final String script) throws ScriptException {
 			((ScriptModule) moduleObj).getInfo() : null;
 
 		// Retrieve the resident worker for the script's environment.
-		final ResidentWorker worker = worker(info);
+		final ResidentWorker worker = worker(info, script);
 
 		// Collect declared inputs, converting array-like values to NDArray.
 		final Map<String, Object> taskInputs = new HashMap<>();
@@ -439,18 +440,33 @@ static boolean ownsNDArray(final Object value, final NDArray nd) {
 	}
 
 	/**
-	 * Gets the resident worker for the Appose environment described by the
-	 * {@code env} and {@code scheme} attributes of the script's
-	 * {@code #@script} directive. The environment itself is built lazily, by
-	 * the worker's first task.
+	 * Gets the resident worker for the script's Appose environment, which the
+	 * script declares either inline, via a PEP 723 {@code # /// script}
+	 * metadata block, or in a file named by the {@code env} (and optionally
+	 * {@code scheme}) attributes of its {@code #@script} directive. The
+	 * environment itself is built lazily, by the worker's first task.
 	 */
-	private ResidentWorker worker(final ScriptInfo info) throws ScriptException {
-		final String envRef = info == null ? null : info.get("env");
-		if (envRef == null) {
-			throw new ScriptException(
-				"No Appose environment configured. " +
-				"Add #@script(env=\"myenv.toml\") to declare one.");
+	private ResidentWorker worker(final ScriptInfo info, final String script)
+		throws ScriptException
+	{
+		if (info == null) throw noEnvironment();
+		final String envRef = info.get("env");
+		final String metadata;
+		try {
+			metadata = InlineMetadata.extract(script);
+		}
+		catch (final IllegalArgumentException e) {
+			throw scriptException(e.getMessage(), e);
+		}
+		if (metadata != null) {
+			if (envRef != null) {
+				throw new ScriptException("The script declares its environment " +
+					"twice: inline, and via #@script(env=\"" + envRef + "\"). " +
+					"Remove one of them.");
+			}
+			return inlineWorker(metadata, info.getPath());
 		}
+		if (envRef == null) throw noEnvironment();
 
 		final File envFile = resolveEnvFile(envRef, info.getPath());
 		if (!envFile.isFile()) {
@@ -466,9 +482,36 @@ private ResidentWorker worker(final ScriptInfo info) throws ScriptException {
 			throw scriptException("Cannot read Appose environment file: " +
 				envFile.getAbsolutePath(), e);
 		}
-		final String envName = envName(envFile);
-		final String scheme = info.get("scheme");
+		return worker(envName(envFile), content, info.get("scheme"));
+	}
 
+	/** Gets the resident worker for an environment declared inline. */
+	private ResidentWorker inlineWorker(final String metadata,
+		final String scriptPath) throws ScriptException
+	{
+		// Note: Name the environment after the script, as for environment
+		// files, so that editing the metadata updates the environment and
+		// replaces its worker, rather than leaving the old one running.
+		// Unsaved scripts, e.g. new from a template, have no path to go by.
+		final String envName = scriptPath == null ? "script-" + String.format(
+			"%08x", metadata.hashCode()) : envName(new File(scriptPath));
+		final String content;
+		try {
+			content = InlineMetadata.toPyProject(metadata, envName);
+		}
+		catch (final IllegalArgumentException e) {
+			throw scriptException(e.getMessage(), e);
+		}
+		return worker(envName, content, InlineMetadata.SCHEME);
+	}
+
+	/**
+	 * Gets the resident worker for the named environment, built from the given
+	 * configuration.
+	 */
+	private ResidentWorker worker(final String envName, final String content,
+		final String scheme)
+	{
 		return workerService.worker(envName, scheme + "\n" + content, () -> {
 			final Builder<?> builder = Appose.content(content);
 			return scheme == null ? builder : builder.scheme(scheme);
@@ -505,6 +548,12 @@ static String envName(final File envFile) {
 			String.format("%08x", path.hashCode());
 	}
 
+	private static ScriptException noEnvironment() {
+		return new ScriptException("No Appose environment configured. " +
+			"Declare one inline with a '# /// script' metadata block (PEP 723), " +
+			"or in a file via #@script(env=\"myenv.toml\").");
+	}
+
 	private static ScriptException scriptException(final String message,
 		final Throwable cause)
 	{