API: Deprecate old Series.to_csv signature (#21896) · pandas-dev/pandas@eb0ac54 (original) (raw)

`@@ -17,6 +17,7 @@

17

`from pandas.core.arrays import ExtensionArray

18

`from pandas.core.dtypes.common import (

19

`is_categorical_dtype,

20

is_string_like,

20

21

`is_bool,

21

22

`is_integer, is_integer_dtype,

22

23

`is_float_dtype,

`@@ -3765,59 +3766,62 @@ def from_csv(cls, path, sep=',', parse_dates=True, header=None,

3765

3766

3767

`return result

3767

3768

def to_csv(self, path=None, index=True, sep=",", na_rep='',

3769

float_format=None, header=False, index_label=None,

3770

mode='w', encoding=None, compression='infer', date_format=None,

3771

decimal='.'):

3772

"""

3773

Write Series to a comma-separated values (csv) file

3774

-

3775

Parameters

3776

3777

path : string or file handle, default None

3778

File path or object, if None is provided the result is returned as

3779

a string.

3780

na_rep : string, default ''

3781

Missing data representation

3782

float_format : string, default None

3783

Format string for floating point numbers

3784

header : boolean, default False

3785

Write out series name

3786

index : boolean, default True

3787

Write row names (index)

3788

index_label : string or sequence, default None

3789

Column label for index column(s) if desired. If None is given, and

3790

`` -

header and index are True, then the index names are used. A

3791

sequence should be given if the DataFrame uses MultiIndex.

3792

mode : Python write mode, default 'w'

3793

sep : character, default ","

3794

Field delimiter for the output file.

3795

encoding : string, optional

3796

a string representing the encoding to use if the contents are

3797

non-ascii, for python versions prior to 3

3798

compression : None or string, default 'infer'

3799

A string representing the compression to use in the output file.

3800

Allowed values are None, 'gzip', 'bz2', 'zip', 'xz', and 'infer'.

3801

This input is only used when the first argument is a filename.

3802

-

3803

.. versionchanged:: 0.24.0

3804

'infer' option added and set to default

3805

date_format: string, default None

3806

Format string for datetime objects.

3807

decimal: string, default '.'

3808

Character recognized as decimal separator. E.g. use ',' for

3809

European data

3810

"""

3811

from pandas.core.frame import DataFrame

3812

df = DataFrame(self)

3813

result is only a string if no path provided, otherwise None

3814

result = df.to_csv(path, index=index, sep=sep, na_rep=na_rep,

3815

float_format=float_format, header=header,

3816

index_label=index_label, mode=mode,

3817

encoding=encoding, compression=compression,

3818

date_format=date_format, decimal=decimal)

3819

if path is None:

3820

return result

3769

@Appender(generic.NDFrame.to_csv.doc)

3770

def to_csv(self, *args, **kwargs):

3771

+

3772

names = ["path_or_buf", "sep", "na_rep", "float_format", "columns",

3773

"header", "index", "index_label", "mode", "encoding",

3774

"compression", "quoting", "quotechar", "line_terminator",

3775

"chunksize", "tupleize_cols", "date_format", "doublequote",

3776

"escapechar", "decimal"]

3777

+

3778

old_names = ["path_or_buf", "index", "sep", "na_rep", "float_format",

3779

"header", "index_label", "mode", "encoding",

3780

"compression", "date_format", "decimal"]

3781

+

3782

if "path" in kwargs:

3783

`` +

warnings.warn("The signature of Series.to_csv was aligned "

3784

`` +

"to that of DataFrame.to_csv, and argument "

3785

"'path' will be renamed to 'path_or_buf'.",

3786

FutureWarning, stacklevel=2)

3787

kwargs["path_or_buf"] = kwargs.pop("path")

3788

+

3789

if len(args) > 1:

3790

Either "index" (old signature) or "sep" (new signature) is being

3791

passed as second argument (while the first is the same)

3792

maybe_sep = args[1]

3793

+

3794

if not (is_string_like(maybe_sep) and len(maybe_sep) == 1):

3795

old signature

3796

`` +

warnings.warn("The signature of Series.to_csv was aligned "

3797

`` +

"to that of DataFrame.to_csv. Note that the "

3798

"order of arguments changed, and the new one "

3799

"has 'sep' in first place, for which "{}" is "

3800

"not a valid value. The old order will cease to "

3801

"be supported in a future version. Please refer "

3802

`` +

"to the documentation for DataFrame.to_csv "

3803

"when updating your function "

3804

"calls.".format(maybe_sep),

3805

FutureWarning, stacklevel=2)

3806

names = old_names

3807

+

3808

pos_args = dict(zip(names[:len(args)], args))

3809

+

3810

for key in pos_args:

3811

if key in kwargs:

3812

raise ValueError("Argument given by name ('{}') and position "

3813

"({})".format(key, names.index(key)))

3814

kwargs[key] = pos_args[key]

3815

+

3816

if kwargs.get("header", None) is None:

3817

`` +

warnings.warn("The signature of Series.to_csv was aligned "

3818

`` +

"to that of DataFrame.to_csv, and argument "

3819

"'header' will change its default value from False "

3820

"to True: please pass an explicit value to suppress "

3821

"this warning.", FutureWarning,

3822

stacklevel=2)

3823

kwargs["header"] = False # Backwards compatibility.

3824

return self.to_frame().to_csv(**kwargs)

3821

3825

3822

3826

`@Appender(generic._shared_docs['to_excel'] % _shared_doc_kwargs)

3823

3827

`def to_excel(self, excel_writer, sheet_name='Sheet1', na_rep='',