Add docs and changelog for new feature

Author: lqhuang

changelog.d/1068.change.rst

@@ -0,0 +1 @@
+filters ``exclude`` and ``include`` now support to pass literal name of attribtes in ``str`` format

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}
 ```
 

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)
 

tests/typing_example.py

@@ -432,6 +432,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
@@ -444,6 +445,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