Python timedelta seconds vs total_seconds

You can construct a timedelta from days, seconds, microseconds, milliseconds, minutes, hours and weeks. Please note the order of these parameters, which is absolutely not useful and probably caused historically.

Internally, the timedelta structure is only made up of days, seconds and microseconds. And these are the properties you can access once the timedelta has been built. Even if you used hours, minutes etc. to construct the object, that information is gone.

import datetime

t = datetime.timedelta(hours=2, minutes=30)
print(t.seconds)

If seconds become larger than 86400 (24*60*60), they will overflow into one day:

import datetime

t = datetime.timedelta(hours=24, minutes=1)
print(t.seconds)
print(t.days)

And thus, timespan.seconds is quite a useless property, because it's only a part of the truth and meaningless without the other two components. The same applies for timespan.days and timespan.microseconds. They should really have been made internal and thus adhere to the principle of information hiding.

total_seconds() on the other hand side, is a valid representation of the timespan. It considers all 3 properties combined into a single number.

seconds is the number of seconds within a day, which is in [0, 86399]. total_seconds is the entire timedelta converted to seconds, and can be any value, for example 604800.0 for one week, or 0.1 for 100 milliseconds.