More warnings & reformat README to avoid confusion/misuse 0.2.14

- Warns the user if they try to manually set the geolocation and locale.
- Move manual config documentation to the bottom of the README to discourage use.
- Make the parameters list more obvious.

.gitignore

@@ -15,6 +15,7 @@ launch.exe
 pythonlib/*.png
 scripts/*.png
 test*
+.vscode
 
 # Old data
 _old/

pythonlib/README.md

@@ -90,16 +90,17 @@ async with AsyncCamoufox(headless=False) as browser:
     await page.goto("https://example.com")
 ```
 
+### Parameters List
+
 <details>
-<summary>Parameters</summary>
+
+<summary><strong>See parameters list...</strong></summary>
 
 ```
 Launches a new browser instance for Camoufox.
 Accepts all Playwright Firefox launch options, along with the following:
 
 Parameters:
-    config (Optional[Dict[str, Any]]):
-        Camoufox properties to use.
     os (Optional[ListOrString]):
         Operating system to use for the fingerprint generation.
         Can be "windows", "macos", "linux", or a list to randomly choose from.
@@ -130,12 +131,16 @@ Parameters:
         Constrains the screen dimensions of the generated fingerprint.
         Takes a browserforge.fingerprints.Screen instance.
     fingerprint (Optional[Fingerprint]):
-        Use a custom BrowserForge fingerprint. Note: Not all values will be implemented.
+        *WILL BE DEPRECATED SOON*
+        Pass a custom BrowserForge fingerprint. Note: Not all values will be implemented.
         If not provided, a random fingerprint will be generated based on the provided
         `os` & `screen` constraints.
     ff_version (Optional[int]):
         Firefox version to use. Defaults to the current Camoufox version.
         To prevent leaks, only use this for special cases.
+    config (Optional[Dict[str, Any]]):
+        Camoufox properties to use. Camoufox will warn you if you are manually setting
+        properties that it handles internally.
     headless (Union[bool, Literal['virtual']]):
         Whether to run the browser in headless mode. Defaults to False.
         If you are running linux, passing 'virtual' will use Xvfb.
@@ -164,27 +169,6 @@ Camoufox will warn you if your passed configuration might cause leaks.
 
 ---
 
-### Config
-
-Camoufox [config data](https://github.com/daijro/camoufox?tab=readme-ov-file#fingerprint-injection) can be passed as a dictionary to the `config` parameter:
-
-```python
-from camoufox.sync_api import Camoufox
-
-with Camoufox(
-    config={
-        'webrtc:ipv4': '123.45.67.89',
-        'webrtc:ipv6': 'e791:d37a:88f6:48d1:2cad:2667:4582:1d6d',
-    }
-) as browser:
-    page = browser.new_page()
-    page.goto("https://www.browserscan.net/webrtc")
-```
-
-This can be used to enable fetures that have not yet been implemented into the Python library. (You shouldn't use this for injecting device fingerprints. Device data is automatically populated.)
-
-<hr width=50>
-
 ### GeoIP & Proxy Support
 
 By passing `geoip=True`, or passing in a target IP address, Camoufox will automatically use the target IP's longitude, latitude, timezone, country, locale, & spoof the WebRTC IP address.
@@ -315,13 +299,9 @@ with Camoufox(
     page.goto("https://example.com/")
 ```
 
-**Notes:**
+If Camoufox is being ran in headful mode, the max screen size will be generated based on your monitor's dimensions unless otherwise specified.
 
-- If Camoufox is being ran in headful mode, the max screen size will be generated based on your monitor's dimensions unless otherwise specified.
+**Note:** To prevent UA mismatch detection, Camoufox only generates fingerprints with the same browser version as the current Camoufox version by default. If rotating the Firefox version is absolutely necessary, it would be more advisable to rotate between older versions of Camoufox instead.
-
-- To prevent UA-spoofing leaks, Camoufox only generates fingerprints with the same browser version as the current Camoufox version by default.
-
-  - If rotating the Firefox version is absolutely necessary, it would be more advisable to rotate between older versions of Camoufox instead.
 
 <details>
 <summary>Injecting custom Fingerprint objects...</summary>
@@ -347,4 +327,27 @@ with Camoufox(fingerprint=fg.generate()) as browser:
 
 </details>
 
+<hr width=50>
+
+### Config
+
+If needed, Camoufox [config data](https://github.com/daijro/camoufox?tab=readme-ov-file#fingerprint-injection) can be overridden/passed as a dictionary to the `config` parameter. This can be used to enable features that have not yet been implemented into the Python library.
+
+Although, this isn't recommended, as Camoufox will populate this data for you automatically. See the parameters list above for more proper usage.
+
+```python
+from camoufox.sync_api import Camoufox
+
+with Camoufox(
+    config={
+        'webrtc:ipv4': '123.45.67.89',
+        'webrtc:ipv6': 'e791:d37a:88f6:48d1:2cad:2667:4582:1d6d',
+    }
+) as browser:
+    page = browser.new_page()
+    page.goto("https://www.browserscan.net/webrtc")
+```
+
+Camoufox will warn you if you are manually setting properties that the Python library handles internally.
+
 ---

pythonlib/camoufox/utils.py

@@ -254,7 +254,7 @@ def is_domain_set(
     """
     for prop in properties:
         # If the . prefix exists, check if the domain is a prefix of any key in the config
-        if prop.endswith('.'):
+        if prop[-1] in ('.', ':'):
             if any(key.startswith(prop) for key in config):
                 return True
         # Otherwise, check if the domain is a direct key in the config
@@ -270,9 +270,12 @@ def warn_manual_config(config: Dict[str, Any]) -> None:
     """
     # Manual locale setting
     if is_domain_set(
-        config, 'navigator.language', 'navigator.languages', 'headers.Accept-Language'
+        config, 'navigator.language', 'navigator.languages', 'headers.Accept-Language', 'locale:'
     ):
         LeakWarning.warn('locale', False)
+    # Manual geolocation and timezone setting
+    if is_domain_set(config, 'geolocation:', 'timezone'):
+        LeakWarning.warn('geolocation', False)
     # Manual User-Agent setting
     if is_domain_set(config, 'headers.User-Agent'):
         LeakWarning.warn('header-ua', False)

pythonlib/camoufox/warnings.yml

@@ -6,6 +6,11 @@ navigator: >-
 locale: >-
     Use the `locale` parameter in Camoufox instead of setting the config manually.
 
+geolocation: >-
+    Please use the `geoip` parameter in Camoufox instead of setting your geolocation manually.
+    This can lead to detection if your target geolocation does not match your IP.
+    Pass `geoip=True` or a target IP (ex: geoip='123.45.67.89') to let Camoufox populate this data for you.
+
 header-ua: >-
     Do not set the header.User-Agent manually. Camoufox will generate a User-Agent for you.
 
@@ -34,13 +39,4 @@ ff_version: >-
 
 no_region: >-
     Because you did not pass in a locale region, Camoufox will generate one for you.
-    This can cause suspicion if your IP does not match your locale region.
+    This can cause suspicion if your IP does not match your locale region.
-
-# headless-non-linux: >-
-#     Headless mode is only recommended on Linux at this time.
-#     Some WAFs are able to detect headless browsers. The issue is currently being investigated.
-
-# headless-linux: >-
-#     Headless mode is only recommended on Linux with Xvfb installed.
-#     Please see the install guide here:
-#     https://github.com/daijro/camoufox/tree/main/pythonlib#virtual-display

pythonlib/pyproject.toml

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