Improve Appose entry points

This significantly simplifies the builder subsystem.

We don't need the concept of source strings in the builders
themselves, only in the toplevel appose convenience entry methods.

Appose now provides four builders, with three options per builder:

Builder | Plain   | Auto       | Path                  | URL
--------|---------|------------|-----------------------|----
Pixi    | pixi()  | pixi(str)  | pixi(Path)            | <none>
Mamba   | mamba() | mamba(str) | mamba(Path)           | <none>
Uv      | uv()    | uv(str)    | uv(Path)              | <none>
Dynamic | <none>  | <none>     | file(str), file(Path) | url(str)

As per apposed/appose-java@427e568.

Co-authored-by: Claude <[email protected]>

Author: ctrueden

src/appose/__init__.py

@@ -214,32 +214,166 @@ def task_listener(event):
     }
 '''
 
+from __future__ import annotations
+
+import re
 from pathlib import Path
 
-from .builder import SimpleBuilder
+from .builder import (
+    BuildException,
+    DynamicBuilder,
+    SimpleBuilder,
+    find_factory_for_wrapping,
+)
+from .builder.pixi import PixiBuilder
+from .builder.mamba import MambaBuilder
+from .builder.uv import UvBuilder
 from .environment import Environment
 from .service import TaskException  # noqa: F401
 from .shm import NDArray, SharedMemory  # noqa: F401
 
 __version__ = "0.7.3.dev0"
 
 
-def base(directory: Path) -> SimpleBuilder:
+def pixi(source: str | Path | None = None) -> PixiBuilder:
+    """
+    Creates a PixiBuilder for Pixi-based environments.
+
+    Args:
+        source: Optional configuration source (file path or URL)
+
+    Returns:
+        A PixiBuilder instance
+    """
+    builder = PixiBuilder()
+    if source:
+        if isinstance(source, Path) or not _is_url(str(source)):
+            return builder.file(source)
+        else:
+            return builder.url(str(source))
+    return builder
+
+
+def mamba(source: str | Path | None = None) -> MambaBuilder:
+    """
+    Creates a MambaBuilder for Micromamba-based environments.
+
+    Args:
+        source: Optional configuration source (file path or URL)
+
+    Returns:
+        A MambaBuilder instance
+    """
+    builder = MambaBuilder()
+    if source:
+        if isinstance(source, Path) or not _is_url(str(source)):
+            return builder.file(source)
+        else:
+            return builder.url(str(source))
+    return builder
+
+
+def uv(source: str | Path | None = None) -> UvBuilder:
     """
-    Create a simple builder with a custom base directory.
+    Creates a UvBuilder for uv-based virtual environments.
 
     Args:
-        directory: The base directory for the environment
+        source: Optional configuration source (file path or URL)
 
     Returns:
-        A SimpleBuilder instance configured with the given directory
+        A UvBuilder instance
     """
-    return SimpleBuilder().base(directory)
+    builder = UvBuilder()
+    if source:
+        if isinstance(source, Path) or not _is_url(str(source)):
+            return builder.file(source)
+        else:
+            return builder.url(str(source))
+    return builder
 
 
-def system(directory: Path = Path(".")) -> Environment:
+def file(source: str | Path) -> DynamicBuilder:
     """
-    Create a simple environment using system executables.
+    Creates a DynamicBuilder from a configuration file.
+    The builder type will be auto-detected from file content.
+
+    Args:
+        source: Path to configuration file
+
+    Returns:
+        A DynamicBuilder instance
+    """
+    return DynamicBuilder().file(source)
+
+
+def url(source: str) -> DynamicBuilder:
+    """
+    Creates a DynamicBuilder from a URL.
+    The builder type will be auto-detected from content.
+
+    Args:
+        source: URL to configuration file
+
+    Returns:
+        A DynamicBuilder instance
+    """
+    return DynamicBuilder().url(source)
+
+
+def content(config_content: str) -> DynamicBuilder:
+    """
+    Creates a DynamicBuilder from configuration content.
+    The builder type will be auto-detected from content syntax.
+
+    Args:
+        config_content: Configuration file content
+
+    Returns:
+        A DynamicBuilder instance
+    """
+    return DynamicBuilder().content(config_content)
+
+
+def wrap(env_dir: str | Path) -> Environment:
+    """
+    Wraps an existing environment directory, auto-detecting its type.
+
+    Args:
+        env_dir: The directory containing the environment
+
+    Returns:
+        An Environment configured for the detected type
+
+    Raises:
+        BuildException: If the directory doesn't exist
+    """
+    env_path = Path(env_dir)
+    if not env_path.exists():
+        raise BuildException(None, f"Environment directory does not exist: {env_dir}")
+
+    # Find a builder factory that can wrap this directory
+    factory = find_factory_for_wrapping(env_path)
+
+    if factory:
+        return factory.create_builder().wrap(env_path)
+
+    # Default to simple builder (no special activation)
+    return custom().wrap(env_path)
+
+
+def custom() -> SimpleBuilder:
+    """
+    Creates a SimpleBuilder for custom environments without package management.
+
+    Returns:
+        A SimpleBuilder instance
+    """
+    return SimpleBuilder()
+
+
+def system(directory: str | Path = Path(".")) -> Environment:
+    """
+    Creates a simple environment using system executables.
 
     Args:
         directory: The working directory (defaults to current directory)
@@ -248,3 +382,21 @@ def system(directory: Path = Path(".")) -> Environment:
         An Environment that uses system PATH for finding executables
     """
     return SimpleBuilder().base(directory).append_system_path().build()
+
+
+def _is_url(source: str) -> bool:
+    """
+    Check if string appears to be a URL.
+    Detects common URL schemes (http, https, ftp, file, jar) by using
+    a pattern of 3+ letter scheme followed by "://" to avoid matching
+    Windows drive letters like "C:".
+
+    Args:
+        source: The source string to check
+
+    Returns:
+        True if the string looks like a URL
+    """
+    if not source:
+        return False
+    return bool(re.match(r"^[a-z]{3,}://", source.lower()))

src/appose/builder/__init__.py

@@ -357,21 +357,13 @@ class BuilderFactory(Protocol):
     the Builders utility class.
     """
 
-    def create_builder(
-        self, source: str | None = None, scheme: str | None = None
-    ) -> Builder:
+    def create_builder(self) -> Builder:
         """
-        Creates a new builder instance.
-
-        Args:
-            source: Optional source file path
-            scheme: Optional scheme (e.g., "environment.yml", "pixi.toml")
+        Creates a new builder instance with no configuration.
+        Configuration should be provided via the fluent API (e.g., content, scheme).
 
         Returns:
             A new builder instance
-
-        Raises:
-            BuildException: If the builder cannot be created
         """
         ...
 
@@ -396,19 +388,6 @@ def supports_scheme(self, scheme: str) -> bool:
         """
         ...
 
-    def supports_source(self, source: str) -> bool:
-        """
-        Checks if this builder can build from the given source file.
-        This allows builders to inspect file extensions or content to determine compatibility.
-
-        Args:
-            source: The source file path to check
-
-        Returns:
-            True if this builder can build from the source
-        """
-        ...
-
     def priority(self) -> float:
         """
         Returns the priority of this builder for scheme resolution.
@@ -577,7 +556,9 @@ def _scheme(self) -> Scheme:
         """Get the scheme, detecting from content if needed."""
         if self.scheme:
             return Schemes.from_name(self.scheme)
-        return Schemes.from_content(self.source_content)
+        if self.source_content:
+            return Schemes.from_content(self.source_content)
+        raise ValueError("Cannot determine scheme: neither scheme nor content is set")
 
     def _create_env(
         self, base: str, bin_paths: list[str], launch_args: list[str]
@@ -743,16 +724,9 @@ class SimpleBuilderFactory:
     SimpleBuilder can wrap any directory as a fallback.
     """
 
-    def create_builder(
-        self, source: str | None = None, scheme: str | None = None
-    ) -> Builder:
+    def create_builder(self) -> Builder:
         """Create a SimpleBuilder instance."""
-        builder = SimpleBuilder()
-        if source:
-            builder.file(source)
-        if scheme:
-            builder.scheme(scheme)
-        return builder
+        return SimpleBuilder()
 
     def name(self) -> str:
         """Return the name of the builder."""
@@ -762,10 +736,6 @@ def supports_scheme(self, scheme: str) -> bool:
         """SimpleBuilder doesn't support any specific schemes."""
         return False
 
-    def supports_source(self, source: str) -> bool:
-        """SimpleBuilder doesn't support any specific source files."""
-        return False
-
     def priority(self) -> float:
         """
         Lowest priority - SimpleBuilder is a fallback.
@@ -785,12 +755,11 @@ def can_wrap(self, env_dir: str | Path) -> bool:
 class DynamicBuilder(BaseBuilder):
     """
     Dynamic builder that auto-detects the appropriate specific builder
-    based on source file and scheme.
+    based on configuration content and scheme.
     """
 
-    def __init__(self, source: str | None = None):
+    def __init__(self):
         super().__init__()
-        self.source = source
         self.builder_name: str | None = None
 
     def builder(self, builder_name: str) -> DynamicBuilder:
@@ -811,13 +780,13 @@ def name(self) -> str:
 
     def build(self) -> Environment:
         """Build by delegating to the appropriate builder."""
-        delegate = self._create_builder(self.builder_name, self.source, self.scheme)
+        delegate = self._create_builder(self.builder_name, self.scheme)
         self._copy_config_to_delegate(delegate)
         return delegate.build()
 
     def rebuild(self) -> Environment:
         """Rebuild by delegating to the appropriate builder."""
-        delegate = self._create_builder(self.builder_name, self.source, self.scheme)
+        delegate = self._create_builder(self.builder_name, self.scheme)
         self._copy_config_to_delegate(delegate)
         return delegate.rebuild()
 
@@ -844,16 +813,15 @@ def _copy_config_to_delegate(self, delegate: Builder) -> None:
     def _create_builder(
         self,
         name: str | None,
-        source: str | None,
         scheme: str | None,
     ) -> Builder:
-        """Create the appropriate builder based on name, source, and scheme."""
+        """Create the appropriate builder based on name and scheme."""
         # Find the builder matching the specified name, if any
         if name:
             factory = find_factory_by_name(name)
             if factory is None:
                 raise ValueError(f"Unknown builder: {name}")
-            return factory.create_builder(source, scheme)
+            return factory.create_builder()
 
         # Detect scheme from content if content is provided but scheme is not
         effective_scheme = scheme
@@ -865,18 +833,9 @@ def _create_builder(
             factory = find_factory_by_scheme(effective_scheme)
             if factory is None:
                 raise ValueError(f"No builder supports scheme: {effective_scheme}")
-            return factory.create_builder(source, effective_scheme)
+            return factory.create_builder()
 
-        # Find the highest-priority builder that supports this source
-        if source:
-            factory = find_factory_by_source(source)
-            if factory is None:
-                raise ValueError(f"No builder supports source: {source}")
-            return factory.create_builder(source)
-
-        raise ValueError(
-            "At least one of builder name, source, content, and scheme must be non-null"
-        )
+        raise ValueError("Content and/or scheme must be provided for dynamic builder")
 
 
 # Builders utility class
@@ -1021,26 +980,6 @@ def find_factory_for_wrapping(env_dir: str | Path) -> BuilderFactory | None:
     return None
 
 
-def find_factory_by_source(source: str) -> BuilderFactory | None:
-    """
-    Finds the first factory that can build from the given source file.
-    Factories are checked in priority order (highest priority first).
-
-    Args:
-        source: The source file path to find a factory for
-
-    Returns:
-        The first factory that can build from the source, or None if none found
-    """
-    if source is None:
-        raise ValueError("Cannot auto-detect builder: no source specified")
-    factories = Builders._discover_factories()
-    for factory in factories:
-        if factory.supports_source(source):
-            return factory
-    return None
-
-
 def can_wrap(env_dir: str | Path) -> bool:
     """
     Checks if the given directory can be wrapped as a known environment type.