Make NG APIs official (#786)

Author: hynek

changelog.d/668.change.rst

@@ -0,0 +1,5 @@
+The instant favorite `next-generation APIs <https://www.attrs.org/en/stable/api.html#next-gen>`_ are not provisional anymore!
+
+They are also officially supported by Mypy as of their `0.800 release <https://mypy-lang.blogspot.com/2021/01/mypy-0800-released.html>`_.
+
+We hope the next release will already contain an (additional) importable package called ``attrs``.

changelog.d/786.change.rst

@@ -0,0 +1,5 @@
+The instant favorite `next-generation APIs <https://www.attrs.org/en/stable/api.html#next-gen>`_ are not provisional anymore!
+
+They are also officially supported by Mypy as of their `0.800 release <https://mypy-lang.blogspot.com/2021/01/mypy-0800-released.html>`_.
+
+We hope the next release will already contain an (additional) importable package called ``attrs``.

docs/api.rst

@@ -17,10 +17,14 @@ Core
 ----
 
 
-.. warning::
-   As of ``attrs`` 20.1.0, it also ships with a bunch of provisional APIs that are intended to become the main way of defining classes in the future.
+.. note::
+
+   ``attrs`` 20.1.0 added a bunch of nicer APIs (sometimes referred to as next generation -- or NG -- APIs) that were intended to become the main way of defining classes in the future.
+   As of 21.1.0, they are not provisional anymore and are the **recommended** way to use ``attrs``!
+   The next step will be adding an importable ``attrs`` namespace.
+   The documentation will be updated successively.
 
-   Please have a look at :ref:`prov`.
+   Please have a look at :ref:`next-gen`!
 
 .. autodata:: attr.NOTHING
 
@@ -578,12 +582,12 @@ These are helpers that you can use together with `attr.s`'s and `attr.ib`'s ``on
    N.B. Please use `attr.s`'s *frozen* argument to freeze whole classes; it is more efficient.
 
 
-.. _prov:
+.. _next-gen:
 
-Provisional APIs
-----------------
+Next Generation APIs
+--------------------
 
-These are Python 3.6 and later-only, keyword-only, and **provisional** APIs that call `attr.s` with different default values.
+These are Python 3.6 and later-only, and keyword-only APIs that call `attr.s` with different default values.
 
 The most notable differences are:
 
@@ -597,14 +601,9 @@ The most notable differences are:
 
 Please note that these are *defaults* and you're free to override them, just like before.
 
-----
-
-Their behavior is scheduled to become part of the upcoming ``import attrs`` that will introduce a new namespace  with nicer names and nicer defaults (see  `#408 <https://github.com/python-attrs/attrs/issues/408>`_ and `#487 <https://github.com/python-attrs/attrs/issues/487>`_).
-
-Therefore your constructive feedback in the linked issues above is strongly encouraged!
+Since the Python ecosystem has settled on the term ``field`` for defining attributes, we have also added `attr.field` as a substitute for `attr.ib`.
 
 .. note::
-   Provisional doesn't mean we will remove it (although it will be deprecated once the final form is released), but that it might change if we receive relevant feedback.
 
    `attr.s` and `attr.ib` (and their serious business cousins) aren't going anywhere.
    The new APIs build on top of them.

docs/comparison.rst

@@ -42,5 +42,5 @@ It is then used as a key function like you may know from `sorted`:
 This is especially useful when you have fields with objects that have atypical comparison properties.
 Common examples of such objects are `NumPy arrays <https://github.com/python-attrs/attrs/issues/435>`_.
 
-Please note that *eq* and *order* are set *independently*, because *order* is `False` by default in `modern APIs <prov>`.
+Please note that *eq* and *order* are set *independently*, because *order* is `False` by default in `modern APIs <next-gen>`.
 You can set both at once by using the *cmp* argument that we've undeprecated just for this use-case.

src/attr/_next_gen.py

@@ -1,8 +1,6 @@
 """
-This is a Python 3.6 and later-only, keyword-only, and **provisional** API that
-calls `attr.s` with different default values.
-
-Provisional APIs that shall become "import attrs" one glorious day.
+These are Python 3.6+-only and keyword-only APIs that call `attr.s` and
+`attr.ib` with different default values.
 """
 
 from functools import partial