API: add Series.dt delegator for datetimelike methods (GH7207)
State: closed

closes #7207

```
In [1]: s = Series(date_range('20130101',periods=3))

In [2]: s.dt.
s.dt.date              s.dt.dayofweek         s.dt.hour              s.dt.is_month_start    s.dt.is_quarter_start  s.dt.is_year_start     s.dt.minute            s.dt.nanosecond        s.dt.second            s.dt.week              s.dt.year              
s.dt.day               s.dt.dayofyear         s.dt.is_month_end      s.dt.is_quarter_end    s.dt.is_year_end       s.dt.microsecond       s.dt.month             s.dt.quarter           s.dt.time              s.dt.weekofyear        

In [3]: s.dt.year
Out[3]: array([2013, 2013, 2013])

In [4]: s.dt.hour
Out[4]: array([0, 0, 0])

In [5]: Series(np.arange(5)).dt
TypeError: Can only use .dt accessor with datetimelike values
```

Tab completion is specific to the type of wrapped delegate (DatetimeIndex or PeriodIndex)

```
In [5]: p = Series(period_range('20130101',periods=3,freq='D').asobject)

In [6]: p.dt.
p.dt.day         p.dt.dayofweek   p.dt.dayofyear   p.dt.hour        p.dt.minute      p.dt.month       p.dt.quarter     p.dt.qyear       p.dt.second      p.dt.week        p.dt.weekofyear  p.dt.year        
```


Labels:
name: Enhancement
name: API Design

Comments:
Looks good! Thanks for this. The only thing I was thinking to have it named `DatetimeAttributes` more in line with `StringMethods`, but doesn't matter.

Only should need some dos (whatsnew, addition to the API (http://pandas.pydata.org/pandas-docs/stable/api.html#time-series-related), and somewhere else in the docs)

yeh could change the name

@jorisvandenbossche ok, this nicely builds the API (similar to StringMethods).

@jorisvandenbossche 

when accessing a doc-string for a property

`s.dt.hour?` it 'works' in that the doc-string is printed, but all of the property info is also printed, any way to prevent that? (is my function creator wrong?)

```
In [1]: s = Series(date_range('20130101',periods=5))

In [2]: s.dt.hour
Out[2]: 
0    0
1    0
2    0
3    0
4    0
dtype: int64

In [3]: s.dt.hour?
Type:            property
String form:     <property object at 0x47998e8>
Docstring:       The hours of the datetime
Class docstring:
property(fget=None, fset=None, fdel=None, doc=None) -> property attribute

fget is a function to be used for getting an attribute value, and likewise
fset is a function for setting, and fdel a function for del'ing, an
attribute.  Typical use is to define a managed attribute x:
class C(object):
    def getx(self): return self._x
    def setx(self, value): self._x = value
    def delx(self): del self._x
    x = property(getx, setx, delx, "I'm the 'x' property.")

Decorators make defining new properties or modifying existing ones easy:
class C(object):
    @property
    def x(self): return self._x
    @x.setter
    def x(self, value): self._x = value
    @x.deleter
    def x(self): del self._x
```

if you have a specific method, then just define it directly (after all this is just a convience to avoid writing each method manuall). which are you referring?

I've added the possibility for a setter in https://github.com/JanSchulz/pandas/commit/1b52a715e069d1fad660a01d1cded8638b16cbfb

gr8; I'll incorporate that and repush

Re "different methods": I just noticed that when I wrote my implementation of "CategoricalProperties" (in the end it was not needed).

@JanSchulz updated to incorporate the get/set

@jreback for the property docs, I think that this is an IPython issue (see https://github.com/ipython/ipython/issues/1555, and fixed by @immerrr in https://github.com/ipython/ipython/pull/4827 which will be in IPython 3.0 I think). 
If you do the plain python help way `help()` it does return only the docstring.

Nice docs! Added some but very minor comments.

A `, use this-and-that.` would be nice :-)

ok in the last

what's a 'use this or that ' mean?

Reading this as a "phd student who does some data munging" would leave me confused:
"A value is trying to be set on an immutable datetimelike object"

So something like this:
"Changing values on '%s' is not supported, change the values on the original Series." % name

What about:

> Modifications to a property of a datetimelike object are not supported and are discarded. Change values on the original {0}.

This is a great PR, looking forward to this!

@hayd Much better!

@JanSchulz @hayd updated to your text for the error messages

@jorisvandenbossche @cpcloud 

cc @rosnfeld 
cc @mtkni

any other comments?

Looking good to me (just two typo/grammar things), and this is a nice enhancement!

I pulled the changes and played around with it, looks very good to me. The only minor improvement I'd suggest is a tiny bit more documentation on the actual DateTimeProperties/PeriodProperties code, i.e. compare:

``` python
In [5]: s.str?
Type:       StringMethods
String Form:<pandas.core.strings.StringMethods object at 0x3c23410>
File:       /home/andrew/git/pandas-rosnfeld/pandas/core/strings.py
Docstring:
Vectorized string functions for Series. NAs stay NA unless handled
otherwise by a particular method. Patterned after Python's string methods,
with some inspiration from R's stringr package.

Examples
--------
>>> s.str.split('_')
>>> s.str.replace('_', '')

In [6]: s.dt?
Type:       DatetimeProperties
String Form:<pandas.tseries.common.DatetimeProperties object at 0x3c06150>
File:       /home/andrew/git/pandas-rosnfeld/pandas/tseries/common.py
Docstring:  Manages a DatetimeIndex Delegate
```

@rosnfeld makes sense, I will emulate

```
In [3]: s.dt?
Type:        DatetimeProperties
String form: <pandas.tseries.common.DatetimeProperties object at 0x3a76650>
File:        /mnt/home/jreback/pandas/pandas/tseries/common.py
Docstring:
Accessor object for datetimelike properties of the Series values.

Examples
--------
>>> s.dt.hour
>>> s.dt.second
>>> s.dt.quarter

Returns a Series indexed like the original Series.
Raises TypeError if the Series does not contain datetimelike values.

In [4]: quit()
```

Nice - thanks!

bombs away.