[Feature] Use typing.Annotated for customization

Open
#571 12 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
backend

Research direction

Review the existing converter-customization path and the proposed cattrs.annotations API, then compare it with typing.get_type_hints and the Annotated example in this issue. Done means the supported metadata behavior, backward-compatibility expectations, and implications for issues #352 and #552 are defined and verified.

Written by the indexing model from the issue text.

Description

  • 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.

Dominant language
Python
Stars
1.1k
Forks
159
Avg merge
12h 21m
Merged PRs (30d)
6

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from python-attrs/cattrs

All issues in python-attrs/cattrs

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.