Merge branch 'main' into mypy_3_10

python-attrs · Jun 14, 2021 · fcbe0ce · fcbe0ce
2 parents a8a5e5c + 7cc3121
commit fcbe0ce
Show file tree

Hide file tree

Showing 52 changed files with 689 additions and 226 deletions.
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -13,12 +13,12 @@ jobs:
     name: "Python ${{ matrix.python-version }}"
     runs-on: "ubuntu-latest"
     env:
-      USING_COVERAGE: "2.7,3.7,3.8"
+      USING_COVERAGE: "2.7,3.7,3.8,3.10.0-beta - 3.10"
 
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10.0-alpha - 3.10", "pypy2", "pypy3"]
+        python-version: ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10.0-beta - 3.10", "pypy2", "pypy3"]
 
     steps:
       - uses: "actions/checkout@v2"
@@ -40,7 +40,7 @@ jobs:
       # parsing errors in older versions for modern code.
       - uses: "actions/setup-python@v2"
         with:
-          python-version: "3.9"
+          python-version: "3.10.0-beta - 3.10"
 
       - name: "Combine coverage"
         run: |

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,34 +1,39 @@
 ---
 repos:
   - repo: https://github.com/psf/black
-    rev: 20.8b1
+    rev: 21.5b2
     hooks:
       - id: black
+        exclude: tests/test_pattern_matching.py
         language_version: python3.8
 
   - repo: https://github.com/PyCQA/isort
-    rev: 5.7.0
+    rev: 5.8.0
     hooks:
       - id: isort
         additional_dependencies: [toml]
+        files: \.py$
+        language_version: python3.10
 
   - repo: https://gitlab.com/pycqa/flake8
-    rev: 3.8.4
+    rev: 3.9.2
     hooks:
       - id: flake8
-        language_version: python3.8
+        language_version: python3.10
 
   - repo: https://github.com/econchick/interrogate
-    rev: 1.3.2
+    rev: 1.4.0
     hooks:
       - id: interrogate
+        exclude: tests/test_pattern_matching.py
         args: [tests]
-        language_version: python3.8
+        language_version: python3.10
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v3.4.0
+    rev: v4.0.1
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: debug-statements
+        language_version: python3.10
       - id: check-toml
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -15,6 +15,103 @@ Changes for the upcoming release can be found in the `"changelog.d" directory <h
 
 .. towncrier release notes start
 
+21.2.0 (2021-05-07)
+-------------------
+
+Backward-incompatible Changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- We had to revert the recursive feature for ``attr.evolve()`` because it broke some use-cases -- sorry!
+  `#806 <https://github.com/python-attrs/attrs/issues/806>`_
+- Python 3.4 is now blocked using packaging metadata because ``attrs`` can't be imported on it anymore.
+  To ensure that 3.4 users can keep installing  ``attrs`` easily, we will `yank <https://pypi.org/help/#yanked>`_ 21.1.0 from PyPI.
+  This has **no** consequences if you pin ``attrs`` to 21.1.0.
+  `#807 <https://github.com/python-attrs/attrs/issues/807>`_
+
+
+----
+
+
+21.1.0 (2021-05-06)
+-------------------
+
+Deprecations
+^^^^^^^^^^^^
+
+- The long-awaited, much-talked-about, little-delivered ``import attrs`` is finally upon us!
+
+  Since the NG APIs have now been proclaimed stable, the **next** release of ``attrs`` will allow you to actually ``import attrs``.
+  We're taking this opportunity to replace some defaults in our APIs that made sense in 2015, but don't in 2021.
+
+  So please, if you have any pet peeves about defaults in ``attrs``'s APIs, *now* is the time to air your grievances in #487!
+  We're not gonna get such a chance for a second time, without breaking our backward-compatibility guarantees, or long deprecation cycles.
+  Therefore, speak now or forever hold you peace!
+  `#487 <https://github.com/python-attrs/attrs/issues/487>`_
+- The *cmp* argument to ``attr.s()`` and `attr.ib()` has been **undeprecated**
+  It will continue to be supported as syntactic sugar to set *eq* and *order* in one go.
+
+  I'm terribly sorry for the hassle around this argument!
+  The reason we're bringing it back is it's usefulness regarding customization of equality/ordering.
+
+  The ``cmp`` attribute and argument on ``attr.Attribute`` remains deprecated and will be removed later this year.
+  `#773 <https://github.com/python-attrs/attrs/issues/773>`_
+
+
+Changes
+^^^^^^^
+
+- It's now possible to customize the behavior of ``eq`` and ``order`` by passing in a callable.
+  `#435 <https://github.com/python-attrs/attrs/issues/435>`_,
+  `#627 <https://github.com/python-attrs/attrs/issues/627>`_
+- 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``.
+  `#668 <https://github.com/python-attrs/attrs/issues/668>`_,
+  `#786 <https://github.com/python-attrs/attrs/issues/786>`_
+- If an attribute defines a converter, the type of its parameter is used as type annotation for its corresponding ``__init__`` parameter.
+
+  If an ``attr.converters.pipe`` is used, the first one's is used.
+  `#710 <https://github.com/python-attrs/attrs/issues/710>`_
+- Fixed the creation of an extra slot for an ``attr.ib`` when the parent class already has a slot with the same name.
+  `#718 <https://github.com/python-attrs/attrs/issues/718>`_
+- ``__attrs__init__()`` will now be injected if ``init=False``, or if ``auto_detect=True`` and a user-defined ``__init__()`` exists.
+
+  This enables users to do "pre-init" work in their ``__init__()`` (such as ``super().__init__()``).
+
+  ``__init__()`` can then delegate constructor argument processing to ``self.__attrs_init__(*args, **kwargs)``.
+  `#731 <https://github.com/python-attrs/attrs/issues/731>`_
+- ``bool(attr.NOTHING)`` is now ``False``.
+  `#732 <https://github.com/python-attrs/attrs/issues/732>`_
+- It's now possible to use ``super()`` inside of properties of slotted classes.
+  `#747 <https://github.com/python-attrs/attrs/issues/747>`_
+- Allow for a ``__attrs_pre_init__()`` method that -- if defined -- will get called at the beginning of the ``attrs``-generated ``__init__()`` method.
+  `#750 <https://github.com/python-attrs/attrs/issues/750>`_
+- Added forgotten ``attr.Attribute.evolve()`` to type stubs.
+  `#752 <https://github.com/python-attrs/attrs/issues/752>`_
+- ``attrs.evolve()`` now works recursively with nested ``attrs`` classes.
+  `#759 <https://github.com/python-attrs/attrs/issues/759>`_
+- Python 3.10 is now officially supported.
+  `#763 <https://github.com/python-attrs/attrs/issues/763>`_
+- ``attr.resolve_types()`` now takes an optional *attrib* argument to work inside a ``field_transformer``.
+  `#774 <https://github.com/python-attrs/attrs/issues/774>`_
+- ``ClassVar``\ s are now also detected if they come from `typing-extensions <https://pypi.org/project/typing-extensions/>`_.
+  `#782 <https://github.com/python-attrs/attrs/issues/782>`_
+- To make it easier to customize attribute comparison (#435), we have added the ``attr.cmp_with()`` helper.
+
+  See the `new docs on comparison <https://www.attrs.org/en/stable/comparison.html>`_ for more details.
+  `#787 <https://github.com/python-attrs/attrs/issues/787>`_
+- Added **provisional** support for static typing in ``pyright`` via the `dataclass_transforms specification <https://github.com/microsoft/pyright/blob/master/specs/dataclass_transforms.md>`_.
+  Both the ``pyright`` specification and ``attrs`` implementation may change in future versions of both projects.
+
+  Your constructive feedback is welcome in both `attrs#795 <https://github.com/python-attrs/attrs/issues/795>`_ and `pyright#1782 <https://github.com/microsoft/pyright/discussions/1782>`_.
+  `#796 <https://github.com/python-attrs/attrs/issues/796>`_
+
+
+----
+
+
 20.3.0 (2020-11-05)
 -------------------
 

diff --git a/README.rst b/README.rst
@@ -7,16 +7,16 @@
    </p>
    <p align="center">
       <a href="https://www.attrs.org/en/stable/?badge=stable">
-          <img src="https://readthedocs.org/projects/attrs/badge/?version=stable" alt="Documentation Status" />
+          <img src="https://img.shields.io/badge/Docs-Read%20The%20Docs-black" alt="Documentation" />
       </a>
-      <a href="https://github.com/python-attrs/attrs/actions?workflow=CI">
-          <img src="https://github.com/python-attrs/attrs/workflows/CI/badge.svg?branch=main" alt="CI Status" />
+      <a href="https://github.com/python-attrs/attrs/blob/main/LICENSE">
+         <img src="https://img.shields.io/badge/license-MIT-C06524" alt="License: MIT" />
       </a>
-      <a href="https://codecov.io/github/python-attrs/attrs">
-          <img src="https://codecov.io/github/python-attrs/attrs/branch/main/graph/badge.svg" alt="Test Coverage" />
+      <a href="https://pypi.org/project/attrs/">
+         <img src="https://img.shields.io/pypi/v/attrs" />
       </a>
-      <a href="https://github.com/psf/black">
-          <img src="https://img.shields.io/badge/code%20style-black-000000.svg" alt="Code style: black" />
+      <a href="https://pepy.tech/project/attrs">
+         <img src="https://static.pepy.tech/personalized-badge/attrs?period=month&units=international_system&left_color=grey&right_color=blue&left_text=Downloads%20/%20Month" alt="Downloads per month" />
       </a>
    </p>
 

diff --git a/changelog.d/435.change.rst b/changelog.d/435.change.rst
diff --git a/changelog.d/487.deprecation.rst b/changelog.d/487.deprecation.rst
diff --git a/changelog.d/627.change.rst b/changelog.d/627.change.rst
diff --git a/changelog.d/668.change.rst b/changelog.d/668.change.rst
diff --git a/changelog.d/710.change.rst b/changelog.d/710.change.rst
diff --git a/changelog.d/718.change.rst b/changelog.d/718.change.rst
diff --git a/changelog.d/731.change.rst b/changelog.d/731.change.rst
diff --git a/changelog.d/732.change.rst b/changelog.d/732.change.rst
diff --git a/changelog.d/747.change.rst b/changelog.d/747.change.rst
diff --git a/changelog.d/750.change.rst b/changelog.d/750.change.rst
diff --git a/changelog.d/752.change.rst b/changelog.d/752.change.rst
diff --git a/changelog.d/759.change.rst b/changelog.d/759.change.rst
diff --git a/changelog.d/763.change.rst b/changelog.d/763.change.rst
diff --git a/changelog.d/773.deprecation.rst b/changelog.d/773.deprecation.rst
diff --git a/changelog.d/774.change.rst b/changelog.d/774.change.rst
diff --git a/changelog.d/782.change.rst b/changelog.d/782.change.rst
diff --git a/changelog.d/786.change.rst b/changelog.d/786.change.rst
diff --git a/changelog.d/787.change.rst b/changelog.d/787.change.rst
diff --git a/changelog.d/796.change.rst b/changelog.d/796.change.rst
diff --git a/changelog.d/815.changes.rst b/changelog.d/815.changes.rst
@@ -0,0 +1,4 @@
+``__match_args__`` are now generated to support Python 3.10's
+`Structural Pattern Matching <https://docs.python.org/3.10/whatsnew/3.10.html#pep-634-structural-pattern-matching>`_.
+This can be controlled by the ``match_args`` argument to the class decorators on Python 3.10 and later.
+On older versions, it is never added and the argument is ignored.
diff --git a/changelog.d/817.change.rst b/changelog.d/817.change.rst
@@ -0,0 +1 @@
+If the class-level *on_setattr* is set to ``attr.setters.validate`` (default in ``@attr.define`` and ``@attr.mutable``) but no field defines a validator, pretend that it's not set.
diff --git a/changelog.d/819.changes.rst b/changelog.d/819.changes.rst
@@ -0,0 +1 @@
+The generated ``__repr__`` is significantly faster on Pythons with F-strings.
diff --git a/conftest.py b/conftest.py
@@ -4,6 +4,8 @@
 
 from hypothesis import HealthCheck, settings
 
+from attr._compat import PY310
+
 
 def pytest_configure(config):
     # HealthCheck.too_slow causes more trouble than good -- especially in CIs.
@@ -23,3 +25,11 @@ def pytest_configure(config):
             "tests/test_next_gen.py",
         ]
     )
+if not PY310:
+    collect_ignore.extend(["tests/test_pattern_matching.py"])
+if PY310:
+    collect_ignore.extend(
+        [
+            "tests/test_mypy.yml",
+        ]
+    )
diff --git a/docs/api.rst b/docs/api.rst
@@ -28,7 +28,7 @@ Core
 
 .. autodata:: attr.NOTHING
 
-.. autofunction:: attr.s(these=None, repr_ns=None, repr=None, cmp=None, hash=None, init=None, slots=False, frozen=False, weakref_slot=True, str=False, auto_attribs=False, kw_only=False, cache_hash=False, auto_exc=False, eq=None, order=None, auto_detect=False, collect_by_mro=False, getstate_setstate=None, on_setattr=None, field_transformer=None)
+.. autofunction:: attr.s(these=None, repr_ns=None, repr=None, cmp=None, hash=None, init=None, slots=False, frozen=False, weakref_slot=True, str=False, auto_attribs=False, kw_only=False, cache_hash=False, auto_exc=False, eq=None, order=None, auto_detect=False, collect_by_mro=False, getstate_setstate=None, on_setattr=None, field_transformer=None, match_args=True)
 
    .. note::
 

diff --git a/docs/examples.rst b/docs/examples.rst
@@ -618,27 +618,6 @@ In Clojure that function is called `assoc <https://clojuredocs.org/clojure.core/
    >>> i1 == i2
    False
 
-This functions also works for nested ``attrs`` classes.
-Pass a (possibly nested) dictionary with changes for an attribute:
-
-.. doctest::
-
-   >>> @attr.s(frozen=True)
-   ... class Child(object):
-   ...     x = attr.ib()
-   ...     y = attr.ib()
-   >>> @attr.s(frozen=True)
-   ... class Parent(object):
-   ...     child = attr.ib()
-   >>> i1 = Parent(Child(1, 2))
-   >>> i1
-   Parent(child=Child(x=1, y=2))
-   >>> i2 = attr.evolve(i1, child={"y": 3})
-   >>> i2
-   Parent(child=Child(x=1, y=3))
-   >>> i1 == i2, i1.child == i2.child
-   (False, False)
-
 
 Other Goodies
 -------------

diff --git a/docs/extending.rst b/docs/extending.rst
@@ -47,7 +47,7 @@ An example for that is the package `environ-config <https://github.com/hynek/env
 Another common use case is to overwrite ``attrs``'s defaults.
 
 Mypy
-************
+^^^^
 
 Unfortunately, decorator wrapping currently `confuses <https://github.com/python/mypy/issues/5406>`_ mypy's ``attrs`` plugin.
 At the moment, the best workaround is to hold your nose, write a fake mypy plugin, and mutate a bunch of global variables::
@@ -90,9 +90,9 @@ Then tell mypy about your plugin using your project's ``mypy.ini``:
    You can only use this trick to tell mypy that a class is actually an ``attrs`` class.
 
 Pyright
-*************
+^^^^^^^
 
-Generic decorator wrapping is supported in ``pyright`` via the provisional dataclass_transform_ specification.
+Generic decorator wrapping is supported in `pyright <https://github.com/microsoft/pyright>`_ via their dataclass_transform_ specification.
 
 For a custom wrapping of the form::
 
@@ -112,11 +112,12 @@ This is implemented via a ``__dataclass_transform__`` type decorator in the cust
     @__dataclass_transform__(field_descriptors=(attr.attrib, attr.field))
     def custom_define(f): ...
 
-.. note::
+.. warning::
+
+   ``dataclass_transform`` is supported **provisionally** as of ``pyright`` 1.1.135.
 
-   ``dataclass_transform`` is supported provisionally as of ``pyright`` 1.1.135.
+   Both the ``pyright`` dataclass_transform_ specification and ``attrs`` implementation may change in future versions.
 
-   Both the ``pyright`` dataclass_transform_ specification and ``attrs`` implementation may changed in future versions.
 
 Types
 -----
@@ -306,4 +307,4 @@ It has the signature
 
 *****
 
-.. _dataclass_transform: https://github.com/microsoft/pyright/blob/1.1.135/specs/dataclass_transforms.md
+.. _dataclass_transform: https://github.com/microsoft/pyright/blob/master/specs/dataclass_transforms.md