Add EnsureWriteableDirectory.__fspath__ method

* Using `__fspath__` method makes the class explicitly conform to the `os.PathLike`
  protocol. It signals that the object is designed to be used as file path.
* Relying `__getattr__` can sometimes have subtle side effects. An explicit
  implementation of `__fspath__` method is always safer.

Author: tomschr

src/docbuild/models/path.py

@@ -3,29 +3,28 @@
 import os
 from pathlib import Path
 from typing import Any, Self
+
 from pydantic import GetCoreSchemaHandler
-from pydantic_core import core_schema 
+from pydantic_core import core_schema
 
 
 class EnsureWritableDirectory:
-    """
-    A Pydantic custom type that ensures a directory exists and is writable.
+    """A Pydantic custom type that ensures a directory exists and is writable.
 
     Behavior:
     1. Expands user paths (e.g., "~/data" -> "/home/user/data").
     2. Validates input is a path.
     3. If path DOES NOT exist: It creates it (including parents).
-    4. If path DOES exist (or was just created): It checks is_dir() and R/W/X permissions.
+    4. If path DOES exist (or was just created): It checks is_dir()
+       and R/W/X permissions.
     """
 
-
     def __init__(self, path: str | Path) -> None:
-        """
-        Initializes the instance with the fully resolved and expanded path.
+        """Initialize the instance with the fully resolved and expanded path.
+
         Assumes the validation step (validate_and_create) has already handled
         creation and permission checks.
         """
-
         self._path: Path = Path(path).expanduser().resolve()
 
     # --- Pydantic V2 Core Schema ---
@@ -59,10 +58,10 @@ def __get_pydantic_core_schema__(
 
     @classmethod
     def validate_and_create(cls, path: Path) -> Self:
-        """
-        Expands user, checks if path exists. If not, creates it. Then checks permissions.
-        """
+        """Expand user, checks if path exists.
 
+        If not, creates it. Then checks permissions.
+        """
         # Ensure user expansion happens before any filesystem operations
         path = path.expanduser()
 
@@ -73,7 +72,7 @@ def validate_and_create(cls, path: Path) -> Self:
                 # exist_ok=True: prevents race conditions
                 path.mkdir(parents=True, exist_ok=True)
             except OSError as e:
-                raise ValueError(f"Could not create directory '{path}': {e}")
+                raise ValueError(f"Could not create directory '{path}': {e}") from e
 
         # 2. Type Check
         if not path.is_dir():
@@ -95,13 +94,24 @@ def validate_and_create(cls, path: Path) -> Self:
         return cls(path)
 
     # --- Usability Methods ---
-
     def __str__(self) -> str:
+        """Return the string representation of the path."""
         return str(self._path)
-    
+
     def __repr__(self) -> str:
+        """Return the developer-friendly representation of the object."""
         return f"{self.__class__.__name__}('{self._path}')"
-    
-    # Allows access to methods/attributes of the underlying Path object (e.g., .joinpath)
+
+    def __truediv__(self, other: str) -> Path:
+        """Implement the / operator to delegate to the underlying Path object."""
+        return self._path / other
+
+    # Allows access to methods/attributes of the underlying Path object
+    # (e.g., .joinpath)
     def __getattr__(self, name: str) -> Any:
+        """Delegate attribute access to the underlying Path object."""
         return getattr(self._path, name)
+
+    def __fspath__(self) -> str:
+        """Return the string path for os.PathLike compatibility."""
+        return str(self._path)

tests/models/test_path.py

@@ -185,3 +185,32 @@ def test_writable_directory_attribute_access(tmp_path: Path):
     # Test string representation
     assert str(model.writable_dir) == str(test_dir.resolve())
     assert repr(model.writable_dir).startswith("EnsureWritableDirectory")
+
+
+@pytest.mark.parametrize(
+    "path_consumer, expected_factory",
+    [
+        (os.fspath, lambda p: str(p.resolve())),
+        (Path, lambda p: p.resolve()),
+        (lambda p: (p / "test.txt").read_text(), lambda p: "hello"),
+    ],
+    ids=["os.fspath", "Path constructor", "open and read"],
+)
+def test_fspath_protocol_compatibility(
+    request: pytest.FixtureRequest,
+    tmp_path: Path,
+    path_consumer, expected_factory
+):
+    """Test that EnsureWritableDirectory works with functions expecting os.PathLike."""
+    test_dir = tmp_path / "fspath_test"
+    model = PathTestModel(writable_dir=test_dir)  # type: ignore
+    custom_path_obj = model.writable_dir
+
+    # Pre-condition for the open() test case
+    if request.node.callspec.id == "open and read":
+        (test_dir / "test.txt").write_text("hello")
+
+    # Execute the function that consumes the path-like object
+    result = path_consumer(custom_path_obj)
+    expected = expected_factory(test_dir)
+    assert result == expected