Document and add a test for user-defined types

Also modifies the handling of exceptions to explicitly chain from exceptions
caused while trying to instantiate a user-defined type.

Author: alecbz

README.md

@@ -13,7 +13,7 @@ Dataclass CSV makes working with CSV files easier and much better than working w
 
 - Use `dataclasses` instead of dictionaries to represent the rows in the CSV file.
 - Take advantage of the `dataclass` properties type annotation. `DataclassReader` use the type annotation to perform validation of the data of the CSV file.
-- Automatic type conversion. `DataclassReader` supports `str`, `int`, `float`, `complex`, `datetime` and `bool`.
+- Automatic type conversion. `DataclassReader` supports `str`, `int`, `float`, `complex`, `datetime` and `bool`, as well as any type whose constructor accepts a string as its single argument.
 - Helps you troubleshoot issues with the data in the CSV file. `DataclassReader` will show exactly in which line of the CSV file contain errors.
 - Extract only the data you need. It will only parse the properties defined in the `dataclass`
 - Familiar syntax. The `DataclassReader` is used almost the same way as the `DictReader` in the standard library.
@@ -279,6 +279,27 @@ class User:
     created_at: datetime
 ```
 
+## User-defined types
+
+You can use any type for a field as long as its constructor accepts a string:
+
+```python
+class SSN:
+    def __init__(self, val):
+        if re.match(r"\d{9}", val):
+            self.val = f"{val[0:3]}-{val[3:5]}-{val[5:9]}"
+        elif re.match(r"\d{3}-\d{2}-\d{4}", val):
+            self.val = val
+        else:
+            raise ValueError(f"Invalid SSN: {val!r}")
+
+
+@dataclasses.dataclass
+class User:
+    name: str
+    ssn: SSN
+```
+
 ## Copyright and License
 
 Copyright (c) 2018 Daniel Furtado. Code released under BSD 3-clause license

dataclass_csv/dataclass_reader.py

@@ -195,14 +195,14 @@ def _process_row(self, row):
 
             try:
                 transformed_value = field_type(value)
-            except ValueError:
+            except ValueError as e:
                 raise CsvValueError(
                     (
                         f'The field `{field.name}` is defined as {field.type} '
                         f'but received a value of type {type(value)}.'
                     ),
                     line_number=self.reader.line_num,
-                ) from None
+                ) from e
             else:
                 values.append(transformed_value)
         return self.cls(*values)

tests/mocks.py

@@ -1,4 +1,5 @@
 import dataclasses
+import re
 
 from datetime import datetime
 
@@ -90,4 +91,20 @@ class UserWithOptionalAge:
 @dataclasses.dataclass
 class UserWithDefaultDatetimeField:
     name: str
-    birthday: datetime = datetime.now()
+    birthday: datetime = datetime.now()
+
+
+class SSN:
+    def __init__(self, val):
+        if re.match(r"\d{9}", val):
+            self.val = f"{val[0:3]}-{val[3:5]}-{val[5:9]}"
+        elif re.match(r"\d{3}-\d{2}-\d{4}", val):
+            self.val = val
+        else:
+            raise ValueError(f"Invalid SSN: {val!r}")
+
+
+@dataclasses.dataclass
+class UserWithSSN:
+    name: str
+    ssn: SSN

tests/test_csv_data_validation.py

@@ -2,7 +2,7 @@
 
 from dataclass_csv import DataclassReader, CsvValueError
 
-from .mocks import User, UserWithDateFormatDecorator
+from .mocks import User, UserWithDateFormatDecorator, UserWithSSN
 
 
 def test_should_raise_error_str_to_int_prop(create_csv):
@@ -75,3 +75,15 @@ def test_csv_header_items_with_spaces_with_prop_with_wrong_type(create_csv):
         with pytest.raises(CsvValueError):
             reader = DataclassReader(f, User)
             items = list(reader)
+
+
+def test_passes_through_exceptions_from_user_defined_types(create_csv):
+    csv_file = create_csv({'name': 'User1', 'ssn': '123-45-678'})
+
+    with csv_file.open() as f:
+        with pytest.raises(CsvValueError) as exc_info:
+            reader = DataclassReader(f, UserWithSSN)
+            items = list(reader)
+        cause = exc_info.value.__cause__
+        assert isinstance(cause, ValueError)
+        assert "Invalid SSN" in str(cause)

tests/test_dataclass_reader.py

@@ -12,6 +12,8 @@
     UserWithInitFalse,
     UserWithInitFalseAndDefaultValue,
     UserWithDefaultDatetimeField,
+    UserWithSSN,
+    SSN,
 )
 
 
@@ -178,3 +180,21 @@ def test_reader_with_datetime_default_value(create_csv):
         items = list(reader)
         assert len(items) > 0
         assert isinstance(items[0].birthday, datetime)
+
+
+def test_should_parse_user_defined_types(create_csv):
+    csv_file = create_csv([
+        {'name': 'User1', 'ssn': '123-45-6789'},
+        {'name': 'User1', 'ssn': '123456789'},
+    ])
+
+    with csv_file.open() as f:
+        reader = DataclassReader(f, UserWithSSN)
+        items = list(reader)
+        assert len(items) == 2
+
+        assert isinstance(items[0].ssn, SSN)
+        assert items[0].ssn.val == '123-45-6789'
+
+        assert isinstance(items[1].ssn, SSN)
+        assert items[1].ssn.val == '123-45-6789'