changed to reuse and docs first pass

* Added material in "Other goodies" section in `examples.md`
* docstrings for `field`, `attrib`, and `reuse`
*Added towncrier changelog message

Author: redruin1

changelog.d/pr1429.change.md

@@ -0,0 +1,50 @@
+Added `Attribute.reuse(**kwargs)`, which allows you to reuse (and simultaneously `evolve()`) attribute definitions from already defined classes:
+
+```py
+@define
+class A:
+    a: int = 100
+
+@define
+class B(A):
+    a = fields(B).a.reuse(default=200)
+
+assert B().a == 200
+```
+
+To preserve attribute ordering of `reuse`d attributes, `inherited` was exposed as a public keyword argument to `attrib` and friends. Setting `inherited=True` manually on a *attrs* field definition simply acts as a flag to tell *attrs* to use the parent class ordering, *if* it can find an attribute in the parent MRO with the same name. Otherwise, the field is simply added to the class's attribute list as if `inherited=False`.
+
+```py
+@define
+class Parent:
+    x: int = 1
+    y: int = 2
+
+@define
+class ChildOrder(Parent):
+    x = fields(Parent).x.reuse(default=3)
+    z: int = 4
+
+assert repr(ChildOrder()) == "ChildOrder(y=2, x=3, z=4)"
+
+@define 
+class ParentOrder(Parent):
+    x = fields(Parent).y.reuse(default=3, inherited=True)
+    z = fields(ChildOrder).z.reuse(inherited=True) # `inherited` does nothing here
+
+assert repr(ParentOrder()) == "ParentOrder(x=3, y=2, z=4)"
+```
+
+Incidentally, because this behavior was added to `field`, this gives you a little more control of attribute ordering even when not using `reuse()`:
+
+```py
+@define
+class Parent:
+    a: int
+    b: int = 10
+
+class Child(Parent):
+    a: str = field(default="test", inherited=True)
+
+assert repr(Child()) == "Child(a='test', b=10)"
+```

docs/api.rst

@@ -38,7 +38,7 @@ Core
 .. autofunction:: field
 
 .. autoclass:: Attribute
-   :members: evolve
+   :members: evolve, reuse
 
    For example:
 

docs/examples.md

@@ -747,6 +747,53 @@ If you need to dynamically make a class with {func}`~attrs.make_class` and it ne
 True
 ```
 
+In certain situations, you might want to reuse part (or all) of an existing attribute instead of entirely redefining it. This pattern is common in inheritance schemes, where you might just want to change one parameter of an attribute (i.e. default value) while leaving all other parts unchanged. For this purpose, *attrs* offers {meth}`.Attribute.reuse`:
+
+```{doctest}
+>>> @define
+... class A:
+...    a: int = field(default=10)
+...
+...    @a.validator
+...    def very_complex_validator(self, attr, value):
+...        print("Validator runs!")
+
+>>> @define
+... class B(A):
+...    a = fields(A).a.reuse(default=20)
+
+>>> B()
+Validator runs!
+B(a=20)
+```
+
+This method inherits all of the keyword arguments from {func}`~attrs.field`, which works identically to defining a new attribute with the same parameters.
+
+While this feature is mostly intended for making working with inherited classes easier, there's nothing requiring `reuse`d attributes actually be part of a parent class:
+
+```{doctest}
+>>> @define
+... class C:  # does not inherit class `A`
+...     a = fields(A).a.reuse(factory=lambda: 100)
+...     # And now that `a` is in scope of `C`, field decorators work again:
+...     @a.validator
+...     def my_new_validator_func(self, attr, value):
+...         print("Another validator function!")
+
+>>> C()
+Validator runs!
+Another validator function!
+C(a=100)
+```
+
+This in combination with {func}`~attrs.make_class` makes a very powerful suite of *attrs* class manipulation tools both before and after class creation:
+
+```{doctest}
+>>> C3 = make_class("C3", {"x": fields(C2).x.reuse(), "y": fields(C2).y.reuse()})
+>>> fields(C2) == fields(C3)
+True
+```
+
 Sometimes, you want to have your class's `__init__` method do more than just
 the initialization, validation, etc. that gets done for you automatically when
 using `@define`.

src/attr/__init__.pyi

@@ -139,7 +139,14 @@ class Attribute(Generic[_T]):
     alias: str | None
 
     def evolve(self, **changes: Any) -> "Attribute[Any]": ...
-    def to_field(self) -> Any: ...
+    @overload
+    def reuse(self, **changes: Any) -> Any: ...
+    @overload
+    def reuse(self, type: _T, **changes: Any) -> _T: ...
+    @overload
+    def reuse(self, default: _T, **changes: Any) -> _T: ...
+    @overload
+    def reuse(self, type: _T | None, **changes: Any) -> _T: ...
 
 # NOTE: We had several choices for the annotation to use for type arg:
 # 1) Type[_T]
@@ -182,6 +189,7 @@ def attrib(
     order: _EqOrderType | None = ...,
     on_setattr: _OnSetAttrArgType | None = ...,
     alias: str | None = ...,
+    inherited: bool | None = ...,
 ) -> Any: ...
 
 # This form catches an explicit None or no default and infers the type from the
@@ -206,6 +214,7 @@ def attrib(
     order: _EqOrderType | None = ...,
     on_setattr: _OnSetAttrArgType | None = ...,
     alias: str | None = ...,
+    inherited: bool | None = ...,
 ) -> _T: ...
 
 # This form catches an explicit default argument.
@@ -229,6 +238,7 @@ def attrib(
     order: _EqOrderType | None = ...,
     on_setattr: _OnSetAttrArgType | None = ...,
     alias: str | None = ...,
+    inherited: bool | None = ...,
 ) -> _T: ...
 
 # This form covers type=non-Type: e.g. forward references (str), Any
@@ -252,6 +262,7 @@ def attrib(
     order: _EqOrderType | None = ...,
     on_setattr: _OnSetAttrArgType | None = ...,
     alias: str | None = ...,
+    inherited: bool | None = ...,
 ) -> Any: ...
 @overload
 @dataclass_transform(order_default=True, field_specifiers=(attrib, field))

src/attr/_make.py

@@ -157,6 +157,7 @@ def attrib(
        *eq*, *order*, and *cmp* also accept a custom callable
     .. versionchanged:: 21.1.0 *cmp* undeprecated
     .. versionadded:: 22.2.0 *alias*
+    .. versionadded:: 25.4.0 *inherited*
     """
     eq, eq_key, order, order_key = _determine_attrib_eq_order(
         cmp, eq, order, True
@@ -2550,34 +2551,55 @@ def evolve(self, **changes):
 
         return new
 
-    def to_field(self):
+    def reuse(
+        self,
+        **field_kwargs,
+    ):
         """
-        Converts this attribute back into a raw :py:class:`_CountingAttr` object,
-        such that it can be used to annotate newly `define`d classes. This is
-        useful if you want to reuse part (or all) of fields defined in other
-        attrs classes that have already been resolved into their finalized state.
+        Converts this attribute back into a raw :py:func:`attrs.field` object,
+        such that it can be used to annotate newly ``@define``-d classes. This
+        is useful if you want to reuse part (or all) of fields defined in other
+        attrs classes that have already been resolved into their finalized
+        :py:class:`.Attribute`.
+
+        Args:
+            field_kwargs: Any valid keyword argument to :py:func:`attrs.field`.
 
         .. versionadded:: 25.4.0
         """
-        return _CountingAttr(
-            default=self.default,
-            validator=self.validator,
-            repr=self.repr,
-            cmp=None,
-            hash=self.hash,
-            init=self.init,
-            converter=self.converter,
-            metadata=self.metadata,
-            type=self.type,
-            kw_only=self.kw_only,
-            eq=self.eq,
-            eq_key=self.eq_key,
-            order=self.order,
-            order_key=self.order_key,
-            on_setattr=self.on_setattr,
-            alias=self.alias,
-            inherited=self.inherited,
-        )
+        args = {
+            "validator": self.validator,
+            "repr": self.repr,
+            "cmp": None,
+            "hash": self.hash,
+            "init": self.init,
+            "converter": self.converter,
+            "metadata": self.metadata,
+            "type": self.type,
+            "kw_only": self.kw_only,
+            "eq": self.eq,
+            "order": self.order,
+            "on_setattr": self.on_setattr,
+            "alias": self.alias,
+            "inherited": self.inherited,
+        }
+
+        # Map the single "validator" object back down to it's aliased pair.
+        # Additionally, we help the user out a little bit by automatically
+        # overwriting the compliment `default` or `factory` function when
+        # overriding; so if a field already has a `default=3`, using
+        # `reuse(factory=lambda: 3)` won't complain about having both kinds of
+        # defaults defined.
+        if "default" not in field_kwargs and "factory" not in field_kwargs:
+            if isinstance(self.default, Factory):
+                field_kwargs["factory"] = self.default.factory
+            else:
+                field_kwargs["default"] = self.default
+
+        args.update(field_kwargs)
+
+        # Send through attrib so we reuse the same errors + syntax sugar
+        return attrib(**args)
 
     # Don't use _add_pickle since fields(Attribute) doesn't work
     def __getstate__(self):

src/attr/_next_gen.py

@@ -429,7 +429,7 @@ def field(
     order=None,
     on_setattr=None,
     alias=None,
-    inherited=None,
+    inherited=False,
 ):
     """
     Create a new :term:`field` / :term:`attribute` on a class.
@@ -566,7 +566,7 @@ def field(
             ``__init__`` method. If left None, default to ``name`` stripped
             of leading underscores. See `private-attributes`.
 
-        inherited (bool | None):
+        inherited (bool):
             Ensure this attribute inherits the ordering of the parent attribute
             with the same name. If no parent attribute with the same name
             exists, this field is treated as normal.