Carregar configurações externas com precedência explícita

from pathlib import Path
import tomllib

CHAVES_CONFIG = {"limite", "detalhado", "arquivo_dados"}


class EstruturaConfigInvalida(ValueError):
    pass


def carregar_toml(config_file: Path) -> dict[str, object]:
    with config_file.open("rb") as arquivo:
        dados = tomllib.load(arquivo)

    aplicacao = dados.get("aplicacao")
    if aplicacao is None:
        return {}

    if not isinstance(aplicacao, dict):
        raise EstruturaConfigInvalida(
            "A seção 'aplicacao' deve ser uma tabela TOML."
        )

    desconhecidas = set(aplicacao) - CHAVES_CONFIG
    if desconhecidas:
        raise EstruturaConfigInvalida(
            "A seção 'aplicacao' contém chaves não reconhecidas."
        )

    return dict(aplicacao)

import os
from collections.abc import Mapping
from pathlib import Path


def converter_booleano(texto: str) -> bool:
    normalizado = texto.strip().lower()
    if normalizado == "true":
        return True
    if normalizado == "false":
        return False
    raise ValueError("APP_DETALHADO deve ser true ou false")


def normalizar_ambiente(
    ambiente: Mapping[str, str],
    *,
    diretorio_trabalho: Path,
) -> dict[str, object]:
    contribuicao: dict[str, object] = {}

    if "APP_LIMITE" in ambiente:
        contribuicao["limite"] = int(ambiente["APP_LIMITE"])

    if "APP_DETALHADO" in ambiente:
        contribuicao["detalhado"] = converter_booleano(
            ambiente["APP_DETALHADO"]
        )

    if "APP_ARQUIVO_DADOS" in ambiente:
        texto_caminho = ambiente["APP_ARQUIVO_DADOS"].strip()
        if not texto_caminho:
            raise ValueError("APP_ARQUIVO_DADOS não pode ser vazio")

        caminho = Path(texto_caminho)
        contribuicao["arquivo_dados"] = (
            caminho if caminho.is_absolute() else diretorio_trabalho / caminho
        )

    return contribuicao


# Na execução normal:
config_do_ambiente = normalizar_ambiente(
    os.environ,
    diretorio_trabalho=Path.cwd(),
)

import argparse


def criar_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser()

    parser.add_argument(
        "--limite",
        type=int,
        default=argparse.SUPPRESS,
    )
    parser.add_argument(
        "--detalhado",
        action="store_true",
        default=argparse.SUPPRESS,
    )
    parser.add_argument(
        "--sem-detalhes",
        dest="detalhado",
        action="store_false",
        default=argparse.SUPPRESS,
    )
    parser.add_argument("--arquivo-dados", default=argparse.SUPPRESS)

    # Seleciona o arquivo; não é entregue à configuração da aplicação.
    parser.add_argument("--config")
    return parser


parser = criar_parser()
vazio = parser.parse_args([])
explicito = parser.parse_args(["--limite", "0", "--sem-detalhes"])

print(vars(vazio))       # {}
print(vars(explicito))   # {'limite': 0, 'detalhado': False}

CHAVES_CONFIG = {"limite", "detalhado", "arquivo_dados"}


def contribuicao_cli(args: argparse.Namespace) -> dict[str, object]:
    valores = vars(args)
    return {
        chave: valores[chave]
        for chave in CHAVES_CONFIG
        if chave in valores
    }

args = criar_parser().parse_args(
    ["--config", "minha-config.toml", "--limite", "0", "--sem-detalhes"]
)

print(args.config)              # minha-config.toml
print(contribuicao_cli(args))   # {'limite': 0, 'detalhado': False}

from pathlib import Path
from typing import Any

PADROES: dict[str, Any] = {
    "limite": 100,
    "detalhado": True,
    "arquivo_dados": Path("dados.csv"),
}


def combinar(
    arquivo: dict[str, Any],
    ambiente: dict[str, Any],
    cli: dict[str, Any],
) -> dict[str, Any]:
    """Sobrepõe contribuições já normalizadas, sem alterar PADROES."""
    configuracao = PADROES.copy()
    configuracao.update(arquivo)
    configuracao.update(ambiente)
    configuracao.update(cli)
    return configuracao

arquivo = {"limite": 20, "detalhado": False}
ambiente = {"limite": 0}
cli = {"arquivo_dados": Path("entrada.csv")}

resultado = combinar(arquivo, ambiente, cli)
# {"limite": 0, "detalhado": False,
#  "arquivo_dados": Path("entrada.csv")}

def ler_limite_toml(valor: object) -> int:
    # bool é subclasse de int; por isso type(...) é int, não isinstance.
    if type(valor) is not int:
        raise ValueError("configuração: limite do TOML deve ser inteiro")
    return valor

ler_limite_toml(25)      # 25
# ler_limite_toml(True)  # ValueError

from dataclasses import dataclass
from pathlib import Path
from typing import Any, Mapping


class ErroConfiguracao(ValueError):
    """Indica uma configuração ausente, malformada ou inválida."""


@dataclass(frozen=True)
class Config:
    limite: int
    detalhado: bool
    arquivo_dados: Path


def validar_config(valores: Mapping[str, Any]) -> Config:
    obrigatorias = {"limite", "detalhado", "arquivo_dados"}
    ausentes = obrigatorias - valores.keys()
    if ausentes:
        chave = sorted(ausentes)[0]
        raise ErroConfiguracao(
            f"configuração inválida: chave '{chave}' está ausente"
        )

    limite = valores["limite"]
    detalhado = valores["detalhado"]
    arquivo_dados = valores["arquivo_dados"]

    # bool é subclasse de int; por isso, teste-o explicitamente.
    if isinstance(limite, bool) or not isinstance(limite, int):
        raise ErroConfiguracao(
            "configuração inválida: chave 'limite' deve ser inteira"
        )
    if not isinstance(detalhado, bool):
        raise ErroConfiguracao(
            "configuração inválida: chave 'detalhado' deve ser booleana"
        )
    if not isinstance(arquivo_dados, Path):
        raise ErroConfiguracao(
            "configuração inválida: chave 'arquivo_dados' deve ser um caminho"
        )
    if limite < 0:
        raise ErroConfiguracao(
            "configuração inválida: chave 'limite' deve ser maior ou igual a zero"
        )

    return Config(
        limite=limite,
        detalhado=detalhado,
        arquivo_dados=arquivo_dados,
    )

from __future__ import annotations

import argparse
import os
import tomllib
from dataclasses import dataclass
from pathlib import Path
from typing import Callable, Mapping


class ConfigError(Exception):
    """Falha segura ao carregar ou validar a configuração."""


@dataclass(frozen=True)
class Config:
    limite: int
    detalhado: bool
    arquivo_dados: Path


PADROES = {
    "limite": 10,
    "detalhado": False,
    "arquivo_dados": Path("dados.json"),
}
CHAVES = set(PADROES)


def caminho(valor: str | Path, base: Path) -> Path:
    if str(valor).strip() == "":
        raise ConfigError("arquivo_dados: caminho vazio")
    resultado = Path(valor)
    return resultado if resultado.is_absolute() else base / resultado


def normalizar_bruto(dados: Mapping[str, object], base: Path) -> dict[str, object]:
    desconhecidas = set(dados) - CHAVES
    if desconhecidas:
        raise ConfigError("estrutura: chave não reconhecida")

    resultado: dict[str, object] = {}
    if "limite" in dados:
        valor = dados["limite"]
        if type(valor) is not int:  # bool não é um limite aceito
            raise ConfigError("limite: inteiro esperado")
        resultado["limite"] = valor
    if "detalhado" in dados:
        valor = dados["detalhado"]
        if type(valor) is not bool:
            raise ConfigError("detalhado: booleano esperado")
        resultado["detalhado"] = valor
    if "arquivo_dados" in dados:
        valor = dados["arquivo_dados"]
        if not isinstance(valor, (str, Path)):
            raise ConfigError("arquivo_dados: caminho esperado")
        resultado["arquivo_dados"] = caminho(valor, base)
    return resultado


def carregar_toml(config: Path | None, cwd: Path) -> dict[str, object]:
    caminho_config = config if config is not None else cwd / "config.toml"
    if not caminho_config.exists():
        if config is None:
            return {}
        raise ConfigError("arquivo de configuração solicitado não foi encontrado")

    try:
        with caminho_config.open("rb") as arquivo:
            documento = tomllib.load(arquivo)
    except tomllib.TOMLDecodeError as erro:
        raise ConfigError("arquivo TOML: sintaxe inválida") from erro
    except OSError as erro:
        raise ConfigError("arquivo TOML: não foi possível ler") from erro

    tabela = documento.get("aplicacao", {})
    if not isinstance(tabela, dict):
        raise ConfigError("arquivo TOML: [aplicacao] deve ser uma tabela")
    return normalizar_bruto(tabela, caminho_config.parent)


def booleano(texto: str, chave: str) -> bool:
    normalizado = texto.strip().lower()
    if normalizado == "true":
        return True
    if normalizado == "false":
        return False
    raise ConfigError(f"{chave}: use true ou false")


def carregar_ambiente(ambiente: Mapping[str, str], cwd: Path) -> dict[str, object]:
    resultado: dict[str, object] = {}
    if "APP_LIMITE" in ambiente:
        try:
            resultado["limite"] = int(ambiente["APP_LIMITE"])
        except ValueError as erro:
            raise ConfigError("APP_LIMITE: inteiro esperado") from erro
    if "APP_DETALHADO" in ambiente:
        resultado["detalhado"] = booleano(ambiente["APP_DETALHADO"], "APP_DETALHADO")
    if "APP_ARQUIVO_DADOS" in ambiente:
        resultado["arquivo_dados"] = caminho(ambiente["APP_ARQUIVO_DADOS"], cwd)
    return resultado


def parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser()
    p.add_argument("--config", type=Path, default=argparse.SUPPRESS)
    p.add_argument("--limite", type=int, default=argparse.SUPPRESS)
    p.add_argument("--arquivo-dados", dest="arquivo_dados", default=argparse.SUPPRESS)
    grupo = p.add_mutually_exclusive_group()
    grupo.add_argument("--detalhado", action="store_true", default=argparse.SUPPRESS)
    grupo.add_argument("--sem-detalhes", dest="detalhado", action="store_false", default=argparse.SUPPRESS)
    return p


def resolver(argv: list[str], ambiente: Mapping[str, str] | None = None, cwd: Path | None = None) -> Config:
    diretorio = (cwd or Path.cwd()).resolve()
    argumentos = vars(parser().parse_args(argv))
    selecionado = argumentos.pop("config", None)
    arquivo = caminho(selecionado, diretorio) if selecionado is not None else None

    cli = normalizar_bruto(argumentos, diretorio)
    ambiente_normalizado = carregar_ambiente(os.environ if ambiente is None else ambiente, diretorio)
    toml = carregar_toml(arquivo, diretorio)

    combinada = dict(PADROES)
    combinada.update(toml)
    combinada.update(ambiente_normalizado)
    combinada.update(cli)

    if combinada["limite"] < 0:
        raise ConfigError("limite: deve ser maior ou igual a zero")
    return Config(**combinada)


def iniciar(argv: list[str], criar_componentes: Callable[[Config], object]) -> object:
    """A composição só ocorre depois de resolver e validar a configuração."""
    return criar_componentes(resolver(argv))

[aplicacao]
limite = 25
detalhado = true
arquivo_dados = "armazenamento/registros.json"

from pathlib import Path

import pytest

from config import ConfigError, iniciar, resolver


def escrever_toml(pasta: Path, texto: str) -> Path:
    arquivo = pasta / "config.toml"
    arquivo.write_text(texto, encoding="utf-8")
    return arquivo


def test_usa_padroes_quando_config_convencional_nao_existe(tmp_path: Path) -> None:
    config = resolver([], {}, tmp_path)
    assert config.limite == 10
    assert config.detalhado is False
    assert config.arquivo_dados == tmp_path / "dados.json"


def test_cli_vence_arquivo_ambiente_e_padroes(tmp_path: Path) -> None:
    arquivo = escrever_toml(
        tmp_path,
        '[aplicacao]\nlimite = 20\ndetalhado = true\narquivo_dados = "toml.json"\n',
    )
    config = resolver(
        ["--config", str(arquivo), "--limite", "0", "--sem-detalhes", "--arquivo-dados", "cli.json"],
        {"APP_LIMITE": "30", "APP_DETALHADO": "true", "APP_ARQUIVO_DADOS": "ambiente.json"},
        tmp_path,
    )
    assert (config.limite, config.detalhado) == (0, False)
    assert config.arquivo_dados == tmp_path / "cli.json"


def test_caminho_do_toml_e_relativo_ao_proprio_arquivo(tmp_path: Path) -> None:
    pasta_config = tmp_path / "configs"
    pasta_config.mkdir()
    arquivo = escrever_toml(pasta_config, '[aplicacao]\narquivo_dados = "dados/base.json"\n')
    config = resolver(["--config", str(arquivo)], {}, tmp_path)
    assert config.arquivo_dados == pasta_config / "dados/base.json"


def test_arquivo_convencional_ausente_e_aceito_mas_solicitado_nao(tmp_path: Path) -> None:
    assert resolver([], {}, tmp_path).limite == 10
    with pytest.raises(ConfigError, match="solicitado"):
        resolver(["--config", "nao-existe.toml"], {}, tmp_path)


def test_erro_de_representacao_falha_mesmo_com_cli_superior(tmp_path: Path) -> None:
    with pytest.raises(ConfigError, match="APP_LIMITE"):
        resolver(["--limite", "3"], {"APP_LIMITE": "muitos"}, tmp_path)


def test_restricao_semantica_incide_sobre_o_valor_vencedor(tmp_path: Path) -> None:
    with pytest.raises(ConfigError, match="maior ou igual"):
        resolver(["--limite", "-1"], {}, tmp_path)
    assert resolver(["--limite", "2"], {"APP_LIMITE": "-1"}, tmp_path).limite == 2


def test_falha_impede_a_composicao(tmp_path: Path) -> None:
    chamadas: list[object] = []

    def sentinela(config: object) -> object:
        chamadas.append(config)
        return object()

    with pytest.raises(ConfigError):
        iniciar(["--limite", "-1"], sentinela)
    assert chamadas == []