ToolDeck

تبدیل CSV به JSON در Python — راهنمای json.dumps()

·Backend Developer·بررسی‌شده توسطPriya Sharma·منتشر شده

از تبدیل 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= با یک تابع جایگزین سفارشی استفاده کنید.
After · json
Before · json
[
  {
    "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
توجه:توجه کنید که quantity و price در خروجی خام به صورت رشته JSON نمایش داده می‌شوند ("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

Python 3.10+
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 را اضافه کنید تا خروجی خوانا داشته باشید:

Python 3.10+ — pretty-printed output
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 حفظ می‌کند.

Python 3.10+ — sort_keys and ensure_ascii
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=(",", ":") را پاس دهید.

توجه:یک دیکشنری Python و یک شیء JSON در چاپ تقریباً یکسان به نظر می‌رسند. تفاوت: 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 تبدیل می‌شود.

Python 3.10+ — full CSV to JSON conversion
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() استفاده کنید:

Python 3.10+ — CSV rows as JSON string
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هایی که نوع‌ها را تأیید می‌کنند این را رد خواهند کرد. باید مقادیر را به صراحت تبدیل کنید.

Python 3.10+ — type coercion for CSV rows
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 نمی‌داند چطور مدیریت کند.

Python 3.10+ — default= for datetime, UUID, Decimal
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() پاس دهید.

Python 3.10+ — dataclass serialization
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() یک آرگومان اول اضافه برای شیء فایل می‌گیرد.

پارامتر
نوع
مقدار پیش‌فرض
توضیح
obj
Any
(الزامی)
شیء Python برای سریال‌سازی — dict، list، str، int، float، bool، None
indent
int | str | None
None
تعداد فاصله‌ها (یا رشته) در هر سطح تورفتگی. None = خروجی فشرده تک‌خطی
sort_keys
bool
False
کلیدهای دیکشنری را به ترتیب الفبایی در خروجی مرتب می‌کند
ensure_ascii
bool
True
تمام کاراکترهای غیر ASCII را به صورت \\uXXXX escape می‌کند. برای نوشتن مستقیم UTF-8 روی False تنظیم کنید
default
Callable | None
None
تابعی که برای اشیاء غیرقابل سریال‌سازی فراخوانی می‌شود — یک مقدار قابل سریال‌سازی برگردانید یا TypeError پرتاب کنید
separators
tuple[str, str] | None
None
جداکننده‌های (item_separator, key_separator) را بازنویسی می‌کند. از (",", ":") برای خروجی فشرده بدون فاصله استفاده کنید
skipkeys
bool
False
کلیدهای dict که str، int، float، bool یا None نیستند را به جای TypeError نادیده می‌گیرد
allow_nan
bool
True
float("nan")، float("inf")، float("-inf") را مجاز می‌داند. برای پرتاب ValueError روی False تنظیم کنید
cls
Type[JSONEncoder] | None
None
زیرکلاس سفارشی JSONEncoder به جای مقدار پیش‌فرض

csv.DictReader — خواندن CSV به دیکشنری‌های Python

csv.DictReader نیمه دیگر خط تبدیل CSV به JSON است. یک شیء فایل را می‌پیچد و به ازای هر ردیف یک dict تولید می‌کند و از خط اول به عنوان نام فیلدها استفاده می‌کند. در مقایسه با csv.reader (که لیست‌های ساده تولید می‌کند)، DictReader دسترسی با نام به ستون‌ها می‌دهد — بدون اندیس‌های جادویی مثل row[3].

Python 3.10+ — DictReader with custom delimiter
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

Python 3.10+ — file conversion with error handling
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

Python 3.10+ — API CSV response to 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 بپیچید.

Python 3.10+ — round-trip validation
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 برای قالب‌بندی زیبا هدایت کنید.

bash — one-liner CSV to JSON
python3 -c "
import csv, json, sys
rows = list(csv.DictReader(sys.stdin))
json.dump(rows, sys.stdout, indent=2)
" < inventory.csv > inventory.json
bash — pipe CSV file and format with json.tool
python3 -c "import csv,json,sys; print(json.dumps(list(csv.DictReader(sys.stdin))))" < data.csv | python3 -m json.tool
bash — convert and validate with jq
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= سریال‌سازی می‌کند.

bash — install orjson
pip install orjson
Python 3.10+ — CSV to JSON with 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 را با رنگ‌آمیزی سینتکس نمایش می‌دهد — کلیدها، رشته‌ها، اعداد و مقادیر بولی هر کدام رنگ خاص خود را دارند.

bash — install rich
pip install rich
Python 3.10+ — rich JSON output
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 در هر خط

Python 3.10+ — streaming CSV to NDJSON
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 بزرگ

Python 3.10+ — ijson for reading large 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")
توجه:وقتی فایل CSV از ۵۰–۱۰۰ مگابایت بیشتر شد به NDJSON یا پردازش جریانی بروید. ijson برای خواندن فایل‌های JSON بزرگ است — برای نوشتن، الگوی NDJSON بالا مصرف حافظه را صرف نظر از اندازه فایل ثابت نگه می‌دارد.

اشتباهات رایج

استفاده از json.dumps() و سپس نوشتن جداگانه در فایل

مشکل: json.dumps() یک رشته برمی‌گرداند. نوشتن آن با f.write() کار می‌کند اما یک رشته میانی غیرضروری در حافظه ایجاد می‌کند — برای مجموعه داده‌های بزرگ اتلاف است.

راه‌حل: از json.dump(data, f) استفاده کنید تا مستقیماً در شیء فایل بنویسید. خروجی را بدون ساختن کل رشته ابتدا، جریانی می‌نویسد.

After · Python
Before · Python
with open("output.json", "w", encoding="utf-8") as f:
    json.dump(rows, f, indent=2, ensure_ascii=False)  # direct write
json_string = json.dumps(rows, indent=2)
with open("output.json", "w") as f:
    f.write(json_string)  # unnecessary intermediate string
فراموش کردن تبدیل مقادیر رشته‌ای CSV به اعداد

مشکل: csv.DictReader همه مقادیر را به صورت رشته برمی‌گرداند. خروجی JSON حاوی "quantity": "5" است به جای "quantity": 5، که مصرف‌کنندگان API با نوع‌بندی را خراب می‌کند.

راه‌حل: ستون‌های عددی را با int() یا float() قبل از سریال‌سازی به صراحت تبدیل کنید.

After · Python
Before · Python
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 integers
rows = list(csv.DictReader(f))
json.dumps(rows)
# [{"port": "8080", "workers": "4"}]  ← strings, not numbers
حذف encoding='utf-8' هنگام باز کردن فایل

مشکل: در ویندوز، کدگذاری پیش‌فرض cp1252 است. کاراکترهای غیر ASCII (نام‌های لهجه‌دار، متن فارسی) بی‌صدا خراب می‌شوند یا UnicodeDecodeError پرتاب می‌شود.

راه‌حل: همیشه encoding='utf-8' را هم برای خواندن CSV و هم برای نوشتن JSON به open() پاس دهید.

After · Python
Before · Python
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() یا repr() به جای json.dumps()

مشکل: str(my_dict) سینتکس Python تولید می‌کند (نقل‌قول تکی، True، None) که JSON معتبر نیست. APIها و پارسرهای JSON آن را رد می‌کنند.

راه‌حل: همیشه از json.dumps() برای تولید JSON معتبر استفاده کنید. True را به true، None را به null تبدیل می‌کند و از نقل‌قول دوگانه استفاده می‌کند.

After · Python
Before · Python
output = json.dumps({"active": True, "note": None})
# '{"active": true, "note": null}'  ← valid JSON
output = str({"active": True, "note": None})
# "{'active': True, 'note': None}"  ← NOT valid JSON

json.dumps() در برابر جایگزین‌ها — مقایسه سریع

روش
خروجی
JSON معتبر
انواع سفارشی
سرعت
نیاز به نصب
json.dumps()
str
از طریق پارامتر default=
پایه
خیر (stdlib)
json.dump()
نوشتن در فایل
از طریق پارامتر default=
پایه
خیر (stdlib)
csv.DictReader + json
str یا فایل
از طریق پارامتر default=
پایه
خیر (stdlib)
pandas to_json()
str یا فایل
✓ datetime بومی
~۲ برابر سریع‌تر برای داده‌های بزرگ
pip install pandas
orjson.dumps()
bytes
✓ datetime/UUID بومی
۵–۱۰ برابر سریع‌تر
pip install orjson
dataclasses.asdict() + json
str
از طریق پارامتر default=
پایه
خیر (stdlib)
polars write_json()
str یا فایل
✓ datetime بومی
~۳ برابر سریع‌تر برای داده‌های بزرگ
pip install polars

برای اکثر تبدیل‌های 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 را برای حفظ کاراکترهایی مانند حروف لهجه‌دار یا متن فارسی پاس دهید.

Python 3.10+
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()) برای خروجی فایل استفاده کنید — مستقیماً در فایل می‌نویسد بدون ایجاد رشته میانی در حافظه.

Python 3.10+
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 پرتاب کنید.

Python 3.10+
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 تنها ارزش افزودن دارد اگر به پاکسازی داده، تشخیص نوع، یا از قبل در پروژه از آن استفاده می‌کنید.

Python 3.10+
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 قالب‌بندی‌شده دریافت کنید.

ابزارهای مرتبط

MS
Maria SantosBackend Developer

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.

PS
Priya Sharmaبازبین فنی

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.