Explore deprecating create arg of get_command_obj and get_finalized_command

Author: Avasam

distutils/cmd.py

@@ -22,9 +22,14 @@
     # type-only import because of mutual dependence between these classes
     from distutils.dist import Distribution
 
-    from typing_extensions import TypeVarTuple, Unpack
+    from typing_extensions import TypeVarTuple, Unpack, deprecated
 
     _Ts = TypeVarTuple("_Ts")
+else:
+
+    def deprecated(message):
+        return lambda fn: fn
+
 
 _StrPathT = TypeVar("_StrPathT", bound="str | os.PathLike[str]")
 _BytesPathT = TypeVar("_BytesPathT", bound="bytes | os.PathLike[bytes]")
@@ -322,11 +327,18 @@ def set_undefined_options(
             if getattr(self, dst_option) is None:
                 setattr(self, dst_option, getattr(src_cmd_obj, src_option))
 
+    @overload
+    def get_finalized_command(self, command: str, create: None = None) -> Command: ...
+    @deprecated("The 'create' argument is deprecated and doesn't do anything.")
+    @overload
+    def get_finalized_command(self, command: str, create: bool) -> Command: ...
     # NOTE: Because distutils is private to Setuptools and not all commands are exposed here,
     # not every possible command is enumerated in the signature.
-    def get_finalized_command(self, command: str, create: bool = True) -> Command:
+    def get_finalized_command(
+        self, command: str, create: bool | None = None
+    ) -> Command:
         """Wrapper around Distribution's 'get_command_obj()' method: find
-        (create if necessary and 'create' is true) the command object for
+        (create if necessary) the command object for
         'command', call its 'ensure_finalized()' method, and return the
         finalized command object.
         """

distutils/dist.py

@@ -41,11 +41,15 @@
 
 if TYPE_CHECKING:
     from _typeshed import SupportsWrite
-    from typing_extensions import TypeAlias
+    from typing_extensions import TypeAlias, deprecated
 
     # type-only import because of mutual dependence between these modules
     from .cmd import Command
     from .extension import Extension
+else:
+
+    def deprecated(message):
+        return lambda fn: fn
 
 _CommandT = TypeVar("_CommandT", bound="Command")
 _OptionsList: TypeAlias = list[
@@ -861,25 +865,27 @@ def get_command_class(self, command: str) -> type[Command]:
         raise DistutilsModuleError(f"invalid command '{command}'")
 
     @overload
-    def get_command_obj(
-        self, command: str, create: Literal[True] = True
-    ) -> Command: ...
+    def get_command_obj(self, command: str, create: None = None) -> Command: ...
+    @deprecated("The 'create' argument is deprecated and doesn't do anything.")
     @overload
-    def get_command_obj(
-        self, command: str, create: Literal[False]
-    ) -> Command | None: ...
-    def get_command_obj(self, command: str, create: bool = True) -> Command | None:
+    def get_command_obj(self, command: str, create: bool) -> Command: ...
+    def get_command_obj(self, command: str, create: object = None) -> Command | None:
         """Return the command object for 'command'.  Normally this object
         is cached on a previous call to 'get_command_obj()'; if no command
-        object for 'command' is in the cache, then we either create and
-        return it (if 'create' is true) or return None.
+        object for 'command' is in the cache, then we create and
+        return it.
         """
+        if create is not None:
+            warnings.warn(
+                "The 'create' argument is deprecated and doesn't do anything.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         cmd_obj = self.command_obj.get(command)
-        if not cmd_obj and create:
+        if not cmd_obj:
             if DEBUG:
                 self.announce(
-                    "Distribution.get_command_obj(): "
-                    f"creating '{command}' command object"
+                    f"Distribution.get_command_obj(): creating '{command}' command object"
                 )
 
             klass = self.get_command_class(command)