Pendulum `interval` seems incompatible with Python native `datetime`

[ayorgo]

• I am on the latest Pendulum version.
• I have searched the issues of this repo and believe that this is not a duplicate.

• OS version and name: macOS 15.5 (24F74)
• Python version: 3.12.10
• Pendulum version: 3.1.0

Issue

I'm new to pendulum and am sorry if this issue is a duplicate.

Set up

The documentation advertises compatibility with native Python datetime.datetime:

>>> from datetime import datetime
>>> import pendulum
>>> dt = pendulum.datetime(2015, 2, 5)
>>> isinstance(dt, datetime)
True

So I thought I could do this:

start_time = datetime(2025, 7, 25, 19, 26, 34)
end_time = datetime(2025, 7, 29, 19, 26, 34)

interval = pendulum.interval(start_time, end_time)

Unexpected behaviour

It turns out I can't:

>>> interval.in_words()
'3 days 4 hours 33 minutes'
>>> interval.days
4
>>> interval.hours
4
>>> interval.minutes
33
>>> interval.in_days()
4
>>> interval.in_hours() / 24
4.0

I now understand that I should've started with:

start_time = pendulum.datetime(2025, 7, 25, 19, 26, 34)
end_time = pendulum.datetime(2025, 7, 29, 19, 26, 34)

or

start_time = pendulum.instance(start_time)
end_time = pendulum.instance(end_time)

But still, the above behaviour is extremely confusing, unless I'm missing something of course.

Expected behaviour

I personally would expect pendulum to either (in the order of preference):

1. Treat Python's native datetime.datetime the same way as pendulum.datetime.
2. Fail at interval() instantiation with a TypeError or ValueError.
3. Document clearly that native datetime.datetime is not fully supported.

[ashb]

This appears to be some bug specifically with the in_words() function -- all the rest of the things such as total_seconds work correctly and report 345600.0 ( == 86400 * 4 = 24 * 60 * 60 * 4)