csv --- خواندن و نوشتن پرونده CSV

کد منبع: Lib/csv.py

---

قالب به‌اصطلاح CSV (مقادیر جداشده با ویرگول) رایج‌ترین قالب ایمپورت و اکسپورت برای صفحات گسترده و پایگاه‌های داده است. قالب CSV سال‌ها پیش از تلاش‌ها برای توصیف این قالب به‌صورت استانداردشده در RFC 4180 استفاده می‌شد. فقدان یک استاندارد خوش‌تعریف به این معناست که اغلب تفاوت‌های ظریفی در داده‌های تولیدشده و مصرف‌شده توسط برنامه‌های کاربردی مختلف وجود دارد. این تفاوت‌ها می‌توانند پردازش پرونده‌های CSV از منابع متعدد را آزاردهنده سازند. با این حال، با وجود اینکه جداکننده‌ها و نویسه‌های نقل‌قول متفاوت‌اند، قالب کلی به‌اندازه‌ای مشابه است که می‌توان یک ماژول واحد نوشت که چنین داده‌هایی را به‌طور کارآمد دست‌کاری کند و جزئیات خواندن و نوشتن داده‌ها را از برنامه‌نویس پنهان کند.

ماژول csv کلاس‌هایی را برای خواندن و نوشتن داده‌های جدولی در قالب CSV پیاده‌سازی می‌کند. این ماژول به برنامه‌نویسان اجازه می‌دهد بگویند: «این داده‌ها را در قالب مورد نظر Excel بنویس» یا «داده‌ها را از این پرونده که توسط Excel تولید شده است بخوان»، بدون آنکه جزئیات دقیق قالب CSV مورد استفاده Excel را بدانند. برنامه‌نویسان همچنین می‌توانند قالب‌های CSV قابل‌فهم برای سایر برنامه‌ها را توصیف کنند یا قالب‌های CSV خاص‌منظور خود را تعریف کنند.

اشیای reader و writer ماژول csv دنباله‌ها را می‌خوانند و می‌نویسند. برنامه‌نویسان همچنین می‌توانند داده‌ها را در قالب دیکشنری با استفاده از کلاس‌های DictReader و DictWriter بخوانند و بنویسند.

همچنین ملاحظه نمائید

PEP 305 - API پرونده‌ی CSV

پیشنهاد بهبود پایتون (Python Enhancement Proposal) که این افزوده را برای پایتون پیشنهاد داد.

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

ماژول 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 داده شده باشد، به‌عنوان رشته‌ای حاوی نویسه‌هایی تفسیر می‌شود که ممکن است جداکننده‌های معتبری باشند.

If several delimiters fit the sample equally well --- for example if both ',' and ';' split every row consistently --- the delimiters listed in the preferred attribute are preferred, in that order, no matter how many times each of them occurs.

has_header(sample)

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

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

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

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

توجه

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

The Sniffer class has the following attribute:

preferred

The list of the delimiters preferred for breaking ties, in the order of preference. It can be modified. Its initial value is [',', '\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

Instructs writer objects to only quote those fields which contain special characters such as delimiter, quotechar, '\r', '\n' or any of the characters in lineterminator. If doublequote is False and escapechar is set, the quotechar is escaped instead of causing the field to be quoted.

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: Previously the escapechar itself was not escaped, which lost it on reading.

تغییر یافته در نسخه‌ی 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)

اشیای 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 جهت خواندن استفاده می‌شود، پرونده به‌طور پیش‌فرض با استفاده از کدگذاری پیش‌فرض سیستم به یونیکد کدگشایی می‌شود (به locale.getencoding() مراجعه کنید). برای کدگشایی یک پرونده با کدگذاری متفاوت، از آرگومان encoding در open استفاده کنید:

import csv
with open('some.csv', newline='', encoding='utf-8') 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)

پانویس‌ها

[1] (1,2)

اگر newline='' مشخص نشود، سطرهای جدید نهفته در فیلدهای نقل‌قول‌شده به‌درستی تفسیر نمی‌شوند، و در سکوهایی که هنگام نوشتن از پایان‌سطرهای \r\n استفاده می‌کنند، یک \r اضافی افزوده می‌شود. مشخص کردن newline='' باید همیشه ایمن باشد، زیرا ماژول csv مدیریت خط جدید (سطرهای جدید همگانی (universal newlines)) خود را انجام می‌دهد.