movva-tech-library 0.1.0__tar.gz

movva_tech_library-0.1.0/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: movva-tech-library
+Version: 0.1.0
+Summary: Core library for movva tech aplications.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: opencv-python>=4.5.0
+Requires-Dist: pyautogui>=0.9.53
+Requires-Dist: pywinauto>=0.6.8
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: openpyxl>=3.1.2
+Requires-Dist: pywin32>=306
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: browser
+Requires-Dist: selenium>=4.10.0; extra == "browser"
+Requires-Dist: playwright>=1.40.0; extra == "browser"
+Provides-Extra: browser-selenium
+Requires-Dist: selenium>=4.10.0; extra == "browser-selenium"
+Provides-Extra: browser-playwright
+Requires-Dist: playwright>=1.40.0; extra == "browser-playwright"
+
+# movva-tech-library
+
+Uma biblioteca de automação desktop focada em Windows, encapsulando e simplificando as funcionalidades do `pywinauto` e `pyautogui`.
+
+## Como inicializar
+
+Para utilizar a biblioteca, basta importar e instanciar a classe `DesktopRobot`:
+
+```python
+from movva_tech_library import DesktopRobot
+from pathlib import Path
+
+# Instanciando o robô
+robot = DesktopRobot()
+
+## Referência de Métodos
+
+### Gerenciamento de Aplicações e Janelas
+
+- **Iniciar uma aplicação:**
+  ```python
+  robot.start_application(path=r"C:\Caminho\Para\App.exe", backend="uia")
+  ```
+
+- **Conectar a uma aplicação em execução:**
+  ```python
+  robot.connect_application(title="Meu App", backend="uia")
+  ```
+
+- **Esperar por uma janela específica:**
+  ```python
+  robot.wait_for_window(title="Janela Principal", timeout=10)
+  ```
+
+- **Definir janela ativa:** (Útil para buscar locators apenas dentro dessa janela)
+  ```python
+  robot.set_active_window(title="Janela Principal")
+  ```
+
+- **Encerrar aplicação:**
+  ```python
+  robot.kill()
+  ```
+
+### Interação com Elementos da Interface (Locators pywinauto)
+
+Os métodos abaixo aceitam qualquer critério do `pywinauto` (ex: `title`, `auto_id`, `control_type`).
+
+- **Clicar por locator:**
+  ```python
+  robot.click_by_locator(title="Botão Confirmar")
+  ```
+
+- **Duplo clique por locator:**
+  ```python
+  robot.double_click_by_locator(auto_id="btnDetalhes")
+  ```
+
+- **Obter texto de um elemento:**
+  ```python
+  texto = robot.get_text(auto_id="labelStatus")
+  print(texto)
+  ```
+
+### Interação por Imagens na Tela (pyautogui)
+
+> Recomenda-se o uso de caminhos absolutos para as imagens.
+
+- **Clicar em uma imagem:**
+  ```python
+  # Opcional: usar offset_x e offset_y para clicar deslocado do centro da imagem
+  image_path = str(BASE_DIR / "assets" / "botao.png")
+  robot.click_by_image(image_path, confidence=0.9, timeout=10)
+  ```
+
+- **Esperar por uma imagem aparecer na tela:**
+  ```python
+  coordenadas = robot.wait_for_image(image_path, confidence=0.9, timeout=10)
+  ```
+
+### Teclado e Digitação
+
+- **Digitar texto:**
+  Pode focar em um elemento específico antes de digitar caso forneça um `locator`.
+  ```python
+  # Digita livremente onde o cursor estiver
+  robot.type_text("Olá Mundo", interval=0.05)
+  
+  # Foca no input primeiro e depois digita
+  robot.type_text("Meu texto direto no campo", locator={"auto_id": "inputTexto"})
+  ```
+
+- **Pressionar teclas isoladas:**
+  ```python
+  robot.press_key("enter")
+  robot.press_key("tab", presses=2)
+  ```
+
+- **Pressionar atalhos (hotkeys):**
+  ```python
+  robot.hotkey("ctrl", "c")
+  robot.hotkey("alt", "f4")
+  ```
+
+### Esperas (Timeouts e Pausas)
+
+- **Pausa estática (não recomendado, use waits dinâmicos quando possível):**
+  ```python
+  robot.wait(2.5) # Aguarda 2.5 segundos
+  ```

movva_tech_library-0.1.0/README.md

@@ -0,0 +1,110 @@
+# movva-tech-library
+
+Uma biblioteca de automação desktop focada em Windows, encapsulando e simplificando as funcionalidades do `pywinauto` e `pyautogui`.
+
+## Como inicializar
+
+Para utilizar a biblioteca, basta importar e instanciar a classe `DesktopRobot`:
+
+```python
+from movva_tech_library import DesktopRobot
+from pathlib import Path
+
+# Instanciando o robô
+robot = DesktopRobot()
+
+## Referência de Métodos
+
+### Gerenciamento de Aplicações e Janelas
+
+- **Iniciar uma aplicação:**
+  ```python
+  robot.start_application(path=r"C:\Caminho\Para\App.exe", backend="uia")
+  ```
+
+- **Conectar a uma aplicação em execução:**
+  ```python
+  robot.connect_application(title="Meu App", backend="uia")
+  ```
+
+- **Esperar por uma janela específica:**
+  ```python
+  robot.wait_for_window(title="Janela Principal", timeout=10)
+  ```
+
+- **Definir janela ativa:** (Útil para buscar locators apenas dentro dessa janela)
+  ```python
+  robot.set_active_window(title="Janela Principal")
+  ```
+
+- **Encerrar aplicação:**
+  ```python
+  robot.kill()
+  ```
+
+### Interação com Elementos da Interface (Locators pywinauto)
+
+Os métodos abaixo aceitam qualquer critério do `pywinauto` (ex: `title`, `auto_id`, `control_type`).
+
+- **Clicar por locator:**
+  ```python
+  robot.click_by_locator(title="Botão Confirmar")
+  ```
+
+- **Duplo clique por locator:**
+  ```python
+  robot.double_click_by_locator(auto_id="btnDetalhes")
+  ```
+
+- **Obter texto de um elemento:**
+  ```python
+  texto = robot.get_text(auto_id="labelStatus")
+  print(texto)
+  ```
+
+### Interação por Imagens na Tela (pyautogui)
+
+> Recomenda-se o uso de caminhos absolutos para as imagens.
+
+- **Clicar em uma imagem:**
+  ```python
+  # Opcional: usar offset_x e offset_y para clicar deslocado do centro da imagem
+  image_path = str(BASE_DIR / "assets" / "botao.png")
+  robot.click_by_image(image_path, confidence=0.9, timeout=10)
+  ```
+
+- **Esperar por uma imagem aparecer na tela:**
+  ```python
+  coordenadas = robot.wait_for_image(image_path, confidence=0.9, timeout=10)
+  ```
+
+### Teclado e Digitação
+
+- **Digitar texto:**
+  Pode focar em um elemento específico antes de digitar caso forneça um `locator`.
+  ```python
+  # Digita livremente onde o cursor estiver
+  robot.type_text("Olá Mundo", interval=0.05)
+  
+  # Foca no input primeiro e depois digita
+  robot.type_text("Meu texto direto no campo", locator={"auto_id": "inputTexto"})
+  ```
+
+- **Pressionar teclas isoladas:**
+  ```python
+  robot.press_key("enter")
+  robot.press_key("tab", presses=2)
+  ```
+
+- **Pressionar atalhos (hotkeys):**
+  ```python
+  robot.hotkey("ctrl", "c")
+  robot.hotkey("alt", "f4")
+  ```
+
+### Esperas (Timeouts e Pausas)
+
+- **Pausa estática (não recomendado, use waits dinâmicos quando possível):**
+  ```python
+  robot.wait(2.5) # Aguarda 2.5 segundos
+  ```

movva_tech_library-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "movva-tech-library"
+version = "0.1.0"
+description = "Core library for movva tech aplications."
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = [
+    "opencv-python>=4.5.0",
+    "pyautogui>=0.9.53",
+    "pywinauto>=0.6.8",
+    "numpy>=1.19.0",
+    "openpyxl>=3.1.2",
+    "pywin32>=306",
+]
+
+
+[project.optional-dependencies]
+dev = ["pytest"]
+browser = ["selenium>=4.10.0", "playwright>=1.40.0"]
+browser-selenium = ["selenium>=4.10.0"]
+browser-playwright = ["playwright>=1.40.0"]

movva_tech_library-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

movva_tech_library-0.1.0/src/movva_tech_library/__init__.py

@@ -0,0 +1,38 @@
+# __init__.py
+
+from .components.general.general import saudacao
+from .components.orchestrator.orchestratorComponent import OrchestratorComponent
+from .components.grid.gridComponent import GridComponent
+from .components.http.httpComponent import HttpComponent
+from .components.windows.windowsComponent import WindowsComponent
+from .components.email.emailComponent import EmailComponent, EmailWrapper
+from .components.browser.browserComponent import Browser
+from .components.worksheet.worksheetComponent import WorksheetComponent
+
+# Backward compatibility aliases
+Orchestrator = OrchestratorComponent
+HttpRequest = HttpComponent
+Grid = GridComponent
+DesktopRobot = WindowsComponent
+SpreadsheetWrapper = WorksheetComponent
+BrowserComponent = Browser
+
+__all__ = [
+    'saudacao',
+    'OrchestratorComponent',
+    'Orchestrator',
+    'HttpComponent',
+    'HttpRequest',
+    'GridComponent',
+    'Grid',
+    'WindowsComponent',
+    'DesktopRobot',
+    'EmailComponent',
+    'EmailWrapper',
+    'Browser',
+    'BrowserComponent',
+    'WorksheetComponent',
+    'SpreadsheetWrapper',
+]
+
+__version__ = '1.0.0'

movva_tech_library-0.1.0/src/movva_tech_library/components/browser/__init__.py

@@ -0,0 +1,3 @@
+from .browser import Browser
+
+__all__ = ['Browser']

movva_tech_library-0.1.0/src/movva_tech_library/components/browser/browserComponent.py

@@ -0,0 +1,333 @@
+import os
+import time
+from typing import Any, Dict, List, Optional, Union
+
+from movva_tech_library.core.lib.browser import _BrowserLibrary, _BrowserPlugin
+from movva_tech_library.core.plugin.browser import _SeleniumPlugin, _PlaywrightPlugin
+
+from .commands import (
+    NavigateCommand,
+    BackCommand,
+    ForwardCommand,
+    RefreshCommand,
+    ClickCommand,
+    DoubleClickCommand,
+    TypeTextCommand,
+    HoverCommand,
+    PressKeyCommand,
+    GetTextCommand,
+    GetAttributeCommand,
+    GetCurrentUrlCommand,
+    GetPageSourceCommand,
+    GetTitleCommand,
+    WaitForElementCommand,
+    WaitCommand,
+    FindElementsCommand,
+    SelectDropdownCommand,
+    NewTabCommand,
+    SwitchToTabCommand,
+    CloseTabCommand,
+    GetTabsCommand,
+    ExecuteScriptCommand,
+    ScreenshotCommand,
+)
+
+
+class Browser(_BrowserLibrary) :
+    """
+    Wrapper unificado de automação web com suporte a Selenium e Playwright.
+
+    Permite escolher o engine de automação no construtor e expõe uma API
+    consistente independente do backend selecionado.
+
+    Engines suportados: 'selenium', 'playwright'
+    Browsers suportados: 'chrome', 'firefox', 'edge'
+
+    Exemplo de uso:
+        browser = Browser(engine='selenium', browser='chrome', headless=True)
+        browser.navigate('https://example.com')
+        browser.click('#botao', by='css')
+        browser.close()
+
+    Nota (Playwright): Após instalar o pacote, execute `playwright install`
+    para baixar os binários dos browsers.
+    """
+
+    def __init__(
+        self,
+        engine: str = 'selenium',
+        browser: str = 'chrome',
+        headless: bool = False,
+        timeout: float = 10,
+    ):
+        """
+        Inicializa o Browser com o engine e browser especificados.
+
+        Args:
+            engine: Engine de automação — 'selenium' ou 'playwright'.
+            browser: Navegador a usar — 'chrome', 'firefox' ou 'edge'.
+            headless: Se True, executa o browser sem interface gráfica.
+            timeout: Tempo padrão de espera (em segundos) para localizar elementos.
+        """
+        engine = engine.lower()
+        if engine == 'selenium':
+            self._driver: _BrowserPlugin = _SeleniumPlugin(browser, headless, timeout)
+        elif engine == 'playwright':
+            self._driver: _BrowserPlugin = _PlaywrightPlugin(browser, headless, timeout)
+        else:
+            raise ValueError(
+                f"Engine '{engine}' não suportado. Use 'selenium' ou 'playwright'."
+            )
+
+        self._engine = engine
+        self._timeout = timeout
+
+    # region Navegação
+
+    def navigate(self, url: str):
+        """Navegar para uma URL."""
+        return NavigateCommand(self, url).run()
+
+    def back(self):
+        """Voltar para a página anterior no histórico."""
+        return BackCommand(self).run()
+
+    def forward(self):
+        """Avançar para a próxima página no histórico."""
+        return ForwardCommand(self).run()
+
+    def refresh(self):
+        """Recarregar a página atual."""
+        return RefreshCommand(self).run()
+    # endregion
+
+    # region Interação
+
+    def click(self, selector: str, by: str = 'css'):
+        """Clicar em um elemento da página.
+
+        Args:
+            selector: Seletor do elemento (ex: '#btn', '//button[@id="ok"]').
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+        """
+        return ClickCommand(self, selector, by).run()
+
+    def double_click(self, selector: str, by: str = 'css'):
+        """Clicar duas vezes (double click) em um elemento da página.
+
+        Args:
+            selector: Seletor do elemento.
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+        """
+        return DoubleClickCommand(self, selector, by).run()
+
+    def type_text(self, selector: str, text: str, by: str = 'css', clear: bool = True):
+        """Digitar texto em um campo de entrada (input/textarea).
+
+        Args:
+            selector: Seletor do elemento.
+            text: Texto a ser digitado.
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+            clear: Se True, limpa o campo antes de digitar. Default True.
+        """
+        return TypeTextCommand(self, selector, text, by, clear).run()
+
+    def hover(self, selector: str, by: str = 'css'):
+        """Passar o mouse sobre um elemento (hover).
+
+        Args:
+            selector: Seletor do elemento.
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+        """
+        return HoverCommand(self, selector, by).run()
+
+    def press_key(self, key: str):
+        """Pressionar uma tecla do teclado.
+
+        Args:
+            key: Nome da tecla (ex: 'Enter', 'Tab', 'Escape', 'ArrowDown').
+                 Selenium usa nomes como 'ENTER', 'TAB'. Playwright usa 'Enter', 'Tab'.
+        """
+        return PressKeyCommand(self, key).run()
+    # endregion
+
+    # region Leitura de Dados
+
+    def get_text(self, selector: str, by: str = 'css') -> str:
+        """Obter o texto visível de um elemento.
+
+        Args:
+            selector: Seletor do elemento.
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+
+        Returns:
+            Texto interno do elemento.
+        """
+        return GetTextCommand(self, selector, by).run()
+
+    def get_attribute(self, selector: str, attribute: str, by: str = 'css') -> Optional[str]:
+        """Obter o valor de um atributo HTML de um elemento.
+
+        Args:
+            selector: Seletor do elemento.
+            attribute: Nome do atributo HTML (ex: 'href', 'src', 'value', 'data-id').
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+
+        Returns:
+            Valor do atributo ou None se não existir.
+        """
+        return GetAttributeCommand(self, selector, attribute, by).run()
+
+    def get_current_url(self) -> str:
+        """Obter a URL atual da página."""
+        return GetCurrentUrlCommand(self).run()
+
+    def get_page_source(self) -> str:
+        """Obter o código-fonte HTML da página atual."""
+        return GetPageSourceCommand(self).run()
+
+    def get_title(self) -> str:
+        """Obter o título da página atual."""
+        return GetTitleCommand(self).run()
+    # endregion
+
+    # region Espera (Wait)
+
+    def wait_for_element(
+        self,
+        selector: str,
+        by: str = 'css',
+        timeout: float = None,
+        visible: bool = False,
+    ):
+        """Esperar até que um elemento esteja presente (ou visível) na página.
+
+        Args:
+            selector: Seletor do elemento.
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+            timeout: Tempo máximo de espera em segundos. Usa o timeout padrão se None.
+            visible: Se True, espera o elemento estar visível. Se False, apenas presente no DOM.
+        """
+        return WaitForElementCommand(self, selector, by, timeout, visible).run()
+
+    def wait(self, seconds: float):
+        """Pausar a execução por um determinado número de segundos.
+
+        Args:
+            seconds: Tempo de espera em segundos.
+        """
+        return WaitCommand(self, seconds).run()
+    # endregion
+
+    # region Busca de Elementos
+
+    def find_elements(self, selector: str, by: str = 'css') -> List[Dict[str, Any]]:
+        """Buscar múltiplos elementos e retornar seus dados.
+
+        Args:
+            selector: Seletor dos elementos.
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+
+        Returns:
+            Lista de dicionários com 'text', 'tag' e 'attributes' de cada elemento.
+        """
+        return FindElementsCommand(self, selector, by).run()
+    # endregion
+
+    # region Seleção (Dropdown / Select)
+
+    def select_dropdown(
+        self,
+        selector: str,
+        value: str = None,
+        text: str = None,
+        index: int = None,
+        by: str = 'css',
+    ):
+        """Selecionar uma opção em um elemento <select>.
+
+        Forneça apenas um dos parâmetros: value, text ou index.
+
+        Args:
+            selector: Seletor do elemento <select>.
+            value: Valor do atributo 'value' da opção.
+            text: Texto visível da opção.
+            index: Índice da opção (base 0).
+            by: Tipo de localizador — 'css', 'xpath', 'id', 'name', 'class', 'tag'.
+        """
+        return SelectDropdownCommand(self, selector, value, text, index, by).run()
+    # endregion
+
+    # region Gerenciamento de Abas
+
+    def new_tab(self, url: str = None):
+        """Abrir uma nova aba no browser.
+
+        Args:
+            url: URL opcional para navegar na nova aba.
+        """
+        return NewTabCommand(self, url).run()
+
+    def switch_to_tab(self, index: int):
+        """Trocar para uma aba pelo índice.
+
+        Args:
+            index: Índice da aba (base 0).
+        """
+        return SwitchToTabCommand(self, index).run()
+
+    def close_tab(self):
+        """Fechar a aba atual e voltar para a última aba disponível."""
+        return CloseTabCommand(self).run()
+
+    def get_tabs(self) -> List[str]:
+        """Listar as abas abertas.
+
+        Returns:
+            Selenium: lista de window handles.
+            Playwright: lista de URLs das páginas abertas.
+        """
+        return GetTabsCommand(self).run()
+    # endregion
+
+    # region JavaScript
+
+    def execute_script(self, script: str, *args) -> Any:
+        """Executar código JavaScript na página.
+
+        Args:
+            script: Código JavaScript a executar.
+            *args: Argumentos passados para o script.
+
+        Returns:
+            Valor retornado pela execução do script.
+        """
+        return ExecuteScriptCommand(self, script, *args).run()
+    # endregion
+
+    # region Captura de Tela
+
+    def screenshot(self, path: str):
+        """Capturar screenshot da página e salvar em arquivo.
+
+        Args:
+            path: Caminho do arquivo de imagem (ex: 'screenshots/pagina.png').
+        """
+        return ScreenshotCommand(self, path).run()
+    # endregion
+
+    # region Encerramento
+
+    def close(self):
+        """Fechar o browser e encerrar o driver/engine."""
+        self._driver.close()
+
+    def __enter__(self):
+        """Suporte a context manager (with statement)."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Fecha o browser automaticamente ao sair do bloco with."""
+        self.close()
+        return False
+    # endregion

movva_tech_library-0.1.0/src/movva_tech_library/components/browser/commands/__init__.py

@@ -0,0 +1,51 @@
+from .NavigateCommand import NavigateCommand
+from .BackCommand import BackCommand
+from .ForwardCommand import ForwardCommand
+from .RefreshCommand import RefreshCommand
+from .ClickCommand import ClickCommand
+from .DoubleClickCommand import DoubleClickCommand
+from .TypeTextCommand import TypeTextCommand
+from .HoverCommand import HoverCommand
+from .PressKeyCommand import PressKeyCommand
+from .GetTextCommand import GetTextCommand
+from .GetAttributeCommand import GetAttributeCommand
+from .GetCurrentUrlCommand import GetCurrentUrlCommand
+from .GetPageSourceCommand import GetPageSourceCommand
+from .GetTitleCommand import GetTitleCommand
+from .WaitForElementCommand import WaitForElementCommand
+from .WaitCommand import WaitCommand
+from .FindElementsCommand import FindElementsCommand
+from .SelectDropdownCommand import SelectDropdownCommand
+from .NewTabCommand import NewTabCommand
+from .SwitchToTabCommand import SwitchToTabCommand
+from .CloseTabCommand import CloseTabCommand
+from .GetTabsCommand import GetTabsCommand
+from .ExecuteScriptCommand import ExecuteScriptCommand
+from .ScreenshotCommand import ScreenshotCommand
+
+__all__ = [
+    'NavigateCommand',
+    'BackCommand',
+    'ForwardCommand',
+    'RefreshCommand',
+    'ClickCommand',
+    'DoubleClickCommand',
+    'TypeTextCommand',
+    'HoverCommand',
+    'PressKeyCommand',
+    'GetTextCommand',
+    'GetAttributeCommand',
+    'GetCurrentUrlCommand',
+    'GetPageSourceCommand',
+    'GetTitleCommand',
+    'WaitForElementCommand',
+    'WaitCommand',
+    'FindElementsCommand',
+    'SelectDropdownCommand',
+    'NewTabCommand',
+    'SwitchToTabCommand',
+    'CloseTabCommand',
+    'GetTabsCommand',
+    'ExecuteScriptCommand',
+    'ScreenshotCommand',
+]