From fe79822e1fa03b94c817176ac78dd54c372d8615 Mon Sep 17 00:00:00 2001 From: Sanghun Lee Date: Mon, 17 Aug 2026 11:33:07 +0900 Subject: [PATCH 1/4] gh-149083: Document that dataclasses.MISSING and KW_ONLY are sentinels Link both to the sentinel builtin and note the 3.15 change. Co-Authored-By: Claude Opus 5 (1M context) --- Doc/library/dataclasses.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst index ce59d89843e761d..af29b0e45a5e8c2 100644 --- a/Doc/library/dataclasses.rst +++ b/Doc/library/dataclasses.rst @@ -262,8 +262,8 @@ Module contents c = C() c.mylist += [1, 2, 3] - As shown above, the :const:`MISSING` value is a sentinel object used to - detect if some parameters are provided by the user. This sentinel is + As shown above, the :const:`MISSING` value is a :class:`sentinel` object + used to detect if some parameters are provided by the user. This sentinel is used because ``None`` is a valid value for some parameters with a distinct meaning. No code should directly use the :const:`MISSING` value. @@ -528,11 +528,15 @@ Module contents .. data:: MISSING - A sentinel value signifying a missing default or default_factory. + A :class:`sentinel` object signifying a missing default or default_factory. + + .. versionchanged:: 3.15 + :const:`!MISSING` is now a :class:`sentinel` object. In earlier versions + it was an instance of a private class and had a different :func:`repr`. .. data:: KW_ONLY - A sentinel value used as a type annotation. Any fields after a + A :class:`sentinel` object used as a type annotation. Any fields after a pseudo-field with the type of :const:`!KW_ONLY` are marked as keyword-only fields. Note that a pseudo-field of type :const:`!KW_ONLY` is otherwise completely ignored. This includes the @@ -557,6 +561,10 @@ Module contents .. versionadded:: 3.10 + .. versionchanged:: 3.15 + :const:`!KW_ONLY` is now a :class:`sentinel` object. In earlier versions + it was an instance of a private class and had a different :func:`repr`. + .. exception:: FrozenInstanceError Raised when an implicitly defined :meth:`~object.__setattr__` or From fbf26cd192a7a6dd045fda1ea1e028a44657755c Mon Sep 17 00:00:00 2001 From: Sanghun Lee Date: Mon, 17 Aug 2026 12:02:28 +0900 Subject: [PATCH 2/4] Drop the repr mention from the sentinel versionchanged notes The old repr is not stated, so "had a different repr" is not actionable, and the sentinel docs already describe how a sentinel reprs itself. Co-Authored-By: Claude Opus 5 (1M context) --- Doc/library/dataclasses.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst index af29b0e45a5e8c2..a3f0c674313de12 100644 --- a/Doc/library/dataclasses.rst +++ b/Doc/library/dataclasses.rst @@ -532,7 +532,7 @@ Module contents .. versionchanged:: 3.15 :const:`!MISSING` is now a :class:`sentinel` object. In earlier versions - it was an instance of a private class and had a different :func:`repr`. + it was an instance of a private class. .. data:: KW_ONLY @@ -563,7 +563,7 @@ Module contents .. versionchanged:: 3.15 :const:`!KW_ONLY` is now a :class:`sentinel` object. In earlier versions - it was an instance of a private class and had a different :func:`repr`. + it was an instance of a private class. .. exception:: FrozenInstanceError From 213db8550e3ced958b18afccdf0af0bfc72b75db Mon Sep 17 00:00:00 2001 From: Sanghun Lee Date: Mon, 17 Aug 2026 12:08:32 +0900 Subject: [PATCH 3/4] Simplify the sentinel versionchanged notes --- Doc/library/dataclasses.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst index a3f0c674313de12..e4024eebff01438 100644 --- a/Doc/library/dataclasses.rst +++ b/Doc/library/dataclasses.rst @@ -531,8 +531,7 @@ Module contents A :class:`sentinel` object signifying a missing default or default_factory. .. versionchanged:: 3.15 - :const:`!MISSING` is now a :class:`sentinel` object. In earlier versions - it was an instance of a private class. + :const:`!MISSING` is now a :class:`sentinel` object. .. data:: KW_ONLY @@ -562,8 +561,7 @@ Module contents .. versionadded:: 3.10 .. versionchanged:: 3.15 - :const:`!KW_ONLY` is now a :class:`sentinel` object. In earlier versions - it was an instance of a private class. + :const:`!KW_ONLY` is now a :class:`sentinel` object. .. exception:: FrozenInstanceError From 69cff04b327bb3896999586b20be42a9ec1ce183 Mon Sep 17 00:00:00 2001 From: Sanghun Lee Date: Mon, 17 Aug 2026 12:42:28 +0900 Subject: [PATCH 4/4] Mark up default_factory as a parameter --- Doc/library/dataclasses.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/dataclasses.rst b/Doc/library/dataclasses.rst index e4024eebff01438..9f4871a55bc8af3 100644 --- a/Doc/library/dataclasses.rst +++ b/Doc/library/dataclasses.rst @@ -528,7 +528,7 @@ Module contents .. data:: MISSING - A :class:`sentinel` object signifying a missing default or default_factory. + A :class:`sentinel` object signifying a missing default or *default_factory*. .. versionchanged:: 3.15 :const:`!MISSING` is now a :class:`sentinel` object.