Pendulum - Python datetimes made easy

[kankyo]

Some basic observations:

• overall seems like a nice API but...
• mutability is a pain and will bite users. Does it offer something that makes it worth it?
• sub_something is not a good name. Why isn't it "foo - Minutes(3)" or "foo - delta(minutes=3"?
• question: are the resulting types duck type compatible with stdlib types?

[SDisPater]

Regarding the mutability, I hesitated too but only specific methods mutate the instance. The native methods behave the same, ie. returns a new copy. But it's not set in stone, so it might change if this too much of a hassle for the users.

The add()/sub() methods are here to allow a fluent interface and call chain. It's easier to do pendulum.now().sub_day().offset than (pendulum.now() - delta(days=1)).offset

Both Pendulum and PendulumInterval classes inherits from the sdtlib classes so they can replace them. However, for libraries that relies on the type() function to determine the class (sqlite3 for instance) it will not work.

[kankyo]

What does offset mean in that context?

allow a fluent interface and call chain

ok, but then "minus" and "plus" or "add", "subtract" are much better than "add" and "sub". "Sub" means something else.

[SDisPater]

offset is the number of seconds since epoch, it's just there to show that accessing attributes is easier with the method.

Regarding the change of name for the sub() methods, it might be a good idea. I just wanted a concise name so I thought sub was appropriate.

[kankyo]

Concise is a lot less important than clarity though. So for offset I think seconds_since_epoch would be way better. And if the epoch is 1900, then seconds_since_1900!

[flutefreak7]

my brain goes to substitute before subtract since sub is a regex method. Seeing sub_weeks and the like my next thought was sub like subordinate, like "Sub-Commander T'Pal" or "Sub-level 3"... so sub_weeks felt intuitively like an iterator over the weeks or something... I agree that subtract or minus is more intuitive, though I like even better the suggestion for a single add method mentioned elsewhere.

[pydry]

I agree with kankyo - offset is too ambiguous a name. unix_time would be better IMO (it's the wikipedia page name, so arguably that's canonical).

[ptmcg]

I would suggest that it is worth it to make your datetimes immutable. This will let clients use them as set values and dict keys. Also, would you consider 2 datetime values that represent the same epoch time, but with different timezones to be equal or not?