Resolve field aliases before calling field_transformer (#1509)

* Resolve field aliases before calling field_transformer

Previously, field_transformer received attributes with alias=None for
fields without an explicit alias. The default alias (e.g., stripping
leading underscores) was only resolved after the transformer ran, making
it impossible for transformers to access or use alias values.

This moves alias resolution to before the field_transformer call, so
transformers receive fully populated Attribute objects. A second pass
after the transformer handles any new fields the transformer may have
added.

Additionally, Attribute.evolve() now automatically updates the alias
when the name changes, if the alias was auto-generated (matching the
default for the old name). Explicit aliases are preserved.

Fixes #1479

* Fix CI failures: update doctest, add changelog, fix coverage

- Update extending.md doctest to reflect that field_transformer now
  receives pre-resolved aliases (use alias == name.lstrip("_") instead
  of `not field.alias` to detect auto-generated aliases)
- Add changelog entry for #1479
- Add test_hook_new_field_without_alias to cover the post-transformer
  alias resolution path (line 496 of _make.py)

* Fix pre-commit

* Change is neat but breaking

Point change at PR, not bug.

* Handle default alias detection explicitly

* Fix docs build

* We actually load 25.3-style

---------

Co-authored-by: Hynek Schlawack <hs@ox.cx>

Author: veeceey

changelog.d/1509.breaking.md

@@ -0,0 +1,2 @@
+Field aliases are now resolved *before* calling `field_transformer`, so transformers receive fully populated `Attribute` objects with usable `alias` values instead of `None`.
+The new `Attribute.alias_is_default` flag indicates whether the alias was auto-generated (`True`) or explicitly set by the user (`False`).

docs/extending.md

@@ -248,13 +248,14 @@ Data(a=3, b='spam', c=datetime.datetime(2020, 5, 4, 13, 37))
 ```
 
 Or, perhaps you would prefer to generate dataclass-compatible `__init__` signatures via a default field *alias*.
-Note, *field_transformer* operates on {class}`attrs.Attribute` instances before the default private-attribute handling is applied so explicit user-provided aliases can be detected.
+Note, *field_transformer* receives {class}`attrs.Attribute` instances with default aliases already resolved, so the leading-underscore stripping has already been applied.
+You can use the `attrs.Attribute.alias_is_default` flag to detect whether an alias was explicitly provided by the user or auto-generated.
 
 ```{doctest}
 >>> def dataclass_names(cls, fields):
 ...     return [
 ...         field.evolve(alias=field.name)
-...         if not field.alias
+...         if field.alias_is_default
 ...         else field
 ...         for field in fields
 ...     ]

src/attr/_make.py

@@ -463,6 +463,15 @@ def _transform_attrs(
 
     attrs = base_attrs + own_attrs
 
+    # Resolve default field alias before executing field_transformer, so that
+    # the transformer receives fully populated Attribute objects with usable
+    # alias values.
+    for a in attrs:
+        if not a.alias:
+            # Evolve is very slow, so we hold our nose and do it dirty.
+            _OBJ_SETATTR.__get__(a)("alias", _default_init_alias_for(a.name))
+            _OBJ_SETATTR.__get__(a)("alias_is_default", True)
+
     if field_transformer is not None:
         attrs = tuple(field_transformer(cls, attrs))
 
@@ -480,13 +489,12 @@ def _transform_attrs(
         if had_default is False and a.default is not NOTHING:
             had_default = True
 
-    # Resolve default field alias after executing field_transformer.
-    # This allows field_transformer to differentiate between explicit vs
-    # default aliases and supply their own defaults.
+    # Resolve default field alias for any new attributes that the
+    # field_transformer may have added without setting an alias.
     for a in attrs:
         if not a.alias:
-            # Evolve is very slow, so we hold our nose and do it dirty.
             _OBJ_SETATTR.__get__(a)("alias", _default_init_alias_for(a.name))
+            _OBJ_SETATTR.__get__(a)("alias_is_default", True)
 
     # Create AttrsClass *after* applying the field_transformer since it may
     # add or remove attributes!
@@ -2427,6 +2435,8 @@ class Attribute:
     - ``name`` (`str`): The name of the attribute.
     - ``alias`` (`str`): The __init__ parameter name of the attribute, after
       any explicit overrides and default private-attribute-name handling.
+    - ``alias_is_default`` (`bool`): Whether the ``alias`` was automatically
+      generated (``True``) or explicitly provided by the user (``False``).
     - ``inherited`` (`bool`): Whether or not that attribute has been inherited
       from a base class.
     - ``eq_key`` and ``order_key`` (`typing.Callable` or `None`): The
@@ -2452,6 +2462,7 @@ class Attribute:
         equality checks and hashing anymore.
     .. versionadded:: 21.1.0 *eq_key* and *order_key*
     .. versionadded:: 22.2.0 *alias*
+    .. versionadded:: 26.1.0 *alias_is_default*
 
     For the full version history of the fields, see `attr.ib`.
     """
@@ -2476,6 +2487,7 @@ class Attribute:
         "inherited",
         "on_setattr",
         "alias",
+        "alias_is_default",
     )
 
     def __init__(
@@ -2498,6 +2510,7 @@ def __init__(
         order_key=None,
         on_setattr=None,
         alias=None,
+        alias_is_default=None,
     ):
         eq, eq_key, order, order_key = _determine_attrib_eq_order(
             cmp, eq_key or eq, order_key or order, True
@@ -2532,6 +2545,10 @@ def __init__(
         bound_setattr("inherited", inherited)
         bound_setattr("on_setattr", on_setattr)
         bound_setattr("alias", alias)
+        bound_setattr(
+            "alias_is_default",
+            alias is None if alias_is_default is None else alias_is_default,
+        )
 
     def __setattr__(self, name, value):
         raise FrozenInstanceError
@@ -2567,6 +2584,7 @@ def from_counting_attr(
             ca.order_key,
             ca.on_setattr,
             ca.alias,
+            ca.alias is None,
         )
 
     # Don't use attrs.evolve since fields(Attribute) doesn't work
@@ -2585,6 +2603,20 @@ def evolve(self, **changes):
 
         new._setattrs(changes.items())
 
+        if "alias" in changes and "alias_is_default" not in changes:
+            # Explicit alias provided -- no longer the default.
+            _OBJ_SETATTR.__get__(new)("alias_is_default", False)
+        elif (
+            "name" in changes
+            and "alias" not in changes
+            # Don't auto-generate alias if the user picked picked the old one.
+            and self.alias_is_default
+        ):
+            # Name changed, alias was auto-generated -- update it.
+            _OBJ_SETATTR.__get__(new)(
+                "alias", _default_init_alias_for(new.name)
+            )
+
         return new
 
     # Don't use _add_pickle since fields(Attribute) doesn't work
@@ -2601,6 +2633,17 @@ def __setstate__(self, state):
         """
         Play nice with pickle.
         """
+        if len(state) < len(self.__slots__):
+            # Pre-26.1.0 pickle without alias_is_default -- infer it
+            # heuristically.
+            state_dict = dict(zip(self.__slots__, state))
+            alias_is_default = state_dict.get(
+                "alias"
+            ) is None or state_dict.get("alias") == _default_init_alias_for(
+                state_dict["name"]
+            )
+            state = (*state, alias_is_default)
+
         self._setattrs(zip(self.__slots__, state))
 
     def _setattrs(self, name_values_pairs):
@@ -2624,7 +2667,7 @@ def _setattrs(self, name_values_pairs):
         name=name,
         default=NOTHING,
         validator=None,
-        repr=True,
+        repr=(name != "alias_is_default"),
         cmp=None,
         eq=True,
         order=False,

tests/test_functional.py

@@ -130,6 +130,7 @@ def test_fields(self, cls):
                 hash=None,
                 init=True,
                 inherited=False,
+                alias_is_default=True,
             ),
             Attribute(
                 name="y",
@@ -143,6 +144,7 @@ def test_fields(self, cls):
                 hash=None,
                 init=True,
                 inherited=False,
+                alias_is_default=True,
             ),
         ) == attr.fields(cls)
 
@@ -201,6 +203,7 @@ def test_programmatic(self, slots, frozen):
                 hash=None,
                 init=True,
                 inherited=False,
+                alias_is_default=True,
             ),
             Attribute(
                 name="b",
@@ -214,6 +217,7 @@ def test_programmatic(self, slots, frozen):
                 hash=None,
                 init=True,
                 inherited=False,
+                alias_is_default=True,
             ),
         ) == attr.fields(PC)
 

tests/test_hooks.py

@@ -178,7 +178,7 @@ class C:
             "eq=True, eq_key=None, order=True, order_key=None, "
             "hash=None, init=True, "
             "metadata=mappingproxy({'field_order': 1}), type='int', converter=None, "
-            "kw_only=False, inherited=False, on_setattr=None, alias=None)",
+            "kw_only=False, inherited=False, on_setattr=None, alias='x')",
         ) == e.value.args
 
     def test_hook_with_inheritance(self):
@@ -233,6 +233,150 @@ class Base:
 
         assert ["x"] == [a.name for a in attr.fields(Base)]
 
+    def test_hook_alias_available(self):
+        """
+        The field_transformer receives attributes with default aliases
+        already resolved, not None.
+
+        Regression test for #1479.
+        """
+        seen = []
+
+        def hook(cls, attribs):
+            seen[:] = [(a.name, a.alias, a.alias_is_default) for a in attribs]
+            return attribs
+
+        @attr.s(auto_attribs=True, field_transformer=hook)
+        class C:
+            _private: int
+            _explicit: int = attr.ib(alias="_explicit")
+            public: int
+
+        assert [
+            ("_private", "private", True),
+            ("_explicit", "_explicit", False),
+            ("public", "public", True),
+        ] == seen
+
+    def test_hook_evolve_name_updates_auto_alias(self):
+        """
+        When a field_transformer evolves a field's name, the alias is
+        automatically updated if it was auto-generated.
+
+        Regression test for #1479.
+        """
+
+        def hook(cls, attribs):
+            return [a.evolve(name="renamed") for a in attribs]
+
+        @attr.s(auto_attribs=True, field_transformer=hook)
+        class C:
+            _original: int
+
+        f = attr.fields(C).renamed
+
+        assert "renamed" == f.alias
+        assert f.alias_is_default is True
+
+    def test_hook_evolve_name_keeps_explicit_alias(self):
+        """
+        When a field_transformer evolves a field's name but the field had
+        an explicit alias, the alias is preserved.
+
+        Regression test for #1479.
+        """
+
+        def hook(cls, attribs):
+            return [a.evolve(name="renamed") for a in attribs]
+
+        @attr.s(auto_attribs=True, field_transformer=hook)
+        class C:
+            original: int = attr.ib(alias="my_alias")
+
+        f = attr.fields(C).renamed
+
+        assert "my_alias" == f.alias
+        assert f.alias_is_default is False
+
+    def test_hook_new_field_without_alias(self):
+        """
+        When a field_transformer adds a brand-new field without setting an
+        alias, the post-transformer alias resolution fills it in.
+
+        Regression test for #1479.
+        """
+
+        def hook(cls, attribs):
+            return [
+                *list(attribs),
+                attr.Attribute(
+                    name="_extra",
+                    default=0,
+                    validator=None,
+                    repr=True,
+                    cmp=None,
+                    hash=None,
+                    init=True,
+                    metadata={},
+                    type=int,
+                    converter=None,
+                    kw_only=False,
+                    eq=True,
+                    eq_key=None,
+                    order=True,
+                    order_key=None,
+                    on_setattr=None,
+                    alias=None,
+                    inherited=False,
+                ),
+            ]
+
+        @attr.s(auto_attribs=True, field_transformer=hook)
+        class C:
+            x: int
+
+        f = attr.fields(C)._extra
+
+        assert "extra" == f.alias
+        assert f.alias_is_default is True
+
+    def test_hook_explicit_alias_matching_default(self):
+        """
+        When a user explicitly sets an alias that happens to equal the
+        auto-generated default, alias_is_default is still False.
+
+        Regression test for #1479.
+        """
+
+        @attr.s(auto_attribs=True)
+        class C:
+            _private: int = attr.ib(alias="private")
+
+        f = attr.fields(C)._private
+
+        assert "private" == f.alias
+        assert f.alias_is_default is False
+
+    def test_hook_evolve_alias_sets_not_default(self):
+        """
+        When a field_transformer uses evolve() to set an explicit alias,
+        alias_is_default becomes False.
+
+        Regression test for #1479.
+        """
+
+        def hook(cls, attribs):
+            return [a.evolve(alias="custom") for a in attribs]
+
+        @attr.s(auto_attribs=True, field_transformer=hook)
+        class C:
+            x: int
+
+        f = attr.fields(C).x
+
+        assert "custom" == f.alias
+        assert f.alias_is_default is False
+
 
 class TestAsDictHook:
     def test_asdict(self):