Unsafe subtype: datetime/date

[m-aciek]

Fixes #9015.

This PR introduces safe-datetime error code, which makes mypy check fail for unsafe date and datetime classes inheritance, following @JukkaL's comment in the related issue.

Before:

from datetime import date, datetime

if datetime.now() < date.today():  # passing the type checking
    print("that's a surprise!")

After:

from datetime import date, datetime

if datetime.now() < date.today():  # E: Unsupported operand types for < ("datetime" and "date")
    print("that's a surprise!")

This is Copilot agent's work with my prompts' guidance. I reviewed the produced code. The change includes tests and documentation.

Alternatives considered

• remove the inheritance in the typeshed: Experiment: revert datetime-date inheritance typeshed#15136 (worse as it isn't configurable)

PR history

• first iteration was adding usafe-subtype code for other potential cases like date/datetime
• I simplified the approach tackling only date/datetime case as others are being handled separately.

[sterliakov]

Regarding str vs Iterable[str]: are you sure it's actually a good thing to do? I hate pandas decision to prohibit passing a single string as DataFrame columns, it adds unnecessary friction to quickly creating a one-off dataframe (one has to do columns=list('abc')). Is there a reason to reject passing str as Iterable[str] intentionally? Is it a common source of bugs in some codebase you know/work with?

[m-aciek]

Thank you for the review, I will update and benchmark the list/set for this case tomorrow, having an access to the desktop computer.

Regarding str vs Iterable[str]: are you sure it's actually a good thing to do? I hate pandas decision to prohibit passing a single string as DataFrame columns, it adds unnecessary friction to quickly creating a one-off dataframe (one has to do columns=list('abc')). Is there a reason to reject passing str as Iterable[str] intentionally? Is it a common source of bugs in some codebase you know/work with?

It was originally suggested by @JukkaL and I thought it was a good idea. I personally at least once in the past experienced or seen a bug that could have been prevented with such a check.

But this makes me think that maybe a way to select an unsafe subtyping class may be a good addition, to offer better control for mypy users, to let use only one inheritance pair, instead of covering only all or none.

[m-aciek]

I'm sorry, it takes me more than I thought to get back to this PR. It looks like #20577 addresses the case of the Iterable[str]/str separately. Probably we can drop this case here.

I looked around for another cases of an unsafe subtyping, and the other one would be bool/int relation. I couldn't find more. I wonder if there shouldn't be separate mypy codes/flags for each of those two cases for a better control and user experience. What do you think @JukkaL @sterliakov ?

[m-aciek]

As discussed in the parent issue, I've updated the PR to focus only on datetime/date case, using safe-datetime code. @sterliakov would you find a spare moment for the review of the updated approach? Thank you.

[wyattscarpenter]

This is just a nit (I haven't reviewed the PR in depth but it seems generally right to me) but the name of the error code should probably be unsafe-datetime, to match the pattern of other codes like unused-awaitable, explicit-any, and untyped-decorator: the error code usually describes the undesirable thing that was found (although you can find a number of exceptions to this rule already).

[github-actions]

According to mypy_primer, this change doesn't affect type check results on a corpus of open source code. ✅