CINXE.COM

<!DOCTYPE html> <html lang="en"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <meta name="color-scheme" content="light dark"> <title>PEP 500 – A protocol for delegating datetime methods to their tzinfo implementations | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0500/"> <link rel="stylesheet" href="../_static/style.css" type="text/css"> <link rel="stylesheet" href="../_static/mq.css" type="text/css"> <link rel="stylesheet" href="../_static/pygments.css" type="text/css" media="(prefers-color-scheme: light)" id="pyg-light"> <link rel="stylesheet" href="../_static/pygments_dark.css" type="text/css" media="(prefers-color-scheme: dark)" id="pyg-dark"> <link rel="alternate" type="application/rss+xml" title="Latest PEPs" href="https://peps.python.org/peps.rss"> <meta property="og:title" content='PEP 500 – A protocol for delegating datetime methods to their tzinfo implementations | peps.python.org'> <meta property="og:description" content="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..."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0500/"> <meta property="og:site_name" content="Python Enhancement Proposals (PEPs)"> <meta property="og:image" content="https://peps.python.org/_static/og-image.png"> <meta property="og:image:alt" content="Python PEPs"> <meta property="og:image:width" content="200"> <meta property="og:image:height" content="200"> <meta name="description" content="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..."> <meta name="theme-color" content="#3776ab"> </head> <body> <svg xmlns="http://www.w3.org/2000/svg" style="display: none;"> <symbol id="svg-sun-half" viewBox="0 0 24 24" pointer-events="all"> <title>Following system colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="9"></circle> <path d="M12 3v18m0-12l4.65-4.65M12 14.3l7.37-7.37M12 19.6l8.85-8.85"></path> </svg> </symbol> <symbol id="svg-moon" viewBox="0 0 24 24" pointer-events="all"> <title>Selected dark colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <path stroke="none" d="M0 0h24v24H0z" fill="none"></path> <path d="M12 3c.132 0 .263 0 .393 0a7.5 7.5 0 0 0 7.92 12.446a9 9 0 1 1 -8.313 -12.454z"></path> </svg> </symbol> <symbol id="svg-sun" viewBox="0 0 24 24" pointer-events="all"> <title>Selected light colour scheme</title> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"> <circle cx="12" cy="12" r="5"></circle> <line x1="12" y1="1" x2="12" y2="3"></line> <line x1="12" y1="21" x2="12" y2="23"></line> <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line> <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line> <line x1="1" y1="12" x2="3" y2="12"></line> <line x1="21" y1="12" x2="23" y2="12"></line> <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line> <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line> </svg> </symbol> </svg> <script> document.documentElement.dataset.colour_scheme = localStorage.getItem("colour_scheme") || "auto" </script> <section id="pep-page-section"> <header> <h1>Python Enhancement Proposals</h1> <ul class="breadcrumbs"> <li><a href="https://www.python.org/" title="The Python Programming Language">Python</a> » </li> <li><a href="../pep-0000/">PEP Index</a> » </li> <li>PEP 500</li> </ul> <button id="colour-scheme-cycler" onClick="setColourScheme(nextColourScheme())"> <svg aria-hidden="true" class="colour-scheme-icon-when-auto"><use href="#svg-sun-half"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-dark"><use href="#svg-moon"></use></svg> <svg aria-hidden="true" class="colour-scheme-icon-when-light"><use href="#svg-sun"></use></svg> Toggle light / dark / auto colour theme </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 500 – A protocol for delegating datetime methods to their tzinfo implementations</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author:</dt> <dd class="field-odd">Alexander Belopolsky <alexander.belopolsky at gmail.com>, Tim Peters <tim.peters at gmail.com></dd> <dt class="field-even">Discussions-To:</dt> <dd class="field-even"><a class="reference external" href="https://mail.python.org/archives/list/datetime-sig@python.org/">Datetime-SIG list</a></dd> <dt class="field-odd">Status:</dt> <dd class="field-odd"><abbr title="Formally declined and will not be accepted">Rejected</abbr></dd> <dt class="field-even">Type:</dt> <dd class="field-even"><abbr title="Normative PEP with a new feature for Python, implementation change for CPython or interoperability standard for the ecosystem">Standards Track</abbr></dd> <dt class="field-odd">Requires:</dt> <dd class="field-odd"><a class="reference external" href="../pep-0495/">495</a></dd> <dt class="field-even">Created:</dt> <dd class="field-even">08-Aug-2015</dd> <dt class="field-odd">Resolution:</dt> <dd class="field-odd"><a class="reference external" href="https://mail.python.org/pipermail/datetime-sig/2015-August/000354.html">Datetime-SIG message</a></dd> </dl> <hr class="docutils" /> <section id="contents"> <details><summary>Table of Contents</summary><ul class="simple"> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#protocol">Protocol</a><ul> <li><a class="reference internal" href="#subtraction-of-datetime">Subtraction of datetime</a></li> <li><a class="reference internal" href="#addition">Addition</a></li> <li><a class="reference internal" href="#subtraction-of-timedelta">Subtraction of timedelta</a></li> <li><a class="reference internal" href="#formatting">Formatting</a></li> <li><a class="reference internal" href="#parsing">Parsing</a></li> </ul> </li> <li><a class="reference internal" href="#changes-to-datetime-methods">Changes to datetime methods</a><ul> <li><a class="reference internal" href="#subtraction">Subtraction</a></li> <li><a class="reference internal" href="#id1">Addition</a></li> </ul> </li> <li><a class="reference internal" href="#strict-arithmetics">Strict arithmetics</a><ul> <li><a class="reference internal" href="#parsing-and-formatting">Parsing and formatting</a></li> </ul> </li> <li><a class="reference internal" href="#applications">Applications</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> </details></section> <section id="abstract"> <h2><a class="toc-backref" href="#abstract" role="doc-backlink">Abstract</a></h2> This PEP specifies a new protocol (PDDM - “A Protocol for Delegating Datetime Methods”) that can be used by concrete implementations of the <code class="docutils literal notranslate">datetime.tzinfo</code> interface to override aware datetime arithmetics, formatting and parsing. We describe changes to the <code class="docutils literal notranslate">datetime.datetime</code> class to support the new protocol and propose a new abstract class <code class="docutils literal notranslate">datetime.tzstrict</code> that implements parts of this protocol necessary to make aware datetime instances to follow “strict” arithmetic rules. </section> <section id="rationale"> <h2><a class="toc-backref" href="#rationale" role="doc-backlink">Rationale</a></h2> As of Python 3.5, aware datetime instances that share a <code class="docutils literal notranslate">tzinfo</code> 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 <code class="docutils literal notranslate">datetime.tzinfo</code> 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 <code class="docutils literal notranslate">tzinfo</code>. </section> <section id="protocol"> <h2><a class="toc-backref" href="#protocol" role="doc-backlink">Protocol</a></h2> <section id="subtraction-of-datetime"> <h3><a class="toc-backref" href="#subtraction-of-datetime" role="doc-backlink">Subtraction of datetime</a></h3> A <code class="docutils literal notranslate">tzinfo</code> subclass supporting the PDDM, may define a method called <code class="docutils literal notranslate">__datetime_diff__</code> that should take two <code class="docutils literal notranslate">datetime.datetime</code> instances and return a <code class="docutils literal notranslate">datetime.timedelta</code> instance representing the time elapsed from the time represented by the first datetime instance to another. </section> <section id="addition"> <h3><a class="toc-backref" href="#addition" role="doc-backlink">Addition</a></h3> A <code class="docutils literal notranslate">tzinfo</code> subclass supporting the PDDM, may define a method called <code class="docutils literal notranslate">__datetime_add__</code> that should take two arguments–a datetime and a timedelta instances–and return a datetime instance. </section> <section id="subtraction-of-timedelta"> <h3><a class="toc-backref" href="#subtraction-of-timedelta" role="doc-backlink">Subtraction of timedelta</a></h3> A <code class="docutils literal notranslate">tzinfo</code> subclass supporting the PDDM, may define a method called <code class="docutils literal notranslate">__datetime_sub__</code> that should take two arguments–a datetime and a timedelta instances–and return a datetime instance. </section> <section id="formatting"> <h3><a class="toc-backref" href="#formatting" role="doc-backlink">Formatting</a></h3> A <code class="docutils literal notranslate">tzinfo</code> subclass supporting the PDDM, may define methods called <code class="docutils literal notranslate">__datetime_isoformat__</code> and <code class="docutils literal notranslate">__datetime_strftime__</code>. The <code class="docutils literal notranslate">__datetime_isoformat__</code> method should take a datetime instance and an optional separator and produce a string representation of the given datetime instance. The <code class="docutils literal notranslate">__datetime_strftime__</code> method should take a datetime instance and a format string and produce a string representation of the given datetime instance formatted according to the given format. </section> <section id="parsing"> <h3><a class="toc-backref" href="#parsing" role="doc-backlink">Parsing</a></h3> A <code class="docutils literal notranslate">tzinfo</code> subclass supporting the PDDM, may define a class method called <code class="docutils literal notranslate">__datetime_strptime__</code> and register the “canonical” names of the timezones that it implements with a registry. TODO Describe a registry. </section> </section> <section id="changes-to-datetime-methods"> <h2><a class="toc-backref" href="#changes-to-datetime-methods" role="doc-backlink">Changes to datetime methods</a></h2> <section id="subtraction"> <h3><a class="toc-backref" href="#subtraction" role="doc-backlink">Subtraction</a></h3> <div class="highlight-default notranslate"><div class="highlight"><pre>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 </pre></div> </div> </section> <section id="id1"> <h3><a class="toc-backref" href="#id1" role="doc-backlink">Addition</a></h3> Addition of a timedelta to a datetime instance will be delegated to the <code class="docutils literal notranslate">self.tzinfo.__datetime_add__</code> method whenever it is defined. </section> </section> <section id="strict-arithmetics"> <h2><a class="toc-backref" href="#strict-arithmetics" role="doc-backlink">Strict arithmetics</a></h2> A new abstract subclass of <code class="docutils literal notranslate">datetime.tzinfo</code> class called <code class="docutils literal notranslate">datetime.tzstrict</code> will be added to the <code class="docutils literal notranslate">datetime</code> module. This subclass will not implement the <code class="docutils literal notranslate">utcoffset()</code>, <code class="docutils literal notranslate">tzname()</code> or <code class="docutils literal notranslate">dst()</code> methods, but will implement some of the methods of the PDDM. The PDDM methods implemented by <code class="docutils literal notranslate">tzstrict</code> will be equivalent to the following: <div class="highlight-default notranslate"><div class="highlight"><pre>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) </pre></div> </div> <section id="parsing-and-formatting"> <h3><a class="toc-backref" href="#parsing-and-formatting" role="doc-backlink">Parsing and formatting</a></h3> Datetime methods <code class="docutils literal notranslate">strftime</code> and <code class="docutils literal notranslate">isoformat</code> will delegate to the namesake methods of their <code class="docutils literal notranslate">tzinfo</code> members whenever those methods are defined. When the <code class="docutils literal notranslate">datetime.strptime</code> method is given a format string that contains a <code class="docutils literal notranslate">%Z</code> instruction, it will lookup the <code class="docutils literal notranslate">tzinfo</code> implementation in the registry by the given timezone name and call its <code class="docutils literal notranslate">__datetime_strptime__</code> method. </section> </section> <section id="applications"> <h2><a class="toc-backref" href="#applications" role="doc-backlink">Applications</a></h2> This PEP will enable third party implementation of many different timekeeping schemes including: <ul class="simple"> <li>Julian / Microsoft Excel calendar.</li> <li>“Right” timezones with the leap second support.</li> <li>French revolutionary calendar (with a lot of work).</li> </ul> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> This document has been placed in the public domain. </section> </section> <hr class="docutils" /> Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0500.rst">https://github.com/python/peps/blob/main/peps/pep-0500.rst</a> Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0500.rst">2025-02-01 08:59:27 GMT</a> </article> <nav id="pep-sidebar"> <h2>Contents</h2> <ul> <li><a class="reference internal" href="#abstract">Abstract</a></li> <li><a class="reference internal" href="#rationale">Rationale</a></li> <li><a class="reference internal" href="#protocol">Protocol</a><ul> <li><a class="reference internal" href="#subtraction-of-datetime">Subtraction of datetime</a></li> <li><a class="reference internal" href="#addition">Addition</a></li> <li><a class="reference internal" href="#subtraction-of-timedelta">Subtraction of timedelta</a></li> <li><a class="reference internal" href="#formatting">Formatting</a></li> <li><a class="reference internal" href="#parsing">Parsing</a></li> </ul> </li> <li><a class="reference internal" href="#changes-to-datetime-methods">Changes to datetime methods</a><ul> <li><a class="reference internal" href="#subtraction">Subtraction</a></li> <li><a class="reference internal" href="#id1">Addition</a></li> </ul> </li> <li><a class="reference internal" href="#strict-arithmetics">Strict arithmetics</a><ul> <li><a class="reference internal" href="#parsing-and-formatting">Parsing and formatting</a></li> </ul> </li> <li><a class="reference internal" href="#applications">Applications</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0500.rst">Page Source (GitHub)</a> </nav> </section> <script src="../_static/colour_scheme.js"></script> <script src="../_static/wrap_tables.js"></script> <script src="../_static/sticky_banner.js"></script> </body> </html>