Deprecate allowing datetime.datetime instances as values for Date traits

[mdickinson]

This PR paves the way for eventually making it illegal to pass a datetime.datetime instance to a Date trait:

• Change the default for allow_datetime to None rather than True
• If allow_datetime is not supplied and the user tries to assign a datetime.datetime value to a Date trait, a DeprecationWarning is issued. In the future (ideally in Traits 7.0), a TraitError will be raised.

Rationale: right now, Date allows any value that's an instance of the Python std. lib. datetime.date class. Somewhat surprisingly, Python's datetime.datetime is a subclass of datetime.date. But in typical uses for the Date trait, we really do want to specify a date and not a datetime.

Users who do want to allow datetimes in addition to date can modify their code in a number of ways to avoid the warning: for example, using Union(Datetime(), Date()), Instance(datetime.date), or Date(allow_datetime=True).

Users can also opt in to the future behaviour right now by using Date(allow_datetime=False).

Checklist

• Tests
• Update API reference (docs/source/traits_api_reference) (docstring updated)
• Update User manual (docs/source/traits_user_manual) N/A
• Update type annotation hints in traits-stubs N/A (the default for allow_datetime has changed, but that default isn't recorded in the stub)

[mdickinson]

This test is redundant with the new test_assign_datetime_with_allow_datetime_not_given test

[mdickinson]

@kitchoi Would this PR meet your project's needs?

[kitchoi]

@mdickinson Thank you for this. I haven't reviewed the code change in details but the intended behaviour looks good to me!

Would this PR meet your project's needs?

Recalling the other project that motivated #398, I believe the answer is yes. With the caveat that my memory of the context is rather dated, here is the details:
The deprecation warning would be rather helpful in capturing programming errors in tests, where DeprecationWarning triggered at runtime are visible. Situations where tests deviate from reality would be harder to capture, as DeprecationWarning won't be visible in production environments (e.g. web server, cronjob, GUI). Just an idea: the DeprecationWarning might need to be bumped to a FutureWarning in a later release?

For the project that revived the discussion around disallowing datetime for Date, allow_datetime=False has been preemptively installed so we won't see deprecation warnings, instead we will get an error if all due diligence has failed to capture anomalies.

Minor: Did you mean to change Union(Datetime, Date) to Union(Datetime(), Date()) in the main description too?

[mdickinson]

Just an idea: the DeprecationWarning might need to be bumped to a FutureWarning in a later release?

Yes, we still don't have a good solution to this problem. FutureWarning isn't really the right thing: it's intended really as a warning to users of an application, rather than developers (and indeed it would result in spurious warnings that were visible to users of Traits-using applications, not just the developers of those applications).

Part of the solution might be simply to recommend that deprecation warnings always be turned on during manual testing of an application, and providing patterns for doing that. But I think this discussion is out of scope for Traits itself.

[mdickinson]

Minor: Did you mean to change Union(Datetime, Date) to Union(Datetime(), Date()) in the main description too?

Thanks! I didn't, but it's a good idea. Done.

[rahulporuri]

LGTM

[rahulporuri]

I was going through the documentation to see if anything needed to be updated - but from the looks of it, Date is not documented in the "Predefined Traits" section of the docs.

We might want to include Date in the above section.

[mdickinson]

Agreed; opened #1445 for this.