Add What's New for dataclass keyword-only parameters. (GH-28158)

ericvsmith · web-flow · commit a1ba3597d2d2 · 2021-09-04T14:58:17.000-04:00
diff --git a/Doc/whatsnew/3.10.rst b/Doc/whatsnew/3.10.rst
@@ -983,9 +983,68 @@ they are provided by the underlying curses library.
 dataclasses
 -----------
 
-Add ``slots`` parameter in :func:`dataclasses.dataclass` decorator.
+__slots__
+~~~~~~~~~
+
+Added ``slots`` parameter in :func:`dataclasses.dataclass` decorator.
 (Contributed by Yurii Karabas in :issue:`42269`)
 
+Keyword-only fields
+~~~~~~~~~~~~~~~~~~~
+
+dataclassses now supports fields that are keyword-only in the
+generated __init__ method.  There are a number of ways of specifying
+keyword-only fields.
+
+You can say that every field is keyword-only:
+
+.. code-block:: python
+
+    from dataclasses import dataclass
+
+    @dataclass(kw_only=True)
+    class Birthday:
+        name: str
+        birthday: datetime.date
+
+Both ``name`` and ``birthday`` are keyword-only parameters to the
+generated __init__ method.
+
+You can specify keyword-only on a per-field basis:
+
+.. code-block:: python
+
+    from dataclasses import dataclass
+
+    @dataclass
+    class Birthday:
+        name: str
+        birthday: datetime.date = field(kw_only=True)
+
+Here only ``birthday`` is keyword-only.  If you set ``kw_only`` on
+individual fields, be aware that there are rules about re-ordering
+fields due to keyword-only fields needing to follow non-keyword-only
+fields.  See the full dataclasses documentation for details.
+
+You can also specify that all fields following a KW_ONLY marker are
+keyword-only.  This will probably be the most common usage:
+
+.. code-block:: python
+
+    from dataclasses import dataclass, KW_ONLY
+
+    @dataclass
+    class Point:
+        x: float
+        y: float
+        _: KW_ONLY
+        z: float = 0.0
+        t: float = 0.0
+
+Here, ``z`` and ``t`` are keyword-only parameters, while ``x`` and
+``y`` are not.
+(Contributed by Eric V. Smith in :issue:`43532`)
+
 .. _distutils-deprecated:
 
 distutils
