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
+32 -39
View File
@@ -1,8 +1,6 @@
# SPDX-License-Identifier: Apache-2.0
# SPDX-FileCopyrightText: Copyright contributors to the vLLM project
"""
Core abstractions for KV cache offloading in vLLM v1.
"""
"""Core abstractions for KV cache offloading in vLLM v1."""
from abc import ABC, abstractmethod
from collections.abc import Collection, Iterable, Sequence
@@ -149,8 +147,7 @@ class ScheduleEndContext(NamedTuple):
class LoadStoreSpec:
"""
Metadata that encapsulates information allowing a worker
"""Metadata that encapsulates information allowing a worker
to load, and optionally also to store, blocks of KV data.
"""
@@ -235,8 +232,7 @@ class OffloadingKVEventsConfig:
class OffloadingManager(ABC):
@abstractmethod
def lookup(self, key: OffloadKey, req_context: ReqContext) -> LookupResult:
"""
Checks whether a single block is offloaded and ready to be read.
"""Checks whether a single block is offloaded and ready to be read.
Args:
key: the key identifying the block to lookup.
@@ -246,6 +242,7 @@ class OffloadingManager(ABC):
HIT if the block is offloaded and ready, MISS if not found,
HIT_PENDING if found but not yet readable, or RETRY if the
lookup should be retried later.
"""
pass
@@ -255,8 +252,7 @@ class OffloadingManager(ABC):
keys: Collection[OffloadKey],
req_context: ReqContext,
) -> LoadStoreSpec:
"""
Prepare the given blocks to be read.
"""Prepare the given blocks to be read.
The given blocks will be protected from eviction until
complete_load is called.
It assumes all given blocks are offloaded.
@@ -268,27 +264,28 @@ class OffloadingManager(ABC):
Returns:
A LoadStoreSpec that can be used by a worker to locate and load
the actual offloaded KV data.
"""
pass
def touch(self, keys: Collection[OffloadKey], req_context: ReqContext):
"""
Mark the given blocks as recently used.
"""Mark the given blocks as recently used.
This could in practice mean moving them to the end of an LRU list.
Args:
keys: the keys identifying the blocks.
req_context: per-request context (e.g. kv_transfer_params).
"""
return
def complete_load(self, keys: Collection[OffloadKey], req_context: ReqContext):
"""
Marks previous blocks that were prepared to load as done loading.
"""Marks previous blocks that were prepared to load as done loading.
Args:
keys: the keys identifying the blocks.
req_context: per-request context (e.g. kv_transfer_params).
"""
return
@@ -298,8 +295,7 @@ class OffloadingManager(ABC):
keys: Collection[OffloadKey],
req_context: ReqContext,
) -> PrepareStoreOutput | None:
"""
Prepare the given blocks to be offloaded.
"""Prepare the given blocks to be offloaded.
The given blocks will be protected from eviction until
complete_store is called.
@@ -312,6 +308,7 @@ class OffloadingManager(ABC):
where to store them (LoadStoreSpec), and list of blocks that
were evicted as a result.
None is returned if the blocks cannot be stored.
"""
pass
@@ -321,8 +318,7 @@ class OffloadingManager(ABC):
req_context: ReqContext,
success: bool = True,
):
"""
Marks blocks which were previously prepared to be stored, as stored.
"""Marks blocks which were previously prepared to be stored, as stored.
Following this call, the blocks become loadable.
If success is False, blocks that were not marked as stored will be
removed.
@@ -331,25 +327,25 @@ class OffloadingManager(ABC):
keys: the keys identifying the blocks.
req_context: per-request context (e.g. kv_transfer_params).
success: whether the blocks were stored successfully.
"""
return
@abstractmethod
def on_new_request(self, req_context: ReqContext) -> RequestOffloadingContext:
"""
Called when a new request is first seen by the scheduler.
"""Called when a new request is first seen by the scheduler.
Returns a RequestOffloadingContext indicating how this request's
blocks should be offloaded.
Args:
req_context: per-request context.
"""
pass
def on_request_finished(self, req_context: ReqContext) -> None:
"""
Called when a request has finished.
"""Called when a request has finished.
By the time this is called, the scheduler will issue no more
submit-side calls for this request, such as prepare_store() and
@@ -364,12 +360,12 @@ class OffloadingManager(ABC):
Args:
req_context: per-request context.
"""
return
def take_events(self) -> Iterable[OffloadingEvent]:
"""
Take the offloading events from the manager.
"""Take the offloading events from the manager.
A tier manager emits only events for storage state it owns. A
composing manager may aggregate child event streams, but should not
@@ -377,6 +373,7 @@ class OffloadingManager(ABC):
Yields:
New OffloadingEvents collected since the last call.
"""
return ()
@@ -410,8 +407,7 @@ class OffloadingManager(ABC):
class BlockIDsLoadStoreSpec(LoadStoreSpec, ABC):
"""
Spec for loading/storing KV blocks from given block numbers.
"""Spec for loading/storing KV blocks from given block numbers.
Subclass semantics differ: GPULoadStoreSpec.block_ids are GPU block
indices; CPULoadStoreSpec.block_ids are CPU cache chunk indices.
@@ -425,8 +421,7 @@ class BlockIDsLoadStoreSpec(LoadStoreSpec, ABC):
class GPULoadStoreSpec(BlockIDsLoadStoreSpec):
"""
Spec for loading/storing a KV block to GPU memory.
"""Spec for loading/storing a KV block to GPU memory.
If there are multiple KV groups, the blocks are expected to be
ordered by the group index.
@@ -460,8 +455,7 @@ class GPULoadStoreSpec(BlockIDsLoadStoreSpec):
@dataclass
class CanonicalKVCacheTensor:
"""
A canonicalized KV cache tensor whose first dimension is num_blocks.
"""A canonicalized KV cache tensor whose first dimension is num_blocks.
With standardized layouts (RFC #42082) num_blocks is always the leading
logical dimension.
@@ -478,7 +472,8 @@ class CopyRun:
"""A strided byte correspondence between this worker's physical page and
a canonical page: for i in range(num_fragments), fragment i spans
[local_offset + i * local_stride, +fragment_size) in the worker's page and
[canonical_offset + i * canonical_stride, +fragment_size) canonically."""
[canonical_offset + i * canonical_stride, +fragment_size) canonically.
"""
local_offset: int
canonical_offset: int
@@ -517,8 +512,7 @@ class CanonicalPageMapping:
@dataclass
class CanonicalKVCacheRef:
"""
Per-layer (or group of layers) reference to a specific (by index)
"""Per-layer (or group of layers) reference to a specific (by index)
CanonicalKVCacheTensor and records the un-padded page size used by that layer.
"""
@@ -532,8 +526,7 @@ class CanonicalKVCacheRef:
@dataclass
class CanonicalKVCaches:
"""
Canonicalized block-level representation of the KV caches.
"""Canonicalized block-level representation of the KV caches.
Composed of:
- Unique list of KV cache data tensors,
@@ -561,7 +554,8 @@ class TransferResult:
class OffloadingWorker(ABC):
"""Runs in the worker process. Performs async KV transfers for ONE
offloaded medium (e.g. CPU). Direction is explicit via submit_store /
submit_load, so there is no (src_medium, dst_medium) routing."""
submit_load, so there is no (src_medium, dst_medium) routing.
"""
@abstractmethod
def submit_store(
@@ -620,8 +614,7 @@ class OffloadingSpec(ABC):
@abstractmethod
def get_manager(self) -> OffloadingManager:
"""
Get an OffloadingManager that will be used
"""Get an OffloadingManager that will be used
by the scheduler-side offloading connector to track
offloaded blocks and manage evictions.
"""
@@ -629,13 +622,13 @@ class OffloadingSpec(ABC):
@abstractmethod
def get_worker(self, kv_caches: CanonicalKVCaches) -> OffloadingWorker:
"""
Get an OffloadingWorker that handles async KV transfers for this spec.
"""Get an OffloadingWorker that handles async KV transfers for this spec.
Args:
kv_caches: Canonicalized KV caches.
Returns:
An OffloadingWorker instance for this medium.
"""
pass