Support multiple aliases for a field

[frenck]

Support multiple aliases for a field

Closes #176.

Lets a field declare more than one alias. On deserialization the aliases are tried in order and the first key present in the input wins; serialization and JSON schema use the first (primary) alias. A single string alias keeps working exactly as before.

Three ways to declare them, matching the API discussed in the issue:

a: Annotated[int, Alias("id"), Alias("ID")]
b: int = field(metadata=field_options(alias=["b", "bee"]))

class Config(BaseConfig):
    aliases = {"c": ["c", "cee"]}

The alias field option now accepts str | Sequence[str], the aliases config accepts dict[str, str | Sequence[str]], and a field may carry several Alias annotations. When allow_deserialization_not_by_alias is set, the field name is tried after the aliases. forbid_extra_keys accepts every alias.

Internally the per-field decode logic now builds an ordered, de-duplicated list of keys to look up, which also collapsed the two near-duplicate alias branches in the field unpacker into a single path. Generated code for fields without multiple aliases is unchanged (verified byte-for-byte against the previous output), so this is purely additive for existing users.

Design notes

A few choices worth your eye:

1. The first alias is the canonical one used for serialization and JSON schema output.
2. Multiple aliases can also be expressed with several Alias(...) annotations on a single field. The issue only mentioned the field option and the config option, so this extends the annotation path for consistency.
3. Resolution precedence is unchanged: field option, then annotation, then config. The first source that supplies any alias wins; sources are not merged.

Tests cover all three declaration styles, deserialization fallback order, allow_deserialization_not_by_alias, forbid_extra_keys, serialization using the primary alias, JSON schema, and the field-name-as-alias dedup case. README updated.

../Frenck

                       

Blogging my personal ramblings at frenck.dev

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.92%. Comparing base (da19903) to head (31b756d).

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #339   +/-   ##
=======================================
  Coverage   99.92%   99.92%           
=======================================
  Files         101      101           
  Lines       12062    12140   +78     
=======================================
+ Hits        12053    12131   +78     
  Misses          9        9           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.