ENH: PeriodIndex now has period dtype
State: closed

- [x] split from #13755. 
- [x] tests added / passed
- [x] passes `git diff upstream/master | flake8 --diff`
- [x] whatsnew entry

splitted `dtype` related part from #13755, to clarify the differences related to `PeriodIndex`


Labels:
name: Dtype Conversions
description: Unexpected or buggy dtype conversions
name: API Design
name: Period
description: Period data type

Comments:
Looks superb! Thanks @sinhrks 

## [Current coverage](https://codecov.io/gh/pydata/pandas/pull/13941?src=pr) is 85.30% (diff: 92.80%)

> Merging [#13941](https://codecov.io/gh/pydata/pandas/pull/13941?src=pr) into [master](https://codecov.io/gh/pydata/pandas/branch/master?src=pr) will increase coverage by **0.01%**

``` diff
@@             master     #13941   diff @@
==========================================
  Files           139        139          
  Lines         50241      50346   +105   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits          42851      42947    +96   
- Misses         7390       7399     +9   
  Partials          0          0          
```

> Powered by [Codecov](https://codecov.io?src=pr). Last update [5d791cc...a968782](https://codecov.io/gh/pydata/pandas/compare/5d791cc7d955c0b074ad602eb03fa32bd3e17503...a968782b289f57ada457ac45ef302da0196527dc?src=pr)

What do you get when you write `np.array(period_index)` or `period_index.values`? Currently these give back arrays of integers, which IMO is pretty broken.

@shoyer yeah that should return an object array of Periods (similar to what a datetime tz does)

split `.values` change as #13988, as it can be handled separately. 

@sinhrks a couple of minor changes, but otherwise lgtm. period is currently broken as its `int64` for its dtype. This makes things much more consistent (on the index side).

Cool!

Some first comments:
- I think this needs more documentation. Eg explaining that the freq is included in the dtype, that you can also do `dtype='period[freq]'`, more stress the API change in the dtype (it's no longer int). Further, also the narrative docs should be updated (not only the whatsnew).
- the repr is now a bit redundant (twice the 'D'):
  
  ```
  In [25]: pi
  Out[25]: PeriodIndex(['2016-08-01'], dtype='period[D]', freq='D')
  ```
  
  Leave out the freq? (although it is also useful to inform the user that the 'D' can be accessed as the freq ...)
- Is there a reason that `dtype_str` does not include the freq?

could add some docs like this: http://pandas.pydata.org/pandas-docs/stable/timeseries.html#tz-aware-dtypes

OK, added doc section to `timeseries.rst`. Also fixed followings:
- `dtype_str` now uses the same repr as `str(dtype)` (use `Index` impl)
- `astype` related things

I don't have strong opinion about dtype repr, but it may better to keep it (different from timezone, users cannot distinguish freq if they don't know freq string).

@sinhrks I had some comments on the wording, but thought it was maybe easier to just change it myself while reviewing than adding a bunch of minor comments -> https://github.com/sinhrks/pandas/pull/2. I hope that is OK

The linter is failing on blank lines:

pandas/tests/types/test_dtypes.py:369:1: E303 too many blank lines (3)

just some minor changes / perf checks. Getting the `is_period_type` to be fast in the common case is important. For datetime w/tz took me several tries to make this happen 

thanks @sinhrks nice change!

Thx for review. Because #14010 includes some period related tests, it'll broken on master. I'll send a fix soon.