{"id":8930,"library":"dataclass-csv","title":"dataclass-csv","description":"dataclass-csv is a Python library designed to effortlessly map CSV data into Python dataclasses. It handles type conversions automatically for standard types and supports custom converters for more complex scenarios. The library provides both a reader and a writer for CSV operations with dataclasses. It is currently at version 1.4.1 and sees active development with a moderate release cadence, addressing issues and adding features.","status":"active","version":"1.4.1","language":"en","source_language":"en","source_url":"https://github.com/dfurtado/dataclass-csv","tags":["dataclasses","csv","data-processing","serialization","deserialization","type-conversion"],"install":[{"cmd":"pip install dataclass-csv","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"DataclassReader","correct":"from dataclass_csv import DataclassReader"},{"symbol":"DataclassWriter","correct":"from dataclass_csv import DataclassWriter"}],"quickstart":{"code":"import dataclasses\nfrom dataclass_csv import DataclassReader\nimport io\n\n@dataclasses.dataclass\nclass Product:\n    product_id: int\n    name: str\n    price: float\n    in_stock: bool\n\ncsv_data = \"\"\"product_id,name,price,in_stock\n101,Laptop,1200.50,true\n102,Mouse,25.99,False\n103,Keyboard,75.00,1\n104,Monitor,300.00,0\n\"\"\"\n\n# Read CSV data into dataclass instances\nreader = DataclassReader(io.StringIO(csv_data), Product)\nproducts = []\nfor product in reader:\n    products.append(product)\n    print(f\"Product: {product.name}, Price: ${product.price}, In Stock: {product.in_stock}\")\n\n# Example of accessing a specific product\nif products:\n    print(f\"\\nFirst product name: {products[0].name}\")\n","lang":"python","description":"Demonstrates how to define a dataclass, prepare CSV data, and use `DataclassReader` to parse the CSV into a list of dataclass objects, handling automatic type conversion for int, float, and bool."},"warnings":[{"fix":"Review your CSV data for non-standard boolean strings (other than 'true', '1', 'yes', 'y', 'on' for True; or 'false', '0', 'no', 'n', 'off' for False). If your application relied on `ValueError` being raised for invalid boolean values, you'll need to add custom validation or a custom converter to replicate that behavior.","message":"Starting from version 1.4.1, the internal boolean string conversion logic has changed. Previously, it used `distutils.util.strtobool` which raised a `ValueError` for unrecognized boolean strings (e.g., 'unknown'). The new implementation converts unrecognized strings to `False` instead of raising an error. This can silently change behavior if your CSV contains non-standard boolean representations.","severity":"breaking","affected_versions":">=1.4.1"},{"fix":"Always ensure your CSV files have unique column headers. If you encounter `DuplicatedHeaderError`, rename duplicate columns in your CSV, or use `dataclasses.field(metadata={'dataclass_csv': {'column_name': '...'}})` for explicit mapping if you absolutely need to handle ambiguous columns (though this is not recommended).","message":"Before version 1.3.0, if your CSV file contained duplicated header names, `dataclass-csv` might have silently mapped data incorrectly or overwritten values. From 1.3.0 onwards, it explicitly checks for and raises a `DuplicatedHeaderError` for such cases.","severity":"gotcha","affected_versions":"<1.3.0"},{"fix":"For versions older than 1.4.0, use a custom `TypeConverter` to handle date/datetime fields. For versions 1.4.0+, ensure your date strings are in standard formats parseable by Python's `datetime` module, or specify a format string via `dataclasses.field(metadata={'dataclass_csv': {'date_format': '%Y-%m-%d'}})`.","message":"Automatic date and datetime type conversion was officially introduced in version 1.4.0. Prior versions did not inherently support converting string representations of dates (e.g., 'YYYY-MM-DD') into `datetime.date` or `datetime.datetime` objects, requiring manual conversion or custom type converters.","severity":"gotcha","affected_versions":"<1.4.0"},{"fix":"For new development environments or contributions, consult the latest `pyproject.toml` and README on GitHub for the recommended dependency management tool (currently `poetry`). If you're only using the library as a dependency, this change does not affect your application.","message":"The project deprecated `pipenv` for dependency management in version 1.4.1, moving towards `poetry`. While this primarily affects project contributors and development setup, users following older contribution guides or examples might find inconsistencies.","severity":"deprecated","affected_versions":">=1.4.1"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Modify your CSV file to ensure all header names are unique. If you have columns with logically similar data, give them distinct names (e.g., `value_1`, `value_2`).","cause":"Your CSV file contains multiple columns with the same header name, which dataclass-csv considers ambiguous and prevents to ensure data integrity.","error":"dataclass_csv.exceptions.DuplicatedHeaderError: CSV header '...' is duplicated. This can lead to unexpected data mapping."},{"fix":"Inspect the CSV data and the dataclass field type. Ensure the data matches the type, or provide a custom `TypeConverter` (via `DataclassReader(..., converter=...)`) if you need special handling for conversions or errors.","cause":"A value in your CSV column could not be automatically converted to the type specified in the corresponding dataclass field (e.g., a string 'abc' into an `int`).","error":"ValueError: invalid literal for int() with base 10: 'abc' (or similar for float, date, bool)"},{"fix":"Verify that your CSV header names exactly match the field names in your dataclass (case-sensitive). If the names differ, use `dataclasses.field(metadata={'dataclass_csv': {'column_name': 'ActualCsvHeader'}})` to explicitly map them.","cause":"This error typically occurs when trying to access a field on your dataclass instance that either does not exist in the dataclass definition or was not mapped from the CSV (e.g., a CSV header name did not match a dataclass field name).","error":"AttributeError: type object 'MyDataclass' has no attribute 'missing_field'"}]}