CSV and JSON

New words in this topic, in plain English. Come back here whenever one feels fuzzy.

CSV

Comma-separated values: a text file where each line is a table row and values are separated by commas.

Header

The first row of a CSV that names the columns.

JSON

A text format for nested data using objects, arrays, strings, numbers, true/false and null.

Serialise

To turn data in memory into text or bytes that can be stored or sent.

Deserialise (parse)

To turn stored text or bytes back into data in memory.

dumps / loads

json functions that work with strings: dump to string, load from string.

dump / load

json functions that work with open files.

JSON Lines

A file with one JSON value per line, easy to append to and to stream.

1. 1

   Add a tricky value

   In the first example add a row with a value that contains a double quote, such as 'He said "hi"'. Print the raw file lines and see how the quote is doubled.

2. 2

   Add up a column

   In the second example try total += row["price"] without int(...). What error do you get? Then restore the int call.

3. 3

   Round trip a set

   In the fourth example make the default function return list(value) instead of sorted(value) and run it a few times. Is the order guaranteed? Why does sorted make the output safe for tests?

Errors are the best teachers. Make each change, read the error, guess what went wrong, then reveal the answer.

import datetime
import json

print(json.dumps({"when": datetime.date(2026, 10, 9)}))

import csv
import io

total = 0
for row in csv.DictReader(io.StringIO("item,price\ntea,20\n")):
    total += row["price"]
print(total)

1. 1

   A CSV file is plain text. Each line is a row and the values in the row are separated by commas, often with a first line of column names (the header). It looks simple, but the details are tricky. A value can contain a comma ("Pune, India", which must be wrapped in quotes), a quote (doubled as "") or even a line break. Never split lines on , yourself. The csv module handles all of this. csv.reader(f) gives each row as a list of strings. csv.DictReader(f) gives each row as a dictionary keyed by the header names (Topic 4.4), which is nearly always the nicer choice.

2. 2

   Two rules for CSV in Python. First, open the file with newline="" (and encoding="utf-8"), because the csv module handles line endings itself. Second, everything you read is a string, including numbers. Convert with int(...) or float(...) yourself. Writing is the mirror image. csv.writer(f).writerow([...]) writes a list. csv.DictWriter(f, fieldnames=[...]) writes dictionaries; call writeheader() first to write the column names.

3. 3

   JSON (JavaScript Object Notation) is the standard way programs exchange data, because every language can read it. It has six kinds of value: objects {"key": value}, arrays [1, 2], strings in double quotes, numbers, true/false and null. Python maps them to dict, list, str, int/float, True/False and None. Every message to and from an AI API is JSON.

4. 4

   The four functions to know: json.dumps(obj) turns Python data into a JSON string (the s means string), json.loads(text) turns a JSON string into Python data, json.dump(obj, file) writes straight to an open file, and json.load(file) reads from one. Useful options of dumps/dump: indent=2 for readable output, sort_keys=True for a stable order, and ensure_ascii=False to keep non-English letters as they are instead of \u escapes.

5. 5

   JSON is narrower than Python. It only knows the six kinds of value above. So json.dumps raises TypeError: Object of type ... is not JSON serializable for a set, a datetime (a date and time value, Topic 7.11), a Path or your own class. Dictionary keys become strings (a key of 1 comes back as "1"). Tuples come back as lists. NaN and Infinity are not valid JSON, yet Python writes them as NaN unless you pass allow_nan=False (then it raises ValueError). To handle extra types, pass default=function to dumps. The function is called for each unknown object and returns something JSON can store (like str(value) or sorted(the_set)).

6. 6

   For large data use JSON Lines (.jsonl): one complete JSON object per line, no surrounding array. You can append one record at a time and read the file line by line (Topic 7.5) without loading it all. Training sets, logs and batch inputs for AI models are usually JSON Lines for exactly this reason. Bad JSON raises json.JSONDecodeError (a kind of ValueError) that says where the mistake is. Catch it where you parse input you do not control.

• ↔

  CSV versus JSON. CSV is compact and opens in spreadsheets, but is flat and untyped. JSON handles nesting and types such as numbers versus strings, but is larger and cannot be opened as a table directly.

• ↔

  One big JSON file versus JSON Lines. One file is simple to load as a whole. JSON Lines streams and appends, but is not a single valid JSON document and needs a loop to read.

• Done when you can write and read a CSV file with csv.writer and csv.DictReader, using newline="".

• Done when you can explain why CSV values are strings and convert them correctly.

• Done when you can use json.dumps, loads, dump and load and name what changes on a round trip.

• Done when you can fix a 'not JSON serializable' error with default= or isoformat().

• Done when you can write and read a JSON Lines file and handle a bad line.