TYP: add some properties to Timestamp

[Dr-Irv]

For typing, add for Timestamp:

• dayofweek
• dayofyear
• days_in_month
• daysinmonth

[twoertwein]

Looks good to me!

Are there plans to only expose day_some_thing or daysomething? Bit weird to have both/a mix of them.

[simonjayhawkins]

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 #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 #37390 (comment) to confirm this.

from a much earlier PR both days_in_month/daysinmonth were added together #9605 (comment)

from #1723 (comment)

... 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.

[simonjayhawkins]

in stubs could these be defined as aliases or do they need to be declared separately?

[Dr-Irv]

They have to be declared separately in stubs, because the type checkers won't see that it is a property if you put the alias in the stubs.

[Dr-Irv]

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.

[simonjayhawkins]

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?

[Dr-Irv]

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 .

[simonjayhawkins]

Doesn't that imply we are making the decision on deprecation?

That's what @jreback was asking in #37390 (comment). 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.

[Dr-Irv]

That's what @jreback was asking in #37390 (comment). maybe we need a dedicated issue to seek consensus.

Created #46768