pythonlib: Add headless detection warning #26 0.2.7

Raises a warning when headless mode is enabled in Camoufox.
This will be reverted once #26 is resolved.

pythonlib/README.md

@@ -127,7 +127,8 @@ Parameters:
         Firefox version to use. Defaults to the current Camoufox version.
         To prevent leaks, only use this for special cases.
     headless (Optional[bool]):
-        Whether to run the browser in headless mode. Defaults to True.
+        Whether to run the browser in headless mode. Defaults to False.
+        WARNING: Please avoid using headless mode until issue #26 is fixed.
     executable_path (Optional[str]):
         Custom Camoufox browser executable path.
     firefox_user_prefs (Optional[Dict[str, Any]]):

pythonlib/camoufox/async_api.py

@@ -106,7 +106,8 @@ async def AsyncNewBrowser(
             Firefox version to use. Defaults to the current Camoufox version.
             To prevent leaks, only use this for special cases.
         headless (Optional[bool]):
-            Whether to run the browser in headless mode. Defaults to True.
+            Whether to run the browser in headless mode. Defaults to False.
+            WARNING: Please avoid using headless mode until issue #26 is fixed.
         executable_path (Optional[str]):
             Custom Camoufox browser executable path.
         firefox_user_prefs (Optional[Dict[str, Any]]):

pythonlib/camoufox/exceptions.py

@@ -116,3 +116,11 @@ class InvalidOS(ValueError):
     """
 
     ...
+
+
+class DetectionWarning(RuntimeWarning):
+    """
+    Raised when a the user has a setting enabled that can cause detection.
+    """
+
+    ...

pythonlib/camoufox/sync_api.py

@@ -106,7 +106,8 @@ def NewBrowser(
             Firefox version to use. Defaults to the current Camoufox version.
             To prevent leaks, only use this for special cases.
         headless (Optional[bool]):
-            Whether to run the browser in headless mode. Defaults to True.
+            Whether to run the browser in headless mode. Defaults to False.
+            WARNING: Please avoid using headless mode until issue #26 is fixed.
         executable_path (Optional[str]):
             Custom Camoufox browser executable path.
         firefox_user_prefs (Optional[Dict[str, Any]]):

pythonlib/camoufox/utils.py

@@ -20,6 +20,7 @@ from .addons import (
     threaded_try_load_addons,
 )
 from .exceptions import (
+    DetectionWarning,
     InvalidOS,
     InvalidPropertyType,
     NonFirefoxFingerprint,
@@ -199,7 +200,8 @@ def check_custom_fingerprint(fingerprint: Fingerprint) -> None:
     warnings.warn(
         'Passing your own fingerprint is not recommended. '
         'BrowserForge fingerprints are automatically generated within Camoufox '
-        'based on the provided `os` and `screen` constraints. '
+        'based on the provided `os` and `screen` constraints.',
+        category=DetectionWarning,
     )
 
 
@@ -287,6 +289,17 @@ def get_launch_options(
     if firefox_user_prefs is None:
         firefox_user_prefs = {}
 
+    # Warn the user if headless is being used
+    # https://github.com/daijro/camoufox/issues/26
+    if headless:
+        warnings.warn(
+            'It is currently not recommended to use headless mode in Camoufox. '
+            'Some WAFs are able to detect headless browsers. The issue is currently being investigated.',
+            category=DetectionWarning,
+        )
+    elif headless is None:
+        headless = False
+
     # Assert the target OS is valid
     if os:
         check_valid_os(os)

pythonlib/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "poetry.core.masonry.api"
 
 [tool.poetry]
 name = "camoufox"
-version = "0.2.6"
+version = "0.2.7"
 description = "Wrapper around Playwright to help launch Camoufox"
 authors = ["daijro <daijro.dev@gmail.com>"]
 license = "MIT"