Python库pandas之三

输入/输出

read_csv

函数

词法：pandas.read_csv(filepath_or_buffer, *, sep=<no_default>, delimiter=None, header=‘infer’, names=<no_default>, index_col=None, usecols=None, dtype=None, engine=None, converters=None, true_values=None, false_values=None, skipinitialspace=False, skiprows=None, skipfooter=0, nrows=None, na_values=None, keep_default_na=True, na_filter=True, verbose=<no_default>, skip_blank_lines=True, parse_dates=None, infer_datetime_format=<no_default>, keep_date_col=<no_default>, date_parser=<no_default>, date_format=None, dayfirst=False, cache_dates=True, iterator=False, chunksize=None, compression=‘infer’, thousands=None, decimal=‘.’, lineterminator=None, quotechar=‘"’, quoting=0, doublequote=True, escapechar=None, comment=None, encoding=None, encoding_errors=‘strict’, dialect=None, on_bad_lines=‘error’, delim_whitespace=<no_default>, low_memory=True, memory_map=False, float_precision=None, storage_options=None, dtype_backend=<no_default>)

将逗号分隔值 (csv) 文件读入 DataFrame。还支持选择性地迭代或将文件分成块。

参数说明

• filepath_or_buffer, 该参数类型是字符串，path对象或file-like对象。任何有效的字符串路径都是可接受的。
  字符串： URL：有效的 URL 方案包括 http、ftp、s3、gs 和 file。对于文件 URL，需要一个主机。本地文件：file://localhost/path/to/table.csv。
  path对象：pandas 接受任何 os.PathLike。
  类文件对象：我们指的是具有 read() 方法的对象，例如文件句柄（例如通过内置 open 函数）或 StringIO。

• sep，该参数类型是字符串，默认值为 ‘,’。用作分隔符的字符，或正则表达式模式。如果 sep是None，则C 引擎无法自动检测分隔符，但 Python 解析引擎可以，这意味着将使用后者并通过 Python 内置嗅探工具 csv.Sniffer，仅从文件的第一个有效行自动检测分隔符。另外，长度超过1个字符，且与’\s+‘不同的分隔符将被解释为正则表达式，也会强制使用Python解析引擎。请注意，正则表达式分隔符很容易忽略引用的数据。正则表达式示例：’\r\t’。

• delimiter，该参数类型是字符串，是可选的。是sep的别名。

• header，该参数类型是int, int 序列, ‘infer’或者是None, 默认值为‘infer’。包含列标签并标记数据开始的行号（零索引）。默认行为是推断列名称：如果未传递名称，则行为与 header=0 相同，并且从文件的第一行推断列名称，如果列名称显式传递给名称，则行为与 header 相同=无。显式传递 header=0 以便能够替换现有名称。标头可以是一个整数列表，用于指定列上 MultiIndex 的行位置，例如[0,1,3]。未指定的中间行将被跳过（例如，本示例中的 2 行将被跳过）。请注意，如果skip_blank_lines=True，该参数会忽略注释行和空行，因此header=0表示数据的第一行而不是文件的第一行。

• names，该参数类型是可哈希对象序列, 是可选的。要应用的列标签的顺序。如果文件包含标题行，则应显式传递 header=0 来覆盖列名称。此列表中不允许有重复项。

• index_col，该参数类型是可哈希对象, 可哈希对象序列或者是False, 是可选的。用作行标签的列，由列标签或列索引表示。如果给定标签或索引序列，将为行标签形成 MultiIndex。
  index_col=False 可用于强制 pandas 不使用第一列作为索引，例如，当文件格式错误，且每行末尾带有分隔符时。

• usecols，该参数类型是可哈希对象或可调用对象序列, 是可选的。要选择的列的子集，由列标签或列索引表示。如果是类列表，则所有元素必须是位置元素（即文档列中的整数索引）或与用户在名称中提供的列名称或从文档标题行推断出的列名称相对应的字符串。如果给出名称，则不考虑文档标题行。例如，有效的类似列表的 usecols 参数将为 [0, 1, 2] 或 [‘foo’, ‘bar’, ‘baz’]。元素顺序被忽略，因此 usecols=[0, 1] 与 [1, 0] 相同。要从保留元素顺序的数据实例化 DataFrame，请对 [‘foo’, ‘bar’ 中的列使用 pd.read_csv(data, usecols=[‘foo’, ‘bar’])[[‘foo’, ‘bar’]] '] 顺序或 pd.read_csv(data, usecols=[‘foo’, ‘bar’])[[‘bar’, ‘foo’]] 为 [‘bar’, ‘foo’] 顺序。
  如果可调用，则将根据列名称评估可调用函数，返回可调用函数评估为 True 的名称。有效的可调用参数的一个示例是 [‘AAA’, ‘BBB’, ‘DDD’] 中的 lambda x: x.upper()。使用此参数会导致更快的解析时间和更低的内存使用量。

• dtype，该参数类型是dtype，或者{Hashable：dtype}型字典, 是可选的。应用于整个数据集，或单个列的数据类型。例如，{‘a’: np.float64, ‘b’: np.int32, ‘c’: ‘Int64’} 将 str 或 object 与合适的 na_values 设置一起使用，保留，而不是解释 dtype。如果指定了转换器，则将应用它们，而不是dtype转换。

• engine，该参数类型是{‘c’, ‘python’, ‘pyarrow’}, 是可选的。解析器引擎。 C 和 pyarrow 引擎速度更快，而 python 引擎目前功能更完整。目前仅 pyarrow 引擎支持多线程。

• converters，该参数类型是 {Hashable：Callable}型字典, 是可选的。用于转换指定列中的值的函数。键可以是列标签，或列索引。

• true_values，该参数类型是list, 是可选的。除了不区分大小写的“True”变体之外，被视为True的值。

• false_values，该参数类型是list, 是可选的。除了‘False’的不区分大小写的变体之外，被视为False 的值。

• skipinitialspace，该参数类型是bool, 默认值为False。跳过分隔符后的空格。

• skiprows，该参数类型是int, list（元素是int或者Callable）, 是可选的。文件开头要跳过的行号（从 0 开始索引）或要跳过的行数 (int)。
  如果该参数是list可调用，则将根据行索引，评估可调用函数，如果应跳过该行，则返回可调用函数True，否则返回 False。

• skipfooter，该参数类型是int, 默认值为0。文件底部要跳过的行数，如果参数engine是’c’时，则不支持这个功能。

• nrows，该参数类型是int, 是可选的。要读取的文件行数。对于读取大文件很有用。

• na_values，该参数类型是Hashable, Hashable迭代指针，或 {Hashable：Iterable}字典, 是可选的。识别为 NA/NaN 的其他字符串。如果该参数是字典，则特定的每列 NA 值。默认情况下，以下值被解释为 NaN：“ “、 “#N/A”、“#N/A N/A”、 “#NA”、 “-1.#IND”、“-1.#QNAN”、 “-NaN”、“-nan”，“1.#IND”、“1.#QNAN”、“”、 “N/A”、“NA”、“NULL”、“NaN”、 “None” ”、“n/a”、“nan”、“null”。

• keep_default_na，该参数类型是bool, 默认值为True。解析数据时，该参数决定是否包含默认NaN 值。根据是否包含参数 na_values，行为如下：
  如果 keep_default_na 为 True，并且指定了 na_values，则 na_values 会附加到用于解析的默认 NaN 值。
  如果 keep_default_na 为 True，但未指定 na_values，则仅使用默认NaN 值进行解析。
  如果 keep_default_na 为 False，并且指定了 na_values，则仅使用 na_values 指定的 NaN 值进行解析。
  如果 keep_default_na 为 False，并且未指定 na_values，则不会将任何字符串解析为 NaN。
  如果参数na_filter是False，则 keep_default_na 和 na_values 参数将被忽略。

• na_filter，该参数类型是bool, 默认值为True。检测缺失值标记（空字符串和 na_values 的值）。在没有任何NA值的数据中，设置参数na_filter为False，可以提高读取大文件的性能。

• verbose，该参数类型是bool, 默认值为False。指示放置在非数字列中的 NA 值的数量。

• skip_blank_lines，该参数类型是bool, 默认值为True。如果为 True，则跳过空白行，而不是解释为NaN 值。

• parse_dates，该参数类型是bool, 值类型为Hashable的list, 值类型为list的list，或者{Hashable：list}字典, 默认值为False。行为如下：
  该参数类型是bool。如果值是True，尝试解析索引。如果已传递 date_format 或 date_parser 参数，则自动设置为 True。
  该参数类型是int或名称list。例如如果 [1, 2, 3] ，尝试将第 1、2、3 列分别解析为单独的日期列。
  该参数类型是元素为list的list，例如If [[1, 3]]，则合并第1 列和第 3 列，并解析为单个日期列。在解析之前，值会与空格连接。
  该参数类型是字典，例如{‘foo’ : [1, 3]} -> 将第 1、3 列解析为日期，并调用结果“foo”。在解析之前，值会与空格连接。
  如果列或索引无法表示为日期时间数组，比如无法解析的值或时区混合，则列或索引将作为对象数据类型返回而不改变。对于非标准日期时间解析，在 read_csv() 之后，使用 to_datetime()。

• infer_datetime_format，该参数类型是bool, 默认值为False。如果该参数是True，而且parse_dates被使能，则pandas 将尝试推断列中日期时间字符串的格式，如果可以推断，则切换到更快的解析方法。

• keep_date_col，该参数类型是bool, 默认值为False。如果该参数是True，而且parse_dates 指定组合多个列，则保留原始列。

• date_parser，该参数类型是Callable, 是可选的。用于将字符串列序列转换为日期时间实例数组的函数。默认使用 dateutil.parser.parser 进行转换。 pandas 将尝试以三种不同的方式调用 date_parser，如果发生异常，则前进到下一个：

  1. 传递一个或多个数组（由 parse_dates 定义）作为参数调用date_parser；
  2. 将 parse_dates 定义的列中的字符串值连接（按行）到单个数组中，作为参数调用date_parser ；
  3. 使用一个或多个字符串（对应于 parse_dates 定义的列）作为参数，为每一行，调用一次 date_parser 。

• date_format，该参数类型是字符串，或者{column ：format}字典, 是可选的。与 parse_dates 结合使用时，用于解析日期的格式。解析时间的 strftime，例如“%d/%m/%Y”。

• dayfirst，该参数类型是bool, 默认值为False。DD/MM 格式日期、国际和欧洲格式。

• cache_dates，该参数类型是bool, 默认值为True。如果cache_dates为 True，则使用唯一的，已转换日期的缓存，来进行日期时间转换。解析重复的日期字符串时，尤其是具有时区偏移量的字符串时，这样的方法可能会产生显着的加速。

• iterator，该参数类型是bool, 默认值为False。该参数返回TextFileReader对象，进行迭代，或使用 get_chunk() 获取块。

• chunksize，该参数类型是int, 是可选的。每个块从文件中读取的行数。通过这个参数传递一个值，将导致函数返回一个 TextFileReader 对象，进行迭代。

• compression，该参数类型是字符串，或者字典, 默认值为‘infer’。用于磁盘数据的即时解压缩。
  如果“infer”和“filepath_or_buffer”是类路径，则检测以下扩展名的压缩： “.gz”、“.bz2”、 “.zip”、“.xz”、“.zst”、“.tar” 、“.tar.gz”、“.tar.xz”或“.tar.bz2”，否则，没有压缩。
  如果使用 “zip” 或 “tar”，ZIP 文件必须仅包含一个要读入的数据文件。设置为 None 则不解压。
  也可以是键值 ‘method’ 设置为 {‘zip’, ‘gzip’, ‘bz2’, ‘zstd’, ‘xz’, ‘tar’} 之一的字典，其他键值转发到 zipfile.ZipFile、gzip.GzipFile、bz2.BZ2File、zstandard.ZstdDecompressor、lzma.LZMAFile 或 tarfile.TarFile。
  可以使用自定义压缩字典，传递以下内容以进行 Zstandard 解压缩：compression={‘method’: ‘zstd’, ‘dict_data’: my_compression_dict}。

• thousands，该参数类型是字符串(长度为1), 是可选的。使用该字符作为数值中千位分隔符符。

• decimal，该参数类型是字符串(长度为1), 默认值为 ‘.’。使用该字符作为小数点。

• lineterminator，该参数类型是字符串(长度为1), 是可选的。使用该字符作为换行符。仅对 C 解析器有效。

• quotechar，该参数类型是字符串(长度为1), 是可选的。用于表示引用项的开始和结束的字符。引用的项目可以包含分隔符，它将被忽略。

• quoting，该参数类型是{0 或者csv.QUOTE_MINIMAL, 1 或者 csv.QUOTE_ALL, 2 或者 csv.QUOTE_NONNUMERIC, 3 或者 csv.QUOTE_NONE}, 默认值为csv.QUOTE_MINIMAL。根据 csv.QUOTE_* 常量控制字段引用行为。默认值为 csv.QUOTE_MINIMAL（即 0），这意味着，仅包含特殊字符的字段被引用。例如，quotechar、delimiter, 或者lineterminator定义的字符。

• doublequote，该参数类型是bool, 默认值为True。当该函数调用中包含quotechar，并且quoting不是 QUOTE_NONE 时，指示是否将一个字段内的两个连续的 quotechar 元素解释为单个 quotechar 元素。

• escapechar，该参数类型是字符串(长度为1), 是可选的。用于转义其他字符的字符。

• comment，该参数类型是字符串(长度为1), 是可选的。该参数指示不应解析该行剩余部分的字符。
  如果在行的开头找到，则该行将被完全忽略。该参数必须是单个字符。如果skip_blank_lines=True，与空行一样。完全注释的行会被header忽略，但不会被skiprows忽略。例如，如果 comment=‘#’，则使用 header=0 解析 #empty\na,b,c\n1,2,3 将导致 ‘a,b,c’ 被视为标头。

• encoding，该参数类型是字符串(长度为1), 是可选的，默认值为‘utf-8’。读取/写入时，用于 UTF 的编码（例如“utf-8”）。

• dialect，该参数类型是字符串或者csv.Dialect, 是可选的。如果提供该参数，它将覆盖以下参数的值（默认或非默认）：delimiter, doublequote, escapechar, skipinitialspace, quotechar和quoting。如果需要覆盖这些值，将产生ParserWarning。

• on_bad_lines，该参数类型是{‘error’, ‘warn’, ‘skip’} 或者Callable, 默认值为‘error’。指定遇到有问题的行（包含太多字段的行）时，要执行的操作。允许的值为：
  ‘error’，当遇到坏行时引发异常。
  ‘warn’，当遇到坏行时发出警告并跳过该行。
  ‘skip’，跳过坏行，遇到坏行时不引发或警告。

• delim_whitespace，该参数类型是bool, 默认值为False。该参数指定是否将空格（例如“ ”或“\t”）用作 sep 分隔符。相当于设置 sep=‘\s+’。如果该参数设置为True，则不应为delimiter参数传递任何内容。

• low_memory，该参数类型是bool, 默认值为True。在内部，以块的形式处理文件，从而在解析时，减少内存使用，但可能会导致混合类型推断。为了确保没有混合类型，将该参数设置 False，或使用 dtype 参数指定类型。无论如何，整个文件都会读入单个 DataFrame，使用 chunksize 或 iterator 参数，以块的形式返回数据。 该参数仅对 C 解析器有效。

• memory_map，该参数类型是bool, 默认值为False。如果为 filepath_or_buffer 提供了文件路径，则将文件对象直接映射到内存，并直接从那里访问数据。使用此选项可以提高性能，因为不再有任何额外的I/O开销。

• float_precision，该参数类型是{‘high’, ‘legacy’, ‘round_trip’}, 是可选的。指定 C 引擎应使用哪个转换器来处理浮点值。对于普通转换器，选项为 None 或“high”；对于原始较低精度 pandas 转换器，选项为“legacy”；对于往返转换器，选项为“round_trip”。

• storage_options，该参数类型是字典dict, 是可选的。对于特定存储连接有意义的额外选项，例如主机、端口、用户名、密码等。对于 HTTP(S) URL，键值对将作为标头选项转发到 urllib.request.Request。对于其他 URL（例如以“s3://”和“gcs://”开头），键值对将转发到 fsspec.open。

• dtype_backend，该参数类型是{‘numpy_nullable’, ‘pyarrow’}, 默认值为‘numpy_nullable’。应用于生成的 DataFrame 的后端数据类型。行为如下：
  “numpy_nullable”：返回支持 nullable-dtype 的 DataFrame（默认）。
  “pyarrow”：返回 pyarrow 支持的，可为空的 ArrowDtype DataFrame。

应用实列

下面展示一些 内联代码片。

import sys
import pandas as pd

def read_cvs_file(fn):
    col_names = ["name","working age","weight","height","salary"]
    use_cols = [0,1,3,4]
    data_frame = pd.read_csv(fn)
    print(data_frame.to_dict())

    data_frame = pd.read_csv(fn, usecols=use_cols, header=0)
    print(data_frame.to_dict())

    data_frame = pd.read_csv(fn, names=col_names, usecols=use_cols)
    print(data_frame.to_dict())

    data_frame = pd.read_csv(fn, names=col_names, header=0, usecols=use_cols)
    print(data_frame.to_dict())
    
if __name__ == "__main__":
    read_cvs_file(sys.argv[1])

屏幕输出

C:\python_devs>python pandas_io_1.py test_1.csv
{'name': {0: 'John', 1: 'Tom'}, 'age': {0: 35, 1: 45}, 'weight': {0: 150, 1: 170}, 'height': {0: 170, 1: 180}, 'salary': {0: 10000.19, 1: 8000.51}}
{'name': {0: 'John', 1: 'Tom'}, 'age': {0: 35, 1: 45}, 'height': {0: 170, 1: 180}, 'salary': {0: 10000.19, 1: 8000.51}}
{'name': {0: 'name', 1: 'John', 2: 'Tom'}, 'working age': {0: 'age', 1: ' 35', 2: ' 45'}, 'height': {0: 'height', 1: ' 170', 2: ' 180'}, 'salary': {0: 'salary', 1: '10000.19', 2: '8000.51'}}
{'name': {0: 'John', 1: 'Tom'}, 'working age': {0: 35, 1: 45}, 'height': {0: 170, 1: 180}, 'salary': {0: 10000.19, 1: 8000.51}}

test_1.csv文件内容

name,age,weight,height,salary
"John", 35, 150, 170,10000.19
"Tom", 45, 170, 180,8000.51