csc-cia-stne 0.0.33__py3-none-any.whl → 0.0.35__py3-none-any.whl

csc_cia_stne/stne_admin.py

@@ -121,6 +121,22 @@ class ReceiptIDValidator(BaseModel):
 class StoneAdmin:
     
     def __init__(self, client_id:str, user_agent:str, private_key:str, ambiente:str):
+        """
+        Inicializa uma instância da classe STNEAdmin.
+        Parâmetros:
+        - client_id (str): O ID do cliente.
+        - user_agent (str): O agente do usuário.
+        - private_key (str): A chave privada.
+        - ambiente (str): O ambiente de execução ('prd' para produção ou qualquer outro valor para sandbox).
+        Exemplo de uso:
+        ```
+        client_id = '123456789'
+        user_agent = 'MyApp/1.0'
+        private_key = 'my_private_key'
+        ambiente = 'prd'
+        admin = STNEAdmin(client_id, user_agent, private_key, ambiente)
+        ```
+        """
     
         try:
             
@@ -153,6 +169,16 @@ class StoneAdmin:
         }
 
     def __get_token(self):
+        """
+        Obtém um token de autenticação para acessar a API do Stone Bank.
+        Returns:
+            str: O token de acesso gerado.
+        Raises:
+            requests.exceptions.RequestException: Se ocorrer um erro durante a solicitação HTTP.
+            KeyError: Se a resposta da solicitação não contiver a chave 'access_token'.
+        Exemplo:
+            >>> token = self.__get_token()
+        """
         base_url = f'{self.base_auth_url}/auth/realms/stone_bank'
         auth_url = f'{base_url}/protocol/openid-connect/token'
         payload = {
@@ -186,6 +212,24 @@ class StoneAdmin:
         return response.json()['access_token']
 
     def renew_authorization(self):
+        """
+        Renova a autorização do usuário.
+
+        Esta função renova a autorização do usuário, obtendo um novo token de autenticação
+        e atualizando o cabeçalho de autenticação.
+
+        Parâmetros:
+        - Nenhum
+
+        Retorno:
+        - Nenhum
+
+        Exemplo de uso:
+        ```
+        obj = ClassName()
+        obj.renew_authorization()
+        ```
+        """
         self.token = self.__get_token()
         self.authenticated_header = {
             'Authorization' : f"Bearer {self.token}",
@@ -194,6 +238,43 @@ class StoneAdmin:
         }
 
     def verificar_cliente(self,documento:str)->dict:
+        """
+        Verifica se um cliente com o documento fornecido existe e se a conta associada está ativa.
+        Args:
+            documento (str): O número do documento do cliente.
+        Returns:
+            dict: Um dicionário contendo as informações do cliente e da conta, se encontrado.
+                - success (bool): Indica se a operação foi bem-sucedida.
+                - status_code (int): O código de status da resposta da API.
+                - error (Exception): O erro ocorrido, se houver.
+                - encontrado (bool): Indica se o cliente foi encontrado.
+                - detalhes (list): Uma lista de dicionários contendo os detalhes das contas encontradas.
+                    - account_code (str): O código da conta.
+                    - account_id (str): O ID da conta.
+                    - owner_id (str): O ID do proprietário da conta.
+                    - closed_at (str): A data de encerramento da conta, se estiver fechada.
+                    - created_at (str): A data de criação da conta.
+                    - conta_ativa (bool): Indica se a conta está ativa.
+        Raises:
+            ValueError: Se ocorrer um erro na validação dos dados de entrada.
+            ValueError: Se ocorrer um erro na requisição à API Stone Admin.
+        Example:
+            # Instanciar o objeto da classe
+            stne_admin = StneAdmin()
+            # Chamar a função verificar_cliente
+            resultado = stne_admin.verificar_cliente("123456789")
+            # Verificar se a operação foi bem-sucedida
+            if resultado["success"]:
+                # Verificar se o cliente foi encontrado
+                if resultado["encontrado"]:
+                    # Acessar os detalhes das contas encontradas
+                    detalhes = resultado["detalhes"]
+                    for conta in detalhes:
+                        print(f"Conta: {conta['account_code']}")
+                        print(f"Status: {'Ativa' if conta['conta_ativa'] else 'Inativa'}")
+                    print("Cliente não encontrado.")
+                print(f"Erro: {resultado['error']}")
+        """
         
         try:
         
@@ -295,6 +376,19 @@ class StoneAdmin:
             return retorno_json
     
     def balance_da_conta(self,account_id:str):
+        """
+        Retorna o saldo da conta especificada.
+        Parâmetros:
+        - account_id (str): O ID da conta.
+        Retorna:
+        - response (objeto): A resposta da requisição GET contendo o saldo da conta.
+        Exemplo de uso:
+        ```
+        account_id = "123456789"
+        response = balance_da_conta(account_id)
+        print(response)
+        ```
+        """
         try:
         
             AccountIDValidator(account_id=account_id)
@@ -308,6 +402,18 @@ class StoneAdmin:
         return response
 
     def detalhar_titular_cpf(self,documento:str):
+        """
+        Detalha o titular do CPF fornecido.
+        Args:
+            documento (str): O número do CPF do titular.
+        Returns:
+            requests.Response: A resposta da requisição HTTP.
+        Raises:
+            ValueError: Se houver um erro na validação dos dados de input.
+        Example:
+            >>> admin = StneAdmin()
+            >>> response = admin.detalhar_titular_cpf('12345678900')
+        """
 
         try:
         
@@ -328,6 +434,18 @@ class StoneAdmin:
         return response
 
     def detalhar_titular_cnpj(self,documento:str):
+        """
+        Detalha o titular de um CNPJ.
+        Args:
+            documento (str): O número do CNPJ a ser consultado.
+        Returns:
+            requests.Response: A resposta da requisição HTTP.
+        Raises:
+            ValueError: Se houver um erro na validação dos dados de input.
+        Example:
+            >>> admin = StneAdmin()
+            >>> response = admin.detalhar_titular_cnpj('12345678901234')
+        """
 
         try:
         
@@ -346,6 +464,44 @@ class StoneAdmin:
         return response
 
     def extrair_extrato(self,account_id:str,data_inicio:datetime,data_fim:datetime,async_mode:bool=False):
+        """
+        Extrai o extrato de uma conta.
+        Args:
+            account_id (str): O ID da conta.
+            data_inicio (datetime): A data de início do extrato.
+            data_fim (datetime): A data de fim do extrato.
+            async_mode (bool, optional): Modo assíncrono. Defaults to False.
+        Returns:
+            dict: Um dicionário contendo informações sobre o resultado da operação.
+                - Se async_mode for False e a resposta for bem-sucedida, retorna:
+                    {
+                        "success": True,
+                        "status_code": int,
+                        "error": None,
+                        "pdf_content": bytes
+                    }
+                - Se async_mode for True e a resposta for bem-sucedida, retorna:
+                    {
+                        "success": True,
+                        "status_code": int,
+                        "error": None,
+                        "receipt_id": str
+                    }
+                - Se a resposta não for bem-sucedida, retorna:
+                    {
+                        "success": False,
+                        "status_code": int,
+                        "error": str,
+                        "pdf_content": None
+                    }
+                - Se ocorrer uma exceção, retorna:
+                    {
+                        "success": False,
+                        "status_code": int,
+                        "error": Exception,
+                        "pdf_content": None
+                    }
+        """
         
         try:
         
@@ -392,6 +548,24 @@ class StoneAdmin:
             return {"success": False, "status_code": response.status_code, "error": e, "pdf_content": None}
 
     def download_receipt(self,receipt_id:str):
+        """
+        Faz o download de um recibo a partir de um ID de recibo.
+        Args:
+            receipt_id (str): O ID do recibo a ser baixado.
+        Returns:
+            dict: Um dicionário contendo os seguintes campos:
+                - 'result' (bool): Indica se o download foi bem-sucedido.
+                - 'status_code' (int): O código de status da resposta HTTP.
+                - 'error' (str ou dict): O erro retornado, se houver.
+                - 'pdf_content' (bytes): O conteúdo do arquivo PDF, se o download for bem-sucedido.
+        Raises:
+            ValueError: Se ocorrer um erro na validação dos dados de entrada.
+        Example:
+            >>> admin = STNEAdmin()
+            >>> result = admin.download_receipt("123456")
+            >>> print(result)
+            {'result': True, 'status_code': 200, 'error': None, 'pdf_content': b'%PDF-1.7\n%����\n1 0 obj\n<<\n/Type /Catalog\n/Pages 2 0 R\n>>\nendobj\n2 0 obj\n<<\n/Type /Pages\n/Kids [3 0 R]\n/Count 1\n>>\nendobj\n3 0 obj\n<<\n/Type /Page\n/Parent 2 0 R\n/Resources <<\n/Font <<\n/F1 4 0 R\n>>\n/ProcSet 5 0 R\n>>\n/MediaBox [0 0 595.276 841.890]\n/Contents 6 0 R\n>>\nendobj\n4 0 obj\n<<\n/Type /Font\n/Subtype /Type1\n/Name /F1\n/BaseFont /Helvetica\n/Encoding /MacRomanEncoding\n>>\nendobj\n5 0 obj\n[/PDF /Text]\nendobj\n6 0 obj\n<<\n/Length 44\n>>\nstream\nBT\n/F1 24 Tf\n100 100 Td\n(Hello, World!) Tj\nET\nendstream\nendobj\nxref\n0 7\n0000000000 65535 f \n0000000010 00000 n \n0000000077 00000 n \n0000000178 00000 n \n0000000302 00000 n \n0000000406 00000 n \n0000000519 00000 n \ntrailer\n<<\n/Size 7\n/Root 1 0 R\n>>\nstartxref\n614\n%%EOF\n'}
+        """
         
         try:
         

csc_cia_stne/utilitarios/__init__.py

@@ -1 +1 @@
-from .functions import titulo, recriar_pasta, b64encode, b64decode, convert_bquery_result_to_json
+from .functions import titulo, recriar_pasta, b64encode, b64decode, convert_bquery_result_to_json,get_config

csc_cia_stne/utilitarios/functions/__init__.py

@@ -1,4 +1,5 @@
 from .func_titulo import titulo
 from .func_recriar_pastas import recriar_pasta
 from .func_b64 import b64decode, b64encode
-from .func_converters import convert_bquery_result_to_json
+from .func_converters import convert_bquery_result_to_json
+from .func_settings import get_config

csc_cia_stne/utilitarios/functions/func_recriar_pastas.py

@@ -2,6 +2,16 @@ import os
 import shutil
 
 def recriar_pasta(caminho_pasta):
+    """
+    Remove a pasta existente, se houver, e cria uma nova pasta no caminho especificado.
+    Args:
+        caminho_pasta (str): O caminho da pasta a ser recriada.
+    Returns:
+        tuple: Uma tupla contendo um valor booleano indicando se a operação foi bem-sucedida e uma mensagem de erro em caso de falha.
+    Examples:
+        >>> recriar_pasta('/caminho/para/pasta')
+        (True, None)
+    """
 
     try:
 

csc_cia_stne/utilitarios/functions/func_settings.py

@@ -0,0 +1,62 @@
+import yaml
+import os
+import sys
+
+
+def get_config(file_path:str="settings.yaml",file_path_local:str=None,prod:bool=False) -> dict:
+    """
+    Retorna as configurações carregadas a partir de um arquivo YAML.
+    Parâmetros:
+    - file_path (str): O caminho do arquivo YAML.
+    - file_path_local (str, opcional): O caminho local do arquivo YAML, caso exista.
+    - prod (bool, opcional): Indica se as configurações de produção devem ser carregadas.
+    Retorna:
+    - dict: Um dicionário contendo as configurações carregadas do arquivo YAML.
+    Lança:
+    - FileNotFoundError: Caso o arquivo especificado não seja encontrado.
+    - Exception: Caso ocorra algum erro ao carregar as configurações.
+    Exemplo de uso:
+    config = get_config('/path/to/config.yaml', prod=True)
+    """
+
+    # Essa validação serve apenas para que continue funcionando mesmo se for dentro de um executavel
+
+    try:
+
+        base_path = sys._MEIPASS
+
+    except:
+
+        base_path = os.path.abspath(".")
+
+    if not os.path.exists(file_path):
+
+        file_place = os.path.join(base_path, file_path)
+
+    elif file_path_local is not None:
+
+        file_place = os.path.join(base_path, file_path_local)
+
+    else:
+
+        raise FileNotFoundError(f"Arquivo '{file_path}' não encontrado.")
+    
+    try:
+
+        with open(file_place, 'r', encoding='utf-8') as f:
+
+            config = yaml.safe_load(f)
+
+        if prod:
+
+            config['env'] = config['prod']
+
+        else:
+
+            config['env'] = config['prod']
+
+        return config
+
+    except Exception as e:
+
+        raise(e)

csc_cia_stne/utilitarios/functions/func_titulo.py

@@ -9,6 +9,16 @@ from pydantic import ValidationError, field_validator
 
 # Classe para validar - titulo
 class TituloSettings(BaseModel):
+    """
+    Classe que define as configurações do título do projeto.
+    Atributos:
+    - project_name (str): O nome do projeto.
+    - project_version (str): A versão do projeto.
+    - project_dev_name (str): O nome do desenvolvedor do projeto.
+    - project_dev_mail (str): O e-mail do desenvolvedor do projeto.
+    Métodos:
+    - check_non_empty_string(value, info): Método de validação para garantir que nenhum campo seja uma string vazia.
+    """
     
     # Titulo
     project_name: str
@@ -16,7 +26,21 @@ class TituloSettings(BaseModel):
     project_dev_name: str
     project_dev_mail: str
     # Validador para garantir que nenhum campo seja uma string vazia
-
+    """
+    Método de validação para garantir que nenhum campo seja uma string vazia.
+    Parâmetros:
+    - value: O valor do campo a ser validado.
+    - info: Informações sobre o campo a ser validado.
+    Retorna:
+    - O valor do campo se for uma string não vazia.
+    Lança:
+    - ValueError: Se o valor do campo for uma string vazia.
+    Exemplo de uso:
+    ```
+    settings = TituloSettings()
+    settings.check_non_empty_string("GitHub Copilot", "project_name")
+    ```
+    """
     @field_validator('project_name', 'project_version', 'project_dev_name', 'project_dev_mail')
     def check_non_empty_string(cls, value, info):
         if not isinstance(value, str) or not value.strip():
@@ -56,6 +80,19 @@ def last_modified()->datetime:
     return last_modified_date
 
 def titulo(project_name:str,project_version:str,project_dev_name:str,project_dev_mail:str):
+    """
+    Gera um título formatado para exibição do projeto.
+    Args:
+        project_name (str): Nome do projeto.
+        project_version (str): Versão do projeto.
+        project_dev_name (str): Nome do desenvolvedor do projeto.
+        project_dev_mail (str): E-mail do desenvolvedor do projeto.
+    Raises:
+        ValueError: Caso alguma variável obrigatória esteja ausente no arquivo .env ou nas variáveis de ambiente da máquina.
+    Example:
+        >>> titulo("Meu Projeto", "1.0", "João", "joao@example.com")
+        [Exemplo de saída]
+    """
 
     try:
         settings = TituloSettings(project_name=project_name,project_version=project_version,project_dev_name=project_dev_name,project_dev_mail=project_dev_mail)

csc_cia_stne/utilitarios/validations/GcpBigQueryValidator.py

@@ -1,4 +1,5 @@
 from pydantic import BaseModel, field_validator, model_validator
+
 class InitParamsValidator(BaseModel):
     limit:int
     id_project:str
@@ -64,11 +65,32 @@ class tryQueryValidator(BaseModel):
 
 
 class tryInsertListValidator(BaseModel):
-
+    """
+    Classe de validação para o modelo tryInsertListValidator.
+    Atributos:
+    - insert_limit (int): Limite de inserção.
+    - list_to_insert (list): Lista a ser inserida.
+    - table (str): Nome da tabela.
+    Métodos:
+    - check_list_input(value, info): Valida se o valor fornecido para 'list_to_insert' é uma lista não vazia.
+    - check_str_input(value, info): Valida se o valor fornecido para 'table' é uma string não vazia.
+    - check_int_input(value, info): Valida se o valor fornecido para 'insert_limit' é um inteiro não maior que 10000.
+    """
+        
     insert_limit:int
     list_to_insert:list
     table:str
 
+    """
+    Valida se o valor fornecido para 'list_to_insert' é uma lista não vazia.
+    Parâmetros:
+    - value: O valor a ser validado.
+    - info: Informações adicionais sobre o campo.
+    Retorna:
+    - O valor fornecido, se for uma lista não vazia.
+    Lança:
+    - ValueError: Se o valor não for uma lista ou estiver vazio.
+    """
     @field_validator('list_to_insert')
     def check_list_input(cls, value, info):
         if not isinstance(value, list) and len(value) > 0:
@@ -76,6 +98,16 @@ class tryInsertListValidator(BaseModel):
         
         return value
     
+    """
+    Valida se o valor fornecido para 'table' é uma string não vazia.
+    Parâmetros:
+    - value: O valor a ser validado.
+    - info: Informações adicionais sobre o campo.
+    Retorna:
+    - O valor fornecido, se for uma string não vazia.
+    Lança:
+    - ValueError: Se o valor não for uma string ou estiver vazio.
+    """
     @field_validator('table')
     def check_str_input(cls, value, info):
         if not isinstance(value, str) or not value.strip():
@@ -83,6 +115,16 @@ class tryInsertListValidator(BaseModel):
         
         return value
     
+    """
+    Valida se o valor fornecido para 'insert_limit' é um inteiro não maior que 10000.
+    Parâmetros:
+    - value: O valor a ser validado.
+    - info: Informações adicionais sobre o campo.
+    Retorna:
+    - O valor fornecido, se for um inteiro não maior que 10000.
+    Lança:
+    - ValueError: Se o valor não for um inteiro ou for maior que 10000.
+    """
     @field_validator('insert_limit')
     def check_int_input(cls, value, info):
         if not isinstance(value, int) or value > 10000:

csc_cia_stne/utilitarios/validations/GoogleDriveValidator.py

@@ -1,16 +1,50 @@
 
 from pydantic import BaseModel, field_validator
+
 class InitParamsValidator(BaseModel):
+    """
+    Classe responsável por validar os parâmetros de inicialização.
+    Atributos:
+    - key (str): A chave de autenticação.
+    - with_subject (str): O assunto da autenticação.
+    - scopes (list): A lista de escopos.
+    - version (str): A versão.
+    Métodos:
+    - check_str_input(cls, value, info): Valida se o valor é uma string não vazia.
+    - check_list_input(cls, value, info): Valida se o valor é uma lista.
+    """
+        
     key: str
     with_subject: str
     scopes : list
     version : str
 
+    """
+    Valida se o valor é uma string não vazia.
+    Parâmetros:
+    - value (Any): O valor a ser validado.
+    - info (FieldInfo): Informações sobre o campo.
+    Retorna:
+    - value (Any): O valor validado.
+    Lança:
+    - ValueError: Se o valor não for uma string ou estiver vazio.
+    """
     @field_validator('key','with_subject', "version")
     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 (Any): O valor a ser validado.
+    - info (FieldInfo): Informações sobre o campo.
+    Retorna:
+    - value (Any): O valor validado.
+    Lança:
+    - ValueError: Se o valor não for uma lista.
+    """
     @field_validator('scopes')
     def check_list_input(cls, value, info):
         if not isinstance(value, list):
@@ -19,9 +53,27 @@ class InitParamsValidator(BaseModel):
         return value
 
 class CreateFolderValidator(BaseModel):
+    """
+    Validação para a criação de uma pasta no Google Drive.
+    Atributos:
+    - name (str): O nome da pasta a ser criada.
+    - parent_folder_id (str): O ID da pasta pai onde a nova pasta será criada.
+    Métodos:
+    - check_str_input(value, info): Valida se o valor fornecido é uma string não vazia.
+    """
     name: str
     parent_folder_id: str
 
+    """
+    Valida se o valor fornecido é uma string não vazia.
+    Parâmetros:
+    - value: O valor a ser validado.
+    - info: Informações sobre o campo sendo validado.
+    Retorna:
+    - O valor fornecido, se for uma string não vazia.
+    Lança:
+    - ValueError: Se o valor não for uma string ou for uma string vazia.
+    """
     @field_validator('name','parent_folder_id')
     def check_str_input(cls, value, info):
         if not isinstance(value, str) or not value.strip():
@@ -29,9 +81,36 @@ class CreateFolderValidator(BaseModel):
         return value
 
 class ListFolderValidator(BaseModel):
-    query : str
-    spaces: str
-    fields : str
+    """
+    Validação para a classe ListFolderValidator.
+
+    Atributos:
+    - query (str): A consulta a ser realizada.
+    - spaces (str): Os espaços a serem considerados.
+    - fields (str): Os campos a serem retornados.
+
+    Métodos:
+    - check_str_input(cls, value, info): Valida se o valor fornecido é uma string não vazia.
+
+    """
+
+    query: str
+    fields: str
+
+    """
+    Valida se o valor fornecido é uma string não vazia.
+
+    Parâmetros:
+    - value (Any): O valor a ser validado.
+    - info (FieldInfo): Informações sobre o campo.
+
+    Retorna:
+    - value (Any): O valor validado.
+
+    Lança:
+    - ValueError: Se o valor não for uma string ou for uma string vazia.
+
+    """
     @field_validator('query','spaces','fields')
     def check_str_input(cls, value, info):
         if not isinstance(value, str) or not value.strip():