JSON в Python: чтение и запись файлов, CSV, pathlib и кодировка UTF-8

Работа с JSON в Python не требует сторонних библиотек: модуль json входит в стандартную библиотеку и превращает словари и списки в текст и обратно. Рядом с ним почти всегда нужны ещё три вещи: функция open с конструкцией with, модуль pathlib для путей и модуль csv для таблиц. Ниже — всё по порядку, с рабочим кодом и граблями, на которых спотыкаются чаще всего.

Функция open в Python: режимы и кодировка

Любой текстовый файл открывается встроенной функцией open(path, mode, encoding=...). Она возвращает файловый объект, у которого есть методы read, readline, write и который можно перебирать в цикле построчно.

Зачем нужен with

Файл нужно закрывать: иначе данные могут не записаться на диск, а система держит дескриптор занятым. Конструкция with закрывает файл автоматически — даже если внутри блока случилась ошибка.

with open("notes.txt", "w", encoding="utf-8") as f:
    f.write("Первая строка\n")
    f.write("Вторая строка\n")

with open("notes.txt", encoding="utf-8") as f:
    for line in f:
        print(line.rstrip("\n"))

Перебор файла в цикле читает его по одной строке и не загружает целиком в память, поэтому так можно обрабатывать и гигабайтные логи. Метод f.read() вернёт всё содержимое одной строкой, f.readlines() — список строк.

Как записать строку в файл и не стереть старое

Самая частая ошибка новичка — открыть файл в режиме "w", чтобы «дописать» строчку. Режим "w" очищает файл в момент открытия, ещё до первого write. Чтобы добавить запись в конец, используйте "a", а чтобы гарантированно не перезаписать чужой файл — "x".

with open("log.txt", "a", encoding="utf-8") as f:
    f.write("новая запись\n")

Учтите, что write не добавляет перевод строки сам — "\n" пишется явно. Можно также использовать print(..., file=f): он поставит перенос за вас.

Кодировка UTF-8: почему появляются «кракозябры»

До Python 3.15 функция open() без параметра encoding брала кодировку системы. На Linux и macOS это UTF-8, а на Windows с русской локалью — cp1251. Скрипт, который нормально работал на сервере, на ноутбуке коллеги выводил «Р•РґР°» вместо «Еда» или падал с UnicodeDecodeError.

В Python 3.15 по PEP 686 режим UTF-8 включён по умолчанию: open() без encoding читает и пишет UTF-8 на всех ОС. Вернуть старое поведение можно переменной окружения PYTHONUTF8=0 или флагом -X utf8=0, а явно попросить системную кодировку — encoding="locale".

import sys
print(sys.flags.utf8_mode)   # 1 в Python 3.15

open("legacy.txt", encoding="locale")   # системная кодировка
open("old_excel.csv", encoding="cp1251")  # файл, сохранённый в cp1251

Обратная сторона: старый CSV из Excel или скрипта на Windows, сохранённый в cp1251, теперь будет прочитан как UTF-8 и вызовет UnicodeDecodeError. Лечится так: прочитать с encoding="cp1251" и пересохранить в UTF-8. Хороший тон не меняется — указывайте encoding явно, тогда код одинаково ведёт себя на любой версии.

pathlib в Python: пути как объекты

Склеивать пути строками ("data" + "/" + name) неудобно и ломается на разных ОС. Модуль pathlib даёт класс Path, где пути соединяются оператором /, а у объекта есть понятные свойства.

from pathlib import Path

data = Path("data")
csv_path = data / "expenses.csv"

print(csv_path.name)    # expenses.csv
print(csv_path.stem)    # expenses
print(csv_path.suffix)  # .csv
print(csv_path.parent)  # data
print(csv_path.exists())

data.mkdir(parents=True, exist_ok=True)
(data / "hello.txt").write_text("Привет", encoding="utf-8")
print((data / "hello.txt").read_text(encoding="utf-8"))

for p in data.glob("*.csv"):
    print(p)

Методы read_text и write_text заменяют связку open + with для небольших файлов. Объект Path можно передать и в обычный open, и в json, и в csv — все они его принимают. Путь относительно самого скрипта, а не текущей папки, получают так: Path(__file__).parent / "data".

В Python 3.14 у Path появились методы copy() и move(), так что для простого копирования больше не нужен shutil. В той же версии в стандартную библиотеку добавили модуль compression.zstd для сжатия Zstandard (PEP 784).

JSON в Python: load, dump, loads, dumps

JSON — текстовый формат обмена данными: его отдают API, в нём хранят конфиги и отчёты. Модуль json умеет две операции: сериализацию (Python-объект → JSON-текст) и десериализацию (текст → объект). Методов четыре, и путаница между ними — частый вопрос.

Запомнить просто: буква s на конце означает string — работа со строкой; без неё — с файлом.

Соответствие типов

Кортеж при обратном чтении станет списком, а множества, даты и Decimal модуль не знает и выдаст TypeError: Object of type ... is not JSON serializable.

Как сохранить JSON в файл

import json
from pathlib import Path

report = {
    "month": "2026-10",
    "total": 15230.5,
    "categories": {"еда": 8200, "транспорт": 2100},
    "tags": ["дом", "работа"],
}

path = Path("data/report.json")
path.parent.mkdir(parents=True, exist_ok=True)
with path.open("w", encoding="utf-8") as f:
    json.dump(report, f, ensure_ascii=False, indent=2)

Параметр ensure_ascii=False сохраняет кириллицу как есть. Без него вместо «еда» в файле окажется "еда" — это корректный JSON, но читать его человеку невозможно. indent=2 делает красивое форматирование с отступами.

Как прочитать JSON из файла

with open("data/report.json", encoding="utf-8") as f:
    data = json.load(f)

print(data["total"])               # 15230.5
print(data["categories"]["еда"])   # 8200

Результат — обычный словарь или список, с ним работают привычными средствами. Если файл не JSON или оборван, будет исключение json.JSONDecodeError с номером строки и позиции — его стоит ловить, когда данные приходят извне.

Парсинг JSON-строки и красивый вывод

import json

raw = '{"name": "Анна", "skills": ["python", "sql"], "active": true}'
user = json.loads(raw)
print(user["skills"][0])   # python

print(json.dumps(user, ensure_ascii=False, indent=2, sort_keys=True))

sort_keys=True сортирует ключи при выводе — удобно, чтобы сравнивать файлы в git. Для быстрого форматирования файла из терминала есть встроенная утилита: python -m json.tool data/report.json.

Ответ HTTP API — тоже строка JSON. Библиотека requests разбирает её методом response.json(), а внутри это тот же json.loads.

Подвох: ключи JSON всегда строки

d = {1: "январь", 2: "февраль"}
back = json.loads(json.dumps(d))
print(back == d)   # False
print(back)        # {'1': 'январь', '2': 'февраль'}
# back[1] -> KeyError, нужно back["1"]

fixed = {int(k): v for k, v in back.items()}

В JSON ключи объекта могут быть только строками, поэтому числовые ключи после круга сериализации превращаются в строки. Приводите их обратно при чтении.

Свои типы: даты и Decimal

import json
from datetime import date

def default(obj):
    if isinstance(obj, date):
        return obj.isoformat()
    raise TypeError(f"не умею сериализовать {type(obj).__name__}")

print(json.dumps({"day": date(2026, 10, 1)}, default=default))
# {"day": "2026-10-01"}

Функция в параметре default вызывается для каждого неизвестного объекта. Для сложных случаев можно унаследоваться от json.JSONEncoder и переопределить метод default.

Как дописать элемент в JSON-массив

JSON нельзя дописать в конец, как текстовый лог: файл нужно прочитать, изменить и записать целиком.

path = Path("data/items.json")
items = json.loads(path.read_text(encoding="utf-8")) if path.exists() else []
items.append({"id": len(items) + 1, "title": "новый"})
path.write_text(json.dumps(items, ensure_ascii=False, indent=2), encoding="utf-8")

Если записей много и они добавляются постоянно, удобнее формат JSON Lines: по одному JSON-объекту на строку, файл открывается в режиме "a".

CSV в Python: модуль csv

CSV — таблица в текстовом файле: строки — записи, значения разделены запятыми. Модуль csv правильно обрабатывает кавычки, запятые внутри значений и переносы, чего не сделает ручной split(",").

import csv

with open("data/expenses.csv", newline="", encoding="utf-8") as f:
    reader = csv.DictReader(f)
    total = 0.0
    for row in reader:
        total += float(row["amount"])
        print(row["date"], row["category"], row["amount"])
print("Итого:", total)

csv.DictReader превращает каждую строку в словарь по заголовку файла. Все значения — строки: числа и даты приводите сами (float, int, date.fromisoformat). Файл с разделителем «;» (так сохраняет русский Excel) читают с параметром delimiter=";".

rows = [
    {"date": "2026-10-01", "category": "еда", "amount": 450},
    {"date": "2026-10-02", "category": "транспорт", "amount": 60},
]
with open("data/out.csv", "w", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=["date", "category", "amount"])
    writer.writeheader()
    writer.writerows(rows)

При записи обязательно newline="": без него на Windows между строками появятся пустые. Если файл будут открывать в Excel, используйте encoding="utf-8-sig" — метка BOM помогает Excel распознать UTF-8.

От CSV к JSON: полный пример

import csv
import json
from collections import defaultdict
from pathlib import Path

src = Path("data/expenses.csv")
dst = Path("data/report.json")

by_category = defaultdict(float)
with src.open(newline="", encoding="utf-8") as f:
    for row in csv.DictReader(f):
        by_category[row["category"]] += float(row["amount"])

report = {"total": sum(by_category.values()), "categories": dict(by_category)}
dst.write_text(json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8")
print(dst.read_text(encoding="utf-8"))

Это ядро любого скрипта-отчёта: вход в CSV, агрегация в словаре, выход в JSON.

Типичные ошибки

• FileNotFoundError — путь относительный и считается от текущей папки запуска, а не от скрипта. Используйте Path(__file__).parent.
• Файл обнулился — открыли в "w" вместо "a".
• UnicodeDecodeError — файл в другой кодировке; укажите её явно (cp1251, utf-8-sig).
• TypeError: Object of type set is not JSON serializable — преобразуйте в список или передайте default.
• KeyError после загрузки JSON — числовые ключи стали строками.
• Свой файл назван json.py или csv.py — он перекрывает стандартный модуль, и import json импортирует его.

Итог

Для JSON в Python достаточно стандартной библиотеки: json.load/json.dump для файлов, loads/dumps для строк, ensure_ascii=False и indent для читаемого вывода. Файлы открывайте через with с явной кодировкой, пути стройте через pathlib, таблицы читайте csv.DictReader. В курсе по Python эта тема разобрана на практике: трекер расходов читает траты из CSV и сохраняет отчёт в JSON.