geocodebr 0.1.0__py3-none-any.whl

geocodebr/__init__.py

@@ -0,0 +1,26 @@
+from .cache import (
+    definir_pasta_cache,
+    deletar_pasta_cache,
+    listar_dados_cache,
+    listar_pasta_cache,
+)
+from .download_cnefe import download_cnefe
+from .fields import definir_campos
+from .geocode import geocode
+from .cep import busca_por_cep
+from .reverse import geocode_reverso
+from .standardize import enderecobr_padronizar_enderecos
+
+__all__ = [
+    "busca_por_cep",
+    "definir_campos",
+    "definir_pasta_cache",
+    "deletar_pasta_cache",
+    "download_cnefe",
+    "geocode",
+    "geocode_reverso",
+    "listar_dados_cache",
+    "listar_pasta_cache",
+    "enderecobr_padronizar_enderecos",
+]
+

geocodebr/_heap.py

@@ -0,0 +1,119 @@
+"""Detecção do heap NT do interpretador Python no Windows.
+
+O python.exe embute no recurso RT_MANIFEST a declaração de heap; sem
+<heapType>SegmentHeap</heapType>, o processo roda no heap NT legacy, que
+degrada sob alocação/liberação multithread intensa do DuckDB
+(duckdb/duckdb#24027; diagnóstico em quality_reports/diagnoses/).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+NOME_COPIA_PATCH = "python-geocodebr-sh.exe"
+N_CORES_HEAP_LEGACY = 4
+
+_aviso_emitido = False
+
+
+def resolve_exe_base() -> str:
+    """Venv: o exe real é o da base (pegadinha do launcher); demais casos, sys.executable."""
+    if sys.platform == "win32" and sys.prefix != sys.base_prefix:
+        base = Path(sys.base_prefix) / "python.exe"
+        if base.is_file():
+            return str(base)
+    return sys.executable
+
+
+def tem_segment_heap(exe: str) -> bool | None:
+    """True/False no Windows; None fora dele ou se o exe não puder ser lido.
+
+    Procura o elemento XML completo, não a palavra solta: a string
+    "SegmentHeap" fora do manifesto daria falso positivo e silenciaria o aviso.
+    """
+    if sys.platform != "win32":
+        return None
+    try:
+        with open(exe, "rb") as fh:
+            return b"SegmentHeap</heapType>" in fh.read()
+    except OSError:
+        return None
+
+
+def cores_disponiveis() -> int:
+    """Núcleos disponíveis ao processo no Windows.
+
+    Respeita a affinity mask via GetProcessAffinityMask: um processo pinado
+    em menos núcleos (ou rodando em container/VM com restrição) não deve
+    receber mais workers que ela permite. Chamado apenas pelo
+    n_cores_efetivo(), que só ativa no Windows.
+    """
+    try:
+        import ctypes
+
+        kernel32 = ctypes.windll.kernel32
+        kernel32.GetCurrentProcess.restype = ctypes.c_void_p
+        kernel32.GetProcessAffinityMask.restype = ctypes.c_int
+        kernel32.GetProcessAffinityMask.argtypes = [
+            ctypes.c_void_p,
+            ctypes.POINTER(ctypes.c_size_t),
+            ctypes.POINTER(ctypes.c_size_t),
+        ]
+        mascara = ctypes.c_size_t()
+        sistema = ctypes.c_size_t()
+        if kernel32.GetProcessAffinityMask(
+            kernel32.GetCurrentProcess(),
+            ctypes.byref(mascara),
+            ctypes.byref(sistema),
+        ) and mascara.value:
+            return bin(mascara.value).count("1")
+    except Exception:
+        pass
+    return os.cpu_count() or 1
+
+
+def n_cores_efetivo(n_cores: int | None) -> int | None:
+    """Aplica a mitigação de threads no Windows sem Segment Heap.
+
+    No heap legacy a contenção de alocação multithread faz a curva tempo x
+    threads ter mínimo em ~4-6 threads. Quando o usuário não definiu
+    n_cores, limita ao ótimo empírico sem exceder os núcleos disponíveis ao
+    processo — `SET threads` acima dos núcleos não é clampeado pelo DuckDB
+    e só gera oversubscription. Valor explícito é respeitado. O aviso é
+    emitido uma vez por sessão, mesmo com n_cores explícito.
+    """
+    global _aviso_emitido
+    if sys.platform != "win32":
+        return n_cores
+    exe = resolve_exe_base()
+    if tem_segment_heap(exe) is not False:
+        return n_cores
+    original = n_cores
+    if original is None:
+        n_cores = min(N_CORES_HEAP_LEGACY, cores_disponiveis())
+    if not _aviso_emitido:
+        _aviso_emitido = True
+        print(_mensagem_aviso(exe, original, n_cores), file=sys.stderr)
+    return n_cores
+
+
+def _mensagem_aviso(exe: str, n_cores_original: int | None, n_cores_efetivo: int | None) -> str:
+    linhas = [
+        "[geocodebr] interpretador Python com heap NT legacy detectado "
+        f"({exe}): no Windows, o DuckDB pode ter queda de performance e "
+        "deterioração entre chamadas sucessivas de geocode().",
+    ]
+    if n_cores_original is None and n_cores_efetivo is not None:
+        linhas.append(
+            f"Mitigação aplicada: threads do DuckDB limitadas a "
+            f"{n_cores_efetivo} nesta sessão (n_cores não definido)."
+        )
+    linhas.append(
+        "Aceleração real: gere um interpretador com Segment Heap com "
+        "python -m geocodebr._heap_patch\n"
+        "e inicie a sessão pela cópia gerada (python-geocodebr-sh.exe). "
+        'Veja a seção "Windows e performance" do README.'
+    )
+    return "\n".join(linhas)

geocodebr/_heap_patch.py

@@ -0,0 +1,130 @@
+"""Cria cópia do interpretador Python base com Segment Heap habilitado.
+
+Uso (Windows):
+
+    python -m geocodebr._heap_patch
+
+Cria `python-geocodebr-sh.exe` ao lado do interpretador base, patcheando o
+recurso RT_MANIFEST com <heapType>SegmentHeap</heapType> — o original nunca é
+alterado. O ganho de performance do DuckDB vale apenas para sessões iniciadas
+pela cópia: o heap é fixado no image load, não muda em runtime.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+from ._heap import NOME_COPIA_PATCH, resolve_exe_base, tem_segment_heap
+
+_ELEMENTO_HEAP = (
+    b'<heapType xmlns="http://schemas.microsoft.com/SMI/2020/WindowsSettings">'
+    b"SegmentHeap</heapType>"
+)
+_ABRE_ASSEMBLY = b"<assembly"
+_FECHA_ASSEMBLY = b"</assembly>"
+_NS_ASSEMBLY = b"urn:schemas-microsoft-com:asm.v1"
+_BLOCO_APPLICATION = (
+    b'<application xmlns="urn:schemas-microsoft-com:asm.v3">'
+    b"<windowsSettings>" + _ELEMENTO_HEAP + b"</windowsSettings></application>"
+)
+_COMPIME_ENTRE_TAGS = re.compile(rb">\s+<")
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv:
+        print("[geocodebr] uso: python -m geocodebr._heap_patch (sem argumentos).", file=sys.stderr)
+        return 2
+    if sys.platform != "win32":
+        print("[geocodebr] o patch de Segment Heap e exclusivo do Windows.", file=sys.stderr)
+        return 1
+
+    exe = resolve_exe_base()
+    print(f"[geocodebr] interpretador base: {exe}")
+
+    heap = tem_segment_heap(exe)
+    if heap is True:
+        print("[geocodebr] o interpretador base ja declara SegmentHeap; nada a fazer.")
+        return 0
+    if heap is None:
+        print("[geocodebr] nao foi possivel ler o interpretador base.", file=sys.stderr)
+        return 1
+
+    destino = str(Path(exe).with_name(NOME_COPIA_PATCH))
+    try:
+        criar_copia(exe, destino)
+    except ValueError as e:
+        print(f"[geocodebr] {e}", file=sys.stderr)
+        return 1
+    except OSError as e:
+        print(
+            f"[geocodebr] falha ao escrever a copia ({e}). Se o interpretador estiver "
+            "em pasta protegida (ex.: Program Files), use um terminal como "
+            "administrador ou uma instalacao por usuario.",
+            file=sys.stderr,
+        )
+        return 1
+
+    print(f"[geocodebr] copia criada: {destino}")
+    print(
+        "[geocodebr] para acelerar o geocode(), inicie a sessao pela copia "
+        "(ex.: \"" + destino + "\" script.py). A copia usa os pacotes do ambiente "
+        "base; veja a secao \"Windows e performance\" do README."
+    )
+    return 0
+
+
+def criar_copia(exe: str, destino: str) -> None:
+    """Lê o exe, patcheia o manifesto e grava a cópia; lança ValueError/OSError."""
+    dados = Path(exe).read_bytes()
+    ini, fim = encontrar_manifesto(dados)
+    novo = patch_manifesto(dados[ini:fim])
+    patcheado = dados[:ini] + novo + dados[fim:]
+    Path(destino).write_bytes(patcheado)
+    if tem_segment_heap(destino) is not True:
+        raise ValueError(
+            "a copia gerada nao declara SegmentHeap; o patch foi abortado "
+            "(o arquivo original nao foi alterado)."
+        )
+
+
+def encontrar_manifesto(dados: bytes) -> tuple[int, int]:
+    """Localiza a região XML do RT_MANIFEST (start, end) no exe."""
+    ini = dados.find(_ABRE_ASSEMBLY)
+    while ini != -1:
+        fim = dados.find(_FECHA_ASSEMBLY, ini)
+        if fim != -1 and _NS_ASSEMBLY in dados[ini:fim]:
+            return ini, fim + len(_FECHA_ASSEMBLY)
+        ini = dados.find(_ABRE_ASSEMBLY, ini + 1)
+    raise ValueError(
+        "manifesto de aplicacao nao encontrado no interpretador; "
+        "exe nao suportado pelo patch."
+    )
+
+
+def patch_manifesto(manifesto: bytes) -> bytes:
+    """Insere <heapType>SegmentHeap</heapType> devolvendo EXATAMENTE o mesmo
+    tamanho em bytes — o recurso RT_MANIFEST tem tamanho fixo no PE. O espaço
+    entre tags é insignificante no XML: comprime a indentação e preenche o
+    resto com espaços antes de </assembly>."""
+    if b"<heapType" in manifesto:
+        raise ValueError("o manifesto ja declara heapType; nada a fazer.")
+    if b"</windowsSettings>" in manifesto:
+        novo = manifesto.replace(b"</windowsSettings>", _ELEMENTO_HEAP + b"</windowsSettings>", 1)
+    else:
+        novo = manifesto.replace(_FECHA_ASSEMBLY, _BLOCO_APPLICATION + _FECHA_ASSEMBLY, 1)
+    novo = _COMPIME_ENTRE_TAGS.sub(b"><", novo)
+    faltam = len(manifesto) - len(novo)
+    if faltam < 0:
+        raise ValueError(
+            "manifesto sem folga para o patch size-preserving; "
+            "reporte em https://github.com/ipeaGIT/geocodebr/issues"
+        )
+    if faltam > 0:
+        novo = novo.replace(_FECHA_ASSEMBLY, b" " * faltam + _FECHA_ASSEMBLY, 1)
+    return novo
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main(sys.argv[1:]))

geocodebr/cache.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from platformdirs import user_cache_dir, user_config_dir
+
+from .messages import confirm
+from .constants import DATA_RELEASE
+
+
+def caminho_parquet(nome_tabela: str, pasta_dados: str | None = None) -> str:
+    """Monta o caminho de um arquivo parquet do CNEFE no disco.
+
+    Espelha ``caminho_parquet()`` em ``r-package/R/cache.R``. ``pasta_dados`` e
+    o ``data_release`` vigente já foram resolvidos pelo chamador (via
+    ``download_cnefe``), não são redescobertos aqui. O arquivo não precisa
+    existir.
+    """
+    if pasta_dados is None:
+        pasta_dados = listar_pasta_cache()
+
+    path = Path(pasta_dados) / f"geocodebr_data_release_{DATA_RELEASE}" / f"{nome_tabela}.parquet"
+    return path.as_posix()
+
+
+def listar_pasta_cache_padrao() -> str:
+    return str(Path(user_cache_dir("geocodebr")))
+
+
+def listar_arquivo_config() -> str:
+    return str(Path(user_config_dir("geocodebr")) / "cache_dir")
+
+
+def definir_pasta_cache(path: str | None, verboso: bool = True) -> str:
+    """Define a pasta de cache do geocodebr.
+
+    Define o diretório de cache para os dados do geocodebr. Essa configuração
+    é persistente entre sessões do Python.
+
+    Parameters
+    ----------
+    path : str ou None
+        O caminho para o diretório usado para armazenar os dados em cache.
+        Se `None`, o pacote usará o diretório padrão do pacote.
+    verboso : bool, opcional
+        Indica se uma mensagem de confirmação deve ser exibida. O padrão é
+        `True`.
+
+    Returns
+    -------
+    str
+        O caminho do diretório de cache configurado.
+
+    Examples
+    --------
+    >>> definir_pasta_cache("D:/dados/geocodebr-cache")
+
+    # retoma pasta padrão do pacote
+    >>> definir_pasta_cache(path=None)
+    """
+    cache_dir = Path(listar_pasta_cache_padrao()) if path is None else Path(path)
+    cache_dir = cache_dir.expanduser()
+
+    config_file = Path(listar_arquivo_config())
+    config_file.parent.mkdir(parents=True, exist_ok=True)
+    config_file.write_text(str(cache_dir), encoding="utf-8")
+
+    if verboso:
+        confirm(f"Definido como pasta de cache {cache_dir}.")
+
+    return str(cache_dir)
+
+
+def listar_pasta_cache() -> str:
+    """Obtém a pasta de cache usada pelo geocodebr.
+
+    Obtém o caminho da pasta utilizada para armazenar em cache os dados do
+    geocodebr. Útil para inspecionar a pasta configurada com
+    `definir_pasta_cache()` em uma sessão anterior. Retorna a pasta de cache
+    padrão caso nenhuma pasta personalizada tenha sido configurada
+    anteriormente.
+
+    Returns
+    -------
+    str
+        O caminho da pasta de cache.
+    """
+    config_file = Path(listar_arquivo_config())
+    if config_file.exists():
+        value = config_file.read_text(encoding="utf-8").strip()
+        if value:
+            return str(Path(value).expanduser())
+    return listar_pasta_cache_padrao()
+
+
+def listar_dados_cache(print_tree: bool = False) -> list[str]:
+    """Lista os dados salvos localmente na pasta de cache.
+
+    Parameters
+    ----------
+    print_tree : bool, opcional
+        Indica se o conteúdo da pasta de cache deve ser exibido em um formato
+        de árvore. O padrão é `False`.
+
+    Returns
+    -------
+    list[str]
+        Os caminhos para os arquivos em cache.
+    """
+    cache_dir = Path(listar_pasta_cache())
+    if not cache_dir.exists():
+        confirm("Nenhum dado em cache local")
+        return []
+
+    files = sorted(str(path) for path in cache_dir.rglob("*") if path.is_file())
+    if print_tree:
+        _print_tree(cache_dir)
+    return files
+
+
+def deletar_pasta_cache() -> str:
+    """Deleta todos os arquivos da pasta de cache do geocodebr.
+
+    Returns
+    -------
+    str
+        O caminho do diretório de cache deletado.
+    """
+    cache_dir = Path(listar_pasta_cache())
+    if cache_dir.exists():
+        shutil.rmtree(cache_dir)
+    confirm(f"Deletada a pasta de cache que se encontrava em {cache_dir}.")
+    return str(cache_dir)
+
+
+def apaga_data_release_antigo(data_release: str) -> str:
+    cache_dir = Path(listar_pasta_cache())
+    if not cache_dir.exists():
+        return str(cache_dir)
+
+    release_dirs = [
+        path
+        for path in cache_dir.iterdir()
+        if path.is_dir() and path.name.startswith("geocodebr_data_release_")
+    ]
+    expected = cache_dir / f"geocodebr_data_release_{data_release}"
+    stale_dirs = [path for path in release_dirs if path != expected]
+    for path in stale_dirs:
+        shutil.rmtree(path)
+    return str(cache_dir)
+
+
+def _print_tree(root: Path) -> None:
+    print(root)
+    for path in sorted(root.rglob("*")):
+        depth = len(path.relative_to(root).parts)
+        prefix = "  " * depth
+        print(f"{prefix}{path.name}")

geocodebr/cep.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+import enderecobr
+
+from typing import TYPE_CHECKING
+
+import duckdb
+import pyarrow as pa
+
+from .cache import caminho_parquet
+from .db import close_geocodebr_db, create_geocodebr_db
+from .download_cnefe import download_cnefe
+from .errors import SemCorrespondenciaError
+from .geo import arrow_to_geodataframe
+from .matching import add_h3_columns
+from .utils import (
+    normalize_h3_res,
+    sql_string
+)
+
+if TYPE_CHECKING:
+    import geopandas as gpd
+
+
+def busca_por_cep(
+    cep: int | str | list[str|int],
+    h3_res: int | list[int] | tuple[int, ...] | None = None,
+    resultado_gpd: bool = False,
+    verboso: bool = True,
+    cache: bool = True,
+) -> pa.Table | gpd.GeoDataFrame:
+    """Busca endereços e coordenadas a partir de CEPs.
+
+    Recebe um CEP (ou uma lista de CEPs) e retorna os endereços associados a
+    cada CEP presentes no CNEFE, com suas coordenadas geográficas. As
+    coordenadas de output utilizam o sistema de referência SIRGAS 2000,
+    EPSG 4674.
+
+    Parameters
+    ----------
+    cep : int, str ou list[int | str]
+        Um CEP ou uma lista de CEPs. CEPs duplicados são eliminados antes da
+        consulta, e o output não guarda relação de 1 para 1 com o input.
+    h3_res : int, list[int] ou None, opcional
+        Número que indica a resolução espacial das células hexagonais H3 da
+        localização dos pontos retornados. Também aceita uma lista de
+        números, e.g. `[8, 10]`. Por padrão, é `None`. Detalhes sobre as
+        resoluções disponíveis em https://h3geo.org/docs/core-library/restable/
+    resultado_gpd : bool, opcional
+        Indica se o retorno deve ser um `geopandas.GeoDataFrame` de pontos no
+        CRS SIRGAS 2000 (EPSG 4674), equivalente ao `sf` do R. Por padrão, é
+        `False`, e o retorno é um `pyarrow.Table`. Requer o extra `geo`
+        (`pip install geocodebr[geo]`).
+    verboso : bool, opcional
+        Indica se barras de progresso e mensagens devem ser exibidas durante
+        o download dos dados do CNEFE. O padrão é `True`.
+    cache : bool, opcional
+        Indica se os dados do CNEFE devem ser salvos ou lidos do cache,
+        reduzindo o tempo de processamento em chamadas futuras. O padrão é
+        `True`. Quando `False`, os dados do CNEFE são baixados para um
+        diretório temporário.
+
+    Returns
+    -------
+    pyarrow.Table or geopandas.GeoDataFrame
+        Os endereços presentes nos CEPs informados, com as colunas `cep`,
+        `estado`, `municipio`, `logradouro`, `localidade`, `lon` e `lat`. Um
+        mesmo CEP pode cobrir vários logradouros/localidades, de modo que o
+        output pode ter mais linhas que o número de CEPs informados. CEPs sem
+        correspondência retornam como linhas com apenas a coluna `cep`
+        preenchida. Se nenhum CEP for encontrado, a função interrompe com
+        erro.
+    """
+    h3_values = normalize_h3_res(h3_res)
+    ceps = _normalize_ceps(cep)
+    
+    cnefe_dir = download_cnefe("municipio_logradouro_cep_localidade", verboso=verboso, cache=cache)
+    con = create_geocodebr_db()
+    try:
+        path_to_parquet = caminho_parquet(
+            "municipio_logradouro_cep_localidade", cnefe_dir
+        )
+        unique_ceps = ", ".join(sql_string(value) for value in sorted(set(ceps)))
+        con.execute(
+            f"""
+            CREATE OR REPLACE TEMP TABLE output_df AS
+            SELECT cep, estado, municipio, logradouro, localidade, lon, lat
+            FROM read_parquet('{path_to_parquet}')
+            WHERE cep IN ({unique_ceps})
+            """
+        )
+        found_ceps = {
+            row[0]
+            for row in con.execute("SELECT DISTINCT cep FROM output_df").fetchall()
+        }
+        missing = sorted(set(ceps) - found_ceps)
+        if len(missing) == len(set(ceps)):
+            raise SemCorrespondenciaError("Nenhum CEP foi encontrado.")
+        if missing:
+            values = ", ".join(f"({sql_string(value)})" for value in missing)
+            con.execute(f"INSERT INTO output_df (cep) VALUES {values}")
+        add_h3_columns(con, "output_df", h3_values)
+        result = con.execute("SELECT * FROM output_df").to_arrow_table()
+
+        if resultado_gpd:
+            return arrow_to_geodataframe(result)
+
+        return result
+    finally:
+        close_geocodebr_db(con)
+
+
+def _normalize_ceps(cep: int | str | list[str|int]) -> list[str]:
+    values = cep if isinstance(cep, list) else [cep]
+    out = [enderecobr.padronizar_cep_numerico(c) if isinstance(c, int) else enderecobr.padronizar_cep(str(c)) for c in values]
+
+    return sorted(set(out))

geocodebr/constants.py

@@ -0,0 +1,21 @@
+DATA_RELEASE = "v0.5.0"
+
+ALL_CNEFE_FILES = [
+    "municipio_logradouro_numero_localidade.parquet",
+    "municipio_logradouro_numero_cep_localidade.parquet",
+    "municipio.parquet",
+    "municipio_cep.parquet",
+    "municipio_cep_localidade.parquet",
+    "municipio_localidade.parquet",
+    "municipio_logradouro_cep_localidade.parquet",
+    "municipio_logradouro_localidade.parquet",
+]
+
+RESERVED_COLUMN_NAMES = [
+    "tempidgeocodebr", "lat", "lon", "precisao", "tipo_resultado",
+    "desvio_metros", "endereco_encontrado", "logradouro_encontrado",
+    "numero_encontrado", "cep_encontrado", "localidade_encontrada",
+    "municipio_encontrado", "estado_encontrado", "similaridade_logradouro",
+    "contagem_cnefe", "empate", "cod_setor"
+]
+

geocodebr/db.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+import duckdb
+
+
+def create_geocodebr_db(
+    db_path: str = "tempdir",
+    n_cores: int | None = None,
+    load_spatial: bool = False,
+) -> duckdb.DuckDBPyConnection:
+    if db_path == "tempdir":
+        handle = tempfile.NamedTemporaryFile(prefix="geocodebr", suffix=".duckdb", delete=True)
+        db_file = handle.name
+        handle.close()
+        Path(db_file).unlink(missing_ok=True)
+    elif db_path == "memory":
+        db_file = ":memory:"
+    else:
+        db_file = db_path
+
+    con = duckdb.connect(db_file)
+    if n_cores is not None:
+        con.execute(f"SET threads = {n_cores}")
+    con.execute("SET enable_progress_bar = false")
+
+    if load_spatial:
+        con.execute("INSTALL spatial")
+        con.execute("LOAD spatial")
+
+    return con
+
+
+def close_geocodebr_db(con: duckdb.DuckDBPyConnection) -> None:
+    """Fecha a conexão e apaga o arquivo do banco se for temporário do pacote.
+
+    Com ``db_path="tempdir"`` (o padrão), o DuckDB recria o arquivo no
+    ``connect`` mesmo após o ``unlink`` do placeholder do NamedTemporaryFile,
+    e o arquivo permanece no disco após ``con.close()`` — um `.duckdb` por
+    chamada se acumula no diretório temporário do sistema. Bancos em memória
+    não têm arquivo associado e caminhos customizados pelo usuário são
+    preservados.
+    """
+    paths = [
+        row[0]
+        for row in con.execute(
+            "SELECT path FROM duckdb_databases() WHERE path IS NOT NULL AND path != ''"
+        ).fetchall()
+    ]
+    con.close()
+    for path in paths:
+        _remove_temp_db_file(path)
+
+
+def _remove_temp_db_file(path: str) -> None:
+    arquivo = Path(path)
+    no_diretorio_temporario = _mesmo_diretorio(
+        arquivo.parent, Path(tempfile.gettempdir())
+    )
+    if not (
+        no_diretorio_temporario
+        and arquivo.name.startswith("geocodebr")
+        and arquivo.suffix == ".duckdb"
+    ):
+        return
+    try:
+        arquivo.unlink(missing_ok=True)
+        # WAL do DuckDB, caso tenha sobrado de um fechamento anormal
+        Path(str(arquivo) + ".wal").unlink(missing_ok=True)
+    except OSError:
+        # remocao cosmetica: nao deve interromper o fluxo do usuario
+        pass
+
+
+def _mesmo_diretorio(a: Path, b: Path) -> bool:
+    """Compara dois diretórios resolvendo symlinks e nomes curtos.
+
+    O DuckDB canonicaliza o caminho do banco no connect: no macOS resolve
+    o symlink /var -> /private/var e no Windows pode expandir nomes curtos
+    8.3 do TEMP, de modo que a comparação textual com tempfile.gettempdir()
+    falha mesmo tratando-se do mesmo diretório.
+    """
+    try:
+        return a.resolve() == b.resolve()
+    except OSError:
+        return a.absolute() == b.absolute()
+