maxframe.dataframe.read_csv#

maxframe.dataframe.read_csv(path, *, names=None, sep: str = ', ', index_col=None, compression='infer', header='infer', dtype=None, usecols=None, nrows=None, chunk_bytes='64M', gpu=None, head_bytes='100k', head_lines=None, default_index_type: DefaultIndexType | str = None, use_nullable_dtypes: bool = <no_default>, dtype_backend: str = <no_default>, storage_options: dict = None, memory_scale: int = None, merge_small_files: bool = True, merge_small_file_options: dict = None, session=None, run_kwargs: dict = None, **kwargs)[源代码]#

将逗号分隔值（CSV）文件读入 DataFrame。也支持可选地迭代或分块读取文件。

参数:

  • path (str) -- 接受任何有效的字符串路径。该字符串可以是 URL。有效的 URL 协议包括 http、ftp、s3 和 file。对于文件 URL，需要指定主机。本地文件可以是：file://localhost/path/to/table.csv，您也可以通过 URL 从外部资源读取，例如：hdfs://localhost:8020/test.csv。如果要传入路径对象，pandas 接受任何 os.PathLike。所谓文件类对象，是指具有 read() 方法的对象，例如文件句柄（如通过内置 open 函数）或 StringIO。

  • sep (str, default ',') -- 要使用的分隔符。如果 sep 为 None，C 引擎无法自动检测分隔符，但 Python 解析引擎可以，这意味着将使用后者并通过 Python 内置的嗅探工具 csv.Sniffer 自动检测分隔符。此外，长度大于 1 个字符且不同于 '\s+' 的分隔符将被解释为正则表达式，并强制使用 Python 解析引擎。请注意，正则表达式分隔符容易忽略引号中的数据。正则表达式示例：'\r\t'。

  • delimiter (str, default None) -- sep 的别名。

  • header (int, list of int, default 'infer') -- 用作列名的行号，并作为数据的起始行。默认行为是推断列名：如果未传递名称，则行为与 header=0 相同，列名将从文件第一行推断；如果显式传递了列名，则行为与 header=None 相同。显式传递 header=0 可以替换现有名称。header 可以是整数列表，用于指定列的多级索引的行位置，例如 [0,1,3]。未指定的中间行将被跳过（例如本例中跳过第 2 行）。请注意，如果 skip_blank_lines=True，此参数将忽略注释行和空行，因此 header=0 表示数据的第一行，而不是文件的第一行。

  • names (array-like, optional) -- 要使用的列名列表。如果文件包含标题行，则应显式传递 header=0 以覆盖列名。此列表中不允许重复。

  • index_col (int, str, sequence of int / str, or False, default None) -- 用作 DataFrame 行标签的列，可以是字符串名称或列索引。如果传入 int / str 序列，则使用 MultiIndex。注意：index_col=False 可用于强制 pandas 不 将第一列作为索引，例如当您有一个格式错误的文件，其每行末尾包含分隔符时。

  • usecols (list-like or callable, optional) -- 返回列的子集。如果为类列表对象，则所有元素必须是位置型（即文档列的整数索引）或字符串（与用户在 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']。使用此参数可以显著加快解析速度并降低内存使用量。

  • prefix (str, optional) -- 当没有标题行时，为列号添加前缀，例如 'X' 表示 X0、X1 等。

  • mangle_dupe_cols (bool, default True) -- 重复列将被指定为 'X'、'X.1'、...'X.N'，而不是 'X'...'X'。如果传入 False，在列名重复时会导致数据被覆盖。

  • dtype (Type name or dict of column -> type, optional) -- 用于数据或列的数据类型。例如 {'a': np.float64, 'b': np.int32, 'c': 'Int64'}。使用 str 或 object 配合适当的 na_values 设置可以保留而不解释 dtype。如果指定了转换器，则将在 dtype 转换前应用它们。

  • engine ({'c', 'python'}, optional) -- 要使用的解析引擎。C 引擎更快，而 Python 引擎目前功能更完整。

  • converters (dict, optional) -- 用于转换某些列中值的函数字典。键可以是整数或列标签。

  • true_values (list, optional) -- 视为 True 的值。

  • false_values (list, optional) -- 视为 False 的值。

  • skipinitialspace (bool, default False) -- 跳过分隔符后的空格。

  • skiprows (list-like, int or callable, optional) -- 要跳过的行号（从 0 开始）或跳过的行数（整数）。如果为可调用对象，则将根据行索引评估该函数，如果应跳过该行则返回 True，否则返回 False。一个有效的可调用参数示例是 lambda x: x in [0, 2]。

  • skipfooter (int, default 0) -- 跳过文件底部的行数（不支持 engine='c'）。

  • nrows (int, optional) -- 要读取的文件行数。对于读取大文件的部分内容非常有用。

  • na_values (scalar, str, list-like, or dict, optional) -- 识别为 NA/NaN 的附加字符串。如果传入字典，则为特定列的 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', 'n/a', 'nan', 'null'。

  • keep_default_na (bool, default 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, default True) -- 检测缺失值标记（空字符串和 na_values 的值）。在没有任何 NA 的数据中，传递 na_filter=False 可以提高读取大文件的性能。

  • verbose (bool, default False) -- 指示放置在非数值列中的 NA 值数量。

  • skip_blank_lines (bool, default True) -- 如果为 True，则跳过空行而不是将其解释为 NaN 值。

  • parse_dates (bool or list of int or names or list of lists or dict, default False) -- 行为如下：* 布尔值。如果为 True -> 尝试解析索引。* int 或名称列表。例如，如果 [1, 2, 3] -> 尝试将列 1、2、3 分别解析为单独的日期列。* 列表的列表。例如，如果 [[1, 3]] -> 合并列 1 和 3 并解析为单个日期列。* 字典，例如 {'foo' : [1, 3]} -> 将列 1、3 解析为日期并调用结果 'foo'。如果列或索引无法表示为日期时间数组，例如由于无法解析的值或时区混合，则该列或索引将以对象数据类型不加修改地返回。对于非标准的日期时间解析，请在 pd.read_csv 之后使用 pd.to_datetime。要解析具有时区混合的索引或列，请将 date_parser 指定为应用了 utc=True 的 pandas.to_datetime()。更多信息请参见 Parsing a CSV with mixed timezones。注意：对于 iso8601 格式的日期存在快速路径。

  • infer_datetime_format (bool, default False) -- 如果为 True 且启用了 parse_dates，pandas 将尝试推断列中日期时间字符串的格式，如果可以推断出来，则切换到更快的解析方法。在某些情况下，这可以将解析速度提高 5-10 倍。

  • keep_date_col (bool, default False) -- 如果为 True 且 parse_dates 指定合并多个列，则保留原始列。

  • date_parser (function, optional) -- 用于将字符串列序列转换为日期时间实例数组的函数。默认使用 dateutil.parser.parser 进行转换。Pandas 将尝试以三种不同的方式调用 date_parser，如果出现异常则继续尝试下一种方式：1) 将一个或多个数组（由 parse_dates 定义）作为参数传递；2) 将 parse_dates 定义的列中的字符串值按行连接成单个数组并传递；3) 对每一行使用一个或多个字符串（对应于 parse_dates 定义的列）作为参数调用 date_parser。

  • dayfirst (bool, default False) -- DD/MM 格式的日期，国际和欧洲格式。

  • cache_dates (bool, default True) -- 如果为 True，则使用唯一转换日期的缓存来应用日期时间转换。在解析重复日期字符串时，尤其是带有时区偏移的日期字符串时，可能会显著提高速度。.. versionadded:: 0.25.0

  • iterator (bool, default False) -- 返回 TextFileReader 对象用于迭代或通过 get_chunk() 获取块。

  • chunksize (int, optional) -- 返回用于迭代的 TextFileReader 对象。有关 iterator 和 chunksize 的更多信息，请参见 IO Tools 文档。

  • compression ({'infer', 'gzip', 'bz2', 'zip', 'xz', None}, default 'infer') -- 用于磁盘数据的即时解压缩。如果为 'infer' 且 filepath_or_buffer 是路径类对象，则从以下扩展名检测压缩格式：'.gz'、'.bz2'、'.zip' 或 '.xz'（否则不解压缩）。如果使用 'zip'，ZIP 文件必须只包含一个要读取的数据文件。设置为 None 表示不解压缩。

  • thousands (str, optional) -- 千位分隔符。

  • decimal (str, default '.') -- 识别为小数点的字符（例如，对欧洲数据使用 ','）。

  • lineterminator (str (length 1), optional) -- 将文件分割成行的字符。仅在使用 C 解析器时有效。

  • quotechar (str (length 1), optional) -- 用于表示引用项开始和结束的字符。引用项可以包含分隔符，该分隔符将被忽略。

  • quoting (int or csv.QUOTE_* instance, default 0) -- 根据 csv.QUOTE_* 常量控制字段引用行为。使用 QUOTE_MINIMAL (0)、QUOTE_ALL (1)、QUOTE_NONNUMERIC (2) 或 QUOTE_NONE (3) 中的一个。

  • doublequote (bool, default True) -- 当指定了 quotechar 且引用不是 QUOTE_NONE 时，指示是否将字段内的两个连续 quotechar 元素解释为单个 quotechar 元素。

  • escapechar (str (length 1), optional) -- 用于转义其他字符的单字符字符串。

  • comment (str, optional) -- 指示行的其余部分不应被解析。如果在行的开头发现该字符，则整行将被完全忽略。此参数必须是单个字符。与空行（只要 skip_blank_lines=True）一样，完全被注释的行会被参数 header 忽略，但不会被 skiprows 忽略。例如，如果 comment='#'，解析 #empty\na,b,c\n1,2,3 并设置 header=0 时，'a,b,c' 将被视为表头。

  • encoding (str, optional) -- 读取/写入时用于 UTF 的编码（例如 'utf-8'）。Python 标准编码列表 。

  • dialect (str or csv.Dialect, optional) -- 如果提供此参数，它将覆盖以下参数的值（默认值或非默认值）：delimiter、doublequote、escapechar、skipinitialspace、quotechar 和 quoting。如果需要覆盖值，将发出 ParserWarning。有关更多详细信息，请参见 csv.Dialect 文档。

  • error_bad_lines (bool, default True) -- 字段过多的行（例如逗号过多的 csv 行）默认情况下会导致引发异常，并且不会返回 DataFrame。如果为 False，则这些"坏行"将从返回的 DataFrame 中删除。

  • warn_bad_lines (bool, default True) -- 如果 error_bad_lines 为 False，且 warn_bad_lines 为 True，则会为每个"坏行"输出警告。

  • delim_whitespace (bool, default False) -- 指定是否使用空白字符（例如 ' ' 或 '    '）作为分隔符。等效于设置 sep='\s+'。如果此选项设置为 True，则不应为 delimiter 参数传递任何值。

  • low_memory (bool, default True) -- 在内部以分块方式处理文件，从而在解析时降低内存使用，但可能导致混合类型推断。要确保没有混合类型，可以设置为 False，或使用 dtype 参数指定类型。请注意，无论怎样整个文件都会被读入一个 DataFrame，使用 chunksize 或 iterator 参数以分块返回数据。（仅对 C 解析器有效）。

  • float_precision (str, optional) -- 指定 C 引擎用于浮点数的转换器。选项包括：None 表示普通转换器，high 表示高精度转换器，round_trip 表示往返转换器。

  • chunk_bytes (int, float or str, optional) -- 每个分块的字节数。

  • gpu (bool, default False) -- 是否读取到 cudf DataFrame。

  • head_bytes (int, float or str, optional) -- 用于文件头部数据推断的字节数。

  • head_lines (int, optional) -- 用于文件头部数据推断的行数。

  • default_index_type ({None, 'range', 'incremental'}, default None) -- 如果未指定 index_col，则指定要生成的索引类型。如果未指定，将使用 options.dataframe.default_index_type。

  • dtype_backend ({'numpy', 'pyarrow'}, default 'numpy') -- 应用于结果 DataFrame 的后端数据类型（仍为实验性功能）。

  • storage_options (dict, optional) -- 存储连接的选项。

  • merge_small_files (bool, default True) -- 合并体积较小的小文件。

  • merge_small_file_options (dict) -- 合并小文件的选项

返回:

逗号分隔值 (csv) 文件被返回为带有标签轴的二维数据结构。

返回类型:

DataFrame

参见

to_csv

将 DataFrame 写入逗号分隔值 (csv) 文件。

示例

>>> import maxframe.dataframe as md
>>> md.read_csv('data.csv')
>>> # read from HDFS
>>> md.read_csv('hdfs://localhost:8020/test.csv')
>>> # read from OSS
>>> md.read_csv('oss://oss-cn-hangzhou.aliyuncs.com/bucket/test.csv',
>>>             storage_options={'role_arn': 'acs:ram::xxxxxx:role/aliyunodpsdefaultrole'})