csc-cia-stne 0.0.34__py3-none-any.whl → 0.0.36__py3-none-any.whl

csc_cia_stne/__init__.py

@@ -33,6 +33,10 @@ load_dotenv(_caminho_env)
 logger = None  # Inicializa como None
 
 def _running_in_container():
+    """
+    Verifica se o código está sendo executado dentro de um container.
+    Retorna True se estiver sendo executado dentro de um container e False caso contrário.
+    """
 
     if os.environ.get("KUBERNETES_SERVICE_HOST") or os.path.exists("/.dockerenv"):
         
@@ -55,6 +59,18 @@ def _running_in_container():
     return False
     
 def logger():
+    """
+    Retorna um objeto logger com base no ambiente de execução.
+    Se a variável de ambiente 'ambiente_de_execucao' estiver definida e for igual a "karavela",
+    retorna um logger formatado em JSON usando a função get_logger_json().
+    Caso contrário, se estiver executando em um container, retorna um logger formatado em JSON
+    usando a função get_logger_json().
+    Caso contrário, retorna um logger formatado em texto usando a função get_logger_rich().
+    Exemplo de uso:
+    logger_obj = logger()
+    logger_obj.info("Mensagem de informação")
+    logger_obj.error("Mensagem de erro")
+    """
     
     if os.getenv('ambiente_de_execucao') is not None and os.getenv('ambiente_de_execucao') == "karavela":
         

csc_cia_stne/bc_correios.py

@@ -60,6 +60,19 @@ class AnexoDict(BaseModel):
 class BC_Correios:
     
     def __init__(self, wsdl_url:str, usuario:str, senha:str, correios_por_pasta_pasta_unidade_nome:str='40797', correios_por_pasta_pasta_unidade_ativa:bool=True, correios_por_pasta_pasta_unidade_tipo:str='InstituicaoFinanceira', correios_por_pasta_pasta_tipo:str='CaixaEntrada',correios_por_pasta_apenas_mensagens:bool=True, correios_por_pasta_pesquisar_em_todas_as_pastas:bool=True):
+        """
+        Inicializa a classe BC_Correios.
+        Parâmetros:
+        - wsdl_url (str): URL do WSDL do serviço dos Correios.
+        - usuario (str): Nome de usuário para autenticação no serviço dos Correios.
+        - senha (str): Senha para autenticação no serviço dos Correios.
+        - correios_por_pasta_pasta_unidade_nome (str, opcional): Nome da unidade da pasta dos Correios. Valor padrão é '40797'.
+        - correios_por_pasta_pasta_unidade_ativa (bool, opcional): Indica se a unidade da pasta dos Correios está ativa. Valor padrão é True.
+        - correios_por_pasta_pasta_unidade_tipo (str, opcional): Tipo da unidade da pasta dos Correios. Valor padrão é 'InstituicaoFinanceira'.
+        - correios_por_pasta_pasta_tipo (str, opcional): Tipo da pasta dos Correios. Valor padrão é 'CaixaEntrada'.
+        - correios_por_pasta_apenas_mensagens (bool, opcional): Indica se deve retornar apenas mensagens da pasta dos Correios. Valor padrão é True.
+        - correios_por_pasta_pesquisar_em_todas_as_pastas (bool, opcional): Indica se deve pesquisar em todas as pastas dos Correios. Valor padrão é True.
+        """
 
         try:
 

csc_cia_stne/bc_sta.py

@@ -7,11 +7,31 @@ from typing import Literal, Dict, Union, Optional
 
 # Validações dos inputs
 class InitParamsValidator(BaseModel):
+    """
+    Classe responsável por validar os parâmetros de inicialização.
+    Atributos:
+        usuario (str): O nome de usuário.
+        senha (str): A senha do usuário.
+        ambiente (Literal["prd", "hml"]): O ambiente, que pode ser "prd" (produção) ou "hml" (homologação).
+    Métodos:
+        check_non_empty_string(value, info): Método de validação para garantir que cada parâmetro é uma string não vazia.
+    """
+        
     usuario: str
     senha: str
     ambiente: Literal["prd", "hml"]  # Aceita apenas "prd" ou "sdx"
 
     # Validação para garantir que cada parâmetro é uma string não vazia
+    """
+    Método de validação para garantir que cada parâmetro é uma string não vazia.
+    Parâmetros:
+        value (Any): O valor do parâmetro a ser validado.
+        info (FieldInfo): As informações do campo a ser validado.
+    Retorna:
+        value (Any): O valor do parâmetro validado.
+    Lança:
+        ValueError: Se o valor do parâmetro não for uma string não vazia.
+    """
     @field_validator('usuario', 'senha')
     def check_non_empty_string(cls, value, info):
         if not isinstance(value, str) or not value.strip():
@@ -21,6 +41,23 @@ class InitParamsValidator(BaseModel):
         return value
 
 class EnviarArquivoValidator(BaseModel):
+    """
+    Classe responsável por validar os parâmetros de envio de arquivo.
+    Args:
+        tipo_arquivo (str): O código do tipo de envio a ser utilizado para o STA.
+            Verificar códigos disponíveis na documentação STA.
+        file_content (bytes): O conteúdo do arquivo a ser enviado, em formato de bytes.
+        nome_arquivo (str): O nome do arquivo a ser enviado.
+            Deve ser uma string não vazia e terminar com uma extensão de arquivo comum.
+        observacao (str): A observação relacionada ao envio do arquivo.
+            Deve ser uma string não vazia.
+        destinatarios (Optional[Union[Dict[str, str], str]], optional): Os destinatários do arquivo.
+            Pode ser um dicionário ou uma string XML. Defaults to None.
+    Raises:
+        ValueError: Se algum dos parâmetros não atender às condições de validação.
+    Returns:
+        O valor de cada parâmetro, se a validação for bem-sucedida.
+    """
     tipo_arquivo:str
     file_content:bytes
     nome_arquivo:str
@@ -85,6 +122,19 @@ class EnviarArquivoValidator(BaseModel):
 class BC_STA:
     
     def __init__(self, usuario:str, senha:str, ambiente:str):
+        """
+        Inicializa uma instância da classe BC_STA.
+        Parâmetros:
+        - usuario (str): O nome de usuário para autenticação.
+        - senha (str): A senha para autenticação.
+        - ambiente (str): O ambiente de execução ('prd' para produção ou qualquer outro valor para ambiente de teste).
+        Raises:
+        - ValueError: Se houver erro na validação dos dados de input da inicialização da instância 'BC_STA'.
+        Exemplo de uso:
+        ```
+        bc_sta = BC_STA(usuario='meu_usuario', senha='minha_senha', ambiente='prd')
+        ```
+        """
 
         try:
             
@@ -115,6 +165,18 @@ class BC_STA:
             self.error = e
     
     def verifica_conexao(self):
+        """
+        Verifica a conexão com o servidor STA do Banco Central do Brasil.
+        Returns:
+            bool: True se a conexão for bem-sucedida, False caso contrário.
+        Raises:
+            Exception: Se ocorrer algum erro durante a verificação da conexão.
+        Example:
+            # Criando uma instância da classe
+            bc_sta = BCSTA()
+            # Verificando a conexão
+            conexao = bc_sta.verifica_conexao()
+        """
         try:
 
             response = requests.get("https://sta.bcb.gov.br/staws/arquivos?tipoConsulta=AVANC&nivelDetalhe=RES", auth=self.auth)
@@ -134,7 +196,34 @@ class BC_STA:
             raise e
 
     def enviar_arquivo(self, tipo_arquivo:str, file_content:bytes, nome_arquivo:str, observacao:str, destinatarios:dict=None):
-
+        """
+        Envia um arquivo para um determinado destino.
+            tipo_arquivo (str): O tipo de arquivo a ser enviado.
+            nome_arquivo (str): O nome do arquivo.
+            observacao (str): Uma observação opcional.
+            destinatarios (dict, optional): Um dicionário contendo informações sobre os destinatários do arquivo. 
+                O dicionário deve ter a seguinte estrutura:
+                {
+                    'unidade': 'nome_da_unidade',
+                    'dependencia': 'nome_da_dependencia',  # opcional
+                    'operador': 'nome_do_operador'  # opcional
+                O campo 'dependencia' e 'operador' são opcionais.
+                - 'enviado': Um valor booleano indicando se o arquivo foi enviado com sucesso.
+                - 'protocolo': O protocolo gerado, caso o arquivo tenha sido enviado com sucesso.
+                - 'link': O link do arquivo, caso tenha sido enviado com sucesso.
+                - 'erro': Uma mensagem de erro, caso ocorra algum problema no envio do arquivo.
+            ValueError: Se ocorrer um erro na validação dos dados de entrada.
+            Exception: Se ocorrer um erro durante o envio do arquivo.
+            # Exemplo de chamada da função
+            tipo_arquivo = 'documento'
+            nome_arquivo = 'arquivo.txt'
+            observacao = 'Este é um arquivo de teste'
+            destinatarios = {
+                'unidade': 'unidade_destino',
+                'dependencia': 'dependencia_destino',
+                'operador': 'operador_destino'
+            resposta = enviar_arquivo(tipo_arquivo, file_content, nome_arquivo, observacao, destinatarios)
+        """
         try:
             
             EnviarArquivoValidator(tipo_arquivo=tipo_arquivo, file_content=file_content, nome_arquivo=nome_arquivo, observacao=observacao, destinatarios=destinatarios)
@@ -144,6 +233,17 @@ class BC_STA:
             raise ValueError("Erro na validação dos dados de input do método 'enviar_arquivo':", e.errors())
 
         def generate_sha256_hash(file_content):
+            """
+            Gera o hash SHA-256 do conteúdo de um arquivo.
+            Args:
+                file_content (bytes): O conteúdo do arquivo como uma sequência de bytes.
+            Returns:
+                str: O hash SHA-256 do conteúdo do arquivo.
+            Example:
+                file_content = b'Lorem ipsum dolor sit amet'
+                hash_value = generate_sha256_hash(file_content)
+                print(hash_value)
+            """
             
             # Gera o hash SHA-256 do arquivo
             sha256_hash = hashlib.sha256()
@@ -151,6 +251,23 @@ class BC_STA:
             return sha256_hash.hexdigest()
 
         def process_response(xml_content):
+            """
+            Processa o conteúdo XML de resposta e retorna um dicionário com as informações relevantes.
+            Args:
+                xml_content (str): O conteúdo XML de resposta.
+            Returns:
+                dict: Um dicionário contendo as seguintes chaves:
+                    - 'enviado': Um valor booleano indicando se o XML foi enviado com sucesso.
+                    - 'protocolo': O protocolo extraído do XML, caso tenha sido enviado com sucesso.
+                    - 'link': O link extraído do XML, caso tenha sido enviado com sucesso.
+                    - 'erro': Uma mensagem de erro, caso ocorra algum problema no processamento do XML.
+            Raises:
+                None
+            Exemplo de uso:
+                xml = "<root>...</root>"
+                resposta = process_response(xml)
+                print(resposta)
+            """
 
             try:
 

csc_cia_stne/email.py

@@ -6,9 +6,27 @@ from email import encoders
 from pydantic import BaseModel, ValidationError, field_validator
 
 class InitParamsValidator(BaseModel):
+    """
+    Classe para validar os parâmetros de inicialização.
+    Atributos:
+    - email_sender (str): O endereço de e-mail do remetente.
+    - email_password (str): A senha do e-mail.
+    Métodos:
+    - check_str_input(value, info): Valida se o valor é uma string não vazia.
+    """
     email_sender: str
     email_password: str
 
+    """
+    Valida se o valor é uma string não vazia.
+    Parâmetros:
+    - value: O valor a ser validado.
+    - info: Informações sobre o campo.
+    Retorna:
+    - value: O valor validado.
+    Lança:
+    - ValueError: Se o valor não for uma string ou estiver vazio.
+    """
     @field_validator('email_sender','email_password')
     def check_str_input(cls, value, info):
         if not isinstance(value, str) or not value.strip():
@@ -16,6 +34,17 @@ class InitParamsValidator(BaseModel):
         return value
     
 class SendEmailParamsValidator(BaseModel):
+    """
+    Classe para validar os parâmetros de envio de e-mail.
+    Atributos:
+    - to (list): Lista de destinatários do e-mail.
+    - message (str): Mensagem do e-mail.
+    - title (str): Título do e-mail.
+    - reply_to (str): Endereço de e-mail para resposta.
+    - attachments (list, opcional): Lista de anexos do e-mail.
+    - cc (list, opcional): Lista de destinatários em cópia do e-mail.
+    - cco (list, opcional): Lista de destinatários em cópia oculta do e-mail.
+    """
 
     to: list
     message: str
@@ -25,12 +54,32 @@ class SendEmailParamsValidator(BaseModel):
     cc: list = []
     cco: list = []
 
+    """
+    Valida se o valor é uma string não vazia.
+    Parâmetros:
+    - value (str): Valor a ser validado.
+    - info (FieldInfo): Informações sobre o campo.
+    Retorna:
+    - str: O valor validado.
+    Lança:
+    - ValueError: Se o valor não for uma string ou estiver vazio.
+    """
     @field_validator('message','title','reply_to')
     def check_str_input(cls, value, info):
         if not isinstance(value, str) or not value.strip():
             raise ValueError(f"O campo '{info.field_name}' deve ser strings e não {type(value)}")
         return value
     
+    """
+    Valida se o valor é uma lista.
+    Parâmetros:
+    - value (list): Valor a ser validado.
+    - info (FieldInfo): Informações sobre o campo.
+    Retorna:
+    - list: O valor validado.
+    Lança:
+    - ValueError: Se o valor não for uma lista.
+    """
     @field_validator('to','attachments','cc','cco')
     def check_list_input(cls, value, info):
         if not isinstance(value, list):
@@ -41,6 +90,16 @@ class SendEmailParamsValidator(BaseModel):
 class Email():
 
     def __init__(self, email_sender, email_password):
+        """
+        Inicializa uma instância da classe Email.
+        Args:
+            email_sender (str): O endereço de e-mail do remetente.
+            email_password (str): A senha do e-mail do remetente.
+        Raises:
+            ValueError: Se houver um erro na validação dos dados de entrada da inicialização da instância.
+        Returns:
+            None
+        """
 
         self.email_sender = email_sender
         self.email_password = email_password
@@ -62,6 +121,18 @@ class Email():
 
 
     def login_email(self):
+        """
+        Realiza o login no servidor de e-mail.
+        Returns:
+            smtplib.SMTP: Objeto que representa a conexão com o servidor de e-mail.
+        Raises:
+            dict: Dicionário contendo o status de erro caso ocorra uma exceção durante o login.
+        Example:
+            email_sender = 'seu_email@gmail.com'
+            email_password = 'sua_senha'
+            email = Email(email_sender, email_password)
+            server = email.login_email()
+        """
 
         try:
 
@@ -80,6 +151,32 @@ class Email():
 
     
     def send_email( self, to : list , message : str , title : str , reply_to: str, attachments : list = [] , cc : list = [] , cco : list = [] ) -> dict:
+        """
+        Envia um email com os parâmetros fornecidos.
+        Args:
+            to (list): Lista de destinatários do email.
+            message (str): Corpo do email.
+            title (str): Título do email.
+            reply_to (str): Endereço de email para resposta.
+            attachments (list, optional): Lista de caminhos dos arquivos anexos. Defaults to [].
+            cc (list, optional): Lista de destinatários em cópia. Defaults to [].
+            cco (list, optional): Lista de destinatários em cópia oculta. Defaults to [].
+        Returns:
+            dict: Dicionário com o status do envio do email. Se o envio for bem-sucedido, o dicionário terá a chave 'status' com valor True. Caso contrário, terá a chave 'status' com valor False e a chave 'error' com a descrição do erro.
+        Raises:
+            ValueError: Se houver erro na validação dos dados para o envio do email.
+        Example:
+            email = EmailSender()
+            to = ['example1@example.com', 'example2@example.com']
+            message = 'Olá, isso é um teste de email.'
+            title = 'Teste de Email'
+            reply_to = 'noreply@example.com'
+            attachments = ['/path/to/file1.txt', '/path/to/file2.txt']
+            cc = ['cc1@example.com', 'cc2@example.com']
+            cco = ['cco1@example.com', 'cco2@example.com']
+            result = email.send_email(to, message, title, reply_to, attachments, cc, cco)
+            print(result)
+        """
 
         try:
         

csc_cia_stne/google_drive.py

@@ -23,11 +23,21 @@ class GoogleDrive():
     
     def __init__(self, key, with_subject : str, scopes : list = ["https://www.googleapis.com/auth/drive"], version : str = "v3"):
         """
-            Inicializa a classe GoogleDrive e autentica o serviço usando a chave fornecida.
-
-            Args:
-                key (str): Chave de autenticação do Google Drive.
+        Inicializa uma instância da classe GoogleDrive.
+        Parâmetros:
+        - key (str): A chave para acessar o segredo necessário para autenticação.
+        - with_subject (str): O assunto para o qual a autenticação será realizada.
+        - scopes (list): Uma lista de escopos de permissão para acesso ao Google Drive. O valor padrão é ["https://www.googleapis.com/auth/drive"].
+        - version (str): A versão da API do Google Drive a ser utilizada. O valor padrão é "v3".
+        Raises:
+        - ValueError: Se ocorrer um erro na validação dos dados de input da inicialização da instância.
+        Exemplo de uso:
+        ```
+        google_drive = GoogleDrive(key="chave_secreta", with_subject="assunto", scopes=["https://www.googleapis.com/auth/drive"], version="v3")
+        ```
         """
+        # código de inicialização da instância
+        
         try:
             InitParamsValidator(key=key, with_subject=with_subject, scopes=scopes)
         except ValidationError as e:
@@ -42,8 +52,18 @@ class GoogleDrive():
 
     def timer_decorator(func):
         """
-            Classe reponsável por calcular qualquer execução que ela seja chamada.        
+        Decorator que calcula o tempo de execução de uma função.
+        Args:
+            func: A função a ser decorada.
+        Returns:
+            A função decorada.
+        Exemplo de uso:
+            @timer_decorator
+            def minha_funcao():
+                # código da função
+            minha_funcao()
         """
+        
         def wrapper(*args, **kwargs):
             inicio = time.time()
             resultado = func(*args, **kwargs)
@@ -54,15 +74,20 @@ class GoogleDrive():
     
     def create_service(self):
         """
-            Cria um serviço para a plataforma Google especificada.
-
-            Args:
-                platform (str): O nome da plataforma Google para a qual o serviço será criado (por exemplo, 'drive', 'sheets').
-
-            Returns:
-                googleapiclient.discovery.Resource: Serviço do Google para a plataforma especificada.
-                bool: Retorna False se houver um erro ao criar o serviço.
+        Cria um serviço do Google Drive.
+        Returns:
+            cred: Objeto de credenciais do Google Drive.
+            False: Caso ocorra algum erro ao criar o serviço.
+        Raises:
+            Exception: Caso ocorra algum erro ao criar o serviço do Google Drive.
+        Exemplo de uso:
+            service = create_service()
+            if service:
+                # Fazer algo com o serviço do Google Drive
+            else:
+                # Tratar o erro de criação do serviço
         """
+        
         try:
             
             cred = build(f"drive", f"{self.version}", credentials=self.__auth)
@@ -74,16 +99,18 @@ class GoogleDrive():
     
     def __autentica(self, with_subject : str):
         """
-            Autentica o serviço do Google utilizando um token e escopos fornecidos.
-
-            Args:
-                token (dict): As credenciais de autenticação.
-                scopes (list): A lista de escopos para o acesso aos serviços do Google.
-
-            Returns:
-                google.oauth2.service_account.Credentials: Objeto de credenciais autenticado.
-                bool: Retorna False em caso de erro.
+        Autentica o usuário com as credenciais fornecidas e retorna as credenciais delegadas para o assunto especificado.
+        Args:
+            with_subject (str): O assunto para o qual as credenciais serão delegadas.
+        Returns:
+            google.auth.credentials.Credentials: As credenciais delegadas para o assunto especificado.
+        Raises:
+            Exception: Se ocorrer um erro durante a autenticação.
+        Example:
+            # Autenticar com o assunto "user@example.com"
+            credentials = self.__autentica("user@example.com")
         """
+        
 
         try:
             credentials = service_account.Credentials.from_service_account_info(self.__token, scopes=self.scopes)

csc_cia_stne/karavela.py

@@ -9,14 +9,22 @@ class Karavela():
         self.healthy_check_file = None
     
     def create_health_check_file(self,health_check_filename:str = None)->bool:
-        """Cria o arquivo de health check
-
+        """
+        Cria um arquivo de verificação de saúde.
         Args:
-            health_check_file (str): nome do arquivo de health check a ser criado
+            health_check_filename (str, optional): O nome do arquivo de verificação de saúde. 
+                Se não for fornecido, um ValueError será levantado.
         Returns:
-            bool: True
+            bool: True se o arquivo for criado com sucesso.
+        Raises:
+            ValueError: Se o parâmetro health_check_filename não for fornecido.
+        Example:
+            >>> karavela = Karavela()
+            >>> karavela.create_health_check_file("health_check.txt")
+            True
         """
         
+        
         if health_check_filename is None or health_check_filename == "":
             
             raise ValueError("O método 'create_health_check_file' precisa do parâmetro health_check_filename especificado")
@@ -43,11 +51,15 @@ class Karavela():
             raise e
     
     def destroy_health_check_file(self)->bool:
-        """Deleta o arquivo de health check
-
-        Returns:
-            bool: True
         """
+        Remove o arquivo de verificação de saúde.
+        Retorna:
+            bool: True se o arquivo foi removido com sucesso, False caso contrário.
+        Raises:
+            ValueError: Se o método 'create_health_check_file' não foi executado antes.
+            Exception: Se ocorrer algum erro durante a remoção do arquivo.
+        """
+        
         
         if self.health_check_filename is None:
         

csc_cia_stne/logger_rich.py

@@ -116,6 +116,13 @@ logger = logging.getLogger()
 """
 
 def get_logger():
+    """
+    Retorna um objeto logger configurado com base nas variáveis de ambiente.
+    Returns:
+        logging.Logger: Objeto logger configurado.
+    Raises:
+        ValueError: Se o valor da variável de ambiente 'log_level' não for 'DEBUG', 'INFO', 'WARNING', 'ERROR' ou 'CRITICAL'.
+    """
     # Instala formatações de exception da biblioteca Rich
     install()