kotsu-cli 0.1.0__py3-none-any.whl

money_cli/armazenamento/migracoes/0003_mesclagem.sql

@@ -0,0 +1,54 @@
+-- 0003: identidade para mesclar bancos de aparelhos diferentes (D39).
+-- `uid` identifica o registro em qualquer aparelho; `id` continua local. `alterado_em` é o
+-- carimbo da última alteração (relógio híbrido: milissegundos-contador-réplica), comparável
+-- como texto. Exclusão de lançamento deixa uma lápide, para ele não voltar na mesclagem.
+
+CREATE TABLE meta (
+    chave TEXT PRIMARY KEY,
+    valor TEXT NOT NULL
+);
+
+INSERT INTO meta (chave, valor) VALUES ('replica', lower(hex(randomblob(4))));
+INSERT INTO meta (chave, valor) VALUES ('relogio', '0000000000000-0000-00000000');
+
+ALTER TABLE conta ADD COLUMN uid TEXT;
+ALTER TABLE conta ADD COLUMN alterado_em TEXT NOT NULL DEFAULT '0000000000000-0000-00000000';
+UPDATE conta SET uid = lower(hex(randomblob(16)));
+CREATE UNIQUE INDEX conta_uid ON conta (uid);
+
+ALTER TABLE categoria ADD COLUMN uid TEXT;
+ALTER TABLE categoria ADD COLUMN alterado_em TEXT NOT NULL DEFAULT '0000000000000-0000-00000000';
+UPDATE categoria SET uid = lower(hex(randomblob(16)));
+CREATE UNIQUE INDEX categoria_uid ON categoria (uid);
+
+-- A série já tem identidade universal (`grupo`); falta só o carimbo do modelo.
+ALTER TABLE recorrencia ADD COLUMN alterado_em TEXT NOT NULL DEFAULT '0000000000000-0000-00000000';
+
+-- `gerado` = mês criado pela série e nunca mexido: fica fora do código de conferência,
+-- porque cada aparelho gera meses futuros até onde a pessoa navegou.
+ALTER TABLE lancamento ADD COLUMN uid TEXT;
+ALTER TABLE lancamento ADD COLUMN alterado_em TEXT NOT NULL DEFAULT '0000000000000-0000-00000000';
+ALTER TABLE lancamento ADD COLUMN gerado INTEGER NOT NULL DEFAULT 0 CHECK (gerado IN (0, 1));
+UPDATE lancamento SET uid = lower(hex(randomblob(16)));
+CREATE UNIQUE INDEX lancamento_uid ON lancamento (uid);
+
+CREATE TABLE lapide (
+    uid         TEXT PRIMARY KEY,
+    excluido_em TEXT NOT NULL
+);
+
+-- Quem insere sem `uid` ganha um: nenhum registro fica sem identidade.
+CREATE TRIGGER conta_uid_novo AFTER INSERT ON conta WHEN NEW.uid IS NULL
+BEGIN
+    UPDATE conta SET uid = lower(hex(randomblob(16))) WHERE id = NEW.id;
+END;
+
+CREATE TRIGGER categoria_uid_novo AFTER INSERT ON categoria WHEN NEW.uid IS NULL
+BEGIN
+    UPDATE categoria SET uid = lower(hex(randomblob(16))) WHERE id = NEW.id;
+END;
+
+CREATE TRIGGER lancamento_uid_novo AFTER INSERT ON lancamento WHEN NEW.uid IS NULL
+BEGIN
+    UPDATE lancamento SET uid = lower(hex(randomblob(16))) WHERE id = NEW.id;
+END;

money_cli/armazenamento/migracoes/__init__.py

@@ -0,0 +1,32 @@
+"""Migrações numeradas: arquivos NNNN_nome.sql nesta pasta, aplicados em ordem."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from importlib import resources
+
+_PADRAO = re.compile(r"^(\d{4})_[a-z0-9_]+\.sql$")
+
+
+@dataclass(frozen=True, slots=True)
+class Migracao:
+    versao: int
+    nome: str
+    sql: str
+
+
+def carregar() -> list[Migracao]:
+    """Lê as migrações do pacote e confere que a numeração é 1, 2, 3... sem buracos."""
+    encontradas = []
+    for item in resources.files(__package__).iterdir():
+        casamento = _PADRAO.match(item.name)
+        if casamento:
+            encontradas.append(
+                Migracao(int(casamento.group(1)), item.name, item.read_text(encoding="utf-8"))
+            )
+    encontradas.sort(key=lambda m: m.versao)
+    for esperado, migracao in enumerate(encontradas, start=1):
+        if migracao.versao != esperado:
+            raise RuntimeError(f"migração {esperado:04d} faltando antes de {migracao.nome}")
+    return encontradas

money_cli/armazenamento/preferencias.py

@@ -0,0 +1,31 @@
+"""Preferências do usuário em `tema.toml`, na pasta de dados. Erro nunca impede o app."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+NOME_ARQUIVO = "tema.toml"
+
+
+def ler_tema(pasta: Path) -> str | None:
+    """Nome do tema salvo, ou None se o arquivo não existe, está ilegível ou sem `tema`."""
+    try:
+        with (pasta / NOME_ARQUIVO).open("rb") as arquivo:
+            nome = tomllib.load(arquivo).get("tema")
+    except (OSError, tomllib.TOMLDecodeError):
+        return None
+    return nome if isinstance(nome, str) else None
+
+
+def gravar_tema(pasta: Path, nome: str) -> bool:
+    """Grava o tema por arquivo temporário e troca atômica. False se não foi possível."""
+    destino = pasta / NOME_ARQUIVO
+    temporario = destino.with_suffix(".toml.tmp")
+    try:
+        pasta.mkdir(parents=True, exist_ok=True)
+        temporario.write_text(f'tema = "{nome}"\n', encoding="utf-8")
+        temporario.replace(destino)
+    except OSError:
+        return False
+    return True

money_cli/armazenamento/trava.py

@@ -0,0 +1,123 @@
+"""Trava de uso (D38): evita abrir o mesmo banco em dois computadores ao mesmo tempo.
+
+Com a pasta de dados num serviço de sincronização (Google Drive), dois computadores abertos
+juntos geram "cópias em conflito" e perdem lançamentos. Enquanto o Kotsu está aberto existe
+`kotsu.trava` ao lado do banco, dizendo quem está usando. A trava é um aviso entre
+computadores, não uma garantia: o Drive leva alguns segundos para propagá-la.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import socket
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+NOME_TRAVA = "kotsu.trava"
+
+
+class BancoEmUso(Exception):
+    """Outro Kotsu (ou outro computador) está com o banco aberto."""
+
+    def __init__(self, maquina: str, desde: str, mesma_maquina: bool) -> None:
+        self.maquina, self.desde, self.mesma_maquina = maquina, desde, mesma_maquina
+        onde = "neste computador" if mesma_maquina else f"no computador {maquina}"
+        super().__init__(f"O Kotsu já está aberto {onde} (desde {desde}).")
+
+
+@dataclass
+class Trava:
+    caminho: Path
+
+    def liberar(self) -> None:
+        """Remove a trava, só se ainda for deste processo."""
+        if (
+            _ler(self.caminho).get("pid") == os.getpid()
+            and _ler(self.caminho).get("maquina") == _maquina()
+        ):
+            self.caminho.unlink(missing_ok=True)
+
+
+def tomar(pasta: Path, desde: str, forcar: bool = False) -> Trava:
+    """Cria a trava ou levanta `BancoEmUso`. `forcar` assume uma trava de outro dono."""
+    caminho = pasta / NOME_TRAVA
+    pasta.mkdir(parents=True, exist_ok=True)
+    dono = _ler(caminho)
+    if dono and not forcar:
+        mesma = dono.get("maquina") == _maquina()
+        # Na mesma máquina, trava de processo que já morreu (queda de energia) é descartada.
+        if not (mesma and not _vivo(int(dono.get("pid", 0)))):
+            raise BancoEmUso(str(dono.get("maquina", "?")), str(dono.get("desde", "?")), mesma)
+    conteudo = json.dumps({"maquina": _maquina(), "pid": os.getpid(), "desde": desde})
+    caminho.unlink(missing_ok=True)
+    try:
+        descritor = os.open(caminho, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    except FileExistsError:  # dois Kotsu na mesma hora: perde quem chegou depois
+        dono = _ler(caminho)
+        raise BancoEmUso(
+            str(dono.get("maquina", "?")),
+            str(dono.get("desde", "?")),
+            dono.get("maquina") == _maquina(),
+        ) from None
+    with os.fdopen(descritor, "w", encoding="utf-8") as arquivo:
+        arquivo.write(conteudo)
+    return Trava(caminho)
+
+
+def conflitos(pasta: Path, nome_banco: str) -> list[Path]:
+    """Cópias do banco que o Drive cria ao ver duas edições (ex.: `money (1).sqlite`).
+
+    Ignora o banco, backups e as cópias de pré-migração (`money.antes-v2.sqlite`).
+    """
+    stem = Path(nome_banco).stem
+    padrao = re.compile(re.escape(stem) + r".+\.sqlite", re.IGNORECASE)
+    antes = re.compile(re.escape(stem) + r"\.antes-v\d+\.sqlite", re.IGNORECASE)
+    try:
+        itens = sorted(pasta.iterdir())
+    except OSError:
+        return []
+    return [
+        p for p in itens if p.is_file() and padrao.fullmatch(p.name) and not antes.fullmatch(p.name)
+    ]
+
+
+def _maquina() -> str:
+    return socket.gethostname()
+
+
+def _ler(caminho: Path) -> dict:
+    try:
+        dados = json.loads(caminho.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        # Trava existe mas está ilegível (ainda sincronizando): trata como de dono desconhecido.
+        return {"maquina": "?", "pid": 0, "desde": "?"} if caminho.exists() else {}
+    return dados if isinstance(dados, dict) else {}
+
+
+def _vivo(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    if sys.platform == "win32":  # os.kill(pid, 0) MATA o processo no Windows
+        import ctypes
+
+        kernel = ctypes.windll.kernel32
+        processo = kernel.OpenProcess(0x1000, False, pid)  # QUERY_LIMITED_INFORMATION
+        if not processo:
+            return False
+        try:
+            codigo = ctypes.c_ulong()
+            return bool(kernel.GetExitCodeProcess(processo, ctypes.byref(codigo))) and (
+                codigo.value == 259  # STILL_ACTIVE
+            )
+        finally:
+            kernel.CloseHandle(processo)
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True

money_cli/armazenamento/troca.py

@@ -0,0 +1,285 @@
+"""Arquivo de troca entre aparelhos (D39): exportar, importar (mesclar) e conferir.
+
+Cada aparelho tem o próprio banco. Para juntar os dados, um exporta um arquivo JSON com
+tudo o que tem e o outro importa: a mesclagem (`dominio.mescla`) decide registro a registro.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import json
+import os
+import sqlite3
+import tempfile
+from pathlib import Path
+
+from money_cli.armazenamento.banco import Banco, copiar_banco
+from money_cli.dominio import mescla
+from money_cli.dominio.mescla import Comparacao, ErroDeTroca, Resumo
+
+NOME_ANTES = "antes-da-troca"
+
+_CAMPOS_SERIE = (
+    "grupo",
+    "dia",
+    "descricao",
+    "valor",
+    "tipo",
+    "conta",
+    "categoria",
+    "gerada_ate",
+    "encerrada",
+    "alterado_em",
+)
+_CAMPOS_LANCAMENTO = (
+    "uid",
+    "data",
+    "descricao",
+    "valor",
+    "tipo",
+    "conta",
+    "categoria",
+    "recorrencia",
+    "gerado",
+    "alterado_em",
+)
+
+
+def ler_estado(banco: Banco) -> dict:
+    """O conteúdo inteiro do banco, com `uid` no lugar dos ids locais."""
+    c = banco.conexao
+    contas = [
+        {"uid": uid, "nome": nome, "cor": cor, "alterado_em": em}
+        for uid, nome, cor, em in c.execute(
+            "SELECT uid, nome, cor, alterado_em FROM conta ORDER BY uid"
+        )
+    ]
+    categorias = [
+        {"uid": uid, "nome": nome, "recorrente": bool(rec), "alterado_em": em}
+        for uid, nome, rec, em in c.execute(
+            "SELECT uid, nome, recorrente, alterado_em FROM categoria ORDER BY uid"
+        )
+    ]
+    recorrencias = []
+    for linha in c.execute(
+        "SELECT r.grupo, r.dia, r.descricao, r.valor, r.tipo, conta.uid, categoria.uid,"
+        " r.gerada_ate, r.encerrada, r.alterado_em FROM recorrencia r"
+        " JOIN conta ON conta.id = r.conta_id"
+        " LEFT JOIN categoria ON categoria.id = r.categoria_id ORDER BY r.grupo"
+    ):
+        serie = dict(zip(_CAMPOS_SERIE, linha, strict=True))
+        serie["encerrada"] = bool(serie["encerrada"])
+        recorrencias.append(serie)
+    lancamentos = []
+    for *comuns, grupo, numero, total in c.execute(
+        "SELECT l.uid, l.data, l.descricao, l.valor, l.tipo, conta.uid, categoria.uid,"
+        " l.grupo_recorrencia, l.gerado, l.alterado_em,"
+        " l.grupo_parcela, l.parcela_numero, l.parcela_total FROM lancamento l"
+        " JOIN conta ON conta.id = l.conta_id"
+        " LEFT JOIN categoria ON categoria.id = l.categoria_id ORDER BY l.uid"
+    ):
+        lanc = dict(zip(_CAMPOS_LANCAMENTO, comuns, strict=True))
+        lanc["gerado"] = bool(lanc["gerado"])
+        lanc["parcela"] = (
+            None if grupo is None else {"grupo": grupo, "numero": numero, "total": total}
+        )
+        lancamentos.append(lanc)
+    lapides = [
+        {"uid": uid, "excluido_em": em}
+        for uid, em in c.execute("SELECT uid, excluido_em FROM lapide ORDER BY uid")
+    ]
+    return {
+        "contas": contas,
+        "categorias": categorias,
+        "recorrencias": recorrencias,
+        "lancamentos": lancamentos,
+        "lapides": lapides,
+    }
+
+
+def codigo(banco: Banco) -> str:
+    """Código de conferência dos dados deste banco."""
+    return mescla.codigo(ler_estado(banco))
+
+
+def exportar(banco: Banco, destino: Path, agora: dt.datetime | None = None) -> str:
+    """Escreve o arquivo de troca em `destino` (troca atômica). Devolve o código."""
+    estado = ler_estado(banco)
+    conferencia = mescla.codigo(estado)
+    arquivo = {
+        "app": "kotsu",
+        "formato": mescla.FORMATO,
+        "replica": banco.replica,
+        "exportado_em": (agora or dt.datetime.now()).isoformat(timespec="seconds"),
+        "conferencia": conferencia,
+        **estado,
+    }
+    destino.parent.mkdir(parents=True, exist_ok=True)
+    descritor, nome = tempfile.mkstemp(prefix=".troca-", suffix=".tmp", dir=destino.parent)
+    temporario = Path(nome)
+    try:
+        with os.fdopen(descritor, "w", encoding="utf-8") as saida:
+            json.dump(arquivo, saida, ensure_ascii=False, separators=(",", ":"))
+            saida.flush()
+            os.fsync(saida.fileno())
+        temporario.replace(destino)
+    finally:
+        temporario.unlink(missing_ok=True)
+    return conferencia
+
+
+def ler_arquivo(origem: Path) -> dict:
+    """Lê e valida um arquivo de troca. Levanta `ErroDeTroca` com mensagem para a pessoa."""
+    try:
+        texto = origem.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as erro:
+        raise ErroDeTroca(f"não foi possível ler {origem}: {erro}") from None
+    try:
+        dados = json.loads(texto)
+    except ValueError:
+        raise ErroDeTroca(f"{origem} não é uma exportação do Kotsu") from None
+    return mescla.validar(dados)
+
+
+def comparar(banco: Banco, origem: Path) -> Comparacao:
+    """Diferenças entre este banco e o arquivo de outro aparelho. Não muda nada."""
+    return mescla.comparar(ler_estado(banco), ler_arquivo(origem))
+
+
+def importar(banco: Banco, origem: Path) -> Resumo:
+    """Mescla o arquivo de outro aparelho neste banco, numa transação só.
+
+    Antes de mudar qualquer coisa, guarda uma cópia do banco em `backups/` (uma só,
+    substituída a cada importação que muda algo).
+    """
+    remoto = ler_arquivo(origem)
+    local = ler_estado(banco)
+    novo = mescla.mesclar(local, remoto)
+    visto = mescla.maior_carimbo(remoto)
+    if novo == local:
+        with banco.transacao() as c:
+            _avancar_relogio(c, visto)
+        return Resumo()
+    if banco.caminho is not None:
+        pasta = banco.pasta_backups or banco.caminho.parent / "backups"
+        try:
+            pasta.mkdir(parents=True, exist_ok=True)
+            copiar_banco(banco.conexao, pasta / f"{banco.caminho.stem}.{NOME_ANTES}.sqlite")
+        except (OSError, sqlite3.Error) as erro:
+            raise ErroDeTroca(
+                f"não foi possível guardar a cópia de segurança em {pasta}: {erro}"
+            ) from None
+    with banco.transacao() as c:
+        _aplicar(c, novo)
+        _avancar_relogio(c, visto)
+    return mescla.resumir(local, novo)
+
+
+def _avancar_relogio(c: sqlite3.Connection, visto: str) -> None:
+    """O próximo carimbo daqui passa de tudo o que o arquivo trouxe."""
+    c.execute(
+        "UPDATE meta SET valor = max(valor, ?) WHERE chave = 'relogio'",
+        (visto,),
+    )
+
+
+def _aplicar(c: sqlite3.Connection, novo: dict) -> None:
+    """Deixa o banco igual ao estado `novo`, preservando os ids locais."""
+    contas = _aplicar_nomeados(c, "conta", novo["contas"], ("cor",))
+    categorias = _aplicar_nomeados(c, "categoria", novo["categorias"], ("recorrente",))
+
+    for r in novo["recorrencias"]:
+        c.execute(
+            "INSERT INTO recorrencia (grupo, dia, descricao, valor, tipo, conta_id, categoria_id,"
+            " gerada_ate, encerrada, alterado_em) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)"
+            " ON CONFLICT (grupo) DO UPDATE SET dia = excluded.dia,"
+            " descricao = excluded.descricao, valor = excluded.valor, tipo = excluded.tipo,"
+            " conta_id = excluded.conta_id, categoria_id = excluded.categoria_id,"
+            " gerada_ate = excluded.gerada_ate, encerrada = excluded.encerrada,"
+            " alterado_em = excluded.alterado_em",
+            (
+                r["grupo"],
+                r["dia"],
+                r["descricao"],
+                r["valor"],
+                r["tipo"],
+                contas[r["conta"]],
+                categorias.get(r["categoria"]),
+                r["gerada_ate"],
+                int(r["encerrada"]),
+                r["alterado_em"],
+            ),
+        )
+
+    locais = {uid for (uid,) in c.execute("SELECT uid FROM lancamento")}
+    vivos = {x["uid"] for x in novo["lancamentos"]}
+    c.executemany("DELETE FROM lancamento WHERE uid = ?", [(uid,) for uid in locais - vivos])
+    for x in novo["lancamentos"]:
+        p = x["parcela"] or {}
+        valores = (
+            x["data"],
+            x["descricao"],
+            x["valor"],
+            x["tipo"],
+            contas[x["conta"]],
+            categorias.get(x["categoria"]),
+            p.get("grupo"),
+            p.get("numero"),
+            p.get("total"),
+            x["recorrencia"],
+            int(x["gerado"]),
+            x["alterado_em"],
+            x["uid"],
+        )
+        if x["uid"] in locais:
+            c.execute(
+                "UPDATE lancamento SET data = ?, descricao = ?, valor = ?, tipo = ?, conta_id = ?,"
+                " categoria_id = ?, grupo_parcela = ?, parcela_numero = ?, parcela_total = ?,"
+                " grupo_recorrencia = ?, gerado = ?, alterado_em = ? WHERE uid = ?",
+                valores,
+            )
+        else:
+            c.execute(
+                "INSERT INTO lancamento (data, descricao, valor, tipo, conta_id, categoria_id,"
+                " grupo_parcela, parcela_numero, parcela_total, grupo_recorrencia, gerado,"
+                " alterado_em, uid) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                valores,
+            )
+
+    c.executemany(
+        "INSERT OR REPLACE INTO lapide (uid, excluido_em) VALUES (?, ?)",
+        [(x["uid"], x["excluido_em"]) for x in novo["lapides"]],
+    )
+
+
+def _aplicar_nomeados(
+    c: sqlite3.Connection, tabela: str, itens: list[dict], campos: tuple[str, ...]
+) -> dict[str, int]:
+    """Grava contas ou categorias mescladas. Devolve `uid -> id local`.
+
+    A que existe aqui com o mesmo nome e outro `uid` é a mesma: passa a usar o `uid` que a
+    mesclagem escolheu, e os lançamentos daqui continuam apontando para ela.
+    """
+    por_uid, por_nome = {}, {}
+    for id_, uid, nome in c.execute(f"SELECT id, uid, nome FROM {tabela}").fetchall():
+        por_uid[uid] = id_
+        por_nome[mescla.chave_do_nome(nome)] = id_
+    ids = {}
+    atribuicoes = ", ".join(f"{campo} = ?" for campo in campos)
+    for item in itens:
+        valores = [int(v) if isinstance(v, bool) else v for v in (item[k] for k in campos)]
+        id_ = por_uid.get(item["uid"]) or por_nome.get(mescla.chave_do_nome(item["nome"]))
+        if id_ is None:
+            id_ = c.execute(
+                f"INSERT INTO {tabela} (uid, nome, alterado_em, {', '.join(campos)})"
+                f" VALUES (?, ?, ?{', ?' * len(campos)})",
+                (item["uid"], item["nome"], item["alterado_em"], *valores),
+            ).lastrowid
+        else:
+            c.execute(
+                f"UPDATE {tabela} SET uid = ?, nome = ?, alterado_em = ?, {atribuicoes}"
+                " WHERE id = ?",
+                (item["uid"], item["nome"], item["alterado_em"], *valores, id_),
+            )
+        ids[item["uid"]] = id_
+    return ids

money_cli/dominio/__init__.py

@@ -0,0 +1,5 @@
+"""Camada de domínio: tipos e regras puras, sem I/O.
+
+Não importa nada de `armazenamento` nem de `tela`, nem módulos de I/O
+(arquivo, banco, rede, terminal). O teste de camadas confere isso.
+"""

money_cli/dominio/dinheiro.py

@@ -0,0 +1,10 @@
+"""Formatação de valores em centavos inteiros."""
+
+
+def formatar(centavos: int) -> str:
+    """Formata centavos como BRL sem sinal: 123456 -> '1.234,56'.
+
+    O sinal nunca aparece no texto: negativo é mostrado só em vermelho pela tela.
+    """
+    reais, cents = divmod(abs(centavos), 100)
+    return f"{reais:,}".replace(",", ".") + f",{cents:02d}"

money_cli/dominio/filtro.py

@@ -0,0 +1,63 @@
+"""Filtro da tela principal (D12, D26). Puro: lê o texto; a tela resolve os nomes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from money_cli.dominio.linha import ErroDeLinha
+
+
+@dataclass(frozen=True, slots=True)
+class FiltroDigitado:
+    """O que foi digitado depois de `/`, antes de virar ids."""
+
+    conta: str | None = None  # @nome
+    categoria: str | None = None  # #nome
+    qualquer: str | None = None  # nome sem prefixo: conta ou categoria
+
+    @property
+    def vazio(self) -> bool:
+        return self.conta is None and self.categoria is None and self.qualquer is None
+
+
+@dataclass(frozen=True, slots=True)
+class Filtro:
+    """Filtro já resolvido em ids. Vale o "e" entre conta e categoria."""
+
+    conta_id: int | None = None
+    categoria_id: int | None = None
+
+    @property
+    def ativo(self) -> bool:
+        return self.conta_id is not None or self.categoria_id is not None
+
+
+SEM_FILTRO = Filtro()
+
+
+def interpretar_filtro(texto: str) -> FiltroDigitado:
+    """`@nubank`, `#casa`, `@nubank #casa` ou `nubank`. Levanta `ErroDeLinha`."""
+    conta = categoria = qualquer = None
+    soltas: list[str] = []
+    for parte in texto.split():
+        if parte.startswith("@"):
+            if conta is not None:
+                raise ErroDeLinha("só uma @conta no filtro")
+            conta = _nome(parte, "conta")
+        elif parte.startswith("#"):
+            if categoria is not None:
+                raise ErroDeLinha("só uma #categoria no filtro")
+            categoria = _nome(parte, "categoria")
+        else:
+            soltas.append(parte)
+    if soltas:
+        if conta is not None or categoria is not None:
+            raise ErroDeLinha("use @conta e #categoria juntos, ou só um nome")
+        qualquer = " ".join(soltas)
+    return FiltroDigitado(conta, categoria, qualquer)
+
+
+def _nome(parte: str, oque: str) -> str:
+    if len(parte) == 1:
+        raise ErroDeLinha(f"falta o nome da {oque} depois de {parte}")
+    return parte[1:]