Add pydocstyle to the ruff rules (#52136)

Signed-off-by: Harry Mellor <19981378+hmellor@users.noreply.github.com>
Signed-off-by: Harry Mellor <hej.mellor@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

tools/generate_cmake_presets.py

@@ -28,7 +28,6 @@ def get_cpu_cores():
 
 def generate_presets(output_path="CMakeUserPresets.json", force_overwrite=False):
     """Generates the CMakeUserPresets.json file."""
-
     print("Attempting to detect your system configuration...")
 
     # Detect NVCC

tools/generate_versions_json.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python3
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""
-Generate docker/versions.json from Dockerfile ARG defaults.
+"""Generate docker/versions.json from Dockerfile ARG defaults.
 
 This script parses the Dockerfile and extracts ARG defaults to create
 a bake-native versions.json file that can be used directly with:

tools/install_nixl_from_source_ubuntu.py

@@ -21,7 +21,7 @@ NIXL_REPO_URL = "https://github.com/ai-dynamo/nixl.git"
 
 # --- Helper Functions ---
 def get_latest_nixl_version():
-    """Helper function to get latest release version of NIXL"""
+    """Helper function to get latest release version of NIXL."""
     try:
         nixl_release_url = "https://api.github.com/repos/ai-dynamo/nixl/releases/latest"
         with urllib.request.urlopen(nixl_release_url) as response:
@@ -104,7 +104,6 @@ def install_system_dependencies():
 
 def build_and_install_prerequisites(args):
     """Builds UCX and NIXL from source, creating a self-contained wheel."""
-
     if not args.force_reinstall and is_pip_package_installed("nixl"):
         print("--> NIXL is already installed. Nothing to do.", flush=True)
         return

tools/pre_commit/check_spdx_header.py

@@ -16,7 +16,7 @@ class HeaderStyle:
 
 
 class SPDXStatus(Enum):
-    """SPDX header status enumeration"""
+    """SPDX header status enumeration."""
 
     EMPTY = "empty"  # empty __init__.py
     COMPLETE = "complete"
@@ -58,7 +58,7 @@ def header_insertion_index(style, lines):
 
 
 def check_spdx_header_status(file_path):
-    """Check SPDX header status of the file"""
+    """Check SPDX header status of the file."""
     license_line, copyright_line = spdx_header(file_style(file_path))
     with open(file_path, encoding="UTF-8") as file:
         lines = file.readlines()
@@ -92,7 +92,7 @@ def check_spdx_header_status(file_path):
 
 
 def add_header(file_path, status):
-    """Add or supplement SPDX header based on status"""
+    """Add or supplement SPDX header based on status."""
     style = file_style(file_path)
     license_line, copyright_line = spdx_header(style)
     full_spdx_header = f"{license_line}\n{copyright_line}"
@@ -137,7 +137,7 @@ def add_header(file_path, status):
 
 
 def main():
-    """Main function"""
+    """Main function."""
     files_missing_both = []
     files_missing_copyright = []
     files_missing_license = []

tools/pre_commit/generate_nightly_torch_test.py

@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""
-Generates specialized requirements files for nightly PyTorch testing.
+"""Generates specialized requirements files for nightly PyTorch testing.
 
 This script reads the main test requirements input file (`requirements/test/cuda.in`)
 and splits its content into two files:

tools/pre_commit/mypy.py

@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""
-Run mypy on changed files.
+"""Run mypy on changed files.
 
 This script is designed to be used as a pre-commit hook. It runs mypy
 on files that have been changed. It groups files into different mypy calls
@@ -14,6 +13,7 @@ Args:
     python_version: Python version to use (e.g., "3.10") or "local" to use
         the local Python version.
     changed_files: List of changed files to check.
+
 """
 
 import subprocess
@@ -125,14 +125,14 @@ EXCLUDE = [
 
 
 def group_files(changed_files: list[str]) -> dict[str, list[str]]:
-    """
-    Group changed files into different mypy calls.
+    """Group changed files into different mypy calls.
 
     Args:
         changed_files: List of changed files.
 
     Returns:
         A dictionary mapping file group names to lists of changed files.
+
     """
     exclude_pattern = re.compile(f"^{'|'.join(EXCLUDE)}.*")
     silent_pattern = re.compile(f"^({'|'.join(SILENT_GROUPS)}).*")
@@ -166,8 +166,7 @@ def mypy(
     follow_imports: str | None,
     file_group: str,
 ) -> int:
-    """
-    Run mypy on the given targets.
+    """Run mypy on the given targets.
 
     Args:
         targets: List of files or directories to check.
@@ -179,6 +178,7 @@ def mypy(
 
     Returns:
         The return code from mypy.
+
     """
     args = ["mypy"]
     if python_version is not None:

tools/pre_commit/validate_config.py

@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""
-Ensures all fields in a config dataclass have default values
+"""Ensures all fields in a config dataclass have default values
 and that each field has a docstring.
 """
 
@@ -14,13 +13,11 @@ import regex as re
 
 
 def get_attr_docs(cls_node: ast.ClassDef) -> dict[str, str]:
-    """
-    Get any docstrings placed after attribute assignments in a class body.
+    """Get any docstrings placed after attribute assignments in a class body.
 
     Adapted from https://davidism.com/attribute-docstrings/
     https://davidism.com/mit-license/
     """
-
     out = {}
 
     # Consider each pair of nodes.

tools/profiler/nsys_profile_tools/gputrc2graph.py

@@ -1,7 +1,6 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""
-This generates gpu kernel analysis output from nsys rep. Will call nsys
+"""This generates gpu kernel analysis output from nsys rep. Will call nsys
 stats  -r cuda_gpu_kern_trace, get non-overlapped gpu cycles, then generate
 csv and html output for analysis
 """
@@ -17,7 +16,7 @@ logger = logging.getLogger(__name__)
 
 # helper data class for annotating kernels
 def load_engine_model():
-    """returns engine_model built from all json files in the current dir"""
+    """Returns engine_model built from all json files in the current dir."""
     import glob
     import json
 
@@ -31,9 +30,7 @@ def load_engine_model():
 
 
 class GPUTrace2Graph:
-    """
-    Parses output of nsys report, generates csv and bar chart output
-    """
+    """Parses output of nsys report, generates csv and bar chart output."""
 
     def __init__(self):
         import pandas as pd  # avoid importing till needed
@@ -64,8 +61,7 @@ class GPUTrace2Graph:
         )
 
     def sum_non_overlapping_intervals(self, df):
-        """
-        returns new sorted df with Elapsed Time (ns) column using
+        """Returns new sorted df with Elapsed Time (ns) column using
         vectorized operations
         """
         logger.info("sorting %s trace records by start time", str(df.shape))
@@ -105,7 +101,7 @@ class GPUTrace2Graph:
 
     # functions for generating html files
     def make_html(self, df, output_dir, title):
-        """make html graph from df"""
+        """Make html graph from df."""
         import plotly.express as px
 
         if df.empty:
@@ -163,7 +159,7 @@ class GPUTrace2Graph:
         )
 
     def anno_gpu_kernname(self, df, mapping):
-        """add "Category" column"""
+        """Add "Category" column."""
 
         def anno_gpu_kernname_helper(name):
             for kern_name, val in mapping.items():
@@ -173,7 +169,7 @@ class GPUTrace2Graph:
         df["Category"] = df["Name"].apply(anno_gpu_kernname_helper)
 
     def make_nongpu_row(self, df, nongpu_sec):
-        """this will append non-gpu time entry at end of df"""
+        """This will append non-gpu time entry at end of df."""
         nongpu_row = self.pd.DataFrame([df.iloc[-1]])
         nongpu_row["Category"] = nongpu_row["Name"] = "CPU(non-GPU)"
         nongpu_row["Instances"] = 1
@@ -181,13 +177,13 @@ class GPUTrace2Graph:
         return nongpu_row
 
     def is_valid_file(self, base_file):
-        """asserts if base_file is non-existent or is empty"""
+        """Asserts if base_file is non-existent or is empty."""
         assert os.path.isfile(base_file) and os.path.getsize(base_file) > 0, (
             f"{base_file} doesn't exist or is empty"
         )
 
     def should_gen_file(self, new_file, base_file):
-        """figure out if new file should be generated from base_file"""
+        """Figure out if new file should be generated from base_file."""
         self.is_valid_file(base_file)
         if (
             os.path.exists(new_file)
@@ -201,8 +197,7 @@ class GPUTrace2Graph:
             return True
 
     def gen_sum_file(self, file, nsys_cmd):
-        """
-        generates sum file from nsys trace with times per kernel and
+        """Generates sum file from nsys trace with times per kernel and
         returns the name of the sum file
         """
         import subprocess
@@ -246,7 +241,7 @@ class GPUTrace2Graph:
         return sum_file
 
     def gen_graph(self, in_file, out_dir, title, nsys_cmd, engine_model):
-        """generates graph and csv file from in_file into out_dir"""
+        """Generates graph and csv file from in_file into out_dir."""
         # Initialize an empty DataFrame to store combined data
         combined_df = self.pd.DataFrame()
         for idx, (file, engine, model, total_sec) in enumerate(in_file):

tools/recipes/recipe_json_to_vllm_config.py

@@ -2,8 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
 
-"""
-Convert a vLLM Recipes per-hardware JSON rendering into:
+"""Convert a vLLM Recipes per-hardware JSON rendering into:
 
   1) config.yml - native `vllm serve --config` YAML
   2) env.sh     - environment variables required by the recipe
@@ -38,6 +37,7 @@ by the Recipes API instead of synthesizing strategy URLs locally.
 The converter intentionally targets a single `vllm serve` process. If the
 recipe rendering is multi-node, PD-disaggregated, or another multi-process
 deployment, it exits instead of silently generating an incomplete config.
+
 """
 
 from __future__ import annotations
@@ -551,8 +551,7 @@ def merge_value(dst: dict[str, Any], path: list[str], value: Any) -> None:
 
 
 def normalize_key(raw_key: str) -> list[str]:
-    """
-    Convert the CLI key to config-file spelling.
+    """Convert the CLI key to config-file spelling.
 
     Only the top-level CLI option name gets underscore -> dash normalization.
     Nested JSON field names after a dot are preserved.

tools/report_build_time_ninja.py

@@ -56,7 +56,8 @@ class Target:
 
     def __init__(self, start, end):
         """Creates a target object by passing in the start/end times in seconds
-        as a float."""
+        as a float.
+        """
         self.start = start
         self.end = end
         # A list of targets, appended to by the owner of this object.
@@ -104,7 +105,8 @@ class Target:
 def ReadTargets(log, show_all):
     """Reads all targets from .ninja_log file |log_file|, sorted by duration.
 
-    The result is a list of Target objects."""
+    The result is a list of Target objects.
+    """
     header = log.readline()
     assert header == "# ninja log v5\n", "unrecognized ninja log version {!r}".format(
         header
@@ -153,7 +155,8 @@ def GetExtension(target, extra_patterns):
 
     For targets that generate multiple outputs it is important to return a
     consistent 'canonical' extension. Ultimately the goal is to group build steps
-    by type."""
+    by type.
+    """
     for output in target.targets:
         if extra_patterns:
             for fn_pattern in extra_patterns.split(";"):
@@ -197,7 +200,6 @@ def GetExtension(target, extra_patterns):
 
 def SummarizeEntries(entries, extra_step_types):
     """Print a summary of the passed in list of Target objects."""
-
     # Create a list that is in order by time stamp and has entries for the
     # beginning and ending of each build step (one time stamp may have multiple
     # entries due to multiple steps starting/stopping at exactly the same time).

tools/vllm-rocm/pin_rocm_dependencies.py

@@ -1,8 +1,7 @@
 #!/usr/bin/env python3
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: Copyright contributors to the vLLM project
-"""
-Pin vLLM dependencies to exact versions of custom ROCm wheels.
+"""Pin vLLM dependencies to exact versions of custom ROCm wheels.
 
 This script modifies vLLM's requirements files to replace version constraints
 with exact versions of custom-built ROCm wheels (torch, triton, torchvision, amdsmi).
@@ -18,12 +17,12 @@ import regex as re
 
 
 def extract_version_from_wheel(wheel_name: str) -> str:
-    """
-    Extract version from wheel filename.
+    """Extract version from wheel filename.
 
     Example:
         torch-2.9.0a0+git1c57644-cp312-cp312-linux_x86_64.whl -> 2.9.0a0+git1c57644
         triton-3.4.0-cp312-cp312-linux_x86_64.whl -> 3.4.0
+
     """
     # Wheel format:
     #    {distribution}-{version}(-{build tag})?-{python}-{abi}-{platform}.whl
@@ -38,11 +37,11 @@ def extract_version_from_wheel(wheel_name: str) -> str:
 
 
 def get_custom_wheel_versions(install_dir: str) -> dict[str, str]:
-    """
-    Read /install directory and extract versions of custom wheels.
+    """Read /install directory and extract versions of custom wheels.
 
     Returns:
         Dict mapping package names to exact versions
+
     """
     install_path = Path(install_dir)
     if not install_path.exists():
@@ -92,8 +91,7 @@ def get_custom_wheel_versions(install_dir: str) -> dict[str, str]:
 
 
 def pin_dependencies_in_requirements(requirements_path: str, versions: dict[str, str]):
-    """
-    Insert custom wheel pins at the TOP of requirements file.
+    """Insert custom wheel pins at the TOP of requirements file.
 
     This ensures that when setup.py processes the file line-by-line,
     custom wheels (torch, triton, etc.) are encountered FIRST, before