Ruff format

Author: haochengxia

examples/basic_usage.py

@@ -3,14 +3,14 @@
 # Step 1: Open a trace hosted on S3 (find more via https://github.com/cacheMon/cache_dataset)
 URI = "s3://cache-datasets/cache_dataset_oracleGeneral/2007_msr/msr_hm_0.oracleGeneral.zst"
 reader = lcs.TraceReader(
-    trace = URI,
-    trace_type = lcs.TraceType.ORACLE_GENERAL_TRACE,
-    reader_init_params = lcs.ReaderInitParam(ignore_obj_size=False)
+    trace=URI,
+    trace_type=lcs.TraceType.ORACLE_GENERAL_TRACE,
+    reader_init_params=lcs.ReaderInitParam(ignore_obj_size=False),
 )
 
 # Step 2: Initialize cache
 cache = lcs.S3FIFO(
-    cache_size=1024*1024,
+    cache_size=1024 * 1024,
     # Cache specific parameters
     small_size_ratio=0.2,
     ghost_size_ratio=0.8,
@@ -22,9 +22,5 @@
 print(f"Request miss ratio: {req_miss_ratio:.4f}, Byte miss ratio: {byte_miss_ratio:.4f}")
 
 # Step 3.1: Further process the first 1000 requests again
-req_miss_ratio, byte_miss_ratio = cache.process_trace(
-    reader,
-    start_req=0,
-    max_req=1000
-)
-print(f"Request miss ratio: {req_miss_ratio:.4f}, Byte miss ratio: {byte_miss_ratio:.4f}")
+req_miss_ratio, byte_miss_ratio = cache.process_trace(reader, start_req=0, max_req=1000)
+print(f"Request miss ratio: {req_miss_ratio:.4f}, Byte miss ratio: {byte_miss_ratio:.4f}")

libcachesim/_s3_cache.py

@@ -16,17 +16,36 @@
 
 class _DataLoader:
     """Internal S3 data loader with local caching."""
-    
+
     DEFAULT_BUCKET = "cache-datasets"
     DEFAULT_CACHE_DIR = Path(os.environ.get("LCS_HUB_CACHE", Path.home() / ".cache/libcachesim/hub"))
 
     # Characters that are problematic on various filesystems
     INVALID_CHARS = set('<>:"|?*\x00')
     # Reserved names on Windows
     RESERVED_NAMES = {
-        'CON', 'PRN', 'AUX', 'NUL',
-        'COM1', 'COM2', 'COM3', 'COM4', 'COM5', 'COM6', 'COM7', 'COM8', 'COM9',
-        'LPT1', 'LPT2', 'LPT3', 'LPT4', 'LPT5', 'LPT6', 'LPT7', 'LPT8', 'LPT9'
+        "CON",
+        "PRN",
+        "AUX",
+        "NUL",
+        "COM1",
+        "COM2",
+        "COM3",
+        "COM4",
+        "COM5",
+        "COM6",
+        "COM7",
+        "COM8",
+        "COM9",
+        "LPT1",
+        "LPT2",
+        "LPT3",
+        "LPT4",
+        "LPT5",
+        "LPT6",
+        "LPT7",
+        "LPT8",
+        "LPT9",
     }
 
     def __init__(
@@ -42,65 +61,65 @@ def _validate_bucket_name(self, bucket_name: str) -> str:
         """Validate S3 bucket name according to AWS rules."""
         if not bucket_name:
             raise ValueError("Bucket name cannot be empty")
-        
+
         if len(bucket_name) < 3 or len(bucket_name) > 63:
             raise ValueError("Bucket name must be between 3 and 63 characters")
-        
-        if not re.match(r'^[a-z0-9.-]+$', bucket_name):
+
+        if not re.match(r"^[a-z0-9.-]+$", bucket_name):
             raise ValueError("Bucket name can only contain lowercase letters, numbers, periods, and hyphens")
-        
-        if bucket_name.startswith('.') or bucket_name.endswith('.'):
+
+        if bucket_name.startswith(".") or bucket_name.endswith("."):
             raise ValueError("Bucket name cannot start or end with a period")
-        
-        if bucket_name.startswith('-') or bucket_name.endswith('-'):
+
+        if bucket_name.startswith("-") or bucket_name.endswith("-"):
             raise ValueError("Bucket name cannot start or end with a hyphen")
-        
-        if '..' in bucket_name:
+
+        if ".." in bucket_name:
             raise ValueError("Bucket name cannot contain consecutive periods")
-        
+
         return bucket_name
 
     def _validate_and_sanitize_key(self, key: str) -> str:
         """Validate and sanitize S3 key for safe local filesystem usage."""
         if not key:
             raise ValueError("S3 key cannot be empty")
-        
+
         if len(key) > 1024:  # S3 limit is 1024 bytes
             raise ValueError("S3 key is too long (max 1024 characters)")
-        
+
         # Check for path traversal attempts
-        if '..' in key:
+        if ".." in key:
             raise ValueError("S3 key cannot contain '..' (path traversal not allowed)")
-        
-        if key.startswith('/'):
+
+        if key.startswith("/"):
             raise ValueError("S3 key cannot start with '/'")
-        
+
         # Split key into parts and validate each part
-        parts = key.split('/')
+        parts = key.split("/")
         sanitized_parts = []
-        
+
         for part in parts:
             if not part:  # Empty part (double slash)
                 continue
-                
+
             # Check for reserved names (case insensitive)
             if part.upper() in self.RESERVED_NAMES:
                 raise ValueError(f"S3 key contains reserved name: {part}")
-            
+
             # Check for invalid characters
             if any(c in self.INVALID_CHARS for c in part):
                 raise ValueError(f"S3 key contains invalid characters in part: {part}")
-            
+
             # Check if part is too long for filesystem
             if len(part) > 255:  # Most filesystems have 255 char limit per component
                 raise ValueError(f"S3 key component too long: {part}")
-            
+
             sanitized_parts.append(part)
-        
+
         if not sanitized_parts:
             raise ValueError("S3 key resulted in empty path after sanitization")
-        
-        return '/'.join(sanitized_parts)
+
+        return "/".join(sanitized_parts)
 
     def _ensure_cache_dir(self) -> None:
         (self.cache_dir / self.bucket_name).mkdir(parents=True, exist_ok=True)
@@ -114,10 +133,11 @@ def _get_available_disk_space(self, path: Path) -> int:
             # Fallback for Windows or other systems
             try:
                 import shutil
+
                 return shutil.disk_usage(path).free
             except Exception:
                 logger.warning("Could not determine available disk space")
-                return float('inf')  # Assume unlimited space if we can't check
+                return float("inf")  # Assume unlimited space if we can't check
 
     @property
     def s3_client(self):
@@ -138,20 +158,20 @@ def _cache_path(self, key: str) -> Path:
         """Create cache path that mirrors S3 structure after validation."""
         sanitized_key = self._validate_and_sanitize_key(key)
         cache_path = self.cache_dir / self.bucket_name / sanitized_key
-        
+
         # Double-check that the resolved path is still within cache directory
         try:
             cache_path.resolve().relative_to(self.cache_dir.resolve())
         except ValueError:
             raise ValueError(f"S3 key resolves outside cache directory: {key}")
-        
+
         return cache_path
 
     def _get_object_size(self, key: str) -> int:
         """Get the size of an S3 object without downloading it."""
         try:
             response = self.s3_client.head_object(Bucket=self.bucket_name, Key=key)
-            return response['ContentLength']
+            return response["ContentLength"]
         except Exception as e:
             logger.warning(f"Could not determine object size for s3://{self.bucket_name}/{key}: {e}")
             return 0
@@ -254,10 +274,10 @@ def list_s3_objects(self, prefix: str = "", delimiter: str = "/") -> dict:
 def set_cache_dir(cache_dir: Union[str, Path]) -> None:
     """
     Set the global cache directory for S3 downloads.
-    
+
     Args:
         cache_dir: Path to the cache directory
-        
+
     Example:
         >>> import libcachesim as lcs
         >>> lcs.set_cache_dir("/tmp/my_cache")
@@ -269,10 +289,10 @@ def set_cache_dir(cache_dir: Union[str, Path]) -> None:
 def get_cache_dir() -> Path:
     """
     Get the current cache directory.
-    
+
     Returns:
         Path to the current cache directory
-        
+
     Example:
         >>> import libcachesim as lcs
         >>> print(lcs.get_cache_dir())
@@ -284,10 +304,10 @@ def get_cache_dir() -> Path:
 def clear_cache(s3_path: Optional[str] = None) -> None:
     """
     Clear cached files.
-    
+
     Args:
         s3_path: Specific S3 path to clear, or None to clear all cache
-        
+
     Example:
         >>> import libcachesim as lcs
         >>> # Clear specific file
@@ -298,7 +318,7 @@ def clear_cache(s3_path: Optional[str] = None) -> None:
     if s3_path and s3_path.startswith("s3://"):
         parsed = urlparse(s3_path)
         bucket = parsed.netloc
-        key = parsed.path.lstrip('/')
+        key = parsed.path.lstrip("/")
         if bucket == _data_loader.bucket_name:
             _data_loader.clear_cache(key)
         else:
@@ -310,10 +330,10 @@ def clear_cache(s3_path: Optional[str] = None) -> None:
 def get_cache_size() -> int:
     """
     Get total size of cached files in bytes.
-    
+
     Returns:
         Total cache size in bytes
-        
+
     Example:
         >>> import libcachesim as lcs
         >>> size_mb = lcs.get_cache_size() / (1024**2)
@@ -325,10 +345,10 @@ def get_cache_size() -> int:
 def list_cached_files() -> list[str]:
     """
     List all cached files.
-    
+
     Returns:
         List of cached file paths
-        
+
     Example:
         >>> import libcachesim as lcs
         >>> files = lcs.list_cached_files()
@@ -344,4 +364,4 @@ def get_data_loader(bucket_name: str = None) -> _DataLoader:
     if bucket_name is None or bucket_name == _data_loader.bucket_name:
         return _data_loader
     else:
-        return _DataLoader(bucket_name=bucket_name, cache_dir=_data_loader.cache_dir.parent)
+        return _DataLoader(bucket_name=bucket_name, cache_dir=_data_loader.cache_dir.parent)

libcachesim/trace_reader.py

@@ -46,65 +46,65 @@ def __init__(
     def _validate_s3_uri(self, s3_uri: str) -> tuple[str, str]:
         """
         Validate and parse S3 URI.
-        
+
         Args:
             s3_uri: S3 URI like "s3://bucket/key"
-            
+
         Returns:
             Tuple of (bucket, key)
-            
+
         Raises:
             ValueError: If URI is invalid
         """
         parsed = urlparse(s3_uri)
-        
+
         if parsed.scheme != "s3":
             raise ValueError(f"Invalid S3 URI scheme. Expected 's3', got '{parsed.scheme}': {s3_uri}")
-        
+
         if not parsed.netloc:
             raise ValueError(f"Missing bucket name in S3 URI: {s3_uri}")
-        
+
         bucket = parsed.netloc
-        key = parsed.path.lstrip('/')
-        
+        key = parsed.path.lstrip("/")
+
         if not key:
             raise ValueError(f"Missing key (object path) in S3 URI: {s3_uri}")
-        
+
         # Check for path traversal in the key part only
-        if '..' in key:
+        if ".." in key:
             raise ValueError(f"S3 key contains path traversal patterns: {key}")
-        
+
         # Check for double slashes in the key part (after s3://)
-        if '//' in key:
+        if "//" in key:
             raise ValueError(f"S3 key contains double slashes: {key}")
-        
+
         # Check for backslashes (not valid in URLs)
-        if '\\' in s3_uri:
+        if "\\" in s3_uri:
             raise ValueError(f"S3 URI contains backslashes: {s3_uri}")
-        
+
         return bucket, key
 
     def _resolve_s3_path(self, s3_path: str) -> str:
         """
         Resolve S3 path to local cached file path.
-        
+
         Args:
             s3_path: S3 URI like "s3://bucket/key"
-            
+
         Returns:
             Local file path
         """
         try:
             bucket, key = self._validate_s3_uri(s3_path)
         except ValueError as e:
             raise ValueError(f"Invalid S3 URI: {e}")
-        
+
         # Get data loader for this bucket
         try:
             loader = get_data_loader(bucket)
         except ValueError as e:
             raise ValueError(f"Invalid bucket name '{bucket}': {e}")
-        
+
         logger.info(f"Resolving S3 path: {s3_path}")
         try:
             return loader.get_cached_path(key)
@@ -296,4 +296,4 @@ def __getitem__(self, index: int) -> Request:
         self._reader.reset()
         self._reader.skip_n_req(index)
         req = Request()
-        return self._reader.read_one_req(req)
+        return self._reader.read_one_req(req)

tests/test_reader.py

@@ -330,7 +330,7 @@ def test_invalid_sampling_ratio(self):
 
         finally:
             os.unlink(temp_file)
-    
+
     def test_trace_reader_s3(self):
         """Test trace reader with S3"""
         URI = "s3://cache-datasets/cache_dataset_oracleGeneral/2007_msr/msr_hm_0.oracleGeneral.zst"