From 608814971c605c8905f1c28eff3c66ef4d94350b Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Tue, 6 Apr 2021 08:06:59 +0200 Subject: [PATCH 1/3] Make NG APIs official Fixes #668 Signed-off-by: Hynek Schlawack --- changelog.d/668.change.rst | 5 +++++ docs/api.rst | 25 ++++++++++++------------- src/attr/_next_gen.py | 6 ++---- 3 files changed, 19 insertions(+), 17 deletions(-) create mode 100644 changelog.d/668.change.rst diff --git a/changelog.d/668.change.rst b/changelog.d/668.change.rst new file mode 100644 index 000000000..9f97a30f0 --- /dev/null +++ b/changelog.d/668.change.rst @@ -0,0 +1,5 @@ +The instant favorite `next-generation APIs `_ are not provisional anymore! + +They are also officially supported by Mypy as of their `0.800 release `_. + +We hope the next release will already contain an (additional) importable package called ``attrs``. diff --git a/docs/api.rst b/docs/api.rst index cfda7ba0d..0a3700482 100644 --- a/docs/api.rst +++ b/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 `_ and `#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. diff --git a/src/attr/_next_gen.py b/src/attr/_next_gen.py index 2990ad257..fab0af966 100644 --- a/src/attr/_next_gen.py +++ b/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 From 8315bba30f9d4fed8718e2cd6a34adae40e3f56d Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Tue, 6 Apr 2021 09:04:49 +0200 Subject: [PATCH 2/3] Fix link --- docs/comparison.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/comparison.rst b/docs/comparison.rst index 4c1beeeb0..307796fb0 100644 --- a/docs/comparison.rst +++ b/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 `_. -Please note that *eq* and *order* are set *independently*, because *order* is `False` by default in `modern APIs `. +Please note that *eq* and *order* are set *independently*, because *order* is `False` by default in `modern APIs `. You can set both at once by using the *cmp* argument that we've undeprecated just for this use-case. From 1f364affa8e4e40275dd9fad6622d96c6d97c545 Mon Sep 17 00:00:00 2001 From: Hynek Schlawack Date: Tue, 6 Apr 2021 13:18:49 +0200 Subject: [PATCH 3/3] Also link to PR Signed-off-by: Hynek Schlawack --- changelog.d/786.change.rst | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 changelog.d/786.change.rst diff --git a/changelog.d/786.change.rst b/changelog.d/786.change.rst new file mode 100644 index 000000000..9f97a30f0 --- /dev/null +++ b/changelog.d/786.change.rst @@ -0,0 +1,5 @@ +The instant favorite `next-generation APIs `_ are not provisional anymore! + +They are also officially supported by Mypy as of their `0.800 release `_. + +We hope the next release will already contain an (additional) importable package called ``attrs``.