pandas.read_table#
- pandas.read_table(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, skip_blank_lines=True, parse_dates=None, 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', low_memory=True, memory_map=False, float_precision=None, storage_options=None, dtype_backend=<no_default>)[源代码][源代码]#
将通用分隔文件读取到 DataFrame 中。
还支持选择性地迭代或将文件拆分成块。
额外的帮助可以在 IO 工具 的在线文档中找到。
- 参数:
- filepath_or_bufferstr, 路径对象或类文件对象
任何有效的字符串路径都是可接受的。该字符串可以是一个URL。有效的URL方案包括http、ftp、s3、gs和file。对于文件URL，需要一个主机。一个本地文件可以是：file://localhost/path/to/table.csv。
如果你想传递一个路径对象，pandas 接受任何
os.PathLike。文件类对象，我们指的是具有
read()方法的对象，例如文件句柄（例如通过内置的open函数）或StringIO。- sep : str, 默认 ‘t’ (制表符)str, 默认 ‘t’ (制表符)
作为分隔符的字符或正则表达式模式。如果
sep=None，C 引擎无法自动检测分隔符，但 Python 解析引擎可以，这意味着将使用后者并自动通过 Python 的内置嗅探工具csv.Sniffer从文件的第一行有效行中检测分隔符。此外，长度超过 1 个字符且不同于'\s+'的分隔符将被解释为正则表达式，并且也将强制使用 Python 解析引擎。请注意，正则表达式分隔符容易忽略带引号的数据。正则表达式示例：'\r\t'。- 分隔符str, 可选
sep的别名。- 标题int, int 序列, ‘infer’ 或 None, 默认 ‘infer’
包含列标签和标记数据开始的行号（从零开始索引）。默认行为是推断列名：如果没有传递
names，则行为与header=0相同，并且从文件的第一行推断列名；如果显式传递列名给names，则行为与header=None相同。显式传递header=0以能够替换现有名称。header 可以是一个整数列表，指定列上MultiIndex的行位置，例如[0, 1, 3]。未指定的中间行将被跳过（例如，此示例中跳过 2）。请注意，如果skip_blank_lines=True，此参数会忽略注释行和空行，因此header=0表示数据的第一行而不是文件的第一行。当从文件内容推断时，标题通过使用形式为
".{count}"的数字后缀重命名重复名称来彼此区分，从1开始，例如"foo"和"foo.1"。空标题命名为"Unnamed: {i}"或"Unnamed: {i}_level_{level}"在 MultiIndex 列的情况下。- 名称可哈希序列，可选
要应用的列标签序列。如果文件包含标题行，则应显式传递
header=0以覆盖列名。此列表中不允许有重复项。- index_col可哈希的，可哈希序列或假，可选
用作行标签的列，可以用列标签或列索引表示。如果给定的是标签或索引的序列，将为行标签形成
MultiIndex。注意：
index_col=False可以用来强制 pandas 不 使用第一列作为索引，例如，当你有一个每行末尾带有分隔符的格式错误的文件时。- usecols可哈希或可调用序列，可选
要选择的列的子集，由列标签或列索引表示。如果是类列表的，所有元素必须是位置的（即文档列的整数索引）或与列名对应的字符串，这些列名由用户在
names中提供或从文档标题行推断。如果给出了names，则不考虑文档标题行。例如，一个有效的类列表usecols参数可以是[0, 1, 2]或['foo', 'bar', 'baz']。元素顺序被忽略，因此usecols=[0, 1]与[1, 0]相同。要从data实例化一个DataFrame并保留元素顺序，请使用pd.read_csv(data, usecols=['foo', 'bar'])[['foo', 'bar']]以['foo', 'bar']顺序排列列，或pd.read_csv(data, usecols=['foo', 'bar'])[['bar', 'foo']]以['bar', 'foo']顺序排列列。如果可调用，可调用函数将对列名进行评估，返回可调用函数评估为
True的名称。一个有效的可调用参数示例是lambda x: x.upper() in ['AAA', 'BBB', 'DDD']。使用此参数会大大加快解析时间并降低内存使用。- dtypedtype 或 {Hashable} 的字典dtype}, 可选
要应用于整个数据集或单个列的数据类型。例如，
{'a': np.float64, 'b': np.int32, 'c': 'Int64'}使用str或object以及合适的na_values设置来保留并不解释dtype。如果指定了converters，它们将代替dtype转换应用。Added in version 1.5.0:
defaultdict的支持已添加。将defaultdict指定为输入，其中默认值决定了未明确列出的列的dtype。- 引擎{‘c’, ‘python’, ‘pyarrow’}, 可选
使用的解析引擎。C 和 pyarrow 引擎更快，而 python 引擎目前功能更全面。多线程目前仅由 pyarrow 引擎支持。
Added in version 1.4.0: 添加了 ‘pyarrow’ 引擎作为 实验性 引擎，并且某些功能在此引擎上不受支持，或者可能无法正常工作。
- 转换器dict of {可哈希}可调用}, 可选
用于转换指定列中值的函数。键可以是列标签或列索引。
- true_values列表，可选
除了不区分大小写的 ‘True’ 变体外，还应考虑为
True的值。- false_values列表，可选
除了不区分大小写的 ‘False’ 变体之外，还应考虑为
False的值。- skipinitialspace布尔值, 默认为 False
在分隔符后跳过空格。
- skiprowsint, int 列表或可调用对象, 可选
在文件开始处要跳过的行号（从0开始索引）或要跳过的行数（
int）。如果是可调用的，可调用函数将对行索引进行评估，如果该行应被跳过则返回
True，否则返回False。一个有效的可调用参数示例是lambda x: x in [0, 2]。- skipfooterint, 默认 0
文件底部要跳过的行数（
engine='c'不支持）。- nrowsint, 可选
要读取的文件行数。对于读取大文件的部分内容非常有用。指的是返回的 DataFrame 中的数据行数，不包括：
包含列名的标题行。
如果
header=1或更大，则在标题行之前的行。
示例用法：
要读取前 999,999 行（非标题行）：
read_csv(..., nrows=999999)要读取第1,000,000到第1,999,999行：
read_csv(..., skiprows=1000000, nrows=999999)
- na_values可哈希的，可哈希的迭代对象或{可哈希的: 可哈希的}的字典可迭代对象}, 可选
额外的字符串识别为
NA/NaN。如果传递dict，则为特定列的NA值。默认情况下，以下值被解释为NaN：””, “#N/A”, “#N/A N/A”, “#NA”, “-1.#IND”, “-1.#QNAN”, “-NaN”, “-nan”, “1.#IND”, “1.#QNAN”, “<NA>”, “N/A”, “NA”, “NULL”, “NaN”, “None”, “n/a”, “nan”, “null”。- keep_default_na布尔值, 默认为 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布尔值, 默认为 True
检测缺失值标记（空字符串和
na_values的值）。在没有NA值的数据中，传递na_filter=False可以提高读取大文件的性能。- skip_blank_lines布尔值, 默认为 True
如果
True，跳过空白行而不是解释为NaN值。- parse_datesbool, None, 可哈希对象的列表, 默认 None
行为如下：
bool。如果True-> 尝试解析索引。None。如果指定了date_format，则其行为类似于True。list的int或名称。例如，如果[1, 2, 3]-> 尝试将第1、2、3列分别解析为单独的日期列。
如果一列或一个索引不能表示为
datetime的数组，例如因为存在无法解析的值或时区混合，该列或索引将以object数据类型原样返回。对于非标准的datetime解析，请在read_csv()之后使用to_datetime()。注意：对于 iso8601 格式的日期，存在一个快速路径。
- date_formatstr 或 列 -> 格式 的字典, 可选
用于解析日期和/或时间的格式，当与
parse_dates一起使用时。用于解析时间的 strftime，例如"%d/%m/%Y"。有关选择的更多信息，请参阅 strftime 文档，但请注意"%f"将解析到纳秒级。您还可以传递：“ISO8601”，用于解析任何 ISO8601 时间字符串（不一定完全相同的格式）；
“混合”，以单独推断每个元素的格式。这是有风险的，您可能应该与 dayfirst 一起使用。
Added in version 2.0.0.
- dayfirst布尔值, 默认为 False
DD/MM 格式日期，国际和欧洲格式。
- cache_dates布尔值, 默认为 True
如果
True，使用一个唯一的、转换后的日期缓存来应用datetime转换。在解析重复的日期字符串时，尤其是带有时区偏移的字符串时，可能会产生显著的速度提升。- 迭代器布尔值, 默认为 False
返回用于迭代或通过
get_chunk()获取块的TextFileReader对象。- chunksizeint, 可选
每次从文件中读取的行数。传递一个值将导致函数返回一个用于迭代的
TextFileReader对象。有关iterator和chunksize的更多信息，请参阅 IO 工具文档。- 压缩str 或 dict，默认 ‘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}。Added in version 1.5.0: 增加了对 .tar 文件的支持。
在 1.4.0 版本发生变更: Zstandard 支持。
- thousandsstr (长度为1), 可选
在数值中作为千位分隔符的字符。
- decimalstr (长度 1), 默认 ‘.’
识别为小数点的字符（例如，使用 ‘,’ 表示欧洲数据）。
- lineterminatorstr (长度为1), 可选
用于表示换行符的字符。仅在C解析器中有效。
- quotecharstr (长度为1), 可选
用于表示引用项开始和结束的字符。引用项可以包括
delimiter，它将被忽略。- 引用{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中定义的字符。- 双引号布尔值, 默认为 True
当
quotechar被指定且quoting不是QUOTE_NONE时，指示是否将字段内连续的两个quotechar元素解释为单个quotechar元素。- escapecharstr (长度为1), 可选
用于转义其他字符的字符。
- 评论str (长度为1), 可选
指示该行剩余部分不应被解析的字符。如果在行首找到，则该行将完全被忽略。此参数必须是一个字符。像空行（只要
skip_blank_lines=True）一样，完全注释的行被参数header忽略，但不被skiprows忽略。例如，如果comment='#'，解析#empty\na,b,c\n1,2,3并使用header=0将导致'a,b,c'被视为标题。- 编码str, 可选, 默认 ‘utf-8’
读取/写入时使用的编码（例如
'utf-8'）。 Python 标准编码列表。- encoding_errorsstr, 可选, 默认 ‘strict’
如何处理编码错误。 可能的值列表 。
Added in version 1.3.0.
- 方言str 或 csv.Dialect, 可选
如果提供，此参数将覆盖以下参数的值（默认或非默认）：
delimiter、doublequote、escapechar、skipinitialspace、quotechar和quoting。如果需要覆盖值，将发出ParserWarning。有关更多详细信息，请参阅csv.Dialect文档。- on_bad_lines{‘error’, ‘warn’, ‘skip’} 或 Callable, 默认 ‘error’
指定在遇到坏行（字段过多的行）时该怎么做。允许的值有：
'error'，当遇到错误行时引发异常。'warn'，当遇到错误行时发出警告并跳过该行。'skip'，在遇到错误行时，不引发或警告而直接跳过。- 可调用对象，将处理单个错误行的函数。
使用
engine='python'，带有签名(bad_line: list[str]) -> list[str] | None的函数。bad_line是一个由sep分割的字符串列表。如果函数返回None，则坏行将被忽略。如果函数返回一个比预期元素更多的新list字符串，将发出ParserWarning并丢弃多余的元素。使用
engine='pyarrow'，函数签名如 pyarrow 文档中所述：invalid_row_handler。
Added in version 1.3.0.
Added in version 1.4.0: 可调用
在 2.2.0 版本发生变更:
engine='pyarrow'的可调用对象- low_memory布尔值, 默认为 True
在内部以块为单位处理文件，从而在解析时减少内存使用，但可能会导致混合类型推断。为确保没有混合类型，可以设置
False，或者使用dtype参数指定类型。请注意，无论怎样，整个文件都会被读入一个单一的DataFrame，使用chunksize或iterator参数以块的形式返回数据。（仅对C解析器有效）。- memory_map布尔值, 默认为 False
如果为
filepath_or_buffer提供了一个文件路径，则将文件对象直接映射到内存中，并直接从那里访问数据。使用此选项可以提高性能，因为不再有任何 I/O 开销。- float_precision{‘high’, ‘legacy’, ‘round_trip’}, 可选
指定 C 引擎应使用哪个转换器来处理浮点值。选项包括
None或'high'用于普通转换器，'legacy'用于原始的低精度 pandas 转换器，以及'round_trip'用于往返转换器。- storage_optionsdict, 可选
对于特定存储连接有意义的额外选项，例如主机、端口、用户名、密码等。对于HTTP(S) URL，键值对被转发到
urllib.request.Request作为头部选项。对于其他URL（例如以“s3://”和“gcs://”开头），键值对被转发到fsspec.open。请参阅fsspec和urllib了解更多详情，关于存储选项的更多示例请参考 这里。- dtype_backend{‘numpy_nullable’, ‘pyarrow’}
应用于结果
DataFrame的后端数据类型（仍在实验中）。如果未指定，默认行为是不使用可空数据类型。如果指定，行为如下："numpy_nullable": 返回支持可空数据类型的DataFrame"pyarrow": 返回由 pyarrow 支持的可空ArrowDtypeDataFrame
Added in version 2.0.
- 返回:
- DataFrame 或 TextFileReader
逗号分隔值（csv）文件作为带有标记轴的二维数据结构返回。
参见
DataFrame.to_csv将 DataFrame 写入一个逗号分隔值（csv）文件。
read_csv将逗号分隔值（csv）文件读取到 DataFrame 中。
read_fwf将固定宽度格式化的行读取到 DataFrame 中。
例子
>>> pd.read_table('data.csv') Name Value 0 foo 1 1 bar 2 2 #baz 3
可以通过 index_col 和 header 参数指定索引和标题。
>>> pd.read_table('data.csv', header=None) 0 1 0 Name Value 1 foo 1 2 bar 2 3 #baz 3
>>> pd.read_table('data.csv', index_col='Value') Name Value 1 foo 2 bar 3 #baz
列类型是推断出来的，但可以使用 dtype 参数显式指定。
>>> pd.read_table('data.csv', dtype={'Value': float}) Name Value 0 foo 1.0 1 bar 2.0 2 #baz 3.0
True、False 和 NA 值，以及千位分隔符有默认值，但也可以明确指定。提供您希望的字符串或字符串列表！
>>> pd.read_table('data.csv', na_values=['foo', 'bar']) Name Value 0 NaN 1 1 NaN 2 2 #baz 3
可以使用 comment 参数跳过输入文件中的注释行。
>>> pd.read_table('data.csv', comment='#') Name Value 0 foo 1 1 bar 2
默认情况下，带有日期的列将被读取为
object而不是datetime。>>> df = pd.read_table('tmp.csv')
>>> df col 1 col 2 col 3 0 10 10/04/2018 Sun 15 Jan 2023 1 20 15/04/2018 Fri 12 May 2023
>>> df.dtypes col 1 int64 col 2 object col 3 object dtype: object
特定的列可以通过使用 parse_dates 和 date_format 参数解析为日期。
>>> df = pd.read_table( ... 'tmp.csv', ... parse_dates=[1, 2], ... date_format={'col 2': '%d/%m/%Y', 'col 3': '%a %d %b %Y'}, ... )
>>> df.dtypes col 1 int64 col 2 datetime64[ns] col 3 datetime64[ns] dtype: object