csv-to-json

A lightweight, dependency-free CSV-to-JSON converter for AI agents and developer workflows.

Features

• Zero dependencies — uses only Python's standard library
• Type inference — automatically converts numeric, boolean, and null values
• Nested key expansion — dot-notation headers (e.g., user.name) become nested JSON objects
• Streaming support — process large CSV files without loading them entirely into memory
• Flexible input — accepts file paths, raw CSV strings, or stdin
• CLI and library usage — use from the command line or import into your own code

Quick Start

Command Line

# Convert a file
python src/csv_converter.py data.csv -o output.json

# Pipe from stdin
cat data.csv | python src/csv_converter.py - --compact

# Use a tab delimiter and expand nested keys
python src/csv_converter.py records.tsv -d '\t' --expand-keys

As a Library

from src.csv_converter import csv_to_json

# From a file path
json_str = csv_to_json("data.csv")

# From a raw CSV string
csv_data = """name,age,active
Alice,30,true
Bob,25,false"""

result = csv_to_json(csv_data)
print(result)
# [
#   {"name": "Alice", "age": 30, "active": true},
#   {"name": "Bob", "age": 25, "active": false}
# ]

Streaming Large Files

from src.csv_converter import stream_csv_to_json

with open("large_dataset.csv") as f:
    for record in stream_csv_to_json(f):
        process(record)  # handle one record at a time

CLI Options

Nested Key Expansion

Given a CSV with dot-notation headers:

user.name,user.email,user.address.city
Alice,alice@example.com,Portland

With --expand-keys, the output becomes:

[
  {
    "user": {
      "name": "Alice",
      "email": "alice@example.com",
      "address": {
        "city": "Portland"
      }
    }
  }
]

Type Inference Rules

When type inference is enabled (the default):

Disable with --no-type-inference to preserve all values as strings.

Requirements

• Python 3.10+
• No external packages required

License

MIT