mtcli-range 1.0.0.dev0__tar.gz

mtcli_range-1.0.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valmir França
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mtcli_range-1.0.0.dev0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: mtcli-range
+Version: 1.0.0.dev0
+Summary: Range bars  plugin para mtcli
+License-Expression: MIT
+License-File: LICENSE
+Keywords: trading,range,metatrader5,mt5,cli,price-action,tape-reading
+Author: Valmir França
+Author-email: vfranca3@gmail.com
+Requires-Python: >=3.10,<3.14
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Dist: click (>=8.3.0,<9.0.0)
+Requires-Dist: metatrader5 (>=5.0.5370,<6.0.0)
+Requires-Dist: mtcli (==3.5.*)
+Project-URL: Documentation, https://vfranca.github.io/mtcli-range
+Project-URL: Homepage, https://github.com/vfranca/mtcli-range
+Project-URL: Issues, https://github.com/vfranca/mtcli-range/issues
+Project-URL: Repository, https://github.com/vfranca/mtcli-range
+Description-Content-Type: text/markdown
+
+\# plugin-exemplo
+
+&nbsp; 
+
+Plugin do mtcli que adiciona o comando plugin de exemplo.
+
+&nbsp; 
+
+---
+
+&nbsp; 
+
+\## Instalação
+
+&nbsp; 
+
+```cmd
+
+git clone git@github.com:vfranca/plugin-exemplo.git
+
+cd plugin-exemplo
+
+pip install .
+
+```
+
+
+
+

mtcli_range-1.0.0.dev0/README.md

@@ -0,0 +1,28 @@
+\# plugin-exemplo
+
+  
+
+Plugin do mtcli que adiciona o comando plugin de exemplo.
+
+  
+
+---
+
+  
+
+\## Instalação
+
+  
+
+```cmd
+
+git clone git@github.com:vfranca/plugin-exemplo.git
+
+cd plugin-exemplo
+
+pip install .
+
+```
+
+
+

mtcli_range-1.0.0.dev0/mtcli_range/cli.py

@@ -0,0 +1,54 @@
+"""
+Interface CLI do plugin mtcli-range.
+
+Comando:
+    mt range
+"""
+
+import click
+from mtcli.logger import setup_logger
+from .range_controller import RangeController
+from .conf import (
+    get_default_symbol,
+    get_default_range,
+    get_default_timeframe,
+    get_default_bars,
+)
+
+log = setup_logger("mtcli.range.cli")
+
+
+@click.command("range")
+@click.version_option(package_name="mtcli-range")
+@click.option("-s", "--symbol", default=get_default_symbol(), show_default=True, help="Ativo.")
+@click.option("-t", "--timeframe", default=get_default_timeframe(), show_default=True, help="Timeframe base.")
+@click.option("-b", "--bars", default=get_default_bars(), show_default=True, help="Quantidade de candles base.")
+@click.option("-r", "--range-size", default=get_default_range(), show_default=True, help="Tamanho do range.")
+@click.option("--ancorar-abertura", is_flag=True, help="Inicia o Range a partir da abertura do primeiro candle.")
+@click.option("--numerar", is_flag=True, help="Numera as linhas exibidas.")
+def range_command(symbol, timeframe, bars, range_size, ancorar_abertura, numerar):
+    """
+    Exibe gráfico de Range no terminal.
+
+    Exemplos:
+
+        mt range -s WING26 -t m5 -b 1000 -r 60
+        mt range --ancorar-abertura
+        mt range --numerar
+    """
+
+    try:
+        controller = RangeController(
+            symbol=symbol,
+            timeframe=timeframe,
+            bars=bars,
+            range_size=range_size,
+            ancorar_abertura=ancorar_abertura,
+            numerar=numerar,
+        )
+
+        controller.executar()
+
+    except Exception as e:
+        log.error(f"Erro ao executar mt range: {e}")
+        click.echo(f"Erro: {e}")

mtcli_range-1.0.0.dev0/mtcli_range/conf.py

@@ -0,0 +1,41 @@
+"""
+Configuração do plugin mtcli-range.
+
+Lê parâmetros do arquivo mtcli.ini na seção [range].
+Permite definir valores padrão para:
+- símbolo
+- tamanho do range
+- timeframe base
+- quantidade de candles
+"""
+
+import configparser
+import os
+
+
+CONFIG_PATH = os.path.join(os.getcwd(), "mtcli.ini")
+
+config = configparser.ConfigParser()
+config.read(CONFIG_PATH)
+
+SECTION = "range"
+
+
+def get_default_symbol() -> str:
+    """Retorna símbolo padrão do arquivo .ini."""
+    return config.get(SECTION, "symbol", fallback="WIN$")
+
+
+def get_default_range() -> float:
+    """Retorna tamanho do range padrão."""
+    return config.getfloat(SECTION, "range_size", fallback=50.0)
+
+
+def get_default_timeframe() -> str:
+    """Retorna timeframe base padrão."""
+    return config.get(SECTION, "timeframe", fallback="m5")
+
+
+def get_default_bars() -> int:
+    """Retorna quantidade padrão de candles base."""
+    return config.getint(SECTION, "bars", fallback=500)

mtcli_range-1.0.0.dev0/mtcli_range/plugin.py

@@ -0,0 +1,6 @@
+from .cli import range_command
+
+
+def register(cli):
+    cli.add_command(range_command, name="range")
+    cli.add_command(range_command, name="r")

mtcli_range-1.0.0.dev0/mtcli_range/range_controller.py

@@ -0,0 +1,65 @@
+"""
+Controller do plugin mtcli-range.
+
+Orquestra:
+- Conexão MT5
+- Model
+- View
+"""
+
+from mtcli.mt5_context import mt5_conexao
+from mtcli.logger import setup_logger
+from mtcli.domain.timeframe import Timeframe
+from .range_model import RangeModel
+from .range_view import RangeView
+
+log = setup_logger("mtcli.range.controller")
+
+
+class RangeController:
+    """
+    Controlador principal do fluxo.
+    """
+
+    def __init__(
+        self,
+        symbol: str,
+        timeframe: str,
+        bars: int,
+        range_size: float,
+        ancorar_abertura: bool,
+        numerar: bool,
+    ):
+        self.symbol = symbol
+        self.timeframe = Timeframe.from_string(timeframe)
+        self.bars = bars
+        self.range_size = range_size
+        self.ancorar_abertura = ancorar_abertura
+        self.numerar = numerar
+
+    def executar(self):
+        """
+        Executa o fluxo completo do gráfico Range.
+        """
+
+        with mt5_conexao():
+            model = RangeModel(
+                self.symbol,
+                self.timeframe.mt5_const,
+                self.bars,
+                self.range_size,
+                ancorar_abertura=self.ancorar_abertura,
+            )
+
+            blocos = model.gerar_range()
+
+        RangeView.exibir_header(
+            self.symbol,
+            self.range_size,
+            self.ancorar_abertura,
+        )
+
+        RangeView.exibir_blocos(
+            blocos,
+            numerar=self.numerar,
+        )

mtcli_range-1.0.0.dev0/mtcli_range/range_model.py

@@ -0,0 +1,103 @@
+"""
+Model responsável pela geração dos blocos Range.
+
+O Range é baseado em movimentação de preço fixa (range_size).
+Um novo bloco é criado somente quando o preço se move
+range_size pontos acima ou abaixo do fechamento (ou abertura ancorada).
+"""
+
+from dataclasses import dataclass
+from typing import List
+import MetaTrader5 as mt5
+from mtcli.logger import setup_logger
+
+log = setup_logger("mtcli.range.model")
+
+
+@dataclass
+class RangeBlock:
+    """Representa um bloco de Range."""
+    open: float
+    close: float
+    direction: str  # "UP" ou "DOWN"
+
+
+class RangeModel:
+    """
+    Responsável por:
+    - Buscar dados no MT5
+    - Calcular blocos de Range
+    """
+
+    def __init__(
+        self,
+        symbol: str,
+        timeframe_const: int,
+        bars: int,
+        range_size: float,
+        ancorar_abertura: bool = False,
+    ):
+        self.symbol = symbol
+        self.timeframe_const = timeframe_const
+        self.bars = bars
+        self.range_size = range_size
+        self.ancorar_abertura = ancorar_abertura
+
+    def obter_candles(self):
+        """Obtém candles do MT5."""
+        log.info(f"Buscando {self.bars} candles de {self.symbol}")
+        rates = mt5.copy_rates_from_pos(
+            self.symbol,
+            self.timeframe_const,
+            0,
+            self.bars
+        )
+
+        if rates is None:
+            raise RuntimeError("Erro ao obter dados do MT5.")
+
+        return rates
+
+    def gerar_range(self) -> List[RangeBlock]:
+        """
+        Constrói blocos de Range a partir dos candles base.
+        """
+
+        rates = self.obter_candles()
+
+        if len(rates) == 0:
+            return []
+
+        blocos: List[RangeBlock] = []
+
+        # 🔹 Âncora inicial
+        if self.ancorar_abertura:
+            ultimo_preco_base = rates[0]["open"]
+            log.info("Range ancorado na abertura do primeiro candle.")
+        else:
+            ultimo_preco_base = rates[0]["close"]
+            log.info("Range iniciado a partir do fechamento do primeiro candle.")
+
+        for candle in rates[1:]:
+            preco = candle["close"]
+
+            while abs(preco - ultimo_preco_base) >= self.range_size:
+
+                if preco > ultimo_preco_base:
+                    novo_close = ultimo_preco_base + self.range_size
+                    direcao = "UP"
+                else:
+                    novo_close = ultimo_preco_base - self.range_size
+                    direcao = "DOWN"
+
+                bloco = RangeBlock(
+                    open=ultimo_preco_base,
+                    close=novo_close,
+                    direction=direcao
+                )
+
+                blocos.append(bloco)
+                ultimo_preco_base = novo_close
+
+        log.info(f"{len(blocos)} blocos de range gerados.")
+        return blocos

mtcli_range-1.0.0.dev0/mtcli_range/range_view.py

@@ -0,0 +1,66 @@
+"""
+View responsável pela saída no terminal.
+
+Layout linear, amigável para leitores de tela.
+Sem uso de gráficos ASCII complexos.
+"""
+
+from typing import List
+from mtcli.logger import setup_logger
+from .range_model import RangeBlock
+
+log = setup_logger("mtcli.range.view")
+
+
+class RangeView:
+    """
+    Responsável por exibir os blocos de forma textual estruturada.
+    """
+
+    @staticmethod
+    def exibir_header(symbol: str, range_size: float, ancorado: bool):
+        """Exibe cabeçalho descritivo."""
+        print("\n========================================")
+        print("GRÁFICO RANGE")
+        print("----------------------------------------")
+        print(f"Ativo: {symbol}")
+        print(f"Tamanho do Range: {range_size}")
+        print(f"Ancorado na abertura: {'SIM' if ancorado else 'NÃO'}")
+        print("========================================\n")
+
+    @staticmethod
+    def exibir_blocos(blocos: List[RangeBlock], numerar: bool):
+        """
+        Exibe blocos linha a linha.
+
+        numerar:
+            - True  -> exibe número da linha
+            - False -> não exibe numeração
+        """
+
+        if not blocos:
+            print("Nenhum bloco gerado.")
+            return
+
+        if numerar:
+            print("Número Direção Abertura Fechamento")
+            print("-----------------------------------")
+        else:
+            print("Direção Abertura Fechamento")
+            print("----------------------------")
+
+        for i, bloco in enumerate(blocos, start=1):
+
+            if numerar:
+                print(
+                    f"{i:>6} "
+                    f"{bloco.direction:<5} "
+                    f"{bloco.open:>8.0f} "
+                    f"{bloco.close:>10.0f}"
+                )
+            else:
+                print(
+                    f"{bloco.direction:<5} "
+                    f"{bloco.open:>8.0f} "
+                    f"{bloco.close:>10.0f}"
+                )

mtcli_range-1.0.0.dev0/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "mtcli-range"
+version = "1.0.0.dev0"
+description = "Range bars  plugin para mtcli"
+authors = [
+    { name = "Valmir França", email = "vfranca3@gmail.com" }
+]
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10,<3.14"
+
+keywords = [
+    "trading",
+    "range",
+    "metatrader5",
+    "mt5",
+    "cli",
+    "price-action",
+    "tape-reading"
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Office/Business :: Financial :: Investment",
+]
+
+dependencies = [
+    "mtcli>=3.5.0.dev0,<3.6.0.dev0",
+    "click>=8.3.0,<9.0.0",
+    "metatrader5>=5.0.5370,<6.0.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/vfranca/mtcli-range"
+Repository = "https://github.com/vfranca/mtcli-range"
+Issues = "https://github.com/vfranca/mtcli-range/issues"
+Documentation = "https://vfranca.github.io/mtcli-range"
+
+[project.entry-points."mtcli.plugins"]
+range = "mtcli_range.plugin:register"
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.4.2"
+pytest-cov = "^6.2.1"
+pytest-mock = "^3.15.1"
+ruff = "^0.14.1"
+
+[tool.poetry.group.docs.dependencies]
+mkdocs = "^1.6.1"
+pymdown-extensions = "^10.16.1"
+
+[tool.ruff]
+line-length = 88
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "B", "I", "UP", "N"]
+ignore = ["E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mtcli", "mtcli_range"]
+combine-as-imports = true
+force-sort-within-sections = true
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+line-ending = "auto"
+skip-magic-trailing-comma = false