Merge branch 'main' into feat/tab-request-api-issue-171

Author: thalissonvs

pydoll/browser/chromium/base.py

@@ -2,6 +2,7 @@
 import json
 import os
 import shutil
+import warnings
 from abc import ABC, abstractmethod
 from contextlib import suppress
 from functools import partial
@@ -106,20 +107,24 @@ async def start(self, headless: bool = False) -> Tab:
         Start browser process and establish CDP connection.
 
         Args:
-            headless: Run without UI.
+            headless: Deprecated. Use `options.headless = True` instead.
 
         Returns:
             Initial tab for interaction.
 
         Raises:
             FailedToStartBrowser: If the browser fails to start or connect.
         """
-        binary_location = self.options.binary_location or self._get_default_binary_location()
-
         if headless:
-            headless_arg = '--headless'
-            if headless_arg not in self.options.arguments:
-                self.options.add_argument(headless_arg)
+            warnings.warn(
+                "The 'headless' parameter is deprecated and will be removed in a future version. "
+                "Use `options.headless = True` instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+            self.options.headless = headless
+
+        binary_location = self.options.binary_location or self._get_default_binary_location()
 
         self._setup_user_dir()
         proxy_config = self._proxy_manager.get_proxy_credentials()

pydoll/browser/interfaces.py

@@ -26,6 +26,16 @@ def add_argument(self, argument: str):
     def browser_preferences(self) -> dict:
         pass
 
+    @property
+    @abstractmethod
+    def headless(self) -> bool:
+        pass
+
+    @headless.setter
+    @abstractmethod
+    def headless(self, headless: bool):
+        pass
+
 
 class BrowserOptionsManager(ABC):
     @abstractmethod

pydoll/browser/options.py

@@ -1,7 +1,11 @@
 from contextlib import suppress
 
 from pydoll.browser.interfaces import Options
-from pydoll.exceptions import ArgumentAlreadyExistsInOptions, WrongPrefsDict
+from pydoll.exceptions import (
+    ArgumentAlreadyExistsInOptions,
+    ArgumentNotFoundInOptions,
+    WrongPrefsDict,
+)
 
 
 class ChromiumOptions(Options):
@@ -23,6 +27,7 @@ def __init__(self):
         self._binary_location = ''
         self._start_timeout = 10
         self._browser_preferences = {}
+        self._headless = False
 
     @property
     def arguments(self) -> list[str]:
@@ -99,6 +104,20 @@ def add_argument(self, argument: str):
         else:
             raise ArgumentAlreadyExistsInOptions(f'Argument already exists: {argument}')
 
+    def remove_argument(self, argument: str):
+        """
+        Removes a command-line argument from the options.
+
+        Args:
+            argument (str): The command-line argument to be removed.
+
+        Raises:
+            ArgumentNotFoundInOptions: If the argument is not in the list of arguments.
+        """
+        if argument not in self._arguments:
+            raise ArgumentNotFoundInOptions(f'Argument not found: {argument}')
+        self._arguments.remove(argument)
+
     @property
     def browser_preferences(self) -> dict:
         return self._browser_preferences
@@ -284,3 +303,19 @@ def open_pdf_externally(self, enabled: bool):
             block -- If True, location access is blocked (value = 2); otherwise allowed (value = 1).
         """
         self._set_pref_path(['plugins', 'always_open_pdf_externally'], enabled)
+
+    @property
+    def headless(self) -> bool:
+        return self._headless
+
+    @headless.setter
+    def headless(self, headless: bool):
+        self._headless = headless
+        has_argument = '--headless' in self.arguments
+        methods_map = {
+            True: self.add_argument,
+            False: self.remove_argument
+        }
+        if headless == has_argument:
+            return
+        methods_map[headless]('--headless')

pydoll/exceptions.py

@@ -199,6 +199,12 @@ class ArgumentAlreadyExistsInOptions(ConfigurationException):
     message = 'The argument already exists in the options'
 
 
+class ArgumentNotFoundInOptions(ConfigurationException):
+    """Raised when attempting to remove an argument that does not exist in browser options."""
+
+    message = 'The argument does not exist in the options'
+
+
 class InvalidFileExtension(ConfigurationException):
     """Raised when an unsupported file extension is provided."""