Align API more consistently with appose-python

Author: ctrueden

src/main/java/org/apposed/appose/Appose.java

@@ -447,6 +447,17 @@ public static DynamicBuilder content(String content) {
 
 	// -- Direct Environment shortcuts --
 
+	/**
+	 * Wraps an existing environment directory, automatically detecting the environment type.
+	 *
+	 * @param envDir The path to the directory containing the environment.
+	 * @return An Environment configured for the detected type.
+	 * @throws BuildException If the directory doesn't exist or type cannot be determined.
+	 */
+	public static Environment wrap(String envDir) throws BuildException {
+		return wrap(new File(envDir));
+	}
+
 	/**
 	 * Wraps an existing environment directory, automatically detecting the environment type.
 	 * This method intelligently detects whether the directory contains a pixi, mamba/conda,
@@ -472,17 +483,6 @@ public static Environment wrap(File envDir) throws BuildException {
 		return custom().wrap(envDir);
 	}
 
-	/**
-	 * Wraps an existing environment directory, automatically detecting the environment type.
-	 *
-	 * @param envDir The path to the directory containing the environment.
-	 * @return An Environment configured for the detected type.
-	 * @throws BuildException If the directory doesn't exist or type cannot be determined.
-	 */
-	public static Environment wrap(String envDir) throws BuildException {
-		return wrap(new File(envDir));
-	}
-
 	/**
 	 * Creates a system environment with sensible defaults.
 	 * <p>

src/main/java/org/apposed/appose/BuildException.java

@@ -40,25 +40,40 @@ public class BuildException extends Exception {
 	@Nullable
 	public final Builder<?> builder;
 
+	public BuildException() {
+		this(null, null, null);
+	}
+
+	public BuildException(Builder<?> builder) {
+		this(builder, null, null);
+	}
+
 	public BuildException(String message) {
-		this(null, message);
+		this(null, message, null);
 	}
 
 	public BuildException(Throwable cause) {
-		this(null, cause);
+		this(null, null, cause);
 	}
 
-	public BuildException(@Nullable Builder<?> builder, String message) {
-		super(message);
-		this.builder = builder;
+	public BuildException(Builder<?> builder, String message) {
+		this(builder, message, null);
+	}
+
+	public BuildException(Builder<?> builder, Throwable cause) {
+		this(builder, null, cause);
 	}
 
-	public BuildException(@Nullable Builder<?> builder, Throwable cause) {
-		this(builder, makeMessage(builder, cause), cause);
+	public BuildException(String message, Throwable cause) {
+		this(null, message, cause);
 	}
 
-	public BuildException(@Nullable Builder<?> builder, String message, Throwable cause) {
-		super(message, cause);
+	public BuildException(
+		@Nullable Builder<?> builder,
+		@Nullable String message,
+		@Nullable Throwable cause)
+	{
+		super(message == null ? makeMessage(builder, cause) : message, cause);
 		this.builder = builder;
 	}
 

src/main/java/org/apposed/appose/BuilderFactory.java

@@ -77,6 +77,17 @@ public interface BuilderFactory {
 	 */
 	double priority();
 
+	/**
+	 * Checks if this builder can wrap the given existing environment directory.
+	 * Used by {@link Appose#wrap(File)} to auto-detect environment type.
+	 *
+	 * @param envDir The directory to check
+	 * @return true if this builder can wrap the directory
+	 */
+	default boolean canWrap(String envDir) {
+		return canWrap(new File(envDir));
+	}
+
 	/**
 	 * Checks if this builder can wrap the given existing environment directory.
 	 * Used by {@link Appose#wrap(File)} to auto-detect environment type.

src/main/java/org/apposed/appose/builder/Builders.java

@@ -48,7 +48,7 @@ private Builders() {
 	}
 
 	/** All known {@link BuilderFactory} implementations, in priority order. */
-	private static final List<BuilderFactory> ALL = Plugins.discover(BuilderFactory.class,
+	private static final List<BuilderFactory> BUILDERS = Plugins.discover(BuilderFactory.class,
 		(a, b) -> Double.compare(b.priority(), a.priority()));
 
 	/**
@@ -58,7 +58,7 @@ private Builders() {
 	 * @return The factory with matching name, or null if not found.
 	 */
 	public static @Nullable BuilderFactory findFactoryByName(String name) {
-		return Plugins.find(ALL, factory -> factory.name().equalsIgnoreCase(name));
+		return Plugins.find(BUILDERS, factory -> factory.name().equalsIgnoreCase(name));
 	}
 
 	/**
@@ -69,7 +69,18 @@ private Builders() {
 	 * @return The first factory that supports the scheme, or null if none found.
 	 */
 	public static @Nullable BuilderFactory findFactoryByScheme(String scheme) {
-		return Plugins.find(ALL, factory -> factory.supportsScheme(scheme));
+		return Plugins.find(BUILDERS, factory -> factory.supportsScheme(scheme));
+	}
+
+	/**
+	 * Finds the first factory that can wrap the given environment directory.
+	 * Factories are checked in priority order (highest priority first).
+	 *
+	 * @param envDir The directory to find a factory for.
+	 * @return The first factory that can wrap the directory, or null if none found.
+	 */
+	public static @Nullable BuilderFactory findFactoryForWrapping(String envDir) {
+		return findFactoryForWrapping(new File(envDir));
 	}
 
 	/**
@@ -80,7 +91,18 @@ private Builders() {
 	 * @return The first factory that can wrap the directory, or null if none found.
 	 */
 	public static @Nullable BuilderFactory findFactoryForWrapping(File envDir) {
-		return Plugins.find(ALL, factory -> factory.canWrap(envDir));
+		return Plugins.find(BUILDERS, factory -> factory.canWrap(envDir));
+	}
+
+	/**
+	 * Checks if the given directory can be wrapped as a known environment type.
+	 * This is a convenience method equivalent to {@code findFactoryForWrapping(envDir) != null}.
+	 *
+	 * @param envDir The directory to check.
+	 * @return true if the directory can be wrapped by any known builder, false otherwise.
+	 */
+	public static boolean canWrap(String envDir) {
+		return canWrap(new File(envDir));
 	}
 
 	/**

src/main/java/org/apposed/appose/builder/MambaBuilder.java

@@ -57,6 +57,17 @@ public String name() {
 		return "mamba";
 	}
 
+	/**
+	 * Adds conda channels to search for packages.
+	 *
+	 * @param channels Channel names (e.g., "conda-forge", "bioconda")
+	 * @return This builder instance, for fluent-style programming.
+	 */
+	@Override
+	public MambaBuilder channels(String... channels) {
+		return super.channels(channels);
+	}
+
 	@Override
 	public Environment build() throws BuildException {
 		File envDir = envDir();
@@ -150,17 +161,6 @@ public Environment wrap(File envDir) throws BuildException {
 		return build();
 	}
 
-	/**
-	 * Adds conda channels to search for packages.
-	 *
-	 * @param channels Channel names (e.g., "conda-forge", "bioconda")
-	 * @return This builder instance, for fluent-style programming.
-	 */
-	@Override
-	public MambaBuilder channels(String... channels) {
-		return super.channels(channels);
-	}
-
 	private Environment createEnvironment(File envDir) {
 		Mamba mamba = new Mamba();
 		String base = envDir.getAbsolutePath();

src/main/java/org/apposed/appose/scheme/Schemes.java

@@ -53,7 +53,7 @@ private Schemes() {
 	 * since both are TOML files but {@code pyproject.toml} has more specific markers.
 	 * </p>
 	 */
-	private static final List<Scheme> ALL = Plugins.discover(Scheme.class,
+	private static final List<Scheme> SCHEMES = Plugins.discover(Scheme.class,
 		(a, b) -> Double.compare(b.priority(), a.priority()));
 
 	/**
@@ -64,7 +64,7 @@ private Schemes() {
 	 * @throws IllegalArgumentException If no scheme can handle the content
 	 */
 	public static Scheme fromContent(String content) {
-		Scheme result = Plugins.find(ALL, scheme -> scheme.supportsContent(content));
+		Scheme result = Plugins.find(SCHEMES, scheme -> scheme.supportsContent(content));
 		if (result != null) return result;
 		throw new IllegalArgumentException(
 			"Cannot infer scheme from content. " +
@@ -79,7 +79,7 @@ public static Scheme fromContent(String content) {
 	 * @throws IllegalArgumentException If no scheme matches the name
 	 */
 	public static Scheme fromName(String name) {
-		Scheme result = Plugins.find(ALL, scheme -> scheme.name().equals(name));
+		Scheme result = Plugins.find(SCHEMES, scheme -> scheme.name().equals(name));
 		if (result != null) return result;
 		throw new IllegalArgumentException("Unknown scheme: " + name);
 	}

src/main/java/org/apposed/appose/syntax/Syntaxes.java

@@ -48,7 +48,7 @@ private Syntaxes() {
 	}
 
 	/** All known script syntax implementations. */
-	private static final List<ScriptSyntax> ALL =
+	private static final List<ScriptSyntax> SYNTAXES =
 		Plugins.discover(ScriptSyntax.class, null);
 
 	/**
@@ -58,7 +58,7 @@ private Syntaxes() {
 	 * @return The matching script syntax object, or null if no syntax with the given name
 	 */
 	public static @Nullable ScriptSyntax get(String name) {
-		return Plugins.find(ALL, syntax -> name.equals(syntax.name()));
+		return Plugins.find(SYNTAXES, syntax -> name.equals(syntax.name()));
 	}
 
 	/**

src/main/java/org/apposed/appose/util/Downloads.java

@@ -69,6 +69,12 @@ private Downloads() {
 		// Prevent instantiation of utility class.
 	}
 
+	public static File download(String name, String urlPath)
+		throws IOException, InterruptedException, URISyntaxException
+	{
+		return download(name, urlPath, null);
+	}
+
 	public static File download(String name, String urlPath, @Nullable BiConsumer<Long, Long> progressConsumer)
 		throws IOException, InterruptedException, URISyntaxException
 	{

src/test/java/org/apposed/appose/ServiceTest.java

@@ -89,7 +89,7 @@ public void testScopeGroovy() throws Exception {
 	@Test
 	public void testServiceStartupFailure() throws Exception {
 		// Create an environment with no binPaths to test startup failure.
-		File tempDir = new File("no-pythons-to-be-found-here");
+		File tempDir = new File("target", "no-pythons-to-be-found-here");
 		tempDir.mkdirs();
 		tempDir.deleteOnExit();