osn-selenium 0.0.0__py3-none-any.whl

osn_selenium/webdrivers/Chrome/flags.py

@@ -0,0 +1,192 @@
+import pathlib
+from typing import (
+	Optional,
+	TypedDict,
+	Union
+)
+from selenium.webdriver.chrome.options import Options
+from osn_selenium.webdrivers.types import (
+	FlagDefinition,
+	FlagType
+)
+from osn_selenium.webdrivers.Blink.flags import (
+	BlinkArguments,
+	BlinkAttributes,
+	BlinkExperimentalOptions,
+	BlinkFeatures,
+	BlinkFlagsManager
+)
+
+
+class ChromeFlagsManager(BlinkFlagsManager):
+	"""
+	Manages Chrome Browser-specific options for Selenium WebDriver.
+
+	This class extends BrowserOptionsManager to provide specific configurations
+	for Chrome Browser options, such as experimental options and arguments.
+
+	Attributes:
+	"""
+	
+	def __init__(
+			self,
+			browser_exe: Optional[Union[str, pathlib.Path]] = None,
+			start_page_url: Optional[str] = None,
+			flags_types: Optional[dict[str, FlagType]] = None,
+			flags_definitions: Optional[dict[str, FlagDefinition]] = None
+	):
+		"""
+		Initializes ChromeOptionsManager.
+
+		Sets up the Chrome Browser options manager with specific option configurations for
+		debugging port, user agent, proxy, and BiDi protocol.
+		"""
+		
+		yandex_flags_types = {}
+		
+		if flags_types is not None:
+			yandex_flags_types.update(flags_types)
+		
+		yandex_flags_definitions = {}
+		
+		if flags_definitions is not None:
+			yandex_flags_definitions.update(flags_definitions)
+		
+		super().__init__(
+				browser_exe=browser_exe,
+				start_page_url=start_page_url,
+				flags_types=yandex_flags_types,
+				flags_definitions=yandex_flags_definitions,
+		)
+	
+	def _renew_webdriver_options(self) -> Options:
+		"""
+		Creates and returns a new Options object.
+
+		Returns a fresh instance of `webdriver.ChromeOptions`, as Chrome Browser is based on Chromium,
+		allowing for a clean state of browser options to be configured.
+
+		Returns:
+			Options: A new Selenium Chrome Browser options object, based on ChromeOptions.
+		"""
+		
+		return Options()
+
+
+class ChromeAttributes(BlinkAttributes, total=False):
+	"""
+	Typed dictionary for WebDriver attributes specific to Chrome browsers.
+
+	Attributes:
+		enable_bidi (Optional[bool]): Enables/disables BiDi (Bidirectional) protocol mapper.
+	"""
+	
+	pass
+
+
+class ChromeExperimentalOptions(BlinkExperimentalOptions, total=False):
+	"""
+	Typed dictionary for experimental options specific to Chrome browsers.
+
+	Attributes:
+		debugger_address (Optional[str]): The address (IP:port) of the remote debugger.
+	"""
+	
+	pass
+
+
+class ChromeArguments(BlinkArguments, total=False):
+	"""
+	Typed dictionary for command-line arguments specific to Chrome browsers.
+
+	Attributes:
+		se_downloads_enabled (bool): Enables/disables Selenium downloads.
+		headless_mode (bool): Runs the browser in headless mode (without a UI).
+		mute_audio (bool): Mutes audio output from the browser.
+		no_first_run (bool): Prevents the browser from showing the "first run" experience.
+		disable_background_timer_throttling (bool): Disables throttling of background timers.
+		disable_backgrounding_occluded_windows (bool): Prevents backgrounding of occluded windows.
+		disable_hang_monitor (bool): Disables the browser's hang monitor.
+		disable_ipc_flooding_protection (bool): Disables IPC flooding protection.
+		disable_renderer_backgrounding (bool): Prevents renderer processes from being backgrounded.
+		disable_back_forward_cache (bool): Disables the Back-Forward Cache.
+		disable_notifications (bool): Disables web notifications.
+		disable_popup_blocking (bool): Disables the built-in popup blocker.
+		disable_prompt_on_repost (bool): Disables the prompt when reposting form data.
+		disable_sync (bool): Disables browser synchronization features.
+		disable_background_networking (bool): Disables background network activity.
+		disable_breakpad (bool): Disables the crash reporter.
+		disable_component_update (bool): Disables component updates.
+		disable_domain_reliability (bool): Disables domain reliability monitoring.
+		disable_new_content_rendering_timeout (bool): Disables timeout for new content rendering.
+		disable_threaded_animation (bool): Disables threaded animation.
+		disable_threaded_scrolling (bool): Disables threaded scrolling.
+		disable_checker_imaging (bool): Disables checker imaging.
+		disable_image_animation_resync (bool): Disables image animation resynchronization.
+		disable_partial_raster (bool): Disables partial rasterization.
+		disable_skia_runtime_opts (bool): Disables Skia runtime optimizations.
+		disable_dev_shm_usage (bool): Disables the use of /dev/shm (important for Docker).
+		disable_gpu (bool): Disables GPU hardware acceleration.
+		aggressive_cache_discard (bool): Enables aggressive discarding of cached data.
+		allow_running_insecure_content (bool): Allows running insecure content on HTTPS pages.
+		no_process_per_site (bool): Runs all sites in a single process (less secure, but saves memory).
+		enable_precise_memory_info (bool): Enables precise memory information reporting.
+		use_fake_device_for_media_stream (bool): Uses a fake camera/microphone for media streams.
+		use_fake_ui_for_media_stream (bool): Uses a fake UI for media stream requests.
+		deny_permission_prompts (bool): Automatically denies all permission prompts.
+		disable_external_intent_requests (bool): Disables external intent requests.
+		noerrdialogs (bool): Suppresses error dialogs.
+		enable_automation (bool): Enables automation features.
+		test_type (bool): Sets the browser to test mode.
+		remote_debugging_pipe (bool): Uses a pipe for remote debugging instead of a port.
+		silent_debugger_extension_api (bool): Silences debugger extension API warnings.
+		enable_logging_stderr (bool): Enables logging to stderr.
+		password_store_basic (bool): Uses a basic password store.
+		use_mock_keychain (bool): Uses a mock keychain for testing.
+		enable_crash_reporter_for_testing (bool): Enables crash reporter for testing purposes.
+		metrics_recording_only (bool): Records metrics without sending them.
+		no_pings (bool): Disables sending pings.
+		allow_pre_commit_input (bool): Allows pre-commit input.
+		deterministic_mode (bool): Runs the browser in a more deterministic mode.
+		run_all_compositor_stages_before_draw (bool): Runs all compositor stages before drawing.
+		enable_begin_frame_control (bool): Enables begin frame control.
+		in_process_gpu (bool): Runs the GPU process in-process.
+		block_new_web_contents (bool): Blocks new web contents (e.g., pop-ups).
+		new_window (bool): Opens a new window instead of a new tab.
+		no_service_autorun (bool): Disables service autorun.
+		process_per_tab (bool): Runs each tab in its own process.
+		single_process (bool): Runs the browser in a single process (less stable).
+		no_sandbox (bool): Disables the sandbox (less secure, but can fix some issues).
+		user_agent (Optional[str]): Sets a custom user agent string.
+		user_data_dir (Optional[str]): Specifies the user data directory.
+		proxy_server (Optional[str]): Specifies a proxy server to use.
+		remote_debugging_port (Optional[int]): Specifies the remote debugging port.
+		remote_debugging_address (Optional[str]): Specifies the remote debugging address.
+		use_file_for_fake_video_capture (Optional[Union[str, pathlib.Path]]): Uses a file for fake video capture.
+		autoplay_policy (Optional[AutoplayPolicyType]): Sets the autoplay policy.
+		log_level (Optional[LogLevelType]): Sets the browser's log level.
+		use_gl (Optional[UseGLType]): Specifies the GL backend to use.
+		force_color_profile (Optional[str]): Forces a specific color profile.
+	"""
+	
+	pass
+
+
+class ChromeFlags(TypedDict, total=False):
+	"""
+	Typed dictionary representing a collection of all flag types for Chrome browsers.
+
+	This combines arguments, experimental options, attributes, and Blink features
+	that are specific to Chrome browsers.
+
+	Attributes:
+		argument (ChromeArguments): Command-line arguments for the Chrome browser.
+		experimental_option (ChromeExperimentalOptions): Experimental options for WebDriver specific to Chrome.
+		attribute (ChromeAttributes): WebDriver attributes specific to Chrome.
+		blink_feature (BlinkFeatures): Blink-specific feature flags.
+	"""
+	
+	argument: ChromeArguments
+	experimental_option: ChromeExperimentalOptions
+	attribute: ChromeAttributes
+	blink_feature: BlinkFeatures

osn_selenium/webdrivers/Chrome/protocols.py

@@ -0,0 +1,228 @@
+import pathlib
+from selenium import webdriver
+from osn_selenium.types import WindowRect
+from osn_selenium.webdrivers.types import _any_flags_mapping
+from osn_selenium.webdrivers.Chrome.flags import ChromeFlagsManager
+from typing import (
+	Optional,
+	Protocol,
+	TYPE_CHECKING,
+	Union,
+	runtime_checkable
+)
+from osn_selenium.webdrivers.Blink.protocols import (
+	TrioBlinkWebDriverWrapperProtocol
+)
+
+
+if TYPE_CHECKING:
+	from osn_selenium.webdrivers.Chrome.webdriver import ChromeWebDriver, ChromeFlags
+
+
+@runtime_checkable
+class TrioChromeWebDriverWrapperProtocol(TrioBlinkWebDriverWrapperProtocol, Protocol):
+	"""
+	Wraps ChromeWebDriver methods for asynchronous execution using Trio.
+
+	This class acts as a proxy to a `BrowserWebDriver` instance. It intercepts
+	method calls and executes them in a separate thread using `trio.to_thread.run_sync`,
+	allowing synchronous WebDriver operations to be called from asynchronous Trio code
+	without blocking the event loop. Properties and non-callable attributes are accessed directly.
+
+	Attributes:
+		_webdriver (BrowserWebDriver): The underlying synchronous BrowserWebDriver instance.
+		_excluding_functions (list[str]): A list of attribute names on the wrapped object
+											  that should *not* be accessible through this wrapper,
+											  typically because they are irrelevant or dangerous
+											  in an async context handled by the wrapper.
+	"""
+	
+	_webdriver: "ChromeWebDriver"
+	_webdriver_flags_manager: "ChromeFlagsManager"
+	_driver: Optional[webdriver.Chrome]
+	
+	@property
+	def driver(self) -> Optional[webdriver.Chrome]:
+		"""
+		Gets the underlying Selenium WebDriver instance associated with this object.
+
+		This property provides direct access to the WebDriver object (e.g., Chrome)
+		that is being controlled, allowing for direct Selenium operations if needed.
+
+		Returns:
+			Optional[webdriver.Chrome]:
+				The active WebDriver instance, or None if no driver is currently set or active.
+		"""
+		
+		...
+	
+	def reset_settings(
+			self,
+			flags: Optional[Union["ChromeFlags", _any_flags_mapping]] = None,
+			browser_exe: Optional[Union[str, pathlib.Path]] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: str = "",
+			window_rect: Optional[WindowRect] = None,
+			trio_tokens_limit: Union[int, float] = 40,
+	):
+		"""
+		Resets various configurable browser settings to their specified or default values.
+
+		This method allows for reconfiguring the WebDriver's operational parameters,
+		such as browser flags, executable path, start URL, window dimensions, and
+		concurrency limits. It is crucial that the browser session is *not* active
+		when this method is called; otherwise, a warning will be issued, and no changes
+		will be applied.
+
+		Args:
+			flags (Optional[Union[ChromeFlags, Mapping[str, Any]]]): New browser flags to apply.
+				If provided, existing flags are cleared and replaced with these.
+				If `None`, all custom flags are cleared, and the browser will start with default flags.
+			browser_exe (Optional[Union[str, pathlib.Path]]): The explicit path to the browser executable.
+				If provided, this path will be used. If `None`, the executable path managed by the
+				flags manager will be cleared, and then potentially re-detected based on
+				`use_browser_exe` and `browser_name_in_system`.
+			browser_name_in_system (Optional[str]): The common name of the browser (e.g., "Chrome", "Edge").
+				Used in conjunction with `use_browser_exe` to automatically detect the browser executable path.
+				This parameter only takes effect if `use_browser_exe` is explicitly `True` or `False`.
+				If `None`, no automatic detection based on name will occur through this method call.
+			use_browser_exe (Optional[bool]): Controls the automatic detection of the browser executable.
+				If `True` (and `browser_name_in_system` is provided), the browser executable path
+				will be automatically detected if `browser_exe` is `None`.
+				If `False` (and `browser_name_in_system` is provided), any existing `browser_exe`
+				path in the flags manager will be cleared.
+				If `None`, the current `use_browser_exe` state is maintained for the `_detect_browser_exe` logic.
+			start_page_url (str): The URL that the browser will attempt to navigate to
+				immediately after starting. Defaults to an empty string.
+			window_rect (Optional[WindowRect]): The initial window size and position settings.
+				If `None`, it defaults to a new `WindowRect()` instance, effectively resetting
+				to the browser's default window behavior.
+			trio_tokens_limit (Union[int, float]): The maximum number of concurrent synchronous
+				WebDriver operations allowed by the Trio capacity limiter. Defaults to 40.
+		"""
+		
+		...
+	
+	def restart_webdriver(
+			self,
+			flags: Optional[Union["ChromeFlags", _any_flags_mapping]] = None,
+			browser_exe: Optional[Union[str, pathlib.Path]] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+			trio_tokens_limit: Optional[Union[int, float]] = None,
+	):
+		"""
+		Restarts the WebDriver and browser session gracefully.
+
+		Performs a clean restart by first closing the existing WebDriver session and browser
+		(using `close_webdriver`), and then initiating a new session (using `start_webdriver`)
+		with potentially updated settings. If settings arguments are provided, they override
+		the existing settings for the new session; otherwise, the current settings are used.
+
+		Args:
+			flags (Optional[Union[ChromeFlags, Mapping[str, Any]]]): Override flags for the new session.
+				If provided, these flags will be applied. If `None`, current settings are used.
+			browser_exe (Optional[Union[str, pathlib.Path]]): Override browser executable for the new session.
+				If provided, this path will be used. If `None`, current settings are used.
+			browser_name_in_system (Optional[str]): Override browser name for auto-detection for the new session.
+				Only takes effect if `use_browser_exe` is also provided. If `None`, current settings are used.
+			use_browser_exe (Optional[bool]): Override auto-detection behavior for the new session.
+				If provided, this boolean determines if the browser executable is auto-detected.
+				If `None`, current settings are used.
+			start_page_url (Optional[str]): Override start page URL for the new session.
+				If provided, this URL will be used. If `None`, current setting is used.
+			window_rect (Optional[WindowRect]): Override window rectangle for the new session.
+				If provided, these dimensions will be used. If `None`, current settings are used.
+			trio_tokens_limit (Optional[Union[int, float]]): Override Trio token limit for the new session.
+				If provided, this limit will be used. If `None`, current setting is used.
+		"""
+		
+		...
+	
+	def start_webdriver(
+			self,
+			flags: Optional[Union["ChromeFlags", _any_flags_mapping]] = None,
+			browser_exe: Optional[Union[str, pathlib.Path]] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+			trio_tokens_limit: Optional[Union[int, float]] = None,
+	):
+		"""
+		Starts the WebDriver service and the browser session.
+
+		Initializes and starts the WebDriver instance and the associated browser process.
+		It first updates settings based on provided parameters (if the driver is not already running),
+		checks if a browser process needs to be started, starts it if necessary using Popen,
+		waits for it to become active, and then creates the WebDriver client instance (`self.driver`).
+
+		Args:
+			flags (Optional[Union[ChromeFlags, Mapping[str, Any]]]): Override flags for this start.
+				If provided, these flags will be applied. If `None`, current settings are used.
+			browser_exe (Optional[Union[str, pathlib.Path]]): Override browser executable path for this start.
+				If provided, this path will be used. If `None`, current settings are used.
+			browser_name_in_system (Optional[str]): Override browser name for auto-detection for this start.
+				Only takes effect if `use_browser_exe` is also provided. If `None`, current settings are used.
+			use_browser_exe (Optional[bool]): Override auto-detection behavior for this start.
+				If provided, this boolean determines if the browser executable is auto-detected.
+				If `None`, current settings are used.
+			start_page_url (Optional[str]): Override start page URL for this start.
+				If provided, this URL will be used. If `None`, current setting is used.
+			window_rect (Optional[WindowRect]): Override window rectangle for this start.
+				If provided, these dimensions will be used. If `None`, current settings are used.
+			trio_tokens_limit (Optional[Union[int, float]]): Override Trio token limit for this start.
+				If provided, this limit will be used. If `None`, current setting is used.
+		"""
+		
+		...
+	
+	def update_settings(
+			self,
+			flags: Optional[Union["ChromeFlags", _any_flags_mapping]] = None,
+			browser_exe: Optional[Union[str, pathlib.Path]] = None,
+			browser_name_in_system: Optional[str] = None,
+			use_browser_exe: Optional[bool] = None,
+			start_page_url: Optional[str] = None,
+			window_rect: Optional[WindowRect] = None,
+			trio_tokens_limit: Optional[Union[int, float]] = None,
+	):
+		"""
+		Updates various browser settings selectively without resetting others.
+
+		This method allows for dynamic updating of browser settings. Only the settings
+		for which a non-None value is provided will be updated. Settings passed as `None`
+		will retain their current values. This method can be called whether the browser
+		is active or not, but some changes might only take effect after the browser is
+		restarted.
+
+		Args:
+			flags (Optional[Union[ChromeFlags, Mapping[str, Any]]]): New browser flags to update.
+				If provided, these flags will be merged with or overwrite existing flags
+				within the flags manager. If `None`, existing flags remain unchanged.
+			browser_exe (Optional[Union[str, pathlib.Path]]): The new path to the browser executable.
+				If provided, this path will be set in the flags manager. If `None`, the
+				current browser executable path remains unchanged.
+			browser_name_in_system (Optional[str]): The common name of the browser (e.g., "Chrome", "Edge").
+				Used in conjunction with `use_browser_exe` to automatically detect the browser executable path.
+				This parameter only takes effect if `use_browser_exe` is explicitly provided.
+				If `None`, no automatic detection based on name will occur through this method call.
+			use_browser_exe (Optional[bool]): Controls the automatic detection of the browser executable.
+				If `True` (and `browser_name_in_system` is provided), the browser executable path
+				will be automatically detected if `browser_exe` is `None`.
+				If `False` (and `browser_name_in_system` is provided), any existing `browser_exe`
+				path in the flags manager will be cleared.
+				If `None`, the current `use_browser_exe` state is maintained for the `_detect_browser_exe` logic.
+			start_page_url (Optional[str]): The new URL that the browser will attempt to navigate to
+				immediately after starting. If `None`, the current start page URL remains unchanged.
+			window_rect (Optional[WindowRect]): The new window size and position settings.
+				If `None`, the current window rectangle settings remain unchanged.
+			trio_tokens_limit (Optional[Union[int, float]]): The new maximum number of concurrent
+				asynchronous operations allowed by the Trio capacity limiter. If `None`, the
+				current limit remains unchanged.
+		"""
+		
+		...