mtcli-volume 2.4.0.dev0__tar.gz → 2.4.1__tar.gz

mtcli_volume-2.4.1/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: mtcli-volume
+Version: 2.4.1
+Summary: Plugin mtcli para cálculo e exibição de Volume Profile no terminal
+License-File: LICENSE
+Author: Valmir França
+Author-email: vfranca3@gmail.com
+Maintainer: Valmir França
+Maintainer-email: vfranca3@gmail.com
+Requires-Python: >=3.10,<3.14
+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
+Requires-Dist: click (>=8.3.0,<9.0.0)
+Requires-Dist: metatrader5 (>=5.0.5370,<6.0.0)
+Requires-Dist: mtcli (>=3.2.0)
+Requires-Dist: tzdata (>=2025.2)
+Project-URL: Documentation, https://mtcli-volume.readthedocs.io
+Project-URL: Homepage, https://github.com/vfranca/mtcli-volume
+Project-URL: Repository, https://github.com/vfranca/mtcli-volume
+Project-URL: issues, https://github.com/vfranca/mtcli-volume/issues
+Description-Content-Type: text/markdown
+
+# mtcli-volume
+
+Plugin do **mtcli** para cálculo e visualização de **Volume Profile** diretamente no terminal, com foco em:
+
+- Precisão técnica (distribuição High–Low)
+- Leitura profissional de mercado
+- Total acessibilidade (screen reader friendly)
+- Integração com MetaTrader 5
+
+---
+
+## Principais recursos
+
+- **Volume Profile por faixa High–Low**
+  - O volume de cada candle é distribuído uniformemente entre todas as faixas de preço tocadas entre o **LOW** e o **HIGH**
+  - Modelo mais próximo do Volume Profile clássico (VAP)
+
+- **Estatísticas de Market Profile**
+  - POC (Point of Control)
+  - Área de Valor (70%)
+  - HVNs e LVNs com critérios profissionais
+
+- ⚙️ **Critérios avançados para HVN/LVN**
+  - Baseado na média (multiplicadores)
+  - Baseado em percentis (ex: 80% / 20%)
+
+- **100% acessível**
+  - Saída textual linear
+  - Compatível com NVDA, JAWS e leitores de tela
+  - Sem dependência de cores ou gráficos visuais
+
+- **Arquitetura MVC**
+  - Model: cálculos e dados
+  - Controller: fluxo de negócio
+  - View: apresentação no terminal
+  - CLI: interface de linha de comando
+
+---
+
+## Instalação
+
+Via PyPI:
+
+```bash
+pip install mtcli-volume
+````
+
+Ou com Poetry:
+
+```bash
+poetry add mtcli-volume
+```
+
+> ⚠️ Requer MetaTrader 5 instalado e configurado corretamente no sistema.
+
+---
+
+## Uso básico
+
+Após a instalação, o comando é registrado automaticamente no `mtcli`:
+
+```bash
+mt vp
+```
+
+Exemplo completo:
+
+```bash
+mt vp \
+  --symbol WING26 \
+  --period m1 \
+  --limit 500 \
+  --range 100 \
+  --volume tick \
+  --hvn-criterio media \
+  --verbose
+```
+
+---
+
+## 🔧 Opções disponíveis
+
+| Opção               | Descrição                                    |
+| ------------------- | -------------------------------------------- |
+| `--symbol`, `-s`    | Símbolo do ativo (ex: WIN, WDO, PETR4)       |
+| `--period`, `-p`    | Timeframe (m1, m5, m15, h1, etc.)            |
+| `--limit`, `-l`     | Quantidade de candles analisados             |
+| `--range`, `-r`     | Tamanho da faixa de preço                    |
+| `--volume`, `-v`    | Tipo de volume (`tick` ou `real`)            |
+| `--inicio`, `-i`    | Data/hora inicial (`YYYY-MM-DD HH:MM`)       |
+| `--fim`, `-f`       | Data/hora final (`YYYY-MM-DD HH:MM`)         |
+| `--timezone`, `-tz` | Fuso horário para exibição                   |
+| `--hvn-criterio`    | Critério de HVN/LVN (`media` ou `percentil`) |
+| `--verbose`, `-vv`  | Exibe informações detalhadas                 |
+
+---
+
+## Metodologia de cálculo
+
+### Volume Profile
+
+* Cada candle contribui volume para **todas as faixas de preço** entre seu `low` e `high`
+* O volume é distribuído **uniformemente**
+* Evita o viés de concentrar volume apenas no preço de fechamento
+
+### HVN / LVN
+
+Critérios disponíveis:
+
+* **Média**
+
+  * HVN: volume ≥ média × multiplicador
+  * LVN: volume ≤ média × multiplicador
+
+* **Percentil**
+
+  * HVN: acima do percentil superior (ex: 80%)
+  * LVN: abaixo do percentil inferior (ex: 20%)
+
+---
+
+## Acessibilidade
+
+Este plugin foi projetado para uso total com leitores de tela:
+
+* Tabelas em texto puro
+* Distribuição expressa em percentuais
+* Estatísticas narráveis
+* Sem gráficos ASCII ruidosos
+
+Funciona corretamente com:
+
+* NVDA
+* JAWS
+* VoiceOver (terminal)
+
+---
+
+## Arquitetura
+
+```text
+mtcli_volume/
+├── cli.py         # Interface de linha de comando
+├── controller.py  # Orquestração do fluxo
+├── model.py       # Cálculos e acesso ao MT5
+├── view.py        # Apresentação acessível
+├── conf.py        # Configurações padrão
+└── plugin.py      # Registro no mtcli
+```
+
+---
+
+## Exemplo de saída
+
+```text
+Volume Profile — WING26
+
+Preço           | Volume        | Distribuição
+-------------------------------------------------------
+186300.00       | 18.250        | 72.4% do máximo
+186200.00       | 25.190        | 100.0% do máximo
+186100.00       | 14.880        | 59.1% do máximo
+
+Estatísticas
+POC             : 186200.00
+Área de Valor   : 185900.00 → 186300.00
+HVNs            : 186200.00, 186100.00
+LVNs            : 185700.00
+```
+
+---
+
+## Testes
+
+O plugin foi projetado para facilitar testes unitários do cálculo no `model.py`,
+permitindo validação independente do MetaTrader 5.
+
+---
+
+## Contribuição
+
+Pull requests são bem-vindos, especialmente para:
+
+* Novos critérios de HVN/LVN
+* Value Area expandida a partir do POC
+* Modo TPO
+* Integração com VWAP e Footprint
+
+---
+
+## Licença
+
+GPL License
+

mtcli_volume-2.4.1/README.md

@@ -0,0 +1,193 @@
+# mtcli-volume
+
+Plugin do **mtcli** para cálculo e visualização de **Volume Profile** diretamente no terminal, com foco em:
+
+- Precisão técnica (distribuição High–Low)
+- Leitura profissional de mercado
+- Total acessibilidade (screen reader friendly)
+- Integração com MetaTrader 5
+
+---
+
+## Principais recursos
+
+- **Volume Profile por faixa High–Low**
+  - O volume de cada candle é distribuído uniformemente entre todas as faixas de preço tocadas entre o **LOW** e o **HIGH**
+  - Modelo mais próximo do Volume Profile clássico (VAP)
+
+- **Estatísticas de Market Profile**
+  - POC (Point of Control)
+  - Área de Valor (70%)
+  - HVNs e LVNs com critérios profissionais
+
+- ⚙️ **Critérios avançados para HVN/LVN**
+  - Baseado na média (multiplicadores)
+  - Baseado em percentis (ex: 80% / 20%)
+
+- **100% acessível**
+  - Saída textual linear
+  - Compatível com NVDA, JAWS e leitores de tela
+  - Sem dependência de cores ou gráficos visuais
+
+- **Arquitetura MVC**
+  - Model: cálculos e dados
+  - Controller: fluxo de negócio
+  - View: apresentação no terminal
+  - CLI: interface de linha de comando
+
+---
+
+## Instalação
+
+Via PyPI:
+
+```bash
+pip install mtcli-volume
+````
+
+Ou com Poetry:
+
+```bash
+poetry add mtcli-volume
+```
+
+> ⚠️ Requer MetaTrader 5 instalado e configurado corretamente no sistema.
+
+---
+
+## Uso básico
+
+Após a instalação, o comando é registrado automaticamente no `mtcli`:
+
+```bash
+mt vp
+```
+
+Exemplo completo:
+
+```bash
+mt vp \
+  --symbol WING26 \
+  --period m1 \
+  --limit 500 \
+  --range 100 \
+  --volume tick \
+  --hvn-criterio media \
+  --verbose
+```
+
+---
+
+## 🔧 Opções disponíveis
+
+| Opção               | Descrição                                    |
+| ------------------- | -------------------------------------------- |
+| `--symbol`, `-s`    | Símbolo do ativo (ex: WIN, WDO, PETR4)       |
+| `--period`, `-p`    | Timeframe (m1, m5, m15, h1, etc.)            |
+| `--limit`, `-l`     | Quantidade de candles analisados             |
+| `--range`, `-r`     | Tamanho da faixa de preço                    |
+| `--volume`, `-v`    | Tipo de volume (`tick` ou `real`)            |
+| `--inicio`, `-i`    | Data/hora inicial (`YYYY-MM-DD HH:MM`)       |
+| `--fim`, `-f`       | Data/hora final (`YYYY-MM-DD HH:MM`)         |
+| `--timezone`, `-tz` | Fuso horário para exibição                   |
+| `--hvn-criterio`    | Critério de HVN/LVN (`media` ou `percentil`) |
+| `--verbose`, `-vv`  | Exibe informações detalhadas                 |
+
+---
+
+## Metodologia de cálculo
+
+### Volume Profile
+
+* Cada candle contribui volume para **todas as faixas de preço** entre seu `low` e `high`
+* O volume é distribuído **uniformemente**
+* Evita o viés de concentrar volume apenas no preço de fechamento
+
+### HVN / LVN
+
+Critérios disponíveis:
+
+* **Média**
+
+  * HVN: volume ≥ média × multiplicador
+  * LVN: volume ≤ média × multiplicador
+
+* **Percentil**
+
+  * HVN: acima do percentil superior (ex: 80%)
+  * LVN: abaixo do percentil inferior (ex: 20%)
+
+---
+
+## Acessibilidade
+
+Este plugin foi projetado para uso total com leitores de tela:
+
+* Tabelas em texto puro
+* Distribuição expressa em percentuais
+* Estatísticas narráveis
+* Sem gráficos ASCII ruidosos
+
+Funciona corretamente com:
+
+* NVDA
+* JAWS
+* VoiceOver (terminal)
+
+---
+
+## Arquitetura
+
+```text
+mtcli_volume/
+├── cli.py         # Interface de linha de comando
+├── controller.py  # Orquestração do fluxo
+├── model.py       # Cálculos e acesso ao MT5
+├── view.py        # Apresentação acessível
+├── conf.py        # Configurações padrão
+└── plugin.py      # Registro no mtcli
+```
+
+---
+
+## Exemplo de saída
+
+```text
+Volume Profile — WING26
+
+Preço           | Volume        | Distribuição
+-------------------------------------------------------
+186300.00       | 18.250        | 72.4% do máximo
+186200.00       | 25.190        | 100.0% do máximo
+186100.00       | 14.880        | 59.1% do máximo
+
+Estatísticas
+POC             : 186200.00
+Área de Valor   : 185900.00 → 186300.00
+HVNs            : 186200.00, 186100.00
+LVNs            : 185700.00
+```
+
+---
+
+## Testes
+
+O plugin foi projetado para facilitar testes unitários do cálculo no `model.py`,
+permitindo validação independente do MetaTrader 5.
+
+---
+
+## Contribuição
+
+Pull requests são bem-vindos, especialmente para:
+
+* Novos critérios de HVN/LVN
+* Value Area expandida a partir do POC
+* Modo TPO
+* Integração com VWAP e Footprint
+
+---
+
+## Licença
+
+GPL License

mtcli_volume-2.4.1/mtcli_volume/cli.py

@@ -0,0 +1,88 @@
+"""
+Interface de linha de comando (CLI) do plugin mtcli-volume.
+
+Este módulo define o comando `vp`, responsável por:
+- Interpretar argumentos do usuário via Click
+- Validar parâmetros de entrada
+- Acionar o controller para cálculo do Volume Profile
+- Delegar a exibição dos resultados para a view
+
+Não contém lógica de cálculo nem regras de negócio.
+"""
+
+from datetime import datetime
+
+import click
+
+from .conf import (
+    FIM,
+    INICIO,
+    LIMIT,
+    PERIOD,
+    RANGE,
+    SYMBOL,
+    TIMEZONE,
+    VOLUME,
+)
+from .controller import calcular_volume_profile
+from .view import exibir_volume_profile
+
+
+@click.command(
+    help=(
+        "Exibe o Volume Profile distribuindo o volume dos candles "
+        "uniformemente entre as faixas de preço entre LOW e HIGH."
+    )
+)
+@click.version_option(package_name="mtcli-volume")
+@click.option("--symbol", "-s", default=SYMBOL, show_default=True, help="Símbolo do ativo.")
+@click.option("--period", "-p", default=PERIOD, show_default=True, help="Timeframe utilizado no cálculo.")
+@click.option("--limit", "-l", default=LIMIT, show_default=True, help="Quantidade de candles analisados.")
+@click.option("--range", "-r", type=float, default=RANGE, show_default=True, help="Tamanho da faixa de preço.")
+@click.option("--volume", "-v", type=click.Choice(["tick", "real"], case_sensitive=False),
+              default=VOLUME, show_default=True, help="Tipo de volume utilizado.")
+@click.option("--inicio", "-i", default=INICIO, show_default=True, help="Data/hora inicial (YYYY-MM-DD HH:MM).")
+@click.option("--fim", "-f", default=FIM, show_default=True, help="Data/hora final (YYYY-MM-DD HH:MM).")
+@click.option("--timezone", "-tz", default=TIMEZONE, show_default=True, help="Fuso horário para exibição.")
+@click.option("--hvn-criterio", type=click.Choice(["media", "percentil"], case_sensitive=False),
+              default="percentil", show_default=True, help="Critério para definição de HVNs/LVNs.")
+@click.option("--verbose", "-vv", is_flag=True, help="Exibe informações detalhadas da análise.")
+def volume(
+    symbol,
+    period,
+    limit,
+    range,
+    volume,
+    inicio,
+    fim,
+    timezone,
+    hvn_criterio,
+    verbose,
+):
+    """
+    Executa o cálculo e a exibição do Volume Profile.
+
+    O Volume Profile é calculado distribuindo o volume de cada candle
+    igualmente entre todas as faixas de preço compreendidas entre
+    o LOW e o HIGH do candle.
+
+    Esta abordagem fornece uma representação mais precisa da
+    concentração de volume ao longo do eixo de preços.
+    """
+    inicio_dt = datetime.strptime(inicio, "%Y-%m-%d %H:%M") if inicio else None
+    fim_dt = datetime.strptime(fim, "%Y-%m-%d %H:%M") if fim else None
+
+    profile, stats, info = calcular_volume_profile(
+        symbol=symbol,
+        period=period,
+        limit=limit,
+        step=range,
+        volume=volume,
+        inicio=inicio_dt,
+        fim=fim_dt,
+        verbose=verbose,
+        timezone_str=timezone,
+        criterio_hvn=hvn_criterio.lower(),
+    )
+
+    exibir_volume_profile(profile, stats, symbol, info, verbose)

mtcli_volume-2.4.1/mtcli_volume/conf.py

@@ -0,0 +1,23 @@
+"""
+Configurações padrão do plugin mtcli-volume.
+
+Os valores podem ser sobrescritos por:
+- Variáveis de ambiente
+- Arquivo de configuração do mtcli
+
+Este módulo não contém lógica, apenas parâmetros padrão.
+"""
+
+import os
+from mtcli.conf import config
+
+SYMBOL = os.getenv("SYMBOL", config["DEFAULT"].get("symbol", fallback="WIN$N"))
+DIGITOS = int(os.getenv("DIGITOS", config["DEFAULT"].getint("digitos", fallback=0)))
+PERIOD = os.getenv("PERIOD", config["DEFAULT"].get("period", fallback="M1"))
+LIMIT = int(os.getenv("LIMIT", config["DEFAULT"].getint("limit", fallback=566)))
+RANGE = float(os.getenv("RANGE", config["DEFAULT"].getfloat("range", fallback=100)))
+VOLUME = os.getenv("VOLUME", config["DEFAULT"].get("volume", fallback="tick"))
+INICIO = os.getenv("INICIO", config["DEFAULT"].get("inicio", fallback=""))
+FIM = os.getenv("FIM", config["DEFAULT"].get("fim", fallback=""))
+TIMEZONE = os.getenv("TIMEZONE", config["DEFAULT"].get("timezone", fallback="America/Sao_Paulo"))
+FORMAT = os.getenv("FORMAT", config["DEFAULT"].get("format", fallback="k"))

mtcli_volume-2.4.1/mtcli_volume/controller.py

@@ -0,0 +1,79 @@
+"""
+Controller do plugin mtcli-volume.
+
+Este módulo coordena o fluxo de execução do Volume Profile:
+- Solicita dados históricos ao model
+- Aciona o cálculo do Volume Profile
+- Calcula estatísticas de Market Profile
+- Prepara informações de contexto (datas, timezone, candles)
+
+Não realiza cálculos matemáticos nem formatação de saída.
+"""
+
+from datetime import datetime, timedelta, timezone
+import zoneinfo
+import numpy as np
+
+from mtcli.logger import setup_logger
+from .model import calcular_profile, calcular_estatisticas, obter_rates
+
+log = setup_logger()
+
+
+def calcular_volume_profile(
+    symbol,
+    period,
+    limit,
+    step,
+    volume,
+    inicio=None,
+    fim=None,
+    verbose=False,
+    timezone_str="America/Sao_Paulo",
+    criterio_hvn="media",
+):
+    """
+    Orquestra o cálculo completo do Volume Profile.
+
+    Etapas:
+    - Obtém candles históricos via MetaTrader 5
+    - Calcula o Volume Profile por faixa de preço (High–Low)
+    - Calcula estatísticas de Market Profile (POC, VA, HVN, LVN)
+    - Converte datas para o fuso horário configurado
+
+    Retorna estruturas prontas para consumo pela camada de visualização.
+    """
+    volume = volume.lower().strip()
+    if volume not in ("tick", "real"):
+        raise ValueError("Tipo de volume inválido. Use 'tick' ou 'real'.")
+
+    rates = obter_rates(symbol, period, limit, inicio, fim)
+
+    if rates is None or not isinstance(rates, np.ndarray) or len(rates) == 0:
+        log.error("Nenhum dado retornado para o cálculo do Volume Profile.")
+        return {}, {}, {}
+
+    profile = calcular_profile(rates, step, volume)
+    stats = calcular_estatisticas(profile, criterio=criterio_hvn)
+
+    try:
+        fuso = zoneinfo.ZoneInfo(timezone_str)
+    except Exception:
+        fuso = timezone(timedelta(hours=-3))
+
+    try:
+        inicio_real = datetime.utcfromtimestamp(float(rates[0]["time"])).astimezone(fuso)
+        fim_real = datetime.utcfromtimestamp(float(rates[-1]["time"])).astimezone(fuso)
+    except Exception:
+        inicio_real = fim_real = "?"
+
+    info = {
+        "symbol": symbol,
+        "period": period,
+        "candles": len(rates),
+        "inicio": str(inicio_real),
+        "fim": str(fim_real),
+        "timezone": timezone_str,
+    }
+
+    return profile, stats, info