Allow optional conversion

This just adds a function that makes an existing converter work for optional
inputs.

CHANGELOG.rst

@@ -36,6 +36,9 @@ Deprecations:
 Changes:
 ^^^^^^^^
 
+- Support optional conversion
+  `#105 <https://github.com/python-attrs/attrs/issues/105>`_
+  `#173 <https://github.com/python-attrs/attrs/pull/173>`_
 - Fix default hashing behavior.
   Now *hash* mirrors the value of *cmp* and classes are unhashable by default.
   `#136`_

src/attr/__init__.py

@@ -23,6 +23,7 @@
 )
 from . import exceptions
 from . import filters
+from . import converters
 from . import validators
 
 
@@ -54,6 +55,7 @@
     "attrib",
     "attributes",
     "attrs",
+    "converters",
     "evolve",
     "exceptions",
     "fields",

src/attr/converters.py

@@ -0,0 +1,23 @@
+"""
+Commonly useful converters.
+"""
+
+from __future__ import absolute_import, division, print_function
+
+
+def optional(converter):
+    """
+    A converter that allows an attribute to be optional. An optional attribute
+    is one which can be set to ``None``.
+
+    :param converter: the converter that is used for non-``None`` values.
+
+    ..  versionadded:: 17.1.0 *convert* can be optional
+    """
+
+    def optional_converter(val):
+        if val is None:
+            return None
+        return converter(val)
+
+    return optional_converter

tests/test_converters.py

@@ -0,0 +1,37 @@
+"""
+Tests for `attr.converters`.
+"""
+
+from __future__ import absolute_import
+
+import pytest
+
+from attr.converters import optional
+
+
+class TestOptional(object):
+    """
+    Tests for `optional`.
+    """
+
+    def test_success_with_type(self):
+        """
+        Nothing happens if types match.
+        """
+        c = optional(int)
+        assert c('42') == 42
+
+    def test_success_with_none(self):
+        """
+        Nothing happens if None.
+        """
+        c = optional(int)
+        assert c(None) is None
+
+    def test_fail(self):
+        """
+        Propagates the underlying conversion error when conversion fails.
+        """
+        c = optional(int)
+        with pytest.raises(ValueError):
+            c("not_an_int")