bpo-43532: Add kw_only to dataclass() and field(), and add KW_ONLY marker.

Doc/library/dataclasses.rst

@@ -46,7 +46,7 @@ directly specified in the ``InventoryItem`` definition shown above.
 Module-level decorators, classes, and functions
 -----------------------------------------------
 
-.. decorator:: dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True)
+.. decorator:: dataclass(*, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False)
 
    This function is a :term:`decorator` that is used to add generated
    :term:`special method`\s to classes, as described below.
@@ -79,7 +79,7 @@ Module-level decorators, classes, and functions
      class C:
          ...
 
-     @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True)
+     @dataclass(init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False)
      class C:
         ...
 
@@ -168,6 +168,10 @@ Module-level decorators, classes, and functions
      ``__match_args__`` is already defined in the class, then
      ``__match_args__`` will not be generated.
 
+   - ``kw_only``: If true (the default value is ``False``), then all
+     fields will be marked as keyword-only.  See the :term:`parameter`
+     glossary entry for details.  Also see the ``dataclasses.KW_ONLY``
+     section.
 
    ``field``\s may optionally specify a default value, using normal
    Python syntax::
@@ -333,17 +337,17 @@ Module-level decorators, classes, and functions
 
    Raises :exc:`TypeError` if ``instance`` is not a dataclass instance.
 
-.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True)
+.. function:: make_dataclass(cls_name, fields, *, bases=(), namespace=None, init=True, repr=True, eq=True, order=False, unsafe_hash=False, frozen=False, match_args=True, kw_only=False)
 
    Creates a new dataclass with name ``cls_name``, fields as defined
    in ``fields``, base classes as given in ``bases``, and initialized
    with a namespace as given in ``namespace``.  ``fields`` is an
    iterable whose elements are each either ``name``, ``(name, type)``,
    or ``(name, type, Field)``.  If just ``name`` is supplied,
    ``typing.Any`` is used for ``type``.  The values of ``init``,
-   ``repr``, ``eq``, ``order``, ``unsafe_hash``, ``frozen``, and
-   ``match_args`` have the same meaning as they do in
-   :func:`dataclass`.
+   ``repr``, ``eq``, ``order``, ``unsafe_hash``, ``frozen``,
+   ``match_args``, and ``kw_only`` have the same meaning as they do
+   in :func:`dataclass`.
 
    This function is not strictly required, because any Python
    mechanism for creating a new class with ``__annotations__`` can
@@ -520,6 +524,32 @@ The generated :meth:`__init__` method for ``C`` will look like::
 
   def __init__(self, x: int = 15, y: int = 0, z: int = 10):
 
+Re-ordering of keyword-only parameters in __init__
+--------------------------------------------------
+
+After the fields needed for :meth:`__init__` are computed, any
+keyword-only fields are put after regular fields.  In this example,
+``Base.y`` and ``D.t`` are keyword-only fields::
+
+  @dataclass
+  class Base:
+      x: Any = 15.0
+      _: KW_ONLY
+      y: int = 0
+
+  @dataclass
+  class D(Base):
+      z: int = 10
+      t: int = field(kw_only=True, default=0)
+
+The generated :meth:`__init__` method for ``D`` will look like::
+
+  def __init__(self, x: Any = 15.0, z: int = 10, *, y: int = 0, t: int = 0):
+
+The relative ordering of keyword-only arguments is not changed from
+the order they are in computed field :meth:`__init__` list.
+
+
 Default factory functions
 -------------------------