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 431 – Time zone support improvements | peps.python.org</title> <link rel="shortcut icon" href="../_static/py.png"> <link rel="canonical" href="https://peps.python.org/pep-0431/"> <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 431 – Time zone support improvements | peps.python.org'> <meta property="og:description" content="This PEP proposes the implementation of concrete time zone support in the Python standard library, and also improvements to the time zone API to deal with ambiguous time specifications during DST changes."> <meta property="og:type" content="website"> <meta property="og:url" content="https://peps.python.org/pep-0431/"> <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 proposes the implementation of concrete time zone support in the Python standard library, and also improvements to the time zone API to deal with ambiguous time specifications during DST changes."> <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 431</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> <span class="visually-hidden">Toggle light / dark / auto colour theme</span> </button> </header> <article> <section id="pep-content"> <h1 class="page-title">PEP 431 – Time zone support improvements</h1> <dl class="rfc2822 field-list simple"> <dt class="field-odd">Author<span class="colon">:</span></dt> <dd class="field-odd">Lennart Regebro <regebro at gmail.com></dd> <dt class="field-even">BDFL-Delegate<span class="colon">:</span></dt> <dd class="field-even">Barry Warsaw <barry at python.org></dd> <dt class="field-odd">Status<span class="colon">:</span></dt> <dd class="field-odd"><abbr title="Replaced by another succeeding PEP">Superseded</abbr></dd> <dt class="field-even">Type<span class="colon">:</span></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">Created<span class="colon">:</span></dt> <dd class="field-odd">11-Dec-2012</dd> <dt class="field-even">Post-History<span class="colon">:</span></dt> <dd class="field-even">11-Dec-2012, 28-Dec-2012, 28-Jan-2013</dd> <dt class="field-odd">Superseded-By<span class="colon">:</span></dt> <dd class="field-odd"><a class="reference external" href="../pep-0615/">615</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="#withdrawal">Withdrawal</a></li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#concrete-time-zone-support">Concrete time zone support</a></li> <li><a class="reference internal" href="#getting-the-local-time-zone">Getting the local time zone</a></li> <li><a class="reference internal" href="#ambiguous-times">Ambiguous times</a></li> </ul> </li> <li><a class="reference internal" href="#implementation-api">Implementation API</a><ul> <li><a class="reference internal" href="#the-zoneinfo-database">The zoneinfo database</a></li> <li><a class="reference internal" href="#changes-in-the-datetime-module">Changes in the <code class="docutils literal notranslate"><span class="pre">datetime</span></code>-module</a><ul> <li><a class="reference internal" href="#new-class-dsttimezone">New class <code class="docutils literal notranslate"><span class="pre">dsttimezone</span></code></a></li> <li><a class="reference internal" href="#new-function-zoneinfo-name-none-db-path-none">New function <code class="docutils literal notranslate"><span class="pre">zoneinfo(name=None,</span> <span class="pre">db_path=None)</span></code></a></li> <li><a class="reference internal" href="#new-parameter-is-dst">New parameter <code class="docutils literal notranslate"><span class="pre">is_dst</span></code></a></li> <li><a class="reference internal" href="#new-exceptions">New exceptions</a></li> <li><a class="reference internal" href="#new-collections">New collections</a></li> </ul> </li> <li><a class="reference internal" href="#the-tzdata-update-package">The <code class="docutils literal notranslate"><span class="pre">tzdata-update</span></code>-package</a></li> </ul> </li> <li><a class="reference internal" href="#differences-from-the-pytz-api">Differences from the <code class="docutils literal notranslate"><span class="pre">pytz</span></code> API</a></li> <li><a class="reference internal" href="#resources">Resources</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> <p>This PEP proposes the implementation of concrete time zone support in the Python standard library, and also improvements to the time zone API to deal with ambiguous time specifications during DST changes.</p> </section> <section id="withdrawal"> <h2><a class="toc-backref" href="#withdrawal" role="doc-backlink">Withdrawal</a></h2> <p>After lengthy discussion it has turned out that the things I thought was problem in datetime’s implementation are intentional. Those include completely ignoring DST transitions when making date time arithmetic. That makes the is_dst flags part of this PEP pointless, as they would have no useful function. <code class="docutils literal notranslate"><span class="pre">datetime</span></code> by design does not separate between ambiguous datetimes and will never do so.</p> <p>I therefore withdraw this PEP.</p> <p><strong>UPDATE</strong>: The <a class="pep reference internal" href="../pep-0615/" title="PEP 615 – Support for the IANA Time Zone Database in the Standard Library">PEP 615</a> “Support for the IANA Time Zone Database in the Standard Library” added the <code class="docutils literal notranslate"><span class="pre">zoneinfo</span></code> module to Python 3.9 and superseded this PEP.</p> </section> <section id="proposal"> <h2><a class="toc-backref" href="#proposal" role="doc-backlink">Proposal</a></h2> <section id="concrete-time-zone-support"> <h3><a class="toc-backref" href="#concrete-time-zone-support" role="doc-backlink">Concrete time zone support</a></h3> <p>The time zone support in Python has no concrete implementation in the standard library outside of a tzinfo baseclass that supports fixed offsets. To properly support time zones you need to include a database over all time zones, both current and historical, including daylight saving changes. But such information changes frequently, so even if we include the last information in a Python release, that information would be outdated just a few months later.</p> <p>Time zone support has therefore only been available through two third-party modules, <code class="docutils literal notranslate"><span class="pre">pytz</span></code> and <code class="docutils literal notranslate"><span class="pre">dateutil</span></code>, both who include and wrap the “zoneinfo” database. This database, also called “tz” or “The Olsen database”, is the de facto standard time zone database over time zones, and it is included in most Unix and Unix-like operating systems, including OS X.</p> <p>This gives us the opportunity to include the code that supports the zoneinfo data in the standard library, but by default use the operating system’s copy of the data, which typically will be kept updated by the updating mechanism of the operating system or distribution.</p> <p>For those who have an operating system that does not include the zoneinfo database, for example Windows, the Python source distribution will include a copy of the zoneinfo database, and a distribution containing the latest zoneinfo database will also be available at the Python Package Index, so it can be easily installed with the Python packaging tools such as <code class="docutils literal notranslate"><span class="pre">easy_install</span></code> or <code class="docutils literal notranslate"><span class="pre">pip</span></code>. This could also be done on Unices that are no longer receiving updates and therefore have an outdated database.</p> <p>With such a mechanism Python would have full-time zone support in the standard library on any platform, and a simple package installation would provide an updated time zone database on those platforms where the zoneinfo database isn’t included, such as Windows, or on platforms where OS updates are no longer provided.</p> <p>The time zone support will be implemented by making the <code class="docutils literal notranslate"><span class="pre">datetime</span></code> module into a package, and adding time zone support to <code class="docutils literal notranslate"><span class="pre">datetime</span></code> based on Stuart Bishop’s <code class="docutils literal notranslate"><span class="pre">pytz</span></code> module.</p> </section> <section id="getting-the-local-time-zone"> <h3><a class="toc-backref" href="#getting-the-local-time-zone" role="doc-backlink">Getting the local time zone</a></h3> <p>On Unix there is no standard way of finding the name of the time zone that is being used. All the information that is available is the time zone abbreviations, such as <code class="docutils literal notranslate"><span class="pre">EST</span></code> and <code class="docutils literal notranslate"><span class="pre">PDT</span></code>, but many of those abbreviations are ambiguous and therefore you can’t rely on them to figure out which time zone you are located in.</p> <p>There is however a standard for finding the compiled time zone information since it’s located in <code class="docutils literal notranslate"><span class="pre">/etc/localtime</span></code>. Therefore, it is possible to create a local time zone object with the correct time zone information even though you don’t know the name of the time zone. A function in <code class="docutils literal notranslate"><span class="pre">datetime</span></code> should be provided to return the local time zone.</p> <p>The support for this will be made by integrating Lennart Regebro’s <code class="docutils literal notranslate"><span class="pre">tzlocal</span></code> module into the new <code class="docutils literal notranslate"><span class="pre">datetime</span></code> module.</p> <p>For Windows it will look up the local Windows time zone name, and use a mapping between Windows time zone names and zoneinfo time zone names provided by the Unicode consortium to convert that to a zoneinfo time zone.</p> <p>The mapping should be updated before each major or bugfix release, scripts for doing so will be provided in the <code class="docutils literal notranslate"><span class="pre">Tools/</span></code> directory.</p> </section> <section id="ambiguous-times"> <h3><a class="toc-backref" href="#ambiguous-times" role="doc-backlink">Ambiguous times</a></h3> <p>When changing over from daylight savings time (DST) the clock is turned back one hour. This means that the times during that hour happens twice, once with DST and then once without DST. Similarly, when changing to daylight savings time, one hour goes missing.</p> <p>The current time zone API can not differentiate between the two ambiguous times during a change from DST. For example, in Stockholm the time of 2012-11-28 02:00:00 happens twice, both at UTC 2012-11-28 00:00:00 and also at 2012-11-28 01:00:00.</p> <p>The current time zone API can not disambiguate this and therefore it’s unclear which time should be returned:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># This could be either 00:00 or 01:00 UTC:</span> <span class="o">>>></span> <span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2012</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">28</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">zoneinfo</span><span class="p">(</span><span class="s1">'Europe/Stockholm'</span><span class="p">))</span> <span class="c1"># But we can not specify which:</span> <span class="o">>>></span> <span class="n">dt</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">zoneinfo</span><span class="p">(</span><span class="s1">'UTC'</span><span class="p">))</span> <span class="n">datetime</span><span class="o">.</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2012</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">28</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=<</span><span class="n">UTC</span><span class="o">></span><span class="p">)</span> </pre></div> </div> <p><code class="docutils literal notranslate"><span class="pre">pytz</span></code> solved this problem by adding <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> parameters to several methods of the tzinfo objects to make it possible to disambiguate times when this is desired.</p> <p>This PEP proposes to add these <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> parameters to the relevant methods of the <code class="docutils literal notranslate"><span class="pre">datetime</span></code> API, and therefore add this functionality directly to <code class="docutils literal notranslate"><span class="pre">datetime</span></code>. This is likely the hardest part of this PEP as this involves updating the C version of the <code class="docutils literal notranslate"><span class="pre">datetime</span></code> library with this functionality, as this involved writing new code, and not just reorganizing existing external libraries.</p> </section> </section> <section id="implementation-api"> <h2><a class="toc-backref" href="#implementation-api" role="doc-backlink">Implementation API</a></h2> <section id="the-zoneinfo-database"> <h3><a class="toc-backref" href="#the-zoneinfo-database" role="doc-backlink">The zoneinfo database</a></h3> <p>The latest version of the zoneinfo database should exist in the <code class="docutils literal notranslate"><span class="pre">Lib/tzdata</span></code> directory of the Python source control system. This copy of the database should be updated before every Python feature and bug-fix release, but not for releases of Python versions that are in security-fix-only-mode.</p> <p>Scripts to update the database will be provided in <code class="docutils literal notranslate"><span class="pre">Tools/</span></code>, and the release instructions will be updated to include this update.</p> <p>New configure options <code class="docutils literal notranslate"><span class="pre">--enable-internal-timezone-database</span></code> and <code class="docutils literal notranslate"><span class="pre">--disable-internal-timezone-database</span></code> will be implemented to enable and disable the installation of this database when installing from source. A source install will default to installing them.</p> <p>Binary installers for systems that have a system-provided zoneinfo database may skip installing the included database since it would never be used for these platforms. For other platforms, for example Windows, binary installers must install the included database.</p> </section> <section id="changes-in-the-datetime-module"> <h3><a class="toc-backref" href="#changes-in-the-datetime-module" role="doc-backlink">Changes in the <code class="docutils literal notranslate"><span class="pre">datetime</span></code>-module</a></h3> <p>The public API of the new time zone support contains one new class, one new function, one new exception and four new collections. In addition to this, several methods on the datetime object gets a new <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> parameter.</p> <section id="new-class-dsttimezone"> <h4><a class="toc-backref" href="#new-class-dsttimezone" role="doc-backlink">New class <code class="docutils literal notranslate"><span class="pre">dsttimezone</span></code></a></h4> <p>This class provides a concrete implementation of the <code class="docutils literal notranslate"><span class="pre">tzinfo</span></code> base class that implements DST support.</p> </section> <section id="new-function-zoneinfo-name-none-db-path-none"> <h4><a class="toc-backref" href="#new-function-zoneinfo-name-none-db-path-none" role="doc-backlink">New function <code class="docutils literal notranslate"><span class="pre">zoneinfo(name=None,</span> <span class="pre">db_path=None)</span></code></a></h4> <p>This function takes a name string that must be a string specifying a valid zoneinfo time zone, i.e. “US/Eastern”, “Europe/Warsaw” or “Etc/GMT”. If not given, the local time zone will be looked up. If an invalid zone name is given, or the local time zone can not be retrieved, the function raises <code class="docutils literal notranslate"><span class="pre">UnknownTimeZoneError</span></code>.</p> <p>The function also takes an optional path to the location of the zoneinfo database which should be used. If not specified, the function will look for databases in the following order:</p> <ol class="arabic simple"> <li>Check if the <code class="docutils literal notranslate"><span class="pre">tzdata-update</span></code> module is installed, and then use that database.</li> <li>Use the database in <code class="docutils literal notranslate"><span class="pre">/usr/share/zoneinfo</span></code>, if it exists.</li> <li>Use the Python-provided database in <code class="docutils literal notranslate"><span class="pre">Lib/tzdata</span></code>.</li> </ol> <p>If no database is found an <code class="docutils literal notranslate"><span class="pre">UnknownTimeZoneError</span></code> or subclass thereof will be raised with a message explaining that no zoneinfo database can be found, but that you can install one with the <code class="docutils literal notranslate"><span class="pre">tzdata-update</span></code> package.</p> </section> <section id="new-parameter-is-dst"> <h4><a class="toc-backref" href="#new-parameter-is-dst" role="doc-backlink">New parameter <code class="docutils literal notranslate"><span class="pre">is_dst</span></code></a></h4> <p>A new <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> parameter is added to several methods to handle time ambiguity during DST changeovers.</p> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">tzinfo.utcoffset(dt,</span> <span class="pre">is_dst=False)</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">tzinfo.dst(dt,</span> <span class="pre">is_dst=False)</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">tzinfo.tzname(dt,</span> <span class="pre">is_dst=False)</span></code></li> <li><code class="docutils literal notranslate"><span class="pre">datetime.astimezone(tz,</span> <span class="pre">is_dst=False)</span></code></li> </ul> <p>The <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> parameter can be <code class="docutils literal notranslate"><span class="pre">False</span></code> (default), <code class="docutils literal notranslate"><span class="pre">True</span></code>, or <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p> <p><code class="docutils literal notranslate"><span class="pre">False</span></code> will specify that the given datetime should be interpreted as not happening during daylight savings time, i.e. that the time specified is after the change from DST. This is default to preserve existing behavior.</p> <p><code class="docutils literal notranslate"><span class="pre">True</span></code> will specify that the given datetime should be interpreted as happening during daylight savings time, i.e. that the time specified is before the change from DST.</p> <p><code class="docutils literal notranslate"><span class="pre">None</span></code> will raise an <code class="docutils literal notranslate"><span class="pre">AmbiguousTimeError</span></code> exception if the time specified was during a DST change over. It will also raise a <code class="docutils literal notranslate"><span class="pre">NonExistentTimeError</span></code> if a time is specified during the “missing time” in a change to DST.</p> </section> <section id="new-exceptions"> <h4><a class="toc-backref" href="#new-exceptions" role="doc-backlink">New exceptions</a></h4> <ul> <li><code class="docutils literal notranslate"><span class="pre">UnknownTimeZoneError</span></code><p>This exception is a subclass of KeyError and raised when giving a time zone specification that can’t be found:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">datetime</span><span class="o">.</span><span class="n">zoneinfo</span><span class="p">(</span><span class="s1">'Europe/New_York'</span><span class="p">)</span> <span class="gt">Traceback (most recent call last):</span> <span class="c">...</span> <span class="gr">UnknownTimeZoneError</span>: <span class="n">There is no time zone called 'Europe/New_York'</span> </pre></div> </div> </li> <li><code class="docutils literal notranslate"><span class="pre">InvalidTimeError</span></code><p>This exception serves as a base for <code class="docutils literal notranslate"><span class="pre">AmbiguousTimeError</span></code> and <code class="docutils literal notranslate"><span class="pre">NonExistentTimeError</span></code>, to enable you to trap these two separately. It will subclass from ValueError, so that you can catch these errors together with inputs like the 29th of February 2011.</p> </li> <li><code class="docutils literal notranslate"><span class="pre">AmbiguousTimeError</span></code><p>This exception is raised when giving a datetime specification that is ambiguous while setting <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> to None:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">datetime</span><span class="p">(</span><span class="mi">2012</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">28</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">zoneinfo</span><span class="p">(</span><span class="s1">'Europe/Stockholm'</span><span class="p">),</span> <span class="n">is_dst</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span> <span class="gp">>>></span> <span class="gt">Traceback (most recent call last):</span> <span class="c">...</span> <span class="gr">AmbiguousTimeError</span>: <span class="n">2012-10-28 02:00:00 is ambiguous in time zone Europe/Stockholm</span> </pre></div> </div> </li> <li><code class="docutils literal notranslate"><span class="pre">NonExistentTimeError</span></code><p>This exception is raised when giving a datetime specification for a time that due to daylight saving does not exist, while setting <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> to None:</p> <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">datetime</span><span class="p">(</span><span class="mi">2012</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">25</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">zoneinfo</span><span class="p">(</span><span class="s1">'Europe/Stockholm'</span><span class="p">),</span> <span class="n">is_dst</span><span class="o">=</span><span class="kc">None</span><span class="p">)</span> <span class="gp">>>></span> <span class="gt">Traceback (most recent call last):</span> <span class="c">...</span> <span class="gr">NonExistentTimeError</span>: <span class="n">2012-03-25 02:00:00 does not exist in time zone Europe/Stockholm</span> </pre></div> </div> </li> </ul> </section> <section id="new-collections"> <h4><a class="toc-backref" href="#new-collections" role="doc-backlink">New collections</a></h4> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">all_timezones</span></code> is the exhaustive list of the time zone names that can be used, listed alphabetically.</li> <li><code class="docutils literal notranslate"><span class="pre">common_timezones</span></code> is a list of useful, current time zones, listed alphabetically.</li> </ul> </section> </section> <section id="the-tzdata-update-package"> <h3><a class="toc-backref" href="#the-tzdata-update-package" role="doc-backlink">The <code class="docutils literal notranslate"><span class="pre">tzdata-update</span></code>-package</a></h3> <p>The zoneinfo database will be packaged for easy installation with <code class="docutils literal notranslate"><span class="pre">easy_install</span></code>/<code class="docutils literal notranslate"><span class="pre">pip</span></code>/<code class="docutils literal notranslate"><span class="pre">buildout</span></code>. This package will not install any Python code, and will not contain any Python code except that which is needed for installation.</p> <p>It will be kept updated with the same tools as the internal database, but released whenever the <code class="docutils literal notranslate"><span class="pre">zoneinfo</span></code>-database is updated, and use the same version schema.</p> </section> </section> <section id="differences-from-the-pytz-api"> <h2><a class="toc-backref" href="#differences-from-the-pytz-api" role="doc-backlink">Differences from the <code class="docutils literal notranslate"><span class="pre">pytz</span></code> API</a></h2> <ul class="simple"> <li><code class="docutils literal notranslate"><span class="pre">pytz</span></code> has the functions <code class="docutils literal notranslate"><span class="pre">localize()</span></code> and <code class="docutils literal notranslate"><span class="pre">normalize()</span></code> to work around that <code class="docutils literal notranslate"><span class="pre">tzinfo</span></code> doesn’t have is_dst. When <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> is implemented directly in <code class="docutils literal notranslate"><span class="pre">datetime.tzinfo</span></code> they are no longer needed.</li> <li>The <code class="docutils literal notranslate"><span class="pre">timezone()</span></code> function is called <code class="docutils literal notranslate"><span class="pre">zoneinfo()</span></code> to avoid clashing with the <code class="docutils literal notranslate"><span class="pre">timezone</span></code> class introduced in Python 3.2.</li> <li><code class="docutils literal notranslate"><span class="pre">zoneinfo()</span></code> will return the local time zone if called without arguments.</li> <li>The class <code class="docutils literal notranslate"><span class="pre">pytz.StaticTzInfo</span></code> is there to provide the <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> support for static time zones. When <code class="docutils literal notranslate"><span class="pre">is_dst</span></code> support is included in <code class="docutils literal notranslate"><span class="pre">datetime.tzinfo</span></code> it is no longer needed.</li> <li><code class="docutils literal notranslate"><span class="pre">InvalidTimeError</span></code> subclasses from <code class="docutils literal notranslate"><span class="pre">ValueError</span></code>.</li> </ul> </section> <section id="resources"> <h2><a class="toc-backref" href="#resources" role="doc-backlink">Resources</a></h2> <ul class="simple"> <li><a class="reference external" href="http://pytz.sourceforge.net/">http://pytz.sourceforge.net/</a></li> <li><a class="reference external" href="http://pypi.python.org/pypi/tzlocal">http://pypi.python.org/pypi/tzlocal</a></li> <li><a class="reference external" href="http://pypi.python.org/pypi/python-dateutil">http://pypi.python.org/pypi/python-dateutil</a></li> <li><a class="reference external" href="http://unicode.org/cldr/data/common/supplemental/windowsZones.xml">http://unicode.org/cldr/data/common/supplemental/windowsZones.xml</a></li> </ul> </section> <section id="copyright"> <h2><a class="toc-backref" href="#copyright" role="doc-backlink">Copyright</a></h2> <p>This document has been placed in the public domain.</p> </section> </section> <hr class="docutils" /> <p>Source: <a class="reference external" href="https://github.com/python/peps/blob/main/peps/pep-0431.rst">https://github.com/python/peps/blob/main/peps/pep-0431.rst</a></p> <p>Last modified: <a class="reference external" href="https://github.com/python/peps/commits/main/peps/pep-0431.rst">2025-02-01 08:59:27 GMT</a></p> </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="#withdrawal">Withdrawal</a></li> <li><a class="reference internal" href="#proposal">Proposal</a><ul> <li><a class="reference internal" href="#concrete-time-zone-support">Concrete time zone support</a></li> <li><a class="reference internal" href="#getting-the-local-time-zone">Getting the local time zone</a></li> <li><a class="reference internal" href="#ambiguous-times">Ambiguous times</a></li> </ul> </li> <li><a class="reference internal" href="#implementation-api">Implementation API</a><ul> <li><a class="reference internal" href="#the-zoneinfo-database">The zoneinfo database</a></li> <li><a class="reference internal" href="#changes-in-the-datetime-module">Changes in the <code class="docutils literal notranslate"><span class="pre">datetime</span></code>-module</a><ul> <li><a class="reference internal" href="#new-class-dsttimezone">New class <code class="docutils literal notranslate"><span class="pre">dsttimezone</span></code></a></li> <li><a class="reference internal" href="#new-function-zoneinfo-name-none-db-path-none">New function <code class="docutils literal notranslate"><span class="pre">zoneinfo(name=None,</span> <span class="pre">db_path=None)</span></code></a></li> <li><a class="reference internal" href="#new-parameter-is-dst">New parameter <code class="docutils literal notranslate"><span class="pre">is_dst</span></code></a></li> <li><a class="reference internal" href="#new-exceptions">New exceptions</a></li> <li><a class="reference internal" href="#new-collections">New collections</a></li> </ul> </li> <li><a class="reference internal" href="#the-tzdata-update-package">The <code class="docutils literal notranslate"><span class="pre">tzdata-update</span></code>-package</a></li> </ul> </li> <li><a class="reference internal" href="#differences-from-the-pytz-api">Differences from the <code class="docutils literal notranslate"><span class="pre">pytz</span></code> API</a></li> <li><a class="reference internal" href="#resources">Resources</a></li> <li><a class="reference internal" href="#copyright">Copyright</a></li> </ul> <br> <a id="source" href="https://github.com/python/peps/blob/main/peps/pep-0431.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>