gavindiaz/mt5cli
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

deploy: f435544f07

Browse Source
This commit is contained in:
dceoy
2026-06-26 09:24:23 +00:00
parent da5afc496b
commit a228b52245
18 changed files with 132 additions and 5179 deletions
Download Patch File Download Diff File Expand all files Collapse all files
404.html
-4
View File
@@ -58,10 +58,6 @@
<a href="/dceoy/mt5cli/api/schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="/dceoy/mt5cli/api/storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="/dceoy/mt5cli/api/converters/" class="dropdown-item">Converters</a>
</li>
api/cli/index.html
-4
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
api/client/index.html
-4
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
api/converters/index.html
+1 -5
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="./" class="dropdown-item active" aria-current="page">Converters</a>
</li>
@@ -100,7 +96,7 @@
</a>
</li>
<li class="nav-item">
<a rel="prev" href="../storage/" class="nav-link">
<a rel="prev" href="../schemas/" class="nav-link">
<i class="fa fa-arrow-left"></i> Previous
</a>
</li>
api/exceptions/index.html
-4
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
api/history/index.html
+20 -22
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
@@ -6043,24 +6039,26 @@ targets without hard-coding view names:</p>
<div class="highlight"><pre><span></span><code><a id="__codelineno-2-1" name="__codelineno-2-1" href="#__codelineno-2-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pathlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Path</span>
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a>
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a> <span class="n">load_rate_data</span><span class="p">,</span>
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a> <span class="n">load_rate_series_by_granularity</span><span class="p">,</span>
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a> <span class="n">load_rate_series_from_sqlite</span><span class="p">,</span>
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a> <span class="n">resolve_rate_table_name</span><span class="p">,</span>
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a><span class="p">)</span>
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.history</span><span class="w"> </span><span class="kn">import</span> <span class="n">resolve_rate_view_name</span>
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a>
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="n">view</span> <span class="o">=</span> <span class="n">resolve_rate_view_name</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;M1&quot;</span><span class="p">,</span> <span class="n">require_existing</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a><span class="n">rates</span> <span class="o">=</span> <span class="n">load_rate_data</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="n">view</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a><span class="n">same_rates</span> <span class="o">=</span> <span class="n">load_rate_series_from_sqlite</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="n">table</span><span class="o">=</span><span class="n">view</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a>
<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a><span class="n">table</span> <span class="o">=</span> <span class="n">resolve_rate_table_name</span><span class="p">(</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;M1&quot;</span><span class="p">)</span> <span class="c1"># &quot;rates&quot;</span>
<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a><span class="n">series</span> <span class="o">=</span> <span class="n">load_rate_series_by_granularity</span><span class="p">(</span>
<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a> <span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span>
<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a> <span class="n">symbols</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;GBPUSD&quot;</span><span class="p">],</span>
<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a> <span class="n">granularities</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;M1&quot;</span><span class="p">,</span> <span class="s2">&quot;H1&quot;</span><span class="p">],</span>
<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a> <span class="n">count</span><span class="o">=</span><span class="mi">500</span><span class="p">,</span>
<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a><span class="p">)</span>
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a> <span class="n">load_rate_series_by_granularity</span><span class="p">,</span>
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a> <span class="n">load_rate_series_from_sqlite</span><span class="p">,</span>
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a><span class="p">)</span>
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.history</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a> <span class="n">load_rate_data</span><span class="p">,</span>
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a> <span class="n">resolve_rate_table_name</span><span class="p">,</span>
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a> <span class="n">resolve_rate_view_name</span><span class="p">,</span>
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="p">)</span>
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a>
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a><span class="n">view</span> <span class="o">=</span> <span class="n">resolve_rate_view_name</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;M1&quot;</span><span class="p">,</span> <span class="n">require_existing</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a><span class="n">rates</span> <span class="o">=</span> <span class="n">load_rate_data</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="n">view</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>
<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a><span class="n">same_rates</span> <span class="o">=</span> <span class="n">load_rate_series_from_sqlite</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="n">table</span><span class="o">=</span><span class="n">view</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>
<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a>
<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a><span class="n">table</span> <span class="o">=</span> <span class="n">resolve_rate_table_name</span><span class="p">(</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;M1&quot;</span><span class="p">)</span> <span class="c1"># &quot;rates&quot;</span>
<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a><span class="n">series</span> <span class="o">=</span> <span class="n">load_rate_series_by_granularity</span><span class="p">(</span>
<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a> <span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span>
<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a> <span class="n">symbols</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;GBPUSD&quot;</span><span class="p">],</span>
<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a> <span class="n">granularities</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;M1&quot;</span><span class="p">,</span> <span class="s2">&quot;H1&quot;</span><span class="p">],</span>
<a id="__codelineno-2-22" name="__codelineno-2-22" href="#__codelineno-2-22"></a> <span class="n">count</span><span class="o">=</span><span class="mi">500</span><span class="p">,</span>
<a id="__codelineno-2-23" name="__codelineno-2-23" href="#__codelineno-2-23"></a><span class="p">)</span>
</code></pre></div>
<p><code>count</code> returns the latest rows while preserving chronological order. Missing
tables/views and mismatched <code>explicit_tables</code> lengths raise <code>ValueError</code> with
api/index.html
+4 -13
View File
@@ -58,10 +58,6 @@
<a href="schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="converters/" class="dropdown-item">Converters</a>
</li>
@@ -179,10 +175,6 @@ responsibilities.</p>
<td>Canonical DataFrame contracts and normalization helpers</td>
</tr>
<tr>
<td><a href="storage/">Storage</a></td>
<td>CSV/JSON/Parquet/SQLite export and history collection helpers</td>
</tr>
<tr>
<td><a href="converters/">Converters</a></td>
<td>Symbol, timeframe, timezone, and date-range utilities</td>
</tr>
@@ -218,14 +210,13 @@ responsibilities.</p>
<a id="__codelineno-0-3" name="__codelineno-0-3" href="#__codelineno-0-3"></a> CLI[&quot;mt5cli CLI&quot;] --&gt; Client
<a id="__codelineno-0-4" name="__codelineno-0-4" href="#__codelineno-0-4"></a> Client --&gt; SDK[&quot;sdk / pdmt5&quot;]
<a id="__codelineno-0-5" name="__codelineno-0-5" href="#__codelineno-0-5"></a> Client --&gt; Schemas[&quot;schemas&quot;]
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> Storage[&quot;storage&quot;] --&gt; History[&quot;history SQLite&quot;]
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> Storage --&gt; Utils[&quot;utils export&quot;]
<a id="__codelineno-0-8" name="__codelineno-0-8" href="#__codelineno-0-8"></a> SDK --&gt; PDMT5[&quot;pdmt5.Mt5DataClient&quot;]
<a id="__codelineno-0-6" name="__codelineno-0-6" href="#__codelineno-0-6"></a> History[&quot;history SQLite&quot;] --&gt; Utils[&quot;utils export&quot;]
<a id="__codelineno-0-7" name="__codelineno-0-7" href="#__codelineno-0-7"></a> SDK --&gt; PDMT5[&quot;pdmt5.Mt5DataClient&quot;]
</code></pre></div>
<p>Downstream packages should depend on the package root exports documented in the
<a href="public-contract/">Public API Contract</a> (<code>MT5Client</code>,
<code>DataKind</code>, <code>normalize_dataframe</code>, <code>collect_history</code>, <code>load_rate_data</code>,
<code>resolve_rate_view_name</code>, etc.) rather than private modules.</p>
<code>collect_history</code>, <code>load_rate_series_from_sqlite</code>, etc.) rather than private
modules. Lower-level helpers are accessible directly from their owning modules.</p>
<p><code>MT5Client.order_send()</code> is a live execution primitive that can place real trades. mt5cli exposes minimal execution helpers only; strategy logic, signals, backtests, and optimization remain out of scope and must be implemented downstream with explicit execution gating.</p>
<h2 id="quick-start">Quick start<a class="headerlink" href="#quick-start" title="Permanent link">&para;</a></h2>
<div class="highlight"><pre><span></span><code><a id="__codelineno-1-1" name="__codelineno-1-1" href="#__codelineno-1-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli</span><span class="w"> </span><span class="kn">import</span> <span class="n">MT5Client</span><span class="p">,</span> <span class="n">build_config</span><span class="p">,</span> <span class="n">mt5_session</span>
api/public-contract/index.html
+45 -159
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
@@ -137,15 +133,11 @@
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#public-api-tiers" class="nav-link">Public API tiers</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#stable-downstream-sdk-api" class="nav-link">Stable downstream SDK API</a>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#secondary-public-exports" class="nav-link">Secondary public exports</a>
<li class="nav-item" data-bs-level="2"><a href="#module-scoped-helpers" class="nav-link">Module-scoped helpers</a>
<ul class="nav flex-column">
</ul>
</li>
@@ -207,34 +199,13 @@ mt5cli does not serve as a pass-through compatibility namespace for pdmt5.</p>
<p>Note: the former <code>mt5cli</code> re-export <code>TICK_FLAG_MAP</code> corresponds to <code>COPY_TICKS_MAP</code>
in pdmt5 — the name changed, it was not simply moved.</p>
<p>Downstream packages should import from the package root (<code>from mt5cli import
...</code>) and use the public tier sets in <code>mt5cli.contract</code> to distinguish API
stability. CLI commands mirror the same behavior but are not importable Python
APIs.</p>
<h2 id="public-api-tiers">Public API tiers<a class="headerlink" href="#public-api-tiers" title="Permanent link">&para;</a></h2>
<p>mt5cli classifies package-root imports by intended downstream use:</p>
<table>
<thead>
<tr>
<th>Tier</th>
<th>Contract set</th>
<th>Meaning</th>
</tr>
</thead>
<tbody>
<tr>
<td>Stable core</td>
<td><code>STABLE_SDK_EXPORTS</code></td>
<td>Preferred SDK surface for downstream MT5 infrastructure adapters. Changes require a deliberate compatibility path.</td>
</tr>
<tr>
<td>Secondary public</td>
<td><code>SECONDARY_PUBLIC_EXPORTS</code></td>
<td>Public helpers for CLI/export/schema integrations and lower-level MT5 wrappers. Importable, but less central to the downstream trading SDK.</td>
</tr>
</tbody>
</table>
...</code>). The contract set <code>STABLE_SDK_EXPORTS</code> in <code>mt5cli.contract</code> enumerates
every package-root symbol. Lower-level helpers (schema utilities, export
functions, parser helpers, low-level MT5 wrappers) are available directly from
their owning modules (<code>mt5cli.schemas</code>, <code>mt5cli.utils</code>, <code>mt5cli.converters</code>,
<code>mt5cli.sdk</code>, etc.) and are not part of the root SDK surface.</p>
<h2 id="stable-downstream-sdk-api">Stable downstream SDK API<a class="headerlink" href="#stable-downstream-sdk-api" title="Permanent link">&para;</a></h2>
<p>These names are exported from <code>mt5cli</code> and covered by the contract in
<p>These names are exported from <code>mt5cli</code> and enumerated in
<code>mt5cli.STABLE_SDK_EXPORTS</code> (defined in <code>mt5cli.contract</code>).</p>
<h3 id="session-lifecycle-and-configuration">Session lifecycle and configuration<a class="headerlink" href="#session-lifecycle-and-configuration" title="Permanent link">&para;</a></h3>
<table>
@@ -269,26 +240,8 @@ APIs.</p>
<td><code>resolve_account_spec</code>, <code>resolve_account_specs</code></td>
<td>Merge overrides and expand <code>${ENV_VAR}</code> placeholders; opt-in <code>allow_whole_dollar_env</code> for bare <code>$NAME</code></td>
</tr>
<tr>
<td><code>substitute_env_placeholders</code></td>
<td>Replace <code>${NAME}</code> substrings from the environment; opt-in <code>allow_whole_dollar_env</code> for whole-value <code>$NAME</code></td>
</tr>
<tr>
<td><code>substitute_mapping_values</code></td>
<td>Recursively traverse a dict/list/scalar structure and substitute <code>${ENV_VAR}</code> placeholders for caller-selected mapping keys only; optionally normalise blank strings to <code>None</code> for a separate caller-selected key set; does not hard-code any application-specific key names</td>
</tr>
</tbody>
</table>
<p>Credential resolution is generic: any environment variable name may appear inside
<code>${...}</code>. mt5cli does not hard-code application-specific keys such as
<code>mt5_login</code> or <code>mt5_exe</code>.</p>
<p>Pass <code>allow_whole_dollar_env=True</code> to <code>substitute_env_placeholders()</code>,
<code>substitute_mapping_values()</code>, <code>resolve_account_spec()</code>, <code>resolve_account_specs()</code>,
and <code>build_config()</code> to additionally expand strings whose entire value is a bare
<code>$ENV_NAME</code> identifier.
Partial strings such as <code>"plan$pass"</code>, <code>"abc$ENV"</code>, or <code>"$ENV-suffix"</code> are
<strong>never</strong> expanded — only an exact <code>$IDENTIFIER</code> whole-string match qualifies.
Default is <code>False</code> to preserve backward compatibility.</p>
<h3 id="closed-bar-rate-helpers">Closed-bar rate helpers<a class="headerlink" href="#closed-bar-rate-helpers" title="Permanent link">&para;</a></h3>
<p>MetaTrader 5 returns the still-forming bar as the last row when
<code>start_pos=0</code>. Use these helpers instead of reimplementing bar trimming or
@@ -353,30 +306,15 @@ timestamp normalization in downstream apps.</p>
<td>Minimum interval between successful incremental updates; optional <code>update_backend</code> injection</td>
</tr>
<tr>
<td><code>resolve_history_datasets</code>, <code>resolve_history_timeframes</code>, <code>resolve_history_tick_flags</code></td>
<td>History pipeline configuration</td>
</tr>
<tr>
<td><code>build_rate_view_name</code>, <code>resolve_rate_table_name</code>, <code>resolve_rate_view_name</code>, <code>resolve_rate_view_names</code>, <code>resolve_rate_tables</code></td>
<td>Map symbols/timeframes to mt5cli-managed table or view names</td>
</tr>
<tr>
<td><code>RateTarget</code>, <code>build_rate_targets</code></td>
<td>Neutral <code>(symbol, timeframe)</code> series descriptors</td>
</tr>
<tr>
<td><code>load_rate_data</code>, <code>load_rate_data_from_connection</code></td>
<td>Load one table/view into a time-indexed DataFrame</td>
</tr>
<tr>
<td><code>load_rate_series_from_sqlite</code>, <code>load_rate_series_by_granularity</code></td>
<td>Load one or many series; fail clearly when managed views are missing</td>
</tr>
</tbody>
</table>
<p>Pass <code>require_existing=True</code> to rate view resolution helpers when downstream
code must fail instead of receiving a best-guess view name. Multi-series loaders
require existing managed <code>rate_*__*</code> views unless <code>explicit_tables</code> is supplied.</p>
<p>See <a href="../history/">History Collection (SQLite)</a> for schema, view naming, and ER
diagrams.</p>
<h3 id="trading-and-sizing-primitives-generic">Trading and sizing primitives (generic)<a class="headerlink" href="#trading-and-sizing-primitives-generic" title="Permanent link">&para;</a></h3>
@@ -494,94 +432,42 @@ and returned as <code>status="failed"</code> with normalized <code>request</code
<td><code>Mt5CliError</code>, <code>Mt5ConnectionError</code>, <code>Mt5OperationError</code>, <code>Mt5SchemaError</code></td>
<td>Stable mt5cli exception types</td>
</tr>
</tbody>
</table>
<h2 id="module-scoped-helpers">Module-scoped helpers<a class="headerlink" href="#module-scoped-helpers" title="Permanent link">&para;</a></h2>
<p>Lower-level helpers are available from their owning modules and are not part
of the package-root stable surface. Import them directly when needed:</p>
<table>
<thead>
<tr>
<th>Module</th>
<th>Examples</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>mt5cli.history</code></td>
<td><code>resolve_rate_view_name</code>, <code>resolve_rate_tables</code>, <code>load_rate_data</code>, <code>build_rate_view_name</code></td>
</tr>
<tr>
<td><code>mt5cli.sdk</code></td>
<td><code>copy_rates_from</code>, <code>copy_ticks_from</code>, <code>account_info</code>, <code>symbols</code>, <code>mt5_summary</code>, <code>latest_rates</code></td>
</tr>
<tr>
<td><code>mt5cli.schemas</code></td>
<td><code>DataKind</code>, <code>normalize_dataframe</code>, <code>validate_schema</code>, <code>DEDUP_KEYS</code></td>
</tr>
<tr>
<td><code>mt5cli.utils</code></td>
<td><code>Dataset</code>, <code>IfExists</code>, <code>detect_format</code>, <code>export_dataframe</code>, <code>export_dataframe_to_sqlite</code></td>
</tr>
<tr>
<td><code>mt5cli.converters</code></td>
<td><code>normalize_symbol</code>, <code>ensure_utc</code>, <code>parse_date_range</code>, <code>granularity_name</code></td>
</tr>
<tr>
<td><code>mt5cli.exceptions</code></td>
<td><code>normalize_mt5_exception</code>, <code>call_with_normalized_errors</code>, <code>is_recoverable_mt5_error</code></td>
<td>Error normalization and retry classification</td>
</tr>
</tbody>
</table>
<h2 id="secondary-public-exports">Secondary public exports<a class="headerlink" href="#secondary-public-exports" title="Permanent link">&para;</a></h2>
<p>These names remain importable from <code>mt5cli</code> and are covered by
<code>SECONDARY_PUBLIC_EXPORTS</code>, but they are oriented toward CLI/export/schema
integrations, parsing, and lower-level MT5 access rather than the stable core
SDK surface. Prefer the stable symbols above for downstream infrastructure
adapters.</p>
<h3 id="read-only-mt5-data-wrappers">Read-only MT5 data wrappers<a class="headerlink" href="#read-only-mt5-data-wrappers" title="Permanent link">&para;</a></h3>
<p>Module-level helpers open a transient connection per call. Prefer <code>mt5_session</code>
or <code>MT5Client</code> when making many requests in one process.</p>
<table>
<thead>
<tr>
<th>Area</th>
<th>Symbols</th>
</tr>
</thead>
<tbody>
<tr>
<td>Rates</td>
<td><code>copy_rates_from</code>, <code>copy_rates_from_pos</code>, <code>copy_rates_range</code>, <code>latest_rates</code>, <code>collect_latest_rates</code></td>
</tr>
<tr>
<td>Ticks</td>
<td><code>copy_ticks_from</code>, <code>copy_ticks_range</code>, <code>recent_ticks</code></td>
</tr>
<tr>
<td>Account / terminal</td>
<td><code>account_info</code>, <code>terminal_info</code>, <code>mt5_version</code>, <code>last_error</code>, <code>mt5_summary</code>, <code>mt5_summary_as_df</code></td>
</tr>
<tr>
<td>Symbols / market</td>
<td><code>symbols</code>, <code>symbol_info</code>, <code>symbol_info_tick</code>, <code>market_book</code>, <code>minimum_margins</code></td>
</tr>
<tr>
<td>Trading state (read)</td>
<td><code>orders</code>, <code>positions</code>, <code>history_orders</code>, <code>history_deals</code>, <code>recent_history_deals</code></td>
</tr>
<tr>
<td>Multi-account rates</td>
<td><code>collect_latest_rates_for_accounts</code></td>
</tr>
</tbody>
</table>
<p>Use <code>mt5_version</code> for MetaTrader 5 terminal version data. The name <code>version</code> at
the package root refers to <code>importlib.metadata.version</code> (package metadata), not
the MT5 SDK helper.</p>
<h3 id="schema-export-and-parser-helpers">Schema, export, and parser helpers<a class="headerlink" href="#schema-export-and-parser-helpers" title="Permanent link">&para;</a></h3>
<table>
<thead>
<tr>
<th>Area</th>
<th>Symbols</th>
</tr>
</thead>
<tbody>
<tr>
<td>Dataset contracts</td>
<td><code>DataKind</code>, <code>Dataset</code>, <code>IfExists</code>, <code>DEDUP_KEYS</code>, <code>REQUIRED_COLUMNS</code>, <code>TIME_COLUMNS</code>, <code>KNOWN_MT5_TIME_COLUMNS</code></td>
</tr>
<tr>
<td>Schema normalization</td>
<td><code>normalize_dataframe</code>, <code>normalize_time_columns</code>, <code>schema_columns</code>, <code>validate_schema</code></td>
</tr>
<tr>
<td>Export helpers</td>
<td><code>detect_format</code>, <code>export_dataframe</code>, <code>export_dataframe_to_sqlite</code></td>
</tr>
<tr>
<td>Symbol parsing</td>
<td><code>normalize_symbol</code>, <code>normalize_symbols</code></td>
</tr>
<tr>
<td>Time parsing</td>
<td><code>ensure_utc</code>, <code>parse_date_range</code>, <code>parse_datetime</code>, <code>recent_window</code></td>
</tr>
<tr>
<td>MT5 parsing maps</td>
<td><code>granularity_name</code>, <code>parse_tick_flags</code>, <code>parse_timeframe</code></td>
</tr>
<tr>
<td>Trading data shapes</td>
<td><code>POSITION_COLUMNS</code></td>
</tr>
</tbody>
</table>
@@ -651,10 +537,10 @@ machinery, closed-bar helpers, generic margin/volume/spread/SL/TP utilities, and
optional order primitives so downstream apps can focus on strategy code behind
their own adapter layer.</p>
<h2 id="contract-verification">Contract verification<a class="headerlink" href="#contract-verification" title="Permanent link">&para;</a></h2>
<p><code>tests/test_contracts.py</code> asserts that every name in the stable and secondary
tier sets is importable from <code>mt5cli</code>, documents key closed-bar, rate-view,
SQLite loading, account-resolution, and trading-session behaviors, and keeps the
tier sets aligned with <code>__all__</code>.</p></div>
<p><code>tests/test_contracts.py</code> asserts that every name in <code>STABLE_SDK_EXPORTS</code> is
importable from <code>mt5cli</code>, that all package-root exports are covered by the
stable set, and documents key closed-bar, SQLite loading, account-resolution,
and trading-session behaviors.</p></div>
</div>
</div>
api/schemas/index.html
+1 -5
View File
@@ -58,10 +58,6 @@
<a href="./" class="dropdown-item active" aria-current="page">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
@@ -105,7 +101,7 @@
</a>
</li>
<li class="nav-item">
<a rel="next" href="../storage/" class="nav-link">
<a rel="next" href="../converters/" class="nav-link">
Next <i class="fa fa-arrow-right"></i>
</a>
</li>
api/sdk/index.html
+18 -21
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
@@ -8905,23 +8901,24 @@ between successful runs (using a monotonic clock), so an application loop can
call it every iteration without over-fetching.</p>
<div class="highlight"><pre><span></span><code><a id="__codelineno-4-1" name="__codelineno-4-1" href="#__codelineno-4-1"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pdmt5</span><span class="w"> </span><span class="kn">import</span> <span class="n">Mt5Config</span><span class="p">,</span> <span class="n">Mt5DataClient</span>
<a id="__codelineno-4-2" name="__codelineno-4-2" href="#__codelineno-4-2"></a>
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli</span><span class="w"> </span><span class="kn">import</span> <span class="n">Dataset</span><span class="p">,</span> <span class="n">ThrottledHistoryUpdater</span>
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a>
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a><span class="n">updater</span> <span class="o">=</span> <span class="n">ThrottledHistoryUpdater</span><span class="p">(</span>
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a> <span class="n">output</span><span class="o">=</span><span class="s2">&quot;history.db&quot;</span><span class="p">,</span>
<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a> <span class="n">datasets</span><span class="o">=</span><span class="p">{</span><span class="n">Dataset</span><span class="o">.</span><span class="n">rates</span><span class="p">},</span>
<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a> <span class="n">timeframes</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;M1&quot;</span><span class="p">],</span>
<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a> <span class="n">interval_seconds</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="c1"># &lt;= 0 updates on every call</span>
<a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a><span class="p">)</span>
<a id="__codelineno-4-11" name="__codelineno-4-11" href="#__codelineno-4-11"></a>
<a id="__codelineno-4-12" name="__codelineno-4-12" href="#__codelineno-4-12"></a><span class="n">client</span> <span class="o">=</span> <span class="n">Mt5DataClient</span><span class="p">(</span><span class="n">config</span><span class="o">=</span><span class="n">Mt5Config</span><span class="p">(</span><span class="n">login</span><span class="o">=</span><span class="mi">12345</span><span class="p">))</span>
<a id="__codelineno-4-13" name="__codelineno-4-13" href="#__codelineno-4-13"></a><span class="n">client</span><span class="o">.</span><span class="n">initialize_and_login_mt5</span><span class="p">()</span>
<a id="__codelineno-4-14" name="__codelineno-4-14" href="#__codelineno-4-14"></a><span class="k">try</span><span class="p">:</span>
<a id="__codelineno-4-15" name="__codelineno-4-15" href="#__codelineno-4-15"></a> <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
<a id="__codelineno-4-16" name="__codelineno-4-16" href="#__codelineno-4-16"></a> <span class="n">updater</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="p">[</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;GBPUSD&quot;</span><span class="p">])</span> <span class="c1"># no-op until 60s elapse</span>
<a id="__codelineno-4-17" name="__codelineno-4-17" href="#__codelineno-4-17"></a> <span class="c1"># ... do other work; break when shutting down ...</span>
<a id="__codelineno-4-18" name="__codelineno-4-18" href="#__codelineno-4-18"></a><span class="k">finally</span><span class="p">:</span>
<a id="__codelineno-4-19" name="__codelineno-4-19" href="#__codelineno-4-19"></a> <span class="n">client</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
<a id="__codelineno-4-3" name="__codelineno-4-3" href="#__codelineno-4-3"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli</span><span class="w"> </span><span class="kn">import</span> <span class="n">ThrottledHistoryUpdater</span>
<a id="__codelineno-4-4" name="__codelineno-4-4" href="#__codelineno-4-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.utils</span><span class="w"> </span><span class="kn">import</span> <span class="n">Dataset</span>
<a id="__codelineno-4-5" name="__codelineno-4-5" href="#__codelineno-4-5"></a>
<a id="__codelineno-4-6" name="__codelineno-4-6" href="#__codelineno-4-6"></a><span class="n">updater</span> <span class="o">=</span> <span class="n">ThrottledHistoryUpdater</span><span class="p">(</span>
<a id="__codelineno-4-7" name="__codelineno-4-7" href="#__codelineno-4-7"></a> <span class="n">output</span><span class="o">=</span><span class="s2">&quot;history.db&quot;</span><span class="p">,</span>
<a id="__codelineno-4-8" name="__codelineno-4-8" href="#__codelineno-4-8"></a> <span class="n">datasets</span><span class="o">=</span><span class="p">{</span><span class="n">Dataset</span><span class="o">.</span><span class="n">rates</span><span class="p">},</span>
<a id="__codelineno-4-9" name="__codelineno-4-9" href="#__codelineno-4-9"></a> <span class="n">timeframes</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;M1&quot;</span><span class="p">],</span>
<a id="__codelineno-4-10" name="__codelineno-4-10" href="#__codelineno-4-10"></a> <span class="n">interval_seconds</span><span class="o">=</span><span class="mi">60</span><span class="p">,</span> <span class="c1"># &lt;= 0 updates on every call</span>
<a id="__codelineno-4-11" name="__codelineno-4-11" href="#__codelineno-4-11"></a><span class="p">)</span>
<a id="__codelineno-4-12" name="__codelineno-4-12" href="#__codelineno-4-12"></a>
<a id="__codelineno-4-13" name="__codelineno-4-13" href="#__codelineno-4-13"></a><span class="n">client</span> <span class="o">=</span> <span class="n">Mt5DataClient</span><span class="p">(</span><span class="n">config</span><span class="o">=</span><span class="n">Mt5Config</span><span class="p">(</span><span class="n">login</span><span class="o">=</span><span class="mi">12345</span><span class="p">))</span>
<a id="__codelineno-4-14" name="__codelineno-4-14" href="#__codelineno-4-14"></a><span class="n">client</span><span class="o">.</span><span class="n">initialize_and_login_mt5</span><span class="p">()</span>
<a id="__codelineno-4-15" name="__codelineno-4-15" href="#__codelineno-4-15"></a><span class="k">try</span><span class="p">:</span>
<a id="__codelineno-4-16" name="__codelineno-4-16" href="#__codelineno-4-16"></a> <span class="k">while</span> <span class="kc">True</span><span class="p">:</span>
<a id="__codelineno-4-17" name="__codelineno-4-17" href="#__codelineno-4-17"></a> <span class="n">updater</span><span class="o">.</span><span class="n">update</span><span class="p">(</span><span class="n">client</span><span class="p">,</span> <span class="p">[</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;GBPUSD&quot;</span><span class="p">])</span> <span class="c1"># no-op until 60s elapse</span>
<a id="__codelineno-4-18" name="__codelineno-4-18" href="#__codelineno-4-18"></a> <span class="c1"># ... do other work; break when shutting down ...</span>
<a id="__codelineno-4-19" name="__codelineno-4-19" href="#__codelineno-4-19"></a><span class="k">finally</span><span class="p">:</span>
<a id="__codelineno-4-20" name="__codelineno-4-20" href="#__codelineno-4-20"></a> <span class="n">client</span><span class="o">.</span><span class="n">shutdown</span><span class="p">()</span>
</code></pre></div>
<p>Pass <code>update_backend</code> to substitute the default <code>update_history</code> implementation
without monkey-patching <code>mt5cli.sdk.update_history</code>. The callable receives the
api/storage/index.html
-4875
View File
File diff suppressed because it is too large Load Diff
api/trading/index.html
-4
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
api/utils/index.html
-4
View File
@@ -58,10 +58,6 @@
<a href="../schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="../storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="../converters/" class="dropdown-item">Converters</a>
</li>
index.html
+42 -50
View File
@@ -58,10 +58,6 @@
<a href="api/schemas/" class="dropdown-item">Schemas</a>
</li>
<li>
<a href="api/storage/" class="dropdown-item">Storage</a>
</li>
<li>
<a href="api/converters/" class="dropdown-item">Converters</a>
</li>
@@ -219,54 +215,50 @@
<a id="__codelineno-2-2" name="__codelineno-2-2" href="#__codelineno-2-2"></a><span class="kn">from</span><span class="w"> </span><span class="nn">pathlib</span><span class="w"> </span><span class="kn">import</span> <span class="n">Path</span>
<a id="__codelineno-2-3" name="__codelineno-2-3" href="#__codelineno-2-3"></a>
<a id="__codelineno-2-4" name="__codelineno-2-4" href="#__codelineno-2-4"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli</span><span class="w"> </span><span class="kn">import</span> <span class="p">(</span>
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a> <span class="n">DataKind</span><span class="p">,</span>
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a> <span class="n">Dataset</span><span class="p">,</span>
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a> <span class="n">MT5Client</span><span class="p">,</span>
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a> <span class="n">build_config</span><span class="p">,</span>
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a> <span class="n">collect_history</span><span class="p">,</span>
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a> <span class="n">export_dataframe</span><span class="p">,</span>
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a> <span class="n">load_rate_data</span><span class="p">,</span>
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a> <span class="n">minimum_margins</span><span class="p">,</span>
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a> <span class="n">mt5_session</span><span class="p">,</span>
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a> <span class="n">normalize_dataframe</span><span class="p">,</span>
<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a> <span class="n">recent_ticks</span><span class="p">,</span>
<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a> <span class="n">resolve_rate_view_name</span><span class="p">,</span>
<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a><span class="p">)</span>
<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a>
<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a><span class="c1"># Persistent session for multiple calls</span>
<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a><span class="k">with</span> <span class="n">mt5_session</span><span class="p">(</span><span class="n">build_config</span><span class="p">(</span><span class="n">login</span><span class="o">=</span><span class="mi">12345</span><span class="p">,</span> <span class="n">server</span><span class="o">=</span><span class="s2">&quot;Broker-Demo&quot;</span><span class="p">))</span> <span class="k">as</span> <span class="n">client</span><span class="p">:</span>
<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a> <span class="n">rates</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">copy_rates_range</span><span class="p">(</span>
<a id="__codelineno-2-22" name="__codelineno-2-22" href="#__codelineno-2-22"></a> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span>
<a id="__codelineno-2-23" name="__codelineno-2-23" href="#__codelineno-2-23"></a> <span class="n">timeframe</span><span class="o">=</span><span class="s2">&quot;H1&quot;</span><span class="p">,</span>
<a id="__codelineno-2-24" name="__codelineno-2-24" href="#__codelineno-2-24"></a> <span class="n">date_from</span><span class="o">=</span><span class="s2">&quot;2024-01-01&quot;</span><span class="p">,</span>
<a id="__codelineno-2-25" name="__codelineno-2-25" href="#__codelineno-2-25"></a> <span class="n">date_to</span><span class="o">=</span><span class="s2">&quot;2024-02-01&quot;</span><span class="p">,</span>
<a id="__codelineno-2-26" name="__codelineno-2-26" href="#__codelineno-2-26"></a> <span class="p">)</span>
<a id="__codelineno-2-27" name="__codelineno-2-27" href="#__codelineno-2-27"></a> <span class="n">positions</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">positions</span><span class="p">()</span>
<a id="__codelineno-2-28" name="__codelineno-2-28" href="#__codelineno-2-28"></a> <span class="n">check</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">order_check</span><span class="p">({</span><span class="s2">&quot;action&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;symbol&quot;</span><span class="p">:</span> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;volume&quot;</span><span class="p">:</span> <span class="mf">0.1</span><span class="p">})</span>
<a id="__codelineno-2-29" name="__codelineno-2-29" href="#__codelineno-2-29"></a>
<a id="__codelineno-2-30" name="__codelineno-2-30" href="#__codelineno-2-30"></a><span class="c1"># Normalize MT5 frames to the public schema contract before storage</span>
<a id="__codelineno-2-31" name="__codelineno-2-31" href="#__codelineno-2-31"></a><span class="n">closed_rates</span> <span class="o">=</span> <span class="n">normalize_dataframe</span><span class="p">(</span>
<a id="__codelineno-2-32" name="__codelineno-2-32" href="#__codelineno-2-32"></a> <span class="n">rates</span><span class="p">,</span> <span class="n">DataKind</span><span class="o">.</span><span class="n">rates</span><span class="p">,</span> <span class="n">symbol</span><span class="o">=</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="n">timeframe</span><span class="o">=</span><span class="s2">&quot;H1&quot;</span>
<a id="__codelineno-2-33" name="__codelineno-2-33" href="#__codelineno-2-33"></a><span class="p">)</span>
<a id="__codelineno-2-34" name="__codelineno-2-34" href="#__codelineno-2-34"></a><span class="n">export_dataframe</span><span class="p">(</span><span class="n">closed_rates</span><span class="p">,</span> <span class="n">Path</span><span class="p">(</span><span class="s2">&quot;rates.csv&quot;</span><span class="p">),</span> <span class="s2">&quot;csv&quot;</span><span class="p">)</span>
<a id="__codelineno-2-5" name="__codelineno-2-5" href="#__codelineno-2-5"></a> <span class="n">MT5Client</span><span class="p">,</span>
<a id="__codelineno-2-6" name="__codelineno-2-6" href="#__codelineno-2-6"></a> <span class="n">build_config</span><span class="p">,</span>
<a id="__codelineno-2-7" name="__codelineno-2-7" href="#__codelineno-2-7"></a> <span class="n">collect_history</span><span class="p">,</span>
<a id="__codelineno-2-8" name="__codelineno-2-8" href="#__codelineno-2-8"></a> <span class="n">mt5_session</span><span class="p">,</span>
<a id="__codelineno-2-9" name="__codelineno-2-9" href="#__codelineno-2-9"></a><span class="p">)</span>
<a id="__codelineno-2-10" name="__codelineno-2-10" href="#__codelineno-2-10"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.history</span><span class="w"> </span><span class="kn">import</span> <span class="n">load_rate_data</span><span class="p">,</span> <span class="n">resolve_rate_view_name</span>
<a id="__codelineno-2-11" name="__codelineno-2-11" href="#__codelineno-2-11"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.schemas</span><span class="w"> </span><span class="kn">import</span> <span class="n">DataKind</span><span class="p">,</span> <span class="n">normalize_dataframe</span>
<a id="__codelineno-2-12" name="__codelineno-2-12" href="#__codelineno-2-12"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.sdk</span><span class="w"> </span><span class="kn">import</span> <span class="n">minimum_margins</span><span class="p">,</span> <span class="n">recent_ticks</span>
<a id="__codelineno-2-13" name="__codelineno-2-13" href="#__codelineno-2-13"></a><span class="kn">from</span><span class="w"> </span><span class="nn">mt5cli.utils</span><span class="w"> </span><span class="kn">import</span> <span class="n">Dataset</span><span class="p">,</span> <span class="n">export_dataframe</span>
<a id="__codelineno-2-14" name="__codelineno-2-14" href="#__codelineno-2-14"></a>
<a id="__codelineno-2-15" name="__codelineno-2-15" href="#__codelineno-2-15"></a><span class="c1"># Persistent session for multiple calls</span>
<a id="__codelineno-2-16" name="__codelineno-2-16" href="#__codelineno-2-16"></a><span class="k">with</span> <span class="n">mt5_session</span><span class="p">(</span><span class="n">build_config</span><span class="p">(</span><span class="n">login</span><span class="o">=</span><span class="mi">12345</span><span class="p">,</span> <span class="n">server</span><span class="o">=</span><span class="s2">&quot;Broker-Demo&quot;</span><span class="p">))</span> <span class="k">as</span> <span class="n">client</span><span class="p">:</span>
<a id="__codelineno-2-17" name="__codelineno-2-17" href="#__codelineno-2-17"></a> <span class="n">rates</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">copy_rates_range</span><span class="p">(</span>
<a id="__codelineno-2-18" name="__codelineno-2-18" href="#__codelineno-2-18"></a> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span>
<a id="__codelineno-2-19" name="__codelineno-2-19" href="#__codelineno-2-19"></a> <span class="n">timeframe</span><span class="o">=</span><span class="s2">&quot;H1&quot;</span><span class="p">,</span>
<a id="__codelineno-2-20" name="__codelineno-2-20" href="#__codelineno-2-20"></a> <span class="n">date_from</span><span class="o">=</span><span class="s2">&quot;2024-01-01&quot;</span><span class="p">,</span>
<a id="__codelineno-2-21" name="__codelineno-2-21" href="#__codelineno-2-21"></a> <span class="n">date_to</span><span class="o">=</span><span class="s2">&quot;2024-02-01&quot;</span><span class="p">,</span>
<a id="__codelineno-2-22" name="__codelineno-2-22" href="#__codelineno-2-22"></a> <span class="p">)</span>
<a id="__codelineno-2-23" name="__codelineno-2-23" href="#__codelineno-2-23"></a> <span class="n">positions</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">positions</span><span class="p">()</span>
<a id="__codelineno-2-24" name="__codelineno-2-24" href="#__codelineno-2-24"></a> <span class="n">check</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">order_check</span><span class="p">({</span><span class="s2">&quot;action&quot;</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="s2">&quot;symbol&quot;</span><span class="p">:</span> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;volume&quot;</span><span class="p">:</span> <span class="mf">0.1</span><span class="p">})</span>
<a id="__codelineno-2-25" name="__codelineno-2-25" href="#__codelineno-2-25"></a>
<a id="__codelineno-2-26" name="__codelineno-2-26" href="#__codelineno-2-26"></a><span class="c1"># Normalize MT5 frames to the public schema contract before storage</span>
<a id="__codelineno-2-27" name="__codelineno-2-27" href="#__codelineno-2-27"></a><span class="n">closed_rates</span> <span class="o">=</span> <span class="n">normalize_dataframe</span><span class="p">(</span>
<a id="__codelineno-2-28" name="__codelineno-2-28" href="#__codelineno-2-28"></a> <span class="n">rates</span><span class="p">,</span> <span class="n">DataKind</span><span class="o">.</span><span class="n">rates</span><span class="p">,</span> <span class="n">symbol</span><span class="o">=</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="n">timeframe</span><span class="o">=</span><span class="s2">&quot;H1&quot;</span>
<a id="__codelineno-2-29" name="__codelineno-2-29" href="#__codelineno-2-29"></a><span class="p">)</span>
<a id="__codelineno-2-30" name="__codelineno-2-30" href="#__codelineno-2-30"></a><span class="n">export_dataframe</span><span class="p">(</span><span class="n">closed_rates</span><span class="p">,</span> <span class="n">Path</span><span class="p">(</span><span class="s2">&quot;rates.csv&quot;</span><span class="p">),</span> <span class="s2">&quot;csv&quot;</span><span class="p">)</span>
<a id="__codelineno-2-31" name="__codelineno-2-31" href="#__codelineno-2-31"></a>
<a id="__codelineno-2-32" name="__codelineno-2-32" href="#__codelineno-2-32"></a><span class="c1"># Offline rate loading from mt5cli-managed SQLite history</span>
<a id="__codelineno-2-33" name="__codelineno-2-33" href="#__codelineno-2-33"></a><span class="n">view</span> <span class="o">=</span> <span class="n">resolve_rate_view_name</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;M1&quot;</span><span class="p">,</span> <span class="n">require_existing</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<a id="__codelineno-2-34" name="__codelineno-2-34" href="#__codelineno-2-34"></a><span class="n">offline_rates</span> <span class="o">=</span> <span class="n">load_rate_data</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="n">view</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>
<a id="__codelineno-2-35" name="__codelineno-2-35" href="#__codelineno-2-35"></a>
<a id="__codelineno-2-36" name="__codelineno-2-36" href="#__codelineno-2-36"></a><span class="c1"># Offline rate loading from mt5cli-managed SQLite history</span>
<a id="__codelineno-2-37" name="__codelineno-2-37" href="#__codelineno-2-37"></a><span class="n">view</span> <span class="o">=</span> <span class="n">resolve_rate_view_name</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;M1&quot;</span><span class="p">,</span> <span class="n">require_existing</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<a id="__codelineno-2-38" name="__codelineno-2-38" href="#__codelineno-2-38"></a><span class="n">offline_rates</span> <span class="o">=</span> <span class="n">load_rate_data</span><span class="p">(</span><span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span> <span class="n">view</span><span class="p">,</span> <span class="n">count</span><span class="o">=</span><span class="mi">1000</span><span class="p">)</span>
<a id="__codelineno-2-36" name="__codelineno-2-36" href="#__codelineno-2-36"></a><span class="c1"># One-off helpers still work without instantiating a client</span>
<a id="__codelineno-2-37" name="__codelineno-2-37" href="#__codelineno-2-37"></a><span class="n">ticks</span> <span class="o">=</span> <span class="n">recent_ticks</span><span class="p">(</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="n">seconds</span><span class="o">=</span><span class="mi">300</span><span class="p">)</span>
<a id="__codelineno-2-38" name="__codelineno-2-38" href="#__codelineno-2-38"></a><span class="n">margins</span> <span class="o">=</span> <span class="n">minimum_margins</span><span class="p">(</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">)</span>
<a id="__codelineno-2-39" name="__codelineno-2-39" href="#__codelineno-2-39"></a>
<a id="__codelineno-2-40" name="__codelineno-2-40" href="#__codelineno-2-40"></a><span class="c1"># One-off helpers still work without instantiating a client</span>
<a id="__codelineno-2-41" name="__codelineno-2-41" href="#__codelineno-2-41"></a><span class="n">ticks</span> <span class="o">=</span> <span class="n">recent_ticks</span><span class="p">(</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="n">seconds</span><span class="o">=</span><span class="mi">300</span><span class="p">)</span>
<a id="__codelineno-2-42" name="__codelineno-2-42" href="#__codelineno-2-42"></a><span class="n">margins</span> <span class="o">=</span> <span class="n">minimum_margins</span><span class="p">(</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">)</span>
<a id="__codelineno-2-43" name="__codelineno-2-43" href="#__codelineno-2-43"></a>
<a id="__codelineno-2-44" name="__codelineno-2-44" href="#__codelineno-2-44"></a><span class="n">collect_history</span><span class="p">(</span>
<a id="__codelineno-2-45" name="__codelineno-2-45" href="#__codelineno-2-45"></a> <span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span>
<a id="__codelineno-2-46" name="__codelineno-2-46" href="#__codelineno-2-46"></a> <span class="n">symbols</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;GBPUSD&quot;</span><span class="p">],</span>
<a id="__codelineno-2-47" name="__codelineno-2-47" href="#__codelineno-2-47"></a> <span class="n">date_from</span><span class="o">=</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2024</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">UTC</span><span class="p">),</span>
<a id="__codelineno-2-48" name="__codelineno-2-48" href="#__codelineno-2-48"></a> <span class="n">date_to</span><span class="o">=</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2024</span><span class="p">,</span> <span class="mi">2</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">UTC</span><span class="p">),</span>
<a id="__codelineno-2-49" name="__codelineno-2-49" href="#__codelineno-2-49"></a> <span class="n">datasets</span><span class="o">=</span><span class="p">{</span><span class="n">Dataset</span><span class="o">.</span><span class="n">rates</span><span class="p">,</span> <span class="n">Dataset</span><span class="o">.</span><span class="n">history_deals</span><span class="p">},</span>
<a id="__codelineno-2-50" name="__codelineno-2-50" href="#__codelineno-2-50"></a><span class="p">)</span>
<a id="__codelineno-2-40" name="__codelineno-2-40" href="#__codelineno-2-40"></a><span class="n">collect_history</span><span class="p">(</span>
<a id="__codelineno-2-41" name="__codelineno-2-41" href="#__codelineno-2-41"></a> <span class="n">Path</span><span class="p">(</span><span class="s2">&quot;history.db&quot;</span><span class="p">),</span>
<a id="__codelineno-2-42" name="__codelineno-2-42" href="#__codelineno-2-42"></a> <span class="n">symbols</span><span class="o">=</span><span class="p">[</span><span class="s2">&quot;EURUSD&quot;</span><span class="p">,</span> <span class="s2">&quot;GBPUSD&quot;</span><span class="p">],</span>
<a id="__codelineno-2-43" name="__codelineno-2-43" href="#__codelineno-2-43"></a> <span class="n">date_from</span><span class="o">=</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2024</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">UTC</span><span class="p">),</span>
<a id="__codelineno-2-44" name="__codelineno-2-44" href="#__codelineno-2-44"></a> <span class="n">date_to</span><span class="o">=</span><span class="n">datetime</span><span class="p">(</span><span class="mi">2024</span><span class="p">,</span> <span class="mi">2</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">UTC</span><span class="p">),</span>
<a id="__codelineno-2-45" name="__codelineno-2-45" href="#__codelineno-2-45"></a> <span class="n">datasets</span><span class="o">=</span><span class="p">{</span><span class="n">Dataset</span><span class="o">.</span><span class="n">rates</span><span class="p">,</span> <span class="n">Dataset</span><span class="o">.</span><span class="n">history_deals</span><span class="p">},</span>
<a id="__codelineno-2-46" name="__codelineno-2-46" href="#__codelineno-2-46"></a><span class="p">)</span>
</code></pre></div>
<p>Schema contracts live in <code>mt5cli.schemas</code> (<code>DataKind</code>, <code>validate_schema</code>, <code>normalize_dataframe</code>). Storage helpers are re-exported from <code>mt5cli.storage</code> and the package root.</p>
<p>Schema contracts live in <code>mt5cli.schemas</code> (<code>DataKind</code>, <code>validate_schema</code>, <code>normalize_dataframe</code>). Export and storage helpers are in <code>mt5cli.utils</code> (<code>Dataset</code>, <code>export_dataframe</code>) and <code>mt5cli.history</code>.</p>
<p><code>MT5Client.order_send()</code> is a live execution primitive: it can place real trades on the connected account. mt5cli does not implement strategy logic, signal generation, backtesting, or optimization — downstream applications must gate live execution explicitly (the CLI requires <code>--yes</code> for <code>order-send</code>).</p>
<p><code>MT5Client.mt5_summary()</code> returns structured nested Python values. Use <code>MT5Client.mt5_summary_as_df()</code> when you need a one-row DataFrame for export.</p>
<h2 id="quick-start">Quick Start<a class="headerlink" href="#quick-start" title="Permanent link">&para;</a></h2>
@@ -656,5 +648,5 @@
<!--
MkDocs version : 1.6.1
Build Date UTC : 2026-06-26 03:08:54.499202+00:00
Build Date UTC : 2026-06-26 09:24:20.959155+00:00
-->
objects.inv
BIN
View File
Binary file not shown.
search/search_index.json
+1 -1
View File
File diff suppressed because one or more lines are too long
sitemap.xml
-4
View File
@@ -40,10 +40,6 @@
<loc>https://github.com/dceoy/mt5cli/api/sdk/</loc>
<lastmod>2026-06-26</lastmod>
</url>
<url>
<loc>https://github.com/dceoy/mt5cli/api/storage/</loc>
<lastmod>2026-06-26</lastmod>
</url>
<url>
<loc>https://github.com/dceoy/mt5cli/api/trading/</loc>
<lastmod>2026-06-26</lastmod>
sitemap.xml.gz
BIN
View File
Binary file not shown.