Initial pandas.typing Module
State: closed

ref #25791 maybe more of a conversation starter than complete PR but wanted to stub out some types that appear commonly in pandas code-base.

Haven't used these yet as wanted to agree on type first. I wouldn't be surprised if we start seeing some issues pop up that would require real development changes once these get utilized

@jreback @jbrockmendel 

Labels:
name: Typing
description: type annotations, mypy/pyright type checking

Comments:
cool, can you use these in a couple of places? and some examples / docs-strings?
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25884?src=pr&el=h1) Report
> Merging [#25884](https://codecov.io/gh/pandas-dev/pandas/pull/25884?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/d40446044fc240f4ec6904d12a7821f0091f3b29?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `0%`.

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

```diff
@@            Coverage Diff             @@
##           master   #25884      +/-   ##
==========================================
- Coverage   91.48%   91.46%   -0.02%     
==========================================
  Files         175      176       +1     
  Lines       52885    52892       +7     
==========================================
  Hits        48380    48380              
- Misses       4505     4512       +7
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.03% <0%> (-0.02%)` | :arrow_down: |
| #single | `41.82% <0%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/25884?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/typing.py](https://codecov.io/gh/pandas-dev/pandas/pull/25884/diff?src=pr&el=tree#diff-cGFuZGFzL3R5cGluZy5weQ==) | `0% <0%> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25884?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/25884?src=pr&el=footer). Last update [d404460...e230500](https://codecov.io/gh/pandas-dev/pandas/pull/25884?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/25884?src=pr&el=h1) Report
> Merging [#25884](https://codecov.io/gh/pandas-dev/pandas/pull/25884?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/d40446044fc240f4ec6904d12a7821f0091f3b29?src=pr&el=desc) will **decrease** coverage by `0.01%`.
> The diff coverage is `0%`.

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

```diff
@@            Coverage Diff             @@
##           master   #25884      +/-   ##
==========================================
- Coverage   91.48%   91.46%   -0.02%     
==========================================
  Files         175      176       +1     
  Lines       52885    52892       +7     
==========================================
  Hits        48380    48380              
- Misses       4505     4512       +7
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.03% <0%> (-0.02%)` | :arrow_down: |
| #single | `41.82% <0%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/25884?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/typing.py](https://codecov.io/gh/pandas-dev/pandas/pull/25884/diff?src=pr&el=tree#diff-cGFuZGFzL3R5cGluZy5weQ==) | `0% <0%> (ø)` | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25884?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/25884?src=pr&el=footer). Last update [d404460...e230500](https://codecov.io/gh/pandas-dev/pandas/pull/25884?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/25884?src=pr&el=h1) Report
> Merging [#25884](https://codecov.io/gh/pandas-dev/pandas/pull/25884?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/1d4c89f4d747854def6c32733383b4afa250165d?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/25884/graphs/tree.svg?width=650&token=eZ4WkYLtcO&height=150&src=pr)](https://codecov.io/gh/pandas-dev/pandas/pull/25884?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #25884      +/-   ##
==========================================
- Coverage    91.8%   91.79%   -0.01%     
==========================================
  Files         174      175       +1     
  Lines       52536    52540       +4     
==========================================
  Hits        48231    48231              
- Misses       4305     4309       +4
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.35% <100%> (ø)` | :arrow_up: |
| #single | `41.88% <83.33%> (-0.07%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/25884?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/gcs.py](https://codecov.io/gh/pandas-dev/pandas/pull/25884/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2djcy5weQ==) | `80% <100%> (ø)` | :arrow_up: |
| [pandas/io/parsers.py](https://codecov.io/gh/pandas-dev/pandas/pull/25884/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3BhcnNlcnMucHk=) | `95.69% <100%> (ø)` | :arrow_up: |
| [pandas/io/s3.py](https://codecov.io/gh/pandas-dev/pandas/pull/25884/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3MzLnB5) | `89.47% <100%> (ø)` | :arrow_up: |
| [pandas/\_typing.py](https://codecov.io/gh/pandas-dev/pandas/pull/25884/diff?src=pr&el=tree#diff-cGFuZGFzL190eXBpbmcucHk=) | `100% <100%> (ø)` | |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/25884/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `75% <0%> (-12.5%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/25884/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `96.79% <0%> (-0.12%)` | :arrow_down: |

------

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

I don’t think so but not sure I follow - what’s the link between NumPy version and types?

Sent from my iPhone

> On Mar 26, 2019, at 5:05 PM, jbrockmendel <notifications@github.com> wrote:
> 
> @jbrockmendel commented on this pull request.
> 
> In pandas/typing.py:
> 
> > @@ -0,0 +1,14 @@
> +from datetime import datetime, timedelta
> +from pathlib import Path
> +from typing import AnyStr, IO, Union
> +
> +from pandas._libs.tslibs import Period, NaT, Timedelta, Timestamp
> +
> +
> +DateTimeLike = Union[datetime, timedelta, Period, Timedelta, Timestamp]
> Do/should the numpy versions go in here?
> 
> —
> You are receiving this because you authored the thread.
> Reply to this email directly, view it on GitHub, or mute the thread.

> I don’t think so but not sure I follow - what’s the link between NumPy version and types?

Bad phrasing on my part.  I was referring to np.datetime64 and np.timedelta64 objects.  Many of our functions that accept datetime inputs will also accept np.datetime64 inputs.  Ditto for timedelta.
Sure just added the FilePathOrBuffer type to io.parsers. CI will fail with the following:

```sh
pandas/io/parsers.py:445: error: Item "str" of "Union[str, Path, IO[Any]]" has no attribute "close"
pandas/io/parsers.py:445: error: Item "Path" of "Union[str, Path, IO[Any]]" has no attribute "close"
```

There's an implicit assumption in the codebase that a local variable `should_close` dictates whether or not a `close` method gets called, which Mypy doesn't like. I suppose that is rather fragile so refactor could be in line

@jbrockmendel any thoughts on where best to try out the DateTimeLike types?
> any thoughts on where best to try out the DateTimeLike types?

Not really.  I guess I'm not clear on the use case.  Aside from running mypy, are we actually doing anything with these?
Use case would be to improve readability and maintainability of code base and in theory reducing bugs. There's some refactor that will go hand in hand with it (as you might have seen with some of the IO stuff above).

This is just starting things off and there's a long way to go. I think I might split off the datetimelike stuff for this for now and just focus on IO. Can see how that goes and learn from there
see some suggestions: https://github.com/pandas-dev/pandas/pull/25829 (can be a followup)
looks fine. better to start small. merge if you like (or add more up 2 you)
merging this so can start using it. less concerned about the test as its private.