Skip to content

Deep Dive: Custom Browser Preferences in Pydoll

Overview

The browser_preferences feature (PR #204) enables direct, fine-grained control over Chromium browser settings via the ChromiumOptions API. This is essential for advanced automation, testing, and scraping scenarios where default browser behavior must be customized.

How It Works

  • ChromiumOptions.browser_preferences is a dictionary that maps directly to Chromium's internal preferences structure.
  • Preferences are merged: setting new keys updates only those keys, preserving others.
  • Helper methods (set_default_download_directory, set_accept_languages, etc.) are provided for common scenarios.
  • Preferences are applied before browser launch, ensuring all settings take effect from the start of the session.
  • Validation ensures only dictionaries are accepted; invalid structures raise clear errors.

Example

options = ChromiumOptions()
options.browser_preferences = {
    'download': {'default_directory': '/tmp', 'prompt_for_download': False},
    'intl': {'accept_languages': 'en-US,en'},
    'profile': {'default_content_setting_values': {'notifications': 2}}
}

Advanced Usage

  • Merging: Multiple assignments merge keys, so you can incrementally build your preferences.
  • Validation: If you pass a non-dict or use the reserved 'prefs' key, an error is raised.
  • Internals: Preferences are set via a recursive setter that creates nested dictionaries as needed.
  • Integration: Used by the browser process manager to initialize the user data directory with your custom settings.

Best Practices

  • Use helper methods for common patterns; set browser_preferences directly for advanced needs.
  • Check Chromium documentation for available preferences: https://chromium.googlesource.com/chromium/src/+/4aaa9f29d8fe5eac55b8632fa8fcb05a68d9005b/chrome/common/pref_names.cc
  • Avoid setting experimental or undocumented preferences unless you know their effects.

References

  • See pydoll/browser/options.py for implementation details.
  • See tests in tests/test_browser/test_browser_chrome.py for usage examples.