Files
archived-camoufox/pythonlib/camoufox/async_api.py
T
icepaq d6540b52ce Service Test and Contributing Guides (#521)
* example files

* contributing guides

* simple service test

* run tests in sync

* update pr template

* pip updates

* Update README.md

* typo fixes

* undo pip package update lol

* upgraded service test

* undo injections

* test with proxies

* auto set timezone and proxy url

* delete checks bundle

* split up service tests

* split up build tests

* rename service tests to service tester

* Update CONTRIBUTING.md

* fix entry vs exit ip

* allow alpha versions

* fix patch issues on macos

* bidirectional patch

* Add note on experimental pip package
2026-03-15 21:31:49 -04:00

186 lines
6.5 KiB
Python

import asyncio
import json as _json
import urllib.request
from functools import partial
from typing import Any, Dict, List, Optional, Union, overload
from urllib.parse import urlparse
from playwright.async_api import (
Browser,
BrowserContext,
Playwright,
PlaywrightContextManager,
)
from typing_extensions import Literal
from camoufox.virtdisplay import VirtualDisplay
from .fingerprints import generate_context_fingerprint
from .utils import async_attach_vd, launch_options
class AsyncCamoufox(PlaywrightContextManager):
"""
Wrapper around playwright.async_api.PlaywrightContextManager that automatically
launches a browser and closes it when the context manager is exited.
"""
def __init__(self, **launch_options):
super().__init__()
self.launch_options = launch_options
self.browser: Optional[Union[Browser, BrowserContext]] = None
async def __aenter__(self) -> Union[Browser, BrowserContext]:
_playwright = await super().__aenter__()
self.browser = await AsyncNewBrowser(_playwright, **self.launch_options)
return self.browser
async def __aexit__(self, *args: Any):
if self.browser:
await self.browser.close()
await super().__aexit__(*args)
@overload
async def AsyncNewBrowser(
playwright: Playwright,
*,
from_options: Optional[Dict[str, Any]] = None,
persistent_context: Literal[False] = False,
**kwargs,
) -> Browser: ...
@overload
async def AsyncNewBrowser(
playwright: Playwright,
*,
from_options: Optional[Dict[str, Any]] = None,
persistent_context: Literal[True],
**kwargs,
) -> BrowserContext: ...
async def AsyncNewBrowser(
playwright: Playwright,
*,
headless: Optional[Union[bool, Literal['virtual']]] = None,
from_options: Optional[Dict[str, Any]] = None,
persistent_context: bool = False,
debug: Optional[bool] = None,
**kwargs,
) -> Union[Browser, BrowserContext]:
"""
Launches a new browser instance for Camoufox given a set of launch options.
Parameters:
from_options (Dict[str, Any]):
A set of launch options generated by `launch_options()` to use
persistent_context (bool):
Whether to use a persistent context.
**kwargs:
All other keyword arugments passed to `launch_options()`.
"""
if headless == 'virtual':
virtual_display = VirtualDisplay(debug=debug)
kwargs['virtual_display'] = virtual_display.get()
headless = False
else:
virtual_display = None
if not from_options:
from_options = await asyncio.get_event_loop().run_in_executor(
None,
partial(launch_options, headless=headless, debug=debug, **kwargs),
)
# Persistent context
if persistent_context:
context = await playwright.firefox.launch_persistent_context(**from_options)
return await async_attach_vd(context, virtual_display)
# Browser
browser = await playwright.firefox.launch(**from_options)
return await async_attach_vd(browser, virtual_display)
def _proxy_url_with_creds(proxy: Dict[str, str]) -> str:
"""Builds a proxy URL string with embedded credentials."""
parsed = urlparse(proxy.get("server", ""))
user = proxy.get("username", "")
pwd = proxy.get("password", "")
if user and pwd:
return f"{parsed.scheme}://{user}:{pwd}@{parsed.netloc}"
return proxy.get("server", "")
async def _resolve_proxy_geo(proxy: Dict[str, str]) -> Dict[str, Optional[str]]:
"""Queries ip-api.com through the proxy for the exit IP and timezone."""
proxy_url = _proxy_url_with_creds(proxy)
def _fetch() -> Dict[str, Optional[str]]:
handler = urllib.request.ProxyHandler({"http": proxy_url, "https": proxy_url})
opener = urllib.request.build_opener(handler)
try:
with opener.open("http://ip-api.com/json?fields=query,timezone", timeout=10) as resp:
data = _json.loads(resp.read())
return {"ip": data.get("query") or None, "timezone": data.get("timezone") or None}
except Exception:
return {"ip": None, "timezone": None}
return await asyncio.get_event_loop().run_in_executor(None, _fetch)
async def AsyncNewContext(
browser: Browser,
*,
preset: Optional[Dict[str, Any]] = None,
os: Optional[str] = None,
ff_version: Optional[str] = None,
webrtc_ip: Optional[str] = None,
proxy: Optional[Dict[str, str]] = None,
geolocation: Optional[Dict[str, float]] = None,
**context_kwargs: Any,
) -> BrowserContext:
"""
Creates a new browser context with a unique fingerprint identity.
Each context gets its own real fingerprint preset (navigator, screen, WebGL, fonts, etc.)
with unique seeds for audio, canvas, and font spacing noise. All values are applied
via addInitScript so they self-destruct before page scripts can detect them.
Parameters:
browser: A Browser instance from AsyncNewBrowser or AsyncCamoufox.
preset: A specific fingerprint preset dict to use. If None, picks randomly.
os: Target OS for preset selection ("windows", "macos", "linux").
ff_version: Firefox version string for UA patching.
webrtc_ip: IPv4 address to spoof for WebRTC ICE candidates.
proxy: Per-context proxy (Playwright format: {"server": "...", "username": "...", "password": "..."}).
geolocation: Per-context geolocation ({"latitude": float, "longitude": float}).
**context_kwargs: Additional Playwright new_context() options.
"""
# Auto-derive WebRTC IP and timezone from proxy's exit IP when not explicitly provided
if proxy and (not webrtc_ip or "timezone_id" not in context_kwargs):
geo = await _resolve_proxy_geo(proxy)
if not webrtc_ip:
webrtc_ip = geo["ip"]
if "timezone_id" not in context_kwargs and geo["timezone"]:
context_kwargs["timezone_id"] = geo["timezone"]
fp = await asyncio.get_event_loop().run_in_executor(
None,
lambda: generate_context_fingerprint(preset=preset, os=os, ff_version=ff_version, webrtc_ip=webrtc_ip),
)
# Merge generated context options with user overrides (user wins)
opts: Dict[str, Any] = {**fp['context_options'], **context_kwargs}
if proxy:
opts['proxy'] = proxy
if geolocation:
opts['geolocation'] = geolocation
opts.setdefault('permissions', ['geolocation'])
context = await browser.new_context(**opts)
await context.add_init_script(fp['init_script'])
return context