MAINT: Standardize deprecation calls and removed_in format (#1817)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: romanlutz

pyrit/datasets/seed_datasets/seed_dataset_provider.py

@@ -4,13 +4,13 @@
 import asyncio
 import inspect
 import logging
-import warnings
 from abc import ABC, abstractmethod
 from dataclasses import fields as dc_fields
 from typing import Any, Optional
 
 from tqdm import tqdm
 
+from pyrit.common.deprecation import print_deprecation_message
 from pyrit.datasets.seed_datasets.seed_metadata import SeedDatasetFilter, SeedDatasetLoadTime, SeedDatasetMetadata
 from pyrit.models.seeds import SeedDataset
 
@@ -50,12 +50,10 @@ def __init_subclass__(cls, **kwargs: Any) -> None:
             cls.fetch_dataset is not SeedDatasetProvider.fetch_dataset
             and cls.fetch_dataset_async is SeedDatasetProvider.fetch_dataset_async
         ):
-            warnings.warn(
-                f"{cls.__name__} overrides the deprecated fetch_dataset method. "
-                "Rename the override to fetch_dataset_async; fetch_dataset will be "
-                "removed in v0.16.0.",
-                DeprecationWarning,
-                stacklevel=2,
+            print_deprecation_message(
+                old_item=f"{cls.__name__}.fetch_dataset",
+                new_item=f"{cls.__name__}.fetch_dataset_async",
+                removed_in="0.16.0",
             )
         if not inspect.isabstract(cls) and getattr(cls, "should_register", True):
             SeedDatasetProvider._registry[cls.__name__] = cls
@@ -95,11 +93,10 @@ async def fetch_dataset_async(self, *, cache: bool = True) -> SeedDataset:
         cls = type(self)
         if cls.fetch_dataset is SeedDatasetProvider.fetch_dataset:
             raise NotImplementedError(f"{cls.__name__} must implement fetch_dataset_async.")
-        warnings.warn(
-            f"{cls.__name__}.fetch_dataset is deprecated and will be removed in v0.16.0; "
-            "rename the override to fetch_dataset_async.",
-            DeprecationWarning,
-            stacklevel=2,
+        print_deprecation_message(
+            old_item=f"{cls.__name__}.fetch_dataset",
+            new_item=f"{cls.__name__}.fetch_dataset_async",
+            removed_in="0.16.0",
         )
         return await self.fetch_dataset(cache=cache)
 
@@ -116,11 +113,10 @@ async def fetch_dataset(self, *, cache: bool = True) -> SeedDataset:
         Returns:
             SeedDataset: The fetched dataset with prompts.
         """
-        warnings.warn(
-            "SeedDatasetProvider.fetch_dataset is deprecated and will be removed in v0.16.0; "
-            "use fetch_dataset_async instead.",
-            DeprecationWarning,
-            stacklevel=2,
+        print_deprecation_message(
+            old_item="SeedDatasetProvider.fetch_dataset",
+            new_item="SeedDatasetProvider.fetch_dataset_async",
+            removed_in="0.16.0",
         )
         return await self.fetch_dataset_async(cache=cache)
 

pyrit/output/attack_result/markdown.py

@@ -132,7 +132,7 @@ async def print_result_async(
         include_adversarial_conversation: bool = False,
     ) -> None:
         """Use ``write_async`` instead. This method is deprecated."""
-        print_deprecation_message(old_item="print_result_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_result_async", new_item="write_async", removed_in="0.16.0")
         await self.write_async(
             result,
             include_auxiliary_scores=include_auxiliary_scores,
@@ -142,13 +142,13 @@ async def print_result_async(
 
     async def output_conversation_async(self, result: AttackResult, *, include_scores: bool = False) -> None:
         """Use ``write_async`` instead. This method is deprecated."""
-        print_deprecation_message(old_item="output_conversation_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="output_conversation_async", new_item="write_async", removed_in="0.16.0")
         lines = await self._get_conversation_markdown_async(result=result, include_scores=include_scores)
         await self._write_async("\n".join(lines))
 
     async def print_summary_async(self, result: AttackResult) -> None:
         """Use ``write_async`` instead. This method is deprecated."""
-        print_deprecation_message(old_item="print_summary_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_summary_async", new_item="write_async", removed_in="0.16.0")
         markdown_lines = await self._get_summary_markdown_async(result)
         await self._write_async("\n".join(markdown_lines))
 

pyrit/output/attack_result/pretty.py

@@ -129,7 +129,7 @@ async def print_result_async(
         include_adversarial_conversation: bool = False,
     ) -> None:
         """Use ``write_async`` instead. This method is deprecated."""
-        print_deprecation_message(old_item="print_result_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_result_async", new_item="write_async", removed_in="0.16.0")
         await self.write_async(
             result,
             include_auxiliary_scores=include_auxiliary_scores,
@@ -171,7 +171,7 @@ async def print_conversation_async(
         self, result: AttackResult, *, include_scores: bool = False, include_reasoning_trace: bool = False
     ) -> None:
         """Use ``write_async`` instead. This method is deprecated."""
-        print_deprecation_message(old_item="print_conversation_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_conversation_async", new_item="write_async", removed_in="0.16.0")
         content = await self._render_conversation_async(
             result, include_scores=include_scores, include_reasoning_trace=include_reasoning_trace
         )
@@ -181,7 +181,7 @@ async def output_conversation_async(
         self, result: AttackResult, *, include_scores: bool = False, include_reasoning_trace: bool = False
     ) -> None:
         """Use ``write_async`` instead. This method is deprecated."""
-        print_deprecation_message(old_item="output_conversation_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="output_conversation_async", new_item="write_async", removed_in="0.16.0")
         content = await self._render_conversation_async(
             result, include_scores=include_scores, include_reasoning_trace=include_reasoning_trace
         )
@@ -195,7 +195,7 @@ async def print_messages_async(
         include_reasoning_trace: bool = False,
     ) -> None:
         """Use the conversation printer's ``write_async`` instead. This method is deprecated."""
-        print_deprecation_message(old_item="print_messages_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_messages_async", new_item="write_async", removed_in="0.16.0")
         content = await self._conversation_printer.render_async(
             messages, include_scores=include_scores, include_reasoning_trace=include_reasoning_trace
         )
@@ -256,7 +256,7 @@ async def _render_summary_async(self, result: AttackResult) -> str:
 
     async def print_summary_async(self, result: AttackResult) -> None:
         """Use ``write_async`` instead. This method is deprecated."""
-        print_deprecation_message(old_item="print_summary_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_summary_async", new_item="write_async", removed_in="0.16.0")
         content = await self._render_summary_async(result)
         await self._write_async(content)
 

pyrit/output/scenario_result/base.py

@@ -35,5 +35,5 @@ async def print_summary_async(self, result: ScenarioResult) -> None:
         Args:
             result (ScenarioResult): The scenario result to summarize.
         """
-        print_deprecation_message(old_item="print_summary_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_summary_async", new_item="write_async", removed_in="0.16.0")
         await self.write_async(result)

pyrit/output/scenario_result/pretty.py

@@ -251,7 +251,7 @@ async def print_summary_async(self, result: ScenarioResult) -> None:
         Args:
             result (ScenarioResult): The scenario result to summarize.
         """
-        print_deprecation_message(old_item="print_summary_async", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_summary_async", new_item="write_async", removed_in="0.16.0")
         await self.write_async(result)
 
 

pyrit/output/scorer/base.py

@@ -65,7 +65,7 @@ async def print_objective_scorer(self, *, scorer_identifier: ComponentIdentifier
         Args:
             scorer_identifier (ComponentIdentifier): The scorer identifier.
         """
-        print_deprecation_message(old_item="print_objective_scorer", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_objective_scorer", new_item="write_async", removed_in="0.16.0")
         await self.write_async(scorer_identifier=scorer_identifier)
 
     async def print_harm_scorer(self, *, scorer_identifier: ComponentIdentifier, harm_category: str) -> None:
@@ -76,5 +76,5 @@ async def print_harm_scorer(self, *, scorer_identifier: ComponentIdentifier, har
             scorer_identifier (ComponentIdentifier): The scorer identifier.
             harm_category (str): The harm category.
         """
-        print_deprecation_message(old_item="print_harm_scorer", new_item="write_async", removed_in="2.0")
+        print_deprecation_message(old_item="print_harm_scorer", new_item="write_async", removed_in="0.16.0")
         await self.write_async(scorer_identifier=scorer_identifier, harm_category=harm_category)

pyrit/prompt_converter/azure_speech_audio_to_text_converter.py

@@ -3,7 +3,6 @@
 
 import logging
 import time
-import warnings
 from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Any, Optional
 
@@ -12,6 +11,7 @@
 
 from pyrit.auth.azure_auth import get_speech_config, get_speech_config_async
 from pyrit.common import default_values
+from pyrit.common.deprecation import print_deprecation_message
 from pyrit.identifiers import ComponentIdentifier
 from pyrit.models import PromptDataType, data_serializer_factory
 from pyrit.prompt_converter.prompt_converter import ConverterResult, PromptConverter
@@ -66,8 +66,16 @@ def __init__(
                 If omitted, Entra ID auth via ``DefaultAzureCredential`` is used automatically.
             azure_speech_resource_id (str, Optional): The resource ID for accessing the service when using
                 Entra ID auth. Required when using a callable token provider or when no API key is available.
-            use_entra_auth (bool, Optional): **Deprecated.** Will be removed in v0.15.0.
-                Authentication is now auto-detected from the provided credentials.
+            use_entra_auth (bool, Optional): **Deprecated.** Will be removed in 0.15.0.
+                Authentication is now selected automatically based on what you pass to
+                ``azure_speech_key`` (and ``AZURE_SPEECH_KEY`` env var):
+
+                - Pass a **string** API key (or set ``AZURE_SPEECH_KEY``) to use API-key auth.
+                - Pass a **callable token provider** (sync or async returning a token string)
+                  to use Entra ID with a custom token; ``azure_speech_resource_id`` must also
+                  be set.
+                - Omit ``azure_speech_key`` entirely to use Entra ID via
+                  ``DefaultAzureCredential``; ``azure_speech_resource_id`` must be set.
             recognition_language (str): Recognition voice language. Defaults to "en-US".
                 For more on supported languages, see the following link:
                 https://learn.microsoft.com/en-us/azure/ai-services/speech-service/language-support
@@ -76,12 +84,13 @@ def __init__(
             ValueError: If the required environment variables or parameters are not set.
         """
         if use_entra_auth is not None:
-            warnings.warn(
-                "'use_entra_auth' is deprecated and will be removed in v0.15.0. "
-                "Authentication is now auto-detected: pass a key string for key auth, "
-                "a callable token provider for token auth, or omit for automatic Entra ID auth.",
-                DeprecationWarning,
-                stacklevel=2,
+            print_deprecation_message(
+                old_item="AzureSpeechAudioToTextConverter(use_entra_auth=...)",
+                new_item=(
+                    "AzureSpeechAudioToTextConverter("
+                    "azure_speech_key=<api-key-string-or-callable-token-provider-or-omit>)"
+                ),
+                removed_in="0.15.0",
             )
 
         self._azure_speech_region: str = default_values.get_required_value(
@@ -189,11 +198,10 @@ def recognize_audio(self, audio_bytes: bytes) -> str:
             ModuleNotFoundError: If the azure.cognitiveservices.speech module is not installed.
         """
         if self._token_provider:
-            warnings.warn(
-                "recognize_audio() does not support callable token providers. "
-                "Use convert_async() instead, which correctly resolves token providers.",
-                DeprecationWarning,
-                stacklevel=2,
+            print_deprecation_message(
+                old_item="AzureSpeechAudioToTextConverter.recognize_audio",
+                new_item="AzureSpeechAudioToTextConverter.convert_async",
+                removed_in="0.15.0",
             )
         speech_config = get_speech_config(
             resource_id=self._azure_speech_resource_id,

pyrit/prompt_converter/azure_speech_text_to_audio_converter.py

@@ -2,7 +2,6 @@
 # Licensed under the MIT license.
 
 import logging
-import warnings
 from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Literal, Optional
 
@@ -11,6 +10,7 @@
 
 from pyrit.auth.azure_auth import get_speech_config_async
 from pyrit.common import default_values
+from pyrit.common.deprecation import print_deprecation_message
 from pyrit.identifiers import ComponentIdentifier
 from pyrit.models import PromptDataType, data_serializer_factory
 from pyrit.prompt_converter.prompt_converter import ConverterResult, PromptConverter
@@ -70,8 +70,16 @@ def __init__(
                 If omitted, Entra ID auth via ``DefaultAzureCredential`` is used automatically.
             azure_speech_resource_id (str, Optional): The resource ID for accessing the service when using
                 Entra ID auth. Required when using a callable token provider or when no API key is available.
-            use_entra_auth (bool, Optional): **Deprecated.** Will be removed in v0.15.0.
-                Authentication is now auto-detected from the provided credentials.
+            use_entra_auth (bool, Optional): **Deprecated.** Will be removed in 0.15.0.
+                Authentication is now selected automatically based on what you pass to
+                ``azure_speech_key`` (and ``AZURE_SPEECH_KEY`` env var):
+
+                - Pass a **string** API key (or set ``AZURE_SPEECH_KEY``) to use API-key auth.
+                - Pass a **callable token provider** (sync or async returning a token string)
+                  to use Entra ID with a custom token; ``azure_speech_resource_id`` must also
+                  be set.
+                - Omit ``azure_speech_key`` entirely to use Entra ID via
+                  ``DefaultAzureCredential``; ``azure_speech_resource_id`` must be set.
             synthesis_language (str): Synthesis voice language.
             synthesis_voice_name (str): Synthesis voice name.
                 For more details see the following link for synthesis language and synthesis voice:
@@ -82,12 +90,13 @@ def __init__(
             ValueError: If the required environment variables or parameters are not set.
         """
         if use_entra_auth is not None:
-            warnings.warn(
-                "'use_entra_auth' is deprecated and will be removed in v0.15.0. "
-                "Authentication is now auto-detected: pass a key string for key auth, "
-                "a callable token provider for token auth, or omit for automatic Entra ID auth.",
-                DeprecationWarning,
-                stacklevel=2,
+            print_deprecation_message(
+                old_item="AzureSpeechTextToAudioConverter(use_entra_auth=...)",
+                new_item=(
+                    "AzureSpeechTextToAudioConverter("
+                    "azure_speech_key=<api-key-string-or-callable-token-provider-or-omit>)"
+                ),
+                removed_in="0.15.0",
             )
 
         self._azure_speech_region: str = default_values.get_required_value(

pyrit/prompt_converter/persuasion_converter.py

@@ -4,9 +4,9 @@
 import json
 import logging
 import pathlib
-import warnings
 
 from pyrit.common.apply_defaults import REQUIRED_VALUE, apply_defaults
+from pyrit.common.deprecation import print_deprecation_message
 from pyrit.common.path import CONVERTER_SEED_PROMPT_PATH
 from pyrit.exceptions import (
     InvalidJsonException,
@@ -129,10 +129,9 @@ async def send_persuasion_prompt_async(self, request: Message) -> str:
         Returns:
             str: The post-processed response text.
         """
-        warnings.warn(
-            "send_persuasion_prompt_async is deprecated; the converter now uses the unified "
-            "_send_with_retries_async helper from LLMGenericTextConverter.",
-            DeprecationWarning,
-            stacklevel=2,
+        print_deprecation_message(
+            old_item="PersuasionConverter.send_persuasion_prompt_async",
+            new_item="PersuasionConverter._send_with_retries_async (inherited from LLMGenericTextConverter)",
+            removed_in="0.16.0",
         )
         return await self._send_with_retries_async(request)

pyrit/prompt_converter/variation_converter.py

@@ -4,9 +4,9 @@
 import json
 import logging
 import pathlib
-import warnings
 
 from pyrit.common.apply_defaults import REQUIRED_VALUE, apply_defaults
+from pyrit.common.deprecation import print_deprecation_message
 from pyrit.common.path import CONVERTER_SEED_PROMPT_PATH
 from pyrit.exceptions import (
     InvalidJsonException,
@@ -113,10 +113,9 @@ async def send_variation_prompt_async(self, request: Message) -> str:
         Returns:
             str: The post-processed response text.
         """
-        warnings.warn(
-            "send_variation_prompt_async is deprecated; the converter now uses the unified "
-            "_send_with_retries_async helper from LLMGenericTextConverter.",
-            DeprecationWarning,
-            stacklevel=2,
+        print_deprecation_message(
+            old_item="VariationConverter.send_variation_prompt_async",
+            new_item="VariationConverter._send_with_retries_async (inherited from LLMGenericTextConverter)",
+            removed_in="0.16.0",
         )
         return await self._send_with_retries_async(request)