محتویات ماژول¶

ماژول csv توابع زیر را تعریف می‌کند:

csv.reader(csvfile, /, dialect='excel', **fmtparams)¶

یک شیء خواننده برمی‌گرداند که سطرهای csvfile داده‌شده را پردازش می‌کند. یک csvfile باید یک پیمایش‌پذیر از رشته‌ها باشد، که هرکدام در قالب csv تعریف‌شده‌ی خواننده قرار دارند. csvfile معمولاً یک شیء شبه‌پرونده یا فهرست است. اگر csvfile یک شیء پرونده باشد، باید با newline='' باز شود. [1] می‌توان یک پارامتر اختیاری dialect را ارائه کرد که برای تعریف مجموعه‌ای از پارامترهای مختص یک گویش CSV خاص استفاده می‌شود. این پارامتر ممکن است نمونه‌ای از یک زیرکلاس از کلاس Dialect یا یکی از رشته‌های برگردانده‌شده توسط تابع list_dialects() باشد. می‌توان سایر آرگومان‌های کلیدواژه‌ای اختیاری fmtparams را برای بازنویسی پارامترهای قالب‌بندی جداگانه در گویش فعلی ارائه کرد. برای جزئیات کامل درباره گویش و پارامترهای قالب‌بندی، بخش گویش‌ها و پارامترهای قالب‌بندی را ببینید.

هر ردیف خوانده‌شده از پرونده csv به‌صورت فهرستی از رشته‌ها برگردانده می‌شود. هیچ تبدیل خودکار نوع داده‌ای انجام نمی‌شود، مگر اینکه گزینه قالب QUOTE_NONNUMERIC مشخص شده باشد (در این صورت فیلدهای بدون علامت نقل‌قول به float تبدیل می‌شوند).

یک مثال کوتاه از کاربرد:

>>> import csv
>>> with open('eggs.csv', newline='') as csvfile:
...     spamreader = csv.reader(csvfile, delimiter=' ', quotechar='|')
...     for row in spamreader:
...         print(', '.join(row))
Spam, Spam, Spam, Spam, Spam, Baked Beans
Spam, Lovely Spam, Wonderful Spam

که eggs.csv شامل:

Spam Spam Spam Spam Spam |Baked Beans|
Spam |Lovely Spam| |Wonderful Spam|

csv.writer(csvfile, /, dialect='excel', **fmtparams)¶

یک شیء نویسنده را برمی‌گرداند که مسئول تبدیل داده‌های کاربر به رشته‌های جداشده روی شیء شبه‌پرونده داده‌شده است. csvfile می‌تواند هر شیءای با متد write() باشد. اگر csvfile یک شیء پرونده است، باید با newline='' باز شود [1]. می‌توان یک پارامتر اختیاری dialect را داد که برای تعریف مجموعه‌ای از پارامترهای مختص یک گویش CSV معین استفاده می‌شود. این ممکن است نمونه‌ای از زیرکلاسی از کلاس Dialect یا یکی از رشته‌های برگردانده‌شده توسط تابع list_dialects() باشد. می‌توان سایر آرگومان‌های کلیدواژه‌ای اختیاری fmtparams را برای لغو پارامترهای قالب‌بندی منفرد در گویش فعلی داد. برای جزئیات کامل درباره گویش‌ها و پارامترهای قالب‌بندی، بخش گویش‌ها و پارامترهای قالب‌بندی را ببینید. برای اینکه تا حد امکان برقراری رابط با ماژول‌هایی که DB API را پیاده‌سازی می‌کنند آسان شود، مقدار None به‌صورت رشته خالی نوشته می‌شود. هرچند این تبدیل بازگشت‌پذیر نیست، اما نوشتن مقادیر داده‌ی SQL NULL در پرونده‌های CSV بدون پیش‌پردازش داده‌های برگردانده‌شده از فراخوانی cursor.fetch* را آسان‌تر می‌کند. تمام داده‌های غیررشته‌ای دیگر پیش از نوشته شدن با str() به رشته تبدیل می‌شوند.

یک مثال کوتاه از کاربرد:

import csv
with open('eggs.csv', 'w', newline='') as csvfile:
    spamwriter = csv.writer(csvfile, delimiter=' ',
                            quotechar='|', quoting=csv.QUOTE_MINIMAL)
    spamwriter.writerow(['Spam'] * 5 + ['Baked Beans'])
    spamwriter.writerow(['Spam', 'Lovely Spam', 'Wonderful Spam'])

که eggs.csv را می‌نویسد، شامل:

Spam Spam Spam Spam Spam |Baked Beans|
Spam |Lovely Spam| |Wonderful Spam|

csv.register_dialect(name, /, dialect='excel', **fmtparams)¶

dialect را با name مرتبط می‌کند. name باید یک رشته باشد. می‌توان گویش را با ارسال یک زیرکلاس از Dialect، یا با آرگومان‌های کلیدواژه‌ای fmtparams، یا هر دو مشخص کرد؛ در این حالت آرگومان‌های کلیدواژه‌ای پارامترهای گویش را بازنویسی می‌کنند. برای جزئیات کامل درباره گویش‌ها و پارامترهای قالب‌بندی، بخش گویش‌ها و پارامترهای قالب‌بندی را ببینید.

csv.unregister_dialect(name)¶

گویش مرتبط با name را از رجیستری گویش‌ها حذف کنید. اگر name یک نام گویش ثبت‌شده نباشد، یک Error پرتاب می‌شود.

csv.get_dialect(name)¶

گویش مرتبط با name را برمی‌گرداند. اگر name یک نام گویش ثبت‌شده نباشد، یک Error پرتاب می‌شود. این تابع یک Dialect تغییرناپذیر برمی‌گرداند.

csv.list_dialects()¶

نام تمام گویش‌های ثبت‌شده را برمی‌گرداند.

csv.field_size_limit()¶

csv.field_size_limit(new_limit)

حداکثر اندازه فیلدی که پارسر در حال حاضر مجاز می‌داند را برمی‌گرداند. اگر new_limit داده شود، به حد جدید تبدیل می‌شود.

ماژول csv کلاس‌های زیر را تعریف می‌کند:

class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)¶

یک شیء ایجاد کنید که مانند یک خواننده معمولی عمل می‌کند، اما اطلاعات هر ردیف را به یک dict نگاشت می‌کند که کلیدهای آن توسط پارامتر اختیاری fieldnames مشخص می‌شوند.

پارامتر fieldnames یک sequence است. اگر fieldnames ارائه نشود، مقدارهای ردیف اول پرونده f به‌عنوان fieldnames استفاده می‌شوند و از نتایج حذف خواهند شد. اگر fieldnames ارائه شود، از آن‌ها استفاده می‌شود و ردیف اول در نتایج گنجانده خواهد شد. صرف‌نظر از این‌که fieldnames چگونه تعیین می‌شوند، دیکشنری ترتیب اصلی آن‌ها را حفظ می‌کند.

اگر یک ردیف فیلدهای بیشتری نسبت به fieldnames داشته باشد، داده‌های باقی‌مانده در یک فهرست قرار می‌گیرند و با نام فیلد مشخص‌شده توسط restkey (که مقدار پیش‌فرض آن None است) ذخیره می‌شوند. اگر یک ردیف غیرخالی فیلدهای کمتری نسبت به fieldnames داشته باشد، مقادیر گم‌شده با مقدار restval (که مقدار پیش‌فرض آن None است) پر می‌شوند.

تمام سایر آرگومان‌های اختیاری یا کلیدواژه‌ای به نمونه‌ی زیربنایی reader ارسال می‌شوند.

اگر آرگومان داده‌شده به fieldnames یک پیمایش‌گر باشد، به یک list تبدیل می‌شود.

تغییر یافته در نسخه‌ی 3.6: ردیف‌های برگردانده‌شده اکنون از نوع OrderedDict هستند.

تغییر یافته در نسخه‌ی 3.8: ردیف‌های برگردانده‌شده اکنون از نوع dict هستند.

یک مثال کوتاه از کاربرد:

>>> import csv
>>> with open('names.csv', newline='') as csvfile:
...     reader = csv.DictReader(csvfile)
...     for row in reader:
...         print(row['first_name'], row['last_name'])
...
Eric Idle
John Cleese

>>> print(row)
{'first_name': 'John', 'last_name': 'Cleese'}

که names.csv شامل موارد زیر است:

first_name,last_name
Eric,Idle
John,Cleese

class csv.DictWriter(f, fieldnames, restval='', extrasaction='raise', dialect='excel', *args, **kwds)¶

یک شیء ایجاد کنید که مانند یک نویسنده معمولی عمل می‌کند، اما دیکشنری‌ها را به ردیف‌های خروجی نگاشت می‌کند. پارامتر fieldnames یک دنباله از کلیدها است که ترتیب نوشتن مقادیر موجود در دیکشنری ارسال‌شده به متد writerow() در پرونده f را مشخص می‌کند. پارامتر اختیاری restval مقداری را مشخص می‌کند که در صورت نبودن کلیدی از fieldnames در دیکشنری، نوشته می‌شود. اگر دیکشنری ارسال‌شده به متد writerow() شامل کلیدی باشد که در fieldnames یافت نمی‌شود، پارامتر اختیاری extrasaction مشخص می‌کند که چه عملی باید انجام شود. اگر روی 'raise'، که مقدار پیش‌فرض است، تنظیم شود، یک ValueError پرتاب می‌شود. اگر روی 'ignore' تنظیم شود، مقادیر اضافی در دیکشنری نادیده گرفته می‌شوند. سایر آرگومان‌های اختیاری یا کلیدواژه‌ای به نمونه‌ی زیرین writer ارسال می‌شوند.

توجه داشته باشید که برخلاف کلاس DictReader، پارامتر fieldnames در کلاس DictWriter اختیاری نیست.

اگر آرگومان داده‌شده به fieldnames یک پیمایش‌گر باشد، به یک list تبدیل می‌شود.

یک مثال کوتاه از کاربرد:

import csv

with open('names.csv', 'w', newline='') as csvfile:
    fieldnames = ['first_name', 'last_name']
    writer = csv.DictWriter(csvfile, fieldnames=fieldnames)

    writer.writeheader()
    writer.writerow({'first_name': 'Baked', 'last_name': 'Beans'})
    writer.writerow({'first_name': 'Lovely', 'last_name': 'Spam'})
    writer.writerow({'first_name': 'Wonderful', 'last_name': 'Spam'})

که names.csv را با محتوای زیر می‌نویسد:

first_name,last_name
Baked,Beans
Lovely,Spam
Wonderful,Spam

class csv.Dialect¶

کلاس Dialect یک کلاس دربرگیرنده است که ویژگی‌های آن حاوی اطلاعاتی درباره نحوه مدیریت علامت‌های نقل‌قول دوتایی، فضای خالی، جداکننده‌ها و غیره است. به دلیل نبود یک مشخصه دقیق برای CSV، برنامه‌های مختلف داده‌های CSV با تفاوت‌های ظریف تولید می‌کنند. نمونه‌های Dialect نحوه رفتار نمونه‌های reader و writer را تعریف می‌کنند.

تمام نام‌های موجود Dialect توسط list_dialects() برگردانده می‌شوند، و می‌توان آن‌ها را با کلاس‌های مشخص reader و writer از طریق توابع مقداردهی اولیه (__init__) آن‌ها به این صورت ثبت کرد:

import csv

with open('students.csv', 'w', newline='') as csvfile:
    writer = csv.writer(csvfile, dialect='unix')

class csv.excel¶

کلاس excel ویژگی‌های معمول یک پرونده CSV تولیدشده توسط Excel را تعریف می‌کند. این کلاس با نام گویش (dialect) 'excel' ثبت شده است.

class csv.excel_tab¶

کلاس excel_tab ویژگی‌های معمول یک پرونده جداشده با TAB تولیدشده توسط اکسل را تعریف می‌کند. این کلاس با نام گویش 'excel-tab' ثبت شده است.

class csv.unix_dialect¶

کلاس unix_dialect ویژگی‌های معمول یک پرونده CSV تولیدشده در سیستم‌های UNIX را تعریف می‌کند؛ یعنی استفاده از '\n' به‌عنوان پایان‌دهنده‌ی خط و در علامت نقل‌قول قرار دادن همه‌ی فیلدها. این کلاس با نام گویش 'unix' ثبت شده است.

اضافه شده در نسخه‌ی 3.2.

class csv.Sniffer¶

کلاس Sniffer برای استنتاج قالب یک پرونده CSV استفاده می‌شود.

کلاس Sniffer دو متد ارائه می‌دهد:

sniff(sample, delimiters=None)¶

sample داده‌شده را تحلیل کنید و زیرکلاسی از Dialect برگردانید که پارامترهای یافت‌شده را بازتاب می‌دهد. اگر پارامتر اختیاری delimiters داده شده باشد، به‌عنوان رشته‌ای حاوی نویسه‌هایی تفسیر می‌شود که ممکن است جداکننده‌های معتبری باشند.

اگر چند جداکننده به‌اندازه‌ی یکسان با نمونه سازگار باشند --- برای مثال اگر هر دو ',' و ';' به‌طور منظم هر ردیف را تقسیم کنند --- جداکننده‌های فهرست‌شده در ویژگی preferred ترجیح داده می‌شوند، در آن ترتیب، مهم نیست که هر یک چند بار رخ دهد.

has_header(sample)¶

متن نمونه را تحلیل می‌کند (فرض می‌شود در قالب CSV باشد) و اگر به نظر برسد که ردیف اول مجموعه‌ای از سرستون‌ها است، True را برمی‌گرداند. در بررسی هر ستون، یکی از دو معیار کلیدی برای تخمین اینکه آیا نمونه حاوی سرستون است در نظر گرفته می‌شود:

• ردیف‌های دوم تا n-ام شامل مقادیر عددی هستند

• ردیف‌های دوم تا n-ام شامل رشته‌هایی هستند که در آن‌ها طول دست‌کم یک مقدار با طول سرآیند فرضی آن ستون متفاوت است.

۲۱ ردیف پس از سرآیند نمونه‌برداری می‌شوند؛ اگر بیش از نیمی از ستون‌ها + ردیف‌ها معیارها را برآورده کنند، True برگردانده می‌شود.

نکته

این متد یک هیوریستیک سرانگشتی است و ممکن است هم مثبت‌های کاذب و هم منفی‌های کاذب تولید کند.

کلاس Sniffer ویژگی‌های زیر را دارد:

preferred¶

فهرست جداکننده‌های ترجیح‌داده‌شده برای شکستن تساوی، به ترتیب ترجیح. این قابل تغییر است. مقدار اولیه‌ی آن [',', '\t', ';', ' ', ':'] است.

مثالی برای استفاده از Sniffer:

with open('example.csv', newline='') as csvfile:
    dialect = csv.Sniffer().sniff(csvfile.read(1024))
    csvfile.seek(0)
    reader = csv.reader(csvfile, dialect)
    # ... process CSV file contents here ...

ماژول csv ثابت‌های زیر را تعریف می‌کند:

csv.QUOTE_ALL¶

به اشیای writer دستور می‌دهد که همه فیلدها را داخل علامت نقل‌قول قرار دهند.

csv.QUOTE_MINIMAL¶

به شیء‌های writer دستور می‌دهد که تنها آن فیلدها را نقل‌قول کند که نویسه‌های خاصی مانند delimiter، quotechar، '\r'، '\n' یا هر یک از نویسه‌های موجود در lineterminator را داشته باشند. اگر doublequote برابر با False باشد و escapechar تنظیم شده باشد، quotechar به جای اینکه باعث نقل‌قول شدن فیلد شود، گریز داده می‌شود.

csv.QUOTE_NONNUMERIC¶

به اشیای writer دستور می‌دهد که تمام فیلدهای غیرعددی را در علامت نقل‌قول قرار دهند.

به اشیای reader دستور می‌دهد که همه فیلدهای بدون علامت نقل‌قول را به نوع float تبدیل کنند.

نکته

برخی از انواع عددی، مانند bool، Fraction یا IntEnum، نمایش رشته‌ای دارند که نمی‌توان آن را به float تبدیل کرد. این موارد را نمی‌توان در حالت‌های QUOTE_NONNUMERIC و QUOTE_STRINGS خواند.

csv.QUOTE_NONE¶

به اشیای writer دستور می‌دهد که هرگز فیلدها را با علامت نقل‌قول محصور نکنند. هنگامی که در حالت فعلی، delimiter، quotechar، escapechar، '\r'، '\n' یا هر یک از نویسه‌های موجود در lineterminator در داده خروجی ظاهر شود، نویسه‌ی escapechar فعلی پیش از آن قرار می‌گیرد. اگر escapechar تنظیم نشده باشد، شیء writer در صورت مواجهه با هر نویسه‌ای که نیاز به خنثی کردن دارد، استثنای Error را پرتاب می‌کند. برای جلوگیری از خنثی شدن quotechar، آن را روی None تنظیم کنید.

به اشیای reader دستور می‌دهد که هیچ پردازش خاصی روی نویسه‌های نقل‌قول انجام ندهند.

csv.QUOTE_NOTNULL¶

به اشیای writer دستور می‌دهد که تمام فیلدهایی را که None نیستند، در علامت نقل‌قول قرار دهند. این مشابه QUOTE_ALL است، با این تفاوت که اگر مقدار یک فیلد None باشد، یک رشته خالی (بدون علامت نقل‌قول) نوشته می‌شود.

به اشیای reader دستور می‌دهد که یک فیلد خالی (بدون علامت نقل‌قول) را به‌عنوان None تفسیر کنند و در غیر این صورت مانند QUOTE_ALL رفتار کنند.

اضافه شده در نسخه‌ی 3.12.

csv.QUOTE_STRINGS¶

به اشیای writer دستور می‌دهد که همیشه فیلدهایی را که رشته هستند در علامت نقل‌قول قرار دهند. این مشابه QUOTE_NONNUMERIC است، با این تفاوت که اگر مقدار یک فیلد None باشد، یک رشته‌ی خالی (بدون علامت نقل‌قول) نوشته می‌شود.

به اشیای reader دستور می‌دهد که یک رشته خالی (بدون علامت نقل‌قول) را به‌عنوان None تفسیر کنند و در غیر این صورت مانند QUOTE_NONNUMERIC رفتار کنند.

اضافه شده در نسخه‌ی 3.12.

ماژول csv استثنای زیر را تعریف می‌کند:

exception csv.Error¶

در صورت تشخیص خطا، توسط هر یک از توابع پرتاب می‌شود.

گویش‌ها و پارامترهای قالب‌بندی¶

برای آسان‌تر کردن تعیین قالب رکوردهای ورودی و خروجی، پارامترهای قالب‌بندی خاصی در گویش‌ها (dialects) گروه‌بندی شده‌اند. یک گویش، زیرکلاسی از کلاس Dialect است که شامل ویژگی‌های مختلفی است که قالب پرونده CSV را توصیف می‌کنند. هنگام ایجاد اشیای reader یا writer، برنامه‌نویس می‌تواند یک رشته یا زیرکلاسی از کلاس Dialect را به‌عنوان پارامتر dialect مشخص کند. علاوه بر، یا به‌جای، پارامتر dialect، برنامه‌نویس همچنین می‌تواند پارامترهای قالب‌بندی جداگانه‌ای را مشخص کند که نام‌هایی مشابه ویژگی‌های تعریف‌شده در زیر برای کلاس Dialect دارند.

گویش‌ها از ویژگی‌های زیر پشتیبانی می‌کنند:

Dialect.delimiter¶

یک رشته تک‌نویسه‌ای که برای جدا کردن فیلدها استفاده می‌شود. پیش‌فرض آن ',' است.

Dialect.doublequote¶

کنترل می‌کند که نمونه‌های quotechar که درون یک فیلد ظاهر می‌شوند، خود چگونه باید نقل‌قول شوند. هنگامی که True باشد، نویسه دو برابر می‌شود. هنگامی که False باشد، از escapechar به‌عنوان پیشوندی برای quotechar استفاده می‌شود. مقدار پیش‌فرض آن True است.

در خروجی، اگر doublequote False باشد و هیچ escapechar تنظیم نشده باشد، در صورتی که یک quotechar در یک فیلد یافت شود، Error پرتاب می‌شود.

Dialect.escapechar¶

یک رشته‌ی تک‌نویسه‌ای که نویسنده برای خنثی کردن نویسه‌هایی که نیاز به خنثی‌سازی دارند از آن استفاده می‌کند:

• اگر quoting روی QUOTE_NONE تنظیم شده باشد، delimiter، quotechar، '\r'، '\n' و هر یک از نویسه‌های موجود در lineterminator خنثی می‌شوند؛

• اگر doublequote برابر False باشد، quotechar خنثی می‌شود؛

• خود escapechar.

هنگام خواندن، escapechar هرگونه معنای خاصی را از نویسه‌ی بعدی می‌گیرد. مقدار پیش‌فرض آن None است که خنثی‌سازی را غیرفعال می‌کند.

تغییر یافته در نسخه‌ی 3.10: پیش از این خودِ escapechar گریز داده نمی‌شد، که باعث از دست رفتن آن هنگام خواندن می‌شد.

تغییر یافته در نسخه‌ی 3.11: escapechar خالی مجاز نیست.

Dialect.lineterminator¶

رشته‌ای که برای پایان‌دادن به سطرهای تولیدشده توسط writer استفاده می‌شود. مقدار پیش‌فرض آن '\r\n' است.

نکته

reader به‌صورت سخت‌کد (hard-coded) برای تشخیص '\r' یا '\n' به‌عنوان پایان خط تنظیم شده است و lineterminator را نادیده می‌گیرد. این رفتار ممکن است در آینده تغییر کند.

Dialect.quotechar¶

یک رشته‌ی تک‌نویسه‌ای که برای نقل‌قول کردن فیلدهای حاوی نویسه‌های خاص، مانند delimiter یا quotechar، یا فیلدهای حاوی نویسه‌های خط جدید ('\r'، '\n' یا هر یک از نویسه‌های موجود در lineterminator) استفاده می‌شود. مقدار پیش‌فرض آن '"' است. در صورتی که quoting روی QUOTE_NONE تنظیم شده باشد، می‌توان آن را روی None تنظیم کرد تا از خنثی کردن '"' جلوگیری شود.

تغییر یافته در نسخه‌ی 3.11: quotechar خالی مجاز نیست.

Dialect.quoting¶

کنترل می‌کند که چه زمانی علامت‌های نقل‌قول باید توسط نویسنده تولید و توسط خواننده شناسایی شوند. این مقدار می‌تواند هر یک از ثابت‌های QUOTE_* را بپذیرد و اگر quotechar برابر None نباشد، پیش‌فرض آن QUOTE_MINIMAL است و در غیر این صورت QUOTE_NONE است.

Dialect.skipinitialspace¶

هنگامی که True باشد، فاصله‌های بلافاصله پس از delimiter نادیده گرفته می‌شوند. مقدار پیش‌فرض False است. هنگام ترکیب delimiter=' ' با skipinitialspace=True، فیلدهای خالی بدون علامت نقل‌قول مجاز نیستند.

Dialect.strict¶

هنگامی که True باشد، در صورت ورودی CSV نامعتبر، استثنای Error پرتاب می‌شود. مقدار پیش‌فرض False است.

شیءهای خواننده¶

اشیای Reader (نمونه‌های DictReader و اشیای برگردانده‌شده از تابع reader()) دارای متدهای عمومی زیر هستند:

csvreader.__next__()¶

ردیف بعدی شیء پیمایش‌پذیر reader را به‌عنوان یک فهرست (اگر شیء از reader() بازگردانده شده باشد) یا یک دیکشنری (اگر یک نمونه DictReader باشد)، تجزیه‌شده بر اساس Dialect جاری، برمی‌گرداند. معمولاً باید آن را به‌صورت next(reader) فراخوانی کنید.

اشیای Reader دارای ویژگی‌های عمومی زیر هستند:

csvreader.dialect¶

توضیحی فقط‌خواندنی درباره‌ی گویش (dialect) مورد استفاده‌ی پارسر .

csvreader.line_num¶

تعداد سطرهای خوانده‌شده از پیمایش‌گر منبع. این تعداد با تعداد رکوردهای برگردانده‌شده یکسان نیست، زیرا رکوردها می‌توانند شامل چندین خط باشند.

اشیای DictReader ویژگی عمومی زیر را دارند:

DictReader.fieldnames¶

اگر هنگام ایجاد شیء به‌عنوان پارامتر ارسال نشده باشد، این ویژگی در اولین دسترسی یا هنگام خواندن اولین رکورد از پرونده مقداردهی اولیه می‌شود.

شیءهای نویسنده¶

اشیای writer (نمونه‌های DictWriter و اشیایی که تابع writer() برمی‌گرداند) دارای متدهای عمومی زیر هستند. برای اشیای writer، یک ردیف باید یک پیمایش‌پذیر از رشته‌ها یا اعداد باشد و برای اشیای DictWriter باید یک دیکشنری باشد که نام فیلدها را به رشته‌ها یا اعداد نگاشت می‌کند (با اعمال str() روی آن‌ها در ابتدا). توجه داشته باشید که اعداد مختلط با پرانتز در اطرافشان نوشته می‌شوند. این موضوع ممکن است برای برنامه‌های دیگری که پرونده‌های CSV را می‌خوانند (اگر اصلاً از اعداد مختلط پشتیبانی کنند) مشکلاتی ایجاد کند.

csvwriter.writerow(row, /)¶

پارامتر row را در شیء فایلِ نویسنده، با قالب‌بندی مطابق Dialect جاری بنویسید. مقدار بازگشتیِ فراخوانی متد write شیء پرونده زیربنایی را برگردانید.

تغییر یافته در نسخه‌ی 3.5: پشتیبانی از پیمایش‌پذیرهای دلخواه افزوده شد.

csvwriter.writerows(rows, /)¶

تمام عناصر موجود در rows (یک پیمایش‌پذیر از اشیای row همان‌گونه که در بالا توضیح داده شد) را در شیء پرونده نویسنده می‌نویسد، به‌صورت قالب‌بندی‌شده بر اساس گویش (dialect) جاری.

اشیای Writer دارای ویژگی عمومی زیر هستند:

csvwriter.dialect¶

توضیحی فقط‌خواندنی از گویش (dialect) که نویسنده از آن استفاده می‌کند.

اشیای DictWriter دارای متد عمومی زیر هستند:

DictWriter.writeheader()¶

ردیفی شامل نام فیلدها (همان‌طور که در سازنده مشخص شده است) را در شیء فایلِ نویسنده بنویسید؛ این ردیف مطابق گویش (dialect) جاری قالب‌بندی می‌شود. مقدار بازگشتیِ فراخوانی داخلی csvwriter.writerow() را برگردانید.

اضافه شده در نسخه‌ی 3.2.

تغییر یافته در نسخه‌ی 3.8: writeheader() اکنون نیز مقداری را که متد csvwriter.writerow()، که به‌صورت داخلی استفاده می‌شود، برمی‌گرداند، برمی‌گرداند.

مثال‌ها¶

ساده‌ترین مثال برای خواندن یک پرونده CSV:

import csv
with open('some.csv', newline='') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

خواندن یک پرونده با قالب جایگزین:

import csv
with open('passwd', newline='') as f:
    reader = csv.reader(f, delimiter=':', quoting=csv.QUOTE_NONE)
    for row in reader:
        print(row)

ساده‌ترین مثال ممکن برای نوشتن، متناظر با آن، به این صورت است:

import csv
with open('some.csv', 'w', newline='') as f:
    writer = csv.writer(f)
    writer.writerows(someiterable)

از آنجا که تابع open() برای گشودن یک پرونده‌ی CSV به منظور خواندن استفاده می‌شود، پرونده به طور پیش‌فرض با استفاده از UTF-8 به یونیکد رمزگشایی خواهد شد. برای رمزگشایی یک پرونده با استفاده از یک کدگذاری متفاوت، از آرگومان encoding در open استفاده کنید:

import csv
with open('some.csv', newline='', encoding='latin-1') as f:
    reader = csv.reader(f)
    for row in reader:
        print(row)

همین امر برای نوشتن با کدگذاری‌ای غیر از کدگذاری پیش‌فرض نیز صدق می‌کند: هنگام گشودن پرونده‌ی خروجی، آرگومان encoding را مشخص کنید.

ثبت یک گویش جدید:

import csv
csv.register_dialect('unixpwd', delimiter=':', quoting=csv.QUOTE_NONE)
with open('passwd', newline='') as f:
    reader = csv.reader(f, 'unixpwd')

یک کاربرد کمی پیشرفته‌تر از reader --- گرفتن و گزارش خطاها:

import csv, sys
filename = 'some.csv'
with open(filename, newline='') as f:
    reader = csv.reader(f)
    try:
        for row in reader:
            print(row)
    except csv.Error as e:
        sys.exit(f'file {filename}, line {reader.line_num}: {e}')

و با وجود اینکه ماژول مستقیماً از تجزیه‌ی رشته‌ها پشتیبانی نمی‌کند، این کار به‌راحتی قابل انجام است:

import csv
for row in csv.reader(['one,two,three']):
    print(row)

پانویس‌ها