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
@@ -15,7 +15,8 @@ from vllm.v1.kv_offload.cpu.policies.lru import LRUCachePolicy
class _DummyCachePolicy(CachePolicy):
"""Minimal CachePolicy for CachePolicyFactory registration tests. Loaded
by module path, so it must be importable at module scope (mirrors
tests/v1/kv_offload/test_factory.py's SingleArgExternalOffloadingSpec)."""
tests/v1/kv_offload/test_factory.py's SingleArgExternalOffloadingSpec).
"""
def __init__(self, cache_capacity: int) -> None:
self.cache_capacity = cache_capacity
@@ -54,7 +55,8 @@ class TestCachePolicyFactory:
def test_pre_registered_policies_can_be_imported(self):
"""If someone moves a policy module but forgets to update
factory.py, CI fails."""
factory.py, CI fails.
"""
for name in CachePolicyFactory._registry:
cls = CachePolicyFactory._registry[name]()
assert issubclass(cls, CachePolicy)
@@ -88,7 +90,8 @@ class TestCachePolicyFactory:
register_cache_policy() call -- this is how external projects
integrate a custom CachePolicy without forking/patching vLLM.
Mirrors tests/v1/kv_offload/test_factory.py's
test_dynamic_load_via_spec_module_path."""
test_dynamic_load_via_spec_module_path.
"""
policy_cls = CachePolicyFactory.get_cache_policy_cls(
"_DummyCachePolicy", "tests.v1.kv_offload.cpu.policies.test_factory"
)
@@ -96,7 +99,8 @@ class TestCachePolicyFactory:
def test_manager_resolves_policy_via_module_path(self):
"""End-to-end: CPUOffloadingManager resolves an unregistered policy
purely from cache_policy_module_path."""
purely from cache_policy_module_path.
"""
manager = CPUOffloadingManager(
num_chunks=4,
cache_policy="_DummyCachePolicy",
@@ -106,6 +110,7 @@ class TestCachePolicyFactory:
def test_unregistered_policy_without_module_path_raises(self):
"""eviction_policy not in registry + no cache_policy_module_path ->
ValueError, same shape as the OffloadingSpecFactory error path."""
ValueError, same shape as the OffloadingSpecFactory error path.
"""
with pytest.raises(ValueError, match="Unknown cache policy"):
CachePolicyFactory.get_cache_policy_cls("nonexistent", None)
@@ -126,7 +126,8 @@ def _canonical_handler(gpu_tensor, cpu_tensor, mapping, gpu_to_cpu):
def test_gpu_roundtrip_assembles_canonical_page_across_ranks():
"""Two TP2-style rank handlers must scatter into one shared canonical
CPU page such that each rank reloads bit-exact and a whole-page (TP1)
reader sees both shards — the cross-topology contract."""
reader sees both shards — the cross-topology contract.
"""
torch.manual_seed(0)
num_blocks = 4
gpu_rank = [
@@ -203,7 +204,8 @@ def _nhd_shard_mapping(tp: int, rank: int) -> CanonicalPageMapping:
def _head_shard(full_kv: torch.Tensor, tp: int, rank: int) -> torch.Tensor:
"""This rank's local page rows out of the (blocks, 2, tokens, heads,
head_bytes) ground truth."""
head_bytes) ground truth.
"""
local_heads = _TOTAL_HEADS // tp
shard = full_kv[:, :, :, rank * local_heads : (rank + 1) * local_heads, :]
return shard.reshape(full_kv.shape[0], -1).contiguous()
@@ -214,7 +216,8 @@ def _head_shard(full_kv: torch.Tensor, tp: int, rank: int) -> torch.Tensor:
def test_cross_topology_roundtrip(writer_tp: int, reader_tp: int):
"""KV written at one tp must be readable at another: writer ranks scatter
head shards into a shared canonical region, reader ranks gather their own
shards, and every reader must see the writers' ground-truth bytes."""
shards, and every reader must see the writers' ground-truth bytes.
"""
torch.manual_seed(0)
num_blocks = 3
full_kv = torch.randint(
+13 -28
View File
@@ -166,8 +166,7 @@ def test_cpu_eviction_removed_precedes_stored():
@pytest.mark.parametrize("eviction_policy", ["lru", "arc"])
def test_already_stored_chunk_not_evicted_during_prepare_store(eviction_policy):
"""
Regression test: a chunk that is already stored must not be evicted
"""Regression test: a chunk that is already stored must not be evicted
by prepare_store() when it needs to make room for new chunks.
Applies to both lru and arc policies.
@@ -367,9 +366,7 @@ def test_cpu_manager_clears_write_usage_after_failed_store():
def test_cpu_manager():
"""
Tests CPUOffloadingManager with lru policy.
"""
"""Tests CPUOffloadingManager with lru policy."""
# initialize a CPU manager with a capacity of 4 chunks
cpu_manager = make_cpu_manager(num_chunks=4, cache_policy="lru", enable_events=True)
@@ -597,8 +594,7 @@ class TestARCPolicy:
return manager, policy
def test_basic(self):
"""
Tests CPUOffloadingManager with arc policy.
"""Tests CPUOffloadingManager with arc policy.
Verifies that ARC handles store, load, and lookup operations correctly.
"""
cpu_manager, arc_policy = self._make_manager()
@@ -637,8 +633,7 @@ class TestARCPolicy:
assert len(arc_policy.t2) == 0
def test_t1_to_t2_promotion(self):
"""
Tests that accessing a chunk in T1 promotes it to T2 (frequent).
"""Tests that accessing a chunk in T1 promotes it to T2 (frequent).
This is a key feature of ARC's adaptive behavior.
"""
cpu_manager, arc_policy = self._make_manager(enable_events=False)
@@ -659,8 +654,7 @@ class TestARCPolicy:
assert to_keys([1])[0] in arc_policy.t2
def test_eviction_with_load(self):
"""
Tests ARC eviction behavior similar to LRU test.
"""Tests ARC eviction behavior similar to LRU test.
Verifies that chunks being loaded (ref_cnt > 0) cannot be evicted.
"""
cpu_manager, _ = self._make_manager()
@@ -700,8 +694,7 @@ class TestARCPolicy:
assert len(prepare_store_output.evicted_keys) >= 1
def test_adaptive_target(self):
"""
Tests ARC's adaptive target adjustment via ghost lists.
"""Tests ARC's adaptive target adjustment via ghost lists.
When a chunk in B1 (ghost list) is accessed, target_t1_size increases.
When a chunk in B2 is accessed, target_t1_size decreases.
"""
@@ -728,8 +721,7 @@ class TestARCPolicy:
assert arc_policy.target_t1_size > initial_target
def test_t1_t2_eviction_policy(self):
"""
Tests that ARC evicts from T1 or T2 based on target_t1_size.
"""Tests that ARC evicts from T1 or T2 based on target_t1_size.
If |T1| >= target_t1_size, evict from T1, otherwise from T2.
"""
cpu_manager, arc_policy = self._make_manager(enable_events=False)
@@ -917,8 +909,7 @@ class TestARCPolicy:
assert not arc_policy.b2
def test_ghost_list_bounds(self):
"""
Tests that ghost lists (B1, B2) don't grow unbounded.
"""Tests that ghost lists (B1, B2) don't grow unbounded.
They should be capped at cache_capacity.
"""
cpu_manager, arc_policy = self._make_manager(num_chunks=2, enable_events=False)
@@ -937,8 +928,7 @@ class TestARCPolicy:
assert len(arc_policy.b2) <= arc_policy.cache_capacity
def test_touch_ordering(self):
"""
Tests that touch() correctly updates access patterns.
"""Tests that touch() correctly updates access patterns.
Similar to LRU test but verifies T1/T2 ordering.
"""
cpu_manager, arc_policy = self._make_manager()
@@ -970,8 +960,7 @@ class TestARCPolicy:
)
def test_failed_store(self):
"""
Tests that failed store operations clean up correctly.
"""Tests that failed store operations clean up correctly.
Similar to LRU test but for ARC.
"""
cpu_manager, arc_policy = self._make_manager()
@@ -999,8 +988,7 @@ class TestARCPolicy:
assert evicted_hash in arc_policy.b1
def test_full_scenario(self):
"""
Comprehensive test covering multiple ARC operations in sequence.
"""Comprehensive test covering multiple ARC operations in sequence.
Similar to the full LRU test but adapted for ARC behavior.
"""
cpu_manager, arc_policy = self._make_manager()
@@ -1039,9 +1027,7 @@ class TestARCPolicy:
def test_filter_reused_manager():
"""
Tests CPUOffloadingManager reuse filtering (store_threshold=2).
"""
"""Tests CPUOffloadingManager reuse filtering (store_threshold=2)."""
manager = make_cpu_manager(
num_chunks=4,
cache_policy="lru",
@@ -1148,8 +1134,7 @@ def test_store_threshold_does_not_hide_ready_reuse():
def test_evictable_cache_chunk_count():
"""
Verifies _num_evictable_cache_chunks is maintained correctly through the
"""Verifies _num_evictable_cache_chunks is maintained correctly through the
full store/load lifecycle, eviction, failed stores, concurrent loads,
reset_cache, and the early-exit fast path in prepare_store.
"""
@@ -167,7 +167,8 @@ def _mp_race_construct_and_write(
) -> None:
"""Race to construct a SharedOffloadRegion, write fill_value, then wait
for the parent's cleanup signal before tearing down. The wait gives the
parent a window to read the raw mmap before the creator removes the file."""
parent a window to read the raw mmap before the creator removes the file.
"""
try:
region = SharedOffloadRegion(
engine_id=engine_id,
@@ -196,7 +197,8 @@ def _mp_barrier_construct_and_hold(
replicated: bool = False,
) -> None:
"""Construct with a real cross-process barrier, write, then hold the
mapping (no cleanup) until the parent SIGKILLs this process."""
mapping (no cleanup) until the parent SIGKILLs this process.
"""
try:
populate_calls = 0
get_populate_write_fn = region_module._get_populate_write_fn
@@ -250,7 +252,8 @@ def iid():
def test_create_next_worker_view_shape_and_stride(iid):
"""Returned tensor must have shape (num_chunks, tensor_page_size) and
stride (row_stride, 1) where row_stride = cpu_page_size * num_workers."""
stride (row_stride, 1) where row_stride = cpu_page_size * num_workers.
"""
with _region(iid, num_chunks=4, cpu_page_size=2 * PAGE_SIZE) as r:
t = r.create_next_worker_view(PAGE_SIZE)
assert t.shape == (4, PAGE_SIZE)
@@ -290,7 +293,8 @@ def test_create_next_worker_view_row_stride_with_multiple_workers(iid):
def test_create_next_worker_view_cursor_advances(iid):
"""Each create_next_worker_view call must advance _worker_offset by
tensor_page_size."""
tensor_page_size.
"""
with _region(iid, cpu_page_size=3 * PAGE_SIZE) as r:
assert r._worker_offset == 0
r.create_next_worker_view(PAGE_SIZE)
@@ -347,7 +351,8 @@ def test_create_next_worker_view_overflow_does_not_mutate_cursor(iid):
def test_create_next_worker_view_write_visible_in_raw_mmap(iid):
"""Writes into a create_next_worker_view view must appear at the correct
raw mmap offset"""
raw mmap offset
"""
with _region(iid, num_chunks=4) as r:
t = r.create_next_worker_view(PAGE_SIZE)
t[2, :] = 42 # write to chunk row 2
@@ -380,7 +385,8 @@ def test_create_next_worker_view_multi_tensor_layout(iid):
def test_create_next_worker_view_multiprocess_slots(iid):
"""Each worker process calls create_next_worker_view and writes distinct data;
the parent verifies each slot lands at the correct interleaved offset."""
the parent verifies each slot lands at the correct interleaved offset.
"""
num_workers = 2
num_chunks = 4
@@ -665,7 +671,8 @@ def test_multi_worker_race_shared_memory_visible(iid):
def test_multiprocess_race_construct_and_write(iid):
"""N processes race to construct the same SharedOffloadRegion, each writes
fill_value = rank+1 into their slot; parent verifies interleaved layout."""
fill_value = rank+1 into their slot; parent verifies interleaved layout.
"""
num_workers = 4
num_chunks = 3
@@ -791,7 +798,8 @@ def test_cleanup_unregisters_every_pinned_chunk(iid, monkeypatch):
def test_cleanup_after_create_next_worker_view_releases_mmap(iid):
"""cleanup() must close the mmap even after create_next_worker_view was called.
create_next_worker_view returns a view that shares storage with _base; both must be
released before mmap.close() can succeed."""
released before mmap.close() can succeed.
"""
r = _make_region(iid)
mmap_obj = r.mmap_obj
@@ -970,7 +978,8 @@ def test_ftruncate_failure_cleans_up_creator(monkeypatch):
def test_backing_file_unlinked_after_barrier(iid):
"""The file must exist until the barrier releases (late joiners need the
name) and be gone right after, so no exit path can leak it."""
name) and be gone right after, so no exit path can leak it.
"""
path = f"/dev/shm/vllm_offload_{iid}.mmap"
seen_at_barrier = []
@@ -992,7 +1001,8 @@ def test_backing_file_unlinked_after_barrier(iid):
def test_barrier_failure_unlinks_creator_and_raises(iid):
"""A failed rendezvous must remove the creator's file and re-raise, not
leave a stub that wedges the next start in _wait_for_file_size."""
leave a stub that wedges the next start in _wait_for_file_size.
"""
path = f"/dev/shm/vllm_offload_{iid}.mmap"
with pytest.raises(RuntimeError, match="peer died"):
_make_region(iid, barrier=MagicMock(side_effect=RuntimeError("peer died")))
@@ -1002,7 +1012,8 @@ def test_barrier_failure_unlinks_creator_and_raises(iid):
@pytest.mark.parametrize("replicated", [False, True])
def test_mp_barrier_unlinks_file_and_survives_sigkill(iid, replicated):
"""With a real cross-process barrier every worker maps one shared inode,
the name is gone while they run, and SIGKILL leaks nothing."""
the name is gone while they run, and SIGKILL leaks nothing.
"""
num_workers = 2
path = f"/dev/shm/vllm_offload_{iid}.mmap"
ctx = get_mp_context()
@@ -1041,7 +1052,8 @@ def test_mp_barrier_unlinks_file_and_survives_sigkill(iid, replicated):
@pytest.mark.parametrize("failure_phase", ["shm", "memory", "population"])
def test_setup_failure_before_barrier_releases_peers(iid, monkeypatch, failure_phase):
"""A worker that dies before the rendezvous must still arrive at the
barrier, or its peers block in the collective until it times out."""
barrier, or its peers block in the collective until it times out.
"""
failure = MagicMock(side_effect=ValueError("Insufficient space"))
memory_check = failure if failure_phase == "memory" else None
if failure_phase == "shm":
@@ -1072,7 +1084,8 @@ def test_setup_failure_before_barrier_releases_peers(iid, monkeypatch, failure_p
def test_mmap_failure_unlinks_creator_before_releasing_peers(iid, monkeypatch):
"""A creator that fails after sizing the file must drop it before arriving
at the barrier, so the next start does not land on a stale file."""
at the barrier, so the next start does not land on a stale file.
"""
path = f"/dev/shm/vllm_offload_{iid}.mmap"
monkeypatch.setattr("mmap.mmap", MagicMock(side_effect=OSError("mmap")))
seen_at_barrier = []
@@ -1085,7 +1098,8 @@ def test_mmap_failure_unlinks_creator_before_releasing_peers(iid, monkeypatch):
def test_barrier_release_failure_keeps_original_error(iid, monkeypatch):
"""When releasing the peers fails too, the setup error that explains the
failure must be the one that propagates."""
failure must be the one that propagates.
"""
import vllm.v1.kv_offload.cpu.shared_offload_region as region
monkeypatch.setattr(