botonomus 0.2.0__py3-none-any.whl

botonomus/__init__.py

@@ -0,0 +1,63 @@
+"""Botonomus: stealth browser automation on real Chrome.
+
+Typical use:
+
+    import asyncio
+    from botonomus import Botonomus, BrowserConfig
+
+    async def main() -> None:
+        async with Botonomus(max_instances=10, config=BrowserConfig()) as bot:
+            async with bot.open(profile="acct-01") as session:
+                await session.page.goto("https://example.com")
+
+    asyncio.run(main())
+"""
+
+from ._version import __version__
+from .config import BrowserConfig, ProxySpec, parse_proxy
+from .core import Botonomus, Session
+from .errors import (
+    BinaryDownloadError,
+    BinaryNotInstalledError,
+    BinaryVerificationError,
+    BotonomusError,
+    BrowserCleanupError,
+    BrowserStartupError,
+    BrowserUnavailableError,
+    ConfigurationError,
+    GeoLookupError,
+    GeoMismatchError,
+    ManagerClosedError,
+    PersonaUnsupportedError,
+    ProfileInUseError,
+)
+from .human import Human, HumanConfig, HumanPage, HumanProfile
+
+__all__ = [
+    "PersonaUnsupportedError",
+    "GeoMismatchError",
+    "GeoLookupError",
+    "BinaryVerificationError",
+    "BinaryNotInstalledError",
+    "BinaryDownloadError",
+    "BinaryDownloadError",
+    "BinaryNotInstalledError",
+    "BinaryVerificationError",
+    "Botonomus",
+    "BotonomusError",
+    "BrowserCleanupError",
+    "BrowserConfig",
+    "BrowserStartupError",
+    "BrowserUnavailableError",
+    "ConfigurationError",
+    "Human",
+    "HumanConfig",
+    "HumanPage",
+    "HumanProfile",
+    "ManagerClosedError",
+    "ProfileInUseError",
+    "ProxySpec",
+    "Session",
+    "__version__",
+    "parse_proxy",
+]

botonomus/_version.py

@@ -0,0 +1,3 @@
+"""Package version."""
+
+__version__ = "0.2.0"

botonomus/browser/__init__.py

@@ -0,0 +1,38 @@
+"""Browser executables, processes, installed builds and the Chrome backend."""
+
+from .arguments import launch_arguments
+from .backend import Backend, BrowserHandle
+from .chrome import ChromeBackend, ChromeHandle
+from .discovery import (
+    BUILD_MARKER,
+    find_botonomus_chromium,
+    find_chrome,
+    is_botonomus_build,
+    is_testing_build,
+)
+from .display import VirtualDisplay, container_flags, needs_virtual_display
+from .installer import InstalledBinary, find_installed, install, installed_binaries, uninstall
+from .version import executable_sha256, executable_version
+
+__all__ = [
+    "BUILD_MARKER",
+    "Backend",
+    "BrowserHandle",
+    "ChromeBackend",
+    "ChromeHandle",
+    "InstalledBinary",
+    "VirtualDisplay",
+    "container_flags",
+    "executable_sha256",
+    "executable_version",
+    "find_botonomus_chromium",
+    "find_chrome",
+    "find_installed",
+    "install",
+    "installed_binaries",
+    "is_botonomus_build",
+    "is_testing_build",
+    "launch_arguments",
+    "needs_virtual_display",
+    "uninstall",
+]

botonomus/browser/arguments.py

@@ -0,0 +1,57 @@
+"""Command-line construction for a native, unobservable browser launch."""
+
+from collections.abc import Sequence
+from pathlib import Path
+
+from ..config import BrowserConfig
+
+
+def launch_arguments(
+    executable: Path,
+    profile_path: Path,
+    port: int,
+    config: BrowserConfig,
+    *,
+    proxy_server: str | None = None,
+    platform_args: Sequence[str] = (),
+) -> list[str]:
+    """Build the full browser command line.
+
+    Args:
+        executable: Browser executable.
+        profile_path: Dedicated ``--user-data-dir``.
+        port: Explicit, nonzero loopback debugging port.
+        config: Session configuration.
+        proxy_server: Credential-free ``--proxy-server`` value, if a proxy is used.
+            Credentials are handled by the loopback forwarder and never appear here.
+        platform_args: Flags the platform needs (container flags, virtual-display
+            window geometry), placed before the user's ``extra_args``.
+
+    Returns:
+        Arguments in launch order, ending with the initial ``about:blank`` page.
+    """
+    arguments = [
+        str(executable),
+        f"--user-data-dir={profile_path}",
+        f"--remote-debugging-port={port}",
+        "--remote-debugging-address=127.0.0.1",
+        "--no-first-run",
+        "--no-default-browser-check",
+    ]
+    if config.headless:
+        arguments.append("--headless=new")
+    if config.render_when_occluded:
+        arguments.append("--disable-backgrounding-occluded-windows")
+    if config.locale is not None:
+        arguments += [f"--lang={config.locale}", f"--accept-lang={config.locale}"]
+    arguments += platform_args
+    arguments += config.extra_args
+    arguments += config.persona_switches
+    if proxy_server is not None:
+        # WebRTC UDP would otherwise bypass the proxy and reveal the real address.
+        arguments += [
+            f"--proxy-server={proxy_server}",
+            "--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
+        ]
+    arguments.append("about:blank")
+    return arguments

botonomus/browser/backend.py

@@ -0,0 +1,64 @@
+"""The contract between the session manager and a browser backend.
+
+The backend owns operating-system processes; the manager owns admission and
+profile leases. A backend may only report successful cleanup once it has confirmed
+that everything it started has stopped.
+"""
+
+from pathlib import Path
+from typing import Any, Protocol
+
+from ..config import BrowserConfig
+
+
+class BrowserHandle(Protocol):
+    """One running browser attached to a dedicated profile."""
+
+    @property
+    def context(self) -> Any:
+        """The browser context (native ``Context`` or a Playwright ``BrowserContext``)."""
+        ...
+
+    @property
+    def page(self) -> Any:
+        """The initial page (native ``Page`` or a Playwright ``Page``)."""
+        ...
+
+    async def close(self) -> None:
+        """Stop the browser.
+
+        Returns only after every owned process is confirmed stopped.
+
+        Raises:
+            BrowserCleanupError: If that cannot be confirmed.
+        """
+        ...
+
+
+class Backend(Protocol):
+    """Starts browsers and guarantees their shutdown."""
+
+    async def start(self) -> None:
+        """Prepare shared resources such as a driver runtime. Idempotent."""
+        ...
+
+    async def launch(self, profile_path: Path, config: BrowserConfig) -> BrowserHandle:
+        """Launch a browser for ``profile_path`` and attach to it.
+
+        Raises:
+            BrowserUnavailableError: If no executable is available.
+            BrowserStartupError: If the process or attachment fails; anything started
+                has been cleaned up.
+            BrowserCleanupError: If a failed launch left processes that could not be
+                confirmed stopped.
+        """
+        ...
+
+    async def close(self) -> None:
+        """Stop every browser this backend owns and release shared resources.
+
+        Raises:
+            BrowserCleanupError: If any owned browser could not be confirmed stopped;
+                ownership is retained.
+        """
+        ...

botonomus/browser/chrome.py

@@ -0,0 +1,227 @@
+"""Chrome backend: native process launch, then loopback CDP attachment.
+
+The browser starts exactly as a user would start it, plus a dedicated profile and
+an explicit loopback debugging port. The driver attaches afterwards without
+applying context overrides, so pages observe an ordinary browser.
+"""
+
+import asyncio
+import logging
+import os
+from contextlib import suppress
+from pathlib import Path
+from typing import Any
+
+import psutil
+
+from ..config import BrowserConfig, DriverName
+from ..drivers import Attachment, Driver, create_driver
+from ..errors import BrowserCleanupError, BrowserStartupError
+from ..network import ProxyForwarder
+from .arguments import launch_arguments
+from .discovery import find_chrome, is_testing_build
+from .display import VirtualDisplay, host_container_flags, needs_virtual_display
+from .process import available_port, descendants, owns_listener, stop_owned
+
+_log = logging.getLogger("botonomus")
+
+
+class ChromeHandle:
+    """One launched browser process, its attachment and its proxy forwarder.
+
+    Args:
+        process: The browser's root process.
+        timeout: Seconds for the whole close sequence (graceful, then forced).
+    """
+
+    def __init__(self, process: asyncio.subprocess.Process, timeout: float) -> None:
+        self.process = process
+        self.identity = psutil.Process(process.pid)
+        self.identity.create_time()  # Cache identity before any later PID reuse.
+        self.attachment: Attachment | None = None
+        self.forwarder: ProxyForwarder | None = None
+        self._timeout = timeout
+        self._close_task: asyncio.Task[None] | None = None
+
+    @property
+    def context(self) -> Any:
+        """The driver's browser context.
+
+        Raises:
+            BrowserStartupError: If the driver has not attached yet.
+        """
+        if self.attachment is None:
+            raise BrowserStartupError("Browser context is not ready")
+        return self.attachment.context
+
+    @property
+    def page(self) -> Any:
+        """The driver's initial page.
+
+        Raises:
+            BrowserStartupError: If the driver has not attached yet.
+        """
+        if self.attachment is None:
+            raise BrowserStartupError("Browser page is not ready")
+        return self.attachment.page
+
+    async def close(self) -> None:
+        """Close gracefully, then terminate owned processes. Idempotent and shielded.
+
+        Raises:
+            BrowserCleanupError: If owned processes could not be confirmed stopped.
+        """
+        if self._close_task is None:
+            self._close_task = asyncio.create_task(self._close())
+        await asyncio.shield(self._close_task)
+
+    async def _close(self) -> None:
+        children = await asyncio.to_thread(descendants, self.identity)
+        try:
+            if self.attachment is not None:
+                with suppress(TimeoutError):
+                    async with asyncio.timeout(self._timeout / 2):
+                        await self.attachment.request_close()
+                        await self.process.wait()
+            await asyncio.to_thread(stop_owned, [*children, self.identity], self._timeout / 2)
+            await asyncio.wait_for(self.process.wait(), self._timeout / 2)
+            if self.attachment is not None:
+                with suppress(TimeoutError):
+                    await asyncio.wait_for(self.attachment.disconnect(), self._timeout / 2)
+            if self.forwarder is not None:
+                await asyncio.wait_for(self.forwarder.close(), self._timeout / 2)
+        except Exception as exc:
+            raise BrowserCleanupError("Could not confirm browser process cleanup") from exc
+
+
+class ChromeBackend:
+    """Launches Chrome (or a named Chromium build) and attaches a driver.
+
+    Args:
+        driver: A driver name, or a [`Driver`][botonomus.drivers.Driver] instance.
+    """
+
+    def __init__(self, driver: DriverName | Driver = "native") -> None:
+        self._driver: Driver = create_driver(driver) if isinstance(driver, str) else driver
+        self._started = False
+        self._handles: set[ChromeHandle] = set()
+        self._display: VirtualDisplay | None = None
+        self._display_lock = asyncio.Lock()
+
+    async def start(self) -> None:
+        """Start the driver runtime. Idempotent.
+
+        Raises:
+            BrowserStartupError: If the driver cannot start.
+        """
+        if not self._started:
+            await self._driver.start()
+            self._started = True
+
+    async def launch(self, profile_path: Path, config: BrowserConfig) -> ChromeHandle:
+        """Launch a browser for ``profile_path`` and attach the driver.
+
+        Raises:
+            BrowserUnavailableError: If no executable is found.
+            ConfigurationError: If ``virtual_display=True`` is requested off Linux.
+            BrowserStartupError: If launch, attachment or the virtual display fails or
+                times out.
+            BrowserCleanupError: If a failed launch could not be cleaned up.
+        """
+        executable = find_chrome(config.executable_path)
+        if is_testing_build(executable):
+            _log.warning("testing_build_executable")
+        if not self._started:
+            raise BrowserStartupError("Backend is not started")
+        # Outside the try below, so display errors keep their own message and type.
+        platform_args, env = await self._platform(config)
+        port = available_port()
+        handle: ChromeHandle | None = None
+        forwarder: ProxyForwarder | None = None
+        try:
+            proxy_server = None
+            if (proxy := config.proxy_spec) is not None:
+                proxy_server = proxy.server
+                if proxy.has_credentials:
+                    forwarder = ProxyForwarder(proxy)
+                    await forwarder.start()
+                    proxy_server = forwarder.server
+            arguments = launch_arguments(
+                executable,
+                profile_path,
+                port,
+                config,
+                proxy_server=proxy_server,
+                platform_args=platform_args,
+            )
+            process = await asyncio.create_subprocess_exec(
+                *arguments,
+                stdout=asyncio.subprocess.DEVNULL,
+                stderr=asyncio.subprocess.DEVNULL,
+                env=env,
+            )
+            handle = ChromeHandle(process, config.close_timeout)
+            handle.forwarder, forwarder = forwarder, None
+            self._handles.add(handle)
+            async with asyncio.timeout(config.launch_timeout):
+                while not await asyncio.to_thread(owns_listener, handle.identity, port):
+                    if process.returncode is not None:
+                        raise BrowserStartupError("Browser exited before its endpoint was ready")
+                    await asyncio.sleep(0.05)
+                handle.attachment = await self._driver.attach(port, config.launch_timeout)
+            return handle
+        except BaseException as exc:
+            if handle is not None:
+                await handle.close()
+                self._handles.discard(handle)
+            if forwarder is not None:
+                await forwarder.close()
+            if isinstance(exc, asyncio.CancelledError):
+                raise
+            raise BrowserStartupError("Browser launch or attachment failed") from exc
+
+    async def _platform(
+        self, config: BrowserConfig
+    ) -> tuple[tuple[str, ...], dict[str, str] | None]:
+        """Container flags, plus the shared virtual display when ``config`` needs one.
+
+        Returns:
+            Extra launch flags and the environment for the browser process (``None``
+            inherits this process's environment).
+        """
+        flags = host_container_flags()
+        if not needs_virtual_display(config):
+            return flags, None
+        async with self._display_lock:
+            if self._display is None:
+                display = VirtualDisplay()
+                await display.start()
+                self._display = display
+        assert self._display.display is not None
+        geometry = (
+            # Chrome would otherwise prefer a Wayland session it inherited.
+            "--ozone-platform=x11",
+            "--window-position=0,0",
+            f"--window-size={self._display.width},{self._display.height}",
+        )
+        env = {k: v for k, v in os.environ.items() if k != "WAYLAND_DISPLAY"}
+        env["DISPLAY"] = self._display.display
+        return (*flags, *geometry), env
+
+    async def close(self) -> None:
+        """Stop every owned browser, then the virtual display and the driver runtime.
+
+        Raises:
+            BrowserCleanupError: If any owned browser could not be stopped; the driver
+                is left running and ownership retained. The virtual display is stopped
+                regardless, so no Xvfb server outlives the manager.
+        """
+        results = await asyncio.gather(*(h.close() for h in self._handles), return_exceptions=True)
+        if self._display is not None:
+            display, self._display = self._display, None
+            await display.stop()
+        if any(isinstance(result, BaseException) for result in results):
+            raise BrowserCleanupError("Some owned browsers could not be stopped")
+        self._handles.clear()
+        await self._driver.stop()
+        self._started = False

botonomus/browser/discovery.py

@@ -0,0 +1,100 @@
+"""Locating a browser executable.
+
+Unbranded Chromium is never a silent substitute for Chrome: `find_chrome` only
+returns Google Chrome unless the caller names an executable. Botonomus Chromium
+builds are found separately and identified by a marker file shipped beside them.
+"""
+
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Final
+
+from ..errors import BrowserUnavailableError
+from . import installer
+
+BUILD_MARKER: Final = "botonomus-build.json"
+"""File placed next to the executable of every Botonomus Chromium build."""
+
+
+def is_botonomus_build(executable: Path) -> bool:
+    """Whether ``executable`` is a Botonomus Chromium build.
+
+    True when the build marker sits next to the executable, or the executable lives
+    inside a verified install made by
+    [`botonomus.browser.install`][botonomus.browser.install]. Blocking.
+    """
+    if (executable.parent / BUILD_MARKER).is_file():
+        return True
+    return any((parent / installer.INSTALL_RECORD).is_file() for parent in executable.parents[:3])
+
+
+def find_chrome(explicit: Path | None = None) -> Path:
+    """Return the browser executable to launch.
+
+    Args:
+        explicit: A caller-supplied executable. When given, it is the only candidate.
+
+    Returns:
+        The resolved path of an existing executable.
+
+    Raises:
+        BrowserUnavailableError: If ``explicit`` does not exist, or no installed Google
+            Chrome is found in the standard locations or on ``PATH``.
+    """
+    if explicit is not None:
+        if explicit.is_file():
+            return explicit
+        raise BrowserUnavailableError("Configured browser executable does not exist")
+    for candidate in _chrome_candidates():
+        if candidate.is_file():
+            return candidate.resolve()
+    raise BrowserUnavailableError(
+        "Chrome not found; set BrowserConfig(executable_path=...) explicitly"
+    )
+
+
+def find_botonomus_chromium(
+    version: str | None = None, *, cache_dir: Path | None = None
+) -> Path | None:
+    """Return the executable of an installed Botonomus Chromium build, if any.
+
+    Not consulted by `find_chrome`; callers decide the precedence between an
+    installed Botonomus build and Google Chrome.
+
+    Args:
+        version: A specific build version, or ``None`` for the newest installed.
+        cache_dir: Botonomus data directory; ``None`` uses the default location.
+
+    Returns:
+        The executable path, or ``None`` if no matching build is installed.
+
+    Raises:
+        ConfigurationError: If ``version`` is malformed.
+    """
+    return installer.find_installed(version, cache_dir=cache_dir)
+
+
+def is_testing_build(executable: Path) -> bool:
+    """Whether ``executable`` looks like Chrome for Testing or a Playwright download.
+
+    Those builds show a permanent "only for automated testing" infobar, which also
+    shrinks the viewport, and are not what ordinary users run.
+    """
+    text = str(executable).replace("\\", "/").lower()
+    return "ms-playwright" in text or "chrome for testing" in text or "chrome-win64/" in text
+
+
+def _chrome_candidates() -> list[Path]:
+    candidates: list[Path] = []
+    if sys.platform == "win32":
+        for key in ("PROGRAMFILES", "PROGRAMFILES(X86)", "LOCALAPPDATA"):
+            if root := os.environ.get(key):
+                candidates.append(Path(root) / "Google/Chrome/Application/chrome.exe")
+    elif sys.platform == "darwin":
+        candidates.append(Path("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"))
+    for name in ("google-chrome", "google-chrome-stable", "chrome"):
+        if found := shutil.which(name):
+            candidates.append(Path(found))
+    return candidates