mtcli-volume 2.5.1__tar.gz → 2.5.2__tar.gz

mtcli_volume-2.5.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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_volume-2.5.1 → mtcli_volume-2.5.2}/PKG-INFO

@@ -1,21 +1,27 @@
 Metadata-Version: 2.4
 Name: mtcli-volume
-Version: 2.5.1
+Version: 2.5.2
 Summary: Plugin mtcli para cálculo e exibição de Volume Profile no terminal
+License-Expression: MIT
 License-File: LICENSE
+Keywords: trading,volume-profile,volume,metatrader5,mt5,cli,acessibilidade,screen reader friendly
 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: 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.2.0)
+Requires-Dist: mtcli (>=3.7.0)
 Requires-Dist: tzdata (>=2025.2)
 Project-URL: Documentation, https://mtcli-volume.readthedocs.io
 Project-URL: Homepage, https://github.com/vfranca/mtcli-volume
@@ -215,5 +221,5 @@ Pull requests são bem-vindos, especialmente para:
 
 ## Licença
 
-GPL License
+MIT License
 

{mtcli_volume-2.5.1 → mtcli_volume-2.5.2}/README.md

@@ -1,193 +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
+
+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
+
+MIT License

{mtcli_volume-2.5.1 → mtcli_volume-2.5.2}/mtcli_volume/controller.py

@@ -1,102 +1,102 @@
-"""
-Controller do plugin mtcli-volume.
-"""
-
-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 resolver_inicio_ancorado(anchor: str, tz):
-    """
-    Resolve a data-base da ancoragem (sem forçar horário fixo).
-    """
-    agora = datetime.now(tz)
-
-    if anchor == "day":
-        return agora.replace(hour=0, minute=0, second=0, microsecond=0)
-
-    if anchor == "week":
-        inicio_semana = agora - timedelta(days=agora.weekday())
-        return inicio_semana.replace(hour=0, minute=0, second=0, microsecond=0)
-
-    if anchor == "month":
-        return agora.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
-
-    return None
-
-
-def calcular_volume_profile(
-    symbol,
-    period,
-    limit,
-    step,
-    volume,
-    inicio=None,
-    fim=None,
-    anchor="day",
-    verbose=False,
-    timezone_str="America/Sao_Paulo",
-    criterio_hvn="media",
-):
-    volume = volume.lower().strip()
-    if volume not in ("tick", "real"):
-        raise ValueError("Tipo de volume inválido. Use 'tick' ou 'real'.")
-
-    try:
-        fuso = zoneinfo.ZoneInfo(timezone_str)
-    except Exception:
-        fuso = timezone(timedelta(hours=-3))
-
-    # Resolve ancoragem se --inicio não foi informado
-    if inicio is None:
-        inicio = resolver_inicio_ancorado(anchor, fuso)
-
-    rates = None
-    tentativas = 0
-    max_tentativas = 7
-
-    while tentativas < max_tentativas:
-        rates = obter_rates(symbol, period, limit, inicio, fim)
-        if rates is not None and isinstance(rates, np.ndarray) and len(rates) > 0:
-            break
-
-        inicio -= timedelta(days=1)
-        tentativas += 1
-
-    if rates is None or len(rates) == 0:
-        log.error("Nenhum dado retornado após fallback de ancoragem.")
-        return {}, {}, {}
-
-    profile = calcular_profile(rates, step, volume)
-    stats = calcular_estatisticas(profile, criterio=criterio_hvn)
-
-    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,
-        "anchor": anchor,
-        "fallback_days": tentativas,
-    }
-
-    return profile, stats, info
+"""
+Controller do plugin mtcli-volume.
+"""
+
+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 resolver_inicio_ancorado(anchor: str, tz):
+    """
+    Resolve a data-base da ancoragem (sem forçar horário fixo).
+    """
+    agora = datetime.now(tz)
+
+    if anchor == "day":
+        return agora.replace(hour=0, minute=0, second=0, microsecond=0)
+
+    if anchor == "week":
+        inicio_semana = agora - timedelta(days=agora.weekday())
+        return inicio_semana.replace(hour=0, minute=0, second=0, microsecond=0)
+
+    if anchor == "month":
+        return agora.replace(day=1, hour=0, minute=0, second=0, microsecond=0)
+
+    return None
+
+
+def calcular_volume_profile(
+    symbol,
+    period,
+    limit,
+    step,
+    volume,
+    inicio=None,
+    fim=None,
+    anchor="day",
+    verbose=False,
+    timezone_str="America/Sao_Paulo",
+    criterio_hvn="media",
+):
+    volume = volume.lower().strip()
+    if volume not in ("tick", "real"):
+        raise ValueError("Tipo de volume inválido. Use 'tick' ou 'real'.")
+
+    try:
+        fuso = zoneinfo.ZoneInfo(timezone_str)
+    except Exception:
+        fuso = timezone(timedelta(hours=-3))
+
+    # Resolve ancoragem se --inicio não foi informado
+    if inicio is None:
+        inicio = resolver_inicio_ancorado(anchor, fuso)
+
+    rates = None
+    tentativas = 0
+    max_tentativas = 7
+
+    while tentativas < max_tentativas:
+        rates = obter_rates(symbol, period, limit, inicio, fim)
+        if rates is not None and isinstance(rates, np.ndarray) and len(rates) > 0:
+            break
+
+        inicio -= timedelta(days=1)
+        tentativas += 1
+
+    if rates is None or len(rates) == 0:
+        log.error("Nenhum dado retornado após fallback de ancoragem.")
+        return {}, {}, {}
+
+    profile = calcular_profile(rates, step, volume)
+    stats = calcular_estatisticas(profile, criterio=criterio_hvn)
+
+    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,
+        "anchor": anchor,
+        "fallback_days": tentativas,
+    }
+
+    return profile, stats, info