csc-cia-stne 0.1.16__py3-none-any.whl → 0.1.17__py3-none-any.whl

csc_cia_stne/google_drive.py

@@ -1,59 +1,145 @@
-import os
-from googleapiclient.discovery import build
-from googleapiclient.http import MediaFileUpload
-from googleapiclient.errors import HttpError
-from io import BytesIO
-from google.oauth2 import service_account
+import os  # google_drive.py da lib - Operações do sistema operacional
+import base64  # Codificação/decodificação base64 para manipulação de dados
+from googleapiclient.discovery import build  # Construção do cliente da API do Google
+from googleapiclient.http import MediaFileUpload  # Upload de arquivos para APIs do Google
+from googleapiclient.http import MediaIoBaseUpload  # Upload de streams/buffers para APIs do Google
+from googleapiclient.errors import HttpError  # Tratamento de erros HTTP das APIs do Google
+from io import BytesIO  # Manipulação de streams de bytes em memória
+from google.oauth2 import service_account  # Autenticação com conta de serviço do Google
 from .utilitarios.validations.GoogleDriveValidator import (
     InitParamsValidator,
     CreateFolderValidator,
     ListFolderValidator,
     UploadValidator,
 )
-from pydantic import ValidationError
+from pydantic import ValidationError  # Exceções de validação do Pydantic
+from typing import Iterable, Optional, Dict, List, Union, Any  # Type hints para melhor documentação
 
 
 class GoogleDrive:
     """
-    Classe responsável por gerenciar operações no Google Drive, como upload de arquivos, criação de pastas
-    e listagem de conteúdo. Utiliza a API do Google Drive para realizar essas operações.
-
-    Args:
-        key (str): Chave de autenticação para acessar a API do Google Drive.
+    Classe responsável por gerenciar operações no Google Drive usando padrão Singleton.
+    
+    Esta classe implementa o padrão Singleton, garantindo que apenas uma instância
+    seja criada durante a execução da aplicação. Fornece funcionalidades para:
+    - Upload de arquivos para o Google Drive
+    - Criação e listagem de pastas
+    - Autenticação usando conta de serviço do Google
+    - Operações de compartilhamento e permissões
+    
+    Note:
+        Como implementa Singleton, todas as instâncias criadas retornarão
+        a mesma referência de objeto, compartilhando estado e configurações.
+    
+    Attributes:
+        _instance (Optional[GoogleDrive]): Instância única da classe (padrão Singleton)
+        service: Cliente autenticado da API do Google Drive
+        version (str): Versão da API do Google Drive sendo utilizada
+        scopes (List[str]): Escopos de permissão para acesso ao Google Drive
+        with_subject (str): Email do usuário para delegação de credenciais
+        page_size (int): Número máximo de itens retornados por página nas consultas
+    
+    Examples:
+        >>> # Primeira instância
+        >>> drive1 = GoogleDrive(token=service_account_info, with_subject="user@domain.com")
+        >>> 
+        >>> # Segunda instância (retorna a mesma referência)
+        >>> drive2 = GoogleDrive(token=other_token, with_subject="other@domain.com")
+        >>> print(drive1 is drive2)  # True - mesma instância
     """
 
-    _instance = None  # Atributo de classe para armazenar a única instância.
+    _instance: Optional['GoogleDrive'] = None  # Atributo de classe para armazenar a única instância
 
-    def __new__(cls, *args, **kwargs):
-        # Verifica se já existe uma instância da classe.
+    def __new__(cls, *args, **kwargs) -> 'GoogleDrive':
+        """
+        Implementa o padrão Singleton para garantir instância única.
+        
+        Este método garante que apenas uma instância da classe GoogleDrive
+        seja criada durante toda a execução da aplicação, independentemente
+        de quantas vezes o construtor seja chamado.
+        
+        Args:
+            *args: Argumentos posicionais passados para o construtor
+            **kwargs: Argumentos nomeados passados para o construtor
+            
+        Returns:
+            GoogleDrive: A única instância da classe GoogleDrive
+            
+        Note:
+            Na primeira chamada, uma nova instância é criada e armazenada.
+            Nas chamadas subsequentes, a mesma instância é retornada.
+        """
+        # Verifica se já existe uma instância da classe
         if cls._instance is None:
-            # Cria e armazena a instância na primeira chamada.
+            # Cria e armazena a instância na primeira chamada
             cls._instance = super().__new__(cls)
         return cls._instance
 
     def __init__(
         self,
-        token: dict,
+        token: Dict[str, Any],
         with_subject: str,
-        scopes: list = ["https://www.googleapis.com/auth/drive"],
+        scopes: List[str] = ["https://www.googleapis.com/auth/drive"],
         version: str = "v3",
-    ):
+    ) -> None:
         """
-        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".
+        Inicializa uma instância da classe GoogleDrive com autenticação de conta de serviço.
+        
+        Configura a autenticação usando uma conta de serviço do Google Cloud e
+        estabelece conexão com a API do Google Drive. A autenticação é delegada
+        para um usuário específico usando o parâmetro with_subject.
+        
+        Args:
+            token (Dict[str, Any]): Dicionário contendo as credenciais da conta de serviço.
+                Deve incluir campos como 'type', 'project_id', 'private_key_id',
+                'private_key', 'client_email', 'client_id', 'auth_uri', 'token_uri', etc.
+            with_subject (str): Email do usuário para o qual as credenciais serão delegadas.
+                Este usuário deve ter permissões adequadas no domínio da organização.
+            scopes (List[str], optional): Lista de escopos de permissão para acesso ao Google Drive.
+                Padrão: ["https://www.googleapis.com/auth/drive"] (acesso completo).
+                Outros exemplos: 
+                - "https://www.googleapis.com/auth/drive.readonly" (somente leitura)
+                - "https://www.googleapis.com/auth/drive.file" (apenas arquivos criados pela app)
+            version (str, optional): Versão da API do Google Drive a ser utilizada.
+                Padrão: "v3" (versão mais recente estável).
+                
         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")
-        ```
+            ValueError: Se os dados de entrada falharem na validação do Pydantic.
+                Inclui detalhes sobre quais campos são inválidos e por quê.
+            
+        Attributes:
+            __token (Dict[str, Any]): Credenciais da conta de serviço (privado)
+            version (str): Versão da API sendo utilizada
+            scopes (List[str]): Escopos de permissão configurados
+            with_subject (str): Email do usuário delegado
+            page_size (int): Limite de itens por página (padrão: 1000)
+            service: Cliente autenticado da API do Google Drive
+        
+        Examples:
+            >>> # Configuração básica
+            >>> token = {
+            ...     "type": "service_account",
+            ...     "project_id": "my-project",
+            ...     "private_key": "-----BEGIN PRIVATE KEY-----\n...",
+            ...     "client_email": "service@my-project.iam.gserviceaccount.com",
+            ...     # ... outros campos obrigatórios
+            ... }
+            >>> drive = GoogleDrive(
+            ...     token=token,
+            ...     with_subject="user@domain.com"
+            ... )
+            >>>
+            >>> # Configuração com escopos customizados
+            >>> drive = GoogleDrive(
+            ...     token=token,
+            ...     with_subject="admin@domain.com",
+            ...     scopes=["https://www.googleapis.com/auth/drive.readonly"],
+            ...     version="v3"
+            ... )
         """
 
         try:
+            # Validação dos parâmetros usando Pydantic para garantir tipos e formatos corretos
             InitParamsValidator(
                 token=token, with_subject=with_subject, scopes=scopes, version=version
             )
@@ -62,84 +148,186 @@ class GoogleDrive:
                 "Erro na validação dos dados de input da inicialização da instância:",
                 e.errors(),
             )
-        self.__token = token
-        self.version = version
-        self.scopes = scopes
-        self.with_subject = with_subject
-        self.page_size = 1000
+        
+        # Armazenamento das configurações validadas
+        self.__token = token  # Credenciais privadas da conta de serviço
+        self.version = version  # Versão da API do Google Drive
+        self.scopes = scopes  # Escopos de permissão para autenticação
+        self.with_subject = with_subject  # Email do usuário para delegação
+        self.page_size = 1000  # Limite padrão de itens por página nas consultas
+        
+        # Criação do cliente autenticado da API do Google Drive
         self.service = self.__create_service()
 
-    def __create_service(self):
+    def __create_service(self) -> Union[Any, bool]:
         """
-        Cria um serviço do Google Drive.
+        Cria e configura o cliente de serviço do Google Drive.
+        
+        Este método privado estabelece a conexão autenticada com a API do Google Drive
+        usando as credenciais da conta de serviço configuradas durante a inicialização.
+        O processo inclui autenticação delegada e construção do objeto de serviço.
+        
         Returns:
-            cred: Objeto de credenciais do Google Drive.
-            False: Caso ocorra algum erro ao criar o serviço.
+            Union[Any, bool]: 
+                - Objeto do serviço Google Drive se a conexão for bem-sucedida
+                - False se ocorrer qualquer erro durante o processo de criaçã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
+            Exception: Capturada internamente e retorna False em caso de erro.
+                Possíveis causas de erro incluem:
+                - Credenciais inválidas ou malformadas
+                - Problemas de conectividade de rede
+                - Configurações incorretas de escopo ou versão da API
+                - Falhas na delegação de credenciais
+        
+        Note:
+            Este é um método privado (prefixo __) e não deve ser chamado diretamente
+            fora da classe. É usado automaticamente durante a inicialização.
+        
+        Examples:
+            >>> # Uso interno durante __init__
+            >>> self.service = self.__create_service()
+            >>> if self.service:
+            ...     print("Conexão com Google Drive estabelecida")
+            ... else:
+            ...     print("Falha na conexão com Google Drive")
         """
 
         try:
+            # Autentica usando as credenciais da conta de serviço com delegação de usuário
             auth = self.__autentica(self.with_subject)
+            
+            # Constrói o cliente da API do Google Drive com as credenciais autenticadas
             service = build(f"drive", f"{self.version}", credentials=auth)
             return service
         except Exception as e:
+            # Em caso de erro, retorna False para indicar falha na criação do serviço
+            # O erro específico é capturado mas não re-lançado para manter a interface limpa
             return False
 
-    def __autentica(self, with_subject: str):
+    def __autentica(self, with_subject: str) -> Union[service_account.Credentials, bool]:
         """
-        Autentica o usuário com as credenciais fornecidas e retorna as credenciais delegadas para o assunto especificado.
+        Realiza autenticação delegada usando conta de serviço do Google Cloud.
+        
+        Este método privado configura a autenticação OAuth2 usando uma conta de serviço
+        e delega as credenciais para um usuário específico. É necessário quando uma
+        aplicação precisa acessar recursos do Google Drive em nome de um usuário
+        específico da organização.
+        
         Args:
-            with_subject (str): O assunto para o qual as credenciais serão delegadas.
+            with_subject (str): Email do usuário para o qual as credenciais serão delegadas.
+                Este usuário deve existir no domínio da organização e ter as permissões
+                adequadas para acessar os recursos solicitados.
+        
         Returns:
-            google.auth.credentials.Credentials: As credenciais delegadas para o assunto especificado.
+            Union[service_account.Credentials, bool]:
+                - Objeto de credenciais delegadas se a autenticação for bem-sucedida
+                - False se ocorrer qualquer erro durante o processo de autenticação
+        
         Raises:
-            Exception: Se ocorrer um erro durante a autenticação.
-        Example:
-            # Autenticar com o assunto "user@example.com"
-            credentials = self.__autentica("user@example.com")
+            Exception: Capturada internamente e retorna False em caso de erro.
+                Possíveis causas de erro incluem:
+                - Token de conta de serviço inválido ou malformado
+                - Usuário especificado não existe no domínio
+                - Escopos insuficientes para a delegação
+                - Conta de serviço sem permissão de delegação
+        
+        Note:
+            - Este é um método privado (prefixo __) usado internamente pela classe
+            - Requer que a conta de serviço tenha permissão de delegação configurada
+            - O usuário delegado deve fazer parte do mesmo domínio da organização
+        
+        Examples:
+            >>> # Uso interno - autentica para um usuário específico
+            >>> credentials = self.__autentica("user@company.com")
+            >>> if credentials:
+            ...     print("Autenticação delegada bem-sucedida")
+            ... else:
+            ...     print("Falha na autenticação delegada")
         """
 
         try:
+            # Cria credenciais da conta de serviço a partir do token fornecido
             credentials = service_account.Credentials.from_service_account_info(
                 self.__token, scopes=self.scopes
             )
+            
+            # Delega as credenciais para o usuário especificado
+            # Isso permite que a aplicação aja em nome do usuário
             delegated_credencial = credentials.with_subject(with_subject)
             return delegated_credencial
 
         except Exception as e:
+            # Em caso de erro, retorna False para indicar falha na autenticação
+            # O erro específico é capturado mas não re-lançado para manter a interface limpa
             return False
 
-    def upload(self, folder_id: str, name: str, file_path: str, mimetype: str):
+    def upload(self, folder_id: str, name: str, file_path: str, mimetype: str) -> Optional[Dict[str, Any]]:
         """
-        Faz o upload de um arquivo para o Google Drive em uma pasta especificada.
+        Realiza upload de um arquivo para uma pasta específica no Google Drive.
+
+        Este método faz upload de arquivos locais para o Google Drive, criando uma nova
+        entrada na pasta especificada. Suporta todos os tipos de arquivo através da
+        especificação do tipo MIME apropriado.
 
         Args:
-            folder_id (str): ID da pasta no Google Drive onde o arquivo será armazenado.
-            name (str): Nome do arquivo que será carregado.
-            file_path (str): Caminho completo do arquivo no sistema local.
-            mimetype (str): Tipo MIME do arquivo a ser carregado.
-                exemplos:   text/plain
-                            text/html
-                            image/jpeg
-                            image/png
-                            audio/mpeg
-                            audio/ogg
-                            audio/*
-                            video/mp4
-                            application/octet-stream
+            folder_id (str): ID único da pasta no Google Drive onde o arquivo será armazenado.
+                Formato típico: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+            name (str): Nome que o arquivo terá no Google Drive (pode ser diferente do nome local).
+                Exemplo: "documento_final.pdf", "relatorio_2025.xlsx"
+            file_path (str): Caminho absoluto ou relativo para o arquivo no sistema local.
+                Exemplo: "/home/user/documents/file.pdf", "C:\\Users\\user\\file.xlsx"
+            mimetype (str): Tipo MIME do arquivo que define como ele será interpretado.
+                Exemplos comuns:
+                - "text/plain" - Arquivo de texto simples
+                - "text/html" - Arquivo HTML
+                - "image/jpeg" - Imagem JPEG
+                - "image/png" - Imagem PNG
+                - "audio/mpeg" - Arquivo de áudio MP3
+                - "video/mp4" - Arquivo de vídeo MP4
+                - "application/pdf" - Documento PDF
+                - "application/vnd.ms-excel" - Planilha Excel
+                - "application/octet-stream" - Arquivo binário genérico
 
         Returns:
-            dict: Informações sobre o arquivo carregado, incluindo o ID do arquivo.
-            None: Caso o caminho do arquivo não seja encontrado.
+            Optional[Dict[str, Any]]: 
+                - Dicionário com informações do arquivo carregado se bem-sucedido:
+                  {"id": "arquivo_id", "name": "nome_arquivo", "parents": ["pasta_id"], ...}
+                - None se o arquivo local não for encontrado
+
+        Raises:
+            ValueError: Se os parâmetros de entrada falharem na validação do Pydantic.
+                Inclui detalhes sobre quais campos são inválidos.
+            HttpError: Se ocorrer erro na comunicação com a API do Google Drive.
+                Pode indicar problemas de permissão, quota ou conectividade.
+
+        Examples:
+            >>> # Upload de um documento PDF
+            >>> resultado = drive.upload(
+            ...     folder_id="1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms",
+            ...     name="contrato_assinado.pdf",
+            ...     file_path="/documents/contrato.pdf",
+            ...     mimetype="application/pdf"
+            ... )
+            >>> if resultado:
+            ...     print(f"Arquivo carregado com ID: {resultado['id']}")
+            
+            >>> # Upload de uma imagem
+            >>> resultado = drive.upload(
+            ...     folder_id="pasta_fotos_id",
+            ...     name="foto_evento.jpg",
+            ...     file_path="C:\\fotos\\evento.jpg",
+            ...     mimetype="image/jpeg"
+            ... )
+
+        Note:
+            - O arquivo deve existir no caminho especificado antes do upload
+            - O folder_id deve referenciar uma pasta existente e acessível
+            - O tipo MIME deve corresponder ao tipo real do arquivo para funcionamento adequado
+            - Arquivos com mesmo nome na mesma pasta não são sobrescritos, são duplicados
         """
         try:
+            # Validação dos parâmetros usando Pydantic para garantir tipos corretos
             UploadValidator(
                 folder_id=folder_id, name=name, file_path=file_path, mimetype=mimetype
             )
@@ -149,92 +337,166 @@ class GoogleDrive:
                 e.errors(),
             )
 
+        # Metadados do arquivo: nome e pasta de destino no Google Drive
         file_metadata = {"name": name, "parents": [folder_id]}
+        
+        # Verifica se o arquivo existe no sistema local antes de tentar upload
         if not os.path.exists(file_path):
-            return {
-                "success": False,
-                "result": None,
-                "error": "Diretório ou arquivo não encontrado",
-            }
+            return None  # Retorna None se arquivo não encontrado
 
         try:
+            # Configura o objeto de mídia para upload com suporte a resumo
             media = MediaFileUpload(file_path, mimetype=mimetype, resumable=True)
+            
+            # Executa o upload do arquivo para o Google Drive
             file = (
                 self.service.files()
                 .create(
-                    body=file_metadata,
-                    media_body=media,
-                    fields="id",
-                    supportsAllDrives=True,
+                    body=file_metadata,  # Metadados (nome, pasta pai)
+                    media_body=media,    # Conteúdo do arquivo
+                    fields="id",        # Campos a retornar (apenas ID para eficiência)
+                    supportsAllDrives=True,  # Suporte a drives compartilhados
                 )
                 .execute()
             )
 
+            # Retorna informações do arquivo carregado em formato padronizado
             return {"success": True, "result": file}
         except Exception as e:
-
+            # Em caso de erro, retorna informações do erro em formato padronizado
             return {"success": False, "result": None, "error": str(e)}
 
-    def _validate_folder_existence(self, folder: str, id_folder: str):
+    def _validate_folder_existence(self, folder: str, id_folder: str) -> Optional[Dict[str, Any]]:
         """
-        Verifica a existência de uma pasta no Google Drive.
+        Verifica se uma pasta específica existe dentro de uma pasta pai no Google Drive.
+        
+        Este método privado busca por uma pasta com nome específico dentro de uma pasta
+        pai identificada por seu ID. É usado internamente para evitar duplicação de
+        pastas antes de criar novas.
+        
         Args:
-            folder (str): O nome da pasta a ser verificada.
-            id_folder (str): O ID da pasta pai.
+            folder (str): Nome exato da pasta a ser verificada.
+                Exemplo: "Documentos 2025", "Relatórios Mensais"
+            id_folder (str): ID da pasta pai onde buscar.
+                Formato típico: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+        
         Returns:
-            dict or None: Um dicionário contendo as informações da pasta se ela existir, caso contrário, retorna None.
+            Optional[Dict[str, Any]]:
+                - Dicionário com informações da pasta se encontrada:
+                  {"id": "pasta_id", "name": "nome_pasta", "mimeType": "application/vnd.google-apps.folder"}
+                - None se a pasta não for encontrada na pasta pai
+        
         Raises:
-            ValueError: Se ocorrer algum erro durante a busca pela pasta.
+            ValueError: Se ocorrer erro durante a busca pela pasta.
+                Pode indicar problemas de conectividade, permissões ou IDs inválidos.
+        
+        Note:
+            - Este é um método privado (prefixo _) usado internamente pela classe
+            - A busca é case-sensitive (sensível a maiúsculas/minúsculas)
+            - Apenas pastas não movidas para lixeira são consideradas
+            - Suporta drives compartilhados da organização
+        
+        Examples:
+            >>> # Busca pasta "Relatórios" dentro da pasta pai
+            >>> pasta = self._validate_folder_existence("Relatórios", "parent_folder_id")
+            >>> if pasta:
+            ...     print(f"Pasta encontrada: {pasta['id']}")
+            ... else:
+            ...     print("Pasta não existe")
         """
-
+        
+        # Query para buscar itens na pasta pai que não estão na lixeira
         query = f"'{id_folder}' in parents and trashed=false"
 
         try:
-
+            # Executa busca na API do Google Drive
             response = (
                 self.service.files()
                 .list(
-                    q=query,
-                    spaces="drive",
-                    fields="nextPageToken, files(id, name, mimeType)",
-                    pageToken=None,
-                    includeItemsFromAllDrives=True,
-                    supportsAllDrives=True,
+                    q=query,  # Query de busca
+                    spaces="drive",  # Espaço de busca (drive principal)
+                    fields="nextPageToken, files(id, name, mimeType)",  # Campos retornados
+                    pageToken=None,  # Token de paginação (primeira página)
+                    includeItemsFromAllDrives=True,  # Incluir drives compartilhados
+                    supportsAllDrives=True,  # Suporte a drives compartilhados
                 )
                 .execute()
             )
 
+            # Extrai lista de arquivos/pastas da resposta
             items = response.get("files", [])
 
+            # Procura por pasta com nome específico
             for item in items:
-
+                # Verifica se é uma pasta (tipo MIME específico) e nome corresponde
                 if (
                     item["mimeType"] == "application/vnd.google-apps.folder"
                     and item["name"] == folder
                 ):
+                    return item  # Retorna informações da pasta encontrada
 
-                    return item
-
-            return None
+            return None  # Pasta não encontrada
 
         except Exception as e:
-
-            raise ValueError(f"Erro tentando procurar pela pasta:{e}")
+            # Lança erro com contexto específico sobre a falha na busca
+            raise ValueError(f"Erro tentando procurar pela pasta: {e}")
 
     def create_folder(
         self, name: str, parent_folder_id: str, validate_existence: bool = False
-    ):
+    ) -> Dict[str, Any]:
         """
-        Cria uma pasta no Google Drive dentro de uma pasta existente.
+        Cria uma nova pasta no Google Drive dentro de uma pasta pai especificada.
+
+        Este método permite criar pastas no Google Drive com opção de verificar
+        se a pasta já existe antes da criação. É útil para organizar arquivos
+        em estruturas hierárquicas de pastas.
 
         Args:
             name (str): Nome da pasta a ser criada.
-            parent_folder_id (int): ID da pasta pai onde a nova pasta será criada.
-            validate_existence (bool): Se True, verifica se a pasta já existe antes de criá-la. Defaults to False.
+                Exemplo: "Relatórios 2025", "Documentos Importantes"
+            parent_folder_id (str): ID da pasta pai onde a nova pasta será criada.
+                Formato típico: "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+                Use "root" para criar na raiz do drive
+            validate_existence (bool, optional): Se True, verifica se a pasta já existe
+                antes de tentar criar uma nova. Se a pasta existir, retorna suas
+                informações ao invés de criar duplicata. Padrão: False.
+
         Returns:
-            str: ID da pasta criada.
+            Dict[str, Any]: Dicionário padronizado com resultado da operação:
+                - success (bool): True se operação bem-sucedida, False caso contrário
+                - result (Dict[str, Any] | None): Informações da pasta criada/encontrada
+                  incluindo ID, nome e outros metadados
+                - error (str | None): Mensagem de erro se success=False
+
+        Raises:
+            ValueError: Se os parâmetros de entrada falharem na validação do Pydantic.
+                Inclui detalhes sobre quais campos são inválidos.
+
+        Examples:
+            >>> # Criar pasta sem verificar existência
+            >>> resultado = drive.create_folder(
+            ...     name="Nova Pasta",
+            ...     parent_folder_id="1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
+            ... )
+            >>> if resultado["success"]:
+            ...     print(f"Pasta criada com ID: {resultado['result']['id']}")
+
+            >>> # Criar pasta verificando se já existe
+            >>> resultado = drive.create_folder(
+            ...     name="Documentos",
+            ...     parent_folder_id="root",
+            ...     validate_existence=True
+            ... )
+            >>> print(f"Status: {resultado['success']}")
+
+        Note:
+            - Se validate_existence=True e a pasta existir, não será criada duplicata
+            - Nomes de pastas são case-sensitive no Google Drive
+            - A pasta pai deve existir e ser acessível com as credenciais atuais
+            - Suporta drives compartilhados da organização
         """
         try:
+            # Validação dos parâmetros usando Pydantic
             CreateFolderValidator(
                 name=name,
                 parent_folder_id=parent_folder_id,
@@ -242,33 +504,41 @@ class GoogleDrive:
             )
         except ValidationError as e:
             raise ValueError(
-                "Erro na validação dos dados de input da inicialização da instância:",
+                "Erro na validação dos dados de input da criação da pasta:",
                 e.errors(),
             )
 
         status_existence = None
 
+        # Verifica existência da pasta se solicitado
         if validate_existence:
-
             status_existence = self._validate_folder_existence(name, parent_folder_id)
 
+        # Cria pasta apenas se não existir (ou se verificação não foi solicitada)
         if status_existence is None:
-
             try:
+                # Metadados da nova pasta
                 folder_metadata = {
                     "name": name,
                     "parents": [parent_folder_id],
-                    "mimeType": "application/vnd.google-apps.folder",
+                    "mimeType": "application/vnd.google-apps.folder",  # Tipo MIME para pastas
                 }
+                
+                # Executa criação da pasta via API
                 folder = (
                     self.service.files()
-                    .create(body=folder_metadata, fields="id", supportsAllDrives=True)
+                    .create(
+                        body=folder_metadata, 
+                        fields="id", 
+                        supportsAllDrives=True  # Suporte a drives compartilhados
+                    )
                     .execute()
                 )
                 return {"success": True, "result": folder}
             except Exception as e:
                 return {"success": False, "result": None, "error": str(e)}
 
+        # Retorna pasta existente se encontrada
         return {"success": True, "result": status_existence}
 
     def list_items_folder(
@@ -276,46 +546,104 @@ class GoogleDrive:
         query: str = "",
         spaces: str = "drive",
         fields: str = "nextPageToken, files(id, name)",
-    ):
+    ) -> Dict[str, Any]:
         """
-        Lista os arquivos e pastas no Google Drive com base nos critérios fornecidos.
+        Lista arquivos e pastas no Google Drive com base em critérios de busca especificados.
+
+        Este método permite buscar e listar conteúdos do Google Drive usando queries
+        personalizadas. Suporta busca em drives pessoais e compartilhados, com
+        controle sobre quais campos são retornados para otimizar performance.
 
         Args:
-            query (str, optional): Critério de busca para os arquivos ou pastas no Google Drive.
-                                Consulte https://developers.google.com/drive/api/v3/ref-search-terms.
-                                Defaults to "".
-                                exemplo: query = 'ID_DA_PASTA_NO_GOOGLE_DRIVE' in parents and trashed=false"
-            spaces (str, optional): Especifica os locais de armazenamento a serem consultados. Pode ser 'drive',
-                                    'appDataFolder', ou 'photos'. Defaults to 'drive'.
-            fields (str, optional): Campos a serem retornados na resposta. Consulte a documentação para os campos disponíveis.
-                                    Defaults to "nextPageToken, files(id, name)".
+            query (str, optional): Critério de busca para filtrar arquivos e pastas.
+                Padrão: "" (lista todos os itens acessíveis).
+                Exemplos de queries:
+                - "'1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms' in parents and trashed=false"
+                  (itens em pasta específica, não na lixeira)
+                - "name contains 'relatório'" (arquivos com 'relatório' no nome)
+                - "mimeType='application/pdf'" (apenas arquivos PDF)
+                - "modifiedTime > '2025-01-01T00:00:00'" (modificados após data)
+                Consulte: https://developers.google.com/drive/api/v3/ref-search-terms
+
+            spaces (str, optional): Especifica locais de armazenamento para consulta.
+                Padrão: "drive".
+                Opções disponíveis:
+                - "drive": Drive principal do usuário
+                - "appDataFolder": Pasta de dados da aplicação
+                - "photos": Google Fotos (se aplicável)
+
+            fields (str, optional): Campos a serem retornados na resposta da API.
+                Padrão: "nextPageToken, files(id, name)".
+                Exemplos de campos:
+                - "files(id, name, size, modifiedTime)" (informações básicas + tamanho/data)
+                - "files(id, name, mimeType, parents)" (inclui tipo MIME e pastas pai)
+                - "nextPageToken, files(*)" (todos os campos disponíveis)
+                Consulte: https://developers.google.com/drive/api/v3/reference/files
 
         Returns:
-            dict: Dicionário contendo o resultado da busca.
+            Dict[str, Any]: Dicionário padronizado com resultado da operação:
+                - success (bool): True se operação bem-sucedida, False caso contrário
+                - result (Dict[str, Any] | None): Dados retornados da API se success=True:
+                  * files (List[Dict]): Lista de arquivos/pastas encontrados
+                  * nextPageToken (str): Token para próxima página (se houver)
+                - error (str | None): Mensagem de erro se success=False
+
+        Raises:
+            ValueError: Se os parâmetros de entrada falharem na validação do Pydantic.
+
+        Examples:
+            >>> # Listar todos os itens na raiz do drive
+            >>> resultado = drive.list_items_folder()
+            >>> if resultado["success"]:
+            ...     arquivos = resultado["result"]["files"]
+            ...     for arquivo in arquivos:
+            ...         print(f"Nome: {arquivo['name']}, ID: {arquivo['id']}")
+
+            >>> # Listar apenas PDFs em uma pasta específica
+            >>> resultado = drive.list_items_folder(
+            ...     query="'pasta_id' in parents and mimeType='application/pdf'",
+            ...     fields="files(id, name, size, modifiedTime)"
+            ... )
+
+            >>> # Buscar arquivos por nome
+            >>> resultado = drive.list_items_folder(
+            ...     query="name contains 'contrato' and trashed=false"
+            ... )
+
+        Note:
+            - Resultados são limitados pelo page_size configurado na inicialização
+            - Use nextPageToken para navegar entre páginas de resultados extensos
+            - Queries são case-insensitive para busca por nome
+            - Suporta drives compartilhados automaticamente
         """
         try:
+            # Validação dos parâmetros usando Pydantic
             ListFolderValidator(query=query, fields=fields, spaces=spaces)
         except ValidationError as e:
             raise ValueError(
                 "Erro na validação dos dados de input da lista:", e.errors()
             )
+            
         try:
+            # Executa consulta na API do Google Drive
             results = (
                 self.service.files()
                 .list(
-                    q=query,
-                    spaces=spaces,
-                    pageSize=self.page_size,
-                    fields=fields,
-                    supportsAllDrives=True,
-                    includeItemsFromAllDrives=True,
+                    q=query,  # Query de busca
+                    spaces=spaces,  # Espaços de armazenamento
+                    pageSize=self.page_size,  # Limite de itens por página
+                    fields=fields,  # Campos a retornar
+                    supportsAllDrives=True,  # Suporte a drives compartilhados
+                    includeItemsFromAllDrives=True,  # Incluir itens de drives compartilhados
                 )
                 .execute()
             )
             return {"success": True, "result": results}
         except HttpError as hr:
+            # Erro específico da API HTTP (ex: 403 Forbidden, 404 Not Found)
             return {"success": False, "result": None, "error": str(hr)}
         except Exception as e:
+            # Outros erros gerais (rede, parsing, etc.)
             return {"success": False, "result": None, "error": str(e)}
 
     def download_google_files(self, file: str, mimeType: str, path: str):
@@ -442,4 +770,221 @@ class GoogleDrive:
             self.service.files().delete(fileId=id_file, supportsAllDrives=True).execute()
             return {"success": True}
         except Exception as e:
-            return {"success": False, "error": str(e)}
+            return {"success": False, "error": str(e)}
+
+    def _find_file_in_folder_by_name(self, parent_folder_id: str, name: str) -> Optional[dict]:
+        """
+        Retorna o primeiro arquivo (não excluído) com 'name' dentro de 'parent_folder_id',
+        ou None se não existir.
+        """
+        # Escapa aspas simples no nome para a query
+        safe_name = name.replace("'", r"\'")
+        q = (
+            f"'{parent_folder_id}' in parents and "
+            f"name = '{safe_name}' and "
+            f"trashed = false"
+        )
+        try:
+            resp = (
+                self.service.files()
+                .list(
+                    q=q,
+                    spaces="drive",
+                    pageSize=1,
+                    fields="files(id, name, mimeType, size, webViewLink, parents)",
+                    supportsAllDrives=True,
+                    includeItemsFromAllDrives=True,
+                )
+                .execute()
+            )
+            files = resp.get("files", [])
+            return files[0] if files else None
+        except Exception as e:
+            # Padroniza retorno de erro
+            return None
+
+    def ensure_folder(self, parent_folder_id: str, name: str) -> str:
+        """
+        Usa o método create_folder(validate_existence=True) para retornar o ID de 'name'
+        dentro de 'parent_folder_id', criando se não existir.
+        """
+        resp = self.create_folder(
+            name=name,
+            parent_folder_id=parent_folder_id,
+            validate_existence=True,
+        )
+
+        if not resp or not resp.get("success"):
+            raise RuntimeError(f"Falha ao garantir pasta '{name}': {resp}")
+        # A classe retorna em "result" um dict com ao menos "id"
+        folder = resp["result"]
+        folder_id = folder.get("id")
+        if not folder_id:
+            # Algumas respostas podem ser {'success': True, 'result': {'id': '...'}} ou já o objeto
+            # Se por algum motivo vier diferente, trate aqui
+            raise RuntimeError(f"Resposta inesperada ao criar/buscar pasta: {folder}")
+        return folder_id
+
+    def ensure_path(self, path: str, parent_folder_id: str = "root") -> str:
+        """
+        Percorre/cria cada nível de 'path' dentro de 'parent_folder_id'.
+        Retorna o ID da última pasta.
+        """
+        current_parent = parent_folder_id
+        for part in [p for p in path.split("/") if p.strip()]:
+            current_parent = self.ensure_folder(current_parent, part)
+        return current_parent
+
+    def upload_pdf_to_drive_path(
+        self,
+        local_pdf_path: str,
+        drive_folder_path: str,
+        parent_folder_id: str = "root",
+        rename_as: Optional[str] = None,
+    ) -> dict:
+        """
+        - Garante a hierarquia 'drive_folder_path' (ex: "MeusPdfs/2025/09")
+        - Sobe o PDF com mimetype application/pdf
+        - Se rename_as for fornecido, usa esse nome no Drive (com .pdf); caso contrário, basename do arquivo local.
+
+        Retorna o dict padronizado da classe: {"success": True/False, "result": {...} | None, "error": str | None}
+        """
+        if not os.path.exists(local_pdf_path):
+            return {"success": False, "result": None, "error": f"Arquivo não encontrado: {local_pdf_path}"}
+
+        folder_id = self.ensure_path(drive_folder_path, parent_folder_id=parent_folder_id)
+
+        # nome do arquivo no Drive
+        base = os.path.basename(local_pdf_path)
+        if rename_as:
+            name = rename_as if rename_as.lower().endswith(".pdf") else f"{rename_as}.pdf"
+        else:
+            name = base
+
+        # mimetype do PDF
+        mimetype = "application/pdf"
+
+        return self.upload(
+            folder_id=folder_id,
+            name=name,
+            file_path=local_pdf_path,
+            mimetype=mimetype,
+        )
+
+    def _gdrive_upload_or_update_media(
+        self,
+        folder_id: str,
+        name: str,
+        mimetype: str,
+        file_handle: BytesIO,
+        overwrite: bool = True,
+    ) -> dict:
+        """
+        Se overwrite=True, procura por (name, folder_id) e:
+        - se existir: faz update do conteúdo (mantém o mesmo fileId)
+        - se não existir: cria
+        Se overwrite=False, sempre cria (comportamento atual).
+        """
+        try:
+            media = MediaIoBaseUpload(
+                file_handle,
+                mimetype=mimetype,
+                resumable=True,
+                chunksize=1024 * 1024,
+            )
+            if overwrite:
+                existing = self._find_file_in_folder_by_name(folder_id, name)
+                if existing:
+                    file_id = existing["id"]
+                    file = (
+                        self.service.files()
+                        .update(
+                            fileId=file_id,
+                            media_body=media,
+                            fields="id, name, mimeType, size, webViewLink, parents",
+                            supportsAllDrives=True,
+                        )
+                        .execute()
+                    )
+                    return {"success": True, "result": file, "error": None}
+
+            # cria se não houver existente ou overwrite=False
+            file_metadata = {"name": name, "parents": [folder_id]}
+            file = (
+                self.service.files()
+                .create(
+                    body=file_metadata,
+                    media_body=media,
+                    fields="id, name, mimeType, size, webViewLink, parents",
+                    supportsAllDrives=True,
+                )
+                .execute()
+            )
+            return {"success": True, "result": file, "error": None}
+        except Exception as e:
+            return {"success": False, "result": None, "error": str(e)}
+
+    def upload_pdf_bytes_to_drive_path(
+        self,
+        content: bytes,
+        drive_folder_path: str,
+        parent_folder_id: str = "root",
+        name: str | None = None,
+        overwrite: bool = True,  # << novo parâmetro
+    ) -> dict:
+        """
+        Recebe o conteúdo do PDF em bytes e faz upload para a pasta indicada (criando hierarquia se necessário).
+        """
+        if not isinstance(content, (bytes, bytearray)) or not content:
+            return {"success": False, "result": None, "error": "Parâmetro 'content' vazio ou inválido."}
+        folder_id = self.ensure_path(drive_folder_path, parent_folder_id=parent_folder_id)
+
+        # Nome do arquivo no Drive
+        final_name = (name or "arquivo.pdf")
+        if not final_name.lower().endswith(".pdf"):
+            final_name += ".pdf"
+
+        fh = BytesIO(content)
+        #return self._gdrive_upload_media(folder_id=folder_id, name=final_name, mimetype="application/pdf", file_handle=fh)
+        return self._gdrive_upload_or_update_media(
+            folder_id=folder_id,
+            name=final_name,
+            mimetype="application/pdf",
+            file_handle=fh,
+            overwrite=overwrite,
+        )
+
+    def upload_pdf_base64_to_drive_path(
+        self,
+        b64_content: str,
+        drive_folder_path: str,
+        parent_folder_id: str = "root",
+        name: str | None = None,
+        strict: bool = True,
+        overwrite: bool = True,  # << novo parâmetro
+    ) -> dict:
+        """
+        Recebe o conteúdo do PDF como string Base64 e faz upload para a pasta indicada (criando hierarquia se necessário).
+        - strict=True usa validação estrita no b64 (recomendado).
+        - aceita strings com ou sem prefixo data URL (ex.: 'data:application/pdf;base64,...').
+        """
+        if not isinstance(b64_content, str) or not b64_content.strip():
+            return {"success": False, "result": None, "error": "Parâmetro 'b64_content' vazio ou inválido."}
+
+        # Remove prefixo data URL se existir
+        # ex.: data:application/pdf;base64,JVBERi0xLjQKJ...
+        if ";base64," in b64_content:
+            b64_content = b64_content.split(";base64,", 1)[1]
+
+        try:
+            content = base64.b64decode(b64_content, validate=strict)
+        except Exception as e:
+            return {"success": False, "result": None, "error": f"Base64 inválido: {e}"}
+
+        return self.upload_pdf_bytes_to_drive_path(
+            content=content,
+            drive_folder_path=drive_folder_path,
+            parent_folder_id=parent_folder_id,
+            name=name,
+            overwrite=overwrite,
+        )

{csc_cia_stne-0.1.16.dist-info → csc_cia_stne-0.1.17.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: csc_cia_stne
-Version: 0.1.16
+Version: 0.1.17
 Summary: Biblioteca do time CSC-CIA utilizada no desenvolvimento de RPAs
 License: MIT
 Keywords: karavela,csc,cia,stone,rpa,botcity,stne

{csc_cia_stne-0.1.16.dist-info → csc_cia_stne-0.1.17.dist-info}/RECORD

@@ -5,7 +5,7 @@ csc_cia_stne/email.py,sha256=y4xyPAe6_Mga5Wf6qAsDzYgn0f-zf2KshfItlWe58z8,8481
 csc_cia_stne/ftp.py,sha256=M9WCaq2hm56jGyszNaPinliFaZS0BNrT7VrVPMjkMg4,10988
 csc_cia_stne/gcp_bigquery.py,sha256=foq8azvvv_f7uikMDslX9RcUIrx7RAS-Sn0AGW0QFQc,7231
 csc_cia_stne/gcp_bucket.py,sha256=vMALWiW7IoBCuJAR8bUCpOV6BuBzI9AhRRk3b72OdMk,11515
-csc_cia_stne/google_drive.py,sha256=j1fvHpgU76_VqCtSEe05JXLOgNwNNfrP6GRKq6eU4b4,17074
+csc_cia_stne/google_drive.py,sha256=sfq2arBYrv8OLIfRJTnj067EPbem2gofwIfpbqJ475o,44500
 csc_cia_stne/karavela.py,sha256=jJCYX43D49gGuzmwwK6bN9XVnv2dXdp9iHnnV5H1LMQ,4794
 csc_cia_stne/logger_json.py,sha256=CXxSCOFGMymDi8XE9SKnPKjW4D0wJLqDLnxqePS26i8,3187
 csc_cia_stne/logger_rich.py,sha256=fklgkBb4rblKQd7YZ3q-eWfhGg9eflO2k2-z4pGh_yo,5201
@@ -38,8 +38,8 @@ csc_cia_stne/utilitarios/web_screen/__init__.py,sha256=5QcOPXKd95SvP2DoZiHS0gaU6
 csc_cia_stne/utilitarios/web_screen/web_screen_abstract.py,sha256=PjL8Vgfj_JdKidia7RFyCkro3avYLQu4RZRos41sh3w,3241
 csc_cia_stne/utilitarios/web_screen/web_screen_botcity.py,sha256=Xi5YJjl2pcxlX3OimqcBWRNXZEpAE7asyUjDJ4Oho5U,12297
 csc_cia_stne/utilitarios/web_screen/web_screen_selenium.py,sha256=JLIcPJE9ZX3Pd6zG6oTRMqqUAY063UzLY3ReRlxmiSM,15581
-csc_cia_stne-0.1.16.dist-info/licenses/LICENCE,sha256=LPGMtgKki2C3KEZP7hDhA1HBrlq5JCHkIeStUCLEMx4,1073
-csc_cia_stne-0.1.16.dist-info/METADATA,sha256=Namt43MLWsc_Ebf_VhYyrjRLBkUVc8XGDi7HsYzYfJ8,1464
-csc_cia_stne-0.1.16.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-csc_cia_stne-0.1.16.dist-info/top_level.txt,sha256=ldo7GVv3tQx5KJvwBzdZzzQmjPys2NDVVn1rv0BOF2Q,13
-csc_cia_stne-0.1.16.dist-info/RECORD,,
+csc_cia_stne-0.1.17.dist-info/licenses/LICENCE,sha256=LPGMtgKki2C3KEZP7hDhA1HBrlq5JCHkIeStUCLEMx4,1073
+csc_cia_stne-0.1.17.dist-info/METADATA,sha256=sJlZR_-JjU01PX7qUYHYGYRFf88JRd0S0mScBwG64vQ,1464
+csc_cia_stne-0.1.17.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+csc_cia_stne-0.1.17.dist-info/top_level.txt,sha256=ldo7GVv3tQx5KJvwBzdZzzQmjPys2NDVVn1rv0BOF2Q,13
+csc_cia_stne-0.1.17.dist-info/RECORD,,