csc-essentials 0.1.0.dev3__tar.gz → 0.2.3__tar.gz

{csc_essentials-0.1.0.dev3 → csc_essentials-0.2.3}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

csc_essentials-0.2.3/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: csc-essentials
+Version: 0.2.3
+Summary: Biblioteca de utilitários essenciais para projetos CSC
+Author-email: David Braga <david.braga@stone.com.br>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: slack-sdk>=3.0.0
+Requires-Dist: google-cloud-secret-manager>=2.0.0
+Requires-Dist: google-cloud-compute>=1.15.0
+Requires-Dist: google-cloud-storage>=2.10.0
+Requires-Dist: google-cloud-bigquery>=3.10.0
+Requires-Dist: google-cloud-logging>=3.5.0
+Requires-Dist: google-api-core>=2.11.0
+Requires-Dist: pytz>=2023.3
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: unidecode>=1.3.6
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: protobuf>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+
+# csc-essentials
+
+Pequeno utilitário para integração com Google Cloud (BigQuery, Secret Manager, Cloud Logging, Compute).
+
+## Instalação
+
+```bash
+pip install csc-essentials
+```
+
+## Quickstart (exemplo rápido)
+
+```python
+from google.cloud import bigquery
+from csc_essentials.logging import GeradorLog
+from csc_essentials.secrets import get_secrets
+from csc_essentials.database import inserir_banco_dados
+
+log = GeradorLog("exemplo")
+# Ler segredo do Secret Manager (ex.: token Slack)
+raw = get_secrets("projects/MEU_PROJ/secrets/SLACK_SECRET/versions/latest")
+
+# Preparar cliente BigQuery
+client = bigquery.Client()
+
+# Carregar arquivo NDJSON para uma tabela
+inserir_banco_dados(
+    arquivo_path="/tmp/dados.ndjson",
+    projeto="meu-projeto",
+    dataset="meu_dataset",
+    tabela="minha_tabela",
+    log=log,
+    client=client,
+    wait_job=True,
+)
+
+print("Upload iniciado")
+```
+
+## Documentação
+
+- Documentação por módulo em `docs/` (veja `docs/overview.md`).
+- Principais módulos: `logging`, `secrets`, `utils`, `database`.
+
+## Contribuindo
+
+- Abra uma issue descrevendo o problema ou feature.
+- Envie um Pull Request com testes e descrição clara das mudanças.
+- Formato de código: siga o estilo existing do projeto e execute os testes (`pytest`).
+
+## Licença
+
+Este repositório está licenciado conforme o arquivo `LICENSE` na raiz.
+
+## Notas rápidas
+
+- Verifique permissões GCP ao usar `bigquery.Client()` e `secretmanager.SecretManagerServiceClient`.
+- Em desenvolvimento local, você pode desativar o envio para Cloud Logging configurando `GCP_LOGGING_ATIVO=false`.

csc_essentials-0.2.3/README.md

@@ -0,0 +1,59 @@
+
+# csc-essentials
+
+Pequeno utilitário para integração com Google Cloud (BigQuery, Secret Manager, Cloud Logging, Compute).
+
+## Instalação
+
+```bash
+pip install csc-essentials
+```
+
+## Quickstart (exemplo rápido)
+
+```python
+from google.cloud import bigquery
+from csc_essentials.logging import GeradorLog
+from csc_essentials.secrets import get_secrets
+from csc_essentials.database import inserir_banco_dados
+
+log = GeradorLog("exemplo")
+# Ler segredo do Secret Manager (ex.: token Slack)
+raw = get_secrets("projects/MEU_PROJ/secrets/SLACK_SECRET/versions/latest")
+
+# Preparar cliente BigQuery
+client = bigquery.Client()
+
+# Carregar arquivo NDJSON para uma tabela
+inserir_banco_dados(
+    arquivo_path="/tmp/dados.ndjson",
+    projeto="meu-projeto",
+    dataset="meu_dataset",
+    tabela="minha_tabela",
+    log=log,
+    client=client,
+    wait_job=True,
+)
+
+print("Upload iniciado")
+```
+
+## Documentação
+
+- Documentação por módulo em `docs/` (veja `docs/overview.md`).
+- Principais módulos: `logging`, `secrets`, `utils`, `database`.
+
+## Contribuindo
+
+- Abra uma issue descrevendo o problema ou feature.
+- Envie um Pull Request com testes e descrição clara das mudanças.
+- Formato de código: siga o estilo existing do projeto e execute os testes (`pytest`).
+
+## Licença
+
+Este repositório está licenciado conforme o arquivo `LICENSE` na raiz.
+
+## Notas rápidas
+
+- Verifique permissões GCP ao usar `bigquery.Client()` e `secretmanager.SecretManagerServiceClient`.
+- Em desenvolvimento local, você pode desativar o envio para Cloud Logging configurando `GCP_LOGGING_ATIVO=false`.

{csc_essentials-0.1.0.dev3 → csc_essentials-0.2.3}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "csc-essentials"
-version = "0.1.0.dev3"
+version = "0.2.3"
 description = "Biblioteca de utilitários essenciais para projetos CSC"
 readme = "README.md"
-requires-python = ">=3.9" # Alterado para maior compatibilidade, ajuste se necessário
-authors = [ { name = "Seu Nome", email = "seuemail@exemplo.com" } ]
+requires-python = ">=3.9"
+authors = [ { name = "David Braga", email = "david.braga@stone.com.br" } ]
 license = { text = "MIT" }
 classifiers = [
     "Programming Language :: Python :: 3",
@@ -33,7 +33,7 @@ dependencies = [
     "unidecode>=1.3.6",
     "pandas>=2.0.0",
     "openpyxl>=3.1.0",
-    "setuptools>=61.0.0", # Removido o excesso da versão 80.x, a menos que precise de algo muito específico
+    "protobuf>=5.0.0",
 ]
 
 [project.optional-dependencies]
@@ -50,4 +50,16 @@ dev = [
 where = ["src"]
 
 [tool.setuptools.package-data]
-"*" = ["LICENSE", "README.md"]
+"*" = ["LICENSE", "README.md"]
+
+# Configuração para o UV encontrar dependências em ambos os repositórios
+[[tool.uv.index]]
+name = "test-pypi"
+url = "https://test.pypi.org/simple/"
+explicit = true
+
+[[tool.uv.index]]
+name = "pypi"
+url = "https://pypi.org/simple/"
+default = true
+

{csc_essentials-0.1.0.dev3 → csc_essentials-0.2.3}/setup.cfg

@@ -1,4 +1,4 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-
+[egg_info]
+tag_build = 
+tag_date = 0
+

csc_essentials-0.2.3/src/csc_essentials/__init__.py

@@ -0,0 +1,30 @@
+"""csc_essentials package exports.
+
+Este módulo agrega exports de utilitários presentes em `csc_essentials` para
+facilitar importações do pacote (ex.: `from csc_essentials import ajusta_nome_coluna`).
+"""
+
+from .utils import ajusta_nome_coluna, converter_valor
+from .database import (
+    inserir_banco_dados,
+    atualiza_tabela,
+    executar_com_fallback,
+    atualiza_tabelas_silvers,
+    obter_schema_map,
+)
+from .logging import GeradorLog, AlertaSlack
+from .core import parar_vm
+
+__all__ = [
+    "ajusta_nome_coluna",
+    "obter_schema_map",
+    "converter_valor",
+    "inserir_banco_dados",
+    "atualiza_tabela",
+    "executar_com_fallback",
+    "atualiza_tabelas_silvers",
+    "parar_vm",
+    "GeradorLog",
+    "AlertaSlack",
+]
+

csc_essentials-0.2.3/src/csc_essentials/core.py

@@ -0,0 +1,32 @@
+"""Operações relacionadas a armazenamento/infra (Compute).
+
+Este módulo contém helpers pequenos para operações em Google Compute.
+"""
+from google.cloud import compute_v1
+
+
+def parar_vm(instance_name, _project, _zona, gerador_log):
+    """Para uma instância do Compute Engine.
+
+    Args:
+        instance_name (str): nome da VM a ser parada.
+        _project (str): projeto GCP onde a VM está localizada.
+        _zona (str): zona da VM.
+        gerador_log (GeradorLog): instância de `GeradorLog` para registrar mensagens.
+
+    Observação: a função registra eventos no `gerador_log` e tenta parar a VM
+    usando o cliente `compute_v1.InstancesClient().stop`.
+    """
+    # Log local de início da operação
+    gerador_log.add(f"Parando {instance_name}...")
+    try:
+        # Chamada ao client do Compute para parar a instância
+        compute_v1.InstancesClient().stop(
+            project=_project,
+            zone=_zona,
+            instance=instance_name,
+        )
+        print("VM Parada.")
+    except Exception as e:
+        # Registra erro sem levantar, para não interromper fluxos que chamam esta util
+        gerador_log.add(f"Erro parar VM: {e}", severity="ERROR")

csc_essentials-0.2.3/src/csc_essentials/database.py

@@ -0,0 +1,222 @@
+"""Helpers para interação com BigQuery.
+
+Fornece funções para obter o schema de tabelas, carregar arquivos NDJSON
+e executar rotinas de atualização de tabelas (ex.: recriar a tabela a partir
+de uma view `_vw`).
+"""
+
+from .utils import executar_com_fallback, converter_valor
+import json
+from google.api_core import exceptions
+from google.cloud import bigquery
+
+
+def obter_schema_map(bq_client, projeto, dataset, tabela, gerador_log):
+    """
+    Busca o schema da tabela no BigQuery e retorna um dicionário {coluna: TIPO}.
+    Ex: {'data_emissao': 'DATE', 'valor': 'FLOAT', 'criado_em': 'DATETIME'}
+    Se a tabela não existir, retorna um dict vazio (fallback).
+    """
+    tabela_completa = f"{projeto}.{dataset}.{tabela}"
+    schema_map = {}
+
+    try:
+        table = bq_client.get_table(tabela_completa)
+        for field in table.schema:
+            schema_map[field.name] = field.field_type
+    except exceptions.NotFound:
+        gerador_log.add(
+            f"Tabela {tabela} ainda não existe no BQ. Conversão inteligente desativada para este fluxo.",
+            severity="WARNING",
+        )
+    except Exception as e:
+        gerador_log.add(f"Erro ao buscar schema de {tabela}: {e}", severity="ERROR")
+
+    return schema_map
+
+
+def inserir_banco_dados(dados=None, arquivo_path=None, projeto=None, dataset=None, tabela=None, tabela_silver="", gerador_log=None, client=None, wait_job=False):
+    """Inserção universal no BigQuery.
+
+    Pode receber `dados` (lista/NDJSON/JSON) ou um `arquivo_path` (NDJSON) para upload.
+    - `client` deve ser um `google.cloud.bigquery.Client`.
+    - Se `arquivo_path` for fornecido, usa `load_table_from_file`.
+    - Se `dados` for fornecido, normaliza e usa `insert_rows_json`.
+    Retorna True em sucesso.
+    """
+    endpoint_name = f"BigQuery-Insert ({tabela})"
+
+    # Preferência pelo arquivo: se arquivo_path é fornecido, faz upload em massa
+    if arquivo_path:
+        if client is None:
+            gerador_log.add("client do BigQuery não fornecido para upload de arquivo.", severity="ERROR")
+            raise ValueError("client obrigatório para upload de arquivo")
+
+        tabela_completa = f"{projeto}.{dataset}.{tabela}"
+        schema_destino = None
+        autodetect_config = True
+
+        try:
+            table_ref = client.get_table(tabela_completa)
+            schema_destino = table_ref.schema
+            autodetect_config = False
+        except exceptions.NotFound:
+            # Tabela ainda não existe; manter autodetect_config=True para o BigQuery
+            # inferir automaticamente o schema durante o carregamento.
+            pass
+
+        job_config = bigquery.LoadJobConfig(
+            source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
+            write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
+            ignore_unknown_values=True,
+            autodetect=autodetect_config,
+        )
+
+        with open(arquivo_path, "rb") as f:
+            job = client.load_table_from_file(f, f"{projeto}.{dataset}.{tabela}", job_config=job_config)
+
+        if wait_job:
+            job.result()
+            gerador_log.add(f"Upload finalizado para {tabela}", severity="DEBUG")
+
+        return True
+
+    # Caso contrário, usa `dados` em memória
+    if dados is None:
+        gerador_log.add("AVISO: Nenhum dado ou arquivo fornecido para inserção.", severity="WARNING")
+        return
+
+    # Normalize incoming `dados` into a list of dicts.
+    try:
+        if isinstance(dados, str):
+            raw = dados.strip()
+            if "\n" in raw:
+                lines = [ln for ln in raw.splitlines() if ln.strip()]
+                dados = [json.loads(ln) for ln in lines]
+            else:
+                parsed = json.loads(raw)
+                dados = parsed if isinstance(parsed, list) else [parsed]
+
+        elif isinstance(dados, (list, tuple)):
+            normalized = []
+            for idx, el in enumerate(dados):
+                if isinstance(el, str):
+                    try:
+                        normalized.append(json.loads(el))
+                    except Exception as e:
+                        gerador_log.add(f"Ignorando elemento {idx} que não é JSON válido: {e}", severity="WARNING")
+                elif isinstance(el, dict):
+                    normalized.append(el)
+                else:
+                    gerador_log.add(f"Ignorando elemento {idx} de tipo {type(el).__name__}", severity="WARNING")
+            dados = normalized
+        else:
+            gerador_log.add(f"Tipo de 'dados' inválido: {type(dados).__name__}", severity="ERROR")
+            raise TypeError("'dados' deve ser uma lista/tupla, dict ou string JSON/NDJSON")
+
+        if not dados:
+            gerador_log.add("AVISO: Após normalização, não há dados válidos para inserção.", severity="WARNING")
+            return
+    except Exception:
+        gerador_log.add("Erro ao parsear/normalizar 'dados' para inserção.", severity="ERROR")
+        raise
+
+    try:
+        if client is None:
+            raise ValueError("Para inserção via 'dados', é necessário fornecer um cliente BigQuery válido.")
+        tabela_completa = f"{projeto}.{dataset}.{tabela}"
+        table_ref = client.get_table(tabela_completa)
+        schema = table_ref.schema
+
+        tamanho_bloco = 1000
+        total_registros = len(dados)
+
+        gerador_log.add(f"Iniciando inserção de {total_registros} registros em blocos de {tamanho_bloco}...")
+
+        inserted = 0
+        for i in range(0, total_registros, tamanho_bloco):
+            bloco = dados[i:i+tamanho_bloco]
+            bloco_ajustado = []
+            for item_idx, item in enumerate(bloco):
+                if not isinstance(item, dict):
+                    gerador_log.add(f"Ignorando registro no bloco (indice {i + item_idx}) pois não é um dict.", severity="WARNING")
+                    continue
+
+                novo_item = {}
+                for campo in schema:
+                    nome_coluna = campo.name
+                    if nome_coluna in item:
+                        # `converter_valor` expects a mapping (row->tipo). Wrap the
+                        # single column value into a dict and pass a single-column
+                        # schema so converter_valor can safely iterate `.items()`.
+                        single_row = {nome_coluna: item.get(nome_coluna)}
+                        single_schema = {nome_coluna: campo.field_type}
+                        converted = converter_valor(single_row, single_schema, gerador_log)
+                        novo_item[nome_coluna] = converted.get(nome_coluna)
+                    else:
+                        novo_item[nome_coluna] = None
+                bloco_ajustado.append(novo_item)
+
+            if not bloco_ajustado:
+                continue
+
+            errors = client.insert_rows_json(table_ref, bloco_ajustado)
+            if errors:
+                error_details = f"A API do BigQuery retornou erros ao inserir dados: {errors}"
+                gerador_log.add(error_details, severity="ERROR")
+                raise Exception(error_details)
+
+            inserted += len(bloco_ajustado)
+
+        gerador_log.add(f"{inserted} registros inseridos com sucesso!")
+
+        if tabela_silver:
+            att = atualiza_tabela(client, projeto, dataset, tabela_silver, gerador_log)
+            gerador_log.add(f'Tabela silver: {att}')
+            return True
+
+        gerador_log.add('Sem Tabela Silver')
+        return True
+
+    except Exception as e:
+        gerador_log.add(f"Erro crítico ao tentar inserir dados no BigQuery: {e}", severity="CRITICAL")
+        raise
+    
+def atualiza_tabela(client, projeto, dataset, tabela, gerador_log):
+    """Recria a tabela destino a partir da view correspondente (`<tabela>_vw`).
+
+    Este helper executa um `CREATE OR REPLACE TABLE <tabela> AS SELECT * FROM <tabela>_vw`.
+    """
+    tabela_completa = f"{projeto}.{dataset}.{tabela}"
+    insert_sql = f"create or replace table `{tabela_completa}` as SELECT * FROM `{tabela_completa}_vw`;"
+    try:
+        client.query(insert_sql).result()
+        gerador_log.add(f"Tabela {tabela_completa} atualizada.")
+    except Exception as e:
+        # Log de erro e re-raise para que chamadores possam detectar falha
+        gerador_log.add(f"Erro query {tabela_completa}: {e}", severity="ERROR")
+        raise
+
+
+def atualiza_tabelas_silvers(client_t1, client_t2, project, dataset, tabelas_silvers, gerador_log, timeout_minutos=5):
+    """Atualiza múltiplas "silvers" com fallback entre dois clientes.
+
+    A ideia é tentar atualizar cada tabela usando `client_t1`. Se houver falha
+    no primeiro cliente (timeout/falha), ativa `secundario` e passa a usar
+    `client_t2` para as próximas tabelas.
+    """
+    gerador_log.add("Iniciando Silvers...")
+    timeout = timeout_minutos * 60
+    secundario = False
+    for tb in tabelas_silvers:
+        if not secundario:
+            # Tenta no client principal com timeout/fallback
+            res = executar_com_fallback(atualiza_tabela, client_t1, timeout, project, dataset, tb, gerador_log)
+            if res != "sucesso":
+                # Marca para usar o secundário a partir de agora
+                secundario = True
+                executar_com_fallback(atualiza_tabela, client_t2, timeout, project, dataset, tb, gerador_log)
+        else:
+            # Já está no secundário: executa diretamente
+            executar_com_fallback(atualiza_tabela, client_t2, timeout, project, dataset, tb, gerador_log)
+    gerador_log.add("Fim Silvers.")

csc_essentials-0.2.3/src/csc_essentials/logging.py

@@ -0,0 +1,159 @@
+import os
+import threading
+import json
+from datetime import datetime
+import pytz
+from google.cloud import logging as cloud_logging
+from google.cloud import secretmanager
+from slack_sdk import WebClient
+from slack_sdk.errors import SlackApiError
+from .secrets import get_secrets
+
+
+"""Integração de logging e alertas (Slack / Cloud Logging).
+
+Contém a classe `GeradorLog` usada para imprimir logs no console,
+enviar entradas estruturadas ao Cloud Logging e acumular erros para
+relatório no Slack via `AlertaSlack`.
+"""
+
+
+class GeradorLog:
+    """Gerador de logs usado por fluxos de dados.
+
+    - Imprime mensagens no console imediatamente.
+    - Se `GCP_LOGGING_ATIVO` estiver habilitado envia logs ao Cloud Logging.
+    - Erros podem ser acumulados e posteriormente enviados ao Slack.
+    """
+
+    def __init__(self, nome_do_log: str):
+        # Lock para operações thread-safe sobre a lista de erros acumulados
+        self.lock = threading.Lock()
+        self.gcp_logging_ativo = os.environ.get("GCP_LOGGING_ATIVO", "true").lower() == "true"
+        self.erros_acumulados = []
+
+        if self.gcp_logging_ativo:
+            try:
+                self.logging_client = cloud_logging.Client()
+                self.gcp_logger = self.logging_client.logger(nome_do_log)
+                print("INFO: Logging para o Google Cloud ATIVADO.")
+            except Exception as e:
+                print(f"CRÍTICO: Falha ao inicializar o cliente do Cloud Logging. Erro: {e}")
+                self.logging_client = None
+                self.gcp_logger = None
+        else:
+            self.logging_client = None
+            self.gcp_logger = None
+            print("INFO: Logging para o Google Cloud DESATIVADO localmente.")
+
+        # Inicializa o alerta Slack (usa SLACK_SECRET_PATH por padrão)
+        self.alertador = AlertaSlack(os.environ.get("SLACK_SECRET_PATH", ""), self)
+
+    def add(self, message, severity="INFO", notify_now=False, **extra_data):
+        """Adiciona uma entrada de log.
+
+        Args:
+            message (str): mensagem do log.
+            severity (str): nível (INFO, DEBUG, ERROR, etc.).
+            notify_now (bool): se True, em caso de ERROR dispara alerta imediato ao Slack.
+            **extra_data: dados extras enviados ao Cloud Logging e/ou usados no alerta.
+        """
+        with self.lock:
+            log_console_message = f"[{severity.upper()}] {message}"
+            if extra_data:
+                log_console_message += f" | Dados: {extra_data}"
+
+            # Impressão local (sempre)
+            print(log_console_message)
+
+            # Envia para Cloud Logging se configurado
+            if self.gcp_logger:
+                payload = {"message": message, **extra_data}
+                self.gcp_logger.log_struct(payload, severity=severity)
+
+            # Acumula ou envia alertas imediatos para severidades altas
+            if severity.upper() in ["ERROR", "CRITICAL", "ALERT"]:
+                timestamp = datetime.now(pytz.timezone("America/Sao_Paulo")).strftime("%H:%M:%S")
+                if notify_now:
+                    self.alertador.envia_alerta(
+                        consumo=extra_data.get("endpoint", "Processo Principal"),
+                        data_execucao=datetime.now(pytz.timezone("America/Sao_Paulo")).strftime("%d/%m/%Y %H:%M:%S"),
+                        exception_msg=message,
+                    )
+                else:
+                    erro_formatado = f"[{timestamp}] {extra_data.get('endpoint', '')}: {message}"
+                    self.erros_acumulados.append(erro_formatado)
+
+    def reportar_erros_acumulados(self):
+        """Envia relatório consolidado dos erros acumulados para o Slack."""
+        with self.lock:
+            if not self.erros_acumulados:
+                print("INFO: Nenhum erro acumulado para reportar.")
+                return
+
+            qtd_erros = len(self.erros_acumulados)
+            detalhes = "\n".join(self.erros_acumulados[:20])
+            if qtd_erros > 20:
+                detalhes += f"\n... e mais {qtd_erros - 20} erros."
+
+            msg_final = (
+                "Houve "
+                f"{qtd_erros} falhas de requisição/página durante a execução.\n\n{detalhes}"
+            )
+
+            print("INFO: Enviando relatório consolidado de erros para o Slack.")
+            self.alertador.envia_alerta(
+                consumo="Relatório de Erros em Lote",
+                data_execucao=datetime.now(pytz.timezone("America/Sao_Paulo")).strftime("%d/%m/%Y %H:%M:%S"),
+                exception_msg=msg_final,
+            )
+            # Limpa a lista após envio
+            self.erros_acumulados = []
+
+
+class AlertaSlack:
+    """Cliente simples para envio de alertas ao Slack usando token em Secret Manager.
+
+    A classe busca um segredo (JSON) que deve conter a chave `token` e opcionalmente
+    `users` com menções.
+    """
+
+    def __init__(self, secret_path, gerador_log):
+        self.gerador_log = gerador_log
+        self.secret_path = secret_path
+        self.slack_client = None
+        self.channel_id = "dados_csc_tecnico"
+        self.users_to_mention = ""
+        self.alertas_ativos = os.environ.get("ALERTAS_SLACK_ATIVOS", "true").lower() == "true"
+        if self.alertas_ativos:
+            self._inicializar_cliente()
+
+    def _inicializar_cliente(self):
+        """Inicializa o `WebClient` do Slack lendo o segredo do Secret Manager."""
+        try:
+            response = get_secrets(self.secret_path)
+            if not response:
+                print("CRÍTICO: Segredo do Slack não encontrado ou vazio.")
+                return
+            config = json.loads(response)
+            self.slack_client = WebClient(token=config.get("token"))
+            self.users_to_mention = config.get("users", "")
+            print("INFO: Cliente do Slack inicializado.")
+        except Exception as e:
+            print(f"CRÍTICO: Erro Slack: {e}")
+
+    def envia_alerta(self, consumo, data_execucao, exception_msg):
+        """Envia mensagem formatada para o canal do Slack configurado."""
+        if not self.alertas_ativos or not self.slack_client:
+            return
+        msg = (
+            "*:red_circle: Falha!*\n"
+            f"*Consumo:* `{consumo}`\n"
+            f"*Data:* `{data_execucao}`\n"
+            f"```{exception_msg}``` {self.users_to_mention}"
+        )
+        try:
+            self.slack_client.chat_postMessage(channel=self.channel_id, text=msg)
+        except SlackApiError:
+            # Falha no envio do Slack é silenciosa (não queremos quebrar o fluxo)
+            pass

csc_essentials-0.2.3/src/csc_essentials/secrets.py

@@ -0,0 +1,28 @@
+"""Helpers para acessar o Google Secret Manager.
+
+Fornece uma função utilitária simples para recuperar o payload de uma
+versão de segredo como string (geralmente JSON).
+"""
+
+from google.cloud import secretmanager
+
+
+
+def get_secrets(secret_name):
+    """Recupera o valor de um segredo do Secret Manager.
+
+    Args:
+        secret_name (str): recurso completo da versão do segredo
+            (ex.: "projects/<proj>/secrets/<name>/versions/latest").
+
+    Returns:
+        str | None: valor do segredo decodificado ou `None` em caso de falha.
+    """
+    try:
+        sm_client = secretmanager.SecretManagerServiceClient()
+        response = sm_client.access_secret_version(request={"name": secret_name})
+        secret_value = response.payload.data.decode("UTF-8")
+        return secret_value
+    except Exception:
+        # Em caso de erro retornamos None para que chamadores possam tratar
+        return None

csc_essentials-0.2.3/src/csc_essentials/utils.py

@@ -0,0 +1,164 @@
+"""Funções utilitárias: normalização, conversão e execução com timeout.
+
+Contém helpers usados em pipelines para preparar dados antes do envio
+ao BigQuery e para executar tarefas com timeout/fallback.
+"""
+
+import json
+from concurrent.futures import ThreadPoolExecutor, TimeoutError
+from unidecode import unidecode
+import re
+import math
+
+
+def ajusta_nome_coluna(nome_coluna):
+    """Normaliza um nome de coluna para formato compatível com BigQuery.
+
+    - converte para minúsculas
+    - substitui espaços por `_`
+    - remove acentos e caracteres especiais
+    - compacta múltiplos underscores
+    """
+    normalized = unidecode(nome_coluna.lower().replace(" ", "_"))
+    sem_caractere_especial = re.sub(r"[^a-zA-Z0-9_]", "", normalized)
+    return re.sub(r"_{2,}", "_", sem_caractere_especial)
+
+
+def converter_valor(row, schema_map, gerador_log):
+    """Converte e sanitiza os valores de uma linha segundo o `schema_map`.
+
+    - Recebe `row` (dict coluna->valor) e `schema_map` (coluna->TIPO BigQuery).
+    - Converte tipos básicos (STRING, INTEGER, FLOAT, BOOLEAN, DATE, DATETIME).
+    - Sanitiza NaN/Inf e formata datas no padrão aceito pelo BigQuery.
+    - Em falhas de conversão registra avisos e armazena `None` no campo.
+    """
+
+    if not schema_map:
+        return row
+
+    nova_linha = {}
+
+    regex_data_br = re.compile(r"^(\d{2})/(\d{2})/(\d{4})$")
+    regex_iso_tz = re.compile(
+        r"^(\d{4}-\d{2}-\d{2})[T ]" r"(\d{2}:\d{2}:\d{2}(?:\.\d+)?)" r"(?:Z|[+-]\d{2}:?\d{2})?$"
+    )
+
+    for col, val in row.items():
+        # Valores vazios viram NULL
+        if val is None or val == "":
+            nova_linha[col] = None
+            continue
+
+        # Serializa estruturas complexas para JSON
+        if isinstance(val, (dict, list)):
+            try:
+                nova_linha[col] = json.dumps(val, ensure_ascii=False)
+            except Exception:
+                nova_linha[col] = str(val)
+            continue
+
+        tipo_bq = schema_map.get(col, "STRING")
+
+        try:
+            if tipo_bq == "STRING":
+                val_str = str(val).replace("\n", " ").replace("\r", "").strip()
+                nova_linha[col] = val_str
+
+            elif tipo_bq in ("INTEGER", "INT64"):
+                # Garante conversão segura string -> float -> int (ex: "10.0" vira 10)
+                nova_linha[col] = int(float(str(val)))
+
+            elif tipo_bq in ("FLOAT", "FLOAT64", "NUMERIC"):
+                # Limpeza inicial de moeda e espaços
+                val_str = str(val).replace("R$", "").replace(" ", "").strip()
+
+                # Trata traço como zero (comum em planilhas)
+                if val_str in ("-", ""):
+                    nova_linha[col] = 0.0
+
+                else:
+                    # Converte formato brasileiro 1.000,00 -> 1000.00
+                    if "," in val_str:
+                        val_str = val_str.replace(".", "").replace(",", ".")
+
+                    try:
+                        valor_float = float(val_str)
+
+                        # Verifica NaN/Infinity
+                        if math.isnan(valor_float) or math.isinf(valor_float):
+                            nova_linha[col] = None
+                        else:
+                            nova_linha[col] = valor_float
+                    except ValueError:
+                        gerador_log.add(
+                            f"AVISO: Não foi possível converter '{val}' para FLOAT. Coluna: {col}. Enviando NULL.",
+                            severity="WARNING",
+                        )
+                        nova_linha[col] = None
+
+            elif tipo_bq in ("BOOLEAN", "BOOL"):
+                nova_linha[col] = str(val).lower() in ("true", "1", "t", "yes")
+
+            elif tipo_bq == "DATE":
+                val_str = str(val).strip()
+                match_br = regex_data_br.match(val_str)
+                if match_br:
+                    nova_linha[col] = f"{match_br.group(3)}-{match_br.group(2)}-{match_br.group(1)}"
+                else:
+                    nova_linha[col] = val_str[:10]
+
+            elif tipo_bq == "DATETIME":
+                val_str = str(val).strip()
+                match_iso = regex_iso_tz.match(val_str)
+                if match_iso:
+                    nova_linha[col] = f"{match_iso.group(1)} {match_iso.group(2)}"
+                else:
+                    # Limpeza robusta de timezone para evitar erro de formato
+                    limpo = val_str.replace("T", " ").replace("Z", "")
+                    # Remove offsets como -03:00 ou +00:00 manualmente se regex falhar
+                    if "+" in limpo:
+                        limpo = limpo.split("+")[0]
+                    if "-" in limpo and len(limpo.split("-")[-1]) == 5:  # tenta pegar offsets tipo -03:00
+                        limpo = limpo.rsplit("-", 1)[0]
+                    nova_linha[col] = limpo.strip()[:23]
+
+            else:
+                # Tipo não tratado: devolve o valor como veio
+                nova_linha[col] = val
+
+        except Exception:
+            # Se falhar a conversão, registra aviso e envia NULL para evitar erros BQ
+            gerador_log.add(
+                f"AVISO: Falha conversão coluna '{col}' valor '{val}'. Enviando NULL."
+            )
+            nova_linha[col] = None
+
+    return nova_linha
+
+
+def executar_com_fallback(func, bq_client, timeout, project, dataset, tabela, gerador_log):
+    """Executa `func` em um executor com timeout e captura falhas.
+
+    Retorna uma string entre: `"sucesso"`, `"timeout"`, `"falha"`.
+    """
+    executor = ThreadPoolExecutor(max_workers=1)
+    future = executor.submit(func, bq_client, project, dataset, tabela, gerador_log)
+    shutdown_done = False
+    try:
+        future.result(timeout=timeout)
+        gerador_log.add(f"✅ {func.__name__} concluída no projeto {bq_client.project}")
+        return "sucesso"
+    except TimeoutError:
+        # Cancela a execução e encerra o executor sem bloquear,
+        # garantindo que o timeout seja efetivo.
+        future.cancel()
+        executor.shutdown(wait=False, cancel_futures=True)
+        shutdown_done = True
+        return "timeout"
+    except Exception as e:
+        gerador_log.add(f"❌ Erro {func.__name__}: {e}")
+        return "falha"
+    finally:
+        if not shutdown_done:
+            # Encerra o executor normalmente nos demais cenários.
+            executor.shutdown(wait=True, cancel_futures=True)

csc_essentials-0.2.3/src/csc_essentials.egg-info/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: csc-essentials
+Version: 0.2.3
+Summary: Biblioteca de utilitários essenciais para projetos CSC
+Author-email: David Braga <david.braga@stone.com.br>
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: slack-sdk>=3.0.0
+Requires-Dist: google-cloud-secret-manager>=2.0.0
+Requires-Dist: google-cloud-compute>=1.15.0
+Requires-Dist: google-cloud-storage>=2.10.0
+Requires-Dist: google-cloud-bigquery>=3.10.0
+Requires-Dist: google-cloud-logging>=3.5.0
+Requires-Dist: google-api-core>=2.11.0
+Requires-Dist: pytz>=2023.3
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Dist: unidecode>=1.3.6
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: openpyxl>=3.1.0
+Requires-Dist: protobuf>=5.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
+Requires-Dist: flake8>=6.0.0; extra == "dev"
+Requires-Dist: isort>=5.0.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Dynamic: license-file
+
+
+# csc-essentials
+
+Pequeno utilitário para integração com Google Cloud (BigQuery, Secret Manager, Cloud Logging, Compute).
+
+## Instalação
+
+```bash
+pip install csc-essentials
+```
+
+## Quickstart (exemplo rápido)
+
+```python
+from google.cloud import bigquery
+from csc_essentials.logging import GeradorLog
+from csc_essentials.secrets import get_secrets
+from csc_essentials.database import inserir_banco_dados
+
+log = GeradorLog("exemplo")
+# Ler segredo do Secret Manager (ex.: token Slack)
+raw = get_secrets("projects/MEU_PROJ/secrets/SLACK_SECRET/versions/latest")
+
+# Preparar cliente BigQuery
+client = bigquery.Client()
+
+# Carregar arquivo NDJSON para uma tabela
+inserir_banco_dados(
+    arquivo_path="/tmp/dados.ndjson",
+    projeto="meu-projeto",
+    dataset="meu_dataset",
+    tabela="minha_tabela",
+    log=log,
+    client=client,
+    wait_job=True,
+)
+
+print("Upload iniciado")
+```
+
+## Documentação
+
+- Documentação por módulo em `docs/` (veja `docs/overview.md`).
+- Principais módulos: `logging`, `secrets`, `utils`, `database`.
+
+## Contribuindo
+
+- Abra uma issue descrevendo o problema ou feature.
+- Envie um Pull Request com testes e descrição clara das mudanças.
+- Formato de código: siga o estilo existing do projeto e execute os testes (`pytest`).
+
+## Licença
+
+Este repositório está licenciado conforme o arquivo `LICENSE` na raiz.
+
+## Notas rápidas
+
+- Verifique permissões GCP ao usar `bigquery.Client()` e `secretmanager.SecretManagerServiceClient`.
+- Em desenvolvimento local, você pode desativar o envio para Cloud Logging configurando `GCP_LOGGING_ATIVO=false`.

csc_essentials-0.2.3/src/csc_essentials.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/csc_essentials/__init__.py
+src/csc_essentials/core.py
+src/csc_essentials/database.py
+src/csc_essentials/logging.py
+src/csc_essentials/secrets.py
+src/csc_essentials/utils.py
+src/csc_essentials.egg-info/PKG-INFO
+src/csc_essentials.egg-info/SOURCES.txt
+src/csc_essentials.egg-info/dependency_links.txt
+src/csc_essentials.egg-info/requires.txt
+src/csc_essentials.egg-info/top_level.txt

{csc_essentials-0.1.0.dev3 → csc_essentials-0.2.3}/src/csc_essentials.egg-info/requires.txt

@@ -10,7 +10,7 @@ python-dateutil>=2.8.2
 unidecode>=1.3.6
 pandas>=2.0.0
 openpyxl>=3.1.0
-setuptools>=61.0.0
+protobuf>=5.0.0
 
 [dev]
 pytest>=7.0.0

csc_essentials-0.2.3/src/csc_essentials.egg-info/top_level.txt

@@ -0,0 +1 @@
+csc_essentials

csc_essentials-0.1.0.dev3/PKG-INFO

@@ -1,38 +0,0 @@
-Metadata-Version: 2.4
-Name: csc-essentials
-Version: 0.1.0.dev3
-Summary: Biblioteca de utilitários essenciais para projetos CSC
-Author-email: Seu Nome <seuemail@exemplo.com>
-License: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: slack-sdk>=3.0.0
-Requires-Dist: google-cloud-secret-manager>=2.0.0
-Requires-Dist: google-cloud-compute>=1.15.0
-Requires-Dist: google-cloud-storage>=2.10.0
-Requires-Dist: google-cloud-bigquery>=3.10.0
-Requires-Dist: google-cloud-logging>=3.5.0
-Requires-Dist: google-api-core>=2.11.0
-Requires-Dist: pytz>=2023.3
-Requires-Dist: python-dateutil>=2.8.2
-Requires-Dist: unidecode>=1.3.6
-Requires-Dist: pandas>=2.0.0
-Requires-Dist: openpyxl>=3.1.0
-Requires-Dist: setuptools>=61.0.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
-Requires-Dist: flake8>=6.0.0; extra == "dev"
-Requires-Dist: isort>=5.0.0; extra == "dev"
-Requires-Dist: black>=24.0.0; extra == "dev"
-Requires-Dist: pre-commit>=3.0.0; extra == "dev"
-Dynamic: license-file

csc_essentials-0.1.0.dev3/src/csc_essentials.egg-info/PKG-INFO

@@ -1,38 +0,0 @@
-Metadata-Version: 2.4
-Name: csc-essentials
-Version: 0.1.0.dev3
-Summary: Biblioteca de utilitários essenciais para projetos CSC
-Author-email: Seu Nome <seuemail@exemplo.com>
-License: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: slack-sdk>=3.0.0
-Requires-Dist: google-cloud-secret-manager>=2.0.0
-Requires-Dist: google-cloud-compute>=1.15.0
-Requires-Dist: google-cloud-storage>=2.10.0
-Requires-Dist: google-cloud-bigquery>=3.10.0
-Requires-Dist: google-cloud-logging>=3.5.0
-Requires-Dist: google-api-core>=2.11.0
-Requires-Dist: pytz>=2023.3
-Requires-Dist: python-dateutil>=2.8.2
-Requires-Dist: unidecode>=1.3.6
-Requires-Dist: pandas>=2.0.0
-Requires-Dist: openpyxl>=3.1.0
-Requires-Dist: setuptools>=61.0.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
-Requires-Dist: flake8>=6.0.0; extra == "dev"
-Requires-Dist: isort>=5.0.0; extra == "dev"
-Requires-Dist: black>=24.0.0; extra == "dev"
-Requires-Dist: pre-commit>=3.0.0; extra == "dev"
-Dynamic: license-file

csc_essentials-0.1.0.dev3/src/csc_essentials.egg-info/SOURCES.txt

@@ -1,8 +0,0 @@
-LICENSE
-README.md
-pyproject.toml
-src/csc_essentials.egg-info/PKG-INFO
-src/csc_essentials.egg-info/SOURCES.txt
-src/csc_essentials.egg-info/dependency_links.txt
-src/csc_essentials.egg-info/requires.txt
-src/csc_essentials.egg-info/top_level.txt

csc_essentials-0.1.0.dev3/src/csc_essentials.egg-info/top_level.txt

@@ -1 +0,0 @@
-