MAINT: introduce ruff-check for docstring quality enforcement (microsoft#1181)

Co-authored-by: Roman Lutz <romanlutz13@gmail.com>

Author: paulinek13

.pre-commit-config.yaml

@@ -49,6 +49,12 @@ repos:
       name: Import Sort (Jupyter Notebooks)
       args: [--profile=black]
 
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.4
+    hooks:
+      - id: ruff-check
+        name: ruff-check
+
   - repo: https://github.com/PyCQA/flake8
     rev: 7.1.2
     hooks:
@@ -67,13 +73,6 @@ repos:
       additional_dependencies: ['requests']
       exclude: (release_process.md|git.md|^doc/deployment/|tests|pyrit/prompt_converter/morse_converter.py|.github|pyrit/prompt_converter/emoji_converter.py|pyrit/score/markdown_injection.py|^pyrit/datasets/|^pyrit/auxiliary_attacks/gcg/)
 
-  - repo: https://github.com/pycqa/pylint
-    rev: v3.3.7
-    hooks:
-      - id: pylint
-        args: [--disable=all, --enable=unused-import]
-        exclude: NOTICE.txt
-
   - repo: https://github.com/pre-commit/mirrors-mypy
     rev: v1.15.0
     hooks:

doc/code/scoring/7_batch_scorer.ipynb

@@ -3,9 +3,7 @@
   {
    "cell_type": "markdown",
    "id": "0",
-   "metadata": {
-    "lines_to_next_cell": 0
-   },
+   "metadata": {},
    "source": [
     "# 7. Batch Scoring\n",
     "\n",
@@ -133,10 +131,9 @@
     }
    ],
    "source": [
-    "# pylint: disable=W0611\n",
     "from pyrit.memory import CentralMemory\n",
     "from pyrit.prompt_target import OpenAIChatTarget\n",
-    "from pyrit.score import (\n",
+    "from pyrit.score import (  # noqa: F401\n",
     "    AzureContentFilterScorer,\n",
     "    BatchScorer,\n",
     "    ContentClassifierPaths,\n",
@@ -205,12 +202,11 @@
     }
    ],
    "source": [
-    "# pylint: disable=W0611\n",
     "import uuid\n",
     "\n",
     "from pyrit.memory import CentralMemory\n",
     "from pyrit.prompt_target import OpenAIChatTarget\n",
-    "from pyrit.score import (\n",
+    "from pyrit.score import (  # noqa: F401\n",
     "    AzureContentFilterScorer,\n",
     "    BatchScorer,\n",
     "    ContentClassifierPaths,\n",
@@ -256,7 +252,8 @@
  ],
  "metadata": {
   "jupytext": {
-   "cell_metadata_filter": "-all"
+   "cell_metadata_filter": "-all",
+   "main_language": "python"
   },
   "language_info": {
    "codemirror_mode": {

doc/code/scoring/7_batch_scorer.py

@@ -64,10 +64,9 @@
 # Once the prompts are in the database (which again, is often automatic) we can use `BatchScorer` to score them with whatever scorers we want. It works in parallel with batches.
 
 # %%
-# pylint: disable=W0611
 from pyrit.memory import CentralMemory
 from pyrit.prompt_target import OpenAIChatTarget
-from pyrit.score import (
+from pyrit.score import (  # noqa: F401
     AzureContentFilterScorer,
     BatchScorer,
     ContentClassifierPaths,
@@ -113,12 +112,11 @@
 # - Converted Value SHA256
 
 # %%
-# pylint: disable=W0611
 import uuid
 
 from pyrit.memory import CentralMemory
 from pyrit.prompt_target import OpenAIChatTarget
-from pyrit.score import (
+from pyrit.score import (  # noqa: F401
     AzureContentFilterScorer,
     BatchScorer,
     ContentClassifierPaths,

pyproject.toml

@@ -81,6 +81,7 @@ dev = [
     "pytest-cov>=6.1.1",
     "pytest-timeout>=2.4.0",
     "respx>=0.22.0",
+    "ruff>=0.14.4",
     "sphinxcontrib-mermaid>=1.0.0",
     "types-PyYAML>=6.0.12.20250516",
     "types-requests>=2.31.0.20250515",
@@ -174,6 +175,9 @@ formats = "ipynb,py:percent"
 
 [tool.ruff]
 line-length = 120
+
+[tool.ruff.lint]
+preview = true
 fixable = [
     "A",
     "B",
@@ -220,3 +224,34 @@ fixable = [
     "UP",
     "YTT",
 ]
+select = [
+    "D",  # https://docs.astral.sh/ruff/rules/#pydocstyle-d
+    "DOC",  # https://docs.astral.sh/ruff/rules/#pydoclint-doc
+    "F401",  # unused-import
+]
+ignore = [
+    "D100",  # Missing docstring in public module
+    "D200",  # One-line docstring should fit on one line
+    "D205",  # 1 blank line required between summary line and description
+    "D212",  # Multi-line docstring summary should start at the first line
+    "D301",  # Use r""" if any backslashes in a docstring
+    "DOC502",  # Raised exception is not explicitly raised
+]
+extend-select = [
+    "D204",  # 1 blank line required after class docstring
+    "D213",  # Multi-line docstring summary should start at the second line
+    "D401",  # First line of docstring should be in imperative mood
+    "D404",  # First word of the docstring should not be "This"
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Ignore D and DOC rules everywhere except for the pyrit/ directory
+"!pyrit/**.py" = ["D", "DOC"]
+# 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/__init__.py" = ["D104"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"

pyrit/analytics/conversation_analytics.py

@@ -29,7 +29,7 @@ def get_prompt_entries_with_same_converted_content(
         self, *, chat_message_content: str
     ) -> list[ConversationMessageWithSimilarity]:
         """
-        Retrieves chat messages that have the same converted content
+        Retrieves chat messages that have the same converted content.
 
         Args:
             chat_message_content (str): The content of the chat message to find similar messages for.
@@ -68,7 +68,6 @@ def get_similar_chat_messages_by_embedding(
             List[ConversationMessageWithSimilarity]: A list of ConversationMessageWithSimilarity objects representing
             the similar chat messages based on embedding similarity.
         """
-
         all_embdedding_memory = self.memory_interface.get_all_embeddings()
         similar_messages = []
 

pyrit/analytics/result_analysis.py

@@ -49,7 +49,6 @@ def analyze_results(attack_results: list[AttackResult]) -> dict:
             "By_attack_identifier": dict[str, AttackStats]
         }
     """
-
     if not attack_results:
         raise ValueError("attack_results cannot be empty")
 

pyrit/auth/azure_auth.py

@@ -41,7 +41,8 @@ def _set_default_token(self) -> None:
         self.token = self.access_token.token
 
     def refresh_token(self) -> str:
-        """Refresh the access token if it is expired.
+        """
+        Refresh the access token if it is expired.
 
         Returns:
             A token
@@ -79,7 +80,8 @@ def get_access_token_from_azure_cli(*, scope: str, tenant_id: str = ""):
 
 
 def get_access_token_from_azure_msi(*, client_id: str, scope: str):
-    """Connect to an AOAI endpoint via managed identity credential attached to an Azure resource.
+    """
+    Connect to an AOAI endpoint via managed identity credential attached to an Azure resource.
     For proper setup and configuration of MSI
     https://learn.microsoft.com/en-us/entra/identity/managed-identities-azure-resources/overview.
 
@@ -100,7 +102,8 @@ def get_access_token_from_azure_msi(*, client_id: str, scope: str):
 
 
 def get_access_token_from_msa_public_client(*, client_id: str, scope: str):
-    """Uses MSA account to connect to an AOAI endpoint via interactive login. A browser window
+    """
+    Uses MSA account to connect to an AOAI endpoint via interactive login. A browser window
     will open and ask for login credentials.
 
     Args:
@@ -120,7 +123,8 @@ def get_access_token_from_msa_public_client(*, client_id: str, scope: str):
 
 
 def get_access_token_from_interactive_login(scope: str) -> str:
-    """Connects to an OpenAI endpoint with an interactive login from Azure. A browser window will
+    """
+    Connects to an OpenAI endpoint with an interactive login from Azure. A browser window will
     open and ask for login credentials.  The token will be scoped for Azure Cognitive services.
 
     Returns:
@@ -135,7 +139,8 @@ def get_access_token_from_interactive_login(scope: str) -> str:
 
 
 def get_token_provider_from_default_azure_credential(scope: str) -> Callable[[], str]:
-    """Connect to an AOAI endpoint via default Azure credential.
+    """
+    Connect to an AOAI endpoint via default Azure credential.
 
     Returns:
         Authentication token provider
@@ -149,7 +154,8 @@ def get_token_provider_from_default_azure_credential(scope: str) -> Callable[[],
 
 
 def get_default_scope(endpoint: str) -> str:
-    """Get the default scope for the given endpoint.
+    """
+    Get the default scope for the given endpoint.
 
     Args:
         endpoint (str): The endpoint to get the scope for.
@@ -170,12 +176,13 @@ def get_default_scope(endpoint: str) -> str:
 def get_speech_config(resource_id: Union[str, None], key: Union[str, None], region: str):
     """
     Get the speech config using key/region pair (for key auth scenarios) or resource_id/region pair
-    (for Entra auth scenarios)
+    (for Entra auth scenarios).
 
     Args:
         resource_id (Union[str, None]): The resource ID to get the token for.
         key (Union[str, None]): The Azure Speech key
         region (str): The region to get the token for.
+
     Returns:
         The speech config based on passed in args
 
@@ -207,7 +214,8 @@ def get_speech_config(resource_id: Union[str, None], key: Union[str, None], regi
 
 
 def get_speech_config_from_default_azure_credential(resource_id: str, region: str):
-    """Get the speech config for the given resource ID and region.
+    """
+    Get the speech config for the given resource ID and region.
 
     Args:
         resource_id (str): The resource ID to get the token for.