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, 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>)[原始碼]#
將逗號分隔值 (csv) 檔案讀取到 DataFrame 中。
還支援可選地迭代或將檔案分塊。
更多幫助可以在 IO Tools 的線上文件中找到。
- 引數:
- filepath_or_bufferstr, path object or file-like object
任何有效的字串路徑都可以接受。字串可以是一個 URL。有效的 URL 方案包括 http, ftp, s3, gs 和 file。對於檔案 URL，需要主機。本地檔案可以是：file:///path/to/table.csv。
如果要傳入路徑物件，pandas 接受任何
os.PathLike。透過“檔案類物件”，我們指的是具有
read()方法的物件，例如檔案控制代碼（例如透過內建open函式）或StringIO。- sepstr, default ‘,’
用作分隔符的字元或正則表示式。如果
sep=None，C 引擎無法自動檢測分隔符，但 Python 解析引擎可以，這意味著後者將被使用，並透過 Python 內建的嗅探器csv.Sniffer自動從檔案的第一個有效行中檢測分隔符。此外，長度超過 1 個字元且與'\s+'不同的分隔符將被解釋為正則表示式，並且還將強制使用 Python 解析引擎。請注意，正則表示式分隔符容易忽略帶引號的資料。正則表示式示例：'\r\t'。- delimiterstr, optional
sep的別名。- headerint, Sequence of int, ‘infer’ 或 None, default ‘infer’
包含列標籤並標記資料開始的行號（從零開始）。預設行為是推斷列名：如果沒有傳遞
names，則行為與header=0相同，並且列名從檔案的第一行推斷；如果明確將列名傳遞給names，則行為與header=None相同。顯式傳遞header=0以便能夠替換現有名稱。header 可以是一個整數列表，指定用於列上MultiIndex的行位置，例如[0, 1, 3]。未指定的中間行將被跳過（例如，此示例中的 2 被跳過）。請注意，此引數會忽略註釋行和空行（如果skip_blank_lines=True），因此header=0表示資料的第一行，而不是檔案的第一行。當從檔案內容推斷時，透過將重複的名稱重新命名為以 1 開頭的數字字尾（例如
".{{count}}"）來區分各個標頭，例如"foo"和"foo.1"。空標頭將被命名為"Unnamed: {{i}}"或在 MultiIndex 列的情況下命名為"Unnamed: {{i}}_level_{{level}}"。- namesSequence of Hashable, optional
要應用的列標籤序列。如果檔案包含標頭行，則應顯式傳遞
header=0以覆蓋列名。此列表中的重複項是不允許的。- index_colHashable, Sequence of Hashable 或 False, optional
用作行標籤的列，透過列標籤或列索引表示。如果給出了標籤或索引的序列，則將為行標籤形成
MultiIndex。注意：
index_col=False可用於強制 pandas 不 將第一列用作索引，例如，當您有一個檔案格式錯誤，每行末尾都有分隔符時。- usecolsSequence of Hashable 或 Callable, optional
要選擇的列的子集，透過列標籤或列索引表示。如果為列表狀，所有元素必須是位置性的（即文件列中的整數索引）或字串，這些字串對應於使用者在
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 或 dict of {{Hashabledtype}}, optional
應用於整個資料集或單個列的資料型別。例如，
{{'a': np.float64, 'b': np.int32, 'c': 'Int64'}}使用str或object結合合適的na_values設定可以保留dtype而不進行解釋。如果指定了converters，則它們將被應用於 *代替*dtype轉換。將defaultdict作為輸入，其中預設值決定了未顯式列出的列的dtype。- engine{{‘c’, ‘python’, ‘pyarrow’}}, optional
要使用的解析器引擎。C 和 pyarrow 引擎速度更快，而 Python 引擎目前功能更完整。多執行緒目前僅受 pyarrow 引擎支援。 “pyarrow”引擎的某些功能不受支援或可能無法正常工作。
- convertersdict of {{HashableCallable}}, optional
用於轉換指定列中值的函式。鍵可以是列標籤或列索引。
- true_valueslist, optional
除大小寫不敏感的“True”變體外，還將哪些值視為
True。- false_valueslist, optional
除大小寫不敏感的“False”變體外，還將哪些值視為
False。- skipinitialspacebool, default False
跳過分隔符後的空格。
- skiprowsint, list of int 或 Callable, optional
要跳過的行號（從零開始）或在檔案開頭要跳過的行數（
int）。如果為可呼叫物件，則可呼叫函式將針對行索引進行評估，如果該行應被跳過，則返回
True，否則返回False。有效可呼叫引數的一個示例將是lambda x: x in [0, 2]。- skipfooterint, default 0
要跳過檔案底部的行數（使用
engine='c'時不支援）。- nrowsint, optional
要從檔案中讀取的行數。有助於讀取大檔案的部分。指的是返回的 DataFrame 中的資料行數，不包括
包含列名的標頭行。
標頭行之前的行，如果
header=1或更大。
示例用法
讀取前 999,999 行（非標頭）：
read_csv(..., nrows=999999)讀取第 1,000,000 行到第 1,999,999 行：
read_csv(..., skiprows=1000000, nrows=999999)
- na_valuesHashable, Iterable of Hashable 或 dict of {{HashableIterable}},
optional 附加字串，用於將它們識別為
NA/NaN。如果傳遞了dict，則為每列指定NA值。預設情況下，以下值被解釋為NaN：空字串、“NaN”、“N/A”、“NULL”以及其他常見的缺失資料表示。- keep_default_nabool, 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_filterbool, default True
檢測缺失值標記（空字串和
na_values的值）。在沒有NA值的 資料中，傳遞na_filter=False可以提高讀取大檔案的效能。- skip_blank_linesbool, default True
如果為
True，則跳過空行，而不是將其解釋為NaN值。- parse_datesbool, None, list of Hashable, default None
行為如下
bool。如果為True-> 嘗試解析索引。None。如果指定了date_format，則行為與True相同。listofint或名稱。例如，如果[1, 2, 3]-> 嘗試將列 1、2、3 分別解析為日期列。
如果某一列或索引無法表示為
datetime陣列，例如由於存在無法解析的值或時區的混合，則該列或索引將保持不變，作為object資料型別返回。對於非標準datetime解析，請在read_csv()之後使用to_datetime()。注意：對於 iso8601 格式的日期，存在快速通道。
- date_formatstr 或 dict of column -> format, optional
與
parse_dates結合使用時，用於解析日期和/或時間的格式。strftime 用於解析時間，例如"%d/%m/%Y"。有關選項，請參閱 strftime 文件，但請注意，"%f"`將解析到納秒級別。您也可以傳遞“ISO8601”，用於解析任何 ISO8601 時間字串（不一定是完全相同的格式）；
“mixed”，用於單獨推斷每個元素的格式。這有風險，您可能應該與 dayfirst 一起使用。
版本 2.0.0 中已新增。
- dayfirstbool, default False
DD/MM 格式日期，國際和歐洲格式。
- cache_datesbool, default True
如果為
True，則使用唯一、已轉換日期的快取來應用datetime轉換。在解析重複日期字串（尤其是帶有時區偏移的字串）時，可能會顯著提速。- iteratorbool, default False
返回
TextFileReader物件以進行迭代或使用get_chunk()獲取塊。- chunksize整數，可選
每塊要從檔案中讀取的行數。傳遞一個值將導致函式返回一個
TextFileReader物件用於迭代。有關iterator和chunksize的更多資訊，請參閱 IO Tools 文件。- compressionstr or dict, default ‘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}。- thousandsstr (length 1), optional
用作數值中千位分隔符的字元。
- decimalstr (length 1), default ‘.’
用於識別小數點（例如，歐洲資料使用“,”）。
- lineterminatorstr (length 1), optional
用於表示換行的字元。僅在使用 C 解析器時有效。
- quotecharstr (length 1), optional
用於表示帶引號項的開始和結束的字元。帶引號的項可以包含
delimiter，並且將被忽略。- quoting{{0 or csv.QUOTE_MINIMAL, 1 or csv.QUOTE_ALL,
2 or csv.QUOTE_NONNUMERIC, 3 or csv.QUOTE_NONE}}, default csv.QUOTE_MINIMAL 根據
csv.QUOTE_*常量控制欄位的引用行為。預設是csv.QUOTE_MINIMAL（即 0），這意味著只有包含特殊字元的欄位才會被引用（例如，quotechar、delimiter或lineterminator中定義的字元）。- doublequotebool, default True
當指定了
quotechar且quoting不是QUOTE_NONE時，指示欄位內部兩個連續的quotechar元素是否被解釋為單個quotechar元素。- escapecharstr (length 1), optional
用於轉義其他字元的字元。
- commentstr (length 1), optional
指示行其餘部分不應被解析的字元。如果出現在行開頭，則整行將被完全忽略。此引數必須是單個字元。與空行一樣（只要
skip_blank_lines=True），完全註釋的行會被header引數忽略，但不會被skiprows引數忽略。例如，如果comment='#'，使用header=0解析#empty\na,b,c\n1,2,3將導致'a,b,c'被視為標頭。- encodingstr, 可選, 預設為 ‘utf-8’
UTF 編碼，用於讀取/寫入（例如
'utf-8'）。Python 標準編碼列表。- encoding_errorsstr, optional, default ‘strict’
如何處理編碼錯誤。可能的取值列表。
- dialectstr 或 csv.Dialect, optional
如果提供，此引數將覆蓋以下引數的值（預設值或非預設值）：
delimiter、doublequote、escapechar、skipinitialspace、quotechar和quoting。如果需要覆蓋值，將發出ParserWarning。有關更多詳細資訊，請參閱csv.Dialect文件。- on_bad_lines{{‘error’, ‘warn’, ‘skip’}} 或 Callable, default ‘error’
指定遇到錯誤行（欄位過多）時要執行的操作。允許的值包括：
'error'，在遇到錯誤行時引發異常。'warn'，在遇到錯誤行時引發警告並跳過該行。'skip'，在遇到錯誤行時跳過，不引發異常或警告。- Callable，用於處理單個錯誤行的函式。
使用
engine='python'時，函式簽名如下：(bad_line: list[str]) -> list[str] | None。bad_line是一個由sep分割的字串列表。如果函式返回None，則將忽略錯誤行。如果函式返回一個比預期元素多的新字串list，則在丟棄多餘元素時會發出ParserWarning。使用
engine='pyarrow'時，函式簽名如 pyarrow 文件所述：invalid_row_handler。
版本 2.2.0 中更改：
engine='pyarrow'的 Callable。- low_memorybool, default True
在內部將檔案分塊處理，從而降低解析時的記憶體使用量，但可能導致型別推斷混合。為了確保沒有混合型別，請將
False，或使用dtype引數指定型別。請注意，整個檔案仍會讀取到一個DataFrame中，請使用chunksize或iterator引數以塊的形式返回資料。（僅在使用 C 解析器時有效）。- memory_mapbool, default False
如果為
filepath_or_buffer提供了檔案路徑，則將檔案物件直接對映到記憶體，並直接從中訪問資料。使用此選項可以提高效能，因為不再存在 I/O 開銷。- float_precision{{‘high’, ‘legacy’, ‘round_trip’}}, optional
指定 C 引擎應為浮點值使用的轉換器。選項包括
None或'high'表示普通轉換器，'legacy'表示原始的低精度 pandas 轉換器，以及'round_trip'表示往返轉換器。- storage_optionsdict, optional
對於特定儲存連線有意義的額外選項，例如主機、埠、使用者名稱、密碼等。對於 HTTP(S) URL，鍵值對將作為標頭選項轉發到
urllib.request.Request。對於其他 URL（例如，以“s3://”和“gcs://”開頭），鍵值對將轉發到fsspec.open。有關更多詳細資訊，請參閱fsspec和urllib，有關儲存選項的更多示例，請參閱 此處。- dtype_backend{{‘numpy_nullable’, ‘pyarrow’}}
應用於結果
DataFrame的後端資料型別（仍處於實驗階段）。如果未指定，則預設行為是不使用可為空的資料型別。如果指定，行為如下："numpy_nullable": 返回支援可為空 dtype 的DataFrame"pyarrow": 返回支援 pyarrow 的可為空ArrowDtype的DataFrame
版本 2.0 中已新增。
- 返回:
- DataFrame 或 TextFileReader
逗號分隔值 (csv) 檔案被返回為具有標籤軸的二維資料結構。
另請參閱
DataFrame.to_csv將 DataFrame 寫入逗號分隔值 (csv) 檔案。
read_table將通用分隔檔案讀取到 DataFrame 中。
read_fwf將固定寬度格式化行表讀取到 DataFrame 中。
示例
>>> pd.read_csv("data.csv") Name Value 0 foo 1 1 bar 2 2 #baz 3
可以透過 index_col 和 header 引數指定索引和標頭。
>>> pd.read_csv("data.csv", header=None) 0 1 0 Name Value 1 foo 1 2 bar 2 3 #baz 3
>>> pd.read_csv("data.csv", index_col="Value") Name Value 1 foo 2 bar 3 #baz
列型別會根據需要推斷，但可以使用 dtype 引數顯式指定。
>>> pd.read_csv("data.csv", dtype={{"Value": float}}) Name Value 0 foo 1.0 1 bar 2.0 2 #baz 3.0
True、False、NA 值和千位分隔符都有預設值，但也可以顯式指定。提供您想要作為字串或字串列表的值！
>>> pd.read_csv("data.csv", na_values=["foo", "bar"]) Name Value 0 NaN 1 1 NaN 2 2 #baz 3
可以使用 comment 引數跳過輸入檔案中的註釋行。
>>> pd.read_csv("data.csv", comment="#") Name Value 0 foo 1 1 bar 2
預設情況下，包含日期的列將作為
object而不是datetime讀取。>>> df = pd.read_csv("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_csv( ... "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