polars.read_csv

polars.read_csv(
    source: str | Path | IO[str] | IO[bytes] | bytes,
    *,
    has_header: bool = True,
    columns: Sequence[int] | Sequence[str] | None = None,
    new_columns: Sequence[str] | None = None,
    separator: str = ',',
    comment_prefix: str | None = None,
    quote_char: str | None = '"',
    skip_rows: int = 0,
    skip_lines: int = 0,
    schema: SchemaDict | None = None,
    schema_overrides: Mapping[str,
    PolarsDataType] | Sequence[PolarsDataType] | None = None,
    null_values: str | Sequence[str] | dict[str,
    str] | None = None,
    empty_string_is_null: bool = True,
    ignore_errors: bool = False,
    try_parse_dates: bool = False,
    n_threads: int | None = None,
    infer_schema: bool = True,
    infer_schema_length: int | None = 100,
    batch_size: int = 8192,
    n_rows: int | None = None,
    encoding: CsvEncoding | str = 'utf8',
    low_memory: bool = False,
    rechunk: bool | None = None,
    use_pyarrow: bool = False,
    storage_options: StorageOptionsDict | None = None,
    skip_rows_after_header: int = 0,
    row_index_name: str | None = None,
    row_index_offset: int = 0,
    sample_size: int = 1024,
    eol_char: str = '\n',
    raise_if_empty: bool = True,
    truncate_ragged_lines: bool = False,
    decimal_comma: bool = False,
    glob: bool = True,
) → DataFrame

Читает CSV-файл в DataFrame.

Polars ожидает, что данные CSV будут строго соответствовать RFC 4180, если не указано иное. Некорректные данные, хотя и встречаются часто, могут привести к неопределённому поведению.

Изменено в версии 0.20.31: Параметр dtypes был переименован в schema_overrides.

Изменено в версии 0.20.4: * Параметр row_count_name был переименован в row_index_name. * Параметр row_count_offset был переименован в row_index_offset.

Параметры:

source

Путь к файлу или файловоподобному объекту (под «файловоподобным объектом» подразумеваются объекты с методом read(), например файловый дескриптор, полученный с помощью встроенной функции open, или экземпляр BytesIO). Если установлен fsspec, он может использоваться для открытия удалённых файлов. При чтении по пути поддерживаются сжатые файлы. При работе с файловоподобными объектами позиция потока после чтения может обновиться некорректно.

has_header

Указывает, является ли первая строка набора данных заголовком. Если задано значение False, имена столбцов будут сгенерированы в следующем формате: column_x, где x — перечисление всех столбцов набора данных, начиная с 1.

columns

Столбцы, которые необходимо выбрать. Принимает список индексов столбцов (начиная с нуля) или список имён столбцов.

new_columns

Переименовывает столбцы сразу после разбора CSV-файла. Если переданный список короче ширины DataFrame, оставшиеся столбцы сохранят исходные имена.

separator

Однобайтовый символ-разделитель в файле.

comment_prefix

Строка, обозначающая начало строки-комментария. Строки-комментарии пропускаются при разборе. Часто используемые префиксы комментариев: # и //.

quote_char

Однобайтовый символ, используемый для экранирования полей CSV; по умолчанию — ". Укажите None, чтобы отключить специальную обработку и экранирование кавычек.

skip_rows

Начать чтение после skip_rows строк. Заголовок будет разобран с этого смещения. Обратите внимание: при пропуске строк учитываются правила экранирования CSV и комментарии. Чтобы пропускать строки только по символу новой строки, используйте skip_lines.

skip_lines

Начать чтение после skip_lines строк. Заголовок будет разобран с этого смещения. Обратите внимание: при пропуске строк правила экранирования CSV не учитываются. Чтобы пропускать корректные строки CSV, используйте skip_rows.

schema

Задаёт схему. В этом случае polars не выводит схему автоматически. Этот аргумент принимает полную схему, тогда как schema_overrides можно использовать для частичного переопределения схемы. Обратите внимание: порядок столбцов в переданной schema должен совпадать с порядком столбцов в читаемом CSV-файле.

schema_overrides

Переопределяет типы данных для некоторых или всех столбцов при выводе схемы.

null_values

Значения, которые следует интерпретировать как null. Можно передать:

• str: все значения, совпадающие с этой строкой, будут считаться null.
• List[str]: все значения, совпадающие с любой строкой из этого списка, будут считаться null.
• Dict[str, str]: словарь, сопоставляющий имя столбца строковому значению null.

empty_string_is_null

По умолчанию отсутствующее строковое значение считается null. Если для empty_string_is_null задано значение False, отсутствующие строковые значения будут декодироваться как пустые строки.

ignore_errors

Продолжать чтение строк, даже если некоторые из них вызывают ошибки. Прежде чем использовать этот параметр, попробуйте увеличить число строк, используемых для вывода схемы, например с помощью infer_schema_length=10000, переопределить автоматический вывод типа данных для отдельных столбцов с помощью параметра schema_overrides или использовать infer_schema=False, чтобы прочитать все столбцы как pl.String и проверить, какие значения могут вызывать проблему.

try_parse_dates

Попытаться автоматически разобрать даты. Можно определить большинство форматов, подобных ISO 8601, а также некоторые другие. Если это не удастся, тип данных столбца останется pl.String. Если задано use_pyarrow=True, даты будут разбираться всегда.

n_threads

Количество потоков для разбора CSV. По умолчанию используется количество физических ядер процессора в системе.

infer_schema

Если задано True, схема выводится на основе данных по первым infer_schema_length строкам. Если задано False, схема не выводится и будет pl.String, если она не указана в schema или schema_overrides.

infer_schema_length

Максимальное количество строк для анализа при выводе схемы. Если задано None, все данные будут считаны в память (это медленно). В качестве альтернативы задайте infer_schema=False, чтобы читать все столбцы как pl.String.

batch_size

Количество строк, одновременно считываемых в буфер. Измените это значение, чтобы настроить производительность.

n_rows

Прекратить чтение CSV-файла после считывания n_rows. При многопоточном разборе нельзя гарантировать верхнюю границу в n_rows строк.

encoding{‘utf8’, ‘utf8-lossy’, ‘windows-1252’, ‘windows-1252-lossy’, …}

«С потерями» означает, что недопустимые значения UTF-8 заменяются символами �. При использовании кодировок, отличных от utf8 или utf8-lossy, входные данные сначала декодируются в памяти средствами Python. По умолчанию — utf8.

low_memory

Снижает нагрузку на память за счёт производительности.

rechunk

Обеспечивает непрерывное размещение всех столбцов в памяти, объединяя фрагменты в один массив.

Устарело с версии 1.43.2: Вызовите rechunk для возвращённого DataFrame.

use_pyarrow

Попытаться использовать встроенный CSV-парсер pyarrow. Даты будут разбираться всегда, даже если задано try_parse_dates=False. Это возможно не во всех случаях. Возможность использовать встроенный парсер pyarrow определяется набором аргументов, переданных этой функции. Обратите внимание: стратегии вывода типов данных в pyarrow и polars могут различаться.

storage_options

Дополнительные параметры для fsspec.open() или конкретного подключения к хранилищу, например узел, порт, имя пользователя, пароль и т. д.

skip_rows_after_header

Количество строк, которое необходимо пропустить после разбора заголовка.

row_index_name

Добавляет в DataFrame столбец индекса строк с указанным именем в качестве первого столбца. Если задано None (значение по умолчанию), столбец индекса строк не создаётся.

row_index_offset

Начальное смещение индекса строк. Не может быть отрицательным. Используется только если задано row_index_name.

sample_size

Задаёт размер выборки. Она используется для сбора статистики и оценки необходимого объёма памяти.

Устарело с версии 1.10.0: Этот параметр больше ни на что не влияет.

eol_char

Однобайтовый символ конца строки (по умолчанию: \n). При чтении файла с окончаниями строк Windows (\r\n) можно оставить значение по умолчанию \n. Лишний символ \r будет удалён при обработке.

raise_if_empty

Если источник не содержит данных, вызывается NoDataError. Если этому параметру задано значение False, вместо этого возвращается пустой DataFrame (без столбцов).

truncate_ragged_lines

Обрезать строки, длина которых превышает ширину схемы.

decimal_comma

Разбирать числа с плавающей точкой, используя запятую вместо точки в качестве десятичного разделителя.

glob

Разворачивать путь согласно правилам glob.

Возвращает:

DataFrame

Предупреждение

Вызов read_csv().lazy() считается антипаттерном, поскольку заставляет Polars полностью материализовать CSV-файл и не позволяет передавать оптимизации в средство чтения. Поэтому всегда предпочитайте scan_csv, если хотите работать с LazyFrame.

См. также

scan_csv

Лениво читает один или несколько CSV-файлов с использованием шаблонов glob.

Примечания

Если схема выводится неправильно (например, как pl.Int64 вместо pl.Float64), попробуйте увеличить число строк, используемых для вывода схемы, с помощью infer_schema_length или переопределить выведенный тип данных для этих столбцов с помощью schema_overrides.

Примеры

>>> pl.read_csv("data.csv", separator="|")  

Пример использования объекта BytesIO для разбора строковых дат.

>>> from io import BytesIO
>>> data = BytesIO(
...     b"ID,Name,Birthday\n"
...     b"1,Alice,1995-07-12\n"
...     b"2,Bob,1990-09-20\n"
...     b"3,Charlie,2002-03-08\n"
... )
>>> pl.read_csv(data, try_parse_dates=True)
shape: (3, 3)
┌─────┬─────────┬────────────┐
│ ID  ┆ Name    ┆ Birthday   │
│ --- ┆ ---     ┆ ---        │
│ i64 ┆ str     ┆ date       │
╞═════╪═════════╪════════════╡
│ 1   ┆ Alice   ┆ 1995-07-12 │
│ 2   ┆ Bob     ┆ 1990-09-20 │
│ 3   ┆ Charlie ┆ 2002-03-08 │
└─────┴─────────┴────────────┘