Merge branch 'main' into tin/mypy-fields

.github/CONTRIBUTING.md

@@ -30,6 +30,9 @@ The official tag is `python-attrs` and helping out in support frees us up to imp
   This is a hard rule; patches with missing tests or documentation can't be merged.
 - Make sure your changes pass our [CI].
   You won't get any feedback until it's green unless you ask for it.
+- For the CI to pass, the coverage must be 100%.
+  If you have problems to test something, open anyway and ask for advice.
+  In some situations, we may agree to add an `# pragma: no cover`.
 - Once you've addressed review feedback, make sure to bump the pull request with a short note, so we know you're done.
 - Don’t break backwards compatibility.
 
@@ -120,27 +123,27 @@ You don't need to install *towncrier* yourself, you just have to abide by a few
 - Wrap arguments into asterisks like in docstrings:
   `Added new argument *an_argument*.`
 - If you mention functions or other callables, add parentheses at the end of their names:
-  `attr.func()` or `attr.Class.method()`.
+  `attrs.func()` or `attrs.Class.method()`.
   This makes the changelog a lot more readable.
 - Prefer simple past tense or constructions with "now".
   For example:
 
-  + Added `attr.validators.func()`.
-  + `attr.func()` now doesn't crash the Large Hadron Collider anymore when passed the *foobar* argument.
+  + Added `attrs.validators.func()`.
+  + `attrs.func()` now doesn't crash the Large Hadron Collider anymore when passed the *foobar* argument.
 - If you want to reference multiple issues, copy the news fragment to another filename.
   *towncrier* will merge all news fragments with identical contents into one entry with multiple links to the respective pull requests.
 
 Example entries:
 
   ```rst
-  Added ``attr.validators.func()``.
+  Added ``attrs.validators.func()``.
   The feature really *is* awesome.
   ```
 
 or:
 
   ```rst
-  ``attr.func()`` now doesn't crash the Large Hadron Collider anymore when passed the *foobar* argument.
+  ``attrs.func()`` now doesn't crash the Large Hadron Collider anymore when passed the *foobar* argument.
   The bug really *was* nasty.
   ```
 

.github/PULL_REQUEST_TEMPLATE.md

@@ -19,13 +19,15 @@ If your pull request is a documentation fix or a trivial typo, feel free to dele
 - [ ] New features have been added to our [Hypothesis testing strategy](https://github.com/python-attrs/attrs/blob/main/tests/strategies.py).
 - [ ] Changes or additions to public APIs are reflected in our type stubs (files ending in ``.pyi``).
     - [ ] ...and used in the stub test file `tests/typing_example.py`.
+    - [ ] If they've been added to `attr/__init__.pyi`, they've *also* been re-imported in `attrs/__init__.pyi`.
 - [ ] Updated **documentation** for changed code.
     - [ ] New functions/classes have to be added to `docs/api.rst` by hand.
     - [ ] Changes to the signature of `@attr.s()` have to be added by hand too.
     - [ ] Changed/added classes/methods/functions have appropriate `versionadded`, `versionchanged`, or `deprecated` [directives](http://www.sphinx-doc.org/en/stable/markup/para.html#directive-versionadded).
           Find the appropriate next version in our [``__init__.py``](https://github.com/python-attrs/attrs/blob/main/src/attr/__init__.py) file.
 - [ ] Documentation in `.rst` files is written using [semantic newlines](https://rhodesmill.org/brandon/2012/one-sentence-per-line/).
 - [ ] Changes (and possible deprecations) have news fragments in [`changelog.d`](https://github.com/python-attrs/attrs/blob/main/changelog.d).
+- [ ] Consider granting [push permissions to the PR branch](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork), so maintainers can fix minor issues themselves without pestering you.
 
 <!--
 If you have *any* questions to *any* of the points above, just **submit and ask**!

.github/workflows/main.yml

@@ -4,31 +4,32 @@ name: CI
 on:
   push:
     branches: ["main"]
+    tags: ["*"]
   pull_request:
     branches: ["main"]
   workflow_dispatch:
 
 env:
   FORCE_COLOR: "1"  # Make tools pretty.
-  TOX_TESTENV_PASSENV: "FORCE_COLOR"
+  TOX_TESTENV_PASSENV: FORCE_COLOR
   PYTHON_LATEST: "3.10"
 
 
 jobs:
   tests:
-    name: "tox on ${{ matrix.python-version }}"
-    runs-on: "ubuntu-latest"
+    name: tox on ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
 
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10", "pypy-2.7", "pypy-3.7"]
+        python-version: ["2.7", "3.5", "3.6", "3.7", "3.8", "3.9", "3.10", "pypy-2.7", "pypy-3.7", "pypy-3.8"]
 
     steps:
-      - uses: "actions/checkout@v2"
-      - uses: "actions/setup-python@v2"
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
         with:
-          python-version: "${{ matrix.python-version }}"
+          python-version: ${{ matrix.python-version }}
 
       - name: "Install dependencies"
         run: |
@@ -37,8 +38,7 @@ jobs:
           python -m pip install --upgrade pip setuptools wheel
           python -m pip install --upgrade virtualenv tox tox-gh-actions
 
-      - name: "Run tox targets for ${{ matrix.python-version }}"
-        run: "python -m tox"
+      - run: "python -m tox"
 
       - name: Upload coverage data
         uses: "actions/upload-artifact@v2"
@@ -49,7 +49,7 @@ jobs:
 
 
   coverage:
-    runs-on: "ubuntu-latest"
+    runs-on: ubuntu-latest
     needs: tests
 
     steps:
@@ -59,21 +59,20 @@ jobs:
           # Use latest Python, so it understands all syntax.
           python-version: ${{env.PYTHON_LATEST}}
 
-      - name: Install Coverage.py
-        run: python -m pip install --upgrade coverage[toml]
+      - run: python -m pip install --upgrade coverage[toml]
 
       - name: Download coverage data
         uses: actions/download-artifact@v2
         with:
           name: coverage-data
 
-      - name: Combine coverage and fail if it's <100%
+      - name: Combine coverage and fail if it's <100%.
         run: |
           python -m coverage combine
           python -m coverage html --skip-covered --skip-empty
           python -m coverage report --fail-under=100
 
-      - name: Upload HTML report for failed check
+      - name: Upload HTML report if check failed.
         uses: actions/upload-artifact@v2
         with:
           name: html-report
@@ -82,35 +81,34 @@ jobs:
 
 
   package:
-    name: "Build & verify package"
-    runs-on: "ubuntu-latest"
+    name: Build & verify package
+    runs-on: ubuntu-latest
 
     steps:
-      - uses: "actions/checkout@v2"
-      - uses: "actions/setup-python@v2"
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
         with:
           python-version: ${{env.PYTHON_LATEST}}
 
-      - run: "python -m pip install build twine check-wheel-contents"
-      - run: "python -m build --sdist --wheel ."
-      - run: "ls -l dist"
-      - run: "check-wheel-contents dist/*.whl"
-      - name: "Check long_description"
-        run: "python -m twine check dist/*"
+      - run: python -m pip install build twine check-wheel-contents
+      - run: python -m build --sdist --wheel .
+      - run: ls -l dist
+      - run: check-wheel-contents dist/*.whl
+      - name: Check long_description
+        run: python -m twine check dist/*
 
 
   install-dev:
-    name: "Verify dev env"
-    runs-on: "${{ matrix.os }}"
+    name: Verify dev env
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: ["ubuntu-latest", "windows-latest"]
 
     steps:
-      - uses: "actions/checkout@v2"
-      - uses: "actions/setup-python@v2"
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
         with:
           python-version: ${{env.PYTHON_LATEST}}
-      - run: "python -m pip install -e .[dev]"
-      - name: "Import package"
-        run: "python -c 'import attr; print(attr.__version__)'"
+      - run: python -m pip install -e .[dev]
+      - run: python -c 'import attr; print(attr.__version__)'

.pre-commit-config.yaml

@@ -33,10 +33,11 @@ repos:
         language_version: python3.10
 
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.0.1
+    rev: v4.1.0
     hooks:
       - id: trailing-whitespace
       - id: end-of-file-fixer
       - id: debug-statements
         language_version: python3.10
       - id: check-toml
+      - id: check-yaml

CHANGELOG.rst

@@ -3,16 +3,16 @@ Changelog
 
 Versions follow `CalVer <https://calver.org>`_ with a strict backwards-compatibility policy.
 
-The **first digit** of the version is the year.
-The **second digit** is incremented with each release, starting at 1 for each year.
-The **third digit** is when we need to start branches for older releases (only for emergencies).
+The **first number** of the version is the year.
+The **second number** is incremented with each release, starting at 1 for each year.
+The **third number** is when we need to start branches for older releases (only for emergencies).
 
 Put simply, you shouldn't ever be afraid to upgrade ``attrs`` if you're only using its public APIs.
 Whenever there is a need to break compatibility, it is announced here in the changelog, and raises a ``DeprecationWarning`` for a year (if possible) before it's finally really broken.
 
 .. warning::
 
-   The structure of the `attr.Attribute` class is exempt from this rule.
+   The structure of the `attrs.Attribute` class is exempt from this rule.
    It *will* change in the future, but since it should be considered read-only, that shouldn't matter.
 
    However if you intend to build extensions on top of ``attrs`` you have to anticipate that.
@@ -28,6 +28,91 @@ Changes for the upcoming release can be found in the `"changelog.d" directory <h
 
 .. towncrier release notes start
 
+21.4.0 (2021-12-29)
+-------------------
+
+Changes
+^^^^^^^
+
+- Fixed the test suite on PyPy3.8 where ``cloudpickle`` does not work.
+  `#892 <https://github.com/python-attrs/attrs/issues/892>`_
+- Fixed ``coverage report`` for projects that use ``attrs`` and don't set a ``--source``.
+  `#895 <https://github.com/python-attrs/attrs/issues/895>`_,
+  `#896 <https://github.com/python-attrs/attrs/issues/896>`_
+
+
+----
+
+
+21.3.0 (2021-12-28)
+-------------------
+
+Backward-incompatible Changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- When using ``@define``, converters are now run by default when setting an attribute on an instance -- additionally to validators.
+  I.e. the new default is ``on_setattr=[attrs.setters.convert, attrs.setters.validate]``.
+
+  This is unfortunately a breaking change, but it was an oversight, impossible to raise a ``DeprecationWarning`` about, and it's better to fix it now while the APIs are very fresh with few users.
+  `#835 <https://github.com/python-attrs/attrs/issues/835>`_,
+  `#886 <https://github.com/python-attrs/attrs/issues/886>`_
+- ``import attrs`` has finally landed!
+  As of this release, you can finally import ``attrs`` using its proper name.
+
+  Not all names from the ``attr`` namespace have been transferred; most notably ``attr.s`` and ``attr.ib`` are missing.
+  See ``attrs.define`` and ``attrs.field`` if you haven't seen our next-generation APIs yet.
+  A more elaborate explanation can be found `On The Core API Names <https://www.attrs.org/en/latest/names.html>`_
+
+  This feature is at least for one release **provisional**.
+  We don't *plan* on changing anything, but such a big change is unlikely to go perfectly on the first strike.
+
+  The API docs have been mostly updated, but it will be an ongoing effort to change everything to the new APIs.
+  Please note that we have **not** moved -- or even removed -- anything from ``attr``!
+
+  Please do report any bugs or documentation inconsistencies!
+  `#887 <https://github.com/python-attrs/attrs/issues/887>`_
+
+
+Changes
+^^^^^^^
+
+- ``attr.asdict(retain_collection_types=False)`` (default) dumps collection-esque keys as tuples.
+  `#646 <https://github.com/python-attrs/attrs/issues/646>`_,
+  `#888 <https://github.com/python-attrs/attrs/issues/888>`_
+- ``__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.
+  `#815 <https://github.com/python-attrs/attrs/issues/815>`_
+- If the class-level *on_setattr* is set to ``attrs.setters.validate`` (default in ``@define`` and ``@mutable``) but no field defines a validator, pretend that it's not set.
+  `#817 <https://github.com/python-attrs/attrs/issues/817>`_
+- The generated ``__repr__`` is significantly faster on Pythons with f-strings.
+  `#819 <https://github.com/python-attrs/attrs/issues/819>`_
+- Attributes transformed via ``field_transformer`` are wrapped with ``AttrsClass`` again.
+  `#824 <https://github.com/python-attrs/attrs/issues/824>`_
+- Generated source code is now cached more efficiently for identical classes.
+  `#828 <https://github.com/python-attrs/attrs/issues/828>`_
+- Added ``attrs.converters.to_bool()``.
+  `#830 <https://github.com/python-attrs/attrs/issues/830>`_
+- ``attrs.resolve_types()`` now resolves types of subclasses after the parents are resolved.
+  `#842 <https://github.com/python-attrs/attrs/issues/842>`_
+  `#843 <https://github.com/python-attrs/attrs/issues/843>`_
+- Added new validators: ``lt(val)`` (< val), ``le(va)`` (≤ val), ``ge(val)`` (≥ val), ``gt(val)`` (> val), and ``maxlen(n)``.
+  `#845 <https://github.com/python-attrs/attrs/issues/845>`_
+- ``attrs`` classes are now fully compatible with `cloudpickle <https://github.com/cloudpipe/cloudpickle>`_ (no need to disable ``repr`` anymore).
+  `#857 <https://github.com/python-attrs/attrs/issues/857>`_
+- Added new context manager ``attrs.validators.disabled()`` and functions ``attrs.validators.(set|get)_disabled()``.
+  They deprecate ``attrs.(set|get)_run_validators()``.
+  All functions are interoperable and modify the same internal state.
+  They are not – and never were – thread-safe, though.
+  `#859 <https://github.com/python-attrs/attrs/issues/859>`_
+- ``attrs.validators.matches_re()`` now accepts pre-compiled regular expressions in addition to pattern strings.
+  `#877 <https://github.com/python-attrs/attrs/issues/877>`_
+
+
+----
+
+
 21.2.0 (2021-05-07)
 -------------------
 
@@ -76,7 +161,7 @@ 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!
+- The instant favorite next-generation APIs 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>`_.
 
@@ -115,7 +200,7 @@ Changes
 
   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>`_.
+- Added **provisional** support for static typing in ``pyright`` via the `dataclass_transforms specification <https://github.com/microsoft/pyright/blob/main/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>`_.
@@ -234,7 +319,7 @@ Deprecations
   Please check out the linked issue for more details.
 
   These new APIs have been added *provisionally* as part of #666 so you can try them out today and provide feedback.
-  Learn more in the `API docs <https://www.attrs.org/en/stable/api.html#provisional-apis>`_.
+  Learn more in the `API docs <https://www.attrs.org/en/stable/api.html>`_.
   `#408 <https://github.com/python-attrs/attrs/issues/408>`_
 
 
@@ -511,7 +596,7 @@ Changes
   `#349 <https://github.com/python-attrs/attrs/issues/349>`_
 - The order of attributes that are passed into ``attr.make_class()`` or the *these* argument of ``@attr.s()`` is now retained if the dictionary is ordered (i.e. ``dict`` on Python 3.6 and later, ``collections.OrderedDict`` otherwise).
 
-  Before, the order was always determined by the order in which the attributes have been defined which may not be desirable when creating classes programatically.
+  Before, the order was always determined by the order in which the attributes have been defined which may not be desirable when creating classes programmatically.
 
   `#300 <https://github.com/python-attrs/attrs/issues/300>`_,
   `#339 <https://github.com/python-attrs/attrs/issues/339>`_,
@@ -523,7 +608,7 @@ Changes
 - Setting the cell type is now completely best effort.
   This fixes ``attrs`` on Jython.
 
-  We cannot make any guarantees regarding Jython though, because our test suite cannot run due to dependency incompatabilities.
+  We cannot make any guarantees regarding Jython though, because our test suite cannot run due to dependency incompatibilities.
 
   `#321 <https://github.com/python-attrs/attrs/issues/321>`_,
   `#334 <https://github.com/python-attrs/attrs/issues/334>`_

MANIFEST.in

@@ -2,8 +2,8 @@ include LICENSE *.rst *.toml *.yml *.yaml *.ini
 graft .github
 
 # Stubs
-include src/attr/py.typed
 recursive-include src *.pyi
+recursive-include src py.typed
 
 # Tests
 include tox.ini conftest.py