Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Volgen 1
Ster 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Tree: 0f75e31513
Branches Labels
${ item.name }
Maak branch ${ searchTerm }
van '0f75e31513'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/zoneinfo.html

749 lines
60KB
Ruw Blame Geschiedenis 

  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" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <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..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>zoneinfo — IANA time zone support &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="calendar — General calendar-related functions" href="calendar.html" />

  39.     <link rel="prev" title="datetime — Basic date and time types" href="datetime.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/zoneinfo.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <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>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <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>

  99. <li><a class="reference internal" href="#using-zoneinfo">Using <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a></li>

  100. <li><a class="reference internal" href="#data-sources">Data sources</a><ul>

  101. <li><a class="reference internal" href="#configuring-the-data-sources">Configuring the data sources</a><ul>

  102. <li><a class="reference internal" href="#compile-time-configuration">Compile-time configuration</a></li>

  103. <li><a class="reference internal" href="#environment-configuration">Environment configuration</a></li>

  104. <li><a class="reference internal" href="#runtime-configuration">Runtime configuration</a></li>

  105. </ul>

  106. </li>

  107. </ul>

  108. </li>

  109. <li><a class="reference internal" href="#the-zoneinfo-class">The <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class</a><ul>

  110. <li><a class="reference internal" href="#string-representations">String representations</a></li>

  111. <li><a class="reference internal" href="#pickle-serialization">Pickle serialization</a></li>

  112. </ul>

  113. </li>

  114. <li><a class="reference internal" href="#functions">Functions</a></li>

  115. <li><a class="reference internal" href="#globals">Globals</a></li>

  116. <li><a class="reference internal" href="#exceptions-and-warnings">Exceptions and warnings</a></li>

  117. </ul>

  118. </li>

  119. </ul>

  120. 

  121.   </div>

  122.   <div>

  123.     <h4>Previous topic</h4>

  124.     <p class="topless"><a href="datetime.html"

  125.                           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>

  126.   </div>

  127.   <div>

  128.     <h4>Next topic</h4>

  129.     <p class="topless"><a href="calendar.html"

  130.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">calendar</span></code> — General calendar-related functions</a></p>

  131.   </div>

  132.   <div role="note" aria-label="source link">

  133.     <h3>This Page</h3>

  134.     <ul class="this-page-menu">

  135.       <li><a href="../bugs.html">Report a Bug</a></li>

  136.       <li>

  137.         <a href="https://github.com/python/cpython/blob/main/Doc/library/zoneinfo.rst"

  138.             rel="nofollow">Show Source

  139.         </a>

  140.       </li>

  141.     </ul>

  142.   </div>

  143.         </nav>

  144.     </div>

  145. </div>

  146. 

  147.   

  148.     <div class="related" role="navigation" aria-label="related navigation">

  149.       <h3>Navigation</h3>

  150.       <ul>

  151.         <li class="right" style="margin-right: 10px">

  152.           <a href="../genindex.html" title="General Index"

  153.              accesskey="I">index</a></li>

  154.         <li class="right" >

  155.           <a href="../py-modindex.html" title="Python Module Index"

  156.              >modules</a> |</li>

  157.         <li class="right" >

  158.           <a href="calendar.html" title="calendar — General calendar-related functions"

  159.              accesskey="N">next</a> |</li>

  160.         <li class="right" >

  161.           <a href="datetime.html" title="datetime — Basic date and time types"

  162.              accesskey="P">previous</a> |</li>

  163. 

  164.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  165.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  166.           <li class="switchers">

  167.             <div class="language_switcher_placeholder"></div>

  168.             <div class="version_switcher_placeholder"></div>

  169.           </li>

  170.           <li>

  171.               

  172.           </li>

  173.     <li id="cpython-language-and-version">

  174.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  175.     </li>

  176. 

  177.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  178.           <li class="nav-item nav-item-2"><a href="datatypes.html" accesskey="U">Data Types</a> &#187;</li>

  179.         <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>

  180.                 <li class="right">

  181.                     

  182. 

  183.     <div class="inline-search" role="search">

  184.         <form class="inline-search" action="../search.html" method="get">

  185.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  186.           <input type="submit" value="Go" />

  187.         </form>

  188.     </div>

  189.                      |

  190.                 </li>

  191.             <li class="right">

  192. <label class="theme-selector-label">

  193.     Theme

  194.     <select class="theme-selector" oninput="activateTheme(this.value)">

  195.         <option value="auto" selected>Auto</option>

  196.         <option value="light">Light</option>

  197.         <option value="dark">Dark</option>

  198.     </select>

  199. </label> |</li>

  200.             

  201.       </ul>

  202.     </div>    

  203. 

  204.     <div class="document">

  205.       <div class="documentwrapper">

  206.         <div class="bodywrapper">

  207.           <div class="body" role="main">

  208.             

  209.   <section id="module-zoneinfo">

  210. <span id="zoneinfo-iana-time-zone-support"></span><h1><a class="reference internal" href="#module-zoneinfo" title="zoneinfo: IANA time zone support"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code></a> — IANA time zone support<a class="headerlink" href="#module-zoneinfo" title="Link to this heading">¶</a></h1>

  211. <div class="versionadded">

  212. <p><span class="versionmodified added">New in version 3.9.</span></p>

  213. </div>

  214. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/zoneinfo">Lib/zoneinfo</a></p>

  215. <hr class="docutils" />

  216. <p>The <a class="reference internal" href="#module-zoneinfo" title="zoneinfo: IANA time zone support"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code></a> module provides a concrete time zone implementation to

  217. support 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>. By

  218. default, <a class="reference internal" href="#module-zoneinfo" title="zoneinfo: IANA time zone support"><code class="xref py py-mod docutils literal notranslate"><span class="pre">zoneinfo</span></code></a> uses the system’s time zone data if available; if no

  219. system time zone data is available, the library will fall back to using the

  220. first-party <a class="reference external" href="https://pypi.org/project/tzdata/">tzdata</a> package available on PyPI.</p>

  221. <div class="admonition seealso">

  222. <p class="admonition-title">See also</p>

  223. <dl class="simple">

  224. <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>

  225. types 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>

  226. </dd>

  227. <dt>Package <a class="reference external" href="https://pypi.org/project/tzdata/">tzdata</a></dt><dd><p>First-party package maintained by the CPython core developers to supply

  228. time zone data via PyPI.</p>

  229. </dd>

  230. </dl>

  231. </div>

  232. <div class="availability docutils container">

  233. <p><a class="reference internal" href="intro.html#availability"><span class="std std-ref">Availability</span></a>: not Emscripten, not WASI.</p>

  234. <p>This module does not work or is not available on WebAssembly platforms

  235. <code class="docutils literal notranslate"><span class="pre">wasm32-emscripten</span></code> and <code class="docutils literal notranslate"><span class="pre">wasm32-wasi</span></code>. See

  236. <a class="reference internal" href="intro.html#wasm-availability"><span class="std std-ref">WebAssembly platforms</span></a> for more information.</p>

  237. </div>

  238. <section id="using-zoneinfo">

  239. <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>

  240. <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>

  241. abstract base class, and is intended to be attached to <code class="docutils literal notranslate"><span class="pre">tzinfo</span></code>, either via

  242. the 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>

  243. method 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>

  244. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">zoneinfo</span> <span class="kn">import</span> <span class="n">ZoneInfo</span>

  245. <span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">datetime</span><span class="p">,</span> <span class="n">timedelta</span>

  246. 

  247. <span class="gp">&gt;&gt;&gt; </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">&quot;America/Los_Angeles&quot;</span><span class="p">))</span>

  248. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">dt</span><span class="p">)</span>

  249. <span class="go">2020-10-31 12:00:00-07:00</span>

  250. 

  251. <span class="gp">&gt;&gt;&gt; </span><span class="n">dt</span><span class="o">.</span><span class="n">tzname</span><span class="p">()</span>

  252. <span class="go">&#39;PDT&#39;</span>

  253. </pre></div>

  254. </div>

  255. <p>Datetimes constructed in this way are compatible with datetime arithmetic and

  256. handle daylight saving time transitions with no further intervention:</p>

  257. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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>

  258. 

  259. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">dt_add</span><span class="p">)</span>

  260. <span class="go">2020-11-01 12:00:00-08:00</span>

  261. 

  262. <span class="gp">&gt;&gt;&gt; </span><span class="n">dt_add</span><span class="o">.</span><span class="n">tzname</span><span class="p">()</span>

  263. <span class="go">&#39;PST&#39;</span>

  264. </pre></div>

  265. </div>

  266. <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> attribute

  267. introduced 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 ambiguous

  268. times (such as a daylight saving time to standard time transition), the offset

  269. from <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>

  270. the transition is used when <code class="docutils literal notranslate"><span class="pre">fold=1</span></code>, for example:</p>

  271. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </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">&quot;America/Los_Angeles&quot;</span><span class="p">))</span>

  272. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">dt</span><span class="p">)</span>

  273. <span class="go">2020-11-01 01:00:00-07:00</span>

  274. 

  275. <span class="gp">&gt;&gt;&gt; </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>

  276. <span class="go">2020-11-01 01:00:00-08:00</span>

  277. </pre></div>

  278. </div>

  279. <p>When converting from another time zone, the fold will be set to the correct

  280. value:</p>

  281. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">datetime</span> <span class="kn">import</span> <span class="n">timezone</span>

  282. <span class="gp">&gt;&gt;&gt; </span><span class="n">LOS_ANGELES</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="s2">&quot;America/Los_Angeles&quot;</span><span class="p">)</span>

  283. <span class="gp">&gt;&gt;&gt; </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>

  284. 

  285. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># Before the PDT -&gt; PST transition</span>

  286. <span class="gp">&gt;&gt;&gt; </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>

  287. <span class="go">2020-11-01 01:00:00-07:00</span>

  288. 

  289. <span class="gp">&gt;&gt;&gt; </span><span class="c1"># After the PDT -&gt; PST transition</span>

  290. <span class="gp">&gt;&gt;&gt; </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>

  291. <span class="go">2020-11-01 01:00:00-08:00</span>

  292. </pre></div>

  293. </div>

  294. </section>

  295. <section id="data-sources">

  296. <h2>Data sources<a class="headerlink" href="#data-sources" title="Link to this heading">¶</a></h2>

  297. <p>The <code class="docutils literal notranslate"><span class="pre">zoneinfo</span></code> module does not directly provide time zone data, and instead

  298. pulls time zone information from the system time zone database or the

  299. first-party PyPI package <a class="reference external" href="https://pypi.org/project/tzdata/">tzdata</a>, if available. Some systems, including

  300. notably Windows systems, do not have an IANA database available, and so for

  301. projects targeting cross-platform compatibility that require time zone data, it

  302. is recommended to declare a dependency on tzdata. If neither system data nor

  303. tzdata 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 raise

  304. <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>

  305. <section id="configuring-the-data-sources">

  306. <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>

  307. <p>When <code class="docutils literal notranslate"><span class="pre">ZoneInfo(key)</span></code> is called, the constructor first searches the

  308. directories 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 on

  309. failure looks for a match in the tzdata package. This behavior can be

  310. configured in three ways:</p>

  311. <ol class="arabic simple">

  312. <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 at

  313. <a class="reference internal" href="#zoneinfo-data-compile-time-config"><span class="std std-ref">compile time</span></a>.</p></li>

  314. <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>

  315. <li><p>At <a class="reference internal" href="#zoneinfo-data-runtime-config"><span class="std std-ref">runtime</span></a>, the search path can be

  316. manipulated 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>

  317. </ol>

  318. <section id="compile-time-configuration">

  319. <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>

  320. <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 the

  321. time zone database (except on Windows, where there are no “well-known”

  322. locations for time zone data). On POSIX systems, downstream distributors and

  323. those building Python from source who know where their system

  324. time zone data is deployed may change the default time zone path by specifying

  325. the 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>

  326. <span class="pre">flag</span> <span class="pre">--with-tzpath</span></code></a>), which should be a string delimited by

  327. <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>

  328. <p>On all platforms, the configured value is available as the <code class="docutils literal notranslate"><span class="pre">TZPATH</span></code> key in

  329. <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>

  330. </section>

  331. <section id="environment-configuration">

  332. <span id="zoneinfo-data-environment-var"></span><h4>Environment configuration<a class="headerlink" href="#environment-configuration" title="Link to this heading">¶</a></h4>

  333. <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 whenever

  334. <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 will

  335. use the environment variable <code class="docutils literal notranslate"><span class="pre">PYTHONTZPATH</span></code>, if it exists, to set the search

  336. path.</p>

  337. <dl class="std envvar">

  338. <dt class="sig sig-object std" id="envvar-PYTHONTZPATH">

  339. <span class="sig-name descname"><span class="pre">PYTHONTZPATH</span></span><a class="headerlink" href="#envvar-PYTHONTZPATH" title="Link to this definition">¶</a></dt>

  340. <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 zone

  341. search path to use. It must consist of only absolute rather than relative

  342. paths. Relative components specified in <code class="docutils literal notranslate"><span class="pre">PYTHONTZPATH</span></code> will not be used,

  343. but otherwise the behavior when a relative path is specified is

  344. implementation-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>, but

  345. other implementations are free to silently ignore the erroneous component

  346. or raise an exception.</p>

  347. </dd></dl>

  348. 

  349. <p>To set the system to ignore the system data and use the tzdata package

  350. instead, set <code class="docutils literal notranslate"><span class="pre">PYTHONTZPATH=&quot;&quot;</span></code>.</p>

  351. </section>

  352. <section id="runtime-configuration">

  353. <span id="zoneinfo-data-runtime-config"></span><h4>Runtime configuration<a class="headerlink" href="#runtime-configuration" title="Link to this heading">¶</a></h4>

  354. <p>The TZ search path can also be configured at runtime using the

  355. <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,

  356. though it is reasonable to use it in test functions that require the use of a

  357. specific time zone path (or require disabling access to the system time zones).</p>

  358. </section>

  359. </section>

  360. </section>

  361. <section id="the-zoneinfo-class">

  362. <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>

  363. <dl class="py class">

  364. <dt class="sig sig-object py" id="zoneinfo.ZoneInfo">

  365. <em class="property"><span class="pre">class</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>

  366. <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 time

  367. zone specified by the string <code class="docutils literal notranslate"><span class="pre">key</span></code>. Calls to the primary constructor will

  368. always return objects that compare identically; put another way, barring

  369. cache 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 of

  370. <code class="docutils literal notranslate"><span class="pre">key</span></code>, the following assertion will always be true:</p>

  371. <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>

  372. <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>

  373. <span class="k">assert</span> <span class="n">a</span> <span class="ow">is</span> <span class="n">b</span>

  374. </pre></div>

  375. </div>

  376. <p><code class="docutils literal notranslate"><span class="pre">key</span></code> must be in the form of a relative, normalized POSIX path, with no

  377. up-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 a

  378. non-conforming key is passed.</p>

  379. <p>If no file matching <code class="docutils literal notranslate"><span class="pre">key</span></code> is found, the constructor will raise

  380. <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>

  381. </dd></dl>

  382. 

  383. <p>The <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class has two alternate constructors:</p>

  384. <dl class="py method">

  385. <dt class="sig sig-object py" id="zoneinfo.ZoneInfo.from_file">

  386. <em class="property"><span class="pre">classmethod</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">fobj</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">/</span></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>

  387. <dd><p>Constructs a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> object from a file-like object returning bytes

  388. (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).

  389. Unlike the primary constructor, this always constructs a new object.</p>

  390. <p>The <code class="docutils literal notranslate"><span class="pre">key</span></code> parameter sets the name of the zone for the purposes of

  391. <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>

  392. <p>Objects created via this constructor cannot be pickled (see <a class="reference internal" href="#pickling">pickling</a>).</p>

  393. </dd></dl>

  394. 

  395. <dl class="py method">

  396. <dt class="sig sig-object py" id="zoneinfo.ZoneInfo.no_cache">

  397. <em class="property"><span class="pre">classmethod</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>

  398. <dd><p>An alternate constructor that bypasses the constructor’s cache. It is

  399. identical to the primary constructor, but returns a new object on each

  400. call. This is most likely to be useful for testing or demonstration

  401. purposes, but it can also be used to create a system with a different cache

  402. invalidation strategy.</p>

  403. <p>Objects created via this constructor will also bypass the cache of a

  404. deserializing process when unpickled.</p>

  405. <div class="admonition caution">

  406. <p class="admonition-title">Caution</p>

  407. <p>Using this constructor may change the semantics of your datetimes in

  408. surprising ways, only use it if you know that you need to.</p>

  409. </div>

  410. </dd></dl>

  411. 

  412. <p>The following class methods are also available:</p>

  413. <dl class="py method">

  414. <dt class="sig sig-object py" id="zoneinfo.ZoneInfo.clear_cache">

  415. <em class="property"><span class="pre">classmethod</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="o"><span class="pre">*</span></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>

  416. <dd><p>A method for invalidating the cache on the <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class. If no

  417. arguments are passed, all caches are invalidated and the next call to

  418. the primary constructor for each key will return a new instance.</p>

  419. <p>If an iterable of key names is passed to the <code class="docutils literal notranslate"><span class="pre">only_keys</span></code> parameter, only

  420. the specified keys will be removed from the cache. Keys passed to

  421. <code class="docutils literal notranslate"><span class="pre">only_keys</span></code> but not found in the cache are ignored.</p>

  422. <div class="admonition warning">

  423. <p class="admonition-title">Warning</p>

  424. <p>Invoking this function may change the semantics of datetimes using

  425. <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> in surprising ways; this modifies module state

  426. and thus may have wide-ranging effects. Only use it if you know that you

  427. need to.</p>

  428. </div>

  429. </dd></dl>

  430. 

  431. <p>The class has one attribute:</p>

  432. <dl class="py attribute">

  433. <dt class="sig sig-object py" id="zoneinfo.ZoneInfo.key">

  434. <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>

  435. <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>

  436. passed to the constructor, which should be a lookup key in the IANA time

  437. zone 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> or

  438. <code class="docutils literal notranslate"><span class="pre">Asia/Tokyo</span></code>).</p>

  439. <p>For zones constructed from file without specifying a <code class="docutils literal notranslate"><span class="pre">key</span></code> parameter,

  440. this will be set to <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>

  441. <div class="admonition note">

  442. <p class="admonition-title">Note</p>

  443. <p>Although it is a somewhat common practice to expose these to end users,

  444. these values are designed to be primary keys for representing the

  445. relevant zones and not necessarily user-facing elements.  Projects like

  446. CLDR (the Unicode Common Locale Data Repository) can be used to get

  447. more user-friendly strings from these keys.</p>

  448. </div>

  449. </dd></dl>

  450. 

  451. <section id="string-representations">

  452. <h3>String representations<a class="headerlink" href="#string-representations" title="Link to this heading">¶</a></h3>

  453. <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 a

  454. <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 (see

  455. the note on usage in the attribute documentation):</p>

  456. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">zone</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="s2">&quot;Pacific/Kwajalein&quot;</span><span class="p">)</span>

  457. <span class="gp">&gt;&gt;&gt; </span><span class="nb">str</span><span class="p">(</span><span class="n">zone</span><span class="p">)</span>

  458. <span class="go">&#39;Pacific/Kwajalein&#39;</span>

  459. 

  460. <span class="gp">&gt;&gt;&gt; </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>

  461. <span class="gp">&gt;&gt;&gt; </span><span class="sa">f</span><span class="s2">&quot;</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">]&quot;</span>

  462. <span class="go">&#39;2020-04-01T03:15:00+12:00 [Pacific/Kwajalein]&#39;</span>

  463. </pre></div>

  464. </div>

  465. <p>For objects constructed from a file without specifying a <code class="docutils literal notranslate"><span class="pre">key</span></code> parameter,

  466. <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> is

  467. implementation-defined and not necessarily stable between versions, but it is

  468. guaranteed not to be a valid <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> key.</p>

  469. </section>

  470. <section id="pickle-serialization">

  471. <span id="pickling"></span><h3>Pickle serialization<a class="headerlink" href="#pickle-serialization" title="Link to this heading">¶</a></h3>

  472. <p>Rather than serializing all transition data, <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> objects are

  473. serialized by key, and <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> objects constructed from files (even those

  474. with a value for <code class="docutils literal notranslate"><span class="pre">key</span></code> specified) cannot be pickled.</p>

  475. <p>The behavior of a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> file depends on how it was constructed:</p>

  476. <ol class="arabic">

  477. <li><p><code class="docutils literal notranslate"><span class="pre">ZoneInfo(key)</span></code>: When constructed with the primary constructor, a

  478. <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> object is serialized by key, and when deserialized, the

  479. deserializing process uses the primary and thus it is expected that these

  480. are expected to be the same object as other references to the same time

  481. zone.  For example, if <code class="docutils literal notranslate"><span class="pre">europe_berlin_pkl</span></code> is a string containing a pickle

  482. constructed from <code class="docutils literal notranslate"><span class="pre">ZoneInfo(&quot;Europe/Berlin&quot;)</span></code>, one would expect the

  483. following behavior:</p>

  484. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="s2">&quot;Europe/Berlin&quot;</span><span class="p">)</span>

  485. <span class="gp">&gt;&gt;&gt; </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>

  486. <span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="ow">is</span> <span class="n">b</span>

  487. <span class="go">True</span>

  488. </pre></div>

  489. </div>

  490. </li>

  491. <li><p><code class="docutils literal notranslate"><span class="pre">ZoneInfo.no_cache(key)</span></code>: When constructed from the cache-bypassing

  492. constructor, the <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> object is also serialized by key, but when

  493. deserialized, the deserializing process uses the cache bypassing

  494. constructor. If <code class="docutils literal notranslate"><span class="pre">europe_berlin_pkl_nc</span></code> is a string containing a pickle

  495. constructed from <code class="docutils literal notranslate"><span class="pre">ZoneInfo.no_cache(&quot;Europe/Berlin&quot;)</span></code>, one would expect

  496. the following behavior:</p>

  497. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="o">=</span> <span class="n">ZoneInfo</span><span class="p">(</span><span class="s2">&quot;Europe/Berlin&quot;</span><span class="p">)</span>

  498. <span class="gp">&gt;&gt;&gt; </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>

  499. <span class="gp">&gt;&gt;&gt; </span><span class="n">a</span> <span class="ow">is</span> <span class="n">b</span>

  500. <span class="go">False</span>

  501. </pre></div>

  502. </div>

  503. </li>

  504. <li><p><code class="docutils literal notranslate"><span class="pre">ZoneInfo.from_file(fobj,</span> <span class="pre">/,</span> <span class="pre">key=None)</span></code>: When constructed from a file, the

  505. <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> object raises an exception on pickling. If an end user wants to

  506. pickle a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> constructed from a file, it is recommended that they

  507. use a wrapper type or a custom serialization function: either serializing by

  508. key or storing the contents of the file object and serializing that.</p></li>

  509. </ol>

  510. <p>This method of serialization requires that the time zone data for the required

  511. key be available on both the serializing and deserializing side, similar to the

  512. way that references to classes and functions are expected to exist in both the

  513. serializing and deserializing environments. It also means that no guarantees

  514. are made about the consistency of results when unpickling a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code>

  515. pickled in an environment with a different version of the time zone data.</p>

  516. </section>

  517. </section>

  518. <section id="functions">

  519. <h2>Functions<a class="headerlink" href="#functions" title="Link to this heading">¶</a></h2>

  520. <dl class="py function">

  521. <dt class="sig sig-object py" id="zoneinfo.available_timezones">

  522. <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>

  523. <dd><p>Get a set containing all the valid keys for IANA time zones available

  524. anywhere on the time zone path. This is recalculated on every call to the

  525. function.</p>

  526. <p>This function only includes canonical zone names and does not include

  527. “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>

  528. directories, or the <code class="docutils literal notranslate"><span class="pre">posixrules</span></code> zone.</p>

  529. <div class="admonition caution">

  530. <p class="admonition-title">Caution</p>

  531. <p>This function may open a large number of files, as the best way to

  532. determine if a file on the time zone path is a valid time zone is to

  533. read the “magic string” at the beginning.</p>

  534. </div>

  535. <div class="admonition note">

  536. <p class="admonition-title">Note</p>

  537. <p>These values are not designed to be exposed to end-users; for user

  538. facing elements, applications should use something like CLDR (the

  539. Unicode Common Locale Data Repository) to get more user-friendly

  540. strings. 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>

  541. </div>

  542. </dd></dl>

  543. 

  544. <dl class="py function">

  545. <dt class="sig sig-object py" id="zoneinfo.reset_tzpath">

  546. <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>

  547. <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.

  548. When called with no arguments, <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> is set to the default value.</p>

  549. <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,

  550. and so calls to the primary <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> constructor will only use the new

  551. <code class="docutils literal notranslate"><span class="pre">TZPATH</span></code> in the case of a cache miss.</p>

  552. <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 or

  553. <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.

  554. <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 path

  555. is passed.</p>

  556. </dd></dl>

  557. 

  558. </section>

  559. <section id="globals">

  560. <h2>Globals<a class="headerlink" href="#globals" title="Link to this heading">¶</a></h2>

  561. <dl class="py data">

  562. <dt class="sig sig-object py" id="zoneinfo.TZPATH">

  563. <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>

  564. <dd><p>A read-only sequence representing the time zone search path – when

  565. constructing a <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> from a key, the key is joined to each entry in

  566. the <code class="docutils literal notranslate"><span class="pre">TZPATH</span></code>, and the first file found is used.</p>

  567. <p><code class="docutils literal notranslate"><span class="pre">TZPATH</span></code> may contain only absolute paths, never relative paths,

  568. regardless of how it is configured.</p>

  569. <p>The object that <code class="docutils literal notranslate"><span class="pre">zoneinfo.TZPATH</span></code> points to may change in response to a

  570. call 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 use

  571. <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> or

  572. assigning a long-lived variable to <code class="docutils literal notranslate"><span class="pre">zoneinfo.TZPATH</span></code>.</p>

  573. <p>For more information on configuring the time zone search path, see

  574. <a class="reference internal" href="#zoneinfo-data-configuration"><span class="std std-ref">Configuring the data sources</span></a>.</p>

  575. </dd></dl>

  576. 

  577. </section>

  578. <section id="exceptions-and-warnings">

  579. <h2>Exceptions and warnings<a class="headerlink" href="#exceptions-and-warnings" title="Link to this heading">¶</a></h2>

  580. <dl class="py exception">

  581. <dt class="sig sig-object py" id="zoneinfo.ZoneInfoNotFoundError">

  582. <em class="property"><span class="pre">exception</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>

  583. <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 the

  584. specified key could not be found on the system. This is a subclass of

  585. <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>

  586. </dd></dl>

  587. 

  588. <dl class="py exception">

  589. <dt class="sig sig-object py" id="zoneinfo.InvalidTZPathWarning">

  590. <em class="property"><span class="pre">exception</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>

  591. <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 will

  592. be filtered out, such as a relative path.</p>

  593. </dd></dl>

  594. 

  595. </section>

  596. </section>

  597. 

  598. 

  599.             <div class="clearer"></div>

  600.           </div>

  601.         </div>

  602.       </div>

  603.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  604.         <div class="sphinxsidebarwrapper">

  605.   <div>

  606.     <h3><a href="../contents.html">Table of Contents</a></h3>

  607.     <ul>

  608. <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>

  609. <li><a class="reference internal" href="#using-zoneinfo">Using <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code></a></li>

  610. <li><a class="reference internal" href="#data-sources">Data sources</a><ul>

  611. <li><a class="reference internal" href="#configuring-the-data-sources">Configuring the data sources</a><ul>

  612. <li><a class="reference internal" href="#compile-time-configuration">Compile-time configuration</a></li>

  613. <li><a class="reference internal" href="#environment-configuration">Environment configuration</a></li>

  614. <li><a class="reference internal" href="#runtime-configuration">Runtime configuration</a></li>

  615. </ul>

  616. </li>

  617. </ul>

  618. </li>

  619. <li><a class="reference internal" href="#the-zoneinfo-class">The <code class="docutils literal notranslate"><span class="pre">ZoneInfo</span></code> class</a><ul>

  620. <li><a class="reference internal" href="#string-representations">String representations</a></li>

  621. <li><a class="reference internal" href="#pickle-serialization">Pickle serialization</a></li>

  622. </ul>

  623. </li>

  624. <li><a class="reference internal" href="#functions">Functions</a></li>

  625. <li><a class="reference internal" href="#globals">Globals</a></li>

  626. <li><a class="reference internal" href="#exceptions-and-warnings">Exceptions and warnings</a></li>

  627. </ul>

  628. </li>

  629. </ul>

  630. 

  631.   </div>

  632.   <div>

  633.     <h4>Previous topic</h4>

  634.     <p class="topless"><a href="datetime.html"

  635.                           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>

  636.   </div>

  637.   <div>

  638.     <h4>Next topic</h4>

  639.     <p class="topless"><a href="calendar.html"

  640.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">calendar</span></code> — General calendar-related functions</a></p>

  641.   </div>

  642.   <div role="note" aria-label="source link">

  643.     <h3>This Page</h3>

  644.     <ul class="this-page-menu">

  645.       <li><a href="../bugs.html">Report a Bug</a></li>

  646.       <li>

  647.         <a href="https://github.com/python/cpython/blob/main/Doc/library/zoneinfo.rst"

  648.             rel="nofollow">Show Source

  649.         </a>

  650.       </li>

  651.     </ul>

  652.   </div>

  653.         </div>

  654. <div id="sidebarbutton" title="Collapse sidebar">

  655. <span>«</span>

  656. </div>

  657. 

  658.       </div>

  659.       <div class="clearer"></div>

  660.     </div>  

  661.     <div class="related" role="navigation" aria-label="related navigation">

  662.       <h3>Navigation</h3>

  663.       <ul>

  664.         <li class="right" style="margin-right: 10px">

  665.           <a href="../genindex.html" title="General Index"

  666.              >index</a></li>

  667.         <li class="right" >

  668.           <a href="../py-modindex.html" title="Python Module Index"

  669.              >modules</a> |</li>

  670.         <li class="right" >

  671.           <a href="calendar.html" title="calendar — General calendar-related functions"

  672.              >next</a> |</li>

  673.         <li class="right" >

  674.           <a href="datetime.html" title="datetime — Basic date and time types"

  675.              >previous</a> |</li>

  676. 

  677.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  678.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  679.           <li class="switchers">

  680.             <div class="language_switcher_placeholder"></div>

  681.             <div class="version_switcher_placeholder"></div>

  682.           </li>

  683.           <li>

  684.               

  685.           </li>

  686.     <li id="cpython-language-and-version">

  687.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  688.     </li>

  689. 

  690.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  691.           <li class="nav-item nav-item-2"><a href="datatypes.html" >Data Types</a> &#187;</li>

  692.         <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>

  693.                 <li class="right">

  694.                     

  695. 

  696.     <div class="inline-search" role="search">

  697.         <form class="inline-search" action="../search.html" method="get">

  698.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  699.           <input type="submit" value="Go" />

  700.         </form>

  701.     </div>

  702.                      |

  703.                 </li>

  704.             <li class="right">

  705. <label class="theme-selector-label">

  706.     Theme

  707.     <select class="theme-selector" oninput="activateTheme(this.value)">

  708.         <option value="auto" selected>Auto</option>

  709.         <option value="light">Light</option>

  710.         <option value="dark">Dark</option>

  711.     </select>

  712. </label> |</li>

  713.             

  714.       </ul>

  715.     </div>  

  716.     <div class="footer">

  717.     &copy; 

  718.       <a href="../copyright.html">

  719.     

  720.     Copyright

  721.     

  722.       </a>

  723.      2001-2024, Python Software Foundation.

  724.     <br />

  725.     This page is licensed under the Python Software Foundation License Version 2.

  726.     <br />

  727.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  728.     <br />

  729.     

  730.       See <a href="/license.html">History and License</a> for more information.<br />

  731.     

  732.     

  733.     <br />

  734. 

  735.     The Python Software Foundation is a non-profit corporation.

  736. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  737. <br />

  738.     <br />

  739.       Last updated on Apr 09, 2024 (13:47 UTC).

  740.     

  741.       <a href="/bugs.html">Found a bug</a>?

  742.     

  743.     <br />

  744. 

  745.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  746.     </div>

  747. 

  748.   </body>

  749. </html>
上海开阖软件有限公司 沪ICP备12045867号-1