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>
This commit is contained in:
Harry Mellor
2026-09-16 16:44:29 +00:00
committed by GitHub
co-authored by Claude Opus 5
parent 804e5377aa
commit 8c1557a79c
2002 changed files with 15024 additions and 14269 deletions
@@ -166,8 +166,8 @@ def _init_kv_cache_quant(
layer: The attention layer instance to initialize.
quant_config: Optional quantization configuration.
prefix: Layer name prefix for quantization method lookup.
"""
"""
# Note [Register q/k/v/prob scales in state dict]
# When calling model.to(device), only parameters/buffers in state dict are
# moved. If not registering q/k/v/prob scales in state dict, there would
@@ -254,8 +254,7 @@ class Attention(nn.Module, AttentionLayerBase):
head_size_v: int | None = None,
**extra_impl_args,
) -> None:
"""
The KV cache is stored inside this class and is accessed via
"""The KV cache is stored inside this class and is accessed via
`self.kv_cache`.
"""
super().__init__()
@@ -493,8 +492,7 @@ class Attention(nn.Module, AttentionLayerBase):
output_shape: torch.Size | None = None,
output_dtype: torch.dtype | None = None,
) -> torch.Tensor:
"""
The KV cache is stored inside this class and is accessed via
"""The KV cache is stored inside this class and is accessed via
`self.kv_cache`.
Attention metadata (`attn_metadata`) is set using a context manager in
@@ -691,6 +689,7 @@ def get_attention_context(
Note: attn_metadata may be None, but attn_layer and kv_cache are always
extracted from the forward context.
"""
forward_context: ForwardContext = get_forward_context()
attn_metadata_raw = forward_context.attn_metadata
@@ -718,8 +717,7 @@ def unified_kv_cache_update(
value: torch.Tensor,
layer_name: LayerNameType,
) -> torch.Tensor:
"""
Returns a dummy that is passed to unified_attention to signal a side effect and
"""Returns a dummy that is passed to unified_attention to signal a side effect and
the data dependency between them to ensure torch.compile preserves ordering.
"""
layer_name = _resolve_layer_name(layer_name)
@@ -34,7 +34,6 @@ def _get_cross_slot_mapping(
device: torch.device,
) -> torch.Tensor:
"""Get cross-attention slot mappings."""
block_size = kv_cache_spec.block_size
slot_mappings = []
@@ -187,8 +186,7 @@ def create_cross_attention_backend(
class CrossAttention(Attention):
"""
Cross-attention for encoder-decoder models.
"""Cross-attention for encoder-decoder models.
Handles attention between decoder queries and encoder keys/values.
"""
@@ -49,9 +49,7 @@ def create_encoder_only_attention_backend(
class EncoderOnlyAttention(Attention):
"""
Encoder attention is a special case that doesn't need a KV Cache.
"""
"""Encoder attention is a special case that doesn't need a KV Cache."""
def __init__(
self,
@@ -1,7 +1,6 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""
# MLA Common Components
"""# MLA Common Components
This file implements common components for MLA implementations.
@@ -1415,8 +1414,7 @@ def unified_mla_kv_cache_update(
kv_cache_dtype: str,
k_scale: torch.Tensor,
) -> torch.Tensor:
"""
Returns a dummy that is passed to unified_attention to signal a side effect and
"""Returns a dummy that is passed to unified_attention to signal a side effect and
the data dependency between them to ensure torch.compile preserves ordering.
"""
layer_name = _resolve_layer_name(layer_name)
@@ -1539,8 +1537,7 @@ def dynamic_per_batched_tensor_quant(
dynamic_arg_dims={"decode_ql_nope": 0, "decode_q_pe": 0},
)
class _DecodeConcatQuantFP8(QuantFP8):
"""
QuantFP8 variant that concatenates decode_ql_nope and decode_q_pe before
"""QuantFP8 variant that concatenates decode_ql_nope and decode_q_pe before
quantization. When disabled, forward_native is compiled via torch.compile,
fusing cat/reshape/quant/view together.
"""
@@ -1571,7 +1568,8 @@ class MLACommonBackend(AttentionBackend):
@classmethod
def customize_spec(cls, spec: "AttentionSpec") -> "AttentionSpec":
"""Per-token-head modes pack an inline fp32 scale pair after the
latent data (single-sided: ``head_size_v == 0`` for MLA)."""
latent data (single-sided: ``head_size_v == 0`` for MLA).
"""
spec = super().customize_spec(spec)
mode = spec.kv_quant_mode
if spec.state_content_bytes is not None or not mode.is_per_token_head:
@@ -2030,6 +2028,7 @@ def build_mla_chunked_context_metadata(
Returns:
The chunked-context metadata, or None when no prefill has any context.
"""
# NOTE: it is recommended you read the `Chunked Prefill` section in the
# comment at the top of the file before trying to understand this code.
@@ -2230,8 +2229,7 @@ def build_mla_chunked_context_metadata(
class MLACommonMetadataBuilder(AttentionMetadataBuilder[M]):
"""
NOTE: Please read the comment at the top of the file before trying to
"""NOTE: Please read the comment at the top of the file before trying to
understand this class
"""
@@ -2316,8 +2314,7 @@ class MLACommonMetadataBuilder(AttentionMetadataBuilder[M]):
vllm_config: VllmConfig,
model_dtype: torch.dtype,
) -> torch.dtype:
"""
Determine the query data type for prefill queries.
"""Determine the query data type for prefill queries.
Return FP8 dtype if cache is FP8 and prefill query quantization
is enabled, else model dtype.
"""
@@ -2484,8 +2481,7 @@ class MLACommonMetadataBuilder(AttentionMetadataBuilder[M]):
def build_for_cudagraph_capture(
self, common_attn_metadata: CommonAttentionMetadata
) -> M:
"""
This method builds the metadata for full cudagraph capture.
"""This method builds the metadata for full cudagraph capture.
Currently, only decode is supported for full cudagraphs with MLA.
"""
m = common_attn_metadata
@@ -2671,14 +2667,16 @@ def reorg_kvcache(
max_seq_len: int,
toks: int,
) -> tuple[torch.Tensor, torch.Tensor]:
"""
reorg and unpad kvcache after cp local gather to tp layout for attn kernel.
"""Reorg and unpad kvcache after cp local gather to tp layout for attn kernel.
e.g.
allgatered_kv_c_normed = [T0_0, T0_1, T0_2, T0_3, T1_0, T1_1, ...,
T0_4, T0_5, pad, pad, T1_2, pad, ...]
-> reorganized_kv_c_normed = [T0_0, T0_1, T0_2, T0_3, T0_4, T0_5,
T1_0, T1_1, T1_2, ...]
Args:
allgatered_kv_c_normed: all-gathered, padded latent KV cache.
allgatered_k_pe: all-gathered, padded RoPE key cache.
padded_local_chunk_seq_lens_lst: local chunk context lengths
under current CP rank.
local_context_lens_allranks: local context lengths on each CP rank.
@@ -2687,6 +2685,7 @@ def reorg_kvcache(
sum_seq_len: the sum of cp_chunk_seq_lens_lst.
max_seq_len: the max value of cp_chunk_seq_lens_lst.
toks: the number of tokens for local gather cache.
"""
kv_c_segments = []
k_pe_segments = []
@@ -2789,10 +2788,16 @@ def accumulate_mla_context_chunk(
remaining token range is initialized.
Args:
chunk: The context chunk being folded in.
attn_output: The chunk's attention output.
attn_softmax_lse: The chunk's log-sum-exp values.
output: Running context partial, updated in place.
output_lse: Running log-sum-exp, updated in place.
output_written: The chunk's attention output already landed in
``output[chunk.token_slice]`` because the backend was handed it as
``out``, leaving only the lse to fold. Invalid for a continuation
chunk, whose leading tokens must be merged rather than overwritten.
"""
token_start = chunk.token_slice.start
token_end = chunk.token_slice.stop
@@ -2819,8 +2824,7 @@ def accumulate_mla_context_chunk(
class MLACommonBaseImpl(MLAAttentionImpl[A], Generic[A]):
"""
Shared MLA base providing dense-MHA prefill (via the selected
"""Shared MLA base providing dense-MHA prefill (via the selected
MLAPrefillBackend) for both dense and sparse impls; subclasses add decode
(``forward_mqa``).
"""
@@ -2856,8 +2860,7 @@ class MLACommonBaseImpl(MLAAttentionImpl[A], Generic[A]):
def _concat_k_nope_k_pe(
self, k_nope: torch.Tensor, k_pe: torch.Tensor
) -> torch.Tensor:
"""
Efficiently concatenate k_nope and k_pe tensors along the last dimension.
"""Efficiently concatenate k_nope and k_pe tensors along the last dimension.
This function avoids the performance penalty of torch.cat with expanded
non-contiguous tensors by pre-allocating the output and using direct copies.
@@ -2869,6 +2872,7 @@ class MLACommonBaseImpl(MLAAttentionImpl[A], Generic[A]):
Returns:
Tensor of shape [..., nope_dim + pe_dim]
"""
if k_pe.shape[-1] == 0:
# NoPE MLA: nothing to append, so no copy either.
@@ -3224,8 +3228,7 @@ class MLACommonBaseImpl(MLAAttentionImpl[A], Generic[A]):
class MLACommonImpl(MLACommonBaseImpl[M], Generic[M]):
"""
NOTE: Please read the comment at the top of the file before trying to
"""NOTE: Please read the comment at the top of the file before trying to
understand this class
"""
@@ -322,14 +322,14 @@ class MMEncoderAttention(CustomOp):
num_kv_heads: int | None = None,
prefix: str = "",
) -> None:
"""
Args:
num_heads: number of attention heads per partition.
head_size: hidden_size per attention head.
scale: scale factor.
num_kv_heads: number of kv heads.
prefix: This has no effect, it is only here to make it easier to
swap between Attention and MultiHeadAttention
"""Args:
num_heads: number of attention heads per partition.
head_size: hidden_size per attention head.
scale: scale factor.
num_kv_heads: number of kv heads.
prefix: This has no effect, it is only here to make it easier to
swap between Attention and MultiHeadAttention
"""
super().__init__()
@@ -517,8 +517,7 @@ class MMEncoderAttention(CustomOp):
q_len: int,
kv_len: int,
) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
"""
Reshape query, key, value to 4D tensors:
"""Reshape query, key, value to 4D tensors:
(batch_size, seq_len, num_heads, head_size)
"""
query = query.view(bsz, q_len, self.num_heads, self.head_size)
@@ -114,9 +114,7 @@ def create_static_sink_attention_backend(
@CustomOp.register("static_sink_attention")
class StaticSinkAttention(Attention, CustomOp):
"""
Attention with static sink tokens
"""
"""Attention with static sink tokens."""
def __init__(
self,