Ditch Protocol in favor of ABC class hierarchies

== Why? ==

The use of Protocol was done with the intention of allowing third-party
duck-typed implementations of interface-style classes. But the mypy
static type analyzer yields errors if type inheritance is not explicit.
If third-party developers create duck-typed implementations without
inheriting from Builder, they'll hit mypy errors when their implicit
builder instance is used anywhere that expects the Builder type (e.g.
the BuildException constructor).

The only way to avoid the error is by explicitly inheriting from the
Protocol anyway:
class MyThirdPartyBuilder(Builder):  # Still need to inherit!
    ...

So the Protocol doesn't actually enable true structural duck-typing in
practice with mypy—it still requires explicit inheritance. This defeats
the whole purpose of using Protocol over ABC.

The Protocol approach only provides value if:
- You're not using static type checkers, OR
- You mark the Protocol as @runtime_checkable and use it only for
  runtime isinstance() checks, OR
- You're okay telling third-party developers "implement the interface
  but also inherit from the Protocol" (which defeats the purpose)

This codebase cares about mypy compliance, so the Protocol provides
no practical benefit over ABC. Therefore, we may as well use:

    from abc import ABC, abstractmethod

    class Builder(ABC):
        @AbstractMethod
        def name(self) -> str: ...
        # etc.

This is:
- Clearer in intent (you must inherit)
- Simpler to understand
- Identical in practice (since inheritance is required anyway for mypy)

The Protocol design was well-intentioned but doesn't deliver on its
promise in a type-checked codebase.

== Summary of Changes ==

1. Converted all Protocols to ABC:
   - Builder(Protocol) → Builder(ABC)
   - BuilderFactory(Protocol) → BuilderFactory(ABC)
   - Scheme(Protocol) → Scheme(ABC)
   - ScriptSyntax(Protocol) → ScriptSyntax(ABC)

2. Aligned Python Builder with Java's default methods:

   In Builder ABC, these are now concrete default methods matching Java:
   - rebuild() - calls delete() then build()
   - file() - reads file and calls content()
   - url() - fetches URL and calls content()
   - log_debug() - subscribes output/error to stdout/stderr

   All other methods remain abstract (require implementation).

3. Cleaned up BaseBuilder:
   - Removed duplicate implementations now in Builder
   - Made it much thinner - just stores configuration and implements
     required abstract methods

Co-authored-by: Claude <noreply@anthropic.com>

Author: ctrueden

src/appose/builder/__init__.py

@@ -40,8 +40,9 @@
 import os
 import shutil
 import sys
+from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Callable, Protocol
+from typing import Callable
 from urllib.request import urlopen
 
 from ..environment import Environment
@@ -81,16 +82,17 @@ def __init__(
         self.__cause__: Exception | None = cause
 
 
-class Builder(Protocol):
+class Builder(ABC):
     """
-    Base protocol for all Appose environment builders.
+    Base class for all Appose environment builders.
 
     Builders are responsible for creating and configuring Appose environments.
 
     The type parameter enables fluent method chaining to return the concrete
     builder type without requiring subclasses to override every method.
     """
 
+    @abstractmethod
     def name(self) -> str:
         """
         Returns the name of this builder (e.g., "pixi", "mamba", "uv", "custom").
@@ -100,6 +102,7 @@ def name(self) -> str:
         """
         ...
 
+    @abstractmethod
     def build(self) -> Environment:
         """
         Builds the environment. This is the terminator method for any fluid building chain.
@@ -129,8 +132,13 @@ def rebuild(self) -> Environment:
         Raises:
             BuildException: If the build fails
         """
-        ...
+        try:
+            self.delete()
+        except Exception as e:
+            raise BuildException(self, cause=e)
+        return self.build()
 
+    @abstractmethod
     def delete(self) -> None:
         """
         Deletes the builder's linked environment directory, if any.
@@ -140,6 +148,7 @@ def delete(self) -> None:
         """
         ...
 
+    @abstractmethod
     def wrap(self, env_dir: str | Path) -> Environment:
         """
         Wraps an existing environment directory, detecting and using any
@@ -160,6 +169,7 @@ def wrap(self, env_dir: str | Path) -> Environment:
         """
         ...
 
+    @abstractmethod
     def env(self, key: str, value: str) -> Builder:
         """
         Sets an environment variable to be passed to worker processes.
@@ -173,6 +183,7 @@ def env(self, key: str, value: str) -> Builder:
         """
         ...
 
+    @abstractmethod
     def env_vars(self, vars: dict[str, str]) -> Builder:
         """
         Sets multiple environment variables to be passed to worker processes.
@@ -185,6 +196,7 @@ def env_vars(self, vars: dict[str, str]) -> Builder:
         """
         ...
 
+    @abstractmethod
     def set_name(self, env_name: str) -> Builder:
         """
         Sets the name for the environment.
@@ -198,6 +210,7 @@ def set_name(self, env_name: str) -> Builder:
         """
         ...
 
+    @abstractmethod
     def base(self, env_dir: str | Path) -> Builder:
         """
         Sets the base directory for the environment.
@@ -211,6 +224,7 @@ def base(self, env_dir: str | Path) -> Builder:
         """
         ...
 
+    @abstractmethod
     def channels(self, *channels: str) -> Builder:
         """
         Adds channels/repositories to search for packages.
@@ -241,8 +255,15 @@ def file(self, path: str | Path) -> Builder:
         Raises:
             BuildException: If the file cannot be read
         """
-        ...
+        try:
+            file_path = Path(path)
+            with open(file_path, "r", encoding="utf-8") as f:
+                content = f.read()
+            return self.content(content)
+        except Exception as e:
+            raise BuildException(self, cause=e)
 
+    @abstractmethod
     def content(self, content: str) -> Builder:
         """
         Specifies configuration file content to build from.
@@ -270,8 +291,14 @@ def url(self, url: str) -> Builder:
         Raises:
             BuildException: If the URL cannot be read
         """
-        ...
+        try:
+            with urlopen(url) as response:
+                content = response.read().decode("utf-8")
+            return self.content(content)
+        except Exception as e:
+            raise BuildException(self, cause=e)
 
+    @abstractmethod
     def scheme(self, scheme: str) -> Builder:
         """
         Explicitly specifies the scheme for the configuration.
@@ -285,6 +312,7 @@ def scheme(self, scheme: str) -> Builder:
         """
         ...
 
+    @abstractmethod
     def subscribe_progress(self, subscriber: ProgressConsumer) -> Builder:
         """
         Registers a callback to be invoked when progress happens during environment building.
@@ -297,6 +325,7 @@ def subscribe_progress(self, subscriber: ProgressConsumer) -> Builder:
         """
         ...
 
+    @abstractmethod
     def subscribe_output(self, subscriber: Callable[[str], None]) -> Builder:
         """
         Registers a callback to be invoked when output is generated during environment building.
@@ -309,6 +338,7 @@ def subscribe_output(self, subscriber: Callable[[str], None]) -> Builder:
         """
         ...
 
+    @abstractmethod
     def subscribe_error(self, subscriber: Callable[[str], None]) -> Builder:
         """
         Registers a callback to be invoked when errors occur during environment building.
@@ -321,6 +351,7 @@ def subscribe_error(self, subscriber: Callable[[str], None]) -> Builder:
         """
         ...
 
+    @abstractmethod
     def flags(self, *flags: str) -> Builder:
         """
         Adds command-line flags to be passed to the underlying tool during build operations.
@@ -347,17 +378,20 @@ def log_debug(self) -> Builder:
         Returns:
             This builder instance, for fluent-style programming
         """
-        ...
+        return self.subscribe_output(
+            lambda msg: print(msg, file=sys.stdout, end="")
+        ).subscribe_error(lambda msg: print(msg, file=sys.stderr, end=""))
 
 
-class BuilderFactory(Protocol):
+class BuilderFactory(ABC):
     """
-    Factory protocol for creating builder instances.
+    Factory base class for creating builder instances.
 
     Implementations are discovered at runtime via entry points and managed by
     the Builders utility class.
     """
 
+    @abstractmethod
     def create_builder(self) -> Builder:
         """
         Creates a new builder instance with no configuration.
@@ -368,6 +402,7 @@ def create_builder(self) -> Builder:
         """
         ...
 
+    @abstractmethod
     def name(self) -> str:
         """
         Returns the name of this builder (e.g., "pixi", "mamba", "custom").
@@ -377,6 +412,7 @@ def name(self) -> str:
         """
         ...
 
+    @abstractmethod
     def supports_scheme(self, scheme: str) -> bool:
         """
         Checks if this builder supports the given scheme.
@@ -389,6 +425,7 @@ def supports_scheme(self, scheme: str) -> bool:
         """
         ...
 
+    @abstractmethod
     def priority(self) -> float:
         """
         Returns the priority of this builder for scheme resolution.
@@ -399,6 +436,7 @@ def priority(self) -> float:
         """
         ...
 
+    @abstractmethod
     def can_wrap(self, env_dir: str | Path) -> bool:
         """
         Checks if this builder can wrap the given existing environment directory.
@@ -412,7 +450,7 @@ def can_wrap(self, env_dir: str | Path) -> bool:
         ...
 
 
-class BaseBuilder:
+class BaseBuilder(Builder):
     """
     Base class for environment builders.
     Provides common implementation for the Builder protocol.
@@ -430,14 +468,6 @@ def __init__(self):
         self.source_content: str | None = None
         self.scheme: str | None = None
 
-    def rebuild(self) -> Environment:
-        """Default implementation: delete then build."""
-        try:
-            self.delete()
-        except Exception as e:
-            raise BuildException(self, cause=e)
-        return self.build()
-
     def delete(self) -> None:
         """Default implementation: delete env_dir if it exists."""
         dir_path = self._env_dir()
@@ -479,30 +509,11 @@ def channels(self, *channels: str) -> BaseBuilder:
         self.channels_list.extend(channels)
         return self
 
-    def file(self, path: str | Path) -> BaseBuilder:
-        """Load configuration from a file."""
-        try:
-            file_path = Path(path)
-            with open(file_path, "r", encoding="utf-8") as f:
-                content = f.read()
-            return self.content(content)
-        except Exception as e:
-            raise BuildException(self, cause=e)
-
     def content(self, content: str) -> BaseBuilder:
         """Set configuration content."""
         self.source_content = content
         return self
 
-    def url(self, url: str) -> BaseBuilder:
-        """Load configuration from a URL."""
-        try:
-            with urlopen(url) as response:
-                content = response.read().decode("utf-8")
-            return self.content(content)
-        except Exception as e:
-            raise BuildException(self, cause=e)
-
     def scheme(self, scheme: str) -> BaseBuilder:
         """Set the explicit scheme."""
         self.scheme = scheme
@@ -528,12 +539,6 @@ def flags(self, *flags: str) -> BaseBuilder:
         self.flags_list.extend(flags)
         return self
 
-    def log_debug(self) -> BaseBuilder:
-        """Log output and errors to stderr."""
-        return self.subscribe_output(
-            lambda msg: print(msg, file=sys.stdout, end="")
-        ).subscribe_error(lambda msg: print(msg, file=sys.stderr, end=""))
-
     # Helper methods
 
     def _env_name(self) -> str:

src/appose/builder/mamba.py

@@ -35,7 +35,7 @@
 
 from pathlib import Path
 
-from . import BaseBuilder, BuildException, Builder
+from . import BaseBuilder, BuildException, Builder, BuilderFactory
 from ..environment import Environment
 
 
@@ -213,7 +213,7 @@ def _create_environment(self, env_dir: Path, mamba) -> Environment:
         return self._create_env(base, bin_paths, launch_args)
 
 
-class MambaBuilderFactory:
+class MambaBuilderFactory(BuilderFactory):
     """
     Factory for creating MambaBuilder instances.
     """

src/appose/builder/pixi.py

@@ -34,7 +34,7 @@
 
 from pathlib import Path
 
-from . import BaseBuilder, BuildException, Builder
+from . import BaseBuilder, BuildException, Builder, BuilderFactory
 from ..environment import Environment
 
 
@@ -317,7 +317,7 @@ def _create_environment(self, env_dir: Path, pixi) -> Environment:
         return self._create_env(base, bin_paths, launch_args)
 
 
-class PixiBuilderFactory:
+class PixiBuilderFactory(BuilderFactory):
     """
     Factory for creating PixiBuilder instances.
     """

src/appose/builder/uv.py

@@ -35,7 +35,7 @@
 
 from pathlib import Path
 
-from . import BaseBuilder, BuildException, Builder
+from . import BaseBuilder, BuildException, Builder, BuilderFactory
 from ..environment import Environment
 
 
@@ -284,7 +284,7 @@ def _create_environment(self, env_dir: Path) -> Environment:
         return self._create_env(base, bin_paths, launch_args)
 
 
-class UvBuilderFactory:
+class UvBuilderFactory(BuilderFactory):
     """
     Factory for creating UvBuilder instances.
     """