Period.end_time should be exclusive or Period should provide duration property

[malina-kirn]

A user may expect that the end_time of a Period minus the start_time of a Period returns its duration. Unfortunately, the end_time of a Period is inclusive, consequently, subtracting start from end yields an incorrect period duration:

jan = Period('2014-01', freq='M')
(jan.end_time - jan.start_time).days # returns 30, not 31

This can be manually rectified by the user:

jan = Period('2014-01', freq='M')
(Timestamp(jan.end_time.value + 1) - jan.start_time).days # correctly returns 31

However, this is not intuitive.

The end_time should either be exclusive or Period should provide a duration property.

Although a strong argument can be made that the definitions of duration, start_time, and end_time should all be consistent, changing the end_time definition to exclusive is a significant modification of long-standing behavior.

Consequently, I propose the addition of a duration property that is logically inconsistent with subtracting start_time from end_time.

[jreback]

I think the start_time,end_time are consistent and intuitive now. Though I can see when you subtract them you might be suprised. I think more surprising would be an end_time which is NOT included in the advertised Period (e..g. in your example returning Period('2014-1',freq='M').end_time == Timestamp('20140201'))

.duration seems reasonable. @shoyer ?

[shoyer]

.duration does seem reasonable -- this would be a Timedelta, yes?

[malina-kirn]

Yes, datetime.timedelta seems the appropriate type.

[malina-kirn]

Apologies, I hadn't realized Timedelta was introduced in 0.15.0. That would seem to be the better type.

[jbrockmendel]

@jreback IIRC there was a semi-recent change to subtract 1 ns from end_time for reasons related to this. Closeable?

[jreback]

yeah i think this is closeable. maybe we should also provide a duration though.

[jorisvandenbossche]

IIRC there was a semi-recent change to subtract 1 ns from end_time for reasons related to this.

I don't think this was recent, but already the case when this issue was discussed (at least it is already this behaviour in 0.14).

I don't know if it is important enough to keep the issue open, but the original reported problem is still valid I think?

Although, (jan.end_time - jan.start_time).days now does give 31 instead of 30, but is that a bug?

In [36]: jan = pd.Period('2014-01', freq='M')                                                                                                                                   

In [37]: td = (jan.end_time - jan.start_time)                                                                                                                                   

In [38]: td                                                                                                                                                                     
Out[38]: Timedelta('30 days 23:59:59.999999')

In [39]: td.components                                                                                                                                                          
Out[39]: Components(days=30, hours=23, minutes=59, seconds=59, milliseconds=999, microseconds=999, nanoseconds=999)

In [40]: td.days                                                                                                                                                                
Out[40]: 31

Or is that a purposed change? (this only changed in 0.23)