susflow 0.1.1__py3-none-any.whl

susflow/__init__.py

@@ -0,0 +1,3 @@
+from .ftp    import FTPError, ArquivoNaoEncontradoError
+from .reader import LeituraError, ler
+from .systems import sinasc, sim, sinan

susflow/cache.py

@@ -0,0 +1,26 @@
+"""
+susflow/cache.py
+================
+Resolução de cache local. Compartilhado por todos os sistemas.
+Pasta padrão: ~/.susflow/cache/, espelhando a estrutura do FTP.
+"""
+
+from pathlib import Path
+
+_CACHE_PADRAO = Path.home() / ".susflow" / "cache"
+
+
+def caminho_local(caminho_ftp: str, raiz: Path | None = None) -> Path:
+    """
+    Retorna o path local correspondente a um caminho FTP.
+    Ex: /dissemin/publicos/SINASC/NOV/DNRES/DNSP2022.dbc
+     →  ~/.susflow/cache/dissemin/publicos/SINASC/NOV/DNRES/DNSP2022.dbc
+    """
+    raiz = Path(raiz) if raiz else _CACHE_PADRAO
+    # remove a barra inicial para não criar path absoluto ao fazer /
+    relativo = caminho_ftp.lstrip("/")
+    return raiz / relativo
+
+
+def existe(caminho_ftp: str, raiz: Path | None = None) -> bool:
+    return caminho_local(caminho_ftp, raiz).exists()

susflow/config.py

@@ -0,0 +1,358 @@
+"""
+susflow/config.py
+=================
+Metadados de todos os sistemas do DATASUS.
+
+Campos de cada sistema:
+  ftp_dir       — caminho absoluto no FTP
+  pattern       — padrão do nome ({UF}, {YYYY}, {YY}, {PREFIX}, {DISEASE}, {TYPE})
+  granularity   — "year" | "month"
+  year_digits   — 2 ou 4
+  format        — "dbc" | "dbf" | "zip"
+  scope         — "uf" | "national"
+  year_range    — (ano_inicio, ano_fim) inclusive
+"""
+
+FTP_HOST = "ftp.datasus.gov.br"
+
+UFS = [
+    "AC", "AL", "AM", "AP", "BA", "CE", "DF", "ES", "GO",
+    "MA", "MG", "MS", "MT", "PA", "PB", "PE", "PI", "PR",
+    "RJ", "RN", "RO", "RR", "RS", "SC", "SE", "SP", "TO",
+]
+
+# ---------------------------------------------------------------------------
+# SIM — /dissemin/publicos/SIM/CID10/
+#   DORES/  → DO{UF}{YYYY}.dbc      por UF, anual, 4 dígitos
+#   DOFET/  → DO{TYPE}{YY}.dbc      nacional, anual, 2 dígitos
+#             tipos: EXT, FET, INF, MAT
+# ---------------------------------------------------------------------------
+SIM = {
+    "description": "Sistema de Informações sobre Mortalidade",
+    "ftp_base":    "/dissemin/publicos/SIM/CID10",
+
+    # Documentação técnica e layouts de campos
+    "docs": {
+        "ftp_dir": "/dissemin/publicos/SIM/CID10/DOCS",
+        "arquivos": {
+            "Docs_Tabs_CID10.zip":       "Layouts, tabelas e dicionário de variáveis",
+            "Estrutura_do_SIM_2025.pdf": "Estrutura atual dos arquivos (referência principal)",
+            "Estrutura_SIM_Anterior.pdf": "Estrutura anterior — necessária para bases legadas",
+        },
+    },
+
+    # Dados agregados tabulados
+    "tab": {
+        "ftp_dir": "/dissemin/publicos/SIM/CID10/TAB",
+        "arquivos": {
+            "OBITOS_CID10_TAB.zip": "Óbitos agregados por CID-10 (série histórica tabulada)",
+        },
+    },
+
+    # Tabelas de apoio (CID-10, municípios, ocupações, países, UFs)
+    "tabelas": {
+        "ftp_dir": "/dissemin/publicos/SIM/CID10/TABELAS",
+        "arquivos": {
+            "CID10.DBF":      "Classificação Internacional de Doenças — CID-10",
+            "CIDCAP10.DBF":   "Capítulos do CID-10",
+            "CADMUN.DBF":     "Cadastro de municípios",
+            "CADMUN.xls":     "Cadastro de municípios (formato Excel)",
+            "TABOCUP.DBF":    "Tabela de ocupações (CBO)",
+            "TABPAIS.DBF":    "Tabela de países",
+            "TABUF.DBF":      "Tabela de unidades federativas",
+        },
+    },
+
+    "uf": {
+        "ftp_dir":     "/dissemin/publicos/SIM/CID10/DORES",
+        "pattern":     "DO{UF}{YYYY}.dbc",
+        "granularity": "year",
+        "year_digits": 4,
+        "format":      "dbc",
+        "scope":       "uf",
+        "year_range":  (1996, 2024),
+    },
+
+    "special": {
+        "ftp_dir":     "/dissemin/publicos/SIM/CID10/DOFET",
+        "pattern":     "DO{TYPE}{YY}.dbc",
+        "granularity": "year",
+        "year_digits": 2,
+        "format":      "dbc",
+        "scope":       "national",
+        "year_range":  (1996, 2024),
+        "types": {
+            "EXT": "Óbitos por causas externas",
+            "FET": "Óbitos fetais",
+            "INF": "Óbitos infantis",
+            "MAT": "Óbitos maternos",
+        },
+    },
+}
+
+# ---------------------------------------------------------------------------
+# SINASC — /dissemin/publicos/SINASC/NOV/
+#   DNRES/  → DN{UF}{YYYY}.dbc      por UF, anual, 4 dígitos
+#   DNRES/  → DNBR{YYYY}.dbc        agregado nacional (2014–2017 apenas)
+#   DNRES/  → DNEX{YYYY}.dbc        exceções/suplementar (pontual, ex: 2021)
+#   DOCS/   → documentação técnica  (caminho a confirmar — não mapeado ainda)
+# ---------------------------------------------------------------------------
+SINASC = {
+    "description": "Sistema de Informações sobre Nascidos Vivos",
+
+    "uf": {
+        "ftp_dir":     "/dissemin/publicos/SINASC/NOV/DNRES",
+        "pattern":     "DN{UF}{YYYY}.dbc",
+        "granularity": "year",
+        "year_digits": 4,
+        "format":      "dbc",
+        "scope":       "uf",
+        "year_range":  (1996, 2022),
+    },
+
+    # Agregado nacional — série incompleta (apenas 2014–2017 confirmados no FTP)
+    "nacional": {
+        "ftp_dir":     "/dissemin/publicos/SINASC/NOV/DNRES",
+        "pattern":     "DNBR{YYYY}.dbc",
+        "granularity": "year",
+        "year_digits": 4,
+        "format":      "dbc",
+        "scope":       "national",
+        "year_range":  (2014, 2017),
+    },
+
+    # Arquivo de exceção/suplementar — pontual, não é uma série regular
+    "excecoes": {
+        "ftp_dir": "/dissemin/publicos/SINASC/NOV/DNRES",
+        "pattern": "DNEX{YYYY}.dbc",
+        "format":  "dbc",
+        "nota":    "Arquivos pontuais com registros suplementares. Confirmado: DNEX2021.dbc.",
+    },
+
+    # Documentação técnica — caminho exato a confirmar (não mapeado ainda)
+    "docs": {
+        "ftp_dir": "/dissemin/publicos/SINASC/NOV/DOCS",
+        "arquivos": {
+            "Estrutura_SINASC_para_CD.pdf": "Estrutura dos arquivos (formato legado de CD-ROM)",
+            "Legislacao_PDF.pdf":           "Legislação relacionada ao SINASC",
+            "NASC98.HLP":                   "Arquivo de ajuda do sistema legado (1998)",
+            "Portaria.pdf":                 "Portaria regulamentadora",
+        },
+        "nota": "Caminho FTP não confirmado — diretório DOCS não foi mapeado ainda.",
+    },
+}
+
+# ---------------------------------------------------------------------------
+# SINAN — /dissemin/publicos/SINAN/DADOS/
+#   FINAIS/{DISEASE}BR{YY}.dbc    dados consolidados
+#   PRELIM/{DISEASE}BR{YY}.dbc    dados preliminares
+#   DOCS/                         documentação técnica (caminho a confirmar)
+# ---------------------------------------------------------------------------
+SINAN = {
+    "description":    "Sistema de Informações de Agravos de Notificação",
+    "ftp_dir":        "/dissemin/publicos/SINAN/DADOS/FINAIS",
+    "ftp_dir_prelim": "/dissemin/publicos/SINAN/DADOS/PRELIM",
+    "pattern":        "{DISEASE}BR{YY}.dbc",
+    "granularity":    "year",
+    "year_digits":    2,
+    "format":         "dbc",
+    "scope":          "national",
+    "diseases": {
+        "ACBI": "Acidente por animal peçonhento",
+        "ACGR": "Acidente de trabalho grave",
+        "ANIM": "Acidente por animal (outros)",
+        "ANTR": "Antraz (Carbúnculo)",
+        "BOTU": "Botulismo",
+        "CANC": "Câncer relacionado ao trabalho",
+        "CHAG": "Doença de Chagas",
+        "CHIK": "Chikungunya",
+        "COLE": "Cólera",
+        "COQU": "Coqueluche",
+        "DCRJ": "Doença de Creutzfeldt-Jakob",
+        "DENG": "Dengue",
+        "DERM": "Dermatose ocupacional",
+        "DIFT": "Difteria",
+        "ESPO": "Esporotricose",
+        "ESQU": "Esquistossomose",
+        "FMAC": "Febre maculosa",
+        "FTIF": "Febre tifoide",
+        "HANS": "Hanseníase",
+        "HANT": "Hantavirose",
+        "IEXO": "Intoxicação exógena",
+        "LEIV": "Leishmaniose visceral",
+        "LEPT": "Leptospirose",
+        "LERD": "LER/DORT",
+        "LTA":  "Leishmaniose tegumentar americana",
+        "MALA": "Malária",
+        "MENI": "Meningite",
+        "MENT": "Transtorno mental relacionado ao trabalho",
+        "NTRA": "Noma (Cancrum oris)",
+        "PAIR": "Perda auditiva induzida por ruído",
+        "PEST": "Peste",
+        "PFAN": "Paralisia flácida aguda / Poliomielite",
+        "PNEU": "Pneumoconiose",
+        "RAIV": "Raiva humana",
+        "ROTA": "Rotavírus",
+        "SDTA": "Surto de doença transmitida por alimento",
+        "TETA": "Tétano acidental",
+        "TETN": "Tétano neonatal",
+        "TOXC": "Toxoplasmose congênita",
+        "TOXG": "Toxoplasmose gestacional",
+        "TRAC": "Tracoma",
+        "TUBE": "Tuberculose",
+        "VIOL": "Violência doméstica / sexual / autoprovocada",
+        "ZIKA": "Zika vírus",
+    },
+
+    # Documentação técnica — caminho FTP a confirmar (não mapeado ainda)
+    "docs": {
+        "ftp_dir": "/dissemin/publicos/SINAN/DOCS",
+        "arquivos": {
+            "Docs_TAB_SINAN.zip":                              "Layouts, tabelas e dicionário de variáveis de todos os agravos",
+            "POP_I_Acesso_a_Microdados_5.pdf":                 "Guia de acesso aos microdados do SINAN",
+            "POP_II_Descompactacao_expansao_conversao_3.pdf":  "Guia de descompactação e conversão dos arquivos .dbc",
+            "POP_III_Instalacao_do_tabulador_TabWin_3.pdf":    "Guia de instalação do TabWin (tabulador oficial)",
+            "Nota_Tecnica_Doenca_de_Creutzfeldt-Jakob(DCJ).pdf": "Nota técnica — Doença de Creutzfeldt-Jakob",
+            "Nota_Tecnica_Intoxicacao_Exogena.pdf":            "Nota técnica — Intoxicação Exógena",
+            "Nota_Tecnica_Rotavirus.pdf":                      "Nota técnica — Rotavírus",
+            "Nota_Tecnica_Surtos_de_DTA.pdf":                  "Nota técnica — Surtos de Doença Transmitida por Alimento",
+            "Nota_Tecnica_Toxoplasmose.pdf":                   "Nota técnica — Toxoplasmose",
+        },
+        "nota": "Caminho FTP não confirmado — diretório DOCS não foi mapeado ainda.",
+    },
+}
+
+# ---------------------------------------------------------------------------
+# SIHSUS — /dissemin/publicos/SIHSUS/200801_/Dados/
+#   {PREFIX}{UF}{YY}{MM}.dbc    por UF, mensal, 2 dígitos
+#   Prefixo principal: RD (AIH Reduzida — registro de internação)
+#   Exceção: CH e CM usam BR fixo (escopo nacional), não {UF}
+# ---------------------------------------------------------------------------
+SIHSUS = {
+    "description": "Sistema de Informações Hospitalares do SUS",
+    "ftp_dir":     "/dissemin/publicos/SIHSUS/200801_/Dados",
+    "ftp_dir_old": "/dissemin/publicos/SIHSUS/199201_200712",
+    "pattern":     "{PREFIX}{UF}{YY}{MM}.dbc",
+    "granularity": "month",
+    "year_digits": 2,
+    "format":      "dbc",
+    "scope":       "uf",
+    "year_range":  (2008, 2026),
+    "prefixes": {
+        "RD": "AIH reduzida (internações — dado principal)",
+        "SP": "Serviços profissionais",
+        "RJ": "AIH rejeitada",
+        "ER": "AIH com erro",
+    },
+    # CH e CM usam BR fixo — padrão: {PREFIX}BR{YY}{MM}.dbc
+    "prefixes_nacionais": {
+        "CH": "Cabeçalho nacional (dados agregados)",
+        "CM": "Comunicação de movimento",
+    },
+}
+
+# ---------------------------------------------------------------------------
+# SIASUS — /dissemin/publicos/SIASUS/200801_/Dados/
+#   {PREFIX}{UF}{YY}{MM}.dbc    por UF, mensal, 2 dígitos
+#   Prefixo principal: PA (Produção Ambulatorial)
+# ---------------------------------------------------------------------------
+SIASUS = {
+    "description": "Sistema de Informações Ambulatoriais do SUS",
+    "ftp_dir":     "/dissemin/publicos/SIASUS/200801_/Dados",
+    "ftp_dir_old": "/dissemin/publicos/SIASUS/199407_200712",
+    "pattern":     "{PREFIX}{UF}{YY}{MM}.dbc",
+    "granularity": "month",
+    "year_digits": 2,
+    "format":      "dbc",
+    "scope":       "uf",
+    "year_range":  (2008, 2026),
+    "prefixes": {
+        "PA":  ("Produção Ambulatorial (BPA)",                          2008, 2026),
+        "BI":  ("BPA Individualizado",                                  2008, 2026),
+        "AD":  ("APAC de Laudos Diversos",                              2008, 2026),
+        "AM":  ("APAC de Medicamentos",                                 2008, 2026),
+        "AMP": ("APAC de Medicamentos Padronizados",                    2020, 2026),
+        "AQ":  ("APAC de Quimioterapia",                                2008, 2026),
+        "AR":  ("APAC de Radioterapia",                                 2008, 2026),
+        "ACF": ("APAC Confecção de Fístula Arteriovenosa",              2014, 2026),
+        "ATD": ("APAC Tratamento Dialítico",                            2014, 2026),
+        "PS":  ("RAAS Psicossocial",                                    2013, 2026),
+        "AB":  ("APAC Acompanhamento Pós Cirurgia Bariátrica (novo)",   2025, 2026),
+        "ABO": ("APAC Acompanhamento Pós Cirurgia Bariátrica (legado)", 2015, 2018),
+        "AN":  ("APAC de Nefrologia (encerrado, substituído por ATD)",  2008, 2014),
+        "SAD": ("RAAS Atenção Domiciliar (encerrado)",                  2013, 2015),
+    },
+}
+
+# ---------------------------------------------------------------------------
+# CNES — /dissemin/publicos/CNES/200508_/Dados/
+#   {TYPE}/{TYPE}{UF}{YY}{MM}.dbc    por UF, mensal, 2 dígitos
+#   Arquivo fica 2 níveis dentro de Dados/: ex. ST/STSP2501.dbc
+#   Subtype principal: ST (Estabelecimentos)
+# ---------------------------------------------------------------------------
+CNES = {
+    "description": "Cadastro Nacional de Estabelecimentos de Saúde",
+    "ftp_base":    "/dissemin/publicos/CNES/200508_/Dados",
+    "pattern":     "{TYPE}/{TYPE}{UF}{YY}{MM}.dbc",
+    "granularity": "month",
+    "year_digits": 2,
+    "format":      "dbc",
+    "scope":       "uf",
+    "subtypes": {
+        "ST": ("Estabelecimentos (dado principal)",          2005, 2026),
+        "PF": ("Profissionais de saúde",                    2005, 2026),
+        "DC": ("Dados complementares",                      2005, 2026),
+        "EQ": ("Equipamentos",                              2005, 2026),
+        "SR": ("Serviços especializados",                   2005, 2026),
+        "LT": ("Leitos",                                    2005, 2026),
+        "HB": ("Habilitações",                             2007, 2026),
+        "EF": ("Centros cirúrgicos e obstétricos",          2007, 2026),
+        "EP": ("Equipes de saúde",                          2007, 2026),
+        "RC": ("Regras contratuais",                        2007, 2026),
+        "IN": ("Incentivos",                                2007, 2026),
+        "GM": ("Gestão e metas",                            2014, 2026),
+        "EE": ("Equipamentos e produções (encerrado)",      2007, 2019),
+    },
+}
+
+# ---------------------------------------------------------------------------
+# PNI — /dissemin/publicos/PNI/DADOS/
+#   DPNI{UF}{YY}.DBF    por UF, anual, 2 dígitos
+#   Formato DBF puro (sem compressão blast) — usar dbfread, não pyreaddbc
+# ---------------------------------------------------------------------------
+PNI = {
+    "description": "Programa Nacional de Imunizações",
+    "ftp_dir":     "/dissemin/publicos/PNI/DADOS",
+    "pattern":     "DPNI{UF}{YY}.DBF",
+    "granularity": "year",
+    "year_digits": 2,
+    "format":      "dbf",
+    "scope":       "uf",
+    "year_range":  (1994, 2019),
+}
+
+# ---------------------------------------------------------------------------
+# IBGE/POP — /dissemin/publicos/IBGE/POP/
+#   POPBR{YY}.zip    nacional, anual, 2 dígitos
+# ---------------------------------------------------------------------------
+IBGE_POP = {
+    "description": "Estimativas populacionais IBGE",
+    "ftp_dir":     "/dissemin/publicos/IBGE/POP",
+    "pattern":     "POPBR{YY}.zip",
+    "granularity": "year",
+    "year_digits": 2,
+    "format":      "zip",
+    "scope":       "national",
+    "year_range":  (1980, 2012),
+}
+
+ALL_SYSTEMS = {
+    "SIM":      SIM,
+    "SINASC":   SINASC,
+    "SINAN":    SINAN,
+    "SIHSUS":   SIHSUS,
+    "SIASUS":   SIASUS,
+    "CNES":     CNES,
+    "PNI":      PNI,
+    "IBGE_POP": IBGE_POP,
+}

susflow/ftp.py

@@ -0,0 +1,111 @@
+"""
+susflow/ftp.py
+==============
+Camada de transporte: toda comunicação com o FTP do DATASUS fica aqui.
+"""
+
+import time
+
+from ftplib import FTP, all_errors
+from pathlib import Path
+
+from .config import FTP_HOST
+
+_TIMEOUT    = 30   # segundos
+_TENTATIVAS = 3
+_BACKOFF    = 2    # segundos entre tentativas
+
+
+class FTPError(Exception):
+    """Erro de comunicação com o FTP do DATASUS."""
+
+class ArquivoNaoEncontradoError(FTPError):
+    """Arquivo não existe no FTP."""
+
+def _conectar() -> FTP:
+    """Abre uma conexão FTP limpa. Reconectar por operação evita o bug '200 Type set to A'."""
+    ftp = FTP()
+    ftp.connect(FTP_HOST, 21, timeout=_TIMEOUT)
+    ftp.login()
+    ftp.set_pasv(True)
+    return ftp
+
+
+def _tentar(fn, *args, **kwargs):
+    """Executa fn com retentativas e backoff."""
+    ultimo_erro = None
+    for tentativa in range(_TENTATIVAS):
+        try:
+            return fn(*args, **kwargs)
+        
+        except all_errors as e:
+            ultimo_erro = e
+            if tentativa < _TENTATIVAS - 1:
+                time.sleep(_BACKOFF)
+
+    raise FTPError(f"Falha após {_TENTATIVAS} tentativas: {ultimo_erro}") from ultimo_erro
+
+
+def listar(caminho: str) -> list[str]:
+    """
+    Lista os nomes de arquivo em um diretório FTP.
+    Retorna apenas arquivos (não subdiretórios).
+    """
+    def _listar():
+        ftp = _conectar()
+
+        try:
+            itens: list[str] = []
+            ftp.retrlines("LIST", itens.append)  # LIST no cwd após cwd()
+            ftp.cwd(caminho)
+            itens.clear()
+            ftp.retrlines("LIST", itens.append)
+
+            arquivos = []
+            for linha in itens:
+                if "<DIR>" in linha:
+                    continue
+
+                nome = linha.split()[-1]
+                arquivos.append(nome)
+            
+            return arquivos
+        
+        finally:
+            ftp.quit()
+
+    return _tentar(_listar)
+
+
+def baixar(caminho_ftp: str, destino: Path) -> Path:
+    """
+    Baixa um arquivo do FTP para o caminho local `destino`.
+    Cria os diretórios necessários. Retorna o path do arquivo salvo.
+    Levanta ArquivoNaoEncontradoError se o arquivo não existir no FTP.
+    """
+    destino = Path(destino)
+    destino.parent.mkdir(parents=True, exist_ok=True)
+
+    def _baixar():
+        ftp = _conectar()
+        
+        try:
+            with open(destino, "wb") as f:
+                ftp.retrbinary(f"RETR {caminho_ftp}", f.write)
+
+        except all_errors as e:
+            if destino.exists():
+                destino.unlink()
+
+            if "550" in str(e):
+                raise ArquivoNaoEncontradoError(
+                    f"Arquivo não encontrado no FTP: {caminho_ftp}"
+                ) from e
+            raise
+
+        finally:
+            ftp.quit()
+
+        return destino
+
+    return _tentar(_baixar)

susflow/reader.py

@@ -0,0 +1,97 @@
+"""
+susflow/reader.py
+=================
+Camada de leitura: converte arquivos locais (.dbc, .dbf, .zip) em DataFrame.
+"""
+
+import tempfile
+import zipfile
+
+from pyreaddbc import dbc2dbf
+from pathlib import Path
+from dbfread import DBF
+
+import pandas as pd
+
+
+class LeituraError(Exception):
+    """Falha ao converter arquivo para DataFrame."""
+
+def ler(arquivo: Path) -> pd.DataFrame:
+    """
+    Lê um arquivo local e retorna um DataFrame.
+    Suporta .dbc, .dbf e .zip (que contenha .dbc ou .dbf).
+    Colunas sempre em maiúsculo, strings decodificadas em latin-1.
+    """
+    arquivo = Path(arquivo)
+    sufixo  = arquivo.suffix.lower()
+
+    if sufixo == ".dbc":
+        return _ler_dbc(arquivo)
+    
+    if sufixo == ".dbf":
+        return _ler_dbf(arquivo)
+    
+    if sufixo == ".zip":
+        return _ler_zip(arquivo)
+
+    raise LeituraError(f"Formato não suportado: {sufixo}")
+
+
+def _ler_dbc(arquivo: Path) -> pd.DataFrame:
+    try:
+        with tempfile.NamedTemporaryFile(suffix=".dbf", delete=False) as tmp:
+            tmp_path = Path(tmp.name)
+        
+        try:
+            dbc2dbf(str(arquivo), str(tmp_path))
+            return _ler_dbf(tmp_path)
+        
+        finally:
+            if tmp_path.exists():
+                tmp_path.unlink()
+
+    except LeituraError:
+        raise
+
+    except Exception as e:
+        raise LeituraError(f"Falha ao ler .dbc: {arquivo}") from e
+
+
+def _ler_dbf(arquivo: Path) -> pd.DataFrame:
+    try:
+        tabela = DBF(str(arquivo), encoding="latin-1", load=True)
+        df = pd.DataFrame(iter(tabela))
+        df.columns = df.columns.str.upper()
+        return df
+    
+    except Exception as e:
+        raise LeituraError(f"Falha ao ler .dbf: {arquivo}") from e
+
+
+def _ler_zip(arquivo: Path) -> pd.DataFrame:
+    try:
+        with tempfile.TemporaryDirectory() as tmp:
+            
+            with zipfile.ZipFile(arquivo) as zf:
+                nomes = [n for n in zf.namelist() if not n.endswith("/")]
+                
+                if not nomes:
+                    raise LeituraError(f"ZIP vazio: {arquivo}")
+                
+                zf.extractall(tmp)
+
+            # lê o primeiro arquivo reconhecível dentro do zip
+            for nome in nomes:
+                extraido = Path(tmp) / nome
+                sufixo   = extraido.suffix.lower()
+                if sufixo in (".dbc", ".dbf"):
+                    return ler(extraido)
+
+        raise LeituraError(f"Nenhum .dbc ou .dbf encontrado dentro de {arquivo}")
+    
+    except LeituraError:
+        raise
+
+    except Exception as e:
+        raise LeituraError(f"Falha ao ler .zip: {arquivo}") from e

susflow/requirements.txt

@@ -0,0 +1,3 @@
+dbfread==2.0.7
+pandas==3.0.3
+pyreaddbc==1.2.0

susflow/systems/__init__.py

@@ -0,0 +1,3 @@
+from . import sim, sinasc, sinan, sihsus, siasus, cnes, pni
+
+__all__ = ["sim", "sinasc", "sinan", "sihsus", "siasus", "cnes", "pni"]