fix: resolve test failures and improve type safety

- Fix file handler to properly extract basenames from Path objects
- Update session close tests to match requests library behavior
- Add TYPE_CHECKING imports to resolve circular dependencies
- Improve type annotations throughout codebase
- Fix linting issues identified by ruff
- All 82 tests now passing with 92.46% coverage

Author: jdrhyne

scripts/generate_api_methods.py

@@ -3,9 +3,7 @@
 
 import re
 from pathlib import Path
-from typing import Any, Dict, List, Optional, Set
-
-import yaml
+from typing import Any, Dict, List
 
 
 def to_snake_case(name: str) -> str:
@@ -21,7 +19,7 @@ def get_python_type(schema: Dict[str, Any]) -> str:
     """Convert OpenAPI schema type to Python type hint."""
     if not schema:
         return "Any"
-    
+
     type_mapping = {
         "string": "str",
         "integer": "int",
@@ -30,7 +28,7 @@ def get_python_type(schema: Dict[str, Any]) -> str:
         "array": "List[Any]",
         "object": "Dict[str, Any]",
     }
-    
+
     schema_type = schema.get("type", "string")
     return type_mapping.get(schema_type, "Any")
 
@@ -213,7 +211,7 @@ def create_manual_tools() -> List[Dict[str, Any]]:
             },
         },
     ]
-    
+
     return tools
 
 
@@ -224,11 +222,11 @@ def generate_method_code(tool_info: Dict[str, Any]) -> str:
     summary = tool_info["summary"]
     description = tool_info["description"]
     parameters = tool_info["parameters"]
-    
+
     # Build parameter list
     param_list = ["self", "input_file: FileInput"]
     param_docs = []
-    
+
     # Add required parameters first
     for param_name, param_info in parameters.items():
         if param_info["required"]:
@@ -238,10 +236,10 @@ def generate_method_code(tool_info: Dict[str, Any]) -> str:
                 param_type = "'FileInput'"  # Forward reference
             param_list.append(f"{param_name}: {param_type}")
             param_docs.append(f"        {param_name}: {param_info['description']}")
-    
+
     # Always add output_path
     param_list.append("output_path: Optional[str] = None")
-    
+
     # Add optional parameters
     for param_name, param_info in parameters.items():
         if not param_info["required"]:
@@ -251,7 +249,7 @@ def generate_method_code(tool_info: Dict[str, Any]) -> str:
                 base_type = param_type
             else:
                 base_type = param_type
-            
+
             default = param_info.get("default")
             if default is None:
                 param_list.append(f"{param_name}: Optional[{base_type}] = None")
@@ -261,30 +259,30 @@ def generate_method_code(tool_info: Dict[str, Any]) -> str:
                 else:
                     param_list.append(f"{param_name}: {base_type} = {default}")
             param_docs.append(f"        {param_name}: {param_info['description']}")
-    
+
     # Build method signature
     if len(param_list) > 3:  # Multiple parameters
         params_str = ",\n        ".join(param_list)
         method_signature = f"    def {method_name}(\n        {params_str},\n    ) -> Optional[bytes]:"
     else:
         params_str = ", ".join(param_list)
         method_signature = f"    def {method_name}({params_str}) -> Optional[bytes]:"
-    
+
     # Build docstring
     docstring_lines = [f'        """{summary}']
     if description and description != summary:
         docstring_lines.append("")
         docstring_lines.append(f"        {description}")
-    
+
     docstring_lines.extend([
         "",
         "        Args:",
         "            input_file: Input file (path, bytes, or file-like object).",
     ])
-    
+
     if param_docs:
         docstring_lines.extend(param_docs)
-    
+
     docstring_lines.extend([
         "            output_path: Optional path to save the output file.",
         "",
@@ -296,22 +294,22 @@ def generate_method_code(tool_info: Dict[str, Any]) -> str:
         "            APIError: For other API errors.",
         '        """',
     ])
-    
+
     # Build method body
     method_body = []
-    
+
     # Collect kwargs
     kwargs_params = [
-        f"{name}={name}" 
+        f"{name}={name}"
         for name in parameters.keys()
     ]
-    
+
     if kwargs_params:
         kwargs_str = ", ".join(kwargs_params)
         method_body.append(f'        return self._process_file("{tool_name}", input_file, output_path, {kwargs_str})')
     else:
         method_body.append(f'        return self._process_file("{tool_name}", input_file, output_path)')
-    
+
     # Combine all parts
     return "\n".join([
         method_signature,
@@ -325,10 +323,10 @@ def generate_api_methods(spec_path: Path, output_path: Path) -> None:
     # For Nutrient API, we'll use manually defined tools since they use
     # a build endpoint with actions rather than individual endpoints
     tools = create_manual_tools()
-    
+
     # Sort tools by method name
     tools.sort(key=lambda t: t["method_name"])
-    
+
     # Generate code
     code_lines = [
         '"""Direct API methods for individual document processing tools.',
@@ -350,12 +348,12 @@ def generate_api_methods(spec_path: Path, output_path: Path) -> None:
         '    """',
         '',
     ]
-    
+
     # Add methods
     for tool in tools:
         code_lines.append(generate_method_code(tool))
         code_lines.append("")  # Empty line between methods
-    
+
     # Write to file
     output_path.write_text("\n".join(code_lines))
     print(f"Generated {len(tools)} API methods in {output_path}")
@@ -364,5 +362,5 @@ def generate_api_methods(spec_path: Path, output_path: Path) -> None:
 if __name__ == "__main__":
     spec_path = Path("openapi_spec.yml")
     output_path = Path("src/nutrient/api/direct.py")
-    
-    generate_api_methods(spec_path, output_path)
+
+    generate_api_methods(spec_path, output_path)

src/nutrient/__init__.py

@@ -15,11 +15,11 @@
 
 __version__ = "0.1.0"
 __all__ = [
+    "APIError",
+    "AuthenticationError",
+    "FileProcessingError",
     "NutrientClient",
     "NutrientError",
-    "AuthenticationError",
-    "APIError",
-    "ValidationError",
     "TimeoutError",
-    "FileProcessingError",
-]
+    "ValidationError",
+]

src/nutrient/api/__init__.py

@@ -1 +1 @@
-"""API module for Nutrient DWS client."""
+"""API module for Nutrient DWS client."""

src/nutrient/api/direct.py

@@ -4,10 +4,13 @@
 for common document processing operations.
 """
 
-from typing import List, Optional
+from typing import TYPE_CHECKING, Any, List, Optional
 
 from nutrient.file_handler import FileInput
 
+if TYPE_CHECKING:
+    from nutrient.client import NutrientClient
+
 
 class DirectAPIMixin:
     """Mixin class containing Direct API methods.
@@ -16,6 +19,16 @@ class DirectAPIMixin:
     processing operations. They internally use the Build API.
     """
 
+    def _process_file(
+        self: "NutrientClient",
+        tool: str,
+        input_file: FileInput,
+        output_path: Optional[str] = None,
+        **options: Any,
+    ) -> Optional[bytes]:
+        """Process file method that will be provided by NutrientClient."""
+        raise NotImplementedError("This method is provided by NutrientClient")
+
     def convert_to_pdf(self, input_file: FileInput, output_path: Optional[str] = None) -> Optional[bytes]:
         """Convert a document to PDF
 

src/nutrient/builder.py

@@ -1,7 +1,6 @@
 """Builder API implementation for multi-step workflows."""
 
-import json
-from typing import Any, Dict, List, Optional, Union
+from typing import Any, Dict, List, Optional
 
 from nutrient.file_handler import FileInput, prepare_file_for_upload, save_file_output
 
@@ -20,7 +19,7 @@ class BuildAPIWrapper:
         ...     .execute(output_path="processed.pdf")
     """
 
-    def __init__(self, client, input_file: FileInput) -> None:
+    def __init__(self, client: Any, input_file: FileInput) -> None:
         """Initialize builder with client and input file.
         
         Args:
@@ -83,24 +82,24 @@ def execute(self, output_path: Optional[str] = None) -> Optional[bytes]:
         """
         # Prepare the build instructions
         instructions = self._build_instructions()
-        
+
         # Prepare file for upload
         file_field, file_data = prepare_file_for_upload(self._input_file)
         files = {file_field: file_data}
-        
+
         # Make API request
         result = self._client._http_client.post(
             "/build",
             files=files,
             json_data=instructions,
         )
-        
+
         # Handle output
         if output_path:
             save_file_output(result, output_path)
             return None
         else:
-            return result
+            return result  # type: ignore[no-any-return]
 
     def _build_instructions(self) -> Dict[str, Any]:
         """Build the instructions payload for the API.
@@ -115,11 +114,11 @@ def _build_instructions(self) -> Dict[str, Any]:
             ],
             "actions": self._actions,
         }
-        
+
         # Add output options if specified
         if self._output_options:
             instructions["output"] = self._output_options
-            
+
         return instructions
 
     def _map_tool_to_action(self, tool: str, options: Dict[str, Any]) -> Dict[str, Any]:
@@ -143,22 +142,22 @@ def _map_tool_to_action(self, tool: str, options: Dict[str, Any]) -> Dict[str, A
             "create-redactions": "createRedactions",
             "apply-redactions": "applyRedactions",
         }
-        
+
         action_type = tool_mapping.get(tool, tool)
-        
+
         # Build action dictionary
         action = {"type": action_type}
-        
+
         # Handle special cases for different action types
         if action_type == "rotate":
             action["rotateBy"] = options.get("degrees", 0)
             if "page_indexes" in options:
                 action["pageIndexes"] = options["page_indexes"]
-                
+
         elif action_type == "ocr":
             if "language" in options:
                 action["language"] = options["language"]
-                
+
         elif action_type == "watermark":
             if "text" in options:
                 action["text"] = options["text"]
@@ -168,11 +167,11 @@ def _map_tool_to_action(self, tool: str, options: Dict[str, Any]) -> Dict[str, A
                 action["opacity"] = options["opacity"]
             if "position" in options:
                 action["position"] = options["position"]
-                
+
         else:
             # For other actions, pass options directly
             action.update(options)
-            
+
         return action
 
     def __str__(self) -> str:
@@ -187,4 +186,4 @@ def __repr__(self) -> str:
             f"input_file={self._input_file!r}, "
             f"actions={self._actions!r}, "
             f"output_options={self._output_options!r})"
-        )
+        )