DEPR: __array__ for tz-aware Series/Index
State: closed

This deprecates the current behvior when converting tz-aware Series
or Index to an ndarray. Previously, we converted to M8[ns], throwing
away the timezone information. In the future, we will return an
object-dtype array filled with Timestamps, each of which has the correct
tz.

```python
In [1]: import pandas as pd; import numpy as np

In [2]: ser = pd.Series(pd.date_range('2000', periods=2, tz="CET"))

In [3]: np.asarray(ser)
/bin/ipython:1: FutureWarning: Converting timezone-aware DatetimeArray to timezone-naive ndarray with 'datetime64[ns]' dtype. In the future, this will return an ndarray with 'object' dtype where each element is a 'pandas.Timestamp' with the correct 'tz'.
        To accept the future behavior, pass 'dtype=object'.
        To keep the old behavior, pass 'dtype="datetime64[ns]"'.
  #!/Users/taugspurger/Envs/pandas-dev/bin/python3
Out[3]:
array(['1999-12-31T23:00:00.000000000', '2000-01-01T23:00:00.000000000'],
      dtype='datetime64[ns]')
```

xref https://github.com/pandas-dev/pandas/issues/23569

closes https://github.com/pandas-dev/pandas/issues/15750

Labels:
name: Datetime
description: Datetime data dtype
name: Timezones
description: Timezone data dtype
name: Deprecate
description: Functionality to remove in pandas

Comments:
xrefing https://github.com/pandas-dev/pandas/issues/15750 as I think it's related to the eventual end goal.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24596?src=pr&el=h1) Report
> Merging [#24596](https://codecov.io/gh/pandas-dev/pandas/pull/24596?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/62506ca3c37b6b0d84833a8329e50c000316250e?src=pr&el=desc) will **decrease** coverage by `49.33%`.
> The diff coverage is `28.88%`.

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

```diff
@@             Coverage Diff             @@
##           master   #24596       +/-   ##
===========================================
- Coverage   92.38%   43.05%   -49.34%     
===========================================
  Files         166      166               
  Lines       52478    52514       +36     
===========================================
- Hits        48483    22609    -25874     
- Misses       3995    29905    +25910
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `?` | |
| #single | `43.05% <28.88%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24596?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexing.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhpbmcucHk=) | `51.83% <0%> (-42.04%)` | :arrow_down: |
| [pandas/core/reshape/tile.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS90aWxlLnB5) | `11.36% <0%> (-83.47%)` | :arrow_down: |
| [pandas/core/groupby/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9ncm91cGJ5LnB5) | `24.28% <0%> (-72.53%)` | :arrow_down: |
| [pandas/core/dtypes/cast.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2Nhc3QucHk=) | `48.59% <0%> (-40.14%)` | :arrow_down: |
| [pandas/core/arrays/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lcy5weQ==) | `65.78% <100%> (-32.24%)` | :arrow_down: |
| [pandas/core/internals/construction.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW50ZXJuYWxzL2NvbnN0cnVjdGlvbi5weQ==) | `62.5% <100%> (-34.17%)` | :arrow_down: |
| [pandas/core/internals/blocks.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW50ZXJuYWxzL2Jsb2Nrcy5weQ==) | `51.58% <14.28%> (-42.91%)` | :arrow_down: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `49.33% <40%> (-44.21%)` | :arrow_down: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `48.45% <50%> (-47.78%)` | :arrow_down: |
| [pandas/core/dtypes/dtypes.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2R0eXBlcy5weQ==) | `73.52% <66.66%> (-21.82%)` | :arrow_down: |
| ... and [133 more](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24596?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/24596?src=pr&el=footer). Last update [62506ca...ea44792](https://codecov.io/gh/pandas-dev/pandas/pull/24596?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24596?src=pr&el=h1) Report
> Merging [#24596](https://codecov.io/gh/pandas-dev/pandas/pull/24596?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/19f715c51d16995fc6cd0c102fdba2f213a83a0f?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #24596      +/-   ##
==========================================
- Coverage   92.37%   92.37%   -0.01%     
==========================================
  Files         166      166              
  Lines       52396    52415      +19     
==========================================
+ Hits        48403    48420      +17     
- Misses       3993     3995       +2
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.8% <100%> (-0.01%)` | :arrow_down: |
| #single | `43.01% <37.14%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/24596?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/dtypes/dtypes.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2R0eXBlcy5weQ==) | `95.58% <100%> (+0.03%)` | :arrow_up: |
| [pandas/core/indexing.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhpbmcucHk=) | `93.87% <100%> (ø)` | :arrow_up: |
| [pandas/core/reshape/tile.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS90aWxlLnB5) | `94.88% <100%> (+0.05%)` | :arrow_up: |
| [pandas/core/arrays/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2RhdGV0aW1lcy5weQ==) | `98.01% <100%> (ø)` | :arrow_up: |
| [pandas/core/internals/blocks.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW50ZXJuYWxzL2Jsb2Nrcy5weQ==) | `94.16% <100%> (-0.06%)` | :arrow_down: |
| [pandas/core/nanops.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvbmFub3BzLnB5) | `94.36% <100%> (ø)` | :arrow_up: |
| [pandas/core/groupby/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS9ncm91cGJ5LnB5) | `96.8% <100%> (ø)` | :arrow_up: |
| [pandas/core/dtypes/cast.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL2Nhc3QucHk=) | `88.72% <100%> (ø)` | :arrow_up: |
| [pandas/core/indexes/datetimes.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZXMucHk=) | `96.26% <100%> (+0.03%)` | :arrow_up: |
| [pandas/core/internals/construction.py](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW50ZXJuYWxzL2NvbnN0cnVjdGlvbi5weQ==) | `95.93% <100%> (-0.75%)` | :arrow_down: |
| ... and [7 more](https://codecov.io/gh/pandas-dev/pandas/pull/24596/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/24596?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/24596?src=pr&el=footer). Last update [19f715c...50f4fbd](https://codecov.io/gh/pandas-dev/pandas/pull/24596?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

I can reproduce the failures with older numpys locally. Debugging that now.
Turns out it was bottleneck

@jreback right now `bn_ok_dtype` excludes datetime & timedelta, but not datetimetz in https://github.com/pandas-dev/pandas/blob/19f715c51d16995fc6cd0c102fdba2f213a83a0f/pandas/core/nanops.py#L147

I assume we don't want to pass datetimetz to bottleneck, since the actual operation should be done on the same values (i8 or M8[ns]).
right should exclude anything that matches needs_i8_conversion
https://github.com/pandas-dev/pandas/pull/24596/commits/349f818a712cf4d641727aa2b86f6107846e2a15 updates with

* changes the parameter name from `result` to `dtype` to match the array interface
* Expands the docstring
* Adds to the API docs (along with a few others that were missing)
All green. I think things are decent here.

I didn't add a TODO in 
https://github.com/pandas-dev/pandas/pull/24596#discussion_r245082156. I could really make sense of what's going on there / when the best time to convert a list-like to an array-like would be.
thanks!
This didn't make it onto #6581, should we enforce it for 1.0?
I don't have a strong opinion.
@jbrockmendel I'll put up a PR enforcing this, just so we have https://github.com/pandas-dev/pandas/issues/6581 cleared.