mtcli 3.6.0.dev0__tar.gz → 3.6.1__tar.gz

{mtcli-3.6.0.dev0 → mtcli-3.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mtcli
-Version: 3.6.0.dev0
+Version: 3.6.1
 Summary: Aplicativo CLI para exibir gráficos do MetaTrader 5 screen reader friendly
 License-Expression: MIT
 License-File: LICENSE

mtcli-3.6.1/mtcli/cli.py

@@ -0,0 +1,34 @@
+"""
+CLI principal do mtcli.
+
+Este módulo define o grupo principal `mt`
+e inicializa o carregamento de plugins.
+"""
+
+import click
+
+from mtcli.plugin_loader import load_plugins
+from .commands.bars import bars
+
+
+@click.group(context_settings={"max_content_width": 120})
+@click.version_option(package_name="mtcli")
+def mt():
+    """
+    CLI principal do mtcli.
+
+    Exibe gráficos e informações de mercado
+    em formato textual compatível com leitores de tela.
+    """
+    pass
+
+
+mt.add_command(bars, name="bars")
+
+
+# Carrega plugins automaticamente
+load_plugins(mt)
+
+
+if __name__ == "__main__":
+    mt()

{mtcli-3.6.0.dev0 → mtcli-3.6.1}/mtcli/conf.py

@@ -1,199 +1,199 @@
-"""
-Configurações principais do mtcli.
-
-Este módulo centraliza a leitura de configurações provenientes de:
-
-1. Variáveis de ambiente
-2. Arquivo mtcli.ini
-
-As variáveis de ambiente sempre têm prioridade sobre o arquivo INI.
-
-Também fornece utilidades para obter o caminho de arquivos do
-terminal MetaTrader5 e selecionar a fonte de dados (CSV ou MT5).
-
-O acesso ao terminal MT5 é realizado apenas sob demanda para evitar
-efeitos colaterais durante a importação do módulo (import side effects),
-facilitando testes automatizados e execução em ambientes CI/CD.
-"""
-
-import os
-import configparser
-
-import MetaTrader5 as mt5
-
-from mtcli.mt5_context import mt5_conexao
-
-# ---------------------------------------------------------
-# Carregamento do arquivo de configuração
-# ---------------------------------------------------------
-
-CONFIG_FILE = "mtcli.ini"
-SECTION = "DEFAULT"
-
-config = configparser.ConfigParser()
-config.read(CONFIG_FILE)
-
-
-def get_config_value(key: str, cast=None, fallback=None):
-    """
-    Retorna um valor de configuração.
-
-    A prioridade de leitura é:
-    1. Variável de ambiente
-    2. Arquivo mtcli.ini
-    3. Valor fallback
-
-    Args:
-        key (str): Nome da chave de configuração.
-        cast (type | None): Tipo de conversão (ex: int, float).
-        fallback (Any): Valor padrão caso não encontrado.
-
-    Returns:
-        Any: valor convertido ou fallback.
-    """
-    value = os.getenv(key)
-
-    if value is None:
-        try:
-            if cast == int:
-                value = config.getint(SECTION, key, fallback=fallback)
-            elif cast == float:
-                value = config.getfloat(SECTION, key, fallback=fallback)
-            else:
-                value = config.get(SECTION, key, fallback=fallback)
-        except (configparser.NoOptionError, ValueError):
-            value = fallback
-    else:
-        if cast:
-            try:
-                value = cast(value)
-            except ValueError:
-                value = fallback
-
-    return value
-
-
-# ---------------------------------------------------------
-# Configurações gerais
-# ---------------------------------------------------------
-
-SYMBOL = get_config_value("symbol", fallback="WIN$N")
-DIGITOS = get_config_value("digitos", cast=int, fallback=2)
-PERIOD = get_config_value("period", fallback="D1")
-BARS = get_config_value("count", cast=int, fallback=999)
-
-VIEW = get_config_value("view", fallback="ch")
-VOLUME = get_config_value("volume", fallback="tick")
-DATE = get_config_value("date", fallback="")
-
-# ---------------------------------------------------------
-# Configurações de leitura de candles
-# ---------------------------------------------------------
-
-LATERAL = get_config_value("lateral", fallback="doji")
-ALTA = get_config_value("alta", fallback="verde")
-BAIXA = get_config_value("baixa", fallback="vermelho")
-
-ROMPIMENTO_ALTA = get_config_value("rompimento_alta", fallback="c")
-ROMPIMENTO_BAIXA = get_config_value("rompimento_baixa", fallback="v")
-
-PERCENTUAL_ROMPIMENTO = get_config_value(
-    "percentual_rompimento", cast=int, fallback=50
-)
-
-PERCENTUAL_DOJI = get_config_value(
-    "percentual_doji", cast=int, fallback=10
-)
-
-# ---------------------------------------------------------
-# Configurações de padrões de barra
-# ---------------------------------------------------------
-
-UP_BAR = get_config_value("up_bar", fallback="asc")
-DOWN_BAR = get_config_value("down_bar", fallback="desc")
-
-INSIDE_BAR = get_config_value("inside_bar", fallback="ib")
-OUTSIDE_BAR = get_config_value("outside_bar", fallback="ob")
-
-SOMBRA_SUPERIOR = get_config_value("sombra_superior", fallback="top")
-SOMBRA_INFERIOR = get_config_value("sombra_inferior", fallback="bottom")
-
-# ---------------------------------------------------------
-# Fonte de dados
-# ---------------------------------------------------------
-
-DATA_SOURCE = get_config_value("dados", fallback="mt5").lower()
-
-# caminho inicial (pode vir do ini/env)
-_INITIAL_CSV_PATH = get_config_value("mt5_pasta", fallback="")
-
-
-def get_csv_path():
-    """
-    Retorna o caminho da pasta de arquivos do MT5 ou CSV.
-
-    Se o caminho não estiver definido no mtcli.ini ou nas
-    variáveis de ambiente, o terminal MT5 é consultado para
-    descobrir automaticamente a pasta MQL5/Files.
-
-    Returns:
-        str: caminho normalizado da pasta de arquivos.
-    """
-    if _INITIAL_CSV_PATH:
-        path = _INITIAL_CSV_PATH
-    else:
-        with mt5_conexao():
-            terminal_info = mt5.terminal_info()
-
-            if terminal_info is None:
-                raise RuntimeError(
-                    "Não foi possível obter as informações do terminal MT5."
-                )
-
-        path = os.path.join(terminal_info.data_path, "MQL5", "Files")
-
-    return os.path.normpath(path) + os.sep
-
-
-# ---------------------------------------------------------
-# Factory de DataSource
-# ---------------------------------------------------------
-
-def get_data_source(source=None):
-    """
-    Retorna a fonte de dados configurada.
-
-    Args:
-        source (str | None): sobrescreve DATA_SOURCE se fornecido.
-
-    Returns:
-        CsvDataSource | MT5DataSource
-
-    Raises:
-        ValueError: se a fonte de dados não for reconhecida.
-    """
-    from mtcli.data import CsvDataSource, MT5DataSource
-
-    src = source.lower() if source else DATA_SOURCE
-
-    if src == "csv":
-        return CsvDataSource()
-
-    if src == "mt5":
-        return MT5DataSource()
-
-    raise ValueError(f"Fonte de dados desconhecida: {src}")
-
-
-# ---------------------------------------------------------
-# Timeframes suportados
-# ---------------------------------------------------------
-
-_HOURS = [12, 8, 6, 4, 3, 2, 1]
-_MINUTES = [30, 20, 15, 12, 10, 6, 5, 4, 3, 2, 1]
-
-TIMEFRAMES = (
-    ["mn1", "w1", "d1"]
-    + [f"h{i}" for i in _HOURS]
-    + [f"m{i}" for i in _MINUTES]
-)
+"""
+Configurações principais do mtcli.
+
+Este módulo centraliza a leitura de configurações provenientes de:
+
+1. Variáveis de ambiente
+2. Arquivo mtcli.ini
+
+As variáveis de ambiente sempre têm prioridade sobre o arquivo INI.
+
+Também fornece utilidades para obter o caminho de arquivos do
+terminal MetaTrader5 e selecionar a fonte de dados (CSV ou MT5).
+
+O acesso ao terminal MT5 é realizado apenas sob demanda para evitar
+efeitos colaterais durante a importação do módulo (import side effects),
+facilitando testes automatizados e execução em ambientes CI/CD.
+"""
+
+import os
+import configparser
+
+import MetaTrader5 as mt5
+
+from mtcli.mt5_context import mt5_conexao
+
+# ---------------------------------------------------------
+# Carregamento do arquivo de configuração
+# ---------------------------------------------------------
+
+CONFIG_FILE = "mtcli.ini"
+SECTION = "DEFAULT"
+
+config = configparser.ConfigParser()
+config.read(CONFIG_FILE)
+
+
+def get_config_value(key: str, cast=None, fallback=None):
+    """
+    Retorna um valor de configuração.
+
+    A prioridade de leitura é:
+    1. Variável de ambiente
+    2. Arquivo mtcli.ini
+    3. Valor fallback
+
+    Args:
+        key (str): Nome da chave de configuração.
+        cast (type | None): Tipo de conversão (ex: int, float).
+        fallback (Any): Valor padrão caso não encontrado.
+
+    Returns:
+        Any: valor convertido ou fallback.
+    """
+    value = os.getenv(key)
+
+    if value is None:
+        try:
+            if cast == int:
+                value = config.getint(SECTION, key, fallback=fallback)
+            elif cast == float:
+                value = config.getfloat(SECTION, key, fallback=fallback)
+            else:
+                value = config.get(SECTION, key, fallback=fallback)
+        except (configparser.NoOptionError, ValueError):
+            value = fallback
+    else:
+        if cast:
+            try:
+                value = cast(value)
+            except ValueError:
+                value = fallback
+
+    return value
+
+
+# ---------------------------------------------------------
+# Configurações gerais
+# ---------------------------------------------------------
+
+SYMBOL = get_config_value("symbol", fallback="WIN$N")
+DIGITOS = get_config_value("digitos", cast=int, fallback=2)
+PERIOD = get_config_value("period", fallback="D1")
+BARS = get_config_value("count", cast=int, fallback=999)
+
+VIEW = get_config_value("view", fallback="ch")
+VOLUME = get_config_value("volume", fallback="tick")
+DATE = get_config_value("date", fallback="")
+
+# ---------------------------------------------------------
+# Configurações de leitura de candles
+# ---------------------------------------------------------
+
+LATERAL = get_config_value("lateral", fallback="doji")
+ALTA = get_config_value("alta", fallback="verde")
+BAIXA = get_config_value("baixa", fallback="vermelho")
+
+ROMPIMENTO_ALTA = get_config_value("rompimento_alta", fallback="c")
+ROMPIMENTO_BAIXA = get_config_value("rompimento_baixa", fallback="v")
+
+PERCENTUAL_ROMPIMENTO = get_config_value(
+    "percentual_rompimento", cast=int, fallback=50
+)
+
+PERCENTUAL_DOJI = get_config_value(
+    "percentual_doji", cast=int, fallback=10
+)
+
+# ---------------------------------------------------------
+# Configurações de padrões de barra
+# ---------------------------------------------------------
+
+UP_BAR = get_config_value("up_bar", fallback="asc")
+DOWN_BAR = get_config_value("down_bar", fallback="desc")
+
+INSIDE_BAR = get_config_value("inside_bar", fallback="ib")
+OUTSIDE_BAR = get_config_value("outside_bar", fallback="ob")
+
+SOMBRA_SUPERIOR = get_config_value("sombra_superior", fallback="top")
+SOMBRA_INFERIOR = get_config_value("sombra_inferior", fallback="bottom")
+
+# ---------------------------------------------------------
+# Fonte de dados
+# ---------------------------------------------------------
+
+DATA_SOURCE = get_config_value("dados", fallback="mt5").lower()
+
+# caminho inicial (pode vir do ini/env)
+_INITIAL_CSV_PATH = get_config_value("mt5_pasta", fallback="")
+
+
+def get_csv_path():
+    """
+    Retorna o caminho da pasta de arquivos do MT5 ou CSV.
+
+    Se o caminho não estiver definido no mtcli.ini ou nas
+    variáveis de ambiente, o terminal MT5 é consultado para
+    descobrir automaticamente a pasta MQL5/Files.
+
+    Returns:
+        str: caminho normalizado da pasta de arquivos.
+    """
+    if _INITIAL_CSV_PATH:
+        path = _INITIAL_CSV_PATH
+    else:
+        with mt5_conexao():
+            terminal_info = mt5.terminal_info()
+
+            if terminal_info is None:
+                raise RuntimeError(
+                    "Não foi possível obter as informações do terminal MT5."
+                )
+
+        path = os.path.join(terminal_info.data_path, "MQL5", "Files")
+
+    return os.path.normpath(path) + os.sep
+
+
+# ---------------------------------------------------------
+# Factory de DataSource
+# ---------------------------------------------------------
+
+def get_data_source(source=None):
+    """
+    Retorna a fonte de dados configurada.
+
+    Args:
+        source (str | None): sobrescreve DATA_SOURCE se fornecido.
+
+    Returns:
+        CsvDataSource | MT5DataSource
+
+    Raises:
+        ValueError: se a fonte de dados não for reconhecida.
+    """
+    from mtcli.data import CsvDataSource, MT5DataSource
+
+    src = source.lower() if source else DATA_SOURCE
+
+    if src == "csv":
+        return CsvDataSource()
+
+    if src == "mt5":
+        return MT5DataSource()
+
+    raise ValueError(f"Fonte de dados desconhecida: {src}")
+
+
+# ---------------------------------------------------------
+# Timeframes suportados
+# ---------------------------------------------------------
+
+_HOURS = [12, 8, 6, 4, 3, 2, 1]
+_MINUTES = [30, 20, 15, 12, 10, 6, 5, 4, 3, 2, 1]
+
+TIMEFRAMES = (
+    ["mn1", "w1", "d1"]
+    + [f"h{i}" for i in _HOURS]
+    + [f"m{i}" for i in _MINUTES]
+)

{mtcli-3.6.0.dev0 → mtcli-3.6.1}/mtcli/data/csv.py

@@ -1,31 +1,31 @@
-"""Módulo fonte de dados via CSV."""
-
-import csv
-import os
-
-from mtcli import conf
-from mtcli.logger import setup_logger
-
-from .base import DataSourceBase
-
-logger = setup_logger()
-
-
-class CsvDataSource(DataSourceBase):
-    """Fonte de dados via CSV."""
-
-    def get_data(self, symbol, period, count=100):
-        """Retorna dados CSV em uma lista de lista."""
-        file_path = os.path.join(conf._INITIAL_CSV_PATH, f"{symbol}{period}.csv")
-        logger.info(f"Iniciando coleta de dados via CSV: {file_path}.")
-        csv_data = []
-        try:
-            with open(file_path, encoding="utf-16", newline="") as f:
-                lines = csv.reader(f, delimiter=",", quotechar="'")
-                for line in lines:
-                    csv_data.append(line)
-        except:
-            logger.warning(f"Arquivo {file_path} não encontrado.")
-            print("Arquivo %s nao encontrado! Tente novamente" % file_path)
-        logger.info("Coleta de dados via CSV finalizada.")
-        return csv_data
+"""Módulo fonte de dados via CSV."""
+
+import csv
+import os
+
+from mtcli import conf
+from mtcli.logger import setup_logger
+
+from .base import DataSourceBase
+
+logger = setup_logger()
+
+
+class CsvDataSource(DataSourceBase):
+    """Fonte de dados via CSV."""
+
+    def get_data(self, symbol, period, count=100):
+        """Retorna dados CSV em uma lista de lista."""
+        file_path = os.path.join(conf._INITIAL_CSV_PATH, f"{symbol}{period}.csv")
+        logger.info(f"Iniciando coleta de dados via CSV: {file_path}.")
+        csv_data = []
+        try:
+            with open(file_path, encoding="utf-16", newline="") as f:
+                lines = csv.reader(f, delimiter=",", quotechar="'")
+                for line in lines:
+                    csv_data.append(line)
+        except:
+            logger.warning(f"Arquivo {file_path} não encontrado.")
+            print("Arquivo %s nao encontrado! Tente novamente" % file_path)
+        logger.info("Coleta de dados via CSV finalizada.")
+        return csv_data

mtcli-3.6.1/mtcli/logger.py

@@ -0,0 +1,136 @@
+"""
+Sistema central de logging do mtcli.
+
+Este módulo fornece uma função única `setup_logger()` utilizada por todo
+o ecossistema de plugins do mtcli para configurar logging consistente.
+
+Características principais
+--------------------------
+
+✔ Arquivo de log rotativo em:
+  %APPDATA%/mtcli/logs/mtcli.log
+
+✔ Rotação automática:
+  - tamanho máximo: 2 MB
+  - até 3 arquivos de backup
+
+✔ Proteção contra duplicação de handlers quando plugins
+  inicializam o logger múltiplas vezes.
+
+✔ Encoding UTF-8 garantido (evita problemas de acentuação
+  no Windows).
+
+✔ Compatível com pytest (caplog).
+
+Observação
+----------
+
+Os logs **não são exibidos no console**.
+Toda saída é direcionada exclusivamente para o arquivo de log.
+"""
+
+import logging
+from logging.handlers import RotatingFileHandler
+import os
+
+
+# ==========================================================
+# DIRETÓRIO DE LOG
+# ==========================================================
+
+base_dir = os.getenv("APPDATA", os.path.expanduser("~"))
+
+LOG_DIR = os.path.join(base_dir, "mtcli", "logs")
+
+os.makedirs(LOG_DIR, exist_ok=True)
+
+LOG_FILE = os.path.join(LOG_DIR, "mtcli.log")
+
+
+# ==========================================================
+# LOGGER SETUP
+# ==========================================================
+
+def setup_logger(name: str = "mtcli") -> logging.Logger:
+    """
+    Cria ou retorna um logger configurado para o mtcli.
+
+    O logger utiliza **apenas um handler de arquivo rotativo**.
+    Nenhuma saída é enviada ao console.
+
+    A função é **idempotente**, ou seja, pode ser chamada
+    múltiplas vezes sem duplicar handlers.
+
+    Parameters
+    ----------
+    name : str
+        Nome do logger (normalmente `__name__`).
+
+    Returns
+    -------
+    logging.Logger
+        Instância configurada do logger.
+    """
+
+    logger = logging.getLogger(name)
+
+    logger.setLevel(logging.DEBUG)
+
+    formatter = logging.Formatter(
+        "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+
+    # ======================================================
+    # REMOVE STREAM HANDLERS (garante silêncio no console)
+    # ======================================================
+
+    for handler in list(logger.handlers):
+        if isinstance(handler, logging.StreamHandler) and not isinstance(handler, RotatingFileHandler):
+            logger.removeHandler(handler)
+
+    # ======================================================
+    # FILE HANDLER ROTATIVO
+    # ======================================================
+
+    file_handler_exists = any(
+        isinstance(h, RotatingFileHandler) for h in logger.handlers
+    )
+
+    if not file_handler_exists:
+
+        file_handler = RotatingFileHandler(
+            LOG_FILE,
+            maxBytes=2_000_000,
+            backupCount=3,
+            encoding="utf-8",
+            delay=True,
+        )
+
+        file_handler.setFormatter(formatter)
+
+        logger.addHandler(file_handler)
+
+    # ======================================================
+    # PROPAGATION
+    # ======================================================
+
+    # Permite que pytest caplog capture logs
+    logger.propagate = True
+
+    return logger
+
+
+# ==========================================================
+# LOGGER PADRÃO DO MTCLI
+# ==========================================================
+
+"""
+Logger padrão utilizado por módulos internos do mtcli.
+
+Plugins geralmente criam seu próprio logger usando:
+
+    setup_logger(__name__)
+"""
+
+log = setup_logger()