TYP: add some properties to Timestamp
State: closed

For typing, add for `Timestamp`:
- `dayofweek`
- `dayofyear`
- `days_in_month`
- `daysinmonth`



Labels:
name: Typing
description: type annotations, mypy/pyright type checking
name: Timestamp
description: pd.Timestamp and associated methods

Comments:
> Are there plans to only expose `day_some_thing` or `daysomething`? Bit weird to have both/a mix of them.

for instance, `day_of_year` was deprecated in https://github.com/pandas-dev/pandas/issues/1723 and then added again in #37390 and it looks like the intention was to deprecate `dayofyear` and `dayofweek`  but there was no response to https://github.com/pandas-dev/pandas/pull/37390#issuecomment-716556106 to confirm this.

from a much earlier PR both `days_in_month`/`daysinmonth` were added together https://github.com/pandas-dev/pandas/pull/9605#issuecomment-77626685

from https://github.com/pandas-dev/pandas/issues/1723#issue-5990831

> ... it may be best to remove the day_of_year method so that there is only one obvious way to do it.

Save any toing and froing in the future I think we could probably leave `dayofweek`, `dayofyear` and `daysinmonth` out of the type stubs as these are coded as aliases of the others in pandas/_libs/tslibs/timestamps.pyx and in the absence of deprecation, we could still consider `day_of_week`, `day_of_year` and `days_in_month` the preferred way to access these and encourage this by only including these in the stubs.
> Save any toing and froing in the future I think we could probably leave `dayofweek`, `dayofyear` and `daysinmonth` out of the type stubs as these are coded as aliases of the others in pandas/_libs/tslibs/timestamps.pyx and in the absence of deprecation, we could still consider `day_of_week`, `day_of_year` and `days_in_month` the preferred way to access these and encourage this by only including these in the stubs.

If that's the case, then we shouldn't document them either.  IMHO, if we document it, we should include it in the stubs, which is why I added them in the stubs.


> If that's the case, then we shouldn't document them either. IMHO, if we document it, we should include it in the stubs, which is why I added them in the stubs.

could perhaps consider removing from documentation too.

I may be wrong here, but I was under the impression that pylance uses the stubs for a better user experience with code completion? If this is the case, it may be better if the recommendations only include the recommended attributes and not the aliases allowed for backwards compatibility.

we already in some of the overloads only include some parameters as keyword only even though these are not yet deprecated.

do we know why the aliases are currently missing from the stub. Was it intentional?
> could perhaps consider removing from documentation too.
> 
Doesn't that imply we are making the decision on deprecation?

> I may be wrong here, but I was under the impression that pylance uses the stubs for a better user experience with code completion? If this is the case, it may be better if the recommendations only include the recommended attributes and not the aliases allowed for backwards compatibility.

pylance uses it for code completion and for type checking.  mypy will use it for type checking, so that if a user used the "old" way (e.g., `dayofweek`), we need to determine if we want a user to get a complaint from `mypy`.  That's how I discovered this - there was some old code written by a colleague that used `dayofweek` - it's documented - and pylance reported it as not being a valid method for `Timestamp`.

> 
> we already in some of the overloads only include some parameters as keyword only even though these are not yet deprecated.
> 
> do we know why the aliases are currently missing from the stub. Was it intentional?

Probably an oversight.  Looking at the first creation of `timestamps.pyi` in #40945, `day_of_week`, `dayofweek`, `day_of_year`, `dayofyear`, `days_in_month` and `daysinmonth` were all missing.  Then `day_of_week` and `day_of_year` were added in #44339 .   


> Doesn't that imply we are making the decision on deprecation?

That's what @jreback was asking in https://github.com/pandas-dev/pandas/pull/37390#issuecomment-716556106. maybe we need a dedicated issue to seek consensus.

> so that if a user used the "old" way (e.g., `dayofweek`), we need to determine if we want a user to get a complaint from `mypy`. 

I think that's OK. nbd to add a type ignore if you don't want to clean up the code there and then.


> That's what @jreback was asking in [#37390 (comment)](https://github.com/pandas-dev/pandas/pull/37390#issuecomment-716556106). maybe we need a dedicated issue to seek consensus.

Created https://github.com/pandas-dev/pandas/issues/46768