splurge-dsv 2025.1.1__py3-none-any.whl → 2025.1.2__py3-none-any.whl

splurge_dsv/resource_manager.py

@@ -11,19 +11,21 @@ Please preserve this header and all related material when sharing!
 This module is licensed under the MIT License.
 """
 
+# Standard library imports
+from collections.abc import Iterator
 from contextlib import contextmanager
 from pathlib import Path
-from typing import Iterator, Any, IO
+from typing import IO, Any
 
+# Local imports
 from splurge_dsv.exceptions import (
-    SplurgeResourceAcquisitionError,
-    SplurgeResourceReleaseError,
+    SplurgeFileEncodingError,
     SplurgeFileNotFoundError,
     SplurgeFilePermissionError,
-    SplurgeFileEncodingError
+    SplurgeResourceAcquisitionError,
+    SplurgeResourceReleaseError,
 )
 from splurge_dsv.path_validator import PathValidator
- 
 
 # Module-level constants for resource management
 DEFAULT_BUFFERING = -1  # Default buffering for file operations
@@ -38,14 +40,14 @@ def _safe_open_file(
     encoding: str | None = None,
     errors: str | None = None,
     newline: str | None = None,
-    buffering: int = DEFAULT_BUFFERING
+    buffering: int = DEFAULT_BUFFERING,
 ) -> IO[Any]:
     """
     Safely open a file with proper error handling.
-    
+
     This function provides centralized file opening with consistent error handling
     that converts standard file operation exceptions to custom exceptions.
-    
+
     Args:
         file_path: Path to the file
         mode: File open mode
@@ -53,10 +55,10 @@ def _safe_open_file(
         errors: Error handling for encoding
         newline: Newline handling
         buffering: Buffer size
-        
+
     Returns:
         File handle
-        
+
     Raises:
         SplurgeFileNotFoundError: If file is not found
         SplurgeFilePermissionError: If permission is denied
@@ -64,75 +66,51 @@ def _safe_open_file(
         SplurgeResourceAcquisitionError: If other file operation fails
     """
     try:
-        if 'b' in mode:
+        if "b" in mode:
             # Binary mode
-            return open(
-                file_path,
-                mode=mode,
-                buffering=buffering
-            )
+            return open(file_path, mode=mode, buffering=buffering)
         else:
             # Text mode
-            return open(
-                file_path,
-                mode=mode,
-                encoding=encoding,
-                errors=errors,
-                newline=newline,
-                buffering=buffering
-            )
+            return open(file_path, mode=mode, encoding=encoding, errors=errors, newline=newline, buffering=buffering)
     except FileNotFoundError as e:
-        raise SplurgeFileNotFoundError(
-            f"File not found: {file_path}",
-            details=str(e)
-        )
+        raise SplurgeFileNotFoundError(f"File not found: {file_path}", details=str(e)) from e
     except PermissionError as e:
-        raise SplurgeFilePermissionError(
-            f"Permission denied: {file_path}",
-            details=str(e)
-        )
+        raise SplurgeFilePermissionError(f"Permission denied: {file_path}", details=str(e)) from e
     except UnicodeDecodeError as e:
-        raise SplurgeFileEncodingError(
-            f"Encoding error reading file: {file_path}",
-            details=str(e)
-        )
+        raise SplurgeFileEncodingError(f"Encoding error reading file: {file_path}", details=str(e)) from e
     except OSError as e:
-        raise SplurgeResourceAcquisitionError(
-            f"Failed to open file: {file_path}",
-            details=str(e)
-        )
+        raise SplurgeResourceAcquisitionError(f"Failed to open file: {file_path}", details=str(e)) from e
 
 
 class ResourceManager:
     """
     Generic resource manager that implements the ResourceManagerProtocol.
-    
+
     This class provides a base implementation for resource management
     with acquire/release semantics.
     """
-    
+
     def __init__(self) -> None:
         """Initialize the resource manager."""
         self._resource: Any | None = None
         self._is_acquired_flag: bool = False
-    
+
     def acquire(self) -> Any:
         """
         Acquire the managed resource.
-        
+
         Returns:
             The acquired resource
-            
+
         Raises:
             NotImplementedError: If _create_resource is not implemented by subclass
             SplurgeResourceAcquisitionError: If resource cannot be acquired
         """
         if self._is_acquired_flag:
             raise SplurgeResourceAcquisitionError(
-                "Resource is already acquired",
-                details="Cannot acquire resource that is already in use"
+                "Resource is already acquired", details="Cannot acquire resource that is already in use"
             )
-        
+
         try:
             self._resource = self._create_resource()
             self._is_acquired_flag = True
@@ -141,74 +119,68 @@ class ResourceManager:
             # Re-raise NotImplementedError without wrapping it
             raise
         except Exception as e:
-            raise SplurgeResourceAcquisitionError(
-                "Failed to acquire resource",
-                details=str(e)
-            )
-    
+            raise SplurgeResourceAcquisitionError("Failed to acquire resource", details=str(e)) from e
+
     def release(self) -> None:
         """
         Release the managed resource.
-        
+
         Raises:
             SplurgeResourceReleaseError: If resource cannot be released
         """
         if not self._is_acquired_flag:
             return  # Nothing to release
-        
+
         try:
             self._cleanup_resource()
             self._resource = None
             self._is_acquired_flag = False
         except Exception as e:
-            raise SplurgeResourceReleaseError(
-                "Failed to release resource",
-                details=str(e)
-            )
-    
+            raise SplurgeResourceReleaseError("Failed to release resource", details=str(e)) from e
+
     def is_acquired(self) -> bool:
         """
         Check if the resource is currently acquired.
-        
+
         Returns:
             True if resource is acquired, False otherwise
         """
         return self._is_acquired_flag
-    
+
     def _create_resource(self) -> Any:
         """
         Create the resource to be managed.
-        
+
         This method should be overridden by subclasses to provide
         specific resource creation logic.
-        
+
         Returns:
             The created resource
-            
+
         Raises:
             NotImplementedError: If not overridden by subclass
         """
         raise NotImplementedError("Subclasses must implement _create_resource")
-    
+
     def _cleanup_resource(self) -> None:
         """
         Clean up the managed resource.
-        
+
         This method should be overridden by subclasses to provide
         specific resource cleanup logic.
         """
-        if self._resource is not None and hasattr(self._resource, 'close'):
+        if self._resource is not None and hasattr(self._resource, "close"):
             self._resource.close()
 
 
 class FileResourceManager:
     """
     Context manager for safe file operations with automatic cleanup.
-    
+
     This class provides context managers for reading and writing files
     with proper error handling and resource cleanup.
     """
-    
+
     def __init__(
         self,
         file_path: str | Path,
@@ -217,11 +189,11 @@ class FileResourceManager:
         encoding: str | None = DEFAULT_ENCODING,
         errors: str | None = None,
         newline: str | None = None,
-        buffering: int = DEFAULT_BUFFERING
+        buffering: int = DEFAULT_BUFFERING,
     ) -> None:
         """
         Initialize FileResourceManager.
-        
+
         Args:
             file_path: Path to the file
             mode: File open mode ('r', 'w', 'a', etc.)
@@ -229,16 +201,13 @@ class FileResourceManager:
             errors: Error handling for encoding
             newline: Newline handling
             buffering: Buffer size
-            
+
         Raises:
             SplurgePathValidationError: If file path is invalid
             SplurgeResourceAcquisitionError: If file cannot be opened
         """
         self._file_path = PathValidator.validate_path(
-            file_path,
-            must_exist=(mode in ['r', 'rb']),
-            must_be_file=True,
-            must_be_readable=(mode in ['r', 'rb'])
+            file_path, must_exist=(mode in ["r", "rb"]), must_be_file=True, must_be_readable=(mode in ["r", "rb"])
         )
         self.mode = mode
         self.encoding = encoding
@@ -246,14 +215,14 @@ class FileResourceManager:
         self.newline = newline
         self.buffering = buffering
         self._file_handle: IO[Any] | None = None
-    
+
     def __enter__(self) -> IO[Any]:
         """
         Open the file and return the file handle.
-        
+
         Returns:
             File handle
-            
+
         Raises:
             SplurgeFileNotFoundError: If file is not found
             SplurgeFilePermissionError: If permission is denied
@@ -266,19 +235,14 @@ class FileResourceManager:
             encoding=self.encoding,
             errors=self.errors,
             newline=self.newline,
-            buffering=self.buffering
+            buffering=self.buffering,
         )
         return self._file_handle
-    
-    def __exit__(
-        self,
-        exc_type: type | None,
-        exc_val: Exception | None,
-        exc_tb: Any | None
-    ) -> None:
+
+    def __exit__(self, exc_type: type | None, exc_val: Exception | None, exc_tb: Any | None) -> None:
         """
         Close the file handle and cleanup resources.
-        
+
         Args:
             exc_type: Exception type if an exception occurred
             exc_val: Exception value if an exception occurred
@@ -288,13 +252,10 @@ class FileResourceManager:
             try:
                 self._file_handle.close()
             except OSError as e:
-                raise SplurgeResourceReleaseError(
-                    f"Failed to close file: {self.file_path}",
-                    details=str(e)
-                )
+                raise SplurgeResourceReleaseError(f"Failed to close file: {self.file_path}", details=str(e)) from e
             finally:
                 self._file_handle = None
-    
+
     @property
     def file_path(self) -> Path | None:
         """Get the path of the temporary file."""
@@ -304,20 +265,15 @@ class FileResourceManager:
 class StreamResourceManager:
     """
     Context manager for stream operations.
-    
+
     This class provides context managers for managing data streams
     with proper cleanup and error handling.
     """
-    
-    def __init__(
-        self,
-        stream: Iterator[Any],
-        *,
-        auto_close: bool = True
-    ) -> None:
+
+    def __init__(self, stream: Iterator[Any], *, auto_close: bool = True) -> None:
         """
         Initialize StreamResourceManager.
-        
+
         Args:
             stream: Iterator to manage
             auto_close: Whether to automatically close the stream
@@ -325,42 +281,34 @@ class StreamResourceManager:
         self.stream = stream
         self.auto_close = auto_close
         self._is_closed = False
-    
+
     def __enter__(self) -> Iterator[Any]:
         """
         Return the stream.
-        
+
         Returns:
             Stream iterator
         """
         return self.stream
-    
-    def __exit__(
-        self,
-        exc_type: type | None,
-        exc_val: Exception | None,
-        exc_tb: Any | None
-    ) -> None:
+
+    def __exit__(self, exc_type: type | None, exc_val: Exception | None, exc_tb: Any | None) -> None:
         """
         Clean up the stream.
-        
+
         Args:
             exc_type: Exception type if an exception occurred
             exc_val: Exception value if an exception occurred
             exc_tb: Exception traceback if an exception occurred
         """
-        if self.auto_close and hasattr(self.stream, 'close'):
+        if self.auto_close and hasattr(self.stream, "close"):
             try:
                 self.stream.close()
             except Exception as e:
-                raise SplurgeResourceReleaseError(
-                    "Failed to close stream",
-                    details=str(e)
-                )
-        
+                raise SplurgeResourceReleaseError("Failed to close stream", details=str(e)) from e
+
         # Mark as closed after context manager exits, regardless of close method
         self._is_closed = True
-    
+
     @property
     def is_closed(self) -> bool:
         """Check if the stream is closed."""
@@ -375,11 +323,11 @@ def safe_file_operation(
     encoding: str | None = DEFAULT_ENCODING,
     errors: str | None = None,
     newline: str | None = None,
-    buffering: int = DEFAULT_BUFFERING
+    buffering: int = DEFAULT_BUFFERING,
 ) -> Iterator[IO[Any]]:
     """
     Context manager for safe file operations.
-    
+
     Args:
         file_path: Path to the file
         mode: File open mode
@@ -387,43 +335,34 @@ def safe_file_operation(
         errors: Error handling for encoding
         newline: Newline handling
         buffering: Buffer size
-        
+
     Yields:
         File handle
-        
+
     Raises:
         SplurgePathValidationError: If file path is invalid
         SplurgeResourceAcquisitionError: If file cannot be opened
         SplurgeResourceReleaseError: If file cannot be closed
     """
     manager = FileResourceManager(
-        file_path,
-        mode=mode,
-        encoding=encoding,
-        errors=errors,
-        newline=newline,
-        buffering=buffering
+        file_path, mode=mode, encoding=encoding, errors=errors, newline=newline, buffering=buffering
     )
     with manager as file_handle:
         yield file_handle
 
 
 @contextmanager
-def safe_stream_operation(
-    stream: Iterator[Any],
-    *,
-    auto_close: bool = True
-) -> Iterator[Iterator[Any]]:
+def safe_stream_operation(stream: Iterator[Any], *, auto_close: bool = True) -> Iterator[Iterator[Any]]:
     """
     Context manager for safe stream operations.
-    
+
     Args:
         stream: Iterator to manage
         auto_close: Whether to automatically close the stream
-        
+
     Yields:
         Stream iterator
-        
+
     Raises:
         SplurgeResourceReleaseError: If stream cannot be closed
     """

splurge_dsv/string_tokenizer.py

@@ -11,6 +11,7 @@ Please preserve this header and all related material when sharing!
 This module is licensed under the MIT License.
 """
 
+# Local imports
 from splurge_dsv.exceptions import SplurgeParameterError
 
 
@@ -27,12 +28,7 @@ class StringTokenizer:
     DEFAULT_STRIP = True
 
     @staticmethod
-    def parse(
-        content: str | None,
-        *,
-        delimiter: str,        
-        strip: bool = DEFAULT_STRIP
-    ) -> list[str]:
+    def parse(content: str | None, *, delimiter: str, strip: bool = DEFAULT_STRIP) -> list[str]:
         """
         Split a string into tokens based on a delimiter.
 
@@ -68,13 +64,7 @@ class StringTokenizer:
         return result
 
     @classmethod
-    def parses(
-        cls,
-        content: list[str],
-        *,
-        delimiter: str,
-        strip: bool = DEFAULT_STRIP
-    ) -> list[list[str]]:
+    def parses(cls, content: list[str], *, delimiter: str, strip: bool = DEFAULT_STRIP) -> list[list[str]]:
         """
         Process multiple strings into lists of tokens.
 
@@ -99,12 +89,7 @@ class StringTokenizer:
         return [cls.parse(text, delimiter=delimiter, strip=strip) for text in content]
 
     @staticmethod
-    def remove_bookends(
-        content: str,
-        *,
-        bookend: str,
-        strip: bool = DEFAULT_STRIP
-    ) -> str:
+    def remove_bookends(content: str, *, bookend: str, strip: bool = DEFAULT_STRIP) -> str:
         """
         Remove matching characters from both ends of a string.
 
@@ -127,10 +112,6 @@ class StringTokenizer:
             raise SplurgeParameterError("bookend cannot be empty or None")
 
         value: str = content.strip() if strip else content
-        if (
-            value.startswith(bookend)
-            and value.endswith(bookend)
-            and len(value) > 2 * len(bookend) - 1
-        ):
+        if value.startswith(bookend) and value.endswith(bookend) and len(value) > 2 * len(bookend) - 1:
             return value[len(bookend) : -len(bookend)]
         return value