[refactor] Soft-deprecate the legacy global ServerArgs accessors + ratchet (stack 3/15) (#30065)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

python/sglang/srt/server_args.py

@@ -7595,10 +7595,14 @@ class ServerArgs:
 
 
 # NOTE: The process-wide ServerArgs is owned by the runtime context
-# (sglang.srt.runtime_context). The two functions below are thin shims kept for
-# the existing call-sites; they publish/read the same live object by reference.
+# (sglang.srt.runtime_context). The two functions below are LEGACY shims kept
+# for the existing call-sites; they publish/read the same live object by
+# reference. Do not add new call-sites — the counts are ratcheted
+# (decrease-only) by test/registered/unit/test_legacy_global_ratchet.py.
 # Imports are in-function so the two modules stay cycle-free at import time.
 def set_global_server_args_for_scheduler(server_args: ServerArgs):
+    """Legacy publish shim — prefer ``get_context().set_server_args()`` from
+    ``sglang.srt.runtime_context`` in new code."""
     from sglang.srt.runtime_context import get_context
 
     get_context().set_server_args(server_args)
@@ -7608,6 +7612,8 @@ set_global_server_args_for_tokenizer = set_global_server_args_for_scheduler
 
 
 def get_global_server_args() -> ServerArgs:
+    """Legacy accessor shim — prefer ``get_server_args()`` from
+    ``sglang.srt.runtime_context`` in new code."""
     from sglang.srt.runtime_context import get_context
 
     return get_context().server_args

test/registered/unit/test_legacy_global_ratchet.py

@@ -0,0 +1,63 @@
+"""Ratchet guard: legacy global-accessor call-sites may only decrease.
+
+The process-wide ``ServerArgs`` is owned by the runtime context; the legacy
+``get_global_server_args`` / ``set_global_server_args_for_*`` names survive as
+thin shims for the existing call-sites. New code should use the
+``sglang.srt.runtime_context`` accessors (``get_server_args()`` /
+``get_context().set_server_args()``), so the shim call-site counts below must
+never grow. When your change removes call-sites, lower the matching baseline
+to the new count.
+"""
+
+from sglang.test.ci.ci_register import register_cpu_ci
+
+register_cpu_ci(est_time=5, suite="base-a-test-cpu")
+
+import re
+import unittest
+from pathlib import Path
+
+import sglang.srt
+from sglang.test.test_utils import CustomTestCase
+
+_SRT_ROOT = Path(next(iter(sglang.srt.__path__)))
+
+# Baselines counted over python/sglang/srt/**/*.py, including each function's
+# own def line. Ratchet: decrease-only.
+_RATCHETS = [
+    ("get_global_server_args", r"\bget_global_server_args\s*\(", 346),
+    (
+        "set_global_server_args_for_*",
+        r"\bset_global_server_args_for_(?:scheduler|tokenizer)\s*\(",
+        5,
+    ),
+]
+
+
+class TestLegacyGlobalRatchet(CustomTestCase):
+    def test_legacy_accessor_call_sites_match_the_baselines(self):
+        # Exact pin, failing in BOTH directions: a grown count means new code
+        # bypassed the runtime_context accessors; a shrunk count means a
+        # removal forgot to lower the baseline, which would let later changes
+        # silently re-add call-sites up to the stale ceiling.
+        sources = [
+            path.read_text(encoding="utf-8", errors="replace")
+            for path in sorted(_SRT_ROOT.rglob("*.py"))
+        ]
+        for name, pattern, baseline in _RATCHETS:
+            count = sum(len(re.findall(pattern, source)) for source in sources)
+            if count > baseline:
+                self.fail(
+                    f"{name} call-sites grew: {count} > baseline {baseline}. "
+                    "New code must use the sglang.srt.runtime_context accessors "
+                    "(get_server_args() / get_context().set_server_args())."
+                )
+            if count < baseline:
+                self.fail(
+                    f"{name} call-sites shrank: {count} < baseline {baseline}. "
+                    "Lower the baseline in this file to lock in the progress."
+                )
+
+
+if __name__ == "__main__":
+    unittest.main()