invisible-playwright 0.3.5__py3-none-any.whl

invisible_playwright/__init__.py

@@ -0,0 +1,68 @@
+"""invisible_playwright - Playwright wrapper for a patched Firefox with stealth profile.
+
+Quickstart:
+
+    from invisible_playwright import InvisiblePlaywright
+
+    with InvisiblePlaywright() as browser:        # random seed
+        page = browser.new_page()
+        page.goto("https://example.com")
+
+    with InvisiblePlaywright(seed=42) as browser: # deterministic
+        ...
+
+    with InvisiblePlaywright(humanize=True) as browser:  # human-like cursor motion
+        page = browser.new_page()
+        page.click("#submit")   # expanded into a Bezier trajectory
+"""
+# ── Import-time core assertion, and repair ───────────────────────────────────
+# Runs BEFORE every other import. Two questions, one check: is the installed
+# invisible-core new enough to carry a release seal at all, and is it the exact
+# version this distribution declares in pyproject? The expected version is read
+# back out of our own metadata, so it is written in exactly one place.
+#
+# A mismatch is REPAIRED, not just reported: the declared core is installed and
+# picked up in this process, so the script that just imported us keeps going.
+# That is only sound here, on the first line, while invisible_core has not been
+# imported by anyone yet; _pin.py captures exactly that fact before it imports
+# the core, and the repair refuses itself if the snapshot says otherwise. Every
+# failure of the repair falls back to the message it replaced.
+#
+# The comparison and the repair both live in invisible_core._pin, shared with the
+# profile manager so both products diagnose and fix an environment the same way.
+# Our _pin.py is the floor: it owns the three states a module inside the core
+# cannot report on (core absent, core present but unimportable, core present but
+# too damaged to derive its own version) and delegates everything else.
+from ._pin import enforce_core_pin as _enforce_core_pin
+_enforce_core_pin()
+
+from ._engine import assert_playwright_range as _assert_pw_range
+_assert_pw_range()
+
+from .config import get_default_args, get_default_stealth_prefs
+from .constants import BINARY_VERSION, FIREFOX_UPSTREAM_VERSION
+from ._geo import GeoTimezoneError, resolve_session_timezone
+from .download import ensure_binary, ensure_geoip_mmdb
+from .launcher import InvisiblePlaywright
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("invisible-playwright")
+except PackageNotFoundError:
+    # Editable / source checkout without an install record: fall back to a
+    # marker rather than risk shipping a stale hardcoded string.
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "InvisiblePlaywright",
+    "ensure_binary",
+    "ensure_geoip_mmdb",
+    "get_default_stealth_prefs",
+    "get_default_args",
+    "resolve_session_timezone",
+    "GeoTimezoneError",
+    "BINARY_VERSION",
+    "FIREFOX_UPSTREAM_VERSION",
+    "__version__",
+]

invisible_playwright/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+import sys
+
+sys.exit(main())

invisible_playwright/_engine.py

@@ -0,0 +1,90 @@
+"""Every route from a chosen path to a spawned Firefox goes through here.
+
+``binary_path=`` (and ``INVPW_BINARY_PATH``, which the test suite and the e2e
+scripts turn into ``binary_path=``) never reaches ``ensure_binary()``, so none
+of the download-side checks run on that route. The guard therefore sits on the
+resolved executable, not inside the fetcher.
+"""
+from __future__ import annotations
+
+import os
+import warnings
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+from pathlib import Path
+from typing import Optional, Union
+
+from invisible_core.download import ensure_binary
+from invisible_core.seal import EngineMismatch, active_seal, verify_engine
+
+
+def resolve_executable(binary_path: Optional[Union[str, Path]]) -> Path:
+    """binary_path= and INVPW_BINARY_PATH skip the download path entirely, so
+    the guard sits on the resolved executable, not inside the fetcher."""
+    seal = active_seal()
+    if binary_path:
+        return verify_engine(Path(binary_path), seal, source=f"binary_path={binary_path}")
+    return ensure_binary(seal=seal)
+
+
+def assert_wire_version(browser) -> None:
+    """Compare what the engine reports over the protocol with the seal.
+
+    browser.version is a cached property from the connection initializer
+    (Juggler Browser.getInfo -> MOZ_APP_VERSION_DISPLAY), so this costs zero
+    round trips and no pref can spoof it. It is the only check that also
+    catches a hand-edited application.ini. Not available on the persistent
+    context path, where Playwright exposes no Browser.
+    """
+    if browser is None:
+        return
+    seal = active_seal()
+    raw = getattr(browser, "version", "")
+    # Playwright types Browser.version as str. Anything else (a stub, a mock,
+    # a driver that did not populate the initializer) carries no evidence
+    # either way, and inventing a mismatch out of it would be a false alarm.
+    if not isinstance(raw, str):
+        return
+    reported = raw.split("/")[-1].strip()
+    if reported and reported != seal.upstream_version:
+        raise EngineMismatch(
+            "engine/seal mismatch after launch - the running browser is not the sealed build\n"
+            f"  protocol says: Firefox {reported}\n"
+            f"  seal says    : Firefox {seal.upstream_version} (tag {seal.tag}, "
+            f"build {seal.build_id})\n"
+            "  why          : application.ini can be edited; this value comes from the "
+            "running engine itself.\n"
+            "  fix          : python -m invisible_playwright fetch --force")
+
+
+def assert_playwright_range() -> None:
+    """The Juggler protocol schema is closed-world: a client outside the range
+    the binary was tested with dies at context creation, or silently loses a
+    feature. The range travels in the seal, so widening it does not need a
+    wrapper release."""
+    seal = active_seal()
+    if not seal.playwright_min or not seal.playwright_max:
+        return
+    try:
+        have = _pkg_version("playwright")
+    except PackageNotFoundError:
+        return
+
+    def t(v: str):
+        out = []
+        for part in v.split(".")[:3]:
+            digits = "".join(c for c in part if c.isdigit())
+            out.append(int(digits or 0))
+        return tuple(out + [0] * (3 - len(out)))
+
+    if t(seal.playwright_min) <= t(have) <= t(seal.playwright_max):
+        return
+    msg = (f"playwright {have} is outside the range this engine was tested with "
+           f"({seal.playwright_min} .. {seal.playwright_max}, from the seal for {seal.tag}).\n"
+           f"The Juggler protocol schema is closed-world: an untested client can kill every "
+           f"session at context creation.\n"
+           f'Run: pip install "playwright=={seal.playwright_max}"   '
+           f"(or set INVISIBLE_PLAYWRIGHT_SKEW=allow to proceed anyway)")
+    if os.environ.get("INVISIBLE_PLAYWRIGHT_SKEW") == "allow":
+        warnings.warn(msg, RuntimeWarning, stacklevel=2)
+    else:
+        raise RuntimeError(msg)

invisible_playwright/_fpforge/__init__.py

@@ -0,0 +1,17 @@
+"""Backward-compat shim - spostato in invisible_core._fpforge (alias completo).
+
+Aliasa il package E i suoi submodule agli stessi oggetti del core, cosi'
+``from invisible_playwright._fpforge.profile import Profile`` e
+``from invisible_core._fpforge.profile import Profile`` sono la STESSA classe
+(isinstance funziona) e i nomi privati restano accessibili.
+"""
+import sys as _sys
+import invisible_core._fpforge as _pkg
+from invisible_core._fpforge import profile as _profile
+from invisible_core._fpforge import _sampler as _sampler_mod
+from invisible_core._fpforge import _network as _network_mod
+
+_sys.modules[__name__] = _pkg
+_sys.modules[__name__ + ".profile"] = _profile
+_sys.modules[__name__ + "._sampler"] = _sampler_mod
+_sys.modules[__name__ + "._network"] = _network_mod

invisible_playwright/_geo.py

@@ -0,0 +1,4 @@
+"""Backward-compat shim - spostato in invisible_core._geo (alias completo)."""
+import sys as _sys
+from invisible_core import _geo as _mod
+_sys.modules[__name__] = _mod

invisible_playwright/_headless.py

@@ -0,0 +1,4 @@
+"""Backward-compat shim - spostato in invisible_core._headless (alias completo)."""
+import sys as _sys
+from invisible_core import _headless as _mod
+_sys.modules[__name__] = _mod

invisible_playwright/_pin.py

@@ -0,0 +1,143 @@
+"""Prelude for the core-pin assertion, then delegation to the core.
+
+THE COMPARISON IS NOT HERE. It lives in invisible_core._pin, because the other
+consumer of the core (the profile manager) asks the same question and two copies
+of the answer drift: the day the two products disagree about why an environment
+is broken, the check has stopped being a diagnosis. This module is the small
+part that genuinely cannot be delegated, plus name-bound wrappers so the rest of
+this package can keep calling the functions without repeating our own
+distribution name.
+
+WHAT CANNOT BE DELEGATED. A module inside invisible_core cannot report that
+invisible_core is absent, unimportable, or so damaged that it cannot derive its
+own version: by the time any line of it runs, it imported. So the import below
+is the whole floor, and its except branches classify the failure:
+
+  * ImportError naming a module under invisible_core - either the core is not
+    installed at all, or it is older than this check and ships no
+    invisible_core._pin (or no invisible_core._pin.enforce_core_pin). Those
+    cannot be told apart from here and do not need to be: one remedy fixes all
+    of them, `pip install --force-reinstall invisible-playwright`, which makes
+    pip resolve the core version from our own Requires-Dist. No version literal
+    in the message, so nothing here can drift out of step with pyproject.
+  * ImportError naming any other module - the core is installed and one of ITS
+    dependencies is missing. That is what `pip install --no-deps` leaves behind,
+    and reporting it as "invisible-core is not installed" sends the user to the
+    wrong package.
+  * anything else - the core is on disk and its import raised something that is
+    not an ImportError at all. Measured: delete invisible_core/seal.json and the
+    import dies with a raw FileNotFoundError naming an absolute path, because
+    invisible_core.__init__ reaches _version.py, which reads the seal. That is a
+    partial install, and without this branch it is the one broken state the user
+    sees as a traceback instead of a remedy.
+
+Both message sets are deliberately short and carry no version number: everything
+that needs one is on the other side of this import.
+
+WHY THE REPAIR IS NOT ATTEMPTED IN THIS FILE. enforce_core_pin() repairs a
+version mismatch by installing the declared version and picking it up in
+process. It can only do that because it knows WHICH version is declared, and
+that comes from the one requirement parser, which lives in the core. When the
+core cannot be imported at all there is no parser to ask, and the only remedy
+that needs no version literal is a force-reinstall of THIS distribution, i.e. of
+the package that is halfway through importing right now. Replacing your own
+files mid-import is not a repair, so this floor reports and stops.
+"""
+from __future__ import annotations
+
+import sys as _sys
+
+DIST_NAME = "invisible-playwright"
+
+# Captured BEFORE the core is imported, and it is the whole soundness argument
+# for the in-process repair: if nothing has imported invisible_core by the time
+# this package's __init__ starts, then nobody is holding an object from the
+# version the repair is about to replace. Read here, at the top of the first
+# module the package imports, because one line later it is always True.
+_CORE_PREIMPORTED = any(
+    name == "invisible_core" or name.startswith("invisible_core.")
+    for name in list(_sys.modules)
+)
+
+try:  # the floor - see the module docstring for why this is the one local part
+    from invisible_core._pin import (  # noqa: F401
+        CORE_NAME,
+        AUTOFIX_ENV,
+        SKIP_ENV,
+        PinDeclaration,
+        Requirement,
+        assert_core_pin as _assert_core_pin,
+        canonical_requirement,
+        declared_core_pin as _declared_core_pin,
+        editable_core_path,
+        enforce_core_pin as _enforce_core_pin,
+        installed_core_version,
+        normalise_name,
+        parse_requirement,
+        pin_declaration as _pin_declaration,
+        pin_from_requirements,
+        pin_problem,
+        pin_report as _pin_report,
+        recorded_core_version,
+        repair_core,
+    )
+except ImportError as _e:
+    _missing = getattr(_e, "name", "") or ""
+    if _missing and not _missing.startswith("invisible_core"):
+        raise ImportError(
+            f"invisible-core is installed but cannot be imported: no module named "
+            f"{_missing!r}.\n"
+            f"That is one of its own dependencies, so it was installed without "
+            f"dependency resolution (pip install --no-deps, or a lockfile that "
+            f"lists the packages separately).\n"
+            f"Run: pip install --force-reinstall {DIST_NAME}"
+        ) from _e
+    raise ImportError(
+        "invisible-core is missing, or too old for this invisible-playwright: it "
+        "does not carry the release-pin check (invisible_core._pin), so the engine "
+        "it downloads cannot be matched against the configuration this package "
+        "ships.\n"
+        f"Run: pip install --force-reinstall {DIST_NAME}"
+    ) from _e
+except Exception as _e:
+    raise ImportError(
+        f"invisible-core is installed but it cannot even determine its own version: "
+        f"importing it raised {type(_e).__name__}: {_e}\n"
+        f"That is a partial or damaged installation, not an old one. A missing or "
+        f"unreadable invisible_core/seal.json is the usual cause, and it is read "
+        f"while invisible_core is still importing, so nothing inside the core can "
+        f"report it.\n"
+        f"Run: pip install --force-reinstall {DIST_NAME}"
+    ) from _e
+
+
+def declared_core_pin(dist_name: str = DIST_NAME) -> "str | None":
+    """The `invisible-core==X` version THIS distribution declares, or None."""
+    return _declared_core_pin(dist_name)
+
+
+def pin_declaration(dist_name: str = DIST_NAME) -> PinDeclaration:
+    """The declaration and why it is or is not checkable."""
+    return _pin_declaration(dist_name)
+
+
+def pin_report(dist_name: str = DIST_NAME) -> dict:
+    """Non-raising form. Read ["verdict"], not ["ok"], to report health."""
+    return _pin_report(dist_name)
+
+
+def assert_core_pin(dist_name: str = DIST_NAME) -> None:
+    """Report-only form: raise ImportError when the core that will run is not the
+    one declared. Installs nothing. Used by the CLI and the tests."""
+    _assert_core_pin(dist_name)
+
+
+def enforce_core_pin(dist_name: str = DIST_NAME, *, stream=None) -> None:
+    """Import-time form: check, and repair the environment instead of only
+    reporting it. Raises ImportError only when it is still wrong afterwards.
+
+    The sys.modules snapshot taken at the top of this module is passed through:
+    it is the only evidence that no caller is already holding a core object, and
+    it stops being available the moment anything imports the core.
+    """
+    _enforce_core_pin(dist_name, core_preimported=_CORE_PREIMPORTED, stream=stream)

invisible_playwright/_proxy.py

@@ -0,0 +1,4 @@
+"""Backward-compat shim - spostato in invisible_core._proxy (alias completo)."""
+import sys as _sys
+from invisible_core import _proxy as _mod
+_sys.modules[__name__] = _mod