CSV (Comma Separated Values) 格式是电子表格和数据库中最常见的输入、输出文件格式。
csv模块实现了 CSV 格式表单数据的读写。其提供了诸如“以兼容 Excel 的方式输出数据文件”或“读取 Excel 程序输出的数据文件”的功能,程序员无需知道 Excel 所采用 CSV 格式的细节。
csv模块中的reader类和writer类可用于读写序列化的数据。也可使用DictReader类和DictWriter类以字典的形式读写数据。
csv 模块定义了以下函数:
csv.
reader
(csvfile,dialect='excel',**fmtparams)
返回一个 reader 对象,该对象将逐行遍历csvfile。
如果csvfile是文件对象,则打开它时应使用newline=''
。
可选参数dialect是用于不同的 CSV 变种的特定参数组。它可以是Dialect类的子类的实例,也可以是list_dialects()函数返回的字符串之一。
另一个可选关键字参数fmtparams可以覆写当前变种格式中的单个格式设置。请参见 变种与格式参数 部分。
import csvfile = open('csvDemo.csv', newline='')csvReader = csv.reader(file, delimiter=' ', quotechar='|')for row in csvReader:for ceil in row:print(ceil)file.close()# output: A1,B1,C1,D1,E1# output: A2,B2,C2,D2,E2# output: A3,B3,C3,D3,E3
csv.
writer
(csvfile,dialect='excel',**fmtparams)
返回一个 writer 对象,该对象负责将用户的数据在给定的文件类对象上转换为带分隔符的字符串。
如果csvfile是一个文件对象,则打开它时应使用newline=''
import csvfile = open('csvDemo.csv', 'a', newline='')csvWriter = csv.writer(file, delimiter=',', quotechar='|', quoting=csv.QUOTE_MINIMAL)row = ['A4', 'B4', 'C4', 'D4', 'E4']csvWriter.writerow(row)rows = [['A5', 'B5', 'C5', 'D5', 'E5'], ['A6', 'B6', 'C6', 'D6', 'E6']]csvWriter.writerows(rows)file.close()
csv.
register_dialect
(name[,dialect[,**fmtparams]])
将 dialect 与 name 关联起来。 name 必须是字符串。
import csvcsv.register_dialect('mySet', delimiter=',', quotechar='|', quoting=csv.QUOTE_MINIMAL)file = open('csvDemo.csv', 'a', newline='')csvWriter = csv.writer(file, 'mySet')row = ['A4', 'B4', 'C4', 'D4', 'E4']csvWriter.writerow(row)rows = [['A5', 'B5', 'C5', 'D5', 'E5'], ['A6', 'B6', 'C6', 'D6', 'E6']]csvWriter.writerows(rows)file.close()
csv.
unregister_dialect
(name)
从变种注册表中删除name对应的变种。如果name不是已注册的变种名称,则抛出Error异常。
import csvcsv.register_dialect('mySet', delimiter=',', quotechar='|', quoting=csv.QUOTE_MINIMAL)file = open('csvDemo.csv', 'a', newline='')csvWriter = csv.writer(file, 'mySet')row = ['A4', 'B4', 'C4', 'D4', 'E4']csvWriter.writerow(row)rows = [['A5', 'B5', 'C5', 'D5', 'E5'], ['A6', 'B6', 'C6', 'D6', 'E6']]csvWriter.writerows(rows)csv.unregister_dialect('mySet')file.close()
csv.
get_dialect
(name)
返回name对应的变种。如果name不是已注册的变种名称,则抛出Error异常。该函数返回的是不可变的Dialect对象。
import csvcsv.register_dialect('mySet', delimiter=',', quotechar='|', quoting=csv.QUOTE_MINIMAL)myDialect=csv.get_dialect('mySet')print(myDialect.delimiter)print(myDialect.quotechar)print(myDialect.quoting)csv.unregister_dialect('mySet')# output: ,# output: |# output: 0
csv.
list_dialects
()
返回所有已注册变种的名称。
import csvcsv.register_dialect('mySet', delimiter=',', quotechar='|', quoting=csv.QUOTE_MINIMAL)print(csv.list_dialects())csv.unregister_dialect('mySet')# output: ['excel', 'excel-tab', 'unix', 'mySet']
csv.
field_size_limit
([new_limit])
返回解析器当前允许的最大字段大小。如果指定了new_limit,则它将成为新的最大字段大小。
import csvprint(csv.field_size_limit())# output: 131072csv.field_size_limit(1024)print(csv.field_size_limit())# output: 1024
csv 模块定义了以下类:
class csv.DictReader(f, fieldnames=None, restkey=None, restval=None, dialect='excel', *args, **kwds)
创建一个对象,该对象在操作上类似于常规 reader,但是将每行中的信息映射到一个 dict,该 dict 的键由 fieldnames 可选参数给出。
fieldnames 参数是一个 sequence。如果省略 fieldnames,则文件 f 第一行中的值将用作字段名。无论字段名是如何确定的,字典都将保留其原始顺序。
如果某一行中的字段多于字段名,则剩余数据会被放入一个列表,并与 restkey 所指定的字段名 (默认为 None) 一起保存。 如果某个非空白行的字段少于字段名,则缺失的值会使用 restval 的值来填充 (默认为 None)。
所有其他可选或关键字参数都传递给底层的 reader 实例。
import csvfile = open('csvDemo.csv', newline='')csvReader = csv.DictReader(file, delimiter=' ', quotechar='|')for row in csvReader:for title in row:print(row[title]) # 第一行作为标题file.close()# output: A2,B2,C2,D2,E2# output: A3,B3,C3,D3,E3
classcsv.
DictWriter
(f,fieldnames,restval='',extrasaction='raise',dialect='excel',*args,**kwds)
创建一个对象,该对象在操作上类似常规 writer,但会将字典映射到输出行。fieldnames参数是由键组成的序列,它指定字典中值的顺序,这些值会按指定顺序传递给writerow()
方法并写入文件f。 如果字典缺少fieldnames中的键,则可选参数restval用于指定要写入的值。 如果传递给writerow()
方法的字典的某些键在fieldnames中找不到,则可选参数extrasaction用于指定要执行的操作。 如果将其设置为默认值'raise'
,则会引发ValueError。 如果将其设置为'ignore'
,则字典中的其他键值将被忽略。 所有其他可选或关键字参数都传递给底层的writer实例。
import csvfrom typing import Mappingfile = open('csvDemo.csv', 'a', newline='')fieldnames = ['A1', 'B2', 'C3', 'D3', 'E3']csvWriter = csv.DictWriter(file, delimiter=',', quotechar='|', quoting=csv.QUOTE_MINIMAL, fieldnames=fieldnames)csvWriter.writeheader()# dict1 = dict()# row = ['A4', 'B4', 'C4', 'D4', 'E4']# for i in range(len(fieldnames)):#dict1[fieldnames[i]] = row[i]# csvWriter.writerow(dict1)row = ['A4', 'B4', 'C4', 'D4', 'E4']dict1 = dict(zip(fieldnames,row))csvWriter.writerow(dict1)rows = [['A5', 'B5', 'C5', 'D5', 'E5'], ['A6', 'B6', 'C6', 'D6', 'E6']]list1 = []for i in range(len(rows)):dict2 = dict(zip(fieldnames, rows[i]))list1.append(dict2)csvWriter.writerows(list1)file.close()
class csv.Dialect
Dialect 类是一个容器类,其属性包含有如何处理双引号、空白符、分隔符等的信息。 由于缺少严格的 CSV 规格描述,不同的应用程序会产生略有差别的 CSV 数据。 Dialect 实例定义了 reader 和 writer 实例将具有怎样的行为。
所有可用的 Dialect 名称会由 list_dialects() 返回,并且它们可由特定的 reader 和 writer 类通过它们的初始化函数 (__init__) 来注册
class csv.excel
excel 类定义了 Excel 生成的 CSV 文件的常规属性。它在变种注册表中的名称是 'excel'。
class csv.excel_tab
excel_tab 类定义了 Excel 生成的、制表符分隔的 CSV 文件的常规属性。它在变种注册表中的名称是 'excel-tab'。
class csv.unix_dialect
unix_dialect 类定义了在 UNIX 系统上生成的 CSV 文件的常规属性,即使用 '\n' 作为换行符,且所有字段都有引号包围。它在变种注册表中的名称是 'unix'。
class csv.Sniffer
Sniffer 类用于推断 CSV 文件的格式。
Sniffer 类提供了两个方法:
sniff(sample, delimiters=None)
分析给定的 sample 并返回一个 Dialect 子类,该子类中包含了分析出的格式参数。如果给出可选的 delimiters 参数,则该参数会被解释为字符串,该字符串包含了可能的有效定界符。
import csvfile = open('csvDemo.csv', newline='')dialect = csv.Sniffer().sniff(file.read(1024))dialect.delimiter = ' 'dialect.quotechar = '|'file.seek(0)reader = csv.reader(file, dialect)for row in reader:for ceil in row:print(ceil)file.close()# output: A1,B2,C3,D3,E3# output: A4,B4,C4,D4,E4# output: A4,B4,C4,D4,E4# output: A4,B4,C4,D4,E4
has_header(sample)
分析 sample 文本(假定为 CSV 格式),如果发现其首行为一组列标题则返回 True。 在检查每一列时,将考虑是否满足两个关键标准之一来估计 sample 是否包含标题:
第二至第 n 行包含数字值第二至第 n 行包含字符串值,其中至少有一个值的长度与该列预期标题的长度不同。
会对第一行之后的二十行进行采样;如果有超过一半的列 + 行符合标准,则返回 True。
import csvfile = open('csvDemo.csv', newline='')dialect = csv.Sniffer().sniff(file.read(5))dialect.delimiter = ' 'dialect.quotechar = '|'file.seek(0)print(csv.Sniffer().has_header(file.read(5)))# output: Truefile.close()
csv模块定义了以下常量:
csv.
QUOTE_ALL
指示writer对象给所有字段加上引号。
csv.
QUOTE_MINIMAL
指示writer对象仅为包含特殊字符(例如定界符、引号字符或行结束符中的任何字符)的字段加上引号。
csv.
QUOTE_NONNUMERIC
指示writer对象为所有非数字字段加上引号。
指示 reader 将所有未用引号引出的字段转换为float类型。
csv.
QUOTE_NONE
指示writer对象不使用引号引出字段。当定界符出现在输出数据中时,其前面应该有转义符。如果未设置转义符,则遇到任何需要转义的字符时,writer 都会抛出Error异常。
指示reader不对引号字符进行特殊处理。
csv模块定义了以下异常:
exceptioncsv.
Error
该异常可能由任何发生错误的函数抛出。
变种与格式参数
创建reader或writer对象时,程序员可以将某个字符串或Dialect类的子类指定为 dialect 参数。
Dialect 类支持以下属性:
Dialect.
delimiter
一个用于分隔字段的单字符,默认为','
。
Dialect.
doublequote
控制出现在字段中的引号字符本身应如何被引出。
当该属性为True时,双写引号字符。默认值为True。如果该属性为False,则在引号字符的前面放置转义符。
如果doublequote是False,且转义符未指定,且在字段中发现引号字符时,会抛出Error异常。
Dialect.
escapechar
一个用于 writer 的单字符,用来在quoting设置为QUOTE_NONE的情况下转义定界符,在doublequote设置为False的情况下转义引号字符。在读取时,escapechar去除了其后所跟字符的任何特殊含义。该属性默认为None,表示禁用转义。
Dialect.
lineterminator
放在writer产生的行的结尾,默认为'\r\n'
。
注解
reader经过硬编码,会识别'\r'
或'\n'
作为行尾,并忽略lineterminator。未来可能会更改这一行为。
Dialect.
quotechar
一个单字符,用于包住含有特殊字符的字段,特殊字符如定界符或引号字符或换行符。默认为'"'
。
Dialect.
quoting
控制 writer 何时生成引号,以及 reader 何时识别引号。该属性可以等于任何QUOTE_*
常量(参见模块内容段落),默认为QUOTE_MINIMAL。
Dialect.
skipinitialspace
如果为True,则忽略定界符之后的空格。默认值为False。
Dialect.
strict
如果为True
,则在输入错误的 CSV 时抛出Error异常。默认值为False
。
Reader 对象
Reader 对象(DictReader实例和reader()函数返回的对象)具有以下公开方法:
csvreader.
__next__
()
返回 reader 的可迭代对象的下一行,它可以是一个列表(如果对象是由reader()返回)或字典(如果是一个DictReader实例),根据当前Dialect来解析。 通常你应当以next(reader)
的形式来调用它。
Reader 对象具有以下公开属性:
csvreader.
dialect
变种描述,只读,供解析器使用。
csvreader.
line_num
源迭代器已经读取了的行数。它与返回的记录数不同,因为记录可能跨越多行。
DictReader 对象具有以下公开属性:
csvreader.
fieldnames
字段名称。如果在创建对象时未传入字段名称,则首次访问时或从文件中读取第一条记录时会初始化此属性。
import csvfile = open('csvDemo.csv', newline='')csvReader = csv.DictReader(file, delimiter=' ', quotechar='|')print(csvReader.line_num)for row in csvReader:print(csvReader.line_num)print(csvReader.fieldnames)file.close()# output: 0# output: 2# output: 3# output: 4# output: A2,B2,C2,D2,E2
Writer 对象
Writer
对象(DictWriter实例和writer()函数返回的对象)具有下面的公开方法。对于Writer
对象,行必须是(一组可迭代的)字符串或数字。对于DictWriter对象,行必须是一个字典,这个字典将字段名映射为字符串或数字(数字要先经过str()转换类型)。请注意,输出的复数会有括号包围。这样其他程序读取 CSV 文件时可能会有一些问题(假设它们完全支持复数)。
csvwriter.
writerow
(row)
将row形参写入到 writer 的文件对象,根据当前Dialect进行格式化。 返回对下层文件对象的write方法的调用的返回值。
csvwriter.
writerows
(rows)
将rows*(即能迭代出多个上述 *row对象的迭代器)中的所有元素写入 writer 的文件对象,并根据当前设置的变种进行格式化。
Writer 对象具有以下公开属性:
csvwriter.
dialect
变种描述,只读,供 writer 使用。
DictWriter 对象具有以下公开方法:
DictWriter.
writeheader
()
在 writer 的文件对象中,写入一行字段名称(字段名称在构造函数中指定),并根据当前设置的变种进行格式化。本方法的返回值就是内部使用的csvwriter.writerow()方法的返回值。