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

deploy: 292fac899a

Browse Source
This commit is contained in:
dceoy
2026-06-23 16:59:18 +00:00
parent 35ac854ab0
commit e962a6adbf
7 changed files with 2270 additions and 1613 deletions
Download Patch File Download Diff File Expand all files Collapse all files
api/client/index.html
+62 -64
View File
@@ -232,9 +232,7 @@
<p>Public client for generic MT5 data access and order primitives.</p>
<p>Extends the read-only SDK client with optional order check/send helpers and
exposes the same connection lifecycle as :class:<code>~mt5cli.sdk.Mt5CliClient</code>.
Downstream applications such as private trading packages should prefer this
type over the legacy <code>Mt5CliClient</code> name.</p>
exposes the same connection lifecycle as :func:<code>mt5_session</code>.</p>
<p>mt5cli intentionally exposes minimal execution primitives only. Trading
decisions, signals, strategies, backtests, and optimization remain the
responsibility of downstream applications.</p>
@@ -380,21 +378,21 @@ responsibility of downstream applications.</p>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/client.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-65">65</a></span>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></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>
<span class="normal"><a href="#__codelineno-0-67">67</a></span>
<span class="normal"><a href="#__codelineno-0-68">68</a></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></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-65" name="__codelineno-0-65"></a><span class="nd">@classmethod</span>
<a id="__codelineno-0-66" name="__codelineno-0-66"></a><span class="k">def</span><span class="w"> </span><span class="nf">from_connected_client</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">client</span><span class="p">:</span> <span class="n">Mt5DataClient</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Self</span><span class="p">:</span>
<a id="__codelineno-0-67" name="__codelineno-0-67"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Bind to an already-connected ``Mt5DataClient`` without owning it.</span>
<a id="__codelineno-0-68" name="__codelineno-0-68"></a>
<a id="__codelineno-0-69" name="__codelineno-0-69"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-70" name="__codelineno-0-70"></a><span class="sd"> Client wrapper bound to the injected connection.</span>
<a id="__codelineno-0-71" name="__codelineno-0-71"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-72" name="__codelineno-0-72"></a> <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">client</span><span class="o">=</span><span class="n">client</span><span class="p">)</span>
<span class="normal"><a href="#__codelineno-0-70">70</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-63" name="__codelineno-0-63"></a><span class="nd">@classmethod</span>
<a id="__codelineno-0-64" name="__codelineno-0-64"></a><span class="k">def</span><span class="w"> </span><span class="nf">from_connected_client</span><span class="p">(</span><span class="bp">cls</span><span class="p">,</span> <span class="n">client</span><span class="p">:</span> <span class="n">Mt5DataClient</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Self</span><span class="p">:</span>
<a id="__codelineno-0-65" name="__codelineno-0-65"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Bind to an already-connected ``Mt5DataClient`` without owning it.</span>
<a id="__codelineno-0-66" name="__codelineno-0-66"></a>
<a id="__codelineno-0-67" name="__codelineno-0-67"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-68" name="__codelineno-0-68"></a><span class="sd"> Client wrapper bound to the injected connection.</span>
<a id="__codelineno-0-69" name="__codelineno-0-69"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-70" name="__codelineno-0-70"></a> <span class="k">return</span> <span class="bp">cls</span><span class="p">(</span><span class="n">client</span><span class="o">=</span><span class="n">client</span><span class="p">)</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
@@ -473,25 +471,25 @@ responsibility of downstream applications.</p>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/client.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-36">36</a></span>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></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></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-36" name="__codelineno-0-36"></a><span class="k">def</span><span class="w"> </span><span class="nf">order_check</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">:</span>
<a id="__codelineno-0-37" name="__codelineno-0-37"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Check funds sufficiency for a trade request.</span>
<a id="__codelineno-0-38" name="__codelineno-0-38"></a>
<a id="__codelineno-0-39" name="__codelineno-0-39"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-40" name="__codelineno-0-40"></a><span class="sd"> request: MT5 order request dictionary.</span>
<a id="__codelineno-0-41" name="__codelineno-0-41"></a>
<a id="__codelineno-0-42" name="__codelineno-0-42"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-43" name="__codelineno-0-43"></a><span class="sd"> One-row DataFrame with the order-check result.</span>
<a id="__codelineno-0-44" name="__codelineno-0-44"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-45" name="__codelineno-0-45"></a> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_fetch</span><span class="p">(</span><span class="k">lambda</span> <span class="n">client</span><span class="p">:</span> <span class="n">client</span><span class="o">.</span><span class="n">order_check_as_df</span><span class="p">(</span><span class="n">request</span><span class="o">=</span><span class="n">request</span><span class="p">))</span>
<span class="normal"><a href="#__codelineno-0-43">43</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-34" name="__codelineno-0-34"></a><span class="k">def</span><span class="w"> </span><span class="nf">order_check</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">:</span>
<a id="__codelineno-0-35" name="__codelineno-0-35"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Check funds sufficiency for a trade request.</span>
<a id="__codelineno-0-36" name="__codelineno-0-36"></a>
<a id="__codelineno-0-37" name="__codelineno-0-37"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-38" name="__codelineno-0-38"></a><span class="sd"> request: MT5 order request dictionary.</span>
<a id="__codelineno-0-39" name="__codelineno-0-39"></a>
<a id="__codelineno-0-40" name="__codelineno-0-40"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-41" name="__codelineno-0-41"></a><span class="sd"> One-row DataFrame with the order-check result.</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="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_fetch</span><span class="p">(</span><span class="k">lambda</span> <span class="n">client</span><span class="p">:</span> <span class="n">client</span><span class="o">.</span><span class="n">order_check_as_df</span><span class="p">(</span><span class="n">request</span><span class="o">=</span><span class="n">request</span><span class="p">))</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
@@ -579,7 +577,9 @@ not implement strategy logic, signal generation, or trade sizing.</p>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/client.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-47">47</a></span>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></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>
<span class="normal"><a href="#__codelineno-0-48">48</a></span>
<span class="normal"><a href="#__codelineno-0-49">49</a></span>
<span class="normal"><a href="#__codelineno-0-50">50</a></span>
@@ -593,25 +593,23 @@ not implement strategy logic, signal generation, or trade sizing.</p>
<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></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-47" name="__codelineno-0-47"></a><span class="k">def</span><span class="w"> </span><span class="nf">order_send</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">:</span>
<a id="__codelineno-0-48" name="__codelineno-0-48"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Send a live trade request to the MT5 trade server.</span>
<a id="__codelineno-0-49" name="__codelineno-0-49"></a>
<a id="__codelineno-0-50" name="__codelineno-0-50"></a><span class="sd"> Warning:</span>
<a id="__codelineno-0-51" name="__codelineno-0-51"></a><span class="sd"> This is a live execution primitive. A successful call can place,</span>
<a id="__codelineno-0-52" name="__codelineno-0-52"></a><span class="sd"> modify, or close real trades on the connected account. Downstream</span>
<a id="__codelineno-0-53" name="__codelineno-0-53"></a><span class="sd"> applications must gate usage explicitly (for example behind manual</span>
<a id="__codelineno-0-54" name="__codelineno-0-54"></a><span class="sd"> confirmation or application-specific risk controls). mt5cli does</span>
<a id="__codelineno-0-55" name="__codelineno-0-55"></a><span class="sd"> not implement strategy logic, signal generation, or trade sizing.</span>
<a id="__codelineno-0-56" name="__codelineno-0-56"></a>
<a id="__codelineno-0-57" name="__codelineno-0-57"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-58" name="__codelineno-0-58"></a><span class="sd"> request: MT5 order request dictionary.</span>
<a id="__codelineno-0-59" name="__codelineno-0-59"></a>
<a id="__codelineno-0-60" name="__codelineno-0-60"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-61" name="__codelineno-0-61"></a><span class="sd"> One-row DataFrame with the order-send result.</span>
<a id="__codelineno-0-62" name="__codelineno-0-62"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-63" name="__codelineno-0-63"></a> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_fetch</span><span class="p">(</span><span class="k">lambda</span> <span class="n">client</span><span class="p">:</span> <span class="n">client</span><span class="o">.</span><span class="n">order_send_as_df</span><span class="p">(</span><span class="n">request</span><span class="o">=</span><span class="n">request</span><span class="p">))</span>
<span class="normal"><a href="#__codelineno-0-61">61</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-45" name="__codelineno-0-45"></a><span class="k">def</span><span class="w"> </span><span class="nf">order_send</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">request</span><span class="p">:</span> <span class="nb">dict</span><span class="p">[</span><span class="nb">str</span><span class="p">,</span> <span class="n">Any</span><span class="p">])</span> <span class="o">-&gt;</span> <span class="n">pd</span><span class="o">.</span><span class="n">DataFrame</span><span class="p">:</span>
<a id="__codelineno-0-46" name="__codelineno-0-46"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Send a live trade request to the MT5 trade server.</span>
<a id="__codelineno-0-47" name="__codelineno-0-47"></a>
<a id="__codelineno-0-48" name="__codelineno-0-48"></a><span class="sd"> Warning:</span>
<a id="__codelineno-0-49" name="__codelineno-0-49"></a><span class="sd"> This is a live execution primitive. A successful call can place,</span>
<a id="__codelineno-0-50" name="__codelineno-0-50"></a><span class="sd"> modify, or close real trades on the connected account. Downstream</span>
<a id="__codelineno-0-51" name="__codelineno-0-51"></a><span class="sd"> applications must gate usage explicitly (for example behind manual</span>
<a id="__codelineno-0-52" name="__codelineno-0-52"></a><span class="sd"> confirmation or application-specific risk controls). mt5cli does</span>
<a id="__codelineno-0-53" name="__codelineno-0-53"></a><span class="sd"> not implement strategy logic, signal generation, or trade sizing.</span>
<a id="__codelineno-0-54" name="__codelineno-0-54"></a>
<a id="__codelineno-0-55" name="__codelineno-0-55"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-56" name="__codelineno-0-56"></a><span class="sd"> request: MT5 order request dictionary.</span>
<a id="__codelineno-0-57" name="__codelineno-0-57"></a>
<a id="__codelineno-0-58" name="__codelineno-0-58"></a><span class="sd"> Returns:</span>
<a id="__codelineno-0-59" name="__codelineno-0-59"></a><span class="sd"> One-row DataFrame with the order-send result.</span>
<a id="__codelineno-0-60" name="__codelineno-0-60"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-61" name="__codelineno-0-61"></a> <span class="k">return</span> <span class="bp">self</span><span class="o">.</span><span class="n">_fetch</span><span class="p">(</span><span class="k">lambda</span> <span class="n">client</span><span class="p">:</span> <span class="n">client</span><span class="o">.</span><span class="n">order_send_as_df</span><span class="p">(</span><span class="n">request</span><span class="o">=</span><span class="n">request</span><span class="p">))</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
@@ -952,7 +950,9 @@ attaches to a running terminal.</p>
<details class="mkdocstrings-source">
<summary>Source code in <code>mt5cli/client.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-75">75</a></span>
<div class="highlight"><table class="highlighttable"><tr><td class="linenos"><div class="linenodiv"><pre><span></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>
@@ -963,22 +963,20 @@ attaches to a running terminal.</p>
<span class="normal"><a href="#__codelineno-0-83">83</a></span>
<span class="normal"><a href="#__codelineno-0-84">84</a></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></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-75" name="__codelineno-0-75"></a><span class="nd">@contextmanager</span>
<a id="__codelineno-0-76" name="__codelineno-0-76"></a><span class="k">def</span><span class="w"> </span><span class="nf">mt5_session</span><span class="p">(</span><span class="n">config</span><span class="p">:</span> <span class="n">Mt5Config</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Iterator</span><span class="p">[</span><span class="n">MT5Client</span><span class="p">]:</span>
<a id="__codelineno-0-77" name="__codelineno-0-77"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Open an MT5 terminal session and yield a connected :class:`MT5Client`.</span>
<a id="__codelineno-0-78" name="__codelineno-0-78"></a>
<a id="__codelineno-0-79" name="__codelineno-0-79"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-80" name="__codelineno-0-80"></a><span class="sd"> config: MT5 connection configuration. Defaults to an empty config that</span>
<a id="__codelineno-0-81" name="__codelineno-0-81"></a><span class="sd"> attaches to a running terminal.</span>
<a id="__codelineno-0-82" name="__codelineno-0-82"></a>
<a id="__codelineno-0-83" name="__codelineno-0-83"></a><span class="sd"> Yields:</span>
<a id="__codelineno-0-84" name="__codelineno-0-84"></a><span class="sd"> Connected :class:`MT5Client` bound to the session.</span>
<a id="__codelineno-0-85" name="__codelineno-0-85"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-86" name="__codelineno-0-86"></a> <span class="n">mt5_config</span> <span class="o">=</span> <span class="n">config</span> <span class="ow">or</span> <span class="n">build_config</span><span class="p">()</span>
<a id="__codelineno-0-87" name="__codelineno-0-87"></a> <span class="k">with</span> <span class="n">connected_client</span><span class="p">(</span><span class="n">mt5_config</span><span class="p">)</span> <span class="k">as</span> <span class="n">client</span><span class="p">:</span>
<a id="__codelineno-0-88" name="__codelineno-0-88"></a> <span class="k">yield</span> <span class="n">MT5Client</span><span class="o">.</span><span class="n">from_connected_client</span><span class="p">(</span><span class="n">client</span><span class="p">)</span>
<span class="normal"><a href="#__codelineno-0-86">86</a></span></pre></div></td><td class="code"><div><pre><span></span><code><a id="__codelineno-0-73" name="__codelineno-0-73"></a><span class="nd">@contextmanager</span>
<a id="__codelineno-0-74" name="__codelineno-0-74"></a><span class="k">def</span><span class="w"> </span><span class="nf">mt5_session</span><span class="p">(</span><span class="n">config</span><span class="p">:</span> <span class="n">Mt5Config</span> <span class="o">|</span> <span class="kc">None</span> <span class="o">=</span> <span class="kc">None</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Iterator</span><span class="p">[</span><span class="n">MT5Client</span><span class="p">]:</span>
<a id="__codelineno-0-75" name="__codelineno-0-75"></a><span class="w"> </span><span class="sd">&quot;&quot;&quot;Open an MT5 terminal session and yield a connected :class:`MT5Client`.</span>
<a id="__codelineno-0-76" name="__codelineno-0-76"></a>
<a id="__codelineno-0-77" name="__codelineno-0-77"></a><span class="sd"> Args:</span>
<a id="__codelineno-0-78" name="__codelineno-0-78"></a><span class="sd"> config: MT5 connection configuration. Defaults to an empty config that</span>
<a id="__codelineno-0-79" name="__codelineno-0-79"></a><span class="sd"> attaches to a running terminal.</span>
<a id="__codelineno-0-80" name="__codelineno-0-80"></a>
<a id="__codelineno-0-81" name="__codelineno-0-81"></a><span class="sd"> Yields:</span>
<a id="__codelineno-0-82" name="__codelineno-0-82"></a><span class="sd"> Connected :class:`MT5Client` bound to the session.</span>
<a id="__codelineno-0-83" name="__codelineno-0-83"></a><span class="sd"> &quot;&quot;&quot;</span>
<a id="__codelineno-0-84" name="__codelineno-0-84"></a> <span class="n">mt5_config</span> <span class="o">=</span> <span class="n">config</span> <span class="ow">or</span> <span class="n">build_config</span><span class="p">()</span>
<a id="__codelineno-0-85" name="__codelineno-0-85"></a> <span class="k">with</span> <span class="n">connected_client</span><span class="p">(</span><span class="n">mt5_config</span><span class="p">)</span> <span class="k">as</span> <span class="n">client</span><span class="p">:</span>
<a id="__codelineno-0-86" name="__codelineno-0-86"></a> <span class="k">yield</span> <span class="n">MT5Client</span><span class="o">.</span><span class="n">from_connected_client</span><span class="p">(</span><span class="n">client</span><span class="p">)</span>
</code></pre></div></td></tr></table></div>
</details>
</div>
api/public-contract/index.html
+142 -56
View File
@@ -133,10 +133,18 @@
<li class="nav-item" data-bs-level="1"><a href="#public-api-contract" class="nav-link">Public API Contract</a>
<ul class="nav flex-column">
<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>
<ul class="nav flex-column">
</ul>
</li>
<li class="nav-item" data-bs-level="2"><a href="#cli-commands" class="nav-link">CLI commands</a>
<ul class="nav flex-column">
</ul>
@@ -166,12 +174,35 @@ Python applications. The intended dependency direction is:</p>
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>downstream app -&gt; mt5cli -&gt; pdmt5 -&gt; MetaTrader 5
</code></pre></div>
<p>Downstream packages should import from the package root (<code>from mt5cli import
...</code>) and treat the symbols listed below as the stable SDK contract. CLI
commands mirror the same behavior but are not importable Python APIs.</p>
...</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>
<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
<code>mt5cli.STABLE_SDK_EXPORTS</code> (defined in <code>mt5cli.contract</code>). Prefer <code>MT5Client</code> over the legacy <code>Mt5CliClient</code>
alias for new code.</p>
<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>
<thead>
@@ -182,7 +213,7 @@ alias for new code.</p>
</thead>
<tbody>
<tr>
<td><code>MT5Client</code>, <code>Mt5CliClient</code></td>
<td><code>MT5Client</code></td>
<td>Read-only data client with optional <code>order_check</code> / <code>order_send</code></td>
</tr>
<tr>
@@ -220,42 +251,6 @@ additionally expand strings whose entire value is a bare <code>$ENV_NAME</code>
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="read-only-mt5-data-access">Read-only MT5 data access<a class="headerlink" href="#read-only-mt5-data-access" 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>
</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="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
@@ -293,10 +288,6 @@ timestamp normalization in downstream apps.</p>
<td>Same data keyed by <code>(symbol, granularity_name)</code></td>
</tr>
<tr>
<td><code>collect_latest_rates_for_accounts</code></td>
<td>Latest bars including the forming bar when <code>start_pos=0</code></td>
</tr>
<tr>
<td><code>collect_latest_rates_for_accounts_with_retries</code></td>
<td>Bounded exponential backoff for transient MT5 errors</td>
</tr>
@@ -366,6 +357,10 @@ strategy entries, exits, Kelly sizing, or signal logic.</p>
<td>Normalized account/symbol/tick/position views</td>
</tr>
<tr>
<td><code>extract_tick_price</code></td>
<td>Positive finite bid/ask extraction from tick mappings</td>
</tr>
<tr>
<td><code>detect_position_side</code></td>
<td>Net long / short / flat from open positions</td>
</tr>
@@ -390,15 +385,27 @@ strategy entries, exits, Kelly sizing, or signal logic.</p>
<td>Summed total margin across symbols (failed symbols skipped)</td>
</tr>
<tr>
<td><code>calculate_projected_margin_ratio</code></td>
<td>Estimated symbol margin/equity after optional new exposure</td>
</tr>
<tr>
<td><code>calculate_symbol_group_margin_ratio</code></td>
<td>Estimated symbol-group margin/equity with optional exposure</td>
</tr>
<tr>
<td><code>determine_order_limits</code></td>
<td>SL/TP price levels from ratios</td>
</tr>
<tr>
<td><code>calculate_trailing_stop_updates</code></td>
<td>Per-ticket generic trailing stop-loss update plan</td>
</tr>
<tr>
<td><code>ensure_symbol_selected</code></td>
<td>Select/verify Market Watch visibility</td>
</tr>
<tr>
<td><code>place_market_order</code>, <code>close_open_positions</code>, <code>update_sltp_for_open_positions</code></td>
<td><code>place_market_order</code>, <code>close_open_positions</code>, <code>update_sltp_for_open_positions</code>, <code>update_trailing_stop_loss_for_open_positions</code></td>
<td>Order execution helpers (<code>dry_run</code> supported)</td>
</tr>
<tr>
@@ -445,12 +452,91 @@ and returned as <code>status="failed"</code> with normalized <code>request</code
</tr>
</tbody>
</table>
<h3 id="additional-public-exports-secondary">Additional public exports (secondary)<a class="headerlink" href="#additional-public-exports-secondary" title="Permanent link">&para;</a></h3>
<p>The package root also exports schema, storage, and parsing helpers (for example
<code>DataKind</code>, <code>Dataset</code>, <code>normalize_dataframe</code>, <code>export_dataframe</code>,
<code>parse_timeframe</code>, <code>TIMEFRAME_MAP</code>). These are public but oriented toward export
pipelines and advanced integration. Prefer the stable symbols above for core
infrastructure.</p>
<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>, <code>TICK_FLAG_MAP</code>, <code>TIMEFRAME_MAP</code></td>
</tr>
<tr>
<td>Trading data shapes</td>
<td><code>POSITION_COLUMNS</code></td>
</tr>
</tbody>
</table>
<h2 id="cli-commands">CLI commands<a class="headerlink" href="#cli-commands" title="Permanent link">&para;</a></h2>
<p>The Typer application in <code>mt5cli.cli</code> exposes file-export commands documented in
<a href="../cli/">CLI Module</a> and the project README. CLI commands:</p>
@@ -512,10 +598,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 <code>STABLE_SDK_EXPORTS</code> is
importable from <code>mt5cli</code>, documents key closed-bar, rate-view, SQLite loading,
account-resolution, and trading-session behaviors, and keeps the contract set
aligned with <code>__all__</code>.</p></div>
<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>
</div>
</div>
api/sdk/index.html
+3 -3
View File
@@ -8499,7 +8499,7 @@ failure is re-raised once <code>retry_count</code> is exhausted.</p>
</code></pre></div>
<h3 id="latest-closed-rate-bars">Latest closed rate bars<a class="headerlink" href="#latest-closed-rate-bars" title="Permanent link">&para;</a></h3>
<p>MetaTrader 5 <code>start_pos=0</code> includes the still-forming current bar as the last
row. <code>fetch_latest_closed_rates()</code> handles one connected <code>Mt5CliClient</code>; use
row. <code>fetch_latest_closed_rates()</code> handles one connected <code>MT5Client</code>; use
<code>fetch_latest_closed_rates_for_trading_client()</code> from an active
<code>Mt5TradingClient</code> session. Multi-account helpers fetch <code>count + 1</code> bars, drop
that row with <code>drop_forming_rate_bar()</code>, and validate each series is non-empty. Returned frames are ordered
@@ -8618,8 +8618,8 @@ runs before any MT5 or SQLite calls, but when <code>suppress_errors=True</code>
resulting <code>ValueError</code> is suppressed along with other recoverable errors.</p>
<h2 id="trading-capable-sessions">Trading-capable sessions<a class="headerlink" href="#trading-capable-sessions" title="Permanent link">&para;</a></h2>
<p>For order placement and trading calculations, use the dedicated
<a href="../trading/">Trading module</a>. The read-only <code>Mt5CliClient</code> and <code>mt5_session()</code>
helpers in this module are unchanged.</p></div>
<a href="../trading/">Trading module</a>. Use <code>mt5_session()</code> / <code>MT5Client</code> for read-only
collection.</p></div>
</div>
</div>
api/trading/index.html
+2060 -1487
View File
File diff suppressed because it is too large Load Diff
index.html
+2 -2
View File
@@ -211,7 +211,7 @@
<div class="highlight"><pre><span></span><code><a id="__codelineno-0-1" name="__codelineno-0-1" href="#__codelineno-0-1"></a>pip<span class="w"> </span>install<span class="w"> </span>mt5cli
</code></pre></div>
<h2 id="python-api-for-downstream-packages">Python API for downstream packages<a class="headerlink" href="#python-api-for-downstream-packages" title="Permanent link">&para;</a></h2>
<p>Import <code>MT5Client</code> for generic MT5 data access, schema normalization, and optional order primitives. <code>Mt5CliClient</code> remains available as a backward-compatible alias.</p>
<p>Import <code>MT5Client</code> for generic MT5 data access, schema normalization, and optional order primitives.</p>
<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">datetime</span><span class="w"> </span><span class="kn">import</span> <span class="n">UTC</span><span class="p">,</span> <span class="n">datetime</span>
<a id="__codelineno-1-2" name="__codelineno-1-2" href="#__codelineno-1-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-1-3" name="__codelineno-1-3" href="#__codelineno-1-3"></a>
@@ -653,5 +653,5 @@
<!--
MkDocs version : 1.6.1
Build Date UTC : 2026-06-23 12:42:20.097301+00:00
Build Date UTC : 2026-06-23 16:59:16.696241+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