تبدیل CSV به JSON در Python — راهنمای json.dumps()
از تبدیل CSV به JSON آنلاین رایگان مستقیم در مرورگرتان استفاده کنید — نیازی به نصب نیست.
امتحان کردن تبدیل CSV به JSON آنلاین ←فایلهای CSV همه جا هستند — گزارشهای صادرشده، پشتیبانگیری پایگاه داده، استخراج گزارشهای رویداد — و دیر یا زود باید این CSV را در Python به JSON تبدیل کنید. کتابخانه استاندارد این کار را با دو ماژول انجام میدهد: csv.DictReader هر ردیف را به یک دیکشنری Python تبدیل میکند، و json.dumps() آن دیکشنریها را به رشته JSON تبدیل میکند. برای تبدیل سریع یکباره بدون کد، ابزار تبدیل CSV به JSON این کار را فوری در مرورگر انجام میدهد. این راهنما مسیر برنامهنویسی کامل را پوشش میدهد: json.dump() در برابر json.dumps()، نوشتن JSON در فایل، سریالسازی dataclass، تبدیل نوع برای مقادیر CSV، مدیریت datetime و Decimal، و جایگزینهای پرسرعت مانند orjson. تمام مثالها برای Python 3.10+ هستند.
- ✓csv.DictReader یک لیست از dicts تولید میکند — کل لیست را با json.dump(rows, f, indent=2) سریالسازی کنید تا فایل JSON بنویسید.
- ✓json.dump() مستقیماً در شیء فایل مینویسد. json.dumps() یک رشته برمیگرداند. درست را انتخاب کنید تا از کپی غیرضروری جلوگیری شود.
- ✓مقادیر CSV همیشه رشته هستند. ستونهای عددی را قبل از سریالسازی به JSON به صراحت تبدیل کنید (int()، float()).
- ✓ensure_ascii=False را به json.dumps() پاس دهید تا کاراکترهای Unicode — نامهای لهجهدار، متن فارسی — در خروجی حفظ شوند.
- ✓برای datetime، UUID یا Decimal از CSV، از پارامتر default= با یک تابع جایگزین سفارشی استفاده کنید.
[
{
"order_id": "ORD-7291",
"product": "Wireless Keyboard",
"quantity": "2",
"price": "49.99"
},
{
"order_id": "ORD-7292",
"product": "USB-C Hub",
"quantity": "1",
"price": "34.50"
}
]order_id,product,quantity,price ORD-7291,Wireless Keyboard,2,49.99 ORD-7292,USB-C Hub,1,34.50
"2", "49.99"). CSV سیستم نوع ندارد — هر مقدار یک رشته است. رفع این مشکل در بخش تبدیل نوع پایینتر توضیح داده شده است.json.dumps() — سریالسازی دیکشنری Python به رشته JSON
ماژول json با هر نصب Python ارائه میشود — نیازی به pip install نیست. json.dumps(obj) یک شیء Python (dict، list، رشته، عدد، bool یا None) میگیرد و یک str حاوی JSON معتبر برمیگرداند. یک دیکشنری Python به یک شیء JSON شبیه است، اما اساساً متفاوتند: dict یک ساختار داده Python در حافظه است، و رشته JSON متن سریالسازیشده است. فراخوانی json.dumps() این شکاف را پر میکند.
مثال ساده — تبدیل یک ردیف CSV به JSON
import json
# A single CSV row represented as a Python dict
server_entry = {
"hostname": "web-prod-03",
"ip_address": "10.0.12.47",
"port": 8080,
"region": "eu-west-1"
}
# Convert dict to JSON string
json_string = json.dumps(server_entry)
print(json_string)
# {"hostname": "web-prod-03", "ip_address": "10.0.12.47", "port": 8080, "region": "eu-west-1"}
print(type(json_string))
# <class 'str'>این یک JSON فشرده تکخطی تولید میکند — برای پیلودها و ذخیرهسازی مناسب، برای خواندن بد است. indent=2 را اضافه کنید تا خروجی خوانا داشته باشید:
import json
server_entry = {
"hostname": "web-prod-03",
"ip_address": "10.0.12.47",
"port": 8080,
"region": "eu-west-1"
}
pretty_json = json.dumps(server_entry, indent=2)
print(pretty_json)
# {
# "hostname": "web-prod-03",
# "ip_address": "10.0.12.47",
# "port": 8080,
# "region": "eu-west-1"
# }دو پارامتر دیگر که در تقریباً هر فراخوانی استفاده میکنم: sort_keys=True کلیدهای دیکشنری را به ترتیب الفبایی مرتب میکند (برای مقایسه فایلهای JSON در نسخههای مختلف عالی است)، و ensure_ascii=False کاراکترهای غیر ASCII را به جای escape کردن به دنبالههای \uXXXX حفظ میکند.
import json
warehouse_record = {
"sku": "WH-9031",
"location": "انبار تهران ۳",
"quantity": 240,
"last_audit": "2026-03-10"
}
output = json.dumps(warehouse_record, indent=2, sort_keys=True, ensure_ascii=False)
print(output)
# {
# "last_audit": "2026-03-10",
# "location": "انبار تهران ۳",
# "quantity": 240,
# "sku": "WH-9031"
# }یادداشتی درباره پارامتر separators: مقدار پیشفرض (", ", ": ") است که پس از کاما و دونقطه فاصله اضافه میکند. برای فشردهترین خروجی ممکن (مفید برای جاسازی JSON در پارامترهای URL یا کاهش حجم پاسخهای API)، separators=(",", ":") را پاس دهید.
json.dumps() مقدار Python True را به JSON true تبدیل میکند، None را به null، و رشتهها را در علامت نقلقول دوگانه میگذارد (Python نقلقول تکی را مجاز میداند، JSON نه). همیشه از json.dumps() برای تولید JSON معتبر استفاده کنید — به str() یا repr() اعتماد نکنید.از csv.DictReader تا فایل JSON — فرایند کامل تبدیل
رایجترین کار واقعی خواندن یک فایل CSV کامل و ذخیره آن به صورت JSON است. در اینجا اسکریپت کامل در کمتر از ۱۰ خط آمده است. csv.DictReader یک iterator از اشیاء dict تولید میکند — یکی در ازای هر ردیف، با استفاده از خط اول به عنوان کلید. دادن آن به list() تمام ردیفها را در یک لیست Python جمع میکند که به آرایه JSON تبدیل میشود.
import csv
import json
# Step 1: Read CSV rows into a list of dicts
with open("inventory.csv", "r", encoding="utf-8") as csv_file:
rows = list(csv.DictReader(csv_file))
# Step 2: Write the list as a JSON file
with open("inventory.json", "w", encoding="utf-8") as json_file:
json.dump(rows, json_file, indent=2, ensure_ascii=False)
print(f"Converted {len(rows)} rows to inventory.json")دو فراخوانی open(): یکی برای خواندن CSV، یکی برای نوشتن JSON. این کل الگو است. توجه کنید که اینجا از json.dump() (بدون s) استفاده میشود — مستقیماً در فایل مینویسد. استفاده از json.dumps() یک رشته برمیگرداند که بعد باید با f.write() جداگانه بنویسید. json.dump() کارایی حافظه بیشتری دارد چون خروجی را جریانی مینویسد به جای اینکه ابتدا کل رشته را در حافظه بسازد.
وقتی JSON را به صورت رشته نیاز دارید نه فایل — برای جاسازی در پیلود API، چاپ در stdout، یا درج در ستون پایگاه داده — از json.dumps() استفاده کنید:
import csv
import json
with open("sensors.csv", "r", encoding="utf-8") as f:
rows = list(csv.DictReader(f))
# Get the JSON as a string instead of writing to a file
json_payload = json.dumps(rows, indent=2)
print(json_payload)
# [
# {
# "sensor_id": "TMP-4401",
# "location": "ساختمان ۷ - طبقه ۲",
# "reading": "22.4",
# "unit": "celsius"
# },
# ...
# ]ردیف تکی در مقابل کل مجموعه داده: اگر json.dumps(single_dict) را فراخوانی کنید یک شیء JSON ({...}) میگیرید. با json.dumps(list_of_dicts) یک آرایه JSON ([{...}, {...}]) میگیرید. شکل ظرف بیرونی به آنچه پاس میدهید بستگی دارد. اکثر APIها و سرویسهایی که این داده را میگیرند برای دادههای جدولی انتظار آرایه دارند.
مدیریت مقادیر غیررشتهای — تبدیل نوع از CSV
این چیزی است که دفعه اول همه را غافلگیر میکند: csv.DictReader هر مقدار را به صورت رشته برمیگرداند. عدد 42 در CSV به رشته "42" در دیکشنری تبدیل میشود. اگر آن را مستقیماً با json.dumps() سریالسازی کنید، JSON شما "quantity": "42" خواهد داشت به جای "quantity": 42. APIهایی که نوعها را تأیید میکنند این را رد خواهند کرد. باید مقادیر را به صراحت تبدیل کنید.
import csv
import json
def coerce_types(row: dict) -> dict:
"""Convert string values to appropriate Python types."""
return {
"sensor_id": row["sensor_id"],
"location": row["location"],
"temperature": float(row["temperature"]),
"humidity": float(row["humidity"]),
"battery_pct": int(row["battery_pct"]),
"active": row["active"].lower() == "true",
}
with open("sensor_readings.csv", "r", encoding="utf-8") as f:
rows = [coerce_types(row) for row in csv.DictReader(f)]
print(json.dumps(rows[0], indent=2))
# {
# "sensor_id": "TMP-4401",
# "location": "ساختمان ۷ - طبقه ۲",
# "temperature": 22.4,
# "humidity": 58.3,
# "battery_pct": 87,
# "active": true
# }اکنون temperature یک float، battery_pct یک عدد صحیح، و active یک boolean در خروجی JSON است. تابع تبدیل نوع مخصوص طرح CSV شما است — هیچ روش عمومی برای حدس زدن انواع از دادههای CSV وجود ندارد، بنابراین برای هر قالب CSV یک تابع مینویسم.
سریالسازی اشیاء سفارشی و انواع غیراستاندارد
ماژول json Python نمیتواند datetime، UUID، Decimal، یا کلاسهای سفارشی را به صورت پیشفرض سریالسازی کند. فراخوانی json.dumps() روی هر کدام از اینها یک TypeError پرتاب میکند. دو رویکرد این مشکل را حل میکنند.
رویکرد ۱: پارامتر default=
یک تابع به default= پاس دهید که انواع ناشناخته را به چیزی قابل سریالسازی تبدیل کند. این تابع فقط برای اشیایی فراخوانی میشود که encoder JSON نمیداند چطور مدیریت کند.
import json
from datetime import datetime
from decimal import Decimal
from uuid import UUID
def json_serial(obj):
"""Fallback serializer for non-standard types."""
if isinstance(obj, datetime):
return obj.isoformat()
if isinstance(obj, UUID):
return str(obj)
if isinstance(obj, Decimal):
return float(obj)
raise TypeError(f"Type {type(obj).__name__} is not JSON serializable")
transaction = {
"txn_id": UUID("a1b2c3d4-e5f6-7890-abcd-ef1234567890"),
"amount": Decimal("149.99"),
"currency": "EUR",
"processed_at": datetime(2026, 3, 15, 14, 30, 0),
"gateway": "stripe",
}
print(json.dumps(transaction, indent=2, default=json_serial))
# {
# "txn_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
# "amount": 149.99,
# "currency": "EUR",
# "processed_at": "2026-03-15T14:30:00",
# "gateway": "stripe"
# }TypeError را در انتهای تابع default= برای انواع ناشناخته پرتاب کنید. اگر None برگردانید یا آنها را بیصدا نادیده بگیرید، null در خروجی خواهید داشت بدون هیچ نشانهای که داده از دست رفته است.رویکرد ۲: Dataclasses با asdict()
Python dataclasses یک تعریف نوع مناسب برای ردیفهای CSV شما میدهند. از dataclasses.asdict() برای تبدیل یک نمونه dataclass به یک دیکشنری ساده استفاده کنید، سپس آن را به json.dumps() پاس دهید.
import json
from dataclasses import dataclass, asdict
from datetime import datetime
@dataclass
class ShipmentRecord:
tracking_id: str
origin: str
destination: str
weight_kg: float
shipped_at: datetime
def json_serial(obj):
if isinstance(obj, datetime):
return obj.isoformat()
raise TypeError(f"Not serializable: {type(obj).__name__}")
shipment = ShipmentRecord(
tracking_id="SHP-9827",
origin="تهران",
destination="اصفهان",
weight_kg=1240.5,
shipped_at=datetime(2026, 3, 12, 8, 0, 0),
)
print(json.dumps(asdict(shipment), indent=2, default=json_serial))
# {
# "tracking_id": "SHP-9827",
# "origin": "تهران",
# "destination": "اصفهان",
# "weight_kg": 1240.5,
# "shipped_at": "2026-03-12T08:00:00"
# }asdict() به صورت بازگشتی dataclasses تودرتو را به دیکشنری تبدیل میکند. اگر dataclass شما حاوی لیستی از dataclasses دیگر باشد، کل درخت تبدیل میشود — نیازی به کد اضافی نیست.مرجع پارامترهای json.dumps()
فهرست کامل آرگومانهای کلیدواژه پذیرفتهشده توسط json.dumps() و json.dump(). هر دو تابع پارامترهای یکسانی میپذیرند — json.dump() یک آرگومان اول اضافه برای شیء فایل میگیرد.
csv.DictReader — خواندن CSV به دیکشنریهای Python
csv.DictReader نیمه دیگر خط تبدیل CSV به JSON است. یک شیء فایل را میپیچد و به ازای هر ردیف یک dict تولید میکند و از خط اول به عنوان نام فیلدها استفاده میکند. در مقایسه با csv.reader (که لیستهای ساده تولید میکند)، DictReader دسترسی با نام به ستونها میدهد — بدون اندیسهای جادویی مثل row[3].
import csv
import json
# Tab-separated file from a database export
with open("user_sessions.tsv", "r", encoding="utf-8") as f:
reader = csv.DictReader(f, delimiter="\t")
sessions = list(reader)
print(json.dumps(sessions[:2], indent=2))
# [
# {
# "session_id": "sess_8f2a91bc",
# "user_id": "usr_4421",
# "started_at": "2026-03-15T09:12:00Z",
# "duration_sec": "342",
# "pages_viewed": "7"
# },
# {
# "session_id": "sess_3c7d44ef",
# "user_id": "usr_1187",
# "started_at": "2026-03-15T09:14:22Z",
# "duration_sec": "128",
# "pages_viewed": "3"
# }
# ]csv.DictReader کل فایل را به صورت تنبل میخواند — ردیفها را یکی یکی تولید میکند. فراخوانی list(reader) تمام ردیفها را در حافظه بارگذاری میکند. برای فایلهای با میلیونها ردیف، به جای جمعآوری همه ردیفها، آنها را به صورت جریانی پردازش کنید.تبدیل CSV از فایل و پاسخ API
دو سناریوی عملیاتی: خواندن یک فایل CSV از دیسک و تبدیل آن، و دریافت دادههای CSV از یک endpoint API (سرویسهای گزارشدهی زیادی CSV برمیگردانند). هر دو به مدیریت خطای مناسب نیاز دارند.
خواندن فایل CSV ← تبدیل ← نوشتن JSON
import csv
import json
import sys
def csv_to_json_file(csv_path: str, json_path: str) -> int:
"""Convert a CSV file to JSON. Returns the number of rows written."""
try:
with open(csv_path, "r", encoding="utf-8") as f:
rows = list(csv.DictReader(f))
except FileNotFoundError:
print(f"Error: {csv_path} not found", file=sys.stderr)
sys.exit(1)
except csv.Error as e:
print(f"CSV parse error in {csv_path}: {e}", file=sys.stderr)
sys.exit(1)
with open(json_path, "w", encoding="utf-8") as f:
json.dump(rows, f, indent=2, ensure_ascii=False)
return len(rows)
count = csv_to_json_file("fleet_vehicles.csv", "fleet_vehicles.json")
print(f"Wrote {count} records to fleet_vehicles.json")دریافت CSV از API ← پردازش ← JSON
import csv
import io
import json
import urllib.request
def fetch_csv_as_json(url: str) -> str:
"""Fetch CSV from a URL and return it as a JSON string."""
try:
with urllib.request.urlopen(url, timeout=10) as resp:
raw = resp.read().decode("utf-8")
except urllib.error.URLError as e:
raise RuntimeError(f"Failed to fetch {url}: {e}")
reader = csv.DictReader(io.StringIO(raw))
rows = list(reader)
if not rows:
raise ValueError("CSV response was empty or had no data rows")
return json.dumps(rows, indent=2, ensure_ascii=False)
# Example: export endpoint that returns CSV
try:
result = fetch_csv_as_json("https://reports.internal/api/v2/daily-metrics.csv")
print(result)
except (RuntimeError, ValueError) as e:
print(f"Error: {e}")هر دو مثال از encoding="utf-8" صریح در هر باز کردن فایل استفاده میکنند. این برای فایلهای CSV با کاراکترهای غیر ASCII اهمیت دارد — نامهای لهجهدار، آدرسها با کاراکترهای خاص، متن فارسی. بدون کدگذاری صریح، Python به کدگذاری پیشفرض سیستم برمیگردد، که در ویندوز اغلب cp1252 است و کاراکترهای چندبایتی را بیصدا خراب میکند.
تأیید خروجی JSON با json.loads()
پس از تبدیل CSV به رشته JSON، میتوانید نتیجه را با تجزیه دوباره آن با json.loads() تأیید کنید. این رفتوبرگشت مشکلات کدگذاری، دنبالههای escape شکسته، یا الحاق تصادفی رشتهها را که JSON نامعتبر تولید میکنند شناسایی میکند. فراخوانی را در یک بلوک try/except بپیچید.
import json
json_string = json.dumps({"order_id": "ORD-7291", "total": 129.99})
# Verify it is valid JSON by parsing it back
try:
parsed = json.loads(json_string)
print(f"Valid JSON with {len(parsed)} keys")
except json.JSONDecodeError as e:
print(f"Invalid JSON: {e}")
# Valid JSON with 2 keysتبدیل CSV به JSON از خط فرمان
تبدیلهای سریع از ترمینال — بدون نیاز به فایل اسکریپت. فلگ -c Python کد درخطی را اجرا میکند، و میتوانید نتیجه را از طریق python3 -m json.tool برای قالببندی زیبا هدایت کنید.
python3 -c " import csv, json, sys rows = list(csv.DictReader(sys.stdin)) json.dump(rows, sys.stdout, indent=2) " < inventory.csv > inventory.json
python3 -c "import csv,json,sys; print(json.dumps(list(csv.DictReader(sys.stdin))))" < data.csv | python3 -m json.tool
python3 -c "import csv,json,sys; json.dump(list(csv.DictReader(sys.stdin)),sys.stdout)" < report.csv | jq .
python3 -m json.tool قالبساز JSON داخلی است. JSON را از stdin میخواند، تأیید میکند و با تورفتگی ۴ فاصله چاپ میکند. برای تأیید اینکه تبدیل CSV به JSON خروجی معتبری تولید کرده مفید است. اگر تورفتگی ۲ فاصله را ترجیح میدهید یا به فیلترکردن نیاز دارید، از jq استفاده کنید.جایگزین پرسرعت — orjson
ماژول داخلی json برای اکثر فایلهای CSV مناسب است. اما اگر مجموعه دادههایی با دهها هزار ردیف را در یک حلقه پردازش میکنید، یا API شما باید دادههای مشتقشده از CSV را در هر درخواست سریالسازی کند، orjson ۵–۱۰ برابر سریعتر است. با Rust نوشته شده، به جای str مقدار bytes برمیگرداند، و datetime، UUID و numpy arrays را بدون تابع سفارشی default= سریالسازی میکند.
pip install orjson
import csv
import orjson
with open("telemetry_events.csv", "r", encoding="utf-8") as f:
rows = list(csv.DictReader(f))
# orjson.dumps() returns bytes, not str
json_bytes = orjson.dumps(rows, option=orjson.OPT_INDENT_2)
with open("telemetry_events.json", "wb") as f: # note: "wb" for bytes
f.write(json_bytes)
print(f"Wrote {len(rows)} events ({len(json_bytes)} bytes)")API کمی متفاوت است: orjson.dumps() مقدار bytes برمیگرداند و به جای آرگومانهای کلیدواژه از فلگهای option= استفاده میکند. هنگام نوشتن خروجی orjson فایلها را در حالت نوشتن دودویی ("wb") باز کنید. اگر رشته نیاز دارید، .decode("utf-8") را روی نتیجه فراخوانی کنید.
خروجی ترمینال با رنگآمیزی سینتکس — rich
اشکالزدایی تبدیلهای CSV به JSON در ترمینال با خروجی رنگی آسانتر میشود. کتابخانه rich JSON را با رنگآمیزی سینتکس نمایش میدهد — کلیدها، رشتهها، اعداد و مقادیر بولی هر کدام رنگ خاص خود را دارند.
pip install rich
import csv
import json
from rich.console import Console
from rich.syntax import Syntax
console = Console()
with open("deployment_log.csv", "r", encoding="utf-8") as f:
rows = list(csv.DictReader(f))
json_output = json.dumps(rows[:3], indent=2, ensure_ascii=False)
syntax = Syntax(json_output, "json", theme="monokai", line_numbers=True)
console.print(syntax)rich کدهای escape ANSI به خروجی اضافه میکند. خروجی قالببندیشده با rich را در فایل یا پاسخ API ننویسید — حاوی کاراکترهای کنترلی نامرئی خواهد بود. از rich فقط برای نمایش در ترمینال استفاده کنید.کار با فایلهای CSV بزرگ
بارگذاری یک فایل CSV با حجم ۵۰۰ مگابایت با list(csv.DictReader(f)) کل مجموعه داده را در حافظه تخصیص میدهد، سپس json.dump() کل رشته JSON را روی آن میسازد. برای فایلهای بزرگتر از ۵۰–۱۰۰ مگابایت، به رویکرد جریانی یا NDJSON بروید (JSON با جداکننده خط جدید) — یک شیء JSON در هر خط.
NDJSON — یک شیء JSON در هر خط
import csv
import json
def csv_to_ndjson(csv_path: str, ndjson_path: str) -> int:
"""Convert CSV to NDJSON, processing one row at a time."""
count = 0
with open(csv_path, "r", encoding="utf-8") as infile, \
open(ndjson_path, "w", encoding="utf-8") as outfile:
for row in csv.DictReader(infile):
outfile.write(json.dumps(row, ensure_ascii=False) + "\n")
count += 1
return count
rows_written = csv_to_ndjson("access_log.csv", "access_log.ndjson")
print(f"Wrote {rows_written} lines to access_log.ndjson")
# Each line is a standalone JSON object:
# {"timestamp":"2026-03-15T09:12:00Z","method":"GET","path":"/api/v2/orders","status":"200"}
# {"timestamp":"2026-03-15T09:12:01Z","method":"POST","path":"/api/v2/payments","status":"201"}پردازش جریانی با ijson برای ورودی JSON بزرگ
import ijson # pip install ijson
def count_high_value_orders(json_path: str, threshold: float) -> int:
"""Count orders above a threshold without loading the full file."""
count = 0
with open(json_path, "rb") as f:
for item in ijson.items(f, "item"):
if float(item.get("total", 0)) > threshold:
count += 1
return count
# Process a 2 GB JSON file with constant memory usage
high_value = count_high_value_orders("all_orders.json", 500.0)
print(f"Found {high_value} orders above $500")ijson برای خواندن فایلهای JSON بزرگ است — برای نوشتن، الگوی NDJSON بالا مصرف حافظه را صرف نظر از اندازه فایل ثابت نگه میدارد.اشتباهات رایج
مشکل: json.dumps() یک رشته برمیگرداند. نوشتن آن با f.write() کار میکند اما یک رشته میانی غیرضروری در حافظه ایجاد میکند — برای مجموعه دادههای بزرگ اتلاف است.
راهحل: از json.dump(data, f) استفاده کنید تا مستقیماً در شیء فایل بنویسید. خروجی را بدون ساختن کل رشته ابتدا، جریانی مینویسد.
with open("output.json", "w", encoding="utf-8") as f:
json.dump(rows, f, indent=2, ensure_ascii=False) # direct writejson_string = json.dumps(rows, indent=2)
with open("output.json", "w") as f:
f.write(json_string) # unnecessary intermediate stringمشکل: csv.DictReader همه مقادیر را به صورت رشته برمیگرداند. خروجی JSON حاوی "quantity": "5" است به جای "quantity": 5، که مصرفکنندگان API با نوعبندی را خراب میکند.
راهحل: ستونهای عددی را با int() یا float() قبل از سریالسازی به صراحت تبدیل کنید.
rows = list(csv.DictReader(f))
for row in rows:
row["port"] = int(row["port"])
row["workers"] = int(row["workers"])
json.dumps(rows)
# [{"port": 8080, "workers": 4}] ← proper integersrows = list(csv.DictReader(f))
json.dumps(rows)
# [{"port": "8080", "workers": "4"}] ← strings, not numbersمشکل: در ویندوز، کدگذاری پیشفرض cp1252 است. کاراکترهای غیر ASCII (نامهای لهجهدار، متن فارسی) بیصدا خراب میشوند یا UnicodeDecodeError پرتاب میشود.
راهحل: همیشه encoding='utf-8' را هم برای خواندن CSV و هم برای نوشتن JSON به open() پاس دهید.
with open("locations.csv", "r", encoding="utf-8") as f:
rows = list(csv.DictReader(f))with open("locations.csv", "r") as f: # uses system default encoding
rows = list(csv.DictReader(f))مشکل: str(my_dict) سینتکس Python تولید میکند (نقلقول تکی، True، None) که JSON معتبر نیست. APIها و پارسرهای JSON آن را رد میکنند.
راهحل: همیشه از json.dumps() برای تولید JSON معتبر استفاده کنید. True را به true، None را به null تبدیل میکند و از نقلقول دوگانه استفاده میکند.
output = json.dumps({"active": True, "note": None})
# '{"active": true, "note": null}' ← valid JSONoutput = str({"active": True, "note": None})
# "{'active': True, 'note': None}" ← NOT valid JSONjson.dumps() در برابر جایگزینها — مقایسه سریع
برای اکثر تبدیلهای CSV به JSON، ترکیب csv + json از کتابخانه استاندارد انتخاب درستی است: بدون وابستگی، با Python ارائه میشود، همه جا کار میکند. به orjson روی بیاورید وقتی پروفایلسازی نشان دهد سریالسازی گلوگاه است — تفاوت سرعت در مقیاس بزرگ واقعاً محسوس است. از pandas استفاده کنید وقتی قبل از تبدیل به JSON به پاکسازی، فیلتر یا تجمیع داده نیاز دارید. اگر فقط یک تبدیل سریع بدون نوشتن کد میخواهید، ابزار تبدیل آنلاین CSV به JSON آن را فوری انجام میدهد.
سؤالات متداول
تفاوت json.dump() و json.dumps() در Python چیست؟
json.dump(obj, file) خروجی JSON را مستقیماً در یک شیء فایلمانند (هر چیزی با متد .write()) مینویسد. json.dumps(obj) یک رشته با قالب JSON برمیگرداند. از json.dump() هنگام نوشتن در فایل استفاده کنید، از json.dumps() وقتی JSON را به عنوان رشته Python برای ثبت گزارش، جاسازی در پیلود یا ارسال از طریق سوکت نیاز دارید. هر دو آرگومانهای کلیدواژه یکسانی (indent، sort_keys، ensure_ascii، default) میپذیرند.
چطور یک دیکشنری Python را به رشته JSON تبدیل کنم؟
json.dumps(your_dict) را فراخوانی کنید. مقدار بازگشتی یک str حاوی JSON معتبر است. برای خروجی خوانا indent=2 اضافه کنید. اگر دیکشنری شما مقادیر غیر ASCII دارد، ensure_ascii=False را برای حفظ کاراکترهایی مانند حروف لهجهدار یا متن فارسی پاس دهید.
import json
server_config = {"host": "api.internal", "port": 8443, "debug": False}
json_string = json.dumps(server_config, indent=2)
print(json_string)
# {
# "host": "api.internal",
# "port": 8443,
# "debug": false
# }چطور یک لیست از dicts را به عنوان فایل JSON ذخیره کنم؟
یک فایل را در حالت نوشتن با کدگذاری UTF-8 باز کنید، سپس json.dump(your_list, f, indent=2, ensure_ascii=False) را فراخوانی کنید. همیشه از json.dump() (نه json.dumps()) برای خروجی فایل استفاده کنید — مستقیماً در فایل مینویسد بدون ایجاد رشته میانی در حافظه.
import json
records = [
{"order_id": "ORD-4821", "total": 129.99, "currency": "USD"},
{"order_id": "ORD-4822", "total": 89.50, "currency": "EUR"},
]
with open("orders.json", "w", encoding="utf-8") as f:
json.dump(records, f, indent=2, ensure_ascii=False)چرا json.dumps() مقدار True را به true و None را به null تبدیل میکند؟
مقادیر بولی Python (True، False) و None توکنهای معتبر JSON نیستند. مشخصات JSON از true، false و null با حروف کوچک استفاده میکند. json.dumps() این نگاشت را به صورت خودکار انجام میدهد — True به true، False به false و None به null تبدیل میشود. نیازی به تبدیل دستی ندارید. در جهت عکس، json.loads() آنها را به انواع Python برمیگرداند.
هنگام تبدیل دادههای CSV به JSON چطور با اشیاء datetime برخورد کنم؟
یک تابع default= به json.dumps() پاس دهید که اشیاء datetime را به رشتههای ISO 8601 تبدیل کند. تابع default برای هر شیئی که json نمیتواند به صورت پیشفرض سریالسازی کند فراخوانی میشود. برای نمونههای datetime مقدار obj.isoformat() را برگردانید و برای هر چیز دیگری TypeError پرتاب کنید.
import json
from datetime import datetime
def json_default(obj):
if isinstance(obj, datetime):
return obj.isoformat()
raise TypeError(f"Not serializable: {type(obj)}")
event = {"action": "login", "timestamp": datetime(2026, 3, 15, 9, 30, 0)}
print(json.dumps(event, default=json_default))
# {"action": "login", "timestamp": "2026-03-15T09:30:00"}آیا میتوان CSV را بدون pandas به JSON تبدیل کرد؟
بله. کتابخانه استاندارد Python همه چیزی که نیاز دارید را دارد. از csv.DictReader برای خواندن هر ردیف به عنوان دیکشنری استفاده کنید، ردیفها را در یک لیست جمعآوری کنید و با json.dump() یا json.dumps() سریالسازی کنید. هیچ کتابخانه خارجی لازم نیست. pandas تنها ارزش افزودن دارد اگر به پاکسازی داده، تشخیص نوع، یا از قبل در پروژه از آن استفاده میکنید.
import csv
import json
with open("inventory.csv", "r", encoding="utf-8") as csv_file:
rows = list(csv.DictReader(csv_file))
with open("inventory.json", "w", encoding="utf-8") as json_file:
json.dump(rows, json_file, indent=2, ensure_ascii=False)برای یک جایگزین بدون نوشتن هیچ کد Python، ابزار تبدیل CSV به JSON را امتحان کنید — دادههای CSV خود را بچسبانید و فوری خروجی JSON قالببندیشده دریافت کنید.
ابزارهای مرتبط
Maria is a backend developer specialising in Python and API integration. She has broad experience with data pipelines, serialisation formats, and building reliable server-side services. She is an active member of the Python community and enjoys writing practical, example-driven guides that help developers solve real problems without unnecessary theory.
Priya is a data scientist and machine learning engineer who has worked across the full Python data stack — from raw data ingestion and cleaning to model deployment and monitoring. She is passionate about reproducible research, Jupyter-based workflows, and the practical engineering side of ML. She writes about NumPy, Pandas, data serialisation, and the Python patterns that make data pipelines reliable at scale.