parthtamu/rag-code-assistant
0
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4 <head>5 <meta charset="utf-8" />6 <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="zoneinfo — IANA time zone support" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/zoneinfo.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="Source code: Lib/zoneinfo The zoneinfo module provides a concrete time zone implementation to support the IANA time zone database as originally specified in PEP 615. By default, zoneinfo uses the s..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_zoneinfo_c1e1e424.png" />15<meta property="og:image:alt" content="Source code: Lib/zoneinfo The zoneinfo module provides a concrete time zone implementation to support the IANA time zone database as originally specified in PEP 615. By default, zoneinfo uses the s..." />16<meta name="description" content="Source code: Lib/zoneinfo The zoneinfo module provides a concrete time zone implementation to support the IANA time zone database as originally specified in PEP 615. By default, zoneinfo uses the s..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20 <title>zoneinfo — IANA time zone support — Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21 22 <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23 <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24 <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25 <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26 <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27 28 <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29 <script src="../_static/doctools.js?v=9bcbadda"></script>30 <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31 <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32 33 <script src="../_static/sidebar.js"></script>34 35 <link rel="search" type="application/opensearchdescription+xml"36 title="Search within Python 3.15.0a6 documentation"37 href="../_static/opensearch.xml"/>38 <link rel="author" title="About these documents" href="../about.html" />39 <link rel="index" title="Index" href="../genindex.html" />40 <link rel="search" title="Search" href="../search.html" />41 <link rel="copyright" title="Copyright" href="../copyright.html" />42 <link rel="next" title="calendar — General calendar-related functions" href="calendar.html" />43 <link rel="prev" title="datetime — Basic date and time types" href="datetime.html" />44 45 46 <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47 48 <link rel="canonical" href="https://docs.python.org/3/library/zoneinfo.html">49 50 51 52 53 <style>54 @media only screen {55 table.full-width-table {56 width: 100%;57 }58 }59 </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61 <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62 <script type="text/javascript" src="../_static/copybutton.js"></script>63 <script type="text/javascript" src="../_static/menu.js"></script>64 <script type="text/javascript" src="../_static/search-focus.js"></script>65 <script type="text/javascript" src="../_static/themetoggle.js"></script> 66 <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67 <meta name="readthedocs-addons-api-version" content="1">68 69 </head>70<body>71<div class="mobile-nav">72 <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73 aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74 <nav class="nav-content" role="navigation">75 <label for="menuToggler" class="toggler__label">76 <span></span>77 </label>78 <span class="nav-items-wrapper">79 <a href="https://www.python.org/" class="nav-logo">80 <img src="../_static/py.svg" alt="Python logo">81 </a>82 <span class="version_switcher_placeholder"></span>83 <form role="search" class="search" action="../search.html" method="get">84 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85 <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86 </svg>87 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88 <input type="submit" value="Go">89 </form>90 </span>91 </nav>92 <div class="menu-wrapper">93 <nav class="menu" role="navigation" aria-label="main navigation">94 <div class="language_switcher_placeholder"></div>95 96<label class="theme-selector-label">97 Theme98 <select class="theme-selector" oninput="activateTheme(this.value)">99 <option value="auto" selected>Auto</option>100 <option value="light">Light</option>101 <option value="dark">Dark</option>102 </select>103</label>104 <div>105 <h3><a href="../contents.html">Table of Contents</a></h3>106 <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> — IANA time zone support</a><ul>108<li><a class="reference internal" href="#using-zoneinfo">Using <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a></li>109<li><a class="reference internal" href="#data-sources">Data sources</a><ul>110<li><a class="reference internal" href="#configuring-the-data-sources">Configuring the data sources</a><ul>111<li><a class="reference internal" href="#compile-time-configuration">Compile-time configuration</a></li>112<li><a class="reference internal" href="#environment-configuration">Environment configuration</a></li>113<li><a class="reference internal" href="#runtime-configuration">Runtime configuration</a></li>114</ul>115</li>116</ul>117</li>118<li><a class="reference internal" href="#the-zoneinfo-class">The <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class</a><ul>119<li><a class="reference internal" href="#string-representations">String representations</a></li>120<li><a class="reference internal" href="#pickle-serialization">Pickle serialization</a></li>121</ul>122</li>123<li><a class="reference internal" href="#functions">Functions</a></li>124<li><a class="reference internal" href="#globals">Globals</a></li>125<li><a class="reference internal" href="#exceptions-and-warnings">Exceptions and warnings</a></li>126</ul>127</li>128</ul>129 130 </div>131 <div>132 <h4>Previous topic</h4>133 <p class="topless"><a href="datetime.html"134 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> — Basic date and time types</a></p>135 </div>136 <div>137 <h4>Next topic</h4>138 <p class="topless"><a href="calendar.html"139 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">calendar</span></code> — General calendar-related functions</a></p>140 </div>141 <script>142 document.addEventListener('DOMContentLoaded', () => {143 const title = document.querySelector('meta[property="og:title"]').content;144 const elements = document.querySelectorAll('.improvepage');145 const pageurl = window.location.href.split('?')[0];146 elements.forEach(element => {147 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));148 url.searchParams.set('pagetitle', title);149 url.searchParams.set('pageurl', pageurl);150 url.searchParams.set('pagesource', "library/zoneinfo.rst");151 element.href = url.toString();152 });153 });154 </script>155 <div role="note" aria-label="source link">156 <h3>This page</h3>157 <ul class="this-page-menu">158 <li><a href="../bugs.html">Report a bug</a></li>159 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>160 <li>161 <a href="https://github.com/python/cpython/blob/main/Doc/library/zoneinfo.rst?plain=1"162 rel="nofollow">Show source163 </a>164 </li>165 166 </ul>167 </div>168 </nav>169 </div>170</div>171 172 173 <div class="related" role="navigation" aria-label="Related">174 <h3>Navigation</h3>175 <ul>176 <li class="right" style="margin-right: 10px">177 <a href="../genindex.html" title="General Index"178 accesskey="I">index</a></li>179 <li class="right" >180 <a href="../py-modindex.html" title="Python Module Index"181 >modules</a> |</li>182 <li class="right" >183 <a href="calendar.html" title="calendar — General calendar-related functions"184 accesskey="N">next</a> |</li>185 <li class="right" >186 <a href="datetime.html" title="datetime — Basic date and time types"187 accesskey="P">previous</a> |</li>188 189 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>190 <li><a href="https://www.python.org/">Python</a> »</li>191 <li class="switchers">192 <div class="language_switcher_placeholder"></div>193 <div class="version_switcher_placeholder"></div>194 </li>195 <li>196 197 </li>198 <li id="cpython-language-and-version">199 <a href="../index.html">3.15.0a6 Documentation</a> »200 </li>201 202 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>203 <li class="nav-item nav-item-2"><a href="datatypes.html" accesskey="U">Data Types</a> »</li>204 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> — IANA time zone support</a></li>205 <li class="right">206 207 208 <div class="inline-search" role="search">209 <form class="inline-search" action="../search.html" method="get">210 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">211 <input type="submit" value="Go">212 </form>213 </div>214 |215 </li>216 <li class="right">217<label class="theme-selector-label">218 Theme219 <select class="theme-selector" oninput="activateTheme(this.value)">220 <option value="auto" selected>Auto</option>221 <option value="light">Light</option>222 <option value="dark">Dark</option>223 </select>224</label> |</li>225 226 </ul>227 </div> 228 229 <div class="document">230 <div class="documentwrapper">231 <div class="bodywrapper">232 <div class="body" role="main">233 234 <section id="module-zoneinfo">235<span id="zoneinfo-iana-time-zone-support"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> — IANA time zone support<a class="headerlink" href="#module-zoneinfo" title="Link to this heading">¶</a></h1>236<div class="versionadded">237<p><span class="versionmodified added">Added in version 3.9.</span></p>238</div>239<p><strong>Source code:</strong> <a class="extlink-source reference external" href="https://github.com/python/cpython/tree/main/Lib/zoneinfo">Lib/zoneinfo</a></p>240<hr class="docutils" />241<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> module provides a concrete time zone implementation to242support the IANA time zone database as originally specified in <span class="target" id="index-0"></span><a class="pep reference external" href="https://peps.python.org/pep-0615/"><strong>PEP 615</strong></a>. By243default, <code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> uses the system’s time zone data if available; if no244system time zone data is available, the library will fall back to using the245first-party <a class="extlink-pypi reference external" href="https://pypi.org/project/tzdata/">tzdata</a> package available on PyPI.</p>246<div class="admonition seealso">247<p class="admonition-title">See also</p>248<dl class="simple">249<dt>Module: <a class="reference internal" href="datetime.html#module-datetime" title="datetime: Basic date and time types."><code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code></a></dt><dd><p>Provides the <a class="reference internal" href="datetime.html#datetime.time" title="datetime.time"><code class="xref py py-class docutils literal notranslate"><span class="pre">time</span></code></a> and <a class="reference internal" href="datetime.html#datetime.datetime" title="datetime.datetime"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime</span></code></a>250types with which the <a class="reference internal" href="#zoneinfo.ZoneInfo" title="zoneinfo.ZoneInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a> class is designed to be used.</p>251</dd>252<dt>Package <a class="extlink-pypi reference external" href="https://pypi.org/project/tzdata/">tzdata</a></dt><dd><p>First-party package maintained by the CPython core developers to supply253time zone data via PyPI.</p>254</dd>255</dl>256</div>257<div class="availability docutils container">258<p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not WASI.</p>259<p>This module does not work or is not available on WebAssembly. See260<a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p>261</div>262<section id="using-zoneinfo">263<h2>Using <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code><a class="headerlink" href="#using-zoneinfo" title="Link to this heading">¶</a></h2>264<p><a class="reference internal" href="#zoneinfo.ZoneInfo" title="zoneinfo.ZoneInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a> is a concrete implementation of the <a class="reference internal" href="datetime.html#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.tzinfo</span></code></a>265abstract base class, and is intended to be attached to <code class="docutils literal notranslate"><span class="pre">tzinfo</span></code>, either via266the constructor, the <a class="reference internal" href="datetime.html#datetime.datetime.replace" title="datetime.datetime.replace"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.replace</span></code></a>267method or <a class="reference internal" href="datetime.html#datetime.datetime.astimezone" title="datetime.datetime.astimezone"><code class="xref py py-meth docutils literal notranslate"><span class="pre">datetime.astimezone</span></code></a>:</p>268<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">zoneinfo</span><span class="w"> </span><span class="kn">import</span> <span class="n">ZoneInfo</span>269<span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">timedelta</span>270 271<span class="gp">>>> </span><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2020</span><span class="p">,</span> <span class="mi">10</span><span class="p">,</span> <span class="mi">31</span><span class="p">,</span> <span class="mi">12</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="s2">"America/Los_Angeles"</span><span class="p">))</span>272<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">dt</span><span class="p">)</span>273<span class="go">2020-10-31 12:00:00-07:00</span>274 275<span class="gp">>>> </span><span class="n">dt</span><span class="o">.</span><span class="n">tzname</span><span class="p">()</span>276<span class="go">'PDT'</span>277</pre></div>278</div>279<p>Datetimes constructed in this way are compatible with datetime arithmetic and280handle daylight saving time transitions with no further intervention:</p>281<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dt_add</span> <span class="o">=</span> <span class="n">dt</span> <span class="o">+</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">days</span><span class="o">=</span><span class="mi">1</span><span class="p">)</span>282 283<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">dt_add</span><span class="p">)</span>284<span class="go">2020-11-01 12:00:00-08:00</span>285 286<span class="gp">>>> </span><span class="n">dt_add</span><span class="o">.</span><span class="n">tzname</span><span class="p">()</span>287<span class="go">'PST'</span>288</pre></div>289</div>290<p>These time zones also support the <a class="reference internal" href="datetime.html#datetime.datetime.fold" title="datetime.datetime.fold"><code class="xref py py-attr docutils literal notranslate"><span class="pre">fold</span></code></a> attribute291introduced in <span class="target" id="index-1"></span><a class="pep reference external" href="https://peps.python.org/pep-0495/"><strong>PEP 495</strong></a>. During offset transitions which induce ambiguous292times (such as a daylight saving time to standard time transition), the offset293from <em>before</em> the transition is used when <code class="docutils literal notranslate"><span class="pre">fold=0</span></code>, and the offset <em>after</em>294the transition is used when <code class="docutils literal notranslate"><span class="pre">fold=1</span></code>, for example:</p>295<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2020</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">1</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="s2">"America/Los_Angeles"</span><span class="p">))</span>296<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">dt</span><span class="p">)</span>297<span class="go">2020-11-01 01:00:00-07:00</span>298 299<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">dt</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">fold</span><span class="o">=</span><span class="mi">1</span><span class="p">))</span>300<span class="go">2020-11-01 01:00:00-08:00</span>301</pre></div>302</div>303<p>When converting from another time zone, the fold will be set to the correct304value:</p>305<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">timezone</span>306<span class="gp">>>> </span><span class="n">LOS_ANGELES</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="s2">"America/Los_Angeles"</span><span class="p">)</span>307<span class="gp">>>> </span><span class="n">dt_utc</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2020</span><span class="p">,</span> <span class="mi">11</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">8</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">timezone</span><span class="o">.</span><span class="n">utc</span><span class="p">)</span>308 309<span class="gp">>>> </span><span class="c1"># Before the PDT -> PST transition</span>310<span class="gp">>>> </span><span class="nb">print</span><span class="p">(</span><span class="n">dt_utc</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">LOS_ANGELES</span><span class="p">))</span>311<span class="go">2020-11-01 01:00:00-07:00</span>312 313<span class="gp">>>> </span><span class="c1"># After the PDT -> PST transition</span>314<span class="gp">>>> </span><span class="nb">print</span><span class="p">((</span><span class="n">dt_utc</span> <span class="o">+</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">hours</span><span class="o">=</span><span class="mi">1</span><span class="p">))</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">LOS_ANGELES</span><span class="p">))</span>315<span class="go">2020-11-01 01:00:00-08:00</span>316</pre></div>317</div>318</section>319<section id="data-sources">320<h2>Data sources<a class="headerlink" href="#data-sources" title="Link to this heading">¶</a></h2>321<p>The <code class="docutils literal notranslate"><span class="pre">zoneinfo</span></code> module does not directly provide time zone data, and instead322pulls time zone information from the system time zone database or the323first-party PyPI package <a class="extlink-pypi reference external" href="https://pypi.org/project/tzdata/">tzdata</a>, if available. Some systems, including324notably Windows systems, do not have an IANA database available, and so for325projects targeting cross-platform compatibility that require time zone data, it326is recommended to declare a dependency on tzdata. If neither system data nor327tzdata are available, all calls to <a class="reference internal" href="#zoneinfo.ZoneInfo" title="zoneinfo.ZoneInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a> will raise328<a class="reference internal" href="#zoneinfo.ZoneInfoNotFoundError" title="zoneinfo.ZoneInfoNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ZoneInfoNotFoundError</span></code></a>.</p>329<section id="configuring-the-data-sources">330<span id="zoneinfo-data-configuration"></span><h3>Configuring the data sources<a class="headerlink" href="#configuring-the-data-sources" title="Link to this heading">¶</a></h3>331<p>When <code class="docutils literal notranslate"><span class="pre">ZoneInfo(key)</span></code> is called, the constructor first searches the332directories specified in <a class="reference internal" href="#zoneinfo.TZPATH" title="zoneinfo.TZPATH"><code class="xref py py-data docutils literal notranslate"><span class="pre">TZPATH</span></code></a> for a file matching <code class="docutils literal notranslate"><span class="pre">key</span></code>, and on333failure looks for a match in the tzdata package. This behavior can be334configured in three ways:</p>335<ol class="arabic simple">336<li><p>The default <a class="reference internal" href="#zoneinfo.TZPATH" title="zoneinfo.TZPATH"><code class="xref py py-data docutils literal notranslate"><span class="pre">TZPATH</span></code></a> when not otherwise specified can be configured at337<a class="reference internal" href="#zoneinfo-data-compile-time-config"><span class="std std-ref">compile time</span></a>.</p></li>338<li><p><a class="reference internal" href="#zoneinfo.TZPATH" title="zoneinfo.TZPATH"><code class="xref py py-data docutils literal notranslate"><span class="pre">TZPATH</span></code></a> can be configured using <a class="reference internal" href="#zoneinfo-data-environment-var"><span class="std std-ref">an environment variable</span></a>.</p></li>339<li><p>At <a class="reference internal" href="#zoneinfo-data-runtime-config"><span class="std std-ref">runtime</span></a>, the search path can be340manipulated using the <a class="reference internal" href="#zoneinfo.reset_tzpath" title="zoneinfo.reset_tzpath"><code class="xref py py-func docutils literal notranslate"><span class="pre">reset_tzpath()</span></code></a> function.</p></li>341</ol>342<section id="compile-time-configuration">343<span id="zoneinfo-data-compile-time-config"></span><h4>Compile-time configuration<a class="headerlink" href="#compile-time-configuration" title="Link to this heading">¶</a></h4>344<p>The default <a class="reference internal" href="#zoneinfo.TZPATH" title="zoneinfo.TZPATH"><code class="xref py py-data docutils literal notranslate"><span class="pre">TZPATH</span></code></a> includes several common deployment locations for the345time zone database (except on Windows, where there are no “well-known”346locations for time zone data). On POSIX systems, downstream distributors and347those building Python from source who know where their system348time zone data is deployed may change the default time zone path by specifying349the compile-time option <code class="docutils literal notranslate"><span class="pre">TZPATH</span></code> (or, more likely, the <a class="reference internal" href="../using/configure.html#cmdoption-with-tzpath"><code class="xref std std-option docutils literal notranslate"><span class="pre">configure</span>350<span class="pre">flag</span> <span class="pre">--with-tzpath</span></code></a>), which should be a string delimited by351<a class="reference internal" href="os.html#os.pathsep" title="os.pathsep"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.pathsep</span></code></a>.</p>352<p>On all platforms, the configured value is available as the <code class="docutils literal notranslate"><span class="pre">TZPATH</span></code> key in353<a class="reference internal" href="sysconfig.html#sysconfig.get_config_var" title="sysconfig.get_config_var"><code class="xref py py-func docutils literal notranslate"><span class="pre">sysconfig.get_config_var()</span></code></a>.</p>354</section>355<section id="environment-configuration">356<span id="zoneinfo-data-environment-var"></span><h4>Environment configuration<a class="headerlink" href="#environment-configuration" title="Link to this heading">¶</a></h4>357<p>When initializing <a class="reference internal" href="#zoneinfo.TZPATH" title="zoneinfo.TZPATH"><code class="xref py py-data docutils literal notranslate"><span class="pre">TZPATH</span></code></a> (either at import time or whenever358<a class="reference internal" href="#zoneinfo.reset_tzpath" title="zoneinfo.reset_tzpath"><code class="xref py py-func docutils literal notranslate"><span class="pre">reset_tzpath()</span></code></a> is called with no arguments), the <code class="docutils literal notranslate"><span class="pre">zoneinfo</span></code> module will359use the environment variable <code class="docutils literal notranslate"><span class="pre">PYTHONTZPATH</span></code>, if it exists, to set the search360path.</p>361<dl class="std envvar">362<dt class="sig sig-object std" id="envvar-PYTHONTZPATH">363<span class="sig-name descname"><span class="pre">PYTHONTZPATH</span></span><a class="headerlink" href="#envvar-PYTHONTZPATH" title="Link to this definition">¶</a></dt>364<dd><p>This is an <a class="reference internal" href="os.html#os.pathsep" title="os.pathsep"><code class="xref py py-data docutils literal notranslate"><span class="pre">os.pathsep</span></code></a>-separated string containing the time zone365search path to use. It must consist of only absolute rather than relative366paths. Relative components specified in <code class="docutils literal notranslate"><span class="pre">PYTHONTZPATH</span></code> will not be used,367but otherwise the behavior when a relative path is specified is368implementation-defined; CPython will raise <a class="reference internal" href="#zoneinfo.InvalidTZPathWarning" title="zoneinfo.InvalidTZPathWarning"><code class="xref py py-exc docutils literal notranslate"><span class="pre">InvalidTZPathWarning</span></code></a>, but369other implementations are free to silently ignore the erroneous component370or raise an exception.</p>371</dd></dl>372 373<p>To set the system to ignore the system data and use the tzdata package374instead, set <code class="docutils literal notranslate"><span class="pre">PYTHONTZPATH=""</span></code>.</p>375</section>376<section id="runtime-configuration">377<span id="zoneinfo-data-runtime-config"></span><h4>Runtime configuration<a class="headerlink" href="#runtime-configuration" title="Link to this heading">¶</a></h4>378<p>The TZ search path can also be configured at runtime using the379<a class="reference internal" href="#zoneinfo.reset_tzpath" title="zoneinfo.reset_tzpath"><code class="xref py py-func docutils literal notranslate"><span class="pre">reset_tzpath()</span></code></a> function. This is generally not an advisable operation,380though it is reasonable to use it in test functions that require the use of a381specific time zone path (or require disabling access to the system time zones).</p>382</section>383</section>384</section>385<section id="the-zoneinfo-class">386<h2>The <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class<a class="headerlink" href="#the-zoneinfo-class" title="Link to this heading">¶</a></h2>387<dl class="py class">388<dt class="sig sig-object py" id="zoneinfo.ZoneInfo">389<em class="property"><span class="k"><span class="pre">class</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">zoneinfo.</span></span><span class="sig-name descname"><span class="pre">ZoneInfo</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#zoneinfo.ZoneInfo" title="Link to this definition">¶</a></dt>390<dd><p>A concrete <a class="reference internal" href="datetime.html#datetime.tzinfo" title="datetime.tzinfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">datetime.tzinfo</span></code></a> subclass that represents an IANA time391zone specified by the string <code class="docutils literal notranslate"><span class="pre">key</span></code>. Calls to the primary constructor will392always return objects that compare identically; put another way, barring393cache invalidation via <a class="reference internal" href="#zoneinfo.ZoneInfo.clear_cache" title="zoneinfo.ZoneInfo.clear_cache"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ZoneInfo.clear_cache()</span></code></a>, for all values of394<code class="docutils literal notranslate"><span class="pre">key</span></code>, the following assertion will always be true:</p>395<div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">a</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>396<span class="n">b</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>397<span class="k">assert</span> <span class="n">a</span> <span class="ow">is</span> <span class="n">b</span>398</pre></div>399</div>400<p><code class="docutils literal notranslate"><span class="pre">key</span></code> must be in the form of a relative, normalized POSIX path, with no401up-level references. The constructor will raise <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> if a402non-conforming key is passed.</p>403<p>If no file matching <code class="docutils literal notranslate"><span class="pre">key</span></code> is found, the constructor will raise404<a class="reference internal" href="#zoneinfo.ZoneInfoNotFoundError" title="zoneinfo.ZoneInfoNotFoundError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ZoneInfoNotFoundError</span></code></a>.</p>405</dd></dl>406 407<p>The <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class has two alternate constructors:</p>408<dl class="py method">409<dt class="sig sig-object py" id="zoneinfo.ZoneInfo.from_file">410<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">ZoneInfo.</span></span><span class="sig-name descname"><span class="pre">from_file</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">file_obj</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">key</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#zoneinfo.ZoneInfo.from_file" title="Link to this definition">¶</a></dt>411<dd><p>Constructs a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> object from a file-like object returning bytes412(e.g. a file opened in binary mode or an <a class="reference internal" href="io.html#io.BytesIO" title="io.BytesIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.BytesIO</span></code></a> object).413Unlike the primary constructor, this always constructs a new object.</p>414<p>The <code class="docutils literal notranslate"><span class="pre">key</span></code> parameter sets the name of the zone for the purposes of415<a class="reference internal" href="../reference/datamodel.html#object.__str__" title="object.__str__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__str__()</span></code></a> and <a class="reference internal" href="../reference/datamodel.html#object.__repr__" title="object.__repr__"><code class="xref py py-meth docutils literal notranslate"><span class="pre">__repr__()</span></code></a>.</p>416<p>Objects created via this constructor cannot be pickled (see <a class="reference internal" href="#pickling">pickling</a>).</p>417<p><a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised if the data read from <em>file_obj</em> is not a valid418TZif file.</p>419</dd></dl>420 421<dl class="py method">422<dt class="sig sig-object py" id="zoneinfo.ZoneInfo.no_cache">423<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">ZoneInfo.</span></span><span class="sig-name descname"><span class="pre">no_cache</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">key</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#zoneinfo.ZoneInfo.no_cache" title="Link to this definition">¶</a></dt>424<dd><p>An alternate constructor that bypasses the constructor’s cache. It is425identical to the primary constructor, but returns a new object on each426call. This is most likely to be useful for testing or demonstration427purposes, but it can also be used to create a system with a different cache428invalidation strategy.</p>429<p>Objects created via this constructor will also bypass the cache of a430deserializing process when unpickled.</p>431<div class="admonition caution">432<p class="admonition-title">Caution</p>433<p>Using this constructor may change the semantics of your datetimes in434surprising ways, only use it if you know that you need to.</p>435</div>436</dd></dl>437 438<p>The following class methods are also available:</p>439<dl class="py method">440<dt class="sig sig-object py" id="zoneinfo.ZoneInfo.clear_cache">441<em class="property"><span class="k"><span class="pre">classmethod</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">ZoneInfo.</span></span><span class="sig-name descname"><span class="pre">clear_cache</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">only_keys</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#zoneinfo.ZoneInfo.clear_cache" title="Link to this definition">¶</a></dt>442<dd><p>A method for invalidating the cache on the <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class. If no443arguments are passed, all caches are invalidated and the next call to444the primary constructor for each key will return a new instance.</p>445<p>If an iterable of key names is passed to the <code class="docutils literal notranslate"><span class="pre">only_keys</span></code> parameter, only446the specified keys will be removed from the cache. Keys passed to447<code class="docutils literal notranslate"><span class="pre">only_keys</span></code> but not found in the cache are ignored.</p>448<div class="admonition warning">449<p class="admonition-title">Warning</p>450<p>Invoking this function may change the semantics of datetimes using451<code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> in surprising ways; this modifies module state452and thus may have wide-ranging effects. Only use it if you know that you453need to.</p>454</div>455</dd></dl>456 457<p>The class has one attribute:</p>458<dl class="py attribute">459<dt class="sig sig-object py" id="zoneinfo.ZoneInfo.key">460<span class="sig-prename descclassname"><span class="pre">ZoneInfo.</span></span><span class="sig-name descname"><span class="pre">key</span></span><a class="headerlink" href="#zoneinfo.ZoneInfo.key" title="Link to this definition">¶</a></dt>461<dd><p>This is a read-only <a class="reference internal" href="../glossary.html#term-attribute"><span class="xref std std-term">attribute</span></a> that returns the value of <code class="docutils literal notranslate"><span class="pre">key</span></code>462passed to the constructor, which should be a lookup key in the IANA time463zone database (e.g. <code class="docutils literal notranslate"><span class="pre">America/New_York</span></code>, <code class="docutils literal notranslate"><span class="pre">Europe/Paris</span></code> or464<code class="docutils literal notranslate"><span class="pre">Asia/Tokyo</span></code>).</p>465<p>For zones constructed from file without specifying a <code class="docutils literal notranslate"><span class="pre">key</span></code> parameter,466this will be set to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>467<div class="admonition note">468<p class="admonition-title">Note</p>469<p>Although it is a somewhat common practice to expose these to end users,470these values are designed to be primary keys for representing the471relevant zones and not necessarily user-facing elements. Projects like472CLDR (the Unicode Common Locale Data Repository) can be used to get473more user-friendly strings from these keys.</p>474</div>475</dd></dl>476 477<section id="string-representations">478<h3>String representations<a class="headerlink" href="#string-representations" title="Link to this heading">¶</a></h3>479<p>The string representation returned when calling <a class="reference internal" href="stdtypes.html#str" title="str"><code class="xref py py-class docutils literal notranslate"><span class="pre">str</span></code></a> on a480<a class="reference internal" href="#zoneinfo.ZoneInfo" title="zoneinfo.ZoneInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a> object defaults to using the <a class="reference internal" href="#zoneinfo.ZoneInfo.key" title="zoneinfo.ZoneInfo.key"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ZoneInfo.key</span></code></a> attribute (see481the note on usage in the attribute documentation):</p>482<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">zone</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="s2">"Pacific/Kwajalein"</span><span class="p">)</span>483<span class="gp">>>> </span><span class="nb">str</span><span class="p">(</span><span class="n">zone</span><span class="p">)</span>484<span class="go">'Pacific/Kwajalein'</span>485 486<span class="gp">>>> </span><span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="p">(</span><span class="mi">2020</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">15</span><span class="p">,</span> <span class="n">tzinfo</span><span class="o">=</span><span class="n">zone</span><span class="p">)</span>487<span class="gp">>>> </span><span class="sa">f</span><span class="s2">"</span><span class="si">{</span><span class="n">dt</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span><span class="si">}</span><span class="s2"> [</span><span class="si">{</span><span class="n">dt</span><span class="o">.</span><span class="n">tzinfo</span><span class="si">}</span><span class="s2">]"</span>488<span class="go">'2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]'</span>489</pre></div>490</div>491<p>For objects constructed from a file without specifying a <code class="docutils literal notranslate"><span class="pre">key</span></code> parameter,492<code class="docutils literal notranslate"><span class="pre">str</span></code> falls back to calling <a class="reference internal" href="functions.html#repr" title="repr"><code class="xref py py-func docutils literal notranslate"><span class="pre">repr()</span></code></a>. <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code>’s <code class="docutils literal notranslate"><span class="pre">repr</span></code> is493implementation-defined and not necessarily stable between versions, but it is494guaranteed not to be a valid <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> key.</p>495</section>496<section id="pickle-serialization">497<span id="pickling"></span><h3>Pickle serialization<a class="headerlink" href="#pickle-serialization" title="Link to this heading">¶</a></h3>498<p>Rather than serializing all transition data, <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> objects are499serialized by key, and <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> objects constructed from files (even those500with a value for <code class="docutils literal notranslate"><span class="pre">key</span></code> specified) cannot be pickled.</p>501<p>The behavior of a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> file depends on how it was constructed:</p>502<ol class="arabic">503<li><p><code class="docutils literal notranslate"><span class="pre">ZoneInfo(key)</span></code>: When constructed with the primary constructor, a504<code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> object is serialized by key, and when deserialized, the505deserializing process uses the primary and thus it is expected that these506are the same object as other references to the same time507zone. For example, if <code class="docutils literal notranslate"><span class="pre">europe_berlin_pkl</span></code> is a string containing a pickle508constructed from <code class="docutils literal notranslate"><span class="pre">ZoneInfo("Europe/Berlin")</span></code>, one would expect the509following behavior:</p>510<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="s2">"Europe/Berlin"</span><span class="p">)</span>511<span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">pickle</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">europe_berlin_pkl</span><span class="p">)</span>512<span class="gp">>>> </span><span class="n">a</span> <span class="ow">is</span> <span class="n">b</span>513<span class="go">True</span>514</pre></div>515</div>516</li>517<li><p><code class="docutils literal notranslate"><span class="pre">ZoneInfo.no_cache(key)</span></code>: When constructed from the cache-bypassing518constructor, the <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> object is also serialized by key, but when519deserialized, the deserializing process uses the cache bypassing520constructor. If <code class="docutils literal notranslate"><span class="pre">europe_berlin_pkl_nc</span></code> is a string containing a pickle521constructed from <code class="docutils literal notranslate"><span class="pre">ZoneInfo.no_cache("Europe/Berlin")</span></code>, one would expect522the following behavior:</p>523<div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">a</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="s2">"Europe/Berlin"</span><span class="p">)</span>524<span class="gp">>>> </span><span class="n">b</span> <span class="o">=</span> <span class="n">pickle</span><span class="o">.</span><span class="n">loads</span><span class="p">(</span><span class="n">europe_berlin_pkl_nc</span><span class="p">)</span>525<span class="gp">>>> </span><span class="n">a</span> <span class="ow">is</span> <span class="n">b</span>526<span class="go">False</span>527</pre></div>528</div>529</li>530<li><p><code class="docutils literal notranslate"><span class="pre">ZoneInfo.from_file(file_obj,</span> <span class="pre">/,</span> <span class="pre">key=None)</span></code>: When constructed from a file, the531<code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> object raises an exception on pickling. If an end user wants to532pickle a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> constructed from a file, it is recommended that they533use a wrapper type or a custom serialization function: either serializing by534key or storing the contents of the file object and serializing that.</p></li>535</ol>536<p>This method of serialization requires that the time zone data for the required537key be available on both the serializing and deserializing side, similar to the538way that references to classes and functions are expected to exist in both the539serializing and deserializing environments. It also means that no guarantees540are made about the consistency of results when unpickling a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code>541pickled in an environment with a different version of the time zone data.</p>542</section>543</section>544<section id="functions">545<h2>Functions<a class="headerlink" href="#functions" title="Link to this heading">¶</a></h2>546<dl class="py function">547<dt class="sig sig-object py" id="zoneinfo.available_timezones">548<span class="sig-prename descclassname"><span class="pre">zoneinfo.</span></span><span class="sig-name descname"><span class="pre">available_timezones</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#zoneinfo.available_timezones" title="Link to this definition">¶</a></dt>549<dd><p>Get a set containing all the valid keys for IANA time zones available550anywhere on the time zone path. This is recalculated on every call to the551function.</p>552<p>This function only includes canonical zone names and does not include553“special” zones such as those under the <code class="docutils literal notranslate"><span class="pre">posix/</span></code> and <code class="docutils literal notranslate"><span class="pre">right/</span></code>554directories, the <code class="docutils literal notranslate"><span class="pre">posixrules</span></code> or the <code class="docutils literal notranslate"><span class="pre">localtime</span></code> zone.</p>555<div class="admonition caution">556<p class="admonition-title">Caution</p>557<p>This function may open a large number of files, as the best way to558determine if a file on the time zone path is a valid time zone is to559read the “magic string” at the beginning.</p>560</div>561<div class="admonition note">562<p class="admonition-title">Note</p>563<p>These values are not designed to be exposed to end-users; for user564facing elements, applications should use something like CLDR (the565Unicode Common Locale Data Repository) to get more user-friendly566strings. See also the cautionary note on <a class="reference internal" href="#zoneinfo.ZoneInfo.key" title="zoneinfo.ZoneInfo.key"><code class="xref py py-attr docutils literal notranslate"><span class="pre">ZoneInfo.key</span></code></a>.</p>567</div>568</dd></dl>569 570<dl class="py function">571<dt class="sig sig-object py" id="zoneinfo.reset_tzpath">572<span class="sig-prename descclassname"><span class="pre">zoneinfo.</span></span><span class="sig-name descname"><span class="pre">reset_tzpath</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">to</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#zoneinfo.reset_tzpath" title="Link to this definition">¶</a></dt>573<dd><p>Sets or resets the time zone search path (<a class="reference internal" href="#zoneinfo.TZPATH" title="zoneinfo.TZPATH"><code class="xref py py-data docutils literal notranslate"><span class="pre">TZPATH</span></code></a>) for the module.574When called with no arguments, <code class="xref py py-data docutils literal notranslate"><span class="pre">TZPATH</span></code> is set to the default value.</p>575<p>Calling <code class="docutils literal notranslate"><span class="pre">reset_tzpath</span></code> will not invalidate the <a class="reference internal" href="#zoneinfo.ZoneInfo" title="zoneinfo.ZoneInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a> cache,576and so calls to the primary <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> constructor will only use the new577<code class="docutils literal notranslate"><span class="pre">TZPATH</span></code> in the case of a cache miss.</p>578<p>The <code class="docutils literal notranslate"><span class="pre">to</span></code> parameter must be a <a class="reference internal" href="../glossary.html#term-sequence"><span class="xref std std-term">sequence</span></a> of strings or579<a class="reference internal" href="os.html#os.PathLike" title="os.PathLike"><code class="xref py py-class docutils literal notranslate"><span class="pre">os.PathLike</span></code></a> and not a string, all of which must be absolute paths.580<a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> will be raised if something other than an absolute path581is passed.</p>582</dd></dl>583 584</section>585<section id="globals">586<h2>Globals<a class="headerlink" href="#globals" title="Link to this heading">¶</a></h2>587<dl class="py data">588<dt class="sig sig-object py" id="zoneinfo.TZPATH">589<span class="sig-prename descclassname"><span class="pre">zoneinfo.</span></span><span class="sig-name descname"><span class="pre">TZPATH</span></span><a class="headerlink" href="#zoneinfo.TZPATH" title="Link to this definition">¶</a></dt>590<dd><p>A read-only sequence representing the time zone search path – when591constructing a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> from a key, the key is joined to each entry in592the <code class="docutils literal notranslate"><span class="pre">TZPATH</span></code>, and the first file found is used.</p>593<p><code class="docutils literal notranslate"><span class="pre">TZPATH</span></code> may contain only absolute paths, never relative paths,594regardless of how it is configured.</p>595<p>The object that <code class="docutils literal notranslate"><span class="pre">zoneinfo.TZPATH</span></code> points to may change in response to a596call to <a class="reference internal" href="#zoneinfo.reset_tzpath" title="zoneinfo.reset_tzpath"><code class="xref py py-func docutils literal notranslate"><span class="pre">reset_tzpath()</span></code></a>, so it is recommended to use597<code class="docutils literal notranslate"><span class="pre">zoneinfo.TZPATH</span></code> rather than importing <code class="docutils literal notranslate"><span class="pre">TZPATH</span></code> from <code class="docutils literal notranslate"><span class="pre">zoneinfo</span></code> or598assigning a long-lived variable to <code class="docutils literal notranslate"><span class="pre">zoneinfo.TZPATH</span></code>.</p>599<p>For more information on configuring the time zone search path, see600<a class="reference internal" href="#zoneinfo-data-configuration"><span class="std std-ref">Configuring the data sources</span></a>.</p>601</dd></dl>602 603</section>604<section id="exceptions-and-warnings">605<h2>Exceptions and warnings<a class="headerlink" href="#exceptions-and-warnings" title="Link to this heading">¶</a></h2>606<dl class="py exception">607<dt class="sig sig-object py" id="zoneinfo.ZoneInfoNotFoundError">608<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">zoneinfo.</span></span><span class="sig-name descname"><span class="pre">ZoneInfoNotFoundError</span></span><a class="headerlink" href="#zoneinfo.ZoneInfoNotFoundError" title="Link to this definition">¶</a></dt>609<dd><p>Raised when construction of a <a class="reference internal" href="#zoneinfo.ZoneInfo" title="zoneinfo.ZoneInfo"><code class="xref py py-class docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a> object fails because the610specified key could not be found on the system. This is a subclass of611<a class="reference internal" href="exceptions.html#KeyError" title="KeyError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">KeyError</span></code></a>.</p>612</dd></dl>613 614<dl class="py exception">615<dt class="sig sig-object py" id="zoneinfo.InvalidTZPathWarning">616<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">zoneinfo.</span></span><span class="sig-name descname"><span class="pre">InvalidTZPathWarning</span></span><a class="headerlink" href="#zoneinfo.InvalidTZPathWarning" title="Link to this definition">¶</a></dt>617<dd><p>Raised when <span class="target" id="index-2"></span><a class="reference internal" href="#envvar-PYTHONTZPATH"><code class="xref std std-envvar docutils literal notranslate"><span class="pre">PYTHONTZPATH</span></code></a> contains an invalid component that will618be filtered out, such as a relative path.</p>619</dd></dl>620 621</section>622</section>623 624 625 <div class="clearer"></div>626 </div>627 </div>628 </div>629 <div class="sphinxsidebar" role="navigation" aria-label="Main">630 <div class="sphinxsidebarwrapper">631 <div>632 <h3><a href="../contents.html">Table of Contents</a></h3>633 <ul>634<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> — IANA time zone support</a><ul>635<li><a class="reference internal" href="#using-zoneinfo">Using <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a></li>636<li><a class="reference internal" href="#data-sources">Data sources</a><ul>637<li><a class="reference internal" href="#configuring-the-data-sources">Configuring the data sources</a><ul>638<li><a class="reference internal" href="#compile-time-configuration">Compile-time configuration</a></li>639<li><a class="reference internal" href="#environment-configuration">Environment configuration</a></li>640<li><a class="reference internal" href="#runtime-configuration">Runtime configuration</a></li>641</ul>642</li>643</ul>644</li>645<li><a class="reference internal" href="#the-zoneinfo-class">The <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class</a><ul>646<li><a class="reference internal" href="#string-representations">String representations</a></li>647<li><a class="reference internal" href="#pickle-serialization">Pickle serialization</a></li>648</ul>649</li>650<li><a class="reference internal" href="#functions">Functions</a></li>651<li><a class="reference internal" href="#globals">Globals</a></li>652<li><a class="reference internal" href="#exceptions-and-warnings">Exceptions and warnings</a></li>653</ul>654</li>655</ul>656 657 </div>658 <div>659 <h4>Previous topic</h4>660 <p class="topless"><a href="datetime.html"661 title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">datetime</span></code> — Basic date and time types</a></p>662 </div>663 <div>664 <h4>Next topic</h4>665 <p class="topless"><a href="calendar.html"666 title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">calendar</span></code> — General calendar-related functions</a></p>667 </div>668 <script>669 document.addEventListener('DOMContentLoaded', () => {670 const title = document.querySelector('meta[property="og:title"]').content;671 const elements = document.querySelectorAll('.improvepage');672 const pageurl = window.location.href.split('?')[0];673 elements.forEach(element => {674 const url = new URL(element.href.split('?')[0].replace("-nojs", ""));675 url.searchParams.set('pagetitle', title);676 url.searchParams.set('pageurl', pageurl);677 url.searchParams.set('pagesource', "library/zoneinfo.rst");678 element.href = url.toString();679 });680 });681 </script>682 <div role="note" aria-label="source link">683 <h3>This page</h3>684 <ul class="this-page-menu">685 <li><a href="../bugs.html">Report a bug</a></li>686 <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>687 <li>688 <a href="https://github.com/python/cpython/blob/main/Doc/library/zoneinfo.rst?plain=1"689 rel="nofollow">Show source690 </a>691 </li>692 693 </ul>694 </div>695 </div>696<div id="sidebarbutton" title="Collapse sidebar">697<span>«</span>698</div>699 700 </div>701 <div class="clearer"></div>702 </div> 703 <div class="related" role="navigation" aria-label="Related">704 <h3>Navigation</h3>705 <ul>706 <li class="right" style="margin-right: 10px">707 <a href="../genindex.html" title="General Index"708 >index</a></li>709 <li class="right" >710 <a href="../py-modindex.html" title="Python Module Index"711 >modules</a> |</li>712 <li class="right" >713 <a href="calendar.html" title="calendar — General calendar-related functions"714 >next</a> |</li>715 <li class="right" >716 <a href="datetime.html" title="datetime — Basic date and time types"717 >previous</a> |</li>718 719 <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>720 <li><a href="https://www.python.org/">Python</a> »</li>721 <li class="switchers">722 <div class="language_switcher_placeholder"></div>723 <div class="version_switcher_placeholder"></div>724 </li>725 <li>726 727 </li>728 <li id="cpython-language-and-version">729 <a href="../index.html">3.15.0a6 Documentation</a> »730 </li>731 732 <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> »</li>733 <li class="nav-item nav-item-2"><a href="datatypes.html" >Data Types</a> »</li>734 <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code> — IANA time zone support</a></li>735 <li class="right">736 737 738 <div class="inline-search" role="search">739 <form class="inline-search" action="../search.html" method="get">740 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">741 <input type="submit" value="Go">742 </form>743 </div>744 |745 </li>746 <li class="right">747<label class="theme-selector-label">748 Theme749 <select class="theme-selector" oninput="activateTheme(this.value)">750 <option value="auto" selected>Auto</option>751 <option value="light">Light</option>752 <option value="dark">Dark</option>753 </select>754</label> |</li>755 756 </ul>757 </div> 758 <div class="footer">759 © <a href="../copyright.html">Copyright</a> 2001 Python Software Foundation.760 <br>761 This page is licensed under the Python Software Foundation License Version 2.762 <br>763 Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.764 <br>765 766 See <a href="/license.html">History and License</a> for more information.<br>767 768 769 <br>770 771 The Python Software Foundation is a non-profit corporation.772<a href="https://www.python.org/psf/donations/">Please donate.</a>773<br>774 <br>775 Last updated on Mar 10, 2026 (08:58 UTC).776 777 <a href="/bugs.html">Found a bug</a>?778 779 <br>780 781 Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.2.3.782 </div>783 784 </body>785</html>