lbxtoolkit 2.3.1__tar.gz → 2.4.0__tar.gz

{lbxtoolkit-2.3.1 → lbxtoolkit-2.4.0}/PKG-INFO

@@ -1,13 +1,14 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: lbxtoolkit
-Version: 2.3.1
-Summary: 
+Version: 2.4.0
+Summary: Caixa ferramentas da LBX para automações de processos (RPA), integrações, utilitários Windows e componentes reutilizáveis.
 Author: Cristiano P. Ferrari
 Author-email: cristiano.ferrari@lbx.com.br
 Requires-Python: >=3.12,<4.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: msal (>=1.30.0)
 Requires-Dist: numpy (>=2.0.1)
 Requires-Dist: pandas (>=2.2.2)

{lbxtoolkit-2.3.1 → lbxtoolkit-2.4.0}/lbxtoolkit/__init__.py

@@ -79,6 +79,8 @@ Classe de miscelâneas/diversos
     - `maximize_console` Maxima a janela do console (cmd.exe)
     - `cor` Altera cores de fonte e funto e estilos (negrito/sublinhado)
 
+### TODO: adicionar novas classes (chrome_session, locators, webdriver_handler)    
+
 ## Instalação e uso:
 
 ### Instalação
@@ -100,6 +102,9 @@ from .auth_entra_id import auth_EntraID
 from .postgresql import postgreSQL
 from .api_rest import api_rest
 from .misc import misc
+from .chrome_session import ChromeSessionConfig, ChromeSessionManager
+from .locators import WebLocator, load_locators_ini, find_element
+from .webdrive_handler import webdrive_handler
 
 locale.setlocale(locale.LC_ALL, 'pt_BR.UTF-8')
 

lbxtoolkit-2.4.0/lbxtoolkit/chrome_session.py

@@ -0,0 +1,263 @@
+from __future__ import annotations
+
+import shutil
+import tempfile
+from dataclasses import dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, Tuple
+
+import psutil # type: ignore
+
+from selenium import webdriver  # type: ignore
+from selenium.common.exceptions import SessionNotCreatedException  # type: ignore
+from selenium.webdriver.chrome.service import Service  # type: ignore
+
+from .lbx_logger import lbx_logger
+from .misc import misc
+
+
+@dataclass
+class ChromeSessionConfig:
+    chrome_exe: str
+    mode: str                      # reuse|new|ephemeral|default|attach (attach tratado fora deste arquivo)
+    profile_name: str
+    profile_root: Path
+    user_data_dir: Path            # Chrome User Data (modo default)
+    profile_directory: str         # "Default", "Profile 5", etc (modo default)
+    log_root: Path
+    headless: bool = False
+    start_maximized: bool = True
+
+    # None = auto; True/False força explicitamente
+    debugging_pipe: Optional[bool] = None
+
+    # None = auto (default -> False); True/False força explicitamente
+    stealth: Optional[bool] = None
+
+    # Se True, em caso de falha ao criar sessão, pausa e pergunta se deve tentar novamente
+    interactive_start: bool = False
+
+    # Quantas tentativas no start (quando interactive_start=False)
+    start_retries: int = 1
+
+
+class ChromeSessionManager:
+    # Ajuste conforme seu padrão (você confirmou este caminho)
+    _DEFAULT_USER_DATA_DIR = Path(r"C:\Users\cristianoferrari\AppData\Local\Google\Chrome\User Data")
+
+    def __init__(self, cfg: ChromeSessionConfig, log: lbx_logger):
+        self.Cfg = cfg
+        self.Log = log
+        self.Driver: Optional[webdriver.Chrome] = None
+
+        self._UserDataDir: Optional[Path] = None
+        self._IsEphemeral: bool = False
+
+        misc.set_dir(self.Cfg.log_root)
+
+    def _resolve_profile_dir(self) -> Tuple[Path, bool]:
+        Mode = (self.Cfg.mode or "reuse").lower().strip()
+
+        if Mode == "default":
+            return Path(self.Cfg.user_data_dir), False
+
+        Root = misc.set_dir(Path(self.Cfg.profile_root) / self.Cfg.profile_name)
+
+        if Mode == "new":
+            self.Log.aviso(f"Modo NEW: apagando profile: [{Root}]")
+            shutil.rmtree(Root, ignore_errors=True)
+            Root = misc.set_dir(Root)
+            return Root, False
+
+        if Mode == "ephemeral":
+            Base = Path(tempfile.gettempdir()) / "rpa_chrome_ephemeral" / self.Cfg.profile_name
+            RunDir = misc.set_dir(Base / datetime.now().strftime("%Y%m%d_%H%M%S"))
+            return RunDir, True
+
+        # reuse
+        return Root, False
+
+    def _bool_auto(self, v: Optional[bool], default_if_none: bool) -> bool:
+        return default_if_none if v is None else bool(v)
+
+    def _is_default_user_data_dir(self, user_data_dir: Path) -> bool:
+        try:
+            return user_data_dir.resolve() == self._DEFAULT_USER_DATA_DIR.resolve()
+        except Exception:
+            # fallback best-effort
+            return str(user_data_dir).strip().lower() == str(self._DEFAULT_USER_DATA_DIR).strip().lower()
+
+    def _list_chrome_pids(self) -> list[int]:
+        Pids: list[int] = []
+        for p in psutil.process_iter(attrs=["pid", "name"]):
+            try:
+                name = (p.info.get("name") or "").lower()
+                if name == "chrome.exe":
+                    Pids.append(int(p.info["pid"]))
+            except Exception:
+                continue
+        return sorted(set(Pids))
+
+    def _kill_chrome(self) -> None:
+        Pids = self._list_chrome_pids()
+        if not Pids:
+            return
+
+        self.Log.aviso(f"Encerrando chrome.exe (PIDs={Pids})...")
+        for pid in Pids:
+            try:
+                psutil.Process(pid).kill()
+            except Exception:
+                pass
+
+    def _build_options(self, user_data_dir: Path) -> webdriver.ChromeOptions:
+        Opts = webdriver.ChromeOptions()
+        Opts.binary_location = self.Cfg.chrome_exe
+
+        Mode = (self.Cfg.mode or "").lower().strip()
+        IsDefaultUD = self._is_default_user_data_dir(user_data_dir)
+
+        # profile
+        Opts.add_argument(f"--user-data-dir={str(user_data_dir)}")
+        if Mode == "default" and self.Cfg.profile_directory:
+            Opts.add_argument(f"--profile-directory={self.Cfg.profile_directory}")
+
+        # Cirúrgicas para evitar travas de restore/crash bubble (especialmente no profile real)
+        Opts.add_argument("--disable-session-crashed-bubble")
+        Opts.add_argument("--hide-crash-restore-bubble")
+        Opts.add_argument("--disable-features=InfiniteSessionRestore")
+
+        # Debugging pipe:
+        # - útil em perfis isolados (não-default)
+        # - PROIBIDO no user-data padrão (Chrome bloqueia DevTools)
+        UsePipe = self._bool_auto(self.Cfg.debugging_pipe, default_if_none=(Mode == "default"))
+        if IsDefaultUD and UsePipe:
+            self.Log.aviso(
+                "Chrome: dbg-pipe solicitado, mas user-data-dir é o padrão do Chrome. "
+                "Forçando dbg-pipe=[off] (Chrome bloqueia DevTools no User Data padrão)."
+            )
+            UsePipe = False
+
+        if UsePipe:
+            Opts.add_argument("--remote-debugging-pipe")
+            self.Log.info("Chrome: remote-debugging-pipe=[on]")
+
+        # flags básicas
+        Opts.add_argument("--no-first-run")
+        Opts.add_argument("--no-default-browser-check")
+        Opts.add_argument("--disable-gpu")
+
+        if self.Cfg.start_maximized:
+            Opts.add_argument("--start-maximized")
+
+        if self.Cfg.headless:
+            Opts.add_argument("--headless=new")
+            self.Log.aviso("Chrome em modo HEADLESS (new)")
+
+        # “Stealth” / anti-automation:
+        # No modo default (perfil real), deixe OFF por padrão.
+        DefaultStealth = (Mode != "default")
+        UseStealth = self._bool_auto(self.Cfg.stealth, default_if_none=DefaultStealth)
+        if UseStealth:
+            Opts.add_argument("--disable-blink-features=AutomationControlled")
+            Opts.add_experimental_option("excludeSwitches", ["enable-automation"])
+            Opts.add_experimental_option("useAutomationExtension", False)
+            self.Log.info("Chrome: stealth=[on]")
+        else:
+            self.Log.info("Chrome: stealth=[off]")
+
+        return Opts
+
+    def _create_driver(self, user_data_dir: Path) -> webdriver.Chrome:
+        Opts = self._build_options(user_data_dir)
+
+        ChromeDriverLog = self.Cfg.log_root / f"chromedriver_{self.Cfg.profile_name}_{datetime.now().strftime('%Y%m%d_%H%M%S')}.log"
+        self.Log.info("Inicializando ChromeDriver...")
+        self.Log.debug(f"chromedriver_log=[{ChromeDriverLog}]")
+
+        ServiceObj = Service(log_output=str(ChromeDriverLog))
+        return webdriver.Chrome(service=ServiceObj, options=Opts)
+
+    def start(self) -> webdriver.Chrome:
+        if self.Driver is not None:
+            return self.Driver
+
+        user_data_dir, is_ephemeral = self._resolve_profile_dir()
+        self._UserDataDir = user_data_dir
+        self._IsEphemeral = is_ephemeral
+
+        Mode = (self.Cfg.mode or "").lower().strip()
+        IsDefaultUD = self._is_default_user_data_dir(user_data_dir)
+
+        # logging do contexto
+        self.Log.info("Sessão Chrome")
+        self.Log.info(f"  mode       : [{self.Cfg.mode}]")
+        self.Log.info(f"  profile    : [{self.Cfg.profile_name}]")
+        self.Log.info(f"  user-data  : [{user_data_dir}]")
+        if Mode == "default":
+            self.Log.info(f"  profile-dir: [{self.Cfg.profile_directory}]")
+        self.Log.info(f"  log_root   : [{self.Cfg.log_root}]")
+        self.Log.info(f"  interactive: [{'on' if self.Cfg.interactive_start else 'off'}]")
+        self.Log.info(f"  retries    : [{self.Cfg.start_retries}]")
+        self.Log.info(f"  user-data-default: [{'yes' if IsDefaultUD else 'no'}]")
+
+        # pré-check de lock (chrome.exe rodando) — importante no modo default
+        ChromePids = self._list_chrome_pids()
+        if ChromePids:
+            self.Log.aviso(f"Detectado chrome.exe em execução (PIDs={ChromePids}). Isso pode bloquear o profile/user-data-dir.")
+            if self.Cfg.interactive_start:
+                Ans = input("Encerrar chrome.exe agora para liberar o profile? (s/N): ").strip().lower()
+                if Ans == "s":
+                    self._kill_chrome()
+                    ChromePids2 = self._list_chrome_pids()
+                    if ChromePids2:
+                        self.Log.aviso(f"Ainda há chrome.exe rodando (PIDs={ChromePids2}). Pode continuar bloqueado.")
+                else:
+                    self.Log.aviso("Você optou por NÃO encerrar o Chrome. Se falhar, o motivo pode ser lock do profile.")
+
+        Attempts = max(1, int(self.Cfg.start_retries or 1))
+
+        while True:
+            last_exc: Exception | None = None
+
+            for i in range(1, Attempts + 1):
+                try:
+                    self.Driver = self._create_driver(user_data_dir)
+                    self.Log.info("Chrome iniciado OK.")
+                    return self.Driver
+                except SessionNotCreatedException as e:
+                    last_exc = e
+                    self.Log.erro(f"Falha ao criar sessão (tentativa {i}/{Attempts}): [{e}]")
+                    if i < Attempts and not self.Cfg.interactive_start:
+                        continue
+                    break
+                except Exception as e:
+                    last_exc = e
+                    self.Log.erro(f"Falha inesperada ao criar sessão (tentativa {i}/{Attempts}): [{e}]")
+                    if i < Attempts and not self.Cfg.interactive_start:
+                        continue
+                    break
+
+            if not self.Cfg.interactive_start:
+                raise last_exc if last_exc else RuntimeError("Falha desconhecida ao criar sessão do ChromeDriver.")
+
+            # interativo: evita crash-loop e permite inspeção
+            self.Log.aviso("Start interativo: não será feito loop automático.")
+            self.Log.aviso("Se o Chrome abriu mas o WebDriver não conectou, cheque: prompts de restore, políticas, AV, perfil bloqueado.")
+            Ans = input("Tentar novamente iniciar a sessão? (s/N): ").strip().lower()
+            if Ans != "s":
+                raise last_exc if last_exc else RuntimeError("Falha desconhecida ao criar sessão do ChromeDriver.")
+
+    def stop(self) -> None:
+        try:
+            if self.Driver is not None:
+                self.Log.info("Encerrando Chrome...")
+                self.Driver.quit()
+                self.Log.info("Chrome encerrado.")
+        finally:
+            self.Driver = None
+            if self._IsEphemeral and self._UserDataDir:
+                shutil.rmtree(self._UserDataDir, ignore_errors=True)
+            self._UserDataDir = None
+            self._IsEphemeral = False

lbxtoolkit-2.4.0/lbxtoolkit/locators.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+import configparser
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from selenium.webdriver.common.by import By  #type: ignore
+from selenium.webdriver.support.ui import WebDriverWait  #type: ignore
+
+from .lbx_logger import lbx_logger
+from .misc import misc
+
+
+@dataclass(frozen=True)
+class WebLocator:
+    """Locator amigável: pode ter HtmlAnchor, Xpath ou ambos."""
+    name: str
+    xpath: str = ""
+    html_anchor: str = ""
+    xpath_check: str = ""                 # dupla checagem opcional
+    must_contain_text: str = ""           # validação opcional
+    must_have_attr: Optional[Dict[str, str]] = None  # validação opcional
+
+
+def load_locators_ini(IniPath: Path) -> Dict[str, WebLocator]:
+    Cfg = configparser.ConfigParser()
+    Cfg.read(IniPath, encoding="utf-8")
+
+    Out: Dict[str, WebLocator] = {}
+    for Section in Cfg.sections():
+        xpath = (Cfg.get(Section, "xpath", fallback="") or "").strip()
+        html = (Cfg.get(Section, "html_anchor", fallback="") or "").strip()
+        xpath_check = (Cfg.get(Section, "xpath_check", fallback="") or "").strip()
+        must_contain_text = (Cfg.get(Section, "must_contain_text", fallback="") or "").strip()
+
+        must_have_attr_raw = (Cfg.get(Section, "must_have_attr", fallback="") or "").strip()
+        must_have_attr = None
+        if must_have_attr_raw:
+            must_have_attr = {}
+            # formato: key=value;key2=value2
+            for part in must_have_attr_raw.split(";"):
+                part = part.strip()
+                if not part:
+                    continue
+                k, _, v = part.partition("=")
+                must_have_attr[k.strip()] = v.strip()
+
+        Out[Section] = WebLocator(
+            name=Section,
+            xpath=xpath,
+            html_anchor=html,
+            xpath_check=xpath_check,
+            must_contain_text=must_contain_text,
+            must_have_attr=must_have_attr,
+        )
+    return Out
+
+
+def _parse_html_anchor(Anchor: str) -> Tuple[str, Dict[str, str], str]:
+    A = re.sub(r"\s+", " ", (Anchor or "").strip())
+    m = re.search(r"<\s*([a-zA-Z0-9:_-]+)", A)
+    Tag = (m.group(1) if m else "*").lower()
+
+    Attrs: Dict[str, str] = {}
+    for Key in ("id", "class", "type", "onclick", "name", "value", "formaction", "href"):
+        mm = re.search(rf"""\b{Key}\s*=\s*["']([^"']+)["']""", A)
+        if mm:
+            Attrs[Key] = mm.group(1)
+
+    Text = ""
+    tm = re.search(r">(.*)<\s*/\s*", A)
+    if tm:
+        Text = re.sub(r"<[^>]+>", " ", tm.group(1) or "")
+        Text = misc._norm(Text)
+
+    return Tag, Attrs, Text
+
+
+def _build_xpath_from_anchor(Tag: str, Attrs: Dict[str, str], Text: str) -> str:
+    Clauses: List[str] = []
+
+    if "id" in Attrs:
+        Clauses.append(f"@id='{Attrs['id']}'")
+
+    if "class" in Attrs:
+        Tokens = [t for t in re.split(r"\s+", Attrs["class"].strip()) if t]
+        for t in Tokens[:4]:
+            Clauses.append("contains(concat(' ', normalize-space(@class), ' '), ' " + t + " ')")
+
+    for k in ("href", "formaction", "onclick"):
+        if k in Attrs:
+            v = (Attrs[k] or "").replace("'", "")
+            Clauses.append(f"contains(@{k}, '{v[:80]}')")
+
+    if Text:
+        t = Text.replace("'", "")
+        Clauses.append(f"contains(normalize-space(.), '{t[:60]}')")
+
+    if not Clauses:
+        return f"//{Tag}"
+    return f"//{Tag}[" + " and ".join(Clauses) + "]"
+
+
+def find_element(
+    *,
+    driver: Any,
+    locator: WebLocator,
+    log: lbx_logger,
+    timeout_s: float,
+    poll_s: float,
+    require_clickable: bool,
+    validate: bool = True,
+) -> Any:
+    """
+    Estratégia:
+      1) HTML-anchor -> gera XPaths candidatos e valida
+      2) fallback XPATH direto
+      3) (opcional) xpath_check como dupla checagem do candidato
+    """
+
+    def _is_ok(el) -> bool:
+        try:
+            if require_clickable and (not el.is_displayed() or not el.is_enabled()):
+                return False
+            if validate and locator.must_contain_text:
+                if locator.must_contain_text.lower() not in misc._norm(el.text).lower():
+                    return False
+            if validate and locator.must_have_attr:
+                for k, v in locator.must_have_attr.items():
+                    if (el.get_attribute(k) or "") != v:
+                        return False
+            if locator.xpath_check:
+                # dupla checagem: ao menos existe na página
+                try:
+                    _ = driver.find_element(By.XPATH, locator.xpath_check)
+                except Exception:
+                    return False
+            return True
+        except Exception:
+            return False
+
+    # 1) html_anchor
+    if locator.html_anchor:
+        Tag, Attrs, Text = _parse_html_anchor(locator.html_anchor)
+        Xp = _build_xpath_from_anchor(Tag, Attrs, Text)
+
+        End = misc._p(timeout_s, 30)
+        Wait = WebDriverWait(driver, End, poll_frequency=poll_s)
+
+        try:
+            Wait.until(lambda d: len(d.find_elements(By.XPATH, Xp)) > 0)
+            Cands = driver.find_elements(By.XPATH, Xp)
+            for el in Cands:
+                if _is_ok(el):
+                    log.info(f"[{locator.name}] selecionado (via html_anchor)")
+                    return el
+        except Exception:
+            pass
+
+    # 2) xpath fallback
+    if locator.xpath:
+        Wait = WebDriverWait(driver, timeout_s, poll_frequency=poll_s)
+        if require_clickable:
+            el = Wait.until(lambda d: d.find_element(By.XPATH, locator.xpath))
+            if not _is_ok(el):
+                raise TimeoutError(f"[{locator.name}] encontrado via xpath, mas falhou validação.")
+            log.info(f"[{locator.name}] selecionado (via xpath)")
+            return el
+
+        el = Wait.until(lambda d: d.find_element(By.XPATH, locator.xpath))
+        if not _is_ok(el):
+            raise TimeoutError(f"[{locator.name}] encontrado via xpath, mas falhou validação.")
+        log.info(f"[{locator.name}] selecionado (via xpath)")
+        return el
+
+    raise TimeoutError(f"[{locator.name}] nenhum locator definido (sem html_anchor e sem xpath).")