Pendulum interval seems incompatible with Python native datetime

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):

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

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)

@ashb

When I looked at it in more detail I realized that inconsistency in the in_words() function exists in only version 3.1. When I tested it again in development version (3.2.0.dev0), I saw that both Native DateTime and Pendulum DateTime gave correct and same results, but I couldn't figure out after which commit this issue was resolved.

@ashb @ayorgo To sum up, could you try again in 3.2.0.dev0? I think this bug has already been fixed in the development version.

fix: precise_diff inconsistent with pendulum.DateTime subclasses

Navigation Menu

Repository navigation

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

Issue

Set up

Unexpected behaviour

Expected behaviour

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Pendulum interval seems incompatible with Python native datetime #906

Description

Issue

Set up

Unexpected behaviour

Expected behaviour

Activity

ashb commented on Aug 2, 2025

Eren-Acar commented on Oct 24, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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