polars.DataFrame.write_csv

DataFrame.write_csv(
    file: str | Path | IO[str] | IO[bytes] | None = None,
    *,
    include_bom: bool = False,
    compression: Literal['uncompressed',
    'gzip',
    'zstd'] = 'uncompressed',
    compression_level: int | None = None,
    check_extension: bool = True,
    include_header: bool = True,
    separator: str = ',',
    line_terminator: str = '\n',
    quote_char: str = '"',
    batch_size: int = 1024,
    datetime_format: str | None = None,
    date_format: str | None = None,
    time_format: str | None = None,
    float_scientific: bool | None = None,
    float_precision: int | None = None,
    decimal_comma: bool = False,
    null_value: str | None = None,
    quote_style: CsvQuoteStyle | None = None,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
) → str | None

Записать файл со значениями, разделёнными запятыми (CSV).

Параметры:

file

Путь к файлу или объект, похожий на файл, доступный для записи, в который будет записан результат. Если задано None (по умолчанию), вместо этого результат возвращается в виде строки.

include_bom

Следует ли включать BOM UTF-8 в выходные данные CSV.

compression

Какой формат сжатия использовать.

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без того, чтобы это считалось нарушением обратной совместимости.

compression_level

Используемый уровень сжатия, обычно от 0 до 9, или None, чтобы позволить движку выбрать его самостоятельно.

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без того, чтобы это считалось нарушением обратной совместимости.

check_extension

Проверять ли соответствие имени файла настройкам сжатия. Будет вызвана ошибка, если для сжатия задано значение ‘uncompressed’, а имя файла заканчивается на одно из значений (“.gz”, “.zst”, “.zstd”), либо если compression != ‘uncompressed’, а имя файла не заканчивается соответствующим расширением. Применяется, только если file — это путь.

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без того, чтобы это считалось нарушением обратной совместимости.

include_header

Следует ли включать заголовок в выходные данные CSV.

separator

Разделять поля CSV этим символом.

line_terminator

Строка, используемая для завершения каждой строки.

quote_char

Байт, используемый в качестве символа кавычек.

batch_size

Количество строк, обрабатываемых каждым потоком.

datetime_format

Строка формата со спецификаторами, определёнными в крейте Rust chrono. Если формат не задан, точность дробной части секунды определяется по максимальной единице времени, найденной в столбцах Datetime фрейма (если таковые имеются).

date_format

Строка формата со спецификаторами, определёнными в крейте Rust chrono.

time_format

Строка формата со спецификаторами, определёнными в крейте Rust chrono.

float_scientific

Использовать ли научную запись всегда (true), никогда (false) или автоматически (None) для типов данных с плавающей точкой.

float_precision

Количество десятичных знаков для записи; применяется к обоим типам данных с плавающей точкой.

decimal_comma

Использовать запятую вместо точки в качестве десятичного разделителя в стандартной записи. При необходимости числа с плавающей точкой заключаются в кавычки; чтобы избежать этого, задайте разделитель полей.

null_value

Строка, представляющая нулевые значения (по умолчанию — пустая строка).

quote_style{‘necessary’, ‘always’, ‘non_numeric’, ‘never’}

Определяет используемую стратегию заключения в кавычки.

• necessary (по умолчанию): заключает поля в кавычки только при необходимости. Это необходимо, если поля содержат кавычку, разделитель или символ окончания записи. Кавычки также необходимы при записи пустой записи (которую невозможно отличить от записи с одним пустым полем). Это стратегия по умолчанию.
• always: всегда заключает в кавычки каждое поле.
• never: никогда не заключает поля в кавычки, даже если в результате данные CSV становятся некорректными (например, если строки с разделителем не заключаются в кавычки).
• non_numeric: заключает в кавычки все поля, не являющиеся числовыми. То есть при записи поля, которое не разбирается как корректное число с плавающей точкой или целое число, используются кавычки, даже если они не являются строго необходимыми.

storage_options

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

В настоящее время поддерживаются следующие облачные провайдеры: AWS, GCP и Azure. Список поддерживаемых ключей:

• aws
• gcp
• azure
• Hugging Face (hf://): принимает ключ API в параметре token: {'token': '...'} или через переменную окружения HF_TOKEN.

Если storage_options не задан, Polars попытается определить необходимые сведения по переменным окружения.

credential_provider

Функция, которую можно вызвать для получения учётных данных облачного хранилища. Функция должна возвращать словарь с ключами учётных данных и необязательным временем истечения срока их действия.

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без того, чтобы это считалось нарушением обратной совместимости.

retries

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

Устарело с версии 1.37.1: Вместо этого передайте {“max_retries”: n} через storage_options.

Примеры

>>> import pathlib
>>>
>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> path: pathlib.Path = dirpath / "new_file.csv"
>>> df.write_csv(path, separator=",")