rpa-suite 1.4.5__py3-none-any.whl → 1.4.8__py3-none-any.whl

rpa_suite/__init__.py

@@ -1,4 +1,5 @@
 # rpa_suite/__init__.py
+
 """
     RPA Suite is a Python module that provides a set of tools for process automation.
     
@@ -26,7 +27,7 @@
         ``printer``: Functions for formatted output
         ``regex``: Operations with regular expressions
         ``validate``: Data validation functions
-        ``Browser``: Object Browser automation functions
+        ``Browser``: Object Browser automation functions (neeeds Selenium and Webdriver_Manager)
 
     pt-br
     -----
@@ -56,8 +57,9 @@
         ``printer``: Funções para output formatado
         ``regex``: Operações com expressões regulares
         ``validate``: Funções de validação de dados
-        ``Browser``: Objeto de Automação de Navegadores
+        ``Browser``: Objeto de Automação de Navegadores (necessario Selenium e Webdriver_Manager)
 """
 
+# allows importing the rpa_suite module without the package name
 from .suite import rpa
 rpa

rpa_suite/core/__init__.py

@@ -3,9 +3,12 @@
 """
 The Core module is where we can import all Sub-Objects used by the rpa_suite module separately, categorized by their respective classes based on functionality. However, we can also use them through the main rpa object using the following syntax:
 >>> from rpa_suite import rpa
->>> rpa.clock.wait_for_exec()
+>>> rpa.clock.wait_for_exec(foo)
 >>> rpa.file.screen_shot() ...
-among others.
+or
+>>> from rpa_suite.core.clock import Clock
+>>> clock = Clock()
+>>> clock.wait_for_exec()
 
 pt-br
 ----------
@@ -13,9 +16,13 @@ O módulo Core é de onde podemos importar todos os Sub-Objetos usados pelo mód
 >>> from rpa_suite import rpa
 >>> rpa.clock.wait_for_exec()
 >>> rpa.file.screen_shot() ...
-entre outros.
+ou
+>>> from rpa_suite.core.clock import Clock
+>>> clock = Clock()
+>>> clock.wait_for_exec(foo)
 
 """
+
 from .clock import Clock
 from .date import Date
 from .dir import Directory
@@ -25,4 +32,14 @@ from .log import Log
 from .print import Print
 from .regex import Regex
 from .validate import Validate
-from .browser import Browser
+from .parallel import ParallelRunner
+
+
+
+# On this case, we are importing the Browser class only if the selenium and webdriver_manager modules are installed.
+# This is useful to avoid unnecessary imports and dependencies if the user does not need the Browser functionality.
+import importlib.util
+
+# from .browser import Browser
+if importlib.util.find_spec("selenium") and importlib.util.find_spec("webdriver_manager"):
+    from .browser import Browser

rpa_suite/core/browser.py

@@ -1,28 +1,92 @@
-# default import
-import os, requests
+# rpa_suite/core/browser.py
 
-# imports
+# imports internal
 from rpa_suite.functions._printer import error_print, alert_print, success_print
 
+# imports external
 from selenium import webdriver
 from selenium.webdriver.common.by import By
 from selenium.webdriver.chrome.options import Options
 from selenium.webdriver.support.ui import WebDriverWait
 from selenium.webdriver.support import expected_conditions as EC
 from webdriver_manager.chrome import ChromeDriverManager
+
+# imports third-party
 from time import sleep
+import os, requests
+
 
-class Browser():
 
+class Browser():
+    
     """
-    WIP ...
+    Browser Object for Automation (Work in Progress)
+    This class provides an interface for automating browser interactions using 
+    Google Chrome with a debugging port. It includes methods for starting, 
+    configuring, navigating, and interacting with the browser. The implementation 
+    is still under development and may require further enhancements.
+    
+    Attributes:
+        driver: The WebDriver instance used to control the browser.
+        port (int): The debugging port used to connect to the browser. Default is 9393.
+        path_driver (str): The path to the ChromeDriver executable.
+        
+    Methods:
+        __init__(port: int = 9393, close_all_chrome_on_this_port: bool = False):
+            Initializes the Browser object with the specified debugging port and 
+            optionally closes all Chrome instances running on the same port.
+        configure_browser() -> None:
+            Configures the browser with debugging options and initializes the WebDriver.
+        start_browser(close_chrome_on_this_port: bool = True, display_message: bool = False):
+            Starts the Chrome browser with the specified debugging port and initializes 
+            the WebDriver.
+        find_ele(value, by=By.XPATH, timeout=12, display_message=True):
+            Finds a single element on the page using the specified locator strategy.
+        get(url: str, display_message: bool = False):
+            Navigates the browser to the specified URL.
+        _close_all_chrome():
+            Closes all Chrome processes forcefully.
+        close_browser(display_message: bool = False):
+            Closes the browser instance and terminates the associated Chrome processes.
+    
+    pt-br
+    ----------
+    Objeto Browser para Automação (Em Desenvolvimento)
+    Esta classe fornece uma interface para automação de interações com o navegador 
+    Google Chrome utilizando uma porta de depuração. Inclui métodos para iniciar, 
+    configurar, navegar e interagir com o navegador. A implementação ainda está em 
+    desenvolvimento e pode requerer melhorias adicionais.
+    
+    Atributos:
+        driver: A instância do WebDriver usada para controlar o navegador.
+        port (int): A porta de depuração usada para conectar ao navegador. O padrão é 9393.
+        path_driver (str): O caminho para o executável do ChromeDriver.
+        
+    Métodos:
+        __init__(port: int = 9393, close_all_chrome_on_this_port: bool = False):
+            Inicializa o objeto Browser com a porta de depuração especificada e, 
+            opcionalmente, fecha todas as instâncias do Chrome que estão sendo executadas 
+            na mesma porta.
+        configure_browser() -> None:
+            Configura o navegador com opções de depuração e inicializa o WebDriver.
+        start_browser(close_chrome_on_this_port: bool = True, display_message: bool = False):
+            Inicia o navegador Chrome com a porta de depuração especificada e inicializa 
+            o WebDriver.
+        find_ele(value, by=By.XPATH, timeout=12, display_message=True):
+            Localiza um único elemento na página usando a estratégia de localização especificada.
+        get(url: str, display_message: bool = False):
+            Navega o navegador para a URL especificada.
+        _close_all_chrome():
+            Fecha todos os processos do Chrome de forma forçada.
+        close_browser(display_message: bool = False):
+            Fecha a instância do navegador e termina os processos associados do Chrome.
     """
 
     driver: None
     port: int = None
     path_driver = None
     
-    def __init__(self, port: int = 9393, close_all_chrome_on_this_port: bool = True):
+    def __init__(self, port: int = 9393, close_all_chrome_on_this_port: bool = False):
         self.port = port
         self.path_driver = ChromeDriverManager().install()
 
@@ -30,6 +94,15 @@ class Browser():
         ...
 
     def configure_browser(self) -> None:
+        """
+        Configures the browser instance with specified options and initializes the WebDriver.
+        This method sets up the browser with debugging options, maximized window, and disables notifications.
+        It also verifies the existence of the ChromeDriver executable at the specified path before creating
+        the WebDriver instance.
+        Raises:
+            FileNotFoundError: If the specified path to the ChromeDriver executable does not exist.
+            Exception: For any other errors encountered during the browser configuration process.
+        """
         
         try:
             # Use the absolute path from comment
@@ -57,6 +130,20 @@ class Browser():
             error_print(f'Erro durante a função: {self.configure_browser.__name__}! Error: {str(e)}.')
 
     def start_browser(self, close_chrome_on_this_port: bool = True, display_message: bool = False):
+        """
+        Starts a Chrome browser instance with remote debugging enabled.
+        Args:
+            close_chrome_on_this_port (bool): If True, closes any existing Chrome instance using the specified debugging port before starting a new one. Defaults to True.
+            display_message (bool): If True, displays a success message upon successfully starting the browser. Defaults to False.
+        Raises:
+            Exception: If an error occurs while starting the browser or connecting to the debugging port.
+        Behavior:
+            - Closes any existing Chrome instance on the specified debugging port if `close_chrome_on_this_port` is True.
+            - Launches Chrome with the specified debugging port and user data directory.
+            - Waits until Chrome is fully initialized and accessible via the debugging port.
+            - Configures the browser instance using the `configure_browser` method.
+            - Optionally displays a success message if `display_message` is True.
+        """
         
         try:
             if close_chrome_on_this_port: self.close_browser()
@@ -83,7 +170,24 @@ class Browser():
             error_print(f'Erro ao iniciar navegador: {str(e)}.')
 
 
-    def find_ele(self, value, by=By.XPATH, timeout=12, display_message=True):
+    def find_ele(self, value: str, by:By=By.XPATH, timeout=12, display_message=True):
+        """
+        Locate and return a web element on the page using the specified locator strategy.
+        Args:
+            value (str): The locator value to identify the web element.
+            by (selenium.webdriver.common.by.By, optional): The locator strategy to use. 
+                Defaults to By.XPATH.
+            timeout (int, optional): The maximum time to wait for the element to appear, in seconds. 
+                Defaults to 12.
+            display_message (bool, optional): Whether to display an error message if the element 
+                is not found. Defaults to True.
+        Returns:
+            selenium.webdriver.remote.webelement.WebElement: The located web element if found.
+            None: If the element is not found or an exception occurs.
+        Raises:
+            Exception: Propagates any exception encountered during the element search if 
+                `display_message` is set to False.
+        """
         
         try:
             sleep(2)
@@ -103,6 +207,14 @@ class Browser():
     
     # navigate
     def get(self, url: str, display_message: bool = False):
+        """
+        Navigates the browser to the specified URL.
+        Args:
+            url (str): The URL to navigate to.
+            display_message (bool, optional): If True, displays a success message upon navigation. Defaults to False.
+        Raises:
+            Exception: If an error occurs while navigating to the URL, it logs the error message.
+        """
         
         try:
             self.driver.get(url)
@@ -112,7 +224,14 @@ class Browser():
             error_print(f'Erro ao navegar para a URL: {url}. Error: {str(e)}.')
 
 
-    def _close_all_chrome(self):
+    def _close_all_browsers(self):
+        """
+        Forcefully closes all instances of Google Chrome running on the system.
+        This method uses the `taskkill` command to terminate all processes with the name
+        "chrome.exe". Any errors during the execution of the command are silently ignored.
+        Note:
+            This method is specific to Windows operating systems and will not work on other platforms.
+        """
 
         try:
             os.system('taskkill /F /IM chrome.exe >nul 2>&1')
@@ -121,6 +240,24 @@ class Browser():
 
 
     def close_browser(self, display_message: bool = False):
+        """
+        Fecha o navegador controlado pelo Selenium e encerra os processos relacionados ao Chrome.
+        Este método tenta fechar o navegador de forma ordenada utilizando os métodos `close` e `quit` do Selenium.
+        Caso esses métodos falhem, ele força o encerramento do processo do Chrome associado à porta de depuração remota.
+        Em último caso, pode encerrar todos os processos do Chrome relacionados à porta especificada.
+        Args:
+            display_message (bool): Indica se mensagens de status devem ser exibidas durante o processo de fechamento.
+        Comportamento:
+            - Tenta fechar o navegador utilizando `self.driver.close()` e `self.driver.quit()`.
+            - Aguarda um momento para liberar o processo.
+            - Força o encerramento do processo do Chrome associado à porta de depuração remota.
+            - Verifica se o processo foi encerrado e tenta métodos mais agressivos, se necessário.
+            - Em caso de falha crítica, tenta encerrar todos os processos do Chrome relacionados à porta especificada.
+        Exceções:
+            - Captura e exibe mensagens de erro caso ocorra falha ao fechar o navegador.
+        Observação:
+            Use com cautela, especialmente o encerramento extremo, pois pode afetar outros processos do Chrome em execução.
+        """
         
         try:
             # Primeiro tenta fechar todas as janelas via Selenium

rpa_suite/core/clock.py

@@ -1,8 +1,12 @@
+# rpa_suite/core/clock.py
 
+# imports internal
+from rpa_suite.functions._printer import error_print, success_print
+
+# imports third-party
 import time
 from typing import Callable, Any
 from datetime import datetime as dt
-from rpa_suite.functions._printer import error_print, success_print
 from typing import Callable, Any
 
 

rpa_suite/core/date.py

@@ -1,9 +1,13 @@
-# /date.py
+# rpa_suite/core/date.py
 
+# imports internal
+from rpa_suite.functions._printer import error_print
+
+# imports third-party
 import datetime as dt
 from typing import Optional as Op
 from typing import Tuple
-from rpa_suite.functions._printer import error_print
+
 
 class Date():
     """

rpa_suite/core/dir.py

@@ -1,7 +1,12 @@
+# rpa_suite/core/dir.py
 
+# imports internal
+from rpa_suite.functions._printer import error_print, alert_print, success_print
+
+# imports third-party
 import os, shutil
 from typing import Union
-from rpa_suite.functions._printer import error_print, alert_print, success_print
+
 
 
 class Directory():

rpa_suite/core/email.py

@@ -1,13 +1,15 @@
-# /sender_smtp.py
+# rpa_suite/core/email.py
 
-import smtplib, os
+# imports internal
+from rpa_suite.functions._printer import alert_print, error_print, success_print
+
+# imports third-party
+import smtplib
 from email.mime.image import MIMEImage
 from email.mime.multipart import MIMEMultipart
 from email.mime.text import MIMEText
 from email.mime.base import MIMEBase
 from email import encoders
-from rpa_suite.functions._printer import alert_print, error_print, success_print
-from rpa_suite.core.validate import email_validator
 
 
 class Email():

rpa_suite/core/file.py

@@ -1,10 +1,19 @@
-import os, time
-from datetime import datetime
+# rpa_suite/core/file.py
+
+# imports internal
 from rpa_suite.functions._printer import error_print, success_print, alert_print
 from rpa_suite.functions.__create_ss_dir import __create_ss_dir as create_ss_dir
+
+# imports external
 from colorama import Fore
+
+# imports third-party
+import os, time
+from datetime import datetime
 from typing import Dict, List, Union
 
+
+
 class File():
     """
     Class that provides utilities for file management, including creation, deletion, and manipulation of files.
@@ -170,7 +179,7 @@ class File():
                 full_path_with_name = fr'{path_to_create}/{name_file}'
                 
             with open(full_path_with_name, 'w', encoding='utf-8') as file:
-                file.write('[T-BOT Crédit Simulation] running in realtime, waiting finish to new execution')
+                file.write('[RPA Suite] - Running Flag File')
             if display_message: success_print("Flag file created.")
 
         except Exception as e:

rpa_suite/core/log.py

@@ -1,6 +1,13 @@
-from typing import Optional as Op
+# rpa_suite/core/log.py
+
+# imports internal
 from rpa_suite.functions._printer import error_print, alert_print, success_print
+
+# imports external
 from loguru import logger
+
+# imports third-party
+from typing import Optional as Op
 import sys, os, inspect
 
 

rpa_suite/core/parallel.py

@@ -0,0 +1,193 @@
+# rpa_suite/core/parallel.py
+
+from multiprocessing import Process, Manager
+from typing import Any, Callable, Dict, Optional, TypeVar, Generic
+import time
+import traceback
+
+# Definir tipo genérico para o retorno da função
+T = TypeVar('T')
+
+class ParallelRunner(Generic[T]):
+    
+    """
+    Classe para executar funções em paralelo mantendo o fluxo principal da aplicação.
+    
+    Permite iniciar uma função em um processo separado e obter seu resultado posteriormente.
+    """
+    
+    def __init__(self):
+        """Inicializa o ParallelRunner."""
+        self._manager = Manager()
+        self._result_dict = self._manager.dict()
+        self._process = None
+        self._start_time = None
+
+    @staticmethod
+    def _execute_function(function, args, kwargs, result_dict):
+        """
+        Função estática que executa a função alvo e armazena o resultado.
+        Esta função precisa ser definida no nível do módulo para ser "picklable".
+        """
+        try:
+            # Executa a função do usuário com os argumentos fornecidos
+            result = function(*args, **kwargs)
+            
+            # Armazena o resultado no dicionário compartilhado
+            result_dict['status'] = 'success'
+            result_dict['result'] = result
+            
+            # Para debug
+            print(f"[Processo Filho] Resultado calculado: {result}")
+            print(f"[Processo Filho] Dicionário de resultados: {dict(result_dict)}")
+            
+        except Exception as e:
+            # Em caso de erro, armazena informações sobre o erro
+            result_dict['status'] = 'error'
+            result_dict['error'] = str(e)
+            result_dict['traceback'] = traceback.format_exc()
+            
+            # Para debug
+            print(f"[Processo Filho] Erro ocorrido: {str(e)}")
+        
+    def run(self, function: Callable[..., T], *args, **kwargs) -> 'ParallelRunner[T]':
+        """
+        Inicia a execução da função em um processo paralelo.
+        
+        Args:
+            function: Função a ser executada em paralelo
+            *args: Argumentos posicionais para a função
+            **kwargs: Argumentos nomeados para a função
+            
+        Returns:
+            self: Retorna a própria instância para permitir chamadas encadeadas
+        """
+        # Limpar resultado anterior, se houver
+        if self._result_dict:
+            self._result_dict.clear()
+        
+        # Configura valores iniciais no dicionário compartilhado
+        self._result_dict['status'] = 'running'
+        
+        # Inicia o processo com a função auxiliar estática
+        self._process = Process(
+            target=ParallelRunner._execute_function, 
+            args=(function, args, kwargs, self._result_dict)
+        )
+        self._process.daemon = True  # Processo filho termina quando o principal termina
+        self._process.start()
+        self._start_time = time.time()
+        
+        return self
+
+    def is_running(self) -> bool:
+        """
+        Verifica se o processo ainda está em execução.
+        
+        Returns:
+            bool: True se o processo ainda estiver em execução, False caso contrário
+        """
+        if self._process is None:
+            return False
+        return self._process.is_alive()
+    
+    def get_result(self, timeout: Optional[float] = None, terminate_on_timeout: bool = True) -> Dict[str, Any]:
+        """
+        Obtém o resultado da execução paralela.
+        
+        Args:
+            timeout: Tempo máximo (em segundos) para aguardar o término do processo
+                    None significa esperar indefinidamente
+            terminate_on_timeout: Se True, termina o processo caso o timeout seja atingido
+            
+        Returns:
+            Dict contendo:
+                - success: bool indicando se a operação foi bem-sucedida
+                - result: resultado da função (se bem-sucedida)
+                - error: mensagem de erro (se houver)
+                - traceback: stack trace completo (se houver erro)
+                - execution_time: tempo de execução em segundos
+                - terminated: True se o processo foi terminado por timeout
+        """
+        if self._process is None:
+            return {
+                'success': False, 
+                'error': 'Nenhum processo foi iniciado',
+                'execution_time': 0,
+                'terminated': False
+            }
+        
+        # Aguarda o processo terminar com tempo limite
+        self._process.join(timeout=timeout)
+        execution_time = time.time() - self._start_time
+        
+        # Preparamos o dicionário de resposta
+        result = {
+            'execution_time': execution_time,
+            'terminated': False
+        }
+        
+        # Debug - mostra o dicionário compartilhado
+        print(f"[Processo Principal] Dicionário compartilhado: {dict(self._result_dict)}")
+        
+        # Verifica se o processo terminou ou se atingiu o timeout
+        if self._process.is_alive():
+            if terminate_on_timeout:
+                self._process.terminate()
+                self._process.join(timeout=1)  # Pequeno timeout para garantir que o processo termine
+                result['terminated'] = True
+                result['success'] = False
+                result['error'] = f'Operação cancelada por timeout após {execution_time:.2f} segundos'
+            else:
+                result['success'] = False
+                result['error'] = f'Operação ainda em execução após {execution_time:.2f} segundos'
+        else:
+            # Processo terminou normalmente - verificamos o status
+            status = self._result_dict.get('status', 'unknown')
+            
+            if status == 'success':
+                result['success'] = True
+                # Garantimos que o resultado está sendo copiado corretamente
+                if 'result' in self._result_dict:
+                    result['result'] = self._result_dict['result']
+                else:
+                    result['success'] = False
+                    result['error'] = 'Resultado não encontrado no dicionário compartilhado'
+            else:
+                result['success'] = False
+                result['error'] = self._result_dict.get('error', 'Erro desconhecido')
+                if 'traceback' in self._result_dict:
+                    result['traceback'] = self._result_dict['traceback']
+        
+        # Finaliza o Manager se o processo terminou e não estamos mais esperando resultado
+        if not self._process.is_alive() and (result.get('success', False) or result.get('terminated', False)):
+            self._cleanup()
+        
+        return result
+    
+    def terminate(self) -> None:
+        """
+        Termina o processo em execução.
+        """
+        if self._process and self._process.is_alive():
+            self._process.terminate()
+            self._process.join(timeout=1)
+            self._cleanup()
+    
+    def _cleanup(self) -> None:
+        """
+        Limpa os recursos utilizados pelo processo.
+        """
+        if hasattr(self, '_manager') and self._manager is not None:
+            try:
+                self._manager.shutdown()
+            except Exception:
+                pass
+            self._manager = None
+        self._process = None
+
+    def __del__(self):
+        """
+        Destrutor da classe, garante que recursos sejam liberados.
+        """
+        self.terminate()

rpa_suite/core/print.py

@@ -1,8 +1,9 @@
+# rpa_suite/core/print.py
 
-# /printer.py
-
+# imports external
 from colorama import Fore
 
+
 # Windows bash colors
 class Colors():
     black     = f'{Fore.BLACK}'
@@ -17,6 +18,7 @@ class Colors():
     call_fn   = f'{Fore.LIGHTMAGENTA_EX}'
     retur_fn  = f'{Fore.LIGHTYELLOW_EX}'
 
+
 class Print():
     
     """

rpa_suite/core/regex.py

@@ -1,7 +1,12 @@
+# rpa_suite/core/regex.py
 
-import re
+# imports internal
 from rpa_suite.functions._printer import error_print, success_print
 
+# imports third-party
+import re
+
+
 class Regex():
     """
     Class that provides utilities for working with regular expressions.

rpa_suite/core/validate.py

@@ -1,8 +1,11 @@
-# /mail_validator.py
+# rpa_suite/core/mail_validator.py
 
-import email_validator
+# imports internal
 from rpa_suite.functions._printer import error_print, success_print
 
+# imports external
+import email_validator
+
 
 class Validate():
 

rpa_suite/functions/__create_ss_dir.py

@@ -1,8 +1,12 @@
-# /_create_ss_dir.py
+# rpa_suite/functions/__create_ss_dir.py
 
+# imports internal
+from rpa_suite.functions._printer import error_print, alert_print, success_print
+
+# imports third-party
 import os
 from typing import Union
-from rpa_suite.functions._printer import error_print, alert_print, success_print
+
 
 
 def __create_ss_dir(path_to_create: str = 'default', name_ss_dir: str='screenshots') -> dict[str, Union[bool, str, None]]:

rpa_suite/functions/_printer.py

@@ -1,7 +1,9 @@
-# /printer.py
+# rpa_suite/functions/_printer.py
 
+# imports external
 from colorama import Fore
 
+
 # Windows bash colors
 class Colors():
     black     = f'{Fore.BLACK}'