ENH: Add timetz attribute to DatetimeIndex and Timestamp

[mroeschke]

Currently DatetimeIndex.time returns a numpy array of local datetime.times. In #18461, the resulting datetime.times gained timezone information (but was an undocumented changed) and was subsequently reverted in #21281. Having .time return timezone information would still be a nice enhancement.

If we allow DatetimeIndex.time to return timezone information, timeseries.rst will need to be changed since it currently indicates that .time does not return timezone information.

[jquinon]

Can I work on this? I'm new to working on pandas, but this seems like a fairly simple issue to get started with.

[mroeschke]

Go for it @jquinon! The main job would be to undo the revision in #21281 make sure this change is documented.

[mroeschke]

So now DatetimeIndex.time matches datetime.time() (minus the property vs method difference) which is an ideal consistency.

However, there is a datetime.timetz() method that returns time with timezone information. We could match the api and have a DatetimeIndex.timetz method, but I am not the biggest fan of the name.

I would prefer instead having DatetimeIndex.time(tz=False) that would match the method-like time api of the standard library, but use a keyword arg to return tz information.

Thoughts?

[jreback]

yeah that would be ok except it’s current a property - not sure we can change this

[mroeschke]

It would be an API change; otherwise, I don't recall an internal reason why we can't break it.

[jorisvandenbossche]

I am not sure this (adding a tz keyword) is worth the API change. Changing from a attribute to method is a quite big change, as every use of the current attribute would be impacted.

[mroeschke]

Fair enough. Should we then mimic the standard library and add a .timetz property?