From 639ed1b5471b8b0cbba9141cff5f1fb737eb9e25 Mon Sep 17 00:00:00 2001
From: Lanqing Huang <lqhuang@outlook.com>
Date: Sun, 4 Dec 2022 21:10:29 +0800
Subject: [PATCH] Add docs and changelog for new feature

---
 changelog.d/1068.change.rst | 1 +
 docs/examples.md            | 6 +++---
 src/attr/filters.py         | 4 ++++
 tests/typing_example.py     | 2 ++
 4 files changed, 10 insertions(+), 3 deletions(-)
 create mode 100644 changelog.d/1068.change.rst

diff --git a/changelog.d/1068.change.rst b/changelog.d/1068.change.rst
new file mode 100644
index 000000000..22ef69d2f
--- /dev/null
+++ b/changelog.d/1068.change.rst
@@ -0,0 +1 @@
+filters ``exclude`` and ``include`` now support to pass literal name of attribtes in ``str`` format
diff --git a/docs/examples.md b/docs/examples.md
index 6329efc35..b7893e125 100644
--- a/docs/examples.md
+++ b/docs/examples.md
@@ -215,7 +215,7 @@ For that, {func}`attrs.asdict` offers a callback that decides whether an attribu
 {'users': [{'email': 'jane@doe.invalid'}, {'email': 'joe@doe.invalid'}]}
 ```
 
-For the common case where you want to [`include`](attrs.filters.include) or [`exclude`](attrs.filters.exclude) certain types or attributes, *attrs* ships with a few helpers:
+For the common case where you want to [`include`](attrs.filters.include) or [`exclude`](attrs.filters.exclude) certain types, string name or attributes, *attrs* ships with a few helpers:
 
 ```{doctest}
 >>> from attrs import asdict, filters, fields
@@ -228,7 +228,7 @@ For the common case where you want to [`include`](attrs.filters.include) or [`ex
 
 >>> asdict(
 ...     User("jane", "s33kred", 42),
-...     filter=filters.exclude(fields(User).password, int))
+...     filter=filters.exclude(fields(User).password, int, "password"))
 {'login': 'jane'}
 
 >>> @define
@@ -238,7 +238,7 @@ For the common case where you want to [`include`](attrs.filters.include) or [`ex
 ...     z: int
 
 >>> asdict(C("foo", "2", 3),
-...        filter=filters.include(int, fields(C).x))
+...        filter=filters.include(int, fields(C).x, "x"))
 {'x': 'foo', 'z': 3}
 ```
 
diff --git a/src/attr/filters.py b/src/attr/filters.py
index 4a81ac045..13fae1149 100644
--- a/src/attr/filters.py
+++ b/src/attr/filters.py
@@ -27,6 +27,8 @@ def include(*what):
         `attrs.Attribute`\\ s
 
     :rtype: `callable`
+
+    .. versionchanged:: 22.2.0 Accept field name string as input argument
     """
     cls, names, attrs = _split_what(what)
 
@@ -49,6 +51,8 @@ def exclude(*what):
         `attrs.Attribute`\\ s.
 
     :rtype: `callable`
+
+    .. versionchanged:: 22.2.0 Accept field name string as input argument
     """
     cls, names, attrs = _split_what(what)
 
diff --git a/tests/typing_example.py b/tests/typing_example.py
index b77b93c0a..0b871410d 100644
--- a/tests/typing_example.py
+++ b/tests/typing_example.py
@@ -441,6 +441,7 @@ def accessing_from_attr() -> None:
     attr.converters.optional
     attr.exceptions.FrozenError
     attr.filters.include
+    attr.filters.exclude
     attr.setters.frozen
     attr.validators.and_
     attr.cmp_using
@@ -453,6 +454,7 @@ def accessing_from_attrs() -> None:
     attrs.converters.optional
     attrs.exceptions.FrozenError
     attrs.filters.include
+    attr.filters.exclude
     attrs.setters.frozen
     attrs.validators.and_
     attrs.cmp_using