MAINT: fix docstrings for /common and /datasets (microsoft#1193)

Author: paulinek13

pyproject.toml

@@ -251,7 +251,7 @@ extend-select = [
 # Temporary ignores for pyrit/ subdirectories until issue #1176
 # https://github.com/Azure/PyRIT/issues/1176 is fully resolved
 # TODO: Remove these ignores once the issues are fixed
-"pyrit/{analytics,auth,auxiliary_attacks,chat_message_normalizer,cli,common,datasets,embedding,exceptions,executor,memory,models,prompt_converter,prompt_normalizer,prompt_target,scenarios,score,setup,ui}/**/*.py" = ["D101", "D102", "D103", "D104", "D105", "D106", "D107", "D401", "D404", "D417", "D418", "DOC102", "DOC201", "DOC202", "DOC402", "DOC501"]
+"pyrit/{analytics,auth,auxiliary_attacks,chat_message_normalizer,cli,embedding,exceptions,executor,memory,models,prompt_converter,prompt_normalizer,prompt_target,scenarios,score,setup,ui}/**/*.py" = ["D101", "D102", "D103", "D104", "D105", "D106", "D107", "D401", "D404", "D417", "D418", "DOC102", "DOC201", "DOC202", "DOC402", "DOC501"]
 "pyrit/__init__.py" = ["D104"]
 
 [tool.ruff.lint.pydocstyle]

pyrit/common/__init__.py

@@ -1,7 +1,7 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT license.
 
-"""This module contains common utilities for PyRIT."""
+"""Common utilities and helpers for PyRIT."""
 
 from pyrit.common.apply_defaults import (
     apply_defaults,

pyrit/common/apply_defaults.py

@@ -62,6 +62,12 @@ class DefaultValueScope:
     include_subclasses: bool = True
 
     def __hash__(self) -> int:
+        """
+        Return a hash based on class type, parameter name, and subclass inclusion flag.
+
+        Returns:
+            int: Hash value for this scope.
+        """
         return hash((self.class_type, self.parameter_name, self.include_subclasses))
 
 
@@ -74,6 +80,7 @@ class GlobalDefaultValues:
     """
 
     def __init__(self) -> None:
+        """Initialize the global default values registry."""
         self._default_values: Dict[DefaultValueScope, Any] = {}
 
     def set_default_value(
@@ -153,7 +160,12 @@ def all_defaults(self) -> Dict[DefaultValueScope, Any]:
 
 
 def get_global_default_values() -> GlobalDefaultValues:
-    """Get the global default values registry."""
+    """
+    Get the global default values registry.
+
+    Returns:
+        GlobalDefaultValues: The global default values registry instance.
+    """
     return _global_default_values
 
 
@@ -221,7 +233,7 @@ def set_global_variable(*, name: str, value: Any) -> None:
 
 def apply_defaults_to_method(method):
     """
-    Decorator that applies default values to a method's parameters.
+    Apply default values to a method's parameters.
 
     This decorator looks up default values for the method's class and applies them
     to parameters that are None or not provided.
@@ -283,7 +295,7 @@ def wrapper(self, *args, **kwargs):
 
 def apply_defaults(method):
     """
-    Decorator that applies default values to a class constructor.
+    Apply default values to a class constructor.
 
     This is an alias for apply_defaults_to_method for backward compatibility.
 

pyrit/common/csv_helper.py

@@ -6,11 +6,24 @@
 
 
 def read_csv(file) -> List[Dict[str, str]]:
+    """
+    Read a CSV file and return its rows as dictionaries.
+
+    Returns:
+        List[Dict[str, str]]: Parsed CSV rows as dictionaries.
+    """
     reader = csv.DictReader(file)
     return [row for row in reader]
 
 
 def write_csv(file, examples: List[Dict[str, str]]):
+    """
+    Write a list of dictionaries to a CSV file.
+
+    Args:
+        file: A file-like object opened for writing CSV data.
+        examples (List[Dict[str, str]]): List of dictionaries to write as CSV rows.
+    """
     writer = csv.DictWriter(file, fieldnames=examples[0].keys())
     writer.writeheader()
     writer.writerows(examples)

pyrit/common/data_url_converter.py

@@ -10,7 +10,7 @@
 
 async def convert_local_image_to_data_url(image_path: str) -> str:
     """
-    Converts a local image file to a data URL encoded in base64.
+    Convert a local image file to a data URL encoded in base64.
 
     Args:
         image_path (str): The file system path to the image file.

pyrit/common/default_values.py

@@ -10,7 +10,7 @@
 
 def get_required_value(*, env_var_name: str, passed_value: str) -> str:
     """
-    Gets a required value from an environment variable or a passed value,
+    Get a required value from an environment variable or a passed value,
     preferring the passed value.
 
     If no value is found, raises a KeyError
@@ -37,7 +37,7 @@ def get_required_value(*, env_var_name: str, passed_value: str) -> str:
 
 def get_non_required_value(*, env_var_name: str, passed_value: Optional[str] = None) -> str:
     """
-    Gets a non-required value from an environment variable or a passed value,
+    Get a non-required value from an environment variable or a passed value,
     preferring the passed value.
 
     Args:

pyrit/common/display_response.py

@@ -14,7 +14,7 @@
 
 async def display_image_response(response_piece: MessagePiece) -> None:
     """
-    Displays response images if running in notebook environment.
+    Display response images if running in notebook environment.
 
     Args:
         response_piece (MessagePiece): The response piece to display.

pyrit/common/download_hf_model.py

@@ -13,7 +13,15 @@
 
 
 def get_available_files(model_id: str, token: str):
-    """Fetches available files for a model from the Hugging Face repository."""
+    """
+    Fetch available files for a model from the Hugging Face repository.
+
+    Returns:
+        List of available file names.
+
+    Raises:
+        ValueError: If no files are found for the model.
+    """
     api = HfApi()
     try:
         model_info = api.model_info(model_id, token=token)
@@ -31,11 +39,8 @@ def get_available_files(model_id: str, token: str):
 
 async def download_specific_files(model_id: str, file_patterns: list, token: str, cache_dir: Path):
     """
-    Downloads specific files from a Hugging Face model repository.
+    Download specific files from a Hugging Face model repository.
     If file_patterns is None, downloads all files.
-
-    Returns:
-        List of URLs for the downloaded files.
     """
     os.makedirs(cache_dir, exist_ok=True)
 
@@ -60,7 +65,12 @@ async def download_specific_files(model_id: str, file_patterns: list, token: str
 
 
 async def download_chunk(url, headers, start, end, client):
-    """Download a chunk of the file with a specified byte range."""
+    """
+    Download a chunk of the file with a specified byte range.
+
+    Returns:
+        The content of the downloaded chunk.
+    """
     range_header = {"Range": f"bytes={start}-{end}", **headers}
     response = await client.get(url, headers=range_header)
     response.raise_for_status()

pyrit/common/json_helper.py

@@ -6,17 +6,43 @@
 
 
 def read_json(file) -> List[Dict[str, str]]:
+    """
+    Read a JSON file and return its content.
+
+    Returns:
+        List[Dict[str, str]]: Parsed JSON content.
+    """
     return json.load(file)
 
 
 def write_json(file, examples: List[Dict[str, str]]):
+    """
+    Write a list of dictionaries to a JSON file.
+
+    Args:
+        file: A file-like object opened for writing JSON data.
+        examples (List[Dict[str, str]]): List of dictionaries to write as JSON.
+    """
     json.dump(examples, file)
 
 
 def read_jsonl(file) -> List[Dict[str, str]]:
+    """
+    Read a JSONL file and return its content.
+
+    Returns:
+        List[Dict[str, str]]: Parsed JSONL content.
+    """
     return [json.loads(line) for line in file]
 
 
 def write_jsonl(file, examples: List[Dict[str, str]]):
+    """
+    Write a list of dictionaries to a JSONL file.
+
+    Args:
+        file: A file-like object opened for writing JSONL data.
+        examples (List[Dict[str, str]]): List of dictionaries to write as JSONL.
+    """
     for example in examples:
         file.write(json.dumps(example) + "\n")

pyrit/common/net_utility.py

@@ -9,7 +9,12 @@
 
 
 def get_httpx_client(use_async: bool = False, debug: bool = False, **httpx_client_kwargs: Optional[Any]):
-    """Get the httpx client for making requests."""
+    """
+    Get the httpx client for making requests.
+
+    Returns:
+        httpx.Client or httpx.AsyncClient: The configured httpx client.
+    """
     client_class = httpx.AsyncClient if use_async else httpx.Client
     proxy = "http://localhost:8080" if debug else None
 
@@ -82,6 +87,9 @@ async def make_request_and_raise_if_error_async(
     1. In the endpoint_uri (e.g., "https://api.com/endpoint?api-version=2024-10-21")
     2. Via the extra_url_parameters dict
     3. Both (extra_url_parameters will be merged with URL query parameters, with extra_url_parameters taking precedence)
+
+    Returns:
+        httpx.Response: The response from the request.
     """
     headers = headers or {}
     request_body = request_body or {}