Add literal string support to include and exclude filters

[lqhuang]

Summary

It's a little too cumbersome that helper util filters only accepts type and Attribute as input, if there are too many fields to include or exclude using asdict.

For example,

from attrs import asdict, fields

@define
Class D:
    a = attr.ib()
    b = attr.ib()
    c = attr.ib()
    d = attr.ib()
    e = attr.ib()
    f = attr.ib()

data = D(...)
fs = fields(D)
asdict(data, filter=exclude(fs.a, fs.c, fs.f))

This PR adds literal string name of Attribute as input argument to exclude and include which provides a more convenience approach for usages of filter. The following codes are similar to the above:

from attrs import asdict

@define
Class D:
    a = attr.ib()
    b = attr.ib()
    c = attr.ib()
    d = attr.ib()
    e = attr.ib()
    f = attr.ib()

data = D(...)
asdict(data, filter=exclude("a", "c", "f"))

And typo issues of input arguments wouldn't cause extra side effects.

This's my first PR to attrs, please feel free to inform me where I'm wrong and what I missed. Thanks!

Pull Request Check List

• Added tests for changed code.
  Our CI fails if coverage is not 100%.
• New features have been added to our Hypothesis testing strategy.
• 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.
    Find the appropriate next version in our __init__.py file.
• Documentation in .rst files is written using semantic newlines.
• Changes (and possible deprecations) have news fragments in changelog.d.
• Consider granting push permissions to the PR branch, so maintainers can fix minor issues themselves without pestering you.

[Tinche]

It's not really equivalent though. See this example with a typo:

from attrs import asdict, define, fields
from attrs.filters import exclude


@define
class User:
    id: str
    password: str

data = User("id", "s3cret")
fs = fields(User)

asdict(data, filter=exclude("passwrd"))
asdict(data, filter=exclude(fs.passwrd))

When passing in a string, the typo goes unnoticed and the password field is serialized.

[lqhuang]

@Tinche Thanks for your reply 😄.

Yeah, you're right, fields will raise an AttributeError when the field doesn't exist. I should update "totally equivalent" to "similar". Current implementation is the simplest way with no overhead, while no extra side effect means no another unexpected behavior.

Could we document this potential consequence explicitly to warn users? IMHO, it probably depends on whether attrs should provide full soundness checks?

I also have an extreme radical thought that perhaps I could implement a generic type signature in pyi level to check correctness of field name string without runtime cost.

[lqhuang]

Rebase to the latest head ref 9cf2ed5 (2023-02-04)

[lqhuang]

Rebase from head ref 683d056 (2023-04-12)

[lqhuang]

Add a note to document incorrect typo behaviors while using literal string in filters

:::{note}
Though using string names directly is convenient, it's not safe in typo issues.
Using `fields()` to get attributes is worth being recommended in most cases.

```{doctest}
>>> asdict(
...     User("jane", "s33kred", 42),
...     filter=filters.exclude("passwd")
... )
{'login': 'jane', 'password': 's33kred', 'id': 42}

>>> asdict(
...     User("jane", "s33kred", 42),
...     filter=fields(User).passwd
... )
Traceback (most recent call last):
...
AttributeError: 'UserAttributes' object has no attribute 'passwd'. Did you mean: 'password'?
```
:::

[lqhuang]

@hynek Could you let actions run again? Or you may have other suggestions?

Thanks :)

[chrysle]

I have left some comments.

[lqhuang]

@chrysle Thank you for review. Updated.

[lqhuang]

@hynek Thanks for your advices. Updated

[hynek]

Thanks, this should be fine now.