Add decorator option for converters

changelog.d/404.change.rst

@@ -0,0 +1,2 @@
+Allow converters to be specified via a decorator including getting access to the partially initialized instance.
+``self`` is also available via ``Converter()`` which can be passed when calling ``attr.ib(converter=...)``.

docs/api.rst

@@ -70,24 +70,28 @@ Core
 
       ``attrs`` also comes with a serious business alias ``attr.attrib``.
 
-   The object returned by `attr.ib` also allows for setting the default and the validator using decorators:
+   The object returned by `attr.ib` also allows for setting the default, the validator, and the converter using decorators:
 
    .. doctest::
 
       >>> @attr.s
       ... class C(object):
       ...     x = attr.ib()
       ...     y = attr.ib()
+      ...     z = attr.ib()
       ...     @x.validator
       ...     def _any_name_except_a_name_of_an_attribute(self, attribute, value):
       ...         if value < 0:
       ...             raise ValueError("x must be positive")
-      ...     @y.default
+      ...     @y.converter
+      ...     def _any_name_except_a_name_of_an_attribute(self, attr, value):
+      ...         return int(value)
+      ...     @z.default
       ...     def _any_name_except_a_name_of_an_attribute(self):
-      ...         return self.x + 1
-      >>> C(1)
-      C(x=1, y=2)
-      >>> C(-1)
+      ...         return self.x + 2
+      >>> C(1, "2")
+      C(x=1, y=2, z=3)
+      >>> C(-1, "2")
       Traceback (most recent call last):
           ...
       ValueError: x must be positive
@@ -141,6 +145,22 @@ Core
       C(x=[1, 2, 3], y={1, 2, 3})
 
 
+.. autoclass:: attr.Converter
+
+   For example:
+
+   .. doctest::
+
+      >>> @attr.s
+      ... class C(object):
+      ...     x = attr.ib(converter=int)
+      ...     y = attr.ib(converter=attr.Converter(
+      ...         lambda self, attr, value: self.x + value,
+      ...     ))
+      >>> C("1", 2)
+      C(x=1, y=3)
+
+
 Exceptions
 ----------
 

docs/examples.rst

@@ -454,9 +454,17 @@ This can be useful for doing type-conversions on values that you don't want to f
     >>> @attr.s
     ... class C(object):
     ...     x = attr.ib(converter=int)
-    >>> o = C("1")
-    >>> o.x
-    1
+    ...     y = attr.ib(
+    ...         converter=attr.Converter(
+    ...             lambda self, attr, value: self.x + value,
+    ...         ),
+    ...     )
+    ...     z = attr.ib()
+    ...     @z.converter
+    ...     def z_converter(self, attr, value):
+    ...         return self.x + value
+    >>> C("10", 2, 3)
+    C(x=10, y=12, z=13)
 
 Check out `converters` for more details.
 

docs/init.rst

@@ -301,6 +301,20 @@ Arguably, you can abuse converters as one-argument validators:
    ValueError: invalid literal for int() with base 10: 'x'
 
 
+Similar to validators, converters can be specified with a decorator.
+
+.. doctest::
+
+    >>> @attr.s
+    ... class C(object):
+    ...     x = attr.ib()
+    ...     @x.converter
+    ...     def int(self, attr, value):
+    ...         return int(value)
+    >>> o = C("1")
+    >>> o
+    C(x=1)
+
 Post-Init Hook
 --------------
 

src/attr/__init__.py

@@ -10,6 +10,7 @@
 from ._make import (
     NOTHING,
     Attribute,
+    Converter,
     Factory,
     attrib,
     attrs,
@@ -43,6 +44,7 @@
 
 __all__ = [
     "Attribute",
+    "Converter",
     "Factory",
     "NOTHING",
     "asdict",