DEPR: Deprecate Series.to_csv signature
State: closed

- [x] closes #19715
- [x] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] whatsnew entry

<strike>Just a proof of concept for discussion (misses docs, whatsnew, new tests). Based on #21868</strike>

@dahlbaek @gfyoung 

Labels:
name: IO CSV
description: read_csv, to_csv
name: Compat
description: pandas objects compatability with Numpy or Python functions

Comments:
Hello @toobaz! Thanks for updating the PR.













Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on August 02, 2018 at 20:52 Hours UTC
This is the solution that feels the most "just get it done" to me, while not breaking any "correctly written" code (as far as I can tell...?).
> while not breaking any "correctly written"

Do you have in mind "uncorrectly written" code it could break?

(**EDIT**: OK: if you mean "code which does not raise errors", I understand)
Just the example of passing `"y"` instead of `True` as a positional argument to `index`.

(**EDIT**: Precisely that)
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21896?src=pr&el=h1) Report
> Merging [#21896](https://codecov.io/gh/pandas-dev/pandas/pull/21896?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/7725fa028aad7a8817c10b7fe67a34cf7fe8ee5c?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `83.33%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/21896/graphs/tree.svg?height=150&width=650&token=eZ4WkYLtcO&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/21896?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #21896      +/-   ##
==========================================
- Coverage   92.06%   92.05%   -0.01%     
==========================================
  Files         169      169              
  Lines       50694    50709      +15     
==========================================
+ Hits        46671    46681      +10     
- Misses       4023     4028       +5
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.46% <83.33%> (-0.01%)` | :arrow_down: |
| #single | `42.31% <33.33%> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/21896?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/21896/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.25% <ø> (-0.02%)` | :arrow_down: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/21896/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.49% <100%> (+0.01%)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/21896/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.72% <75%> (-0.4%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21896?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21896?src=pr&el=footer). Last update [7725fa0...e69c5ca](https://codecov.io/gh/pandas-dev/pandas/pull/21896?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

> Just the example of passing "y" instead of True as a positional argument to index.

Right, the previous version was wrong and incomplete. Should be fixed now, thanks.

``` python
In [2]: s = pd.Series(list('abcd'))

In [3]: s.to_csv('/tmp/test1.csv', 'y')
/home/nobackup/repo/pandas/pandas/core/series.py:3812: UserWarning: Argument 'header' has changed default value to True: please pass an explicit value to suppress this warning
  warnings.warn("Argument 'header' has changed default value to "

In [4]: cat /tmp/test1.csv
y0
0ya
1yb
2yc
3yd

In [5]: s.to_csv('/tmp/test1.csv', True)
/usr/bin/ipython3:1: FutureWarning: The signature of `Series.to_csv` was  aligned to that of `DataFrame.to_csv`. Note that the order of arguments changed, and the new one has 'sep' in first place, for which "True" is not a valid value. The old order will cease to be supported in a future version. Please refer to the documentation for `DataFrame.to_csv` when updating your function calls.
  #! /bin/sh
/home/nobackup/repo/pandas/pandas/core/series.py:3812: UserWarning: Argument 'header' has changed default value to True: please pass an explicit value to suppress this warning
  warnings.warn("Argument 'header' has changed default value to "

In [6]: cat /tmp/test1.csv
,0
0,a
1,b
2,c
3,d
```
is this replacing #21868 .  - haven't been following 2 closely @toobaz @gfyoung 
@jreback : No.  Actually would like your or @jorisvandenbossche input, as the conversations have produced three possible fixes:

#19745 (@dahlbaek)
#21868 (@gfyoung)
#21896 (@toobaz)

Just need to resolve this before the conversations drag out forever 🙂 
#21896 and #21868 (this one) look very similar at first glance, what is the substantive diff?

I prefer either of these over #19745 which I find much harder to read.
@jreback : @toobaz does major argument introspection by changing the signature to `Series(*args, **kwargs)`.  I (#21868) kept things a little simpler by adding only `**kwargs` to the current signature and doing argument introspection on `**kwargs`.
> @toobaz does major argument introspection

Yes; one additional important change is that this PR tries to support both the old and the new positional signature (where "tries" means that it will never know for sure if some user had the idea to pass ``index="y"`` in place of ``index=True``).
@jreback @jorisvandenbossche : Any further thoughts on #21896 and #21868?  I think @toobaz, @dahlbaek , and I have exhausted our own thoughts 😄 , so fresh eyes would be good.
@jreback @jorisvandenbossche : Another friendly ping on this.
I like this version. I think bending over to give a helpful error message is pretty useful to the user. This is not completely crazy and doesn't add a huge amount of code. I think a couple of TODO's were left in the code.
@toobaz : Don't forget `whatsnew` entry as well.
> @toobaz : Don't forget whatsnew entry as well.

Tests are missing too, but I tought that maybe the simplest thing would be for you to take my code in your PR. Otherwise I can do the opposite (not sure when I'll find the time though).
@toobaz : I can push to those changes to you branch.  You have the changes, but just need the finishing touches, which I can add here.
> @toobaz : I can push to your branch if that works.

Sure, feel free (I saw now only that you closed the other one)
Rebased (on #22011 ) and added missing ``.. versionchanged:: 0.24.0`` for ``header`` argument. 

<strike>Lint complains with ``pandas/core/strings.py:296:80: E501 line too long (87 > 79 characters)`` but that's not a file I edited...</strike> it was unrelated
Thanks!