[Feature] Use typing.Annotated for customization

[diego-oncoramedical]

• cattrs version: 23.2.3
• Python version: 3.12
• Operating System: MacOS

Description

There's a decent amount of overhead in creating separate converters that needs to be done, which can get cumbersome quickly for a large number of classes. I was thinking it'd be possible to use typing.Annotated to reduce this work in a backwards-compatible way, without messing up type checking for those who need it.

An example that could solve (#352 and #552 if I understand them correctly)

from typing import Annotated
import cattrs.annotations as ca   # hypothetically

class SomeKVPair:
    key: Annotated[str, ca.Rename("Key")]
    data_size: Annotated[int, ca.FromNested("Data.Size")]
    value: Annotated[bytes, ca.AsBase64, ca.Rename("Value")] = b""

There are a few benefits to this:

1. Type checkers will still understand the annotations.
2. No need to rely on metadata inserted using attrs.field() or similar.
3. It's clear to anyone looking at just the class what transforms are made. If they want to do their own serialization (e.g. create an XML serializer) it'll be clear what transforms they need to do.
4. Getting the extra annotations is opt-in, so it'll be invisible to older versions of cattrs that don't support it.
5. Other libraries can also see these and use it for their own purposes.
6. It's been available since 3.9. Version 3.8 goes EOL in October, so there's no need for compatibility shims.

Presumably this will be a non-trivial change, but I think it would be really valuable.