rpa-suite 1.6.2__py3-none-any.whl → 1.6.3__py3-none-any.whl

rpa_suite/core/browser.py

@@ -14,8 +14,12 @@ from selenium.webdriver.support import expected_conditions as EC
 from webdriver_manager.chrome import ChromeDriverManager
 
 # imports internal
-from rpa_suite.functions._printer import error_print, alert_print, success_print
+from rpa_suite.functions._printer import alert_print, success_print
 
+class BrowserError(Exception):
+    """Custom exception for Browser errors."""
+    def __init__(self, message):
+        super().__init__(f'BrowserError: {message}')
 
 class Browser:
     """
@@ -36,16 +40,16 @@ class Browser:
             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):
+        start_browser(close_chrome_on_this_port: bool = True, verbose: 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):
+        find_ele(value, by=By.XPATH, timeout=12, verbose=True):
             Finds a single element on the page using the specified locator strategy.
-        get(url: str, display_message: bool = False):
+        get(url: str, verbose: bool = False):
             Navigates the browser to the specified URL.
         _close_all_browsers():
             Closes all Chrome processes forcefully.
-        close_browser(display_message: bool = False):
+        close_browser(verbose: bool = False):
             Closes the browser instance and terminates the associated Chrome processes.
 
     pt-br
@@ -68,16 +72,16 @@ class Browser:
             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):
+        start_browser(close_chrome_on_this_port: bool = True, verbose: 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):
+        find_ele(value, by=By.XPATH, timeout=12, verbose=True):
             Localiza um único elemento na página usando a estratégia de localização especificada.
-        get(url: str, display_message: bool = False):
+        get(url: str, verbose: bool = False):
             Navega o navegador para a URL especificada.
         _close_all_browsers():
             Fecha todos os processos do Chrome de forma forçada.
-        close_browser(display_message: bool = False):
+        close_browser(verbose: bool = False):
             Fecha a instância do navegador e termina os processos associados do Chrome.
     """
 
@@ -85,13 +89,12 @@ class Browser:
     port: int = None
     path_driver = None
 
-    def __init__(self, port: int = 9393, close_browser_on_this_port: bool = False):
+    def __init__(self, port: int = 9393, close_browser_on_this_port: bool = False) -> None:
         self.port = port
         self.path_driver = ChromeDriverManager().install()
 
         if close_browser_on_this_port:
             self._close_all_browsers()
-        ...
 
     def configure_browser(self) -> None:
         """
@@ -116,7 +119,7 @@ class Browser:
 
             # Verifica se o caminho do driver está correto
             if not os.path.exists(self.path_driver):
-                raise FileNotFoundError(f"O caminho do driver não foi encontrado: {self.path_driver}")
+                raise FileNotFoundError(f"Driver path not found: {self.path_driver}")
 
             # Create driver with options and chromedriver path
             self.driver = webdriver.Chrome(
@@ -126,14 +129,14 @@ class Browser:
             )
 
         except Exception as e:
-            error_print(f"Erro durante a função: {self.configure_browser.__name__}! Error: {str(e)}.")
+            BrowserError(f"Error configure_brower: {str(e)}.")
 
-    def start_browser(self, close_chrome_on_this_port: bool = True, display_message: bool = False):
+    def start_browser(self, close_chrome_on_this_port: bool = True, verbose: 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.
+            verbose (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:
@@ -141,7 +144,7 @@ class Browser:
             - 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.
+            - Optionally displays a success message if `verbose` is True.
         """
 
         try:
@@ -166,13 +169,13 @@ class Browser:
             # Inicializa o Chrome com as opções
             self.configure_browser()
 
-            if display_message:
-                success_print(f"Browser: Iniciado com sucesso!")
+            if verbose:
+                success_print(f"Browser: Started successfully!")
 
         except Exception as e:
-            error_print(f"Erro ao iniciar navegador: {str(e)}.")
+            BrowserError(f"Error starting browser: {str(e)}.")
 
-    def find_ele(self, value: str, by: By = By.XPATH, timeout=12, display_message=True):
+    def find_ele(self, value: str, by: By = By.XPATH, timeout=12, verbose=True):
         """
         Locate and return a web element on the page using the specified locator strategy.
         Args:
@@ -181,14 +184,14 @@ class Browser:
                 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
+            verbose (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.
+                `verbose` is set to False.
         """
 
         try:
@@ -198,8 +201,8 @@ class Browser:
 
         except Exception as e:
 
-            if display_message:
-                error_print(f"Erro durante a função: {self.find_ele.__name__}! Error: {str(e)}.")
+            if verbose:
+                BrowserError(f"Error find_ele (FindElement): {str(e)}.")
                 return None
             else:
                 return None
@@ -208,23 +211,23 @@ class Browser:
     ...
 
     # navigate
-    def get(self, url: str, display_message: bool = False):
+    def get(self, url: str, verbose: 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.
+            verbose (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)
-            if display_message:
-                success_print(f"Browser: Navegando para: {url}")
+            if verbose:
+                success_print(f"Browser: Navigating to: {url}")
 
         except Exception as e:
-            error_print(f"Erro ao navegar para a URL: {url}. Error: {str(e)}.")
+            BrowserError(f"Error navigating to URL: {url}. Error: {str(e)}.")
 
     def _close_all_browsers(self):
         """
@@ -240,14 +243,14 @@ class Browser:
         except:
             pass
 
-    def close_browser(self, display_message: bool = False):
+    def close_browser(self, verbose: 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.
+            verbose (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.
@@ -291,26 +294,26 @@ class Browser:
                 os.system(
                     f'taskkill /f /im chrome.exe /fi "commandline like *--remote-debugging-port={str(self.port)}*" /t >nul 2>&1'
                 )
-                if display_message:
-                    alert_print("Browser: Fechado via força!")
+                if verbose:
+                    alert_print("Browser: Closed forcefully!")
 
             else:
-                if display_message:
-                    success_print("Browser: Fechado com sucesso!")
+                if verbose:
+                    success_print("Browser: Closed successfully!")
 
         except Exception as e:
 
             try:
-                if display_message:
-                    alert_print(f"Erro ao fechar navegador: {str(e)}, Tentando meio mais forte!")
+                if verbose:
+                    alert_print(f"Error closing browser: {str(e)}, Trying stronger method!")
 
                 # Último recurso - mata todos os processos do Chrome (use com cautela)
                 os.system(
                     f'taskkill /f /im chrome.exe /fi "commandline like *--remote-debugging-port={str(self.port)}*" /t >nul 2>&1'
                 )
-                if display_message:
-                    alert_print("Browser: Fechado via força extrema!")
+                if verbose:
+                    alert_print("Browser: Closed with extreme force!")
 
             except Exception as error_ultimate:
-                if display_message:
-                    error_print(f"Falha crítica ao tentar fechar o navegador! Error: {str(error_ultimate)}!")
+                if verbose:
+                    BrowserError(f"Critical failure trying to close browser! Error: {str(error_ultimate)}!")

rpa_suite/core/clock.py

@@ -6,8 +6,12 @@ from typing import Callable, Any
 from datetime import datetime as dt
 
 # imports internal
-from rpa_suite.functions._printer import error_print, success_print
+from rpa_suite.functions._printer import success_print
 
+class ClockError(Exception):
+    """Custom exception for Clock errors."""
+    def __init__(self, message):
+        super().__init__(f'ClockError: {message}')
 
 class Clock:
     """
@@ -42,7 +46,39 @@ class Clock:
         >>> rpa.clock.exec_at_hour("14:30", minha_funcao)
     """
 
-    def __init__(self): ...
+    def __init__(self) -> None:
+        """
+        Class that provides utilities for time manipulation and stopwatch.
+
+        This class offers functionalities for:
+            - Timed function execution
+            - Execution time control
+            - Task scheduling
+
+        Methods:
+            exec_at_hour: Executes a function at a specific time
+
+        The Clock class is part of RPA Suite and can be accessed through the rpa object:
+            >>> from rpa_suite import rpa
+            >>> rpa.clock.exec_at_hour("14:30", my_function)
+
+        pt-br
+        ----------
+        Classe que fornece utilitários para manipulação de tempo e cronômetro.
+
+        Esta classe oferece funcionalidades para:
+            - Execução temporizada de funções
+            - Controle de tempo de execução
+            - Agendamento de tarefas
+
+        Métodos:
+            exec_at_hour: Executa uma função em um horário específico
+
+        A classe Clock é parte do RPA Suite e pode ser acessada através do objeto rpa:
+            >>> from rpa_suite import rpa
+            >>> rpa.clock.exec_at_hour("14:30", minha_funcao)
+        """
+        pass
 
     def exec_at_hour(
         self,
@@ -127,7 +163,7 @@ class Clock:
                         run = False
                         result["tried"] = not run
                         result["success"] = False
-                        error_print(
+                        ClockError(
                             f"An error occurred that prevented the function from executing: {fn_to_exec.__name__} correctly. Error: {str(e)}"
                         )
                         break
@@ -147,10 +183,9 @@ class Clock:
                             run = False
                             result["tried"] = not run
                             result["success"] = False
-                            error_print(
+                            ClockError(
                                 f"An error occurred that prevented the function from executing: {fn_to_exec.__name__} correctly. Error: {str(e)}"
-                            )
-                            break
+                            ) from e
                     else:
                         time.sleep(30)
                         now = dt.now()
@@ -161,10 +196,8 @@ class Clock:
             return result
 
         except Exception as e:
-
             result["success"] = False
-            error_print(f"An error occurred on function from executing: {self.exec_at_hour.__name__}. Error: {str(e)}")
-            return result
+            raise ClockError(str(e)) from e
 
     def wait_for_exec(self, wait_time: int, fn_to_exec: Callable[..., Any], *args, **kwargs) -> dict[str, bool]:
         """
@@ -222,9 +255,9 @@ class Clock:
 
         except Exception as e:
             result["success"] = False
-            error_print(
+            ClockError(
                 f"Error while trying to wait to execute the function: {fn_to_exec.__name__} \nMessage: {str(e)}"
-            )
+            ) from e
 
         return result
 
@@ -284,8 +317,8 @@ class Clock:
 
         except Exception as e:
             result["success"] = False
-            error_print(
+            ClockError(
                 f"Error while trying to wait to execute the function: {fn_to_exec.__name__} \nMessage: {str(e)}"
-            )
+            ) from e
 
         return result

rpa_suite/core/date.py

@@ -5,9 +5,10 @@ import datetime as dt
 from typing import Optional as Op
 from typing import Tuple
 
-# imports internal
-from rpa_suite.functions._printer import error_print
-
+class DateError(Exception):
+    """Custom exception for Date errors."""
+    def __init__(self, message):
+        super().__init__(f'DateError: {message}')
 
 class Date:
     """
@@ -42,7 +43,39 @@ class Date:
         >>> hora, minuto, segundo = rpa.date.get_hms()
     """
 
-    def __init__(self): ...
+    def __init__(self) -> None: 
+        """
+        Class that provides utilities for date manipulation and formatting.
+
+        This class offers functionalities for:
+            - Getting current time components (hours, minutes, seconds)
+            - Date formatting and manipulation
+            - Date validation and conversion
+
+        Methods:
+            get_hms: Returns current time as tuple of hour, minute, second
+
+        The Date class is part of RPA Suite and can be accessed through the rpa object:
+            >>> from rpa_suite import rpa
+            >>> hour, minute, second = rpa.date.get_hms()
+
+        pt-br
+        ----------
+        Classe que fornece utilitários para manipulação e formatação de datas.
+
+        Esta classe oferece funcionalidades para:
+            - Obtenção de componentes do tempo atual (horas, minutos, segundos)
+            - Formatação e manipulação de datas
+            - Validação e conversão de datas
+
+        Métodos:
+            get_hms: Retorna o horário atual como tupla de hora, minuto, segundo
+
+        A classe Date é parte do RPA Suite e pode ser acessada através do objeto rpa:
+            >>> from rpa_suite import rpa
+            >>> hora, minuto, segundo = rpa.date.get_hms()
+        """
+        pass
 
     def get_hms(self) -> Tuple[Op[str], Op[str], Op[str]]:
         """
@@ -106,13 +139,9 @@ class Date:
                 return hours, minutes, seconds
 
             except Exception as e:
-
-                error_print(f"Unable to capture the time. Error: {str(e)}")
-                return None, None, None
-
+                raise e from e
         except Exception as e:
-            error_print(f"Error function: {self.get_hms.__name__}! Error: {str(e)}.")
-            return None, None, None
+            DateError(f"Error function: {self.get_hms.__name__}! {str(e)}.") from e
 
     def get_dmy(self) -> Tuple[Op[str], Op[str], Op[str]]:
         """
@@ -160,10 +189,6 @@ class Date:
                 return day_got, month_got, year_got
 
             except Exception as e:
-
-                error_print(f"Unable to capture the time. Error: {str(e)}")
-                return None, None, None
-
+                raise e from e
         except Exception as e:
-            error_print(f"Erro function: {self.get_dmy.__name__}! Error: {str(e)}.")
-            return None, None, None
+            DateError(f"Erro function: {self.get_dmy.__name__}! {str(e)}.")

rpa_suite/core/dir.py

@@ -6,8 +6,13 @@ import shutil
 from typing import Union
 
 # imports internal
-from rpa_suite.functions._printer import error_print, alert_print, success_print
+from rpa_suite.functions._printer import alert_print, success_print
 
+class DirectoryError(Exception):
+    """Custom exception for Directory errors."""
+    def __init__(self, message):
+        clean_message = message.replace("DirectoryError:", "").strip()
+        super().__init__(f'DirectoryError: {clean_message}')
 
 class Directory:
     """
@@ -29,35 +34,17 @@ class Directory:
     Parameters:
         path_to_create (str): The full path where the temporary directory should be created. Default is 'default', which creates it in the current directory.
         name_temp_dir (str): The name of the temporary directory to be created. Default is 'temp'.
-
-    pt-br
-    ----------
-    Classe que fornece utilitários para gerenciamento de diretórios, incluindo criação, exclusão e manipulação de diretórios.
-
-    Esta classe oferece funcionalidades para:
-        - Criar diretórios temporários
-        - Excluir diretórios
-        - Verificar se um diretório existe
-        - Listar arquivos em um diretório
-
-    Métodos:
-        create_temp_dir: Cria um diretório temporário para operações com arquivos.
-
-    A classe Directory é parte do RPA Suite e pode ser acessada através do objeto rpa:
-        >>> from rpa_suite import rpa
-        >>> rpa.directory.create_temp_dir(path_to_create='minha_pasta', name_temp_dir='temp_dir')
-
-    Parâmetros:
-        path_to_create (str): O caminho completo onde o diretório temporário deve ser criado. O padrão é 'default', que o cria no diretório atual.
-        name_temp_dir (str): O nome do diretório temporário a ser criado. O padrão é 'temp'.
     """
 
     def __init__(self): 
         """
-        Função construtora da Classe que fornece utilitários para gerenciamento de:\n
-        diretórios, incluindo criação, exclusão e manipulação de diretórios.
+        Constructor function of the Class that provides utilities for directory management,
+        including creation, deletion and manipulation of directories.
         """
-        ...
+        try:
+            pass
+        except Exception as e:
+            raise DirectoryError(f"Error trying execute: {self.__init__.__name__}! {str(e)}.")
 
     def create_temp_dir(
         self,
@@ -66,7 +53,7 @@ class Directory:
         display_message: bool = False,
     ) -> dict[str, Union[bool, str, None]]:
         """
-        Function responsible for creating a temporary directory to work with files and etc. \n
+        Function responsible for creating a temporary directory to work with files and etc.
 
         Parameters:
         ----------
@@ -81,24 +68,6 @@ class Directory:
         >>> type:dict
             * 'success': bool - represents case the action was performed successfully
             * 'path_created': str - path of the directory that was created on the process
-
-        Description: pt-br
-        ----------
-        Função responsavel por criar diretório temporário para trabalhar com arquivos e etc. \n
-
-        Parametros:
-        ----------
-        ``path_to_create: str`` - deve ser uma string com o path completo apontando para a pasta onde deve ser criada a pasta temporaria, se estiver vazio sera usado valor ``default`` que criará pasta no diretório atual onde o arquivo contendo esta função foi chamada.
-
-        ``name_temp_dir: str`` - deve ser uma string representando o nome do diretório temporário a ser criado. Se estiver vazio, o valor ``temp`` será usado como o nome padrão do diretório.
-
-        ``display_message: bool`` - deve ser um bool para exibir mensagens no terminal, por padrão False.
-
-        Retorno:
-        ----------
-        >>> type:dict
-            * 'success': bool - representa se ação foi realizada com sucesso
-            * 'path_created': str - path do diretório que foi criado no processo
         """
 
         # Local Variables
@@ -117,7 +86,6 @@ class Directory:
 
             # Create dir in this block
             try:
-
                 # Successefully created
                 os.makedirs(full_path, exist_ok=False)
 
@@ -131,17 +99,18 @@ class Directory:
                 result["success"] = False
                 result["path_created"] = None
                 if display_message:
-                    alert_print(f"Directory:'{full_path}' already exists.")
+                    DirectoryError(f"Directory:'{full_path}' already exists.")
 
             except PermissionError:
                 result["success"] = False
                 result["path_created"] = None
-                alert_print(f"Permission denied: Not possible to create Directory '{full_path}'.")
+                if display_message:
+                    DirectoryError(f"Permission denied: Not possible to create Directory '{full_path}'.")
 
         except Exception as e:
             result["success"] = False
             result["path_created"] = None
-            error_print(f"Error capturing current path to create temporary directory! Error: {str(e)}")
+            raise DirectoryError(f"Error trying execute: {self.create_temp_dir.__name__}! {str(e)}.")
 
         return result
 
@@ -153,7 +122,7 @@ class Directory:
         display_message: bool = False,
     ) -> dict[str, Union[bool, str, None]]:
         """
-        Function responsible for deleting a temporary directory. \n
+        Function responsible for deleting a temporary directory.
 
         Parameters:
         ----------
@@ -168,24 +137,6 @@ class Directory:
         >>> type:dict
             * 'success': bool - represents case the action was performed successfully
             * 'path_deleted': str - path of the directory that was deleted on the process
-
-        Description: pt-br
-        ----------
-        Função responsavel por deletar diretório temporário. \n
-
-        Parametros:
-        ----------
-        ``path_to_delete: str`` - deve ser uma string com o path completo apontando para a pasta onde deve ser deletada a pasta temporaria, se estiver vazio sera usado valor ``default`` que deletará pasta no diretório atual onde o arquivo contendo esta função foi chamada.
-
-        ``name_temp_dir: str`` - deve ser uma string representando o nome do diretório temporário a ser deletado. Se estiver vazio, o valor ``temp`` será usado como o nome padrão do diretório.
-
-        ``delete_files: bool`` - deve ser um booleano indicando se deve deletar arquivos no diretório. Se for False, arquivos no diretório não serão deletados.
-
-        Retorno:
-        ----------
-        >>> type:dict
-            * 'success': bool - representa se ação foi realizada com sucesso
-            * 'path_deleted': str - path do diretório que foi deletado no processo
         """
 
         # Local Variables
@@ -204,7 +155,6 @@ class Directory:
 
             # Delete dir in this block
             try:
-
                 # Check if directory exists
                 if os.path.exists(full_path):
 
@@ -221,21 +171,28 @@ class Directory:
                     result["path_deleted"] = rf"{full_path}"
 
                     if display_message:
-                        success_print(f"Directory:'{full_path}' successfully delete.")
+                        success_print(f"Directory:'{full_path}' successfully deleted.")
                 else:
                     result["success"] = False
                     result["path_deleted"] = None
                     if display_message:
-                        alert_print(f"Directory:'{full_path}' don't exists.")
+                        alert_print(f"Directory:'{full_path}' doesn't exist.")
 
             except PermissionError:
                 result["success"] = False
                 result["path_deleted"] = None
-                alert_print(f"Permission denied: Not possible to delete Directory '{full_path}'.")
+                if display_message:
+                    DirectoryError(f"Permission denied: Not possible to delete Directory '{full_path}'.")
+
+            except OSError as e:
+                result["success"] = False
+                result["path_deleted"] = None
+                if display_message:
+                    DirectoryError(f"OS error occurred while deleting directory '{full_path}': {str(e)}")
 
         except Exception as e:
             result["success"] = False
             result["path_deleted"] = None
-            error_print(f"Error capturing current path to delete temporary directory! Error: {str(e)}.")
+            raise DirectoryError(f"Error trying execute: {self.delete_temp_dir.__name__}! {str(e)}.")
 
         return result