converters: allow wrapping and passing self and fields

changelog.d/1267.change.md

@@ -0,0 +1 @@
+It is now possible to wrap a converter into an `attrs.Converter` and get the current instance and/or the current field definition passed into the converter callable.

docs/api.rst

@@ -607,6 +607,27 @@ Validators can be both globally and locally disabled:
 Converters
 ----------
 
+.. autoclass:: attrs.Converter
+
+   For example:
+
+   .. doctest::
+
+      >>> def complicated(value, self_, field):
+      ...     return int(value) * self_.factor + field.metadata["offset"]
+      >>> @define
+      ... class C:
+      ...     factor = 5  # not an *attrs* field
+      ...     x = field(
+      ...         metadata={"offset": 200},
+      ...         converter=attrs.Converter(
+      ...             complicated,
+      ...             takes_self=True, takes_field=True
+      ...     ))
+      >>> C("42")
+      C(x=410)
+
+
 .. module:: attrs.converters
 
 All objects from ``attrs.converters`` are also available from ``attr.converters`` (it's the same module in a different namespace).

src/attr/__init__.py

@@ -15,6 +15,7 @@
 from ._make import (
     NOTHING,
     Attribute,
+    Converter,
     Factory,
     attrib,
     attrs,
@@ -39,6 +40,7 @@ class AttrsInstance(Protocol):
 __all__ = [
     "Attribute",
     "AttrsInstance",
+    "Converter",
     "Factory",
     "NOTHING",
     "asdict",