Document Python runtime pinning helpers

Co-authored-by: Codex <noreply@openai.com>

sdk/python/_runtime_setup.py

@@ -27,6 +27,7 @@ class RuntimeSetupError(RuntimeError):
 
 
 def pinned_runtime_version() -> str:
+    """Return the exact runtime version pinned by the SDK package dependency."""
     source_pin = _source_tree_runtime_dependency_version()
     if source_pin is not None:
         return _normalized_package_version(source_pin)
@@ -405,6 +406,7 @@ def _release_tag(version: str) -> str:
 
 
 def _source_tree_runtime_dependency_version() -> str | None:
+    """Read the runtime dependency pin when the SDK is running from a checkout."""
     pyproject_path = Path(__file__).resolve().parent / "pyproject.toml"
     if not pyproject_path.exists():
         return None
@@ -416,6 +418,7 @@ def _source_tree_runtime_dependency_version() -> str | None:
 
 
 def _installed_sdk_runtime_dependency_version() -> str | None:
+    """Read the runtime dependency pin from installed package metadata."""
     requirements = importlib.metadata.requires(SDK_PACKAGE_NAME) or []
     for requirement in requirements:
         match = re.search(_runtime_dependency_pin_pattern(), requirement)
@@ -425,6 +428,7 @@ def _installed_sdk_runtime_dependency_version() -> str | None:
 
 
 def _runtime_dependency_pin_pattern() -> str:
+    """Match the exact runtime dependency pin in TOML and wheel metadata."""
     return rf'{re.escape(PACKAGE_NAME)}\s*==\s*"?([^",;\s]+)"?'
 
 

sdk/python/tests/test_artifact_workflow_and_binaries.py

@@ -163,6 +163,7 @@ def test_runtime_package_template_has_no_checked_in_binaries() -> None:
 
 
 def test_examples_readme_points_to_runtime_version_source_of_truth() -> None:
+    """Document that examples should point at the dependency pin, not release lore."""
     readme = (ROOT / "examples" / "README.md").read_text()
     assert "The pinned runtime version comes from the SDK package dependency." in readme
 
@@ -212,6 +213,7 @@ def test_release_metadata_retries_without_invalid_auth(
 
 
 def test_source_sdk_package_pins_published_runtime() -> None:
+    """The source package metadata should pin the runtime wheel that ships schemas."""
     pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())
 
     assert {
@@ -227,6 +229,7 @@ def test_source_sdk_package_pins_published_runtime() -> None:
 
 
 def test_runtime_setup_uses_pep440_package_version_and_codex_release_tags() -> None:
+    """The SDK uses PEP 440 package pins and converts only when fetching releases."""
     runtime_setup = _load_runtime_setup_module()
     pyproject = tomllib.loads((ROOT / "pyproject.toml").read_text())