feat: Warn on incompatible TimeUnit in pandas<2

[benrutter]

What type of PR is this? (check all applicable)

• 💾 Refactor
• ✨ Feature
• 🐛 Bug Fix
• 🔧 Optimization
• 📝 Documentation
• ✅ Test
• 🐳 Other

Related issues

• Related issue warn or raise on explicit incompatible TimeUnit #2964
• Closes warn or raise on explicit incompatible TimeUnit #2964

Checklist

• Code follows style guide (ruff)
• [-] Tests added (this happens within a pragma no cover block - I'm happy to take off the no-cover and add a test, but I think it potentially could require a pre-v2 pandas tests, or some clever patching?)
• Documented the changes

If you have comments or can explain your changes, please do so below

In order to tell between a default "us" and a specified "us", I've added in a _defaulted object variable to DateTime. This feels a little crufty, but I'm not sure I can see a better option?

[benrutter]

⚠️ Note that might be important in a subtle way that I haven't realised ⚠️

In order to make this consistent type wise, I've actually altered the narwhals/v1 type signature for dtypes. This feels like it could be a red-flag depending how type-strict folks our? Essentially, a None value can now (and is by default) be passed to time_unit, which under the hood switched to us but indicates that the time_unit has been set by default rather than explicitly.

I'm pretty sure this behaviour doesn't actually change anything for anyone's code, and it definitely doesn't invalidate any existing code, but editing stable/v1 makes me feel nervous 😅

[dangotbanned]

Thanks for the PR @benrutter!

In order to tell between a default "us" and a specified "us", I've added in a _defaulted object variable to DateTime. This feels a little crufty, but I'm not sure I can see a better option?

What I was trying (and failed 😭) to suggest in (#2964 (comment)) was intended to only change things in _pandas_like

Fully my bad on that one - hopefully the comments here help explain things better

[dangotbanned]

In the warning I would like to see:

• Which time_unit is being ignored?
• Why is it being ignored?
  • Possibly a link to pandas changelog
  • Or mention the required + found versions in the style of
    

    narwhals/narwhals/_utils.py

    Line 1877 in d318ad3

    NotImplementedError: `really_complex_feature` is only available in 'pyarrow>=9000.0.0', found version '20.0.0'.

• How can I fix this?
  • Upgrading pandas is an option
  • but not the only one and probably not the easiest if they're stuck on a 2+ year old version 😄

[benrutter]

Thanks, that's really helpful! I've updated the error to:

msg = (
    f"The time unit '{dtype.time_unit}' has been specified but is only "
    f"available in pandas>2.0, found version {pd.__version__}."
    "To avoid an error, Narwhal's has therefore fallen back to using "
    "'ns' as a time unit.\n"
    "To avoid this warning, consider upgrading pandas or otherwise "
    "specifying 'ns' time units."
)

I think that makes things clearer, but let me know if you'd change any of the wording!

[dangotbanned]

Okay with #3098 merged things are looking good

I'll take another look at the error message tomorrow

The main thing standing out is

Narwhal's

Should be

Narwhals

But I'll chew on the rest a bit in the meantime 😄

[dangotbanned]

This is what I'd suggest, was a bit more involved than a GH suggestion could be 😅

(docs(suggestion): Tweaks to warning message)

Which comes out as:

UserWarning: `nw.Datetime(time_unit='us')` is only available in 'pandas>=2.0', found version '1.5'.
Narwhals has fallen back to using `time_unit='ns'` to avoid an error.

Hint: to avoid this warning, consider either:
- Upgrading pandas: https://pandas.pydata.org/docs/dev/whatsnew/v2.0.0.html#construction-with-datetime64-or-timedelta64-dtype-with-unsupported-resolution
- Using a bare `nw.Datetime`, if this precision is not important

[dangotbanned]

Thanks for bearing with me on this @benrutter!

[MarcoGorelli]

great feature, thanks all!