{"id":4917,"library":"csvw","title":"CSVW Python Library","description":"The `csvw` Python library (version 3.7.0) provides an API to read and write relational, tabular data in adherence to the W3C CSV on the Web specification. It offers functionalities for parsing CSVW described data, converting it to JSON, and validating metadata. The project maintains an active development status with regular releases.","status":"active","version":"3.7.0","language":"python","source_language":"en","source_url":"https://github.com/cldf/csvw","tags":["csv","data","metadata","linked-data","csvw","w3c"],"install":[{"cmd":"pip install csvw","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Requires Python 3.8 or higher.","package":"Python","optional":false}],"imports":[{"note":"The primary class for interacting with CSVW data and metadata.","symbol":"CSVW","correct":"from csvw import CSVW"}],"quickstart":{"code":"import json\nfrom csvw import CSVW\nimport os\n\n# Example using a remote CSVW metadata file\n# Note: In a real application, you might use a local file path.\n# Ensure 'https://raw.githubusercontent.com/cldf/csvw/master/tests/fixtures/test.tsv' is accessible.\n\ntry:\n    data = CSVW('https://raw.githubusercontent.com/cldf/csvw/master/tests/fixtures/test.tsv')\n    # Convert the CSVW data to JSON\n    json_output = data.to_json()\n    print(json.dumps(json_output, indent=2))\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure the URL is correct and accessible.\")","lang":"python","description":"This quickstart demonstrates how to instantiate a `CSVW` object from a URL pointing to a TSV file (or a CSVW metadata file) and then convert the described data to a JSON representation. The `to_json()` method serializes the tabular data according to the CSVW specification."},"warnings":[{"fix":"Ensure you explicitly `pip install csvw` and `from csvw import CSVW`. Do not confuse it with `csvwlib` which uses `from csvwlib import CSVWConverter`.","message":"There are multiple Python libraries with 'csvw' in their name, notably `csvw` (this library) and `csvwlib`. They have distinct APIs and functionalities. Installing and importing `csvwlib` instead of `csvw` will lead to incompatible API calls and unexpected behavior.","severity":"breaking","affected_versions":"All versions"},{"fix":"If strict positional matching is required, explicitly specify `'header': false` and `'skipRows': 1` in the table's dialect description within your CSVW metadata.","message":"The `csvw` library does not implement the *full* CSVW specification. Specifically, when reading CSV files with headers, columns are matched based on their header text and column descriptions' 'name' or 'titles' attributes, not strictly by order as might be expected by the spec. This allows more flexibility but deviates from a strict interpretation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be aware of these specific `csv` module limitations, particularly when dealing with `commentPrefix`, `escapechar`, `quoteChar`, and `doubleQuote` settings in your dialect. Test data thoroughly with complex characters and quoting.","message":"Due to reliance on Python's standard `csv` module, certain behaviors related to `escapechar` and `commentPrefix` can be inconsistent or unexpected. For instance, if `commentPrefix` is specified in a `Dialect` instance, rows starting with it will be skipped even if the value was quoted. Also, cell content with `escapechar` may not round-trip as expected when `doubleQuote==False` and minimal quoting is used.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When working with `anyURI` types, be aware that the string representation may change due to normalization. If exact string preservation is critical for non-normalized URIs, consider storing them as `string` datatype instead, or handle normalization explicitly before passing to `anyURI`.","message":"The `anyURI` datatype in `csvw.datatypes` normalizes URLs according to RFC 3986 during serialization to a string. This normalization means that round-tripping (serializing and then deserializing) a URI is not guaranteed to yield an identical string if the original URI contained non-normalized forms.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"search_vec":"'3.7.0':9 'activ':49 'adher':21 'api':12 'convert':38 'csv':25,55 'csvw':1,5,35,61 'data':19,37,56,60 'describ':36 'develop':50 'function':32 'json':41 'librari':3,7 'link':59 'linked-data':58 'maintain':47 'metadata':44,57 'offer':31 'pars':34 'project':46 'provid':10 'python':2,6 'read':14 'regular':53 'relat':17 'releas':54 'specif':29 'status':51 'tabular':18 'valid':43 'version':8 'w3c':24,62 'web':28 'write':16","created_at":"2026-04-12T16:46:14.823795+00:00","updated_at":"2026-04-16T04:19:49.471715+00:00","problems":[{"fix":"Install the library using pip: `pip install csvw`","cause":"The `csvw` library is not installed in your Python environment or the environment where you are trying to run your code.","error":"ModuleNotFoundError: No module named 'csvw'"},{"fix":"Ensure that the data in columns specified as 'integer' in your CSVW metadata (`.json`) only contains integer values, or adjust the datatype in your metadata to a more flexible type like 'string' or 'decimal' if non-integer data is expected. Alternatively, you might set `strict=False` during CSVW parsing if the library supports it for your specific operation to handle invalid data more gracefully (e.g., by logging warnings instead of raising errors).","cause":"This error often occurs in `csvw` when a column defined as an 'integer' datatype in the metadata contains non-integer values in the CSV data, and the parser is operating in a strict mode or attempting a direct conversion.","error":"ValueError: invalid literal for int() with base 10"},{"fix":"Specify the correct encoding when opening or reading the CSV file. If you are using the `csvw` library directly to read, ensure any underlying file-reading mechanisms are provided with the correct encoding. For instance, if reading the CSV first, explicitly set the encoding: `with open('your_file.csv', 'r', encoding='latin-1') as f: ...` or use a tool like `chardet` to detect the encoding if unknown, then apply it.","cause":"The CSV file you are trying to process with `csvw` is not encoded in UTF-8, but Python (and often `csvw` by default) is attempting to decode it as such. This commonly happens with files created on different operating systems or with specific software that use encodings like 'latin-1' or 'windows-1252'.","error":"UnicodeDecodeError: 'utf-8' codec can't decode byte 0x__ in position __: invalid start byte"},{"fix":"Correct the data in your CSV file to match the datatype defined in your CSVW metadata for that column, or update your CSVW metadata (`.json`) to accurately reflect the actual data type of the column in the CSV file. If parsing programmatically, ensure `validate=True` is set in the `csvw.CSVW` instance to catch these issues during processing.","cause":"This is a `csvw` validation error indicating that a specific cell's content in your CSV file does not conform to the `datatype` specified for its column in the associated CSVW metadata. For example, a cell in a column defined as `datatype: 'integer'` might contain text.","error":"Cell (row X column Y) cannot be formatted as 'datatype'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.1.0","cli_name":"csvw","cli_version":"sh: 1: csvw: not found","type":"library","homepage":null,"github":"https://github.com/cldf/csvw","docs":null,"changelog":null,"pypi":"https://pypi.org/project/csvw/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-30","next_check":"2026-07-28","install_tag":null}}