[SPARK-46107][PYTHON][ML] Deprecate pyspark.keyword_only API

python/docs/source/conf.py

@@ -176,7 +176,6 @@
 # -- Options for autodoc --------------------------------------------------
 
 # Look at the first line of the docstring for function and method signatures.
-autodoc_docstring_signature = True
 autosummary_generate = True
 
 # -- Options for HTML output ----------------------------------------------

python/pyspark/__init__.py

@@ -45,7 +45,7 @@
   - :class:`InheritableThread`:
       A inheritable thread to use in Spark when the pinned thread mode is on.
 """
-
+import warnings
 from functools import wraps
 import types
 from typing import cast, Any, Callable, Optional, TypeVar, Union
@@ -76,7 +76,9 @@ def since(version: Union[str, float]) -> Callable[[_F], _F]:
     indent_p = re.compile(r"\n( +)")
 
     def deco(f: _F) -> _F:
-        assert f.__doc__ is not None
+        if f.__doc__ is None:
+            # Should still at least add a versionadded.
+            f.__doc__ = ""
 
         indents = indent_p.findall(f.__doc__)
         indent = " " * (min(len(m) for m in indents) if indents else 0)
@@ -121,10 +123,19 @@ def keyword_only(func: _F) -> _F:
     A decorator that forces keyword arguments in the wrapped method
     and saves actual input keyword arguments in `_input_kwargs`.
 
+    .. deprecated:: 4.0.0
+        `keyword_only` method is deprecated. Use the standard
+         keyword-only syntax in Python instead.
+
     Notes
     -----
     Should only be used to wrap a method where first arg is `self`
     """
+    warnings.warn(
+        "keyword_only method is deprecated. Use the standard keyword-only"
+        "syntax in Python instead.",
+        FutureWarning,
+    )
 
     @wraps(func)
     def wrapper(self: Any, *args: Any, **kwargs: Any) -> Any: