csvw

library4.1.0pypypi✓ verified 27d ago

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.

data serialization

pip install csvw

github ↗package ↗

INSTALL

IMPORT

SIG · CSVW

csvw

datapythonv4.1.0

Install

3.7s avg

Import

888ms

Disk

62MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v4.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.928s · 63.3MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.7s · import 0.848s · 63MB

62MB installed

● package 62MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CSVW

✓ from csvw import CSVW

The primary class for interacting with CSVW data and metadata.

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.

import json from csvw import CSVW import os # Example using a remote CSVW metadata file # Note: In a real application, you might use a local file path. # Ensure 'https://raw.githubusercontent.com/cldf/csvw/master/tests/fixtures/test.tsv' is accessible. try: data = CSVW('https://raw.githubusercontent.com/cldf/csvw/master/tests/fixtures/test.tsv') # Convert the CSVW data to JSON json_output = data.to_json() print(json.dumps(json_output, indent=2)) except Exception as e: print(f"An error occurred: {e}") print("Please ensure the URL is correct and accessible.")

csvw --version

Debug

Known issues

breakingThere 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.

fix

Ensure you explicitly `pip install csvw` and `from csvw import CSVW`. Do not confuse it with `csvwlib` which uses `from csvwlib import CSVWConverter`.

affects: All versions

gotchaThe `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.

fix

If strict positional matching is required, explicitly specify `'header': false` and `'skipRows': 1` in the table's dialect description within your CSVW metadata.

affects: All versions

gotchaDue 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.

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.

affects: All versions

gotchaThe `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.

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`.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'csvw'

The `csvw` library is not installed in your Python environment or the environment where you are trying to run your code.

fix

Install the library using pip: `pip install csvw`

ValueError: invalid literal for int() with base 10

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.

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).

UnicodeDecodeError: 'utf-8' codec can't decode byte 0x__ in position __: invalid start byte

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'.

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.

Cell (row X column Y) cannot be formatted as 'datatype'

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.

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.

Upgrade

Version history

4.1.0latest on PyPI · released Jul 6, 2026

Audit

Dependencies

PythonrequiredRequires Python 3.8 or higher.

Agent activity

15 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cldf/csvw ↗

packagehttps://pypi.org/project/csvw/ ↗