MAINT: fix docstrings for /prompt_converter (microsoft#1314)

Author: paulinek13

pyproject.toml

@@ -279,7 +279,7 @@ notice-rgx = "Copyright \\(c\\) Microsoft Corporation\\.\\s*\\n.*Licensed under
 # 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/{auxiliary_attacks,exceptions,models,prompt_converter,ui}/**/*.py" = ["D101", "D102", "D103", "D104", "D105", "D106", "D107", "D401", "D404", "D417", "D418", "DOC102", "DOC201", "DOC202", "DOC402", "DOC501"]
+"pyrit/{auxiliary_attacks,exceptions,models,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/prompt_converter/__init__.py

@@ -1,6 +1,16 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT license.
 
+"""
+Prompt converters for transforming prompts before sending them to targets in red teaming workflows.
+
+Converters are organized into categories: Text-to-Text (encoding, obfuscation, translation, variation),
+Audio (text-to-audio, audio-to-text, audio-to-audio), Image (text-to-image, image-to-image),
+Video (image-to-video), File (text-to-PDF/URL), Selective Converting (partial prompt transformation),
+and Human-in-the-Loop (interactive review). Converters can be stacked together to create complex
+transformation pipelines for testing AI system robustness.
+"""
+
 from pyrit.prompt_converter.add_image_text_converter import AddImageTextConverter
 from pyrit.prompt_converter.add_image_to_video_converter import AddImageVideoConverter
 from pyrit.prompt_converter.add_text_image_converter import AddTextImageConverter

pyrit/prompt_converter/add_image_text_converter.py

@@ -38,7 +38,7 @@ def __init__(
         y_pos: int = 10,
     ):
         """
-        Initializes the converter with the image file path and text properties.
+        Initialize the converter with the image file path and text properties.
 
         Args:
             img_to_add (str): File path of image to add text to.
@@ -65,7 +65,7 @@ def __init__(
 
     def _load_font(self) -> FreeTypeFont:
         """
-        Loads the font for a given font name and font size.
+        Load the font for a given font name and font size.
 
         Returns:
             ImageFont.FreeTypeFont or ImageFont.ImageFont: The loaded font object. If the specified font
@@ -84,13 +84,16 @@ def _load_font(self) -> FreeTypeFont:
 
     def _add_text_to_image(self, text: str) -> Image.Image:
         """
-        Adds wrapped text to the image at `self._img_to_add`.
+        Add wrapped text to the image at `self._img_to_add`.
 
         Args:
             text (str): The text to add to the image.
 
         Returns:
             Image.Image: The image with added text.
+
+        Raises:
+            ValueError: If ``text`` is empty.
         """
         if not text:
             raise ValueError("Please provide valid text value")
@@ -123,7 +126,7 @@ def _add_text_to_image(self, text: str) -> Image.Image:
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
         """
-        Converts the given prompt by adding it as text to the image.
+        Convert the given prompt by adding it as text to the image.
 
         Args:
             prompt (str): The text to be added to the image.

pyrit/prompt_converter/add_image_to_video_converter.py

@@ -42,7 +42,7 @@ def __init__(
         img_resize_size: tuple[int, int] = (500, 500),
     ):
         """
-        Initializes the converter with the video path and image properties.
+        Initialize the converter with the video path and image properties.
 
         Args:
             video_path (str): File path of video to add image to.
@@ -63,14 +63,18 @@ def __init__(
 
     async def _add_image_to_video(self, image_path: str, output_path: str) -> str:
         """
-        Adds an image to video.
+        Add an image to video.
 
         Args:
             image_path (str): The image path to add to video.
             output_path (str): The output video path.
 
         Returns:
             str: The output video path.
+
+        Raises:
+            ModuleNotFoundError: If OpenCV is not installed.
+            ValueError: If the image path is invalid or unsupported video format.
         """
         try:
             import cv2  # noqa: F401
@@ -167,7 +171,7 @@ async def _add_image_to_video(self, image_path: str, output_path: str) -> str:
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "image_path") -> ConverterResult:
         """
-        Converts the given prompt (image) by adding it to a video.
+        Convert the given prompt (image) by adding it to a video.
 
         Args:
             prompt (str): The image path to be added to the video.

pyrit/prompt_converter/add_text_image_converter.py

@@ -38,7 +38,7 @@ def __init__(
         y_pos: int = 10,
     ):
         """
-        Initializes the converter with the text and text properties.
+        Initialize the converter with the text and text properties.
 
         Args:
             text_to_add (str): Text to add to an image. Defaults to empty string.
@@ -65,7 +65,7 @@ def __init__(
 
     def _load_font(self) -> FreeTypeFont:
         """
-        Loads the font for a given font name and font size.
+        Load the font for a given font name and font size.
 
         Returns:
             ImageFont.FreeTypeFont or ImageFont.ImageFont: The loaded font object. If the specified font
@@ -84,7 +84,7 @@ def _load_font(self) -> FreeTypeFont:
 
     def _add_text_to_image(self, image: Image.Image) -> Image.Image:
         """
-        Adds wrapped text to the image.
+        Add wrapped text to the image.
 
         Args:
             image (Image.Image): The image to which text will be added.
@@ -119,7 +119,7 @@ def _add_text_to_image(self, image: Image.Image) -> Image.Image:
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "image_path") -> ConverterResult:
         """
-        Converts the given prompt (image) by adding text to it.
+        Convert the given prompt (image) by adding text to it.
 
         Args:
             prompt (str): The image file path to which text will be added.

pyrit/prompt_converter/ansi_escape/ansi_attack_converter.py

@@ -41,7 +41,7 @@ def __init__(
         incorporate_user_prompt: bool = True,
     ):
         """
-        Initializes the converter with various options to control the scenarios generated.
+        Initialize the converter with various options to control the scenarios generated.
 
         Args:
             include_raw (bool): Include scenarios with raw ANSI codes.
@@ -59,13 +59,43 @@ def __init__(
         self.incorporate_user_prompt = incorporate_user_prompt
 
     def input_supported(self, input_type: PromptDataType) -> bool:
+        """
+        Check if the input type is supported.
+
+        Args:
+            input_type (PromptDataType): The type of input data.
+
+        Returns:
+            bool: True if the input type is supported, False otherwise.
+        """
         return input_type == "text"
 
     def output_supported(self, output_type: PromptDataType) -> bool:
+        """
+        Check if the output type is supported.
+
+        Args:
+            output_type (PromptDataType): The type of output data.
+
+        Returns:
+            bool: True if the output type is supported, False otherwise.
+        """
         return output_type == "text"
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
-        """Converts the given prompt into an ANSI attack scenario."""
+        """
+        Convert the given prompt into an ANSI attack scenario.
+
+        Args:
+            prompt (str): The original user prompt.
+            input_type (PromptDataType): The type of input data.
+
+        Returns:
+            ConverterResult: The result containing the generated ANSI scenario prompt.
+
+        Raises:
+            ValueError: If the input type is not supported.
+        """
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")
 

pyrit/prompt_converter/ascii_art_converter.py

@@ -17,15 +17,27 @@ class AsciiArtConverter(PromptConverter):
 
     def __init__(self, font: str = "rand") -> None:
         """
-        Initializes the converter with a specified font.
+        Initialize the converter with a specified font.
 
         Args:
             font (str): The font to use for ASCII art. Defaults to "rand" which selects a random font.
         """
         self.font_value = font
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
-        """Converts the given prompt into ASCII art."""
+        """
+        Convert the given prompt into ASCII art.
+
+        Args:
+            prompt (str): The prompt to be converted.
+            input_type (PromptDataType): The type of input data.
+
+        Returns:
+            ConverterResult: The result containing the ASCII art representation of the prompt.
+
+        Raises:
+            ValueError: If the input type is not supported.
+        """
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")
 

pyrit/prompt_converter/ask_to_decode_converter.py

@@ -41,7 +41,7 @@ class AskToDecodeConverter(PromptConverter):
 
     def __init__(self, template: Optional[str] = None, encoding_name: str = "cipher") -> None:
         """
-        Initializes the converter with a specified encoding name and template.
+        Initialize the converter with a specified encoding name and template.
 
         By default, if no template is provided, a random template from basic_templates
         will be used. If an encoding_name is provided, both basic_templates and
@@ -60,14 +60,14 @@ def __init__(self, template: Optional[str] = None, encoding_name: str = "cipher"
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
         """
-        Converts the given encoded text by wrapping it with a decoding request prompt.
+        Convert the given encoded text by wrapping it with a decoding request prompt.
 
         Args:
             prompt (str): The encoded text to be wrapped with a decoding request.
             input_type (PromptDataType, optional): Type of input data. Defaults to "text".
 
         Returns:
-            ConverterResult: The encoded text wrapped in a decoding prompt.
+            ConverterResult: The result containing the converted prompt.
 
         Raises:
             ValueError: If the input type is not supported (only "text" is supported).

pyrit/prompt_converter/atbash_converter.py

@@ -25,7 +25,7 @@ class AtbashConverter(PromptConverter):
 
     def __init__(self, *, append_description: bool = False) -> None:
         """
-        Initializes the converter with an option to append a description.
+        Initialize the converter with an option to append a description.
 
         Args:
             append_description (bool): If True, appends plaintext "expert" text to the prompt.
@@ -40,7 +40,19 @@ def __init__(self, *, append_description: bool = False) -> None:
         )
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "text") -> ConverterResult:
-        """Converts the given prompt using the Atbash cipher."""
+        """
+        Convert the given prompt using the Atbash cipher.
+
+        Args:
+            prompt (str): The prompt to be converted.
+            input_type (PromptDataType): The type of input data.
+
+        Returns:
+            ConverterResult: The result containing the encoded prompt.
+
+        Raises:
+            ValueError: If the input type is not supported.
+        """
         if not self.input_supported(input_type):
             raise ValueError("Input type not supported")
 

pyrit/prompt_converter/audio_frequency_converter.py

@@ -33,7 +33,7 @@ def __init__(
         shift_value: int = 20000,
     ) -> None:
         """
-        Initializes the converter with the specified output format and shift value.
+        Initialize the converter with the specified output format and shift value.
 
         Args:
             output_format (str): The format of the audio file, defaults to "wav".
@@ -44,7 +44,7 @@ def __init__(
 
     async def convert_async(self, *, prompt: str, input_type: PromptDataType = "audio_path") -> ConverterResult:
         """
-        Converts the given audio file by shifting its frequency.
+        Convert the given audio file by shifting its frequency.
 
         Args:
             prompt (str): File path to the audio file to be converted.