TYPING: add skeleton stub for Timestamp
State: closed

xref #28133

This PR adds just the skeleton so that the attributes, methods and arguments available are known.

in this PR, the methods starting with an underscore have been omitted and the attributes typed with Any. This follows default stubgen output. https://mypy.readthedocs.io/en/latest/stubgen.html#automatic-stub-generation-stubgen

fix for `pandas\core\arrays\datetimes.py:275: error: Incompatible types in assignment (expression has type "Type[Timestamp]", base class "AttributesMixin" defined the type as "Type[DatetimeLikeScalar]")` arising from adding type information for Timestamp.

relevant diff for `mypy pandas --disallow-any-unimported`...

```
< pandas\_typing.py:23: error: Constraint 2 becomes "Any" due to an unfollowed import
7d5
< pandas\core\dtypes\dtypes.py:653: error: Type of variable becomes "Type[Any]" due to an unfollowed import
44,45d41
< pandas\core\arrays\_ranges.py:15: error: Argument 1 to "generate_regular_range" becomes "Any" due to an unfollowed import
< pandas\core\arrays\_ranges.py:15: error: Argument 2 to "generate_regular_range" becomes "Any" due to an unfollowed import
129c125
< pandas\io\formats\format.py:1550: error: Argument 1 to "_format_datetime64" becomes "Union[Any, Any]" due to an unfollowed import
---
> pandas\io\formats\format.py:1550: error: Argument 1 to "_format_datetime64" becomes "Union[Any, Timestamp]" due to an unfollowed import
131c127
< pandas\io\formats\format.py:1567: error: Argument 1 to "_format_datetime64_dateonly" becomes "Union[Any, Any]" due to an unfollowed import
---
> pandas\io\formats\format.py:1567: error: Argument 1 to "_format_datetime64_dateonly" becomes "Union[Any, Timestamp]" due to an unfollowed import
```

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

Comments:
I'm happy to defer to folks who have thought about typing more than me, but my initial reaction tot this is that we're getting more verbose but not more clear
I think were still going trough a pain period before we can really reap the benefits.

mypy ensures that class structures comply with the Liskov Substitution Principle. 

For instance, we need isinstance checks for subclasses in places where we should be able to operate without the check, i.e. Index.format and MutliIndex.format
we need to just establish a process there is a high probability that if you
start adding types it will find other problems in the code base and then
the diff
 would be much bigger

On Wed, 28 Aug 2019, 18:26 William Ayd, <notifications@github.com> wrote:

> *@WillAyd* commented on this pull request.
> ------------------------------
>
> In pandas/_libs/tslibs/timestamps.pyi
> <https://github.com/pandas-dev/pandas/pull/28195#discussion_r318702076>:
>
> > +class RoundTo:
> +    @property
> +    def MINUS_INFTY(self) -> int: ...
> +    @property
> +    def PLUS_INFTY(self) -> int: ...
> +    @property
> +    def NEAREST_HALF_EVEN(self) -> int: ...
> +    @property
> +    def NEAREST_HALF_PLUS_INFTY(self) -> int: ...
> +    @property
> +    def NEAREST_HALF_MINUS_INFTY(self) -> int: ...
> +
> +def round_nsint64(values, mode, freq): ...
> +
> +class Timestamp:
> +    value: Any = ...
>
> Is the plan here just to get this in first then refine types later? Seems
> like some of these could easily be inferred more strictly than any
>
> —
> You are receiving this because you authored the thread.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/28195?email_source=notifications&email_token=ADEMUXKHSVYKPNWCPVUHPTLQG2YLRA5CNFSM4IRKCCB2YY3PNVWWK3TUL52HS4DFWFIHK3DMKJSXC5LFON2FEZLWNFSXPKTDN5WW2ZLOORPWSZGOCC7X57I#pullrequestreview-280985341>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ADEMUXLJU4RJTWPHTS25UPLQG2YLRANCNFSM4IRKCCBQ>
> .
>

@WillAyd OK to merge?
having the skeleton stub is too beneficial to not get in play.

having just the attributes, methods and arguments will catch..

```
from pandas import Timestamp

t = Timestamp()

t.foo
t.bar()
t.dayofweek = 1
t.tz_localize(foo=10)
```
```
timestamp.py:5: error: "Timestamp" has no attribute "foo"
timestamp.py:6: error: "Timestamp" has no attribute "bar"
timestamp.py:7: error: Property "dayofweek" defined in "Timestamp" is read-only
timestamp.py:8: error: Unexpected keyword argument "foo" for "tz_localize"
```

the types can start to be added as a follow on or as needed. 

from the docs "Note that if you decide to write your own stub files, they don’t need to be complete! A good strategy is to add stubs for just the parts of the library you need and iterate on them over time."
https://mypy.readthedocs.io/en/latest/running_mypy.html#missing-imports
does this have any immediate benefit? 
we have no testing on this to ensure it’s consistent correct? if so i am -1
Realize this was closed but are there any other options for having mypy detect annotations for Cython files? Assumed stub files like this were the only way
@simonjayhawkins didnlt mean for you to close this

was more wanting to understand the reasoning here
> Realize this was closed but are there any other options for having mypy detect annotations for Cython files? Assumed stub files like this were the only way

if we don't use stubs, we should discuss the alternatives in #28133 rather than here.
> we have no testing on this to ensure it’s consistent correct? if so i am -1

correct, we have no guarantee that the stub file stays in sync.
> > we have no testing on this to ensure it’s consistent correct? if so i am -1
> 
> correct, we have no guarantee that the stub file stays in sync.

cython/cython#3818 should help us move forward with this.