mtcli 3.8.0.dev7__py3-none-any.whl → 3.8.0.dev8__py3-none-any.whl

mtcli/__main__.py

@@ -0,0 +1,3 @@
+from .cli import mt
+
+mt()

mtcli/cli.py

@@ -27,7 +27,6 @@ from mtcli.marketdata.tick_engine import TickEngine
 
 from .commands.bars import bars
 from .commands.doctor import doctor
-from .commands.migrate import migrate
 from .commands.ticks import ticks
 
 
@@ -89,7 +88,6 @@ def mt(ctx):
 mt.add_command(doctor, name="doctor")
 mt.add_command(bars, name="bars")
 mt.add_command(doctor, name="dr")
-mt.add_command(migrate)
 mt.add_command(ticks)
 
 loaded_plugins = load_plugins(mt)

mtcli/cli_dev.py

@@ -0,0 +1,8 @@
+import click
+from .commands_dev.migrate import migrate
+
+@click.group()
+def cli():
+    pass
+
+cli.add_command(migrate)

mtcli/commands_dev/migrate.py

@@ -0,0 +1,48 @@
+"""
+Comando CLI para execução das migrations do banco de dados.
+
+Este comando aplica todas as migrations pendentes no banco
+utilizado pelo mtcli.
+
+Fluxo de execução:
+
+1. Abre conexão com o banco SQLite
+2. Executa o migration runner
+3. Aplica migrations ainda não executadas
+
+Uso:
+
+    mtcli migrate
+
+Este comando é implementado utilizando o framework
+:contentReference[oaicite:1]{index=1} para construção de aplicações CLI.
+"""
+
+import click
+
+from mtcli.database import get_connection
+from mtcli.migrations.runner import run_migrations
+
+
+@click.command()
+def migrate():
+    """
+    Executa as migrations pendentes do banco de dados.
+
+    O comando conecta ao banco configurado no mtcli
+    e executa o migration runner responsável por:
+
+    - detectar migrations disponíveis
+    - identificar a versão atual do schema
+    - aplicar migrations pendentes
+    - registrar migrations aplicadas
+
+    Este comando é normalmente executado:
+
+    - na primeira inicialização do sistema
+    - após atualização de versão do mtcli
+    """
+
+    conn = get_connection()
+
+    run_migrations(conn)

mtcli/migrations/001_initial_schema.py

@@ -1,4 +1,34 @@
+"""
+Migration 001
+
+Cria o schema inicial do banco de dados do mtcli.
+
+Esta migration cria a tabela principal `ticks`, responsável por
+armazenar os ticks de mercado capturados do MetaTrader.
+
+Estrutura inicial:
+
+- symbol : símbolo do ativo
+- time   : timestamp em segundos
+- bid    : preço bid
+- ask    : preço ask
+- last   : último preço negociado
+- volume : volume do tick
+- flags  : flags fornecidas pela API MT5
+
+Também cria o índice `idx_ticks_symbol_time` para acelerar
+consultas por símbolo e tempo.
+"""
+
+
 def upgrade(conn):
+    """
+    Executa a migration inicial criando a tabela `ticks`
+    e o índice principal utilizado nas consultas.
+
+    A operação é idempotente graças ao uso de
+    `CREATE TABLE IF NOT EXISTS`.
+    """
 
     conn.execute("""
     CREATE TABLE IF NOT EXISTS ticks(

mtcli/migrations/002_ticks_time_msc.py

@@ -1,4 +1,32 @@
+"""
+Migration 002
+
+Adiciona a coluna `time_msc` à tabela `ticks`.
+
+A API do MetaTrader fornece timestamps com resolução em
+milissegundos (`time_msc`). Esta migration adiciona suporte
+a esse campo sem quebrar compatibilidade com bancos antigos.
+"""
+
+
 def column_exists(conn, table, column):
+    """
+    Verifica se uma coluna existe em uma tabela SQLite.
+
+    Parameters
+    ----------
+    conn : sqlite3.Connection
+        Conexão com o banco de dados.
+    table : str
+        Nome da tabela.
+    column : str
+        Nome da coluna.
+
+    Returns
+    -------
+    bool
+        True se a coluna existir.
+    """
 
     cursor = conn.execute(f"PRAGMA table_info({table})")
 
@@ -10,6 +38,10 @@ def column_exists(conn, table, column):
 
 
 def upgrade(conn):
+    """
+    Adiciona a coluna `time_msc` à tabela `ticks`
+    caso ela ainda não exista.
+    """
 
     if not column_exists(conn, "ticks", "time_msc"):
 

mtcli/migrations/003_optimize_ticks_without_rowid.py

@@ -1,4 +1,27 @@
+"""
+Migration 003
+
+Otimiza a tabela `ticks` convertendo-a para `WITHOUT ROWID`.
+
+Tabelas SQLite com chave primária composta podem ter melhor
+performance e menor uso de disco utilizando `WITHOUT ROWID`.
+
+Para aplicar esta otimização é necessário reconstruir a tabela.
+"""
+
+
 def upgrade(conn):
+    """
+    Reconstrói a tabela `ticks` utilizando `WITHOUT ROWID`.
+
+    Processo executado:
+
+    1. Cria nova tabela otimizada
+    2. Copia os dados da tabela antiga
+    3. Remove tabela antiga
+    4. Renomeia nova tabela
+    5. Recria índices necessários
+    """
 
     cursor = conn.execute("""
         SELECT sql

mtcli/migrations/004_ticks_pk_time_msc.py

@@ -1,4 +1,26 @@
+"""
+Migration 004
+
+Reconstrói a tabela `ticks` utilizando `time_msc` como parte
+da chave primária.
+
+Motivação:
+
+- `time` possui resolução em segundos
+- `time_msc` possui resolução em milissegundos
+- múltiplos ticks podem ocorrer dentro do mesmo segundo
+
+Nova chave primária:
+
+    PRIMARY KEY(symbol, time_msc)
+"""
+
+
 def upgrade(conn):
+    """
+    Reconstrói a tabela `ticks` alterando a chave primária
+    para `(symbol, time_msc)`.
+    """
 
     cursor = conn.execute("""
         SELECT sql

mtcli/migrations/005_tick_price_compression.py

@@ -1,4 +1,31 @@
+"""
+Migration 005
+
+Aplica compressão de preços nos ticks.
+
+Preços e volume passam a ser armazenados como inteiros
+para reduzir uso de espaço em disco.
+
+Transformações aplicadas:
+
+    bid   -> INTEGER (bid * 100)
+    ask   -> INTEGER (ask * 100)
+    last  -> INTEGER (last * 100)
+    volume -> INTEGER
+
+A tabela precisa ser reconstruída para alterar os tipos
+das colunas.
+"""
+
+
 def upgrade(conn):
+    """
+    Reconstrói a tabela `ticks` aplicando compressão
+    de preços e volumes.
+
+    Isso reduz significativamente o tamanho do banco
+    e melhora performance de leitura.
+    """
 
     cursor = conn.execute("""
         SELECT sql

mtcli/migrations/006_add_index_ticks_symbol_time.py

@@ -0,0 +1,32 @@
+"""
+Migration 006
+
+Cria índice para acelerar consultas por símbolo e tempo
+utilizando a coluna `time_msc`.
+
+Este índice é importante para consultas comuns como:
+
+    SELECT * FROM ticks
+    WHERE symbol = ?
+    ORDER BY time_msc
+"""
+
+SQL = """
+CREATE INDEX IF NOT EXISTS idx_ticks_symbol_time
+ON ticks(symbol, time_msc);
+"""
+
+
+def upgrade(conn):
+    """
+    Executa a criação do índice `idx_ticks_symbol_time`.
+
+    A operação é idempotente graças ao uso de
+    `CREATE INDEX IF NOT EXISTS`.
+    """
+
+    cursor = conn.cursor()
+
+    cursor.execute(SQL)
+
+    conn.commit()

mtcli/migrations/__main__.py

@@ -0,0 +1,7 @@
+from mtcli.database import get_connection
+from .runner import run_migrations
+
+
+conn = get_connection()
+run_migrations(conn)
+

mtcli/migrations/runner.py

@@ -1,3 +1,28 @@
+"""
+Migration Runner do mtcli.
+
+Responsabilidades:
+
+1. Descobrir migrations disponíveis no diretório `mtcli/migrations`
+2. Determinar a versão atual do schema no banco
+3. Executar migrations pendentes em ordem
+4. Registrar migrations aplicadas na tabela `schema_migrations`
+
+Formato obrigatório das migrations:
+
+    NNN_nome_da_migration.py
+
+Exemplo:
+
+    001_initial_schema.py
+    002_ticks_time_msc.py
+    003_optimize_ticks_without_rowid.py
+
+Cada migration deve implementar:
+
+    def upgrade(conn)
+"""
+
 import importlib
 from pathlib import Path
 
@@ -6,7 +31,42 @@ MIGRATIONS_DIR = Path(__file__).parent
 PACKAGE = "mtcli.migrations"
 
 
+# ---------------------------------------------------------
+# Infraestrutura
+# ---------------------------------------------------------
+
+def ensure_migrations_table(conn):
+    """
+    Garante que a tabela `schema_migrations` exista.
+
+    Esta tabela armazena quais migrations já foram
+    aplicadas no banco.
+    """
+
+    conn.execute("""
+    CREATE TABLE IF NOT EXISTS schema_migrations(
+        version INTEGER PRIMARY KEY,
+        applied_at TEXT NOT NULL
+    )
+    """)
+
+    conn.commit()
+
+
+# ---------------------------------------------------------
+# Estado do banco
+# ---------------------------------------------------------
+
 def get_current_version(conn):
+    """
+    Retorna a versão atual do schema.
+
+    Returns
+    -------
+    int
+        Maior versão registrada em `schema_migrations`.
+        Retorna 0 se nenhuma migration foi aplicada.
+    """
 
     cursor = conn.execute(
         "SELECT MAX(version) FROM schema_migrations"
@@ -18,6 +78,9 @@ def get_current_version(conn):
 
 
 def mark_version(conn, version):
+    """
+    Marca uma migration como aplicada.
+    """
 
     conn.execute(
         """
@@ -30,7 +93,24 @@ def mark_version(conn, version):
     conn.commit()
 
 
+# ---------------------------------------------------------
+# Descoberta de migrations
+# ---------------------------------------------------------
+
 def discover_migrations():
+    """
+    Descobre migrations válidas no diretório.
+
+    Apenas arquivos no formato:
+
+        NNN_nome.py
+
+    serão considerados migrations.
+
+    Returns
+    -------
+    list[(int,str)]
+    """
 
     migrations = []
 
@@ -39,7 +119,13 @@ def discover_migrations():
         if file.name in ("__init__.py", "runner.py"):
             continue
 
-        version = int(file.name.split("_")[0])
+        prefix = file.stem.split("_")[0]
+
+        # ignora arquivos inválidos
+        if not prefix.isdigit():
+            continue
+
+        version = int(prefix)
 
         module_name = file.stem
 
@@ -47,10 +133,45 @@ def discover_migrations():
 
     migrations.sort(key=lambda x: x[0])
 
+    validate_migrations(migrations)
+
     return migrations
 
 
+def validate_migrations(migrations):
+    """
+    Valida integridade das migrations.
+
+    Verifica:
+
+    - versões duplicadas
+    - gaps na sequência
+    """
+
+    versions = [v for v, _ in migrations]
+
+    if len(versions) != len(set(versions)):
+        raise RuntimeError("Duplicate migration versions detected.")
+
+    if not versions:
+        return
+
+    expected = list(range(min(versions), max(versions) + 1))
+
+    if versions != expected:
+        raise RuntimeError(
+            f"Migration sequence gap detected: {versions}"
+        )
+
+
+# ---------------------------------------------------------
+# Compatibilidade com bancos antigos
+# ---------------------------------------------------------
+
 def legacy_database_detected(conn):
+    """
+    Detecta bancos antigos sem controle de migrations.
+    """
 
     cursor = conn.execute("""
         SELECT name
@@ -63,9 +184,8 @@ def legacy_database_detected(conn):
 
 
 def bootstrap_legacy(conn):
-
     """
-    Marca migration 1 como aplicada se banco já tinha schema.
+    Inicializa migrations em banco legado.
     """
 
     if legacy_database_detected(conn):
@@ -78,7 +198,23 @@ def bootstrap_legacy(conn):
         conn.commit()
 
 
+# ---------------------------------------------------------
+# Runner principal
+# ---------------------------------------------------------
+
 def run_migrations(conn):
+    """
+    Executa migrations pendentes.
+
+    Fluxo:
+
+    1. Garante tabela `schema_migrations`
+    2. Detecta bancos legados
+    3. Descobre migrations
+    4. Executa migrations pendentes
+    """
+
+    ensure_migrations_table(conn)
 
     bootstrap_legacy(conn)
 
@@ -95,6 +231,11 @@ def run_migrations(conn):
 
         module = importlib.import_module(module_path)
 
+        if not hasattr(module, "upgrade"):
+            raise RuntimeError(
+                f"Migration {module_name} does not define upgrade()"
+            )
+
         print(f"Applying migration {version}: {module_name}")
 
         module.upgrade(conn)

{mtcli-3.8.0.dev7.dist-info → mtcli-3.8.0.dev8.dist-info}/METADATA

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

{mtcli-3.8.0.dev7.dist-info → mtcli-3.8.0.dev8.dist-info}/RECORD

@@ -1,11 +1,14 @@
 mtcli/__init__.py,sha256=guFO5EmCfuH8MNujJH8hw_oPg8Ee__QlQgVd-4A3N6o,84
-mtcli/cli.py,sha256=dXeTB_hlVroYesn_jD6oMs8LOl9OuOtfgrtp4Nifgto,2644
+mtcli/__main__.py,sha256=cV4B4W1RDBOeAWwocqPzuEfJP2AKccvSzColBIqKA9c,29
+mtcli/cli.py,sha256=-e-6MFnqAJyZjAGqUbVC38TcuixY4DvZ_mRSCgEZD0I,2580
+mtcli/cli_dev.py,sha256=vUBoS5hmcB76tJFMADKWTg4-bWqdOZhuYOnDu8VYHYs,125
 mtcli/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 mtcli/commands/bars.py,sha256=JXXq9HIeFU-VKf8e2rOKTMXx_h5SRcuvKER-mlOjxjM,4205
 mtcli/commands/conf.py,sha256=nYN3dk9hZVagkf3mP41yBdKUuCKlvzgaF8DHGKbG8OU,866
 mtcli/commands/doctor.py,sha256=OIuJlQ2-PODGGOXj6pVVULLcyiI5htdERc8l6VHqjYM,4610
-mtcli/commands/migrate.py,sha256=iJOkEQObVOIfyCXottn7M38xURByVgXITXVKapoDmfE,208
 mtcli/commands/ticks.py,sha256=emXXgwDnyxLSEvEO9t3oIHuwXCm2rxV6p7NkeXrUQAk,887
+mtcli/commands_dev/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mtcli/commands_dev/migrate.py,sha256=6PiyAZJSOtPXVxLyaCTPlakM7sAwIt2DrethGrUzzzA,1151
 mtcli/conecta.py,sha256=PraDErB7wparbosxRdHGhhPYVn02z99Bj9mqfbmE4iw,1074
 mtcli/conf.py,sha256=-nGmAtAzLZpZYT9arXxg7jUmK4m32aPLuYHKqHsQWuA,8613
 mtcli/config_registre.py,sha256=H2iVKrQr8NWn3--tszsnZBNk-WoBCXgGFZ1-GGT8mho,1000
@@ -21,13 +24,15 @@ mtcli/marketdata/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,
 mtcli/marketdata/tick_cache.py,sha256=T-auTfkhk5s-TZkaVaTuJGLEnaoxyED7yPr6CGyUDfM,1191
 mtcli/marketdata/tick_engine.py,sha256=YKU66-NJh2hlK8GZdclk3kBgP7VYEyiLawYNYcIDonA,2930
 mtcli/marketdata/tick_repository.py,sha256=cquyNUcXT6G3ljBqrMR8NxaZai8MuTDPyNunfFWSXJA,5518
-mtcli/migrations/001_initial_schema.py,sha256=Xve9r9RRAOtoZQ2iOaD-gdTfxSjaqoaCwGHn_ZSUtlg,439
-mtcli/migrations/002_ticks_time_msc.py,sha256=OKpxZZlb5QEKzVaYAt3kgi2vHu5CRoxLHQ4RRzYTX4E,420
-mtcli/migrations/003_optimize_ticks_without_rowid.py,sha256=AyOUJA1SvEhNVXnFRpz2FI4hKk1PutHuC6FSneceR4s,1234
-mtcli/migrations/004_ticks_pk_time_msc.py,sha256=omwgquaUPEL3IKleeNR1cYOqDQg-rc5W_AZ-f8b765Y,1153
-mtcli/migrations/005_tick_price_compression.py,sha256=gyzaBCC4R1vXcEKpU-FKNeFtIqLTNlLXYoscs2Wuvho,1232
+mtcli/migrations/001_initial_schema.py,sha256=5RrlQzCe_4vX73HxFPt9jvjFIRum4r7H61A5_XpH3D0,1199
+mtcli/migrations/002_ticks_time_msc.py,sha256=LraR699iEnYgCqbq3atXU6gvOiH-4G-ETGd1m9HtQVg,1125
+mtcli/migrations/003_optimize_ticks_without_rowid.py,sha256=tlDpRrwfwP9bmWMQETR-mJfh9UHXFdaxouoa9ApWsw0,1803
+mtcli/migrations/004_ticks_pk_time_msc.py,sha256=XFX0QZdajeWZ6HbsRxOhMaNY-_yTgVnC8TZUWe_akME,1609
+mtcli/migrations/005_tick_price_compression.py,sha256=jcuvaujn4ZnS2M40HX8D1kkl3yr3JKHSucjMvCArIWA,1832
+mtcli/migrations/006_add_index_ticks_symbol_time.py,sha256=w94PlUxh_Ux028HzI_4Ei_VyQ-iZJMMCkf0lnWfb5C4,615
 mtcli/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mtcli/migrations/runner.py,sha256=1ArCvMXP9qV0se7n2NWsaByomBpGBhO6x9M8auH68c4,2048
+mtcli/migrations/__main__.py,sha256=S10PGkeeewNMge5X3eGpfNyWc3g7_ZdoTO1veJuZol4,132
+mtcli/migrations/runner.py,sha256=P4EvF-_C0enBUx_lbx1fINim7_wJDwLY_ji3zispxZ4,5374
 mtcli/models/__init__.py,sha256=mkEpxtmwIl3AhP-RNhr-jSdyK_MREjySPZASmOD53CQ,35
 mtcli/models/bar_model.py,sha256=yCnHrKWmslcQZ-HN7Lbs3clSahS0-yu8s6vjM-FI1mw,2999
 mtcli/models/bars_model.py,sha256=srq7YEsyyeI0e7rcsDUAfVPoxbBq0oWXPUpqRseRrPs,674
@@ -76,8 +81,8 @@ mtcli/views/ranges_view.py,sha256=5gA2bAJuco-Xj964nsjs87tZ-079O7xKvaeif1UJ-PQ,12
 mtcli/views/rates_view.py,sha256=Jkdbg-Q_OVJuID-Q9HFUVICCF1jE82d-qfZWNm1JJ_4,1214
 mtcli/views/vars_view.py,sha256=Vpcej41qnZSvvSyvXYyW8W7CEFdqTxBd8NczV84XPJY,1635
 mtcli/views/volumes_view.py,sha256=d_6YxM0vA1revwoPwnwUjV19KcqnddVgdpBHTt5Vqms,1575
-mtcli-3.8.0.dev7.dist-info/entry_points.txt,sha256=EH8lMNy2L-TCJB3E3EJHF5QySz_b_86oOhcAKAN20-Q,103
-mtcli-3.8.0.dev7.dist-info/licenses/LICENSE,sha256=Z-2ANeRgM9IjXnHeg9mA2gillM6eTQj8sIExAGNe2-8,1092
-mtcli-3.8.0.dev7.dist-info/METADATA,sha256=601kT3fP5o3adTChzeGS0qNNuwow194PukB7h_RrIGo,3654
-mtcli-3.8.0.dev7.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-mtcli-3.8.0.dev7.dist-info/RECORD,,
+mtcli-3.8.0.dev8.dist-info/entry_points.txt,sha256=nXgZqVVUkbj5drC8CLfELsz1DcRKGQcSh_NHOU_s9Xs,127
+mtcli-3.8.0.dev8.dist-info/licenses/LICENSE,sha256=Z-2ANeRgM9IjXnHeg9mA2gillM6eTQj8sIExAGNe2-8,1092
+mtcli-3.8.0.dev8.dist-info/METADATA,sha256=cUi_W4Ibn0a_5jraq1ahW7rifHTf1wgg6EE3ffizye4,3654
+mtcli-3.8.0.dev8.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+mtcli-3.8.0.dev8.dist-info/RECORD,,

{mtcli-3.8.0.dev7.dist-info → mtcli-3.8.0.dev8.dist-info}/entry_points.txt

@@ -1,6 +1,7 @@
 [console_scripts]
 mt=mtcli.cli:mt
 mtcli=mtcli.cli:mt
+mtdev=mtcli.cli_dev:cli
 
 [mtcli.plugins]
 internals=mtcli.plugin:register

mtcli/commands/migrate.py

@@ -1,12 +0,0 @@
-import click
-
-from mtcli.database import get_connection
-from mtcli.migrations.runner import run_migrations
-
-
-@click.command()
-def migrate():
-
-    conn = get_connection()
-
-    run_migrations(conn)