Contents

• Abstract
• Rationale
• Protocol
  • Subtraction of datetime
  • Addition
  • Subtraction of timedelta
  • Formatting
  • Parsing
• Changes to datetime methods
  • Subtraction
  • Addition
• Strict arithmetics
  • Parsing and formatting
• Applications
• Copyright

Abstract

This PEP specifies a new protocol (PDDM - “A Protocol for Delegating Datetime Methods”) that can be used by concrete implementations of the datetime.tzinfo interface to override aware datetime arithmetics, formatting and parsing. We describe changes to the datetime.datetime class to support the new protocol and propose a new abstract class datetime.tzstrict that implements parts of this protocol necessary to make aware datetime instances to follow “strict” arithmetic rules.

Rationale

As of Python 3.5, aware datetime instances that share a tzinfo object follow the rules of arithmetics that are induced by a simple bijection between (year, month, day, hour, minute, second, microsecond) 7-tuples and large integers. In this arithmetics, the difference between YEAR-11-02T12:00 and YEAR-11-01T12:00 is always 24 hours, even though in the US/Eastern timezone, for example, there are 25 hours between 2014-11-01T12:00 and 2014-11-02T12:00 because the local clocks were rolled back one hour at 2014-11-02T02:00, introducing an extra hour in the night between 2014-11-01 and 2014-11-02.

Many business applications require the use of Python’s simplified view of local dates. No self-respecting car rental company will charge its customers more for a week that straddles the end of DST than for any other week or require that they return the car an hour early. Therefore, changing the current rules for aware datetime arithmetics will not only create a backward compatibility nightmare, it will eliminate support for legitimate and common use cases.

Since it is impossible to choose universal rules for local time arithmetics, we propose to delegate implementation of those rules to the classes that implement datetime.tzinfo interface. With such delegation in place, users will be able to choose between different arithmetics by simply picking instances of different classes for the value of tzinfo.

Protocol

Changes to datetime methods

class datetime:
    def __sub__(self, other):
        if isinstance(other, datetime):
            try:
                self_diff = self.tzinfo.__datetime_diff__
            except AttributeError:
                self_diff = None
            try:
                other_diff = self.tzinfo.__datetime_diff__
            except AttributeError:
                other_diff = None
            if self_diff is not None:
                if self_diff is not other_diff and self_diff.__func__ is not other_diff.__func__:
                    raise ValueError("Cannot find difference of two datetimes with "
                                     "different tzinfo.__datetime_diff__ implementations.")
                return self_diff(self, other)
        elif isinstance(other, timedelta):
            try:
                sub = self.tzinfo.__datetime_sub__
            except AttributeError:
                pass
            else:
                return sub(self, other)
            return self + -other
        else:
            return NotImplemented
        # current implementation

Strict arithmetics

A new abstract subclass of datetime.tzinfo class called datetime.tzstrict will be added to the datetime module. This subclass will not implement the utcoffset(), tzname() or dst() methods, but will implement some of the methods of the PDDM.

The PDDM methods implemented by tzstrict will be equivalent to the following:

class tzstrict(tzinfo):
    def __datetime_diff__(self, dt1, dt2):
        utc_dt1 = dt1.astimezone(timezone.utc)
        utc_dt2 = dt2.astimezone(timezone.utc)
        return utc_dt2 - utc_dt1

    def __datetime_add__(self, dt, delta):
        utc_dt = dt.astimezone(timezone.utc)
        return (utc_dt + delta).astimezone(self)

    def __datetime_sub__(self, dt, delta):
        utc_dt = dt.astimezone(timezone.utc)
        return (utc_dt - delta).astimezone(self)

Applications

This PEP will enable third party implementation of many different timekeeping schemes including:

• Julian / Microsoft Excel calendar.
• “Right” timezones with the leap second support.
• French revolutionary calendar (with a lot of work).

Copyright

This document has been placed in the public domain.