gavindiaz/mt5cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
29a3ddd8b73ebeb22fe01dcc189c36126e4fa905
mt5cli/api/converters/index.html
T
dceoy 29a3ddd8b7 deploy: efc0de230a
2026-07-03 16:04:05 +00:00

1576 lines
86 KiB
HTML
Raw Blame History

<!DOCTYPE html>
<html lang="en" data-bs-theme="light">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="author" content="dceoy">
<link rel="canonical" href="https://github.com/dceoy/mt5cli/api/converters/">
<link rel="shortcut icon" href="../../img/favicon.ico">
<title>Converters - mt5cli API Documentation</title>
<link href="../../css/bootstrap.min.css" rel="stylesheet">
<link href="../../css/fontawesome.min.css" rel="stylesheet">
<link href="../../css/brands.min.css" rel="stylesheet">
<link href="../../css/solid.min.css" rel="stylesheet">
<link href="../../css/v4-font-face.min.css" rel="stylesheet">
<link href="../../css/base.css" rel="stylesheet">
<link id="hljs-light" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github.min.css" >
<link id="hljs-dark" rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/styles/github-dark.min.css" disabled>
<link href="../../assets/_mkdocstrings.css" rel="stylesheet">
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.8.0/highlight.min.js"></script>
<script>hljs.highlightAll();</script>
</head>
<body>
<div class="navbar fixed-top navbar-expand-lg navbar-dark bg-primary">
<div class="container">
<a class="navbar-brand" href="../..">mt5cli API Documentation</a>
<!-- Expander button -->
<button type="button" class="navbar-toggler" data-bs-toggle="collapse" data-bs-target="#navbar-collapse" aria-controls="navbar-collapse" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<!-- Expanded navigation -->
<div id="navbar-collapse" class="navbar-collapse collapse">
<!-- Main navigation -->
<ul class="nav navbar-nav">
<li class="nav-item">
<a href="../.." class="nav-link">Home</a>
</li>
<li class="nav-item dropdown">
<a href="#" class="nav-link dropdown-toggle active" aria-current="page" role="button" data-bs-toggle="dropdown" aria-expanded="false">API Reference</a>
<ul class="dropdown-menu">
<li>
<a href="../" class="dropdown-item">Overview</a>
</li>
<li>
<a href="../public-contract/" class="dropdown-item">Public API Contract</a>
</li>
<li>
<a href="../client/" class="dropdown-item">Client</a>
</li>
<li>
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="./" class="dropdown-item active" aria-current="page">Converters</a>
</li>
<li>
<a href="../exceptions/" class="dropdown-item">Exceptions</a>
</li>
<li>
<a href="../cli/" class="dropdown-item">CLI</a>
</li>
<li>
<a href="../sdk/" class="dropdown-item">SDK</a>
</li>
<li>
<a href="../trading/" class="dropdown-item">Trading</a>
</li>
<li>
<a href="../history/" class="dropdown-item">History Collection (SQLite)</a>
</li>
<li>
<a href="../telemetry/" class="dropdown-item">Telemetry</a>
</li>
<li>
<a href="../grafana/" class="dropdown-item">Grafana</a>
</li>
<li>
<a href="../utils/" class="dropdown-item">Utils</a>
</li>
</ul>
</li>
</ul>
<ul class="nav navbar-nav ms-md-auto">
<li class="nav-item">
<a href="#" class="nav-link" data-bs-toggle="modal" data-bs-target="#mkdocs_search_modal">
<i class="fa fa-search"></i> Search
</a>
</li>
<li class="nav-item">
<a rel="prev" href="../schemas/" class="nav-link">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
<li class="nav-item">
<a rel="next" href="../exceptions/" class="nav-link">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
<li class="nav-item">
<a href="https://github.com/dceoy/mt5cli/edit/master/docs/api/converters.md" class="nav-link">Edit on dceoy/mt5cli
</a>
</li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-3"><div class="navbar-expand-md bs-sidebar hidden-print affix" role="complementary">
<div class="navbar-header">
<button type="button" class="navbar-toggler collapsed" data-bs-toggle="collapse" data-bs-target="#toc-collapse" title="Table of Contents">
<span class="fa fa-angle-down"></span>
</button>
</div>
<div id="toc-collapse" class="navbar-collapse collapse card bg-body-tertiary">
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="1"><a href="#converters" class="nav-link">Converters</a>
<ul class="nav flex-column">
<li class="nav-item" data-bs-level="2"><a href="#mt5cli.converters" class="nav-link">converters</a>
<ul class="nav flex-column">
</ul>
</li>
</ul>
</li>
</ul>
</div>
</div></div>
<div class="col-md-9" role="main">
<h1 id="converters">Converters<a class="headerlink" href="#converters" title="Permanent link">&para;</a></h1>
<div class="doc doc-object doc-module">
<h2 id="mt5cli.converters" class="doc doc-heading">
<span class="doc doc-object-name doc-module-name">mt5cli.converters</span>
<a href="#mt5cli.converters" class="headerlink" title="Permanent link">&para;</a></h2>
<div class="doc doc-contents first">
<p>Shared conversion helpers for MT5 symbols, timeframes, and date ranges.</p>
<div class="doc doc-children">
<div class="doc doc-object doc-attribute">
<h3 id="mt5cli.converters.__all__" class="doc doc-heading">
<span class="doc doc-object-name doc-attribute-name">__all__</span>
<span class="doc doc-labels">
<small class="doc doc-label doc-label-module-attribute"><code>module-attribute</code></small>
</span>
<a href="#mt5cli.converters.__all__" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="n">__all__</span> <span class="o">=</span> <span class="p">[</span>
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> <span class="s2">&quot;ensure_utc&quot;</span><span class="p">,</span>
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> <span class="s2">&quot;granularity_name&quot;</span><span class="p">,</span>
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a> <span class="s2">&quot;normalize_symbol&quot;</span><span class="p">,</span>
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> <span class="s2">&quot;normalize_symbols&quot;</span><span class="p">,</span>
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> <span class="s2">&quot;parse_date_range&quot;</span><span class="p">,</span>
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> <span class="s2">&quot;parse_datetime&quot;</span><span class="p">,</span>
<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a> <span class="s2">&quot;parse_tick_flags&quot;</span><span class="p">,</span>
<a id="__codelineno-0-9" name="__codelineno-0-9" href="#__codelineno-0-9"></a> <span class="s2">&quot;parse_timeframe&quot;</span><span class="p">,</span>
<a id="__codelineno-0-10" name="__codelineno-0-10" href="#__codelineno-0-10"></a> <span class="s2">&quot;recent_window&quot;</span><span class="p">,</span>
<a id="__codelineno-0-11" name="__codelineno-0-11" href="#__codelineno-0-11"></a><span class="p">]</span>
</code></pre></div>
<div class="doc doc-contents ">
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.ensure_utc" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">ensure_utc</span>
<a href="#mt5cli.converters.ensure_utc" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">ensure_utc</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="n"><span title="datetime.datetime">datetime</span></span> <span class="o">|</span> <span class="n"><span title="str">str</span></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="datetime.datetime">datetime</span></span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Return a timezone-aware UTC datetime.</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>value</code>
</td>
<td>
<code><span title="datetime.datetime">datetime</span> | <span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Datetime instance or ISO 8601 string.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="datetime.datetime">datetime</span></code>
</td>
<td>
<div class="doc-md-description">
<p>UTC-aware datetime.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/converters.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-69">69</a></span>
<span class="normal"><a href="#__codelineno-0-70">70</a></span>
<span class="normal"><a href="#__codelineno-0-71">71</a></span>
<span class="normal"><a href="#__codelineno-0-72">72</a></span>
<span class="normal"><a href="#__codelineno-0-73">73</a></span>
<span class="normal"><a href="#__codelineno-0-74">74</a></span>
<span class="normal"><a href="#__codelineno-0-75">75</a></span>
<span class="normal"><a href="#__codelineno-0-76">76</a></span>
<span class="normal"><a href="#__codelineno-0-77">77</a></span>
<span class="normal"><a href="#__codelineno-0-78">78</a></span>
<span class="normal"><a href="#__codelineno-0-79">79</a></span>
<span class="normal"><a href="#__codelineno-0-80">80</a></span>
<span class="normal"><a href="#__codelineno-0-81">81</a></span>
<span class="normal"><a href="#__codelineno-0-82">82</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-69" name="__codelineno-0-69"></a><span class="k">def</span><span class="w"> </span><span class="nf">ensure_utc</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="n">datetime</span> <span class="o">|</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">datetime</span><span class="p">:</span>
<a id="__codelineno-0-70" name="__codelineno-0-70"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Return a timezone-aware UTC datetime.</span>
<a id="__codelineno-0-71" name="__codelineno-0-71"></a>
<a id="__codelineno-0-72" name="__codelineno-0-72"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-73" name="__codelineno-0-73"></a><span class="sd"> value: Datetime instance or ISO 8601 string.</span>
<a id="__codelineno-0-74" name="__codelineno-0-74"></a>
<a id="__codelineno-0-75" name="__codelineno-0-75"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-76" name="__codelineno-0-76"></a><span class="sd"> UTC-aware datetime.</span>
<a id="__codelineno-0-77" name="__codelineno-0-77"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-78" name="__codelineno-0-78"></a> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">str</span><span class="p">):</span>
<a id="__codelineno-0-79" name="__codelineno-0-79"></a> <span class="k">return</span> <span class="n">parse_datetime</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<a id="__codelineno-0-80" name="__codelineno-0-80"></a> <span class="k">if</span> <span class="n">value</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<a id="__codelineno-0-81" name="__codelineno-0-81"></a> <span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="n">UTC</span><span class="p">)</span>
<a id="__codelineno-0-82" name="__codelineno-0-82"></a> <span class="k">return</span> <span class="n">value</span><span class="o">.</span><span class="n">astimezone</span><span class="p">(</span><span class="n">UTC</span><span class="p">)</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.granularity_name" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">granularity_name</span>
<a href="#mt5cli.converters.granularity_name" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">granularity_name</span><span class="p">(</span><span class="n">timeframe</span><span class="p">:</span> <span class="n"><span title="int">int</span></span> <span class="o">|</span> <span class="n"><span title="str">str</span></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="str">str</span></span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Return a short granularity label for a timeframe integer or name.</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>timeframe</code>
</td>
<td>
<code><span title="int">int</span> | <span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>MT5 timeframe as integer or name (for example <code>M1</code>).</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Short name such as <code>M1</code> or the stringified integer when unknown.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/converters.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-148">148</a></span>
<span class="normal"><a href="#__codelineno-0-149">149</a></span>
<span class="normal"><a href="#__codelineno-0-150">150</a></span>
<span class="normal"><a href="#__codelineno-0-151">151</a></span>
<span class="normal"><a href="#__codelineno-0-152">152</a></span>
<span class="normal"><a href="#__codelineno-0-153">153</a></span>
<span class="normal"><a href="#__codelineno-0-154">154</a></span>
<span class="normal"><a href="#__codelineno-0-155">155</a></span>
<span class="normal"><a href="#__codelineno-0-156">156</a></span>
<span class="normal"><a href="#__codelineno-0-157">157</a></span>
<span class="normal"><a href="#__codelineno-0-158">158</a></span>
<span class="normal"><a href="#__codelineno-0-159">159</a></span>
<span class="normal"><a href="#__codelineno-0-160">160</a></span>
<span class="normal"><a href="#__codelineno-0-161">161</a></span>
<span class="normal"><a href="#__codelineno-0-162">162</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-148" name="__codelineno-0-148"></a><span class="k">def</span><span class="w"> </span><span class="nf">granularity_name</span><span class="p">(</span><span class="n">timeframe</span><span class="p">:</span> <span class="nb">int</span> <span class="o">|</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
<a id="__codelineno-0-149" name="__codelineno-0-149"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Return a short granularity label for a timeframe integer or name.</span>
<a id="__codelineno-0-150" name="__codelineno-0-150"></a>
<a id="__codelineno-0-151" name="__codelineno-0-151"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-152" name="__codelineno-0-152"></a><span class="sd"> timeframe: MT5 timeframe as integer or name (for example ``M1``).</span>
<a id="__codelineno-0-153" name="__codelineno-0-153"></a>
<a id="__codelineno-0-154" name="__codelineno-0-154"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-155" name="__codelineno-0-155"></a><span class="sd"> Short name such as ``M1`` or the stringified integer when unknown.</span>
<a id="__codelineno-0-156" name="__codelineno-0-156"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-157" name="__codelineno-0-157"></a> <span class="n">tf</span> <span class="o">=</span> <span class="n">parse_timeframe</span><span class="p">(</span><span class="n">timeframe</span><span class="p">)</span>
<a id="__codelineno-0-158" name="__codelineno-0-158"></a> <span class="k">try</span><span class="p">:</span>
<a id="__codelineno-0-159" name="__codelineno-0-159"></a> <span class="n">name</span> <span class="o">=</span> <span class="n">_get_timeframe_name</span><span class="p">(</span><span class="n">tf</span><span class="p">)</span>
<a id="__codelineno-0-160" name="__codelineno-0-160"></a> <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<a id="__codelineno-0-161" name="__codelineno-0-161"></a> <span class="k">return</span> <span class="nb">str</span><span class="p">(</span><span class="n">tf</span><span class="p">)</span>
<a id="__codelineno-0-162" name="__codelineno-0-162"></a> <span class="k">return</span> <span class="n">name</span><span class="o">.</span><span class="n">removeprefix</span><span class="p">(</span><span class="s2">&quot;TIMEFRAME_&quot;</span><span class="p">)</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.normalize_symbol" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">normalize_symbol</span>
<a href="#mt5cli.converters.normalize_symbol" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">normalize_symbol</span><span class="p">(</span><span class="n">symbol</span><span class="p">:</span> <span class="n"><span title="str">str</span></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="str">str</span></span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Normalize a broker symbol name for MT5 API calls.</p>
<p>Strips surrounding whitespace while preserving broker-specific casing and
suffixes (for example <code>XAUUSDm</code>, <code>US500.cash</code>, or <code>EURUSD.r</code>).</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>symbol</code>
</td>
<td>
<code><span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Raw symbol name.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Normalized symbol string.</p>
</div>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Raises:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="ValueError">ValueError</span></code>
</td>
<td>
<div class="doc-md-description">
<p>If the symbol is empty after normalization.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/converters.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-28">28</a></span>
<span class="normal"><a href="#__codelineno-0-29">29</a></span>
<span class="normal"><a href="#__codelineno-0-30">30</a></span>
<span class="normal"><a href="#__codelineno-0-31">31</a></span>
<span class="normal"><a href="#__codelineno-0-32">32</a></span>
<span class="normal"><a href="#__codelineno-0-33">33</a></span>
<span class="normal"><a href="#__codelineno-0-34">34</a></span>
<span class="normal"><a href="#__codelineno-0-35">35</a></span>
<span class="normal"><a href="#__codelineno-0-36">36</a></span>
<span class="normal"><a href="#__codelineno-0-37">37</a></span>
<span class="normal"><a href="#__codelineno-0-38">38</a></span>
<span class="normal"><a href="#__codelineno-0-39">39</a></span>
<span class="normal"><a href="#__codelineno-0-40">40</a></span>
<span class="normal"><a href="#__codelineno-0-41">41</a></span>
<span class="normal"><a href="#__codelineno-0-42">42</a></span>
<span class="normal"><a href="#__codelineno-0-43">43</a></span>
<span class="normal"><a href="#__codelineno-0-44">44</a></span>
<span class="normal"><a href="#__codelineno-0-45">45</a></span>
<span class="normal"><a href="#__codelineno-0-46">46</a></span>
<span class="normal"><a href="#__codelineno-0-47">47</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-28" name="__codelineno-0-28"></a><span class="k">def</span><span class="w"> </span><span class="nf">normalize_symbol</span><span class="p">(</span><span class="n">symbol</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">str</span><span class="p">:</span>
<a id="__codelineno-0-29" name="__codelineno-0-29"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Normalize a broker symbol name for MT5 API calls.</span>
<a id="__codelineno-0-30" name="__codelineno-0-30"></a>
<a id="__codelineno-0-31" name="__codelineno-0-31"></a><span class="sd"> Strips surrounding whitespace while preserving broker-specific casing and</span>
<a id="__codelineno-0-32" name="__codelineno-0-32"></a><span class="sd"> suffixes (for example ``XAUUSDm``, ``US500.cash``, or ``EURUSD.r``).</span>
<a id="__codelineno-0-33" name="__codelineno-0-33"></a>
<a id="__codelineno-0-34" name="__codelineno-0-34"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-35" name="__codelineno-0-35"></a><span class="sd"> symbol: Raw symbol name.</span>
<a id="__codelineno-0-36" name="__codelineno-0-36"></a>
<a id="__codelineno-0-37" name="__codelineno-0-37"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-38" name="__codelineno-0-38"></a><span class="sd"> Normalized symbol string.</span>
<a id="__codelineno-0-39" name="__codelineno-0-39"></a>
<a id="__codelineno-0-40" name="__codelineno-0-40"></a><span class="sd"> Raises:</span>
<a id="__codelineno-0-41" name="__codelineno-0-41"></a><span class="sd"> ValueError: If the symbol is empty after normalization.</span>
<a id="__codelineno-0-42" name="__codelineno-0-42"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-43" name="__codelineno-0-43"></a> <span class="n">normalized</span> <span class="o">=</span> <span class="n">symbol</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span>
<a id="__codelineno-0-44" name="__codelineno-0-44"></a> <span class="k">if</span> <span class="ow">not</span> <span class="n">normalized</span><span class="p">:</span>
<a id="__codelineno-0-45" name="__codelineno-0-45"></a> <span class="n">msg</span> <span class="o">=</span> <span class="s2">&quot;Symbol must not be empty.&quot;</span>
<a id="__codelineno-0-46" name="__codelineno-0-46"></a> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
<a id="__codelineno-0-47" name="__codelineno-0-47"></a> <span class="k">return</span> <span class="n">normalized</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.normalize_symbols" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">normalize_symbols</span>
<a href="#mt5cli.converters.normalize_symbols" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">normalize_symbols</span><span class="p">(</span><span class="n">symbols</span><span class="p">:</span> <span class="n"><span title="collections.abc.Sequence">Sequence</span></span><span class="p">[</span><span class="n"><span title="str">str</span></span><span class="p">])</span> <span class="o">-&gt;</span> <span class="n"><span title="list">list</span></span><span class="p">[</span><span class="n"><span title="str">str</span></span><span class="p">]</span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Normalize a sequence of broker symbol names.</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>symbols</code>
</td>
<td>
<code><span title="collections.abc.Sequence">Sequence</span>[<span title="str">str</span>]</code>
</td>
<td>
<div class="doc-md-description">
<p>Raw symbol names.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="list">list</span>[<span title="str">str</span>]</code>
</td>
<td>
<div class="doc-md-description">
<p>List of normalized, de-duplicated symbols preserving first-seen order.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/converters.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-50">50</a></span>
<span class="normal"><a href="#__codelineno-0-51">51</a></span>
<span class="normal"><a href="#__codelineno-0-52">52</a></span>
<span class="normal"><a href="#__codelineno-0-53">53</a></span>
<span class="normal"><a href="#__codelineno-0-54">54</a></span>
<span class="normal"><a href="#__codelineno-0-55">55</a></span>
<span class="normal"><a href="#__codelineno-0-56">56</a></span>
<span class="normal"><a href="#__codelineno-0-57">57</a></span>
<span class="normal"><a href="#__codelineno-0-58">58</a></span>
<span class="normal"><a href="#__codelineno-0-59">59</a></span>
<span class="normal"><a href="#__codelineno-0-60">60</a></span>
<span class="normal"><a href="#__codelineno-0-61">61</a></span>
<span class="normal"><a href="#__codelineno-0-62">62</a></span>
<span class="normal"><a href="#__codelineno-0-63">63</a></span>
<span class="normal"><a href="#__codelineno-0-64">64</a></span>
<span class="normal"><a href="#__codelineno-0-65">65</a></span>
<span class="normal"><a href="#__codelineno-0-66">66</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-50" name="__codelineno-0-50"></a><span class="k">def</span><span class="w"> </span><span class="nf">normalize_symbols</span><span class="p">(</span><span class="n">symbols</span><span class="p">:</span> <span class="n">Sequence</span><span class="p">[</span><span class="nb">str</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]:</span>
<a id="__codelineno-0-51" name="__codelineno-0-51"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Normalize a sequence of broker symbol names.</span>
<a id="__codelineno-0-52" name="__codelineno-0-52"></a>
<a id="__codelineno-0-53" name="__codelineno-0-53"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-54" name="__codelineno-0-54"></a><span class="sd"> symbols: Raw symbol names.</span>
<a id="__codelineno-0-55" name="__codelineno-0-55"></a>
<a id="__codelineno-0-56" name="__codelineno-0-56"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-57" name="__codelineno-0-57"></a><span class="sd"> List of normalized, de-duplicated symbols preserving first-seen order.</span>
<a id="__codelineno-0-58" name="__codelineno-0-58"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-59" name="__codelineno-0-59"></a> <span class="n">seen</span><span class="p">:</span> <span class="nb">set</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="nb">set</span><span class="p">()</span>
<a id="__codelineno-0-60" name="__codelineno-0-60"></a> <span class="n">resolved</span><span class="p">:</span> <span class="nb">list</span><span class="p">[</span><span class="nb">str</span><span class="p">]</span> <span class="o">=</span> <span class="p">[]</span>
<a id="__codelineno-0-61" name="__codelineno-0-61"></a> <span class="k">for</span> <span class="n">symbol</span> <span class="ow">in</span> <span class="n">symbols</span><span class="p">:</span>
<a id="__codelineno-0-62" name="__codelineno-0-62"></a> <span class="n">normalized</span> <span class="o">=</span> <span class="n">normalize_symbol</span><span class="p">(</span><span class="n">symbol</span><span class="p">)</span>
<a id="__codelineno-0-63" name="__codelineno-0-63"></a> <span class="k">if</span> <span class="n">normalized</span> <span class="ow">not</span> <span class="ow">in</span> <span class="n">seen</span><span class="p">:</span>
<a id="__codelineno-0-64" name="__codelineno-0-64"></a> <span class="n">seen</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">normalized</span><span class="p">)</span>
<a id="__codelineno-0-65" name="__codelineno-0-65"></a> <span class="n">resolved</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">normalized</span><span class="p">)</span>
<a id="__codelineno-0-66" name="__codelineno-0-66"></a> <span class="k">return</span> <span class="n">resolved</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.parse_date_range" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">parse_date_range</span>
<a href="#mt5cli.converters.parse_date_range" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">parse_date_range</span><span class="p">(</span>
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> <span class="n">date_from</span><span class="p">:</span> <span class="n"><span title="datetime.datetime">datetime</span></span> <span class="o">|</span> <span class="n"><span title="str">str</span></span><span class="p">,</span> <span class="n">date_to</span><span class="p">:</span> <span class="n"><span title="datetime.datetime">datetime</span></span> <span class="o">|</span> <span class="n"><span title="str">str</span></span>
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="tuple">tuple</span></span><span class="p">[</span><span class="n"><span title="datetime.datetime">datetime</span></span><span class="p">,</span> <span class="n"><span title="datetime.datetime">datetime</span></span><span class="p">]</span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Parse and validate an inclusive UTC date range.</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>date_from</code>
</td>
<td>
<code><span title="datetime.datetime">datetime</span> | <span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Range start as datetime or ISO 8601 string.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>date_to</code>
</td>
<td>
<code><span title="datetime.datetime">datetime</span> | <span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Range end as datetime or ISO 8601 string.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="tuple">tuple</span>[<span title="datetime.datetime">datetime</span>, <span title="datetime.datetime">datetime</span>]</code>
</td>
<td>
<div class="doc-md-description">
<p>Tuple of UTC-aware <code>(start, end)</code> datetimes.</p>
</div>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Raises:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="ValueError">ValueError</span></code>
</td>
<td>
<div class="doc-md-description">
<p>If <code>date_from</code> is after <code>date_to</code>.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/converters.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-85"> 85</a></span>
<span class="normal"><a href="#__codelineno-0-86"> 86</a></span>
<span class="normal"><a href="#__codelineno-0-87"> 87</a></span>
<span class="normal"><a href="#__codelineno-0-88"> 88</a></span>
<span class="normal"><a href="#__codelineno-0-89"> 89</a></span>
<span class="normal"><a href="#__codelineno-0-90"> 90</a></span>
<span class="normal"><a href="#__codelineno-0-91"> 91</a></span>
<span class="normal"><a href="#__codelineno-0-92"> 92</a></span>
<span class="normal"><a href="#__codelineno-0-93"> 93</a></span>
<span class="normal"><a href="#__codelineno-0-94"> 94</a></span>
<span class="normal"><a href="#__codelineno-0-95"> 95</a></span>
<span class="normal"><a href="#__codelineno-0-96"> 96</a></span>
<span class="normal"><a href="#__codelineno-0-97"> 97</a></span>
<span class="normal"><a href="#__codelineno-0-98"> 98</a></span>
<span class="normal"><a href="#__codelineno-0-99"> 99</a></span>
<span class="normal"><a href="#__codelineno-0-100">100</a></span>
<span class="normal"><a href="#__codelineno-0-101">101</a></span>
<span class="normal"><a href="#__codelineno-0-102">102</a></span>
<span class="normal"><a href="#__codelineno-0-103">103</a></span>
<span class="normal"><a href="#__codelineno-0-104">104</a></span>
<span class="normal"><a href="#__codelineno-0-105">105</a></span>
<span class="normal"><a href="#__codelineno-0-106">106</a></span>
<span class="normal"><a href="#__codelineno-0-107">107</a></span>
<span class="normal"><a href="#__codelineno-0-108">108</a></span>
<span class="normal"><a href="#__codelineno-0-109">109</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-85" name="__codelineno-0-85"></a><span class="k">def</span><span class="w"> </span><span class="nf">parse_date_range</span><span class="p">(</span>
<a id="__codelineno-0-86" name="__codelineno-0-86"></a> <span class="n">date_from</span><span class="p">:</span> <span class="n">datetime</span> <span class="o">|</span> <span class="nb">str</span><span class="p">,</span>
<a id="__codelineno-0-87" name="__codelineno-0-87"></a> <span class="n">date_to</span><span class="p">:</span> <span class="n">datetime</span> <span class="o">|</span> <span class="nb">str</span><span class="p">,</span>
<a id="__codelineno-0-88" name="__codelineno-0-88"></a><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">tuple</span><span class="p">[</span><span class="n">datetime</span><span class="p">,</span> <span class="n">datetime</span><span class="p">]:</span>
<a id="__codelineno-0-89" name="__codelineno-0-89"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Parse and validate an inclusive UTC date range.</span>
<a id="__codelineno-0-90" name="__codelineno-0-90"></a>
<a id="__codelineno-0-91" name="__codelineno-0-91"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-92" name="__codelineno-0-92"></a><span class="sd"> date_from: Range start as datetime or ISO 8601 string.</span>
<a id="__codelineno-0-93" name="__codelineno-0-93"></a><span class="sd"> date_to: Range end as datetime or ISO 8601 string.</span>
<a id="__codelineno-0-94" name="__codelineno-0-94"></a>
<a id="__codelineno-0-95" name="__codelineno-0-95"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-96" name="__codelineno-0-96"></a><span class="sd"> Tuple of UTC-aware ``(start, end)`` datetimes.</span>
<a id="__codelineno-0-97" name="__codelineno-0-97"></a>
<a id="__codelineno-0-98" name="__codelineno-0-98"></a><span class="sd"> Raises:</span>
<a id="__codelineno-0-99" name="__codelineno-0-99"></a><span class="sd"> ValueError: If ``date_from`` is after ``date_to``.</span>
<a id="__codelineno-0-100" name="__codelineno-0-100"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-101" name="__codelineno-0-101"></a> <span class="n">start</span> <span class="o">=</span> <span class="n">ensure_utc</span><span class="p">(</span><span class="n">date_from</span><span class="p">)</span>
<a id="__codelineno-0-102" name="__codelineno-0-102"></a> <span class="n">end</span> <span class="o">=</span> <span class="n">ensure_utc</span><span class="p">(</span><span class="n">date_to</span><span class="p">)</span>
<a id="__codelineno-0-103" name="__codelineno-0-103"></a> <span class="k">if</span> <span class="n">start</span> <span class="o">&gt;</span> <span class="n">end</span><span class="p">:</span>
<a id="__codelineno-0-104" name="__codelineno-0-104"></a> <span class="n">msg</span> <span class="o">=</span> <span class="p">(</span>
<a id="__codelineno-0-105" name="__codelineno-0-105"></a> <span class="sa">f</span><span class="s2">&quot;date_from (</span><span class="si">{</span><span class="n">start</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span><span class="si">}</span><span class="s2">) must not be after &quot;</span>
<a id="__codelineno-0-106" name="__codelineno-0-106"></a> <span class="sa">f</span><span class="s2">&quot;date_to (</span><span class="si">{</span><span class="n">end</span><span class="o">.</span><span class="n">isoformat</span><span class="p">()</span><span class="si">}</span><span class="s2">).&quot;</span>
<a id="__codelineno-0-107" name="__codelineno-0-107"></a> <span class="p">)</span>
<a id="__codelineno-0-108" name="__codelineno-0-108"></a> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
<a id="__codelineno-0-109" name="__codelineno-0-109"></a> <span class="k">return</span> <span class="n">start</span><span class="p">,</span> <span class="n">end</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.parse_datetime" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">parse_datetime</span>
<a href="#mt5cli.converters.parse_datetime" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">parse_datetime</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="n"><span title="str">str</span></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="datetime.datetime">datetime</span></span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Parse an ISO 8601 datetime string to a timezone-aware datetime.</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>value</code>
</td>
<td>
<code><span title="str">str</span></code>
</td>
<td>
<div class="doc-md-description">
<p>ISO 8601 datetime string (e.g., '2024-01-01' or
'2024-01-01T12:00:00+00:00').</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="datetime.datetime">datetime</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Parsed datetime with UTC timezone if no timezone is specified.</p>
</div>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Raises:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="ValueError">ValueError</span></code>
</td>
<td>
<div class="doc-md-description">
<p>If the string cannot be parsed.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/utils.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-351">351</a></span>
<span class="normal"><a href="#__codelineno-0-352">352</a></span>
<span class="normal"><a href="#__codelineno-0-353">353</a></span>
<span class="normal"><a href="#__codelineno-0-354">354</a></span>
<span class="normal"><a href="#__codelineno-0-355">355</a></span>
<span class="normal"><a href="#__codelineno-0-356">356</a></span>
<span class="normal"><a href="#__codelineno-0-357">357</a></span>
<span class="normal"><a href="#__codelineno-0-358">358</a></span>
<span class="normal"><a href="#__codelineno-0-359">359</a></span>
<span class="normal"><a href="#__codelineno-0-360">360</a></span>
<span class="normal"><a href="#__codelineno-0-361">361</a></span>
<span class="normal"><a href="#__codelineno-0-362">362</a></span>
<span class="normal"><a href="#__codelineno-0-363">363</a></span>
<span class="normal"><a href="#__codelineno-0-364">364</a></span>
<span class="normal"><a href="#__codelineno-0-365">365</a></span>
<span class="normal"><a href="#__codelineno-0-366">366</a></span>
<span class="normal"><a href="#__codelineno-0-367">367</a></span>
<span class="normal"><a href="#__codelineno-0-368">368</a></span>
<span class="normal"><a href="#__codelineno-0-369">369</a></span>
<span class="normal"><a href="#__codelineno-0-370">370</a></span>
<span class="normal"><a href="#__codelineno-0-371">371</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-351" name="__codelineno-0-351"></a><span class="k">def</span><span class="w"> </span><span class="nf">parse_datetime</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="nb">str</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">datetime</span><span class="p">:</span>
<a id="__codelineno-0-352" name="__codelineno-0-352"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Parse an ISO 8601 datetime string to a timezone-aware datetime.</span>
<a id="__codelineno-0-353" name="__codelineno-0-353"></a>
<a id="__codelineno-0-354" name="__codelineno-0-354"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-355" name="__codelineno-0-355"></a><span class="sd"> value: ISO 8601 datetime string (e.g., &#39;2024-01-01&#39; or</span>
<a id="__codelineno-0-356" name="__codelineno-0-356"></a><span class="sd"> &#39;2024-01-01T12:00:00+00:00&#39;).</span>
<a id="__codelineno-0-357" name="__codelineno-0-357"></a>
<a id="__codelineno-0-358" name="__codelineno-0-358"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-359" name="__codelineno-0-359"></a><span class="sd"> Parsed datetime with UTC timezone if no timezone is specified.</span>
<a id="__codelineno-0-360" name="__codelineno-0-360"></a>
<a id="__codelineno-0-361" name="__codelineno-0-361"></a><span class="sd"> Raises:</span>
<a id="__codelineno-0-362" name="__codelineno-0-362"></a><span class="sd"> ValueError: If the string cannot be parsed.</span>
<a id="__codelineno-0-363" name="__codelineno-0-363"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-364" name="__codelineno-0-364"></a> <span class="k">try</span><span class="p">:</span>
<a id="__codelineno-0-365" name="__codelineno-0-365"></a> <span class="n">dt</span> <span class="o">=</span> <span class="n">datetime</span><span class="o">.</span><span class="n">fromisoformat</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<a id="__codelineno-0-366" name="__codelineno-0-366"></a> <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<a id="__codelineno-0-367" name="__codelineno-0-367"></a> <span class="n">msg</span> <span class="o">=</span> <span class="sa">f</span><span class="s2">&quot;Invalid datetime format: &#39;</span><span class="si">{</span><span class="n">value</span><span class="si">}</span><span class="s2">&#39;. Use ISO 8601 format.&quot;</span>
<a id="__codelineno-0-368" name="__codelineno-0-368"></a> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span> <span class="kn">from</span><span class="w"> </span><span class="kc">None</span>
<a id="__codelineno-0-369" name="__codelineno-0-369"></a> <span class="k">if</span> <span class="n">dt</span><span class="o">.</span><span class="n">tzinfo</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">:</span>
<a id="__codelineno-0-370" name="__codelineno-0-370"></a> <span class="n">dt</span> <span class="o">=</span> <span class="n">dt</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">tzinfo</span><span class="o">=</span><span class="n">UTC</span><span class="p">)</span>
<a id="__codelineno-0-371" name="__codelineno-0-371"></a> <span class="k">return</span> <span class="n">dt</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.parse_tick_flags" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">parse_tick_flags</span>
<a href="#mt5cli.converters.parse_tick_flags" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">parse_tick_flags</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="n"><span title="object">object</span></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="int">int</span></span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Parse tick flags string or integer value.</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>value</code>
</td>
<td>
<code><span title="object">object</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Tick flag name (ALL, INFO, TRADE, COPY_TICKS_*) or integer value.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="int">int</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Integer tick flag value compatible with MetaTrader 5 <code>COPY_TICKS_*</code>.</p>
</div>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Raises:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="ValueError">ValueError</span></code>
</td>
<td>
<div class="doc-md-description">
<p>If the flag is invalid.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/utils.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-398">398</a></span>
<span class="normal"><a href="#__codelineno-0-399">399</a></span>
<span class="normal"><a href="#__codelineno-0-400">400</a></span>
<span class="normal"><a href="#__codelineno-0-401">401</a></span>
<span class="normal"><a href="#__codelineno-0-402">402</a></span>
<span class="normal"><a href="#__codelineno-0-403">403</a></span>
<span class="normal"><a href="#__codelineno-0-404">404</a></span>
<span class="normal"><a href="#__codelineno-0-405">405</a></span>
<span class="normal"><a href="#__codelineno-0-406">406</a></span>
<span class="normal"><a href="#__codelineno-0-407">407</a></span>
<span class="normal"><a href="#__codelineno-0-408">408</a></span>
<span class="normal"><a href="#__codelineno-0-409">409</a></span>
<span class="normal"><a href="#__codelineno-0-410">410</a></span>
<span class="normal"><a href="#__codelineno-0-411">411</a></span>
<span class="normal"><a href="#__codelineno-0-412">412</a></span>
<span class="normal"><a href="#__codelineno-0-413">413</a></span>
<span class="normal"><a href="#__codelineno-0-414">414</a></span>
<span class="normal"><a href="#__codelineno-0-415">415</a></span>
<span class="normal"><a href="#__codelineno-0-416">416</a></span>
<span class="normal"><a href="#__codelineno-0-417">417</a></span>
<span class="normal"><a href="#__codelineno-0-418">418</a></span>
<span class="normal"><a href="#__codelineno-0-419">419</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-398" name="__codelineno-0-398"></a><span class="k">def</span><span class="w"> </span><span class="nf">parse_tick_flags</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="nb">object</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
<a id="__codelineno-0-399" name="__codelineno-0-399"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Parse tick flags string or integer value.</span>
<a id="__codelineno-0-400" name="__codelineno-0-400"></a>
<a id="__codelineno-0-401" name="__codelineno-0-401"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-402" name="__codelineno-0-402"></a><span class="sd"> value: Tick flag name (ALL, INFO, TRADE, COPY_TICKS_*) or integer value.</span>
<a id="__codelineno-0-403" name="__codelineno-0-403"></a>
<a id="__codelineno-0-404" name="__codelineno-0-404"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-405" name="__codelineno-0-405"></a><span class="sd"> Integer tick flag value compatible with MetaTrader 5 ``COPY_TICKS_*``.</span>
<a id="__codelineno-0-406" name="__codelineno-0-406"></a>
<a id="__codelineno-0-407" name="__codelineno-0-407"></a><span class="sd"> Raises:</span>
<a id="__codelineno-0-408" name="__codelineno-0-408"></a><span class="sd"> ValueError: If the flag is invalid.</span>
<a id="__codelineno-0-409" name="__codelineno-0-409"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-410" name="__codelineno-0-410"></a> <span class="k">try</span><span class="p">:</span>
<a id="__codelineno-0-411" name="__codelineno-0-411"></a> <span class="k">return</span> <span class="n">_parse_copy_ticks</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<a id="__codelineno-0-412" name="__codelineno-0-412"></a> <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<a id="__codelineno-0-413" name="__codelineno-0-413"></a> <span class="n">display</span> <span class="o">=</span> <span class="n">value</span> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span> <span class="k">else</span> <span class="nb">repr</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<a id="__codelineno-0-414" name="__codelineno-0-414"></a> <span class="n">valid</span> <span class="o">=</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">_TICK_FLAG_NAMES</span><span class="p">)</span>
<a id="__codelineno-0-415" name="__codelineno-0-415"></a> <span class="n">msg</span> <span class="o">=</span> <span class="p">(</span>
<a id="__codelineno-0-416" name="__codelineno-0-416"></a> <span class="sa">f</span><span class="s2">&quot;Invalid tick flags: &#39;</span><span class="si">{</span><span class="n">display</span><span class="si">}</span><span class="s2">&#39;. &quot;</span>
<a id="__codelineno-0-417" name="__codelineno-0-417"></a> <span class="sa">f</span><span class="s2">&quot;Use one of: </span><span class="si">{</span><span class="n">valid</span><span class="si">}</span><span class="s2">, or a supported integer.&quot;</span>
<a id="__codelineno-0-418" name="__codelineno-0-418"></a> <span class="p">)</span>
<a id="__codelineno-0-419" name="__codelineno-0-419"></a> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span> <span class="kn">from</span><span class="w"> </span><span class="kc">None</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.parse_timeframe" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">parse_timeframe</span>
<a href="#mt5cli.converters.parse_timeframe" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">parse_timeframe</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="n"><span title="object">object</span></span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="int">int</span></span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Parse a timeframe string or integer value.</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>value</code>
</td>
<td>
<code><span title="object">object</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Timeframe name (e.g., 'M1', 'H1', 'D1') or integer value.</p>
</div>
</td>
<td>
<em>required</em>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="int">int</span></code>
</td>
<td>
<div class="doc-md-description">
<p>Integer timeframe value.</p>
</div>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Raises:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="ValueError">ValueError</span></code>
</td>
<td>
<div class="doc-md-description">
<p>If the timeframe is invalid.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/utils.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-374">374</a></span>
<span class="normal"><a href="#__codelineno-0-375">375</a></span>
<span class="normal"><a href="#__codelineno-0-376">376</a></span>
<span class="normal"><a href="#__codelineno-0-377">377</a></span>
<span class="normal"><a href="#__codelineno-0-378">378</a></span>
<span class="normal"><a href="#__codelineno-0-379">379</a></span>
<span class="normal"><a href="#__codelineno-0-380">380</a></span>
<span class="normal"><a href="#__codelineno-0-381">381</a></span>
<span class="normal"><a href="#__codelineno-0-382">382</a></span>
<span class="normal"><a href="#__codelineno-0-383">383</a></span>
<span class="normal"><a href="#__codelineno-0-384">384</a></span>
<span class="normal"><a href="#__codelineno-0-385">385</a></span>
<span class="normal"><a href="#__codelineno-0-386">386</a></span>
<span class="normal"><a href="#__codelineno-0-387">387</a></span>
<span class="normal"><a href="#__codelineno-0-388">388</a></span>
<span class="normal"><a href="#__codelineno-0-389">389</a></span>
<span class="normal"><a href="#__codelineno-0-390">390</a></span>
<span class="normal"><a href="#__codelineno-0-391">391</a></span>
<span class="normal"><a href="#__codelineno-0-392">392</a></span>
<span class="normal"><a href="#__codelineno-0-393">393</a></span>
<span class="normal"><a href="#__codelineno-0-394">394</a></span>
<span class="normal"><a href="#__codelineno-0-395">395</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-374" name="__codelineno-0-374"></a><span class="k">def</span><span class="w"> </span><span class="nf">parse_timeframe</span><span class="p">(</span><span class="n">value</span><span class="p">:</span> <span class="nb">object</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">int</span><span class="p">:</span>
<a id="__codelineno-0-375" name="__codelineno-0-375"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Parse a timeframe string or integer value.</span>
<a id="__codelineno-0-376" name="__codelineno-0-376"></a>
<a id="__codelineno-0-377" name="__codelineno-0-377"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-378" name="__codelineno-0-378"></a><span class="sd"> value: Timeframe name (e.g., &#39;M1&#39;, &#39;H1&#39;, &#39;D1&#39;) or integer value.</span>
<a id="__codelineno-0-379" name="__codelineno-0-379"></a>
<a id="__codelineno-0-380" name="__codelineno-0-380"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-381" name="__codelineno-0-381"></a><span class="sd"> Integer timeframe value.</span>
<a id="__codelineno-0-382" name="__codelineno-0-382"></a>
<a id="__codelineno-0-383" name="__codelineno-0-383"></a><span class="sd"> Raises:</span>
<a id="__codelineno-0-384" name="__codelineno-0-384"></a><span class="sd"> ValueError: If the timeframe is invalid.</span>
<a id="__codelineno-0-385" name="__codelineno-0-385"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-386" name="__codelineno-0-386"></a> <span class="k">try</span><span class="p">:</span>
<a id="__codelineno-0-387" name="__codelineno-0-387"></a> <span class="k">return</span> <span class="n">_parse_timeframe</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<a id="__codelineno-0-388" name="__codelineno-0-388"></a> <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
<a id="__codelineno-0-389" name="__codelineno-0-389"></a> <span class="n">display</span> <span class="o">=</span> <span class="n">value</span> <span class="k">if</span> <span class="nb">isinstance</span><span class="p">(</span><span class="n">value</span><span class="p">,</span> <span class="nb">str</span><span class="p">)</span> <span class="k">else</span> <span class="nb">repr</span><span class="p">(</span><span class="n">value</span><span class="p">)</span>
<a id="__codelineno-0-390" name="__codelineno-0-390"></a> <span class="n">valid</span> <span class="o">=</span> <span class="s2">&quot;, &quot;</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">TIMEFRAME_NAMES</span><span class="p">)</span>
<a id="__codelineno-0-391" name="__codelineno-0-391"></a> <span class="n">msg</span> <span class="o">=</span> <span class="p">(</span>
<a id="__codelineno-0-392" name="__codelineno-0-392"></a> <span class="sa">f</span><span class="s2">&quot;Invalid timeframe: &#39;</span><span class="si">{</span><span class="n">display</span><span class="si">}</span><span class="s2">&#39;. &quot;</span>
<a id="__codelineno-0-393" name="__codelineno-0-393"></a> <span class="sa">f</span><span class="s2">&quot;Use one of: </span><span class="si">{</span><span class="n">valid</span><span class="si">}</span><span class="s2">, or a supported integer.&quot;</span>
<a id="__codelineno-0-394" name="__codelineno-0-394"></a> <span class="p">)</span>
<a id="__codelineno-0-395" name="__codelineno-0-395"></a> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span> <span class="kn">from</span><span class="w"> </span><span class="kc">None</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
<div class="doc doc-object doc-function">
<h3 id="mt5cli.converters.recent_window" class="doc doc-heading">
<span class="doc doc-object-name doc-function-name">recent_window</span>
<a href="#mt5cli.converters.recent_window" class="headerlink" title="Permanent link">&para;</a></h3>
<div class="doc-signature highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a><span class="nf">recent_window</span><span class="p">(</span>
<a id="__codelineno-0-2" name="__codelineno-0-2" href="#__codelineno-0-2"></a> <span class="o">*</span><span class="p">,</span>
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> <span class="n">hours</span><span class="p">:</span> <span class="n"><span title="float">float</span></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a> <span class="n">seconds</span><span class="p">:</span> <span class="n"><span title="float">float</span></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> <span class="n">date_to</span><span class="p">:</span> <span class="n"><span title="datetime.datetime">datetime</span></span> <span class="o">|</span> <span class="n"><span title="str">str</span></span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a><span class="p">)</span> <span class="o">-&gt;</span> <span class="n"><span title="tuple">tuple</span></span><span class="p">[</span><span class="n"><span title="datetime.datetime">datetime</span></span><span class="p">,</span> <span class="n"><span title="datetime.datetime">datetime</span></span><span class="p">]</span>
</code></pre></div>
<div class="doc doc-contents ">
<p>Build a trailing UTC window ending at <code>date_to</code> or now.</p>
<p>Exactly one of <code>hours</code> or <code>seconds</code> must be provided.</p>
<p><span class="doc-section-title">Parameters:</span></p>
<table>
<thead>
<tr>
<th>Name</th>
<th>Type</th>
<th>Description</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code>hours</code>
</td>
<td>
<code><span title="float">float</span> | None</code>
</td>
<td>
<div class="doc-md-description">
<p>Trailing window length in hours.</p>
</div>
</td>
<td>
<code>None</code>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>seconds</code>
</td>
<td>
<code><span title="float">float</span> | None</code>
</td>
<td>
<div class="doc-md-description">
<p>Trailing window length in seconds.</p>
</div>
</td>
<td>
<code>None</code>
</td>
</tr>
<tr class="doc-section-item">
<td>
<code>date_to</code>
</td>
<td>
<code><span title="datetime.datetime">datetime</span> | <span title="str">str</span> | None</code>
</td>
<td>
<div class="doc-md-description">
<p>Window end. Defaults to current UTC time.</p>
</div>
</td>
<td>
<code>None</code>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Returns:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="tuple">tuple</span>[<span title="datetime.datetime">datetime</span>, <span title="datetime.datetime">datetime</span>]</code>
</td>
<td>
<div class="doc-md-description">
<p>Tuple of UTC-aware <code>(start, end)</code> datetimes.</p>
</div>
</td>
</tr>
</tbody>
</table>
<p><span class="doc-section-title">Raises:</span></p>
<table>
<thead>
<tr>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr class="doc-section-item">
<td>
<code><span title="ValueError">ValueError</span></code>
</td>
<td>
<div class="doc-md-description">
<p>If neither or both window lengths are provided, or if a
length is not positive.</p>
</div>
</td>
</tr>
</tbody>
</table>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/converters.py</code></summary>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></span><span class="normal"><a href="#__codelineno-0-112">112</a></span>
<span class="normal"><a href="#__codelineno-0-113">113</a></span>
<span class="normal"><a href="#__codelineno-0-114">114</a></span>
<span class="normal"><a href="#__codelineno-0-115">115</a></span>
<span class="normal"><a href="#__codelineno-0-116">116</a></span>
<span class="normal"><a href="#__codelineno-0-117">117</a></span>
<span class="normal"><a href="#__codelineno-0-118">118</a></span>
<span class="normal"><a href="#__codelineno-0-119">119</a></span>
<span class="normal"><a href="#__codelineno-0-120">120</a></span>
<span class="normal"><a href="#__codelineno-0-121">121</a></span>
<span class="normal"><a href="#__codelineno-0-122">122</a></span>
<span class="normal"><a href="#__codelineno-0-123">123</a></span>
<span class="normal"><a href="#__codelineno-0-124">124</a></span>
<span class="normal"><a href="#__codelineno-0-125">125</a></span>
<span class="normal"><a href="#__codelineno-0-126">126</a></span>
<span class="normal"><a href="#__codelineno-0-127">127</a></span>
<span class="normal"><a href="#__codelineno-0-128">128</a></span>
<span class="normal"><a href="#__codelineno-0-129">129</a></span>
<span class="normal"><a href="#__codelineno-0-130">130</a></span>
<span class="normal"><a href="#__codelineno-0-131">131</a></span>
<span class="normal"><a href="#__codelineno-0-132">132</a></span>
<span class="normal"><a href="#__codelineno-0-133">133</a></span>
<span class="normal"><a href="#__codelineno-0-134">134</a></span>
<span class="normal"><a href="#__codelineno-0-135">135</a></span>
<span class="normal"><a href="#__codelineno-0-136">136</a></span>
<span class="normal"><a href="#__codelineno-0-137">137</a></span>
<span class="normal"><a href="#__codelineno-0-138">138</a></span>
<span class="normal"><a href="#__codelineno-0-139">139</a></span>
<span class="normal"><a href="#__codelineno-0-140">140</a></span>
<span class="normal"><a href="#__codelineno-0-141">141</a></span>
<span class="normal"><a href="#__codelineno-0-142">142</a></span>
<span class="normal"><a href="#__codelineno-0-143">143</a></span>
<span class="normal"><a href="#__codelineno-0-144">144</a></span>
<span class="normal"><a href="#__codelineno-0-145">145</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-112" name="__codelineno-0-112"></a><span class="k">def</span><span class="w"> </span><span class="nf">recent_window</span><span class="p">(</span>
<a id="__codelineno-0-113" name="__codelineno-0-113"></a> <span class="o">*</span><span class="p">,</span>
<a id="__codelineno-0-114" name="__codelineno-0-114"></a> <span class="n">hours</span><span class="p">:</span> <span class="nb">float</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<a id="__codelineno-0-115" name="__codelineno-0-115"></a> <span class="n">seconds</span><span class="p">:</span> <span class="nb">float</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<a id="__codelineno-0-116" name="__codelineno-0-116"></a> <span class="n">date_to</span><span class="p">:</span> <span class="n">datetime</span> <span class="o">|</span> <span class="nb">str</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">,</span>
<a id="__codelineno-0-117" name="__codelineno-0-117"></a><span class="p">)</span> <span class="o">-&gt;</span> <span class="nb">tuple</span><span class="p">[</span><span class="n">datetime</span><span class="p">,</span> <span class="n">datetime</span><span class="p">]:</span>
<a id="__codelineno-0-118" name="__codelineno-0-118"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Build a trailing UTC window ending at ``date_to`` or now.</span>
<a id="__codelineno-0-119" name="__codelineno-0-119"></a>
<a id="__codelineno-0-120" name="__codelineno-0-120"></a><span class="sd"> Exactly one of ``hours`` or ``seconds`` must be provided.</span>
<a id="__codelineno-0-121" name="__codelineno-0-121"></a>
<a id="__codelineno-0-122" name="__codelineno-0-122"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-123" name="__codelineno-0-123"></a><span class="sd"> hours: Trailing window length in hours.</span>
<a id="__codelineno-0-124" name="__codelineno-0-124"></a><span class="sd"> seconds: Trailing window length in seconds.</span>
<a id="__codelineno-0-125" name="__codelineno-0-125"></a><span class="sd"> date_to: Window end. Defaults to current UTC time.</span>
<a id="__codelineno-0-126" name="__codelineno-0-126"></a>
<a id="__codelineno-0-127" name="__codelineno-0-127"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-128" name="__codelineno-0-128"></a><span class="sd"> Tuple of UTC-aware ``(start, end)`` datetimes.</span>
<a id="__codelineno-0-129" name="__codelineno-0-129"></a>
<a id="__codelineno-0-130" name="__codelineno-0-130"></a><span class="sd"> Raises:</span>
<a id="__codelineno-0-131" name="__codelineno-0-131"></a><span class="sd"> ValueError: If neither or both window lengths are provided, or if a</span>
<a id="__codelineno-0-132" name="__codelineno-0-132"></a><span class="sd"> length is not positive.</span>
<a id="__codelineno-0-133" name="__codelineno-0-133"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-134" name="__codelineno-0-134"></a> <span class="k">if</span> <span class="p">(</span><span class="n">hours</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">)</span> <span class="o">==</span> <span class="p">(</span><span class="n">seconds</span> <span class="ow">is</span> <span class="kc">None</span><span class="p">):</span>
<a id="__codelineno-0-135" name="__codelineno-0-135"></a> <span class="n">msg</span> <span class="o">=</span> <span class="s2">&quot;Provide exactly one of hours or seconds.&quot;</span>
<a id="__codelineno-0-136" name="__codelineno-0-136"></a> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
<a id="__codelineno-0-137" name="__codelineno-0-137"></a> <span class="k">if</span> <span class="n">hours</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span><span class="p">:</span>
<a id="__codelineno-0-138" name="__codelineno-0-138"></a> <span class="n">length</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="n">hours</span><span class="p">)</span>
<a id="__codelineno-0-139" name="__codelineno-0-139"></a> <span class="k">else</span><span class="p">:</span>
<a id="__codelineno-0-140" name="__codelineno-0-140"></a> <span class="n">length</span> <span class="o">=</span> <span class="n">timedelta</span><span class="p">(</span><span class="n">seconds</span><span class="o">=</span><span class="n">seconds</span> <span class="k">if</span> <span class="n">seconds</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="mi">0</span><span class="p">)</span>
<a id="__codelineno-0-141" name="__codelineno-0-141"></a> <span class="k">if</span> <span class="n">length</span><span class="o">.</span><span class="n">total_seconds</span><span class="p">()</span> <span class="o">&lt;=</span> <span class="mi">0</span><span class="p">:</span>
<a id="__codelineno-0-142" name="__codelineno-0-142"></a> <span class="n">msg</span> <span class="o">=</span> <span class="s2">&quot;Window length must be positive.&quot;</span>
<a id="__codelineno-0-143" name="__codelineno-0-143"></a> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="n">msg</span><span class="p">)</span>
<a id="__codelineno-0-144" name="__codelineno-0-144"></a> <span class="n">end</span> <span class="o">=</span> <span class="n">ensure_utc</span><span class="p">(</span><span class="n">date_to</span><span class="p">)</span> <span class="k">if</span> <span class="n">date_to</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="k">else</span> <span class="n">datetime</span><span class="o">.</span><span class="n">now</span><span class="p">(</span><span class="n">UTC</span><span class="p">)</span>
<a id="__codelineno-0-145" name="__codelineno-0-145"></a> <span class="k">return</span> <span class="n">end</span> <span class="o">-</span> <span class="n">length</span><span class="p">,</span> <span class="n">end</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
</div>
</div>
</div>
</div></div>
</div>
</div>
<footer class="col-md-12">
<hr>
<p>Documentation built with <a href="https://www.mkdocs.org/">MkDocs</a>.</p>
</footer>
<script src="../../js/bootstrap.bundle.min.js"></script>
<script>
var base_url = "../..",
shortcuts = {"help": 191, "next": 78, "previous": 80, "search": 83};
</script>
<script src="../../js/base.js"></script>
<script src="../../search/main.js"></script>
<div class="modal" id="mkdocs_search_modal" tabindex="-1" role="dialog" aria-labelledby="searchModalLabel" aria-hidden="true">
<div class="modal-dialog modal-lg">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="searchModalLabel">Search</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<p>From here you can search these documents. Enter your search terms below.</p>
<form>
<div class="form-group">
<input type="search" class="form-control" placeholder="Search..." id="mkdocs-search-query" title="Type search term here">
</div>
</form>
<div id="mkdocs-search-results" data-no-results-text="No results found"></div>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div><div class="modal" id="mkdocs_keyboard_modal" tabindex="-1" role="dialog" aria-labelledby="keyboardModalLabel" aria-hidden="true">
<div class="modal-dialog">
<div class="modal-content">
<div class="modal-header">
<h4 class="modal-title" id="keyboardModalLabel">Keyboard Shortcuts</h4>
<button type="button" class="btn-close" data-bs-dismiss="modal" aria-label="Close"></button>
</div>
<div class="modal-body">
<table class="table">
<thead>
<tr>
<th style="width: 20%;">Keys</th>
<th>Action</th>
</tr>
</thead>
<tbody>
<tr>
<td class="help shortcut"><kbd>?</kbd></td>
<td>Open this help</td>
</tr>
<tr>
<td class="next shortcut"><kbd>n</kbd></td>
<td>Next page</td>
</tr>
<tr>
<td class="prev shortcut"><kbd>p</kbd></td>
<td>Previous page</td>
</tr>
<tr>
<td class="search shortcut"><kbd>s</kbd></td>
<td>Search</td>
</tr>
</tbody>
</table>
</div>
<div class="modal-footer">
</div>
</div>
</div>
</div>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink