Further refined path handling and added more tests

Author: AlePouroullis

src/humanloop/overload.py

@@ -1,28 +1,30 @@
 import inspect
 import logging
 import types
-from typing import Any, Dict, Optional, Union, Callable
+from pathlib import Path
+from typing import Any, Callable, Dict, Optional, Union
 
+from humanloop import path_utils
+from humanloop.agents.client import AgentsClient
 from humanloop.context import (
     get_decorator_context,
     get_evaluation_context,
     get_trace_id,
 )
+from humanloop.datasets.client import DatasetsClient
 from humanloop.error import HumanloopRuntimeError
-from humanloop.sync.sync_client import SyncClient
-from humanloop.prompts.client import PromptsClient
+from humanloop.evaluators.client import EvaluatorsClient
 from humanloop.flows.client import FlowsClient
-from humanloop.datasets.client import DatasetsClient
-from humanloop.agents.client import AgentsClient
+from humanloop.prompts.client import PromptsClient
+from humanloop.sync.sync_client import SyncClient
 from humanloop.tools.client import ToolsClient
-from humanloop.evaluators.client import EvaluatorsClient
 from humanloop.types import FileType
+from humanloop.types.agent_call_response import AgentCallResponse
 from humanloop.types.create_evaluator_log_response import CreateEvaluatorLogResponse
 from humanloop.types.create_flow_log_response import CreateFlowLogResponse
 from humanloop.types.create_prompt_log_response import CreatePromptLogResponse
 from humanloop.types.create_tool_log_response import CreateToolLogResponse
 from humanloop.types.prompt_call_response import PromptCallResponse
-from humanloop.types.agent_call_response import AgentCallResponse
 
 logger = logging.getLogger("humanloop.sdk")
 
@@ -95,16 +97,21 @@ def _handle_local_files(
 
     path = kwargs["path"]
 
-    # Check if the path has a file type extension (.prompt/.agent)
-    if sync_client.is_file(path):
-        file_type = _get_file_type_from_client(client)
+    # First check for path format issues (absolute paths or leading/trailing slashes)
+    normalized_path = path.strip("/")
+    if Path(path).is_absolute() or path != normalized_path:
+        raise HumanloopRuntimeError(
+            f"Path '{path}' format is invalid. "
+            f"Paths must follow the standard API format 'path/to/resource' without leading or trailing slashes. "
+            f"Please use '{normalized_path}' instead."
+        )
 
-        # Safely extract the extension and path by handling potential errors
+    # Then check for file extensions
+    if sync_client.is_file(path):
         try:
             parts = path.rsplit(".", 1)
             path_without_extension = parts[0] if len(parts) > 0 else path
         except Exception:
-            # Fallback to original path if any error occurs
             path_without_extension = path
 
         raise HumanloopRuntimeError(
@@ -124,7 +131,7 @@ def _handle_local_files(
 
     file_type = _get_file_type_from_client(client)
     if file_type not in SyncClient.SERIALIZABLE_FILE_TYPES:
-        raise HumanloopRuntimeError(f"Local files are not supported for `{file_type}` files.")
+        raise HumanloopRuntimeError(f"Local files are not supported for `{file_type.capitalize()}` files: '{path}'.")
 
     # If file_type is already specified in kwargs (prompt or agent), it means user provided a Prompt- or AgentKernelRequestParams object
     if file_type in kwargs and not isinstance(kwargs[file_type], str):

src/humanloop/path_utils.py

@@ -1,39 +1,22 @@
 from pathlib import Path
-from typing import Optional
 
 from humanloop.error import HumanloopRuntimeError
 
 
-def validate_no_extensions(path: str, allowed_extensions: Optional[list[str]] = None) -> str:
-    """Validates that path has no extensions (or only allowed ones) and returns path without extension."""
-    if "." in path:
-        parts = path.rsplit(".", 1)
-        extension = parts[1] if len(parts) > 1 else ""
-        path_without_extension = parts[0]
-        
-        if allowed_extensions and extension in allowed_extensions:
-            return path
-        
-        raise HumanloopRuntimeError(
-            f"Path '{path}' includes a file extension which is not supported in this context. "
-            f"Use the format without extensions: '{path_without_extension}'."
-        )
-    return path
+def normalize_path(path: str, strip_extension: bool = False) -> str:
+    """Normalize a path to the standard API format: path/to/resource, where resource can be a file or a directory."""
+    # Remove leading/trailing slashes
+    path_obj = Path(path.strip("/"))
 
-def validate_no_slashes(path: str) -> str:
-    """Validates that path has no leading/trailing slashes."""
-    if path != path.strip("/"):
-        raise HumanloopRuntimeError(
-            f"Invalid path: '{path}'. Path should not contain leading/trailing slashes. "
-            f"Valid example: 'path/to/resource'"
-        )
-    return path
+    # Check if path is absolute
+    if path_obj.is_absolute():
+        raise HumanloopRuntimeError("Absolute paths are not supported. Ensure the ")
 
-def validate_not_absolute(path: str, base_dir: Optional[str] = None) -> str:
-    """Validates that path is not absolute."""
-    if Path(path).is_absolute():
-        message = f"Absolute paths are not supported: '{path}'."
-        if base_dir:
-            message += f" Paths should be relative to '{base_dir}'."
-        raise HumanloopRuntimeError(message)
-    return path
+    # Handle extension
+    if strip_extension:
+        normalized = str(path_obj.with_suffix(""))
+    else:
+        normalized = str(path_obj)
+
+    # Normalize separators
+    return "/".join(part for part in normalized.replace("\\", "/").split("/") if part)

src/humanloop/sync/sync_client.py

@@ -1,11 +1,13 @@
+import json
 import logging
-from pathlib import Path
-from typing import List, Optional, Tuple, TYPE_CHECKING, Union
-from functools import lru_cache
-import typing
 import time
+import typing
+from functools import lru_cache
+from pathlib import Path
+from typing import TYPE_CHECKING, List, Optional, Tuple
+
+from humanloop import path_utils
 from humanloop.error import HumanloopRuntimeError
-import json
 
 if TYPE_CHECKING:
     from humanloop.base_client import BaseHumanloop
@@ -154,30 +156,6 @@ def clear_cache(self) -> None:
         """Clear the LRU cache."""
         self.get_file_content.cache_clear()  # type: ignore [attr-defined]
 
-    def _normalize_path(self, path: str, strip_extension: bool = False) -> str:
-        """Normalize the path by:
-        1. Converting to a Path object to handle platform-specific separators
-        2. Removing any file extensions if strip_extension is True
-        3. Converting to a string with forward slashes and no leading/trailing slashes
-        """
-        # Convert to Path object to handle platform-specific separators
-        path_obj = Path(path)
-
-        # Reject absolute paths to ensure all paths are relative to base_dir.
-        # This maintains consistency with the remote filesystem where paths are relative to project root.
-        if path_obj.is_absolute():
-            raise HumanloopRuntimeError(
-                f"Absolute paths are not supported: `{path}`. "
-                f"Paths should be relative to the base directory (`{self.base_dir}`)."
-            )
-
-        # Remove extension, convert to string with forward slashes, and remove leading/trailing slashes
-        if strip_extension:
-            normalized = str(path_obj.with_suffix(""))
-        else:
-            normalized = str(path_obj)
-        # Replace all backslashes and normalize multiple forward slashes
-        return "/".join(part for part in normalized.replace("\\", "/").split("/") if part)
 
     def is_file(self, path: str) -> bool:
         """Check if the path is a file by checking for .{file_type} extension for serializable file types.
@@ -369,7 +347,7 @@ def pull(self, path: Optional[str] = None, environment: Optional[str] = None) ->
             is_file_path = self.is_file(path)
 
             # For API communication, we need path without extension
-            api_path = self._normalize_path(path, strip_extension=True)
+            api_path = path_utils.normalize_path(path, strip_extension=True)
 
         logger.info(f"Starting pull: path={api_path or '(root)'}, environment={environment or '(default)'}")
 

tests/custom/integration/test_overload.py

@@ -54,9 +54,9 @@ def test_path_validation(
         f"//{test_file.path}//",  # Multiple leading and trailing slashes
     ]
 
-    # THEN appropriate error should be raised
+    # THEN appropriate error should be raised about slashes
     for path in slash_paths:
-        with pytest.raises(HumanloopRuntimeError, match=""):
+        with pytest.raises(HumanloopRuntimeError, match="Path .* format is invalid"):
             if test_file.type == "prompt":
                 humanloop_client.prompts.call(path=path, messages=[{"role": "user", "content": "Testing"}])
             elif test_file.type == "agent":
@@ -68,9 +68,9 @@ def test_path_validation(
         f"/{test_file.path}.{test_file.type}",  # Extension and leading slash
     ]
 
-    # THEN the extension error should be prioritized (more specific validation first)
+    # THEN the format validation error should be raised first (before extension validation)
     for path in combined_paths:
-        with pytest.raises(HumanloopRuntimeError, match="includes a file extension which is not supported"):
+        with pytest.raises(HumanloopRuntimeError, match="Path .* format is invalid"):
             if test_file.type == "prompt":
                 humanloop_client.prompts.call(path=path, messages=[{"role": "user", "content": "Testing"}])
             elif test_file.type == "agent":

tests/custom/integration/test_sync.py

@@ -44,10 +44,58 @@ def test_pull_with_invalid_path(
     with pytest.raises(HumanloopRuntimeError, match=f"Directory `{non_existent_path}` does not exist"):
         humanloop_client.pull(path=non_existent_path)
 
+
 def test_pull_with_invalid_environment(
     get_humanloop_client: GetHumanloopClientFn,
 ):
     """Test that humanloop.sync() raises an error when the environment is invalid"""
     humanloop_client = get_humanloop_client()
-    with pytest.raises(HumanloopRuntimeError, match="Invalid environment"):
-        humanloop_client.pull(environment="invalid_environment")
+    with pytest.raises(HumanloopRuntimeError, match="Environment .* does not exist"):
+        humanloop_client.pull(environment="invalid_environment")
+
+
+# def test_pull_with_environment(
+#     get_humanloop_client: GetHumanloopClientFn,
+#     syncable_files_fixture: list[SyncableFile],
+# ):
+#     """Test that humanloop.sync() correctly syncs files from a specific environment"""
+#     # NOTE: This test is currently not feasible to implement because:
+#     # 1. We have no way of deploying to an environment using its name, only by ID
+#     # 2. There's no API endpoint to retrieve environments for an organization
+#     #
+#     # If implemented, this test would:
+#     # 1. Deploy one of the syncable files to a specific environment (e.g., "production" as it's non-default)
+#     # 2. Pull files filtering by the production environment
+#     # 3. Check if the deployed file is present in the local filesystem
+#     # 4. Verify that none of the other syncable files (that weren't deployed to production) are present
+#     #    This would confirm that environment filtering works correctly
+
+
+def test_pull_with_path_filter(
+    get_humanloop_client: GetHumanloopClientFn,
+    syncable_files_fixture: list[SyncableFile],
+    sdk_test_dir: str,
+):
+    """Test that humanloop.sync() correctly filters files by path when pulling"""
+    # GIVEN a client
+    humanloop_client = get_humanloop_client()
+
+    # First clear any existing files to ensure clean state
+    import shutil
+
+    if Path("humanloop").exists():
+        shutil.rmtree("humanloop")
+
+    # WHEN pulling only files from the sdk_test_dir path
+    humanloop_client.pull(path=sdk_test_dir)
+
+    # THEN count the total number of files synced
+    synced_file_count = 0
+    for path in Path("humanloop").glob("**/*"):
+        if path.is_file():
+            synced_file_count += 1
+
+    # The count should match our fixture length
+    assert synced_file_count == len(syncable_files_fixture), (
+        f"Expected {len(syncable_files_fixture)} files, got {synced_file_count}"
+    )

tests/custom/sync/test_client.py

@@ -33,36 +33,6 @@ def test_init(sync_client: SyncClient, tmp_path: Path):
     assert sync_client.SERIALIZABLE_FILE_TYPES == frozenset(["prompt", "agent"])
 
 
-def test_normalize_path(sync_client: SyncClient):
-    """Test path normalization functionality."""
-    # GIVEN various file paths with different formats
-    test_cases = [
-        # Input path, expected with strip_extension=False, expected with strip_extension=True
-        ("path/to/file.prompt", "path/to/file.prompt", "path/to/file"),
-        ("path\\to\\file.agent", "path/to/file.agent", "path/to/file"),
-        ("trailing/slashes/file.agent/", "trailing/slashes/file.agent", "trailing/slashes/file"),
-        ("multiple//slashes//file.prompt", "multiple/slashes/file.prompt", "multiple/slashes/file"),
-    ]
-
-    # Test with strip_extension=False (default)
-    for input_path, expected_with_ext, _ in test_cases:
-        # WHEN they are normalized without stripping extension
-        normalized = sync_client._normalize_path(input_path, strip_extension=False)
-        # THEN they should be converted to the expected format with extension
-        assert normalized == expected_with_ext
-
-    # Test with strip_extension=True
-    for input_path, _, expected_without_ext in test_cases:
-        # WHEN they are normalized with extension stripping
-        normalized = sync_client._normalize_path(input_path, strip_extension=True)
-        # THEN they should be converted to the expected format without extension
-        assert normalized == expected_without_ext
-
-    # Test absolute path raises error
-    with pytest.raises(HumanloopRuntimeError, match="Absolute paths are not supported"):
-        sync_client._normalize_path("/leading/slashes/file.prompt")
-
-
 def test_is_file(sync_client: SyncClient):
     """Test file type detection with case insensitivity."""
     # GIVEN a SyncClient instance

tests/custom/unit/test_path_utils.py

@@ -0,0 +1,28 @@
+from humanloop import path_utils
+
+
+def test_normalize_path():
+    """Test path normalization functionality."""
+    # GIVEN various file paths with different formats
+    test_cases = [
+        # Input path, expected with strip_extension=False, expected with strip_extension=True
+        ("path/to/file.prompt", "path/to/file.prompt", "path/to/file"),
+        ("path\\to\\file.agent", "path/to/file.agent", "path/to/file"),
+        ("/leading/slashes/file.prompt", "leading/slashes/file.prompt", "leading/slashes/file"),
+        ("trailing/slashes/file.agent/", "trailing/slashes/file.agent", "trailing/slashes/file"),
+        ("multiple//slashes//file.prompt", "multiple/slashes/file.prompt", "multiple/slashes/file"),
+    ]
+
+    # Test with strip_extension=False (default)
+    for input_path, expected_with_ext, _ in test_cases:
+        # WHEN they are normalized without stripping extension
+        normalized = path_utils.normalize_path(input_path, strip_extension=False)
+        # THEN they should be converted to the expected format with extension
+        assert normalized == expected_with_ext
+
+    # Test with strip_extension=True
+    for input_path, _, expected_without_ext in test_cases:
+        # WHEN they are normalized with extension stripping
+        normalized = path_utils.normalize_path(input_path, strip_extension=True)
+        # THEN they should be converted to the expected format without extension
+        assert normalized == expected_without_ext