Add _typeshed.sentinel (#10582)

stdlib/_typeshed/__init__.pyi

@@ -36,6 +36,19 @@ Incomplete: TypeAlias = Any
 # To describe a function parameter that is unused and will work with anything.
 Unused: TypeAlias = object
 
+# Used to mark arguments that default to a sentinel value. This prevents
+# stubtest from complaining about the default value not matching.
+#
+# def foo(x: int | None = sentinel) -> None: ...
+#
+# In cases where the sentinel object is exported and can be used by user code,
+# a construct like this is better:
+#
+# _SentinelType = NewType("_SentinelType", object)
+# sentinel: _SentinelType
+# def foo(x: int | None | _SentinelType = ...) -> None: ...
+sentinel = Any  # noqa: Y026
+
 # stable
 class IdentityFunction(Protocol):
     def __call__(self, __x: _T) -> _T: ...

stdlib/argparse.pyi

@@ -1,4 +1,5 @@
 import sys
+from _typeshed import sentinel
 from collections.abc import Callable, Generator, Iterable, Sequence
 from re import Pattern
 from typing import IO, Any, Generic, NewType, NoReturn, Protocol, TypeVar, overload
@@ -334,7 +335,21 @@ class Action(_AttributeHolder):
     if sys.version_info >= (3, 9):
         def format_usage(self) -> str: ...
 
-if sys.version_info >= (3, 9):
+if sys.version_info >= (3, 12):
+    class BooleanOptionalAction(Action):
+        def __init__(
+            self,
+            option_strings: Sequence[str],
+            dest: str,
+            default: _T | str | None = None,
+            type: Callable[[str], _T] | FileType | None = sentinel,  # noqa: Y011
+            choices: Iterable[_T] | None = sentinel,  # noqa: Y011
+            required: bool = False,
+            help: str | None = None,
+            metavar: str | tuple[str, ...] | None = sentinel,  # noqa: Y011
+        ) -> None: ...
+
+elif sys.version_info >= (3, 9):
     class BooleanOptionalAction(Action):
         def __init__(
             self,