DOC add dayfirst to to_datetime
State: closed

At the moment only some of the arguments are shown in the docstring for to_datetime, which can [lead to unnecessary confusion](http://stackoverflow.com/questions/15929861/pandas-to-datetime-inconsistent-time-string-format/15937890#15937890). This adds all of them to the docstring.

~~Also a cheeky enhancement to use print configs default to set date (copied from `parse_time_string`), not sure how to test that one.... tbh **I think it would make sense to default dayfirst to None**, the current behaviour can be strange (as seen in the above question).~~

Thoughts?


Labels:

Comments:
(I don't think the travis fail is from this commit) 

@hayd merge for 0.11?

@jreback if it all looks ok, I'm flipping between defaulting dayfirst to None, I really think at the moment the current default behaviour is broken (see the question)... what do you think?

I would like add a test for dayfirst=None if we were to change the default.

@hayd wouldn't you ALWAYS use format, or is dayfirst just a shorcut for : '%d/%M/%Y'?

If I wanted to always set my datest in dayfirst order I guess would set_option, this is just a local override, right?

@jreback dayfirst is a little more vague, i.e. equivalent to '%d-%m%Y' or '%d/%m/%Y' or '%d/%m/%y' etc. ?

_Sometimes you (or at least I) may not care about the specific format (or it may even be inconsistent!) but you "know" it's dayfirst (or at least hope it is...), dayfirst is excellent for that._ Setting dayfirst to default to your system setting would mean (for the most part) you wouldn't need to care, whereas now calling without dayfirst leads to inconsistency/incorrect results.

Now I think about it, there is related bugginess:

```
In [5]: pd.to_datetime('1/12/00', dayfirst=True)
Out[5]: datetime.datetime(2000, 12, 1, 0, 0)

In [6]: pd.to_datetime('1/13/00', dayfirst=True)
Out[6]: datetime.datetime(2000, 1, 13, 0, 0)
```

When it should almost certainly raise here.

@hayd, please don't hide behaviour changes in commits marked "DOC", even
if you warn of them in issue comments.

That change would break working code for users in european locales who reasonably 
expect options under `display` to affect display only. very bad idea.

Also, not implementing it as on by default would make different users get different 
answers for the same code and it's usually best to avoid those kinds of hair pulling 
situations if possible.

It would be fine to add this as new option (bool `use_dayfirst`) under `options.mode` and 
clearly document it, but it should be opt-in only. It would also need to be in
effect wherever date parsing occurs in the codebase (read_csv etc), or it would create
confusion as to when you need to specify dayfirst in the method call and where
it's unnecessary. that's a lot of stuff to get right.

@y-p My bad about not making it ENH/DOC, the ENH change was a last minute thought, apologies for shoving it there.

The two lines are actually lifted from `parse_time_string`, which is why I thought it was ok to use the same...

You're right, changing the default would break working code. I'll delete those two lines and rebase.

I had no idea `parse_time_string` does that. how bizzare. Maybe I'm wrong in voting this down.

and it's used for "shortcut" slicing in timeseries as well, I really wouldn't have done that.
Still probably best not to change existing behaviour, although the inconsitent behaviour
is a wart.