refactor: refactor screenshot path handling and enhance error checking

Author: thalissonvs

pydoll/browser/tab.py

@@ -385,7 +385,7 @@ async def refresh(
 
     async def take_screenshot(
         self,
-        path: str,
+        path: Optional[str] = None,
         quality: int = 100,
         as_base64: bool = False,
     ) -> Optional[str]:
@@ -402,8 +402,12 @@ async def take_screenshot(
 
         Raises:
             InvalidFileExtension: If file extension not supported.
+            ValueError: If path is None and as_base64 is False.
         """
-        output_extension = path.split('.')[-1]
+        if not path and not as_base64:
+            raise ValueError('path is required when as_base64 is False')
+
+        output_extension = path.split('.')[-1] if path else ScreenshotFormat.PNG
         if not ScreenshotFormat.has_value(output_extension):
             raise InvalidFileExtension(f'{output_extension} extension is not supported.')
 
@@ -417,9 +421,10 @@ async def take_screenshot(
         if as_base64:
             return screenshot_data
 
-        screenshot_bytes = decode_base64_to_bytes(screenshot_data)
-        async with aiofiles.open(path, 'wb') as file:
-            await file.write(screenshot_bytes)
+        if path:
+            screenshot_bytes = decode_base64_to_bytes(screenshot_data)
+            async with aiofiles.open(path, 'wb') as file:
+                await file.write(screenshot_bytes)
 
         return None
 
@@ -540,13 +545,15 @@ async def expect_file_chooser(
         Args:
             files: File path(s) for upload.
         """
+
         async def event_handler(event):
             await self._execute_command(
                 DomCommands.upload_files(
                     files=files,
                     backend_node_id=event['params']['backendNodeId'],
                 )
             )
+
         if self.page_events_enabled is False:
             _before_page_events_enabled = False
             await self.enable_page_events()

pydoll/commands/fetch_commands.py

@@ -69,9 +69,9 @@ def continue_request(  # noqa: PLR0913, PLR0917
             post_data (Optional[dict]): The body data to send with the fetch
                 request. Defaults to None.
             headers (Optional[list[HeaderEntry]]): A list of HTTP headers to include
-              in the fetch request. Defaults to None.
+                in the fetch request. Defaults to None.
             intercept_response (Optional[bool]): Indicates if the response
-              should be intercepted. Defaults to None.
+                should be intercepted. Defaults to None.
 
         Returns:
             Command[Response]: A command for continuing the fetch request.

pydoll/commands/input_commands.py

@@ -97,7 +97,7 @@ def dispatch_key_event(  # noqa: PLR0913, PLR0917, PLR0912
                  Not needed for 'keyUp' and 'rawKeyDown' events (default: "").
             unmodified_text: Text that would have been generated by the keyboard without modifiers
                            (except for shift). Useful for shortcut key handling (default: "").
-            keyIdentifier: Unique key identifier (e.g., 'U+0041') (default: "").
+            key_identifier: Unique key identifier (e.g., 'U+0041') (default: "").
             code: Unique DOM defined string value for each physical key (e.g., 'KeyA')
                 (default: "").
             key: Unique DOM defined string value describing the meaning of the key in the
@@ -180,30 +180,30 @@ def dispatch_mouse_event(  # noqa: PLR0913, PLR0917
                  - mouseWheel: Mouse wheel rotated
             x: X coordinate of the event relative to the main frame's viewport in CSS pixels.
             y: Y coordinate of the event relative to the main frame's viewport in CSS pixels.
-               0 refers to the top of the viewport, and Y increases going down.
+                0 refers to the top of the viewport, and Y increases going down.
             modifiers: Bit field representing pressed modifier keys. Values:
-                      Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
+                Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).
             timestamp: Time at which the event occurred, in seconds since epoch.
             button: Mouse button being pressed/released. Default is "none".
-                   Allowed values: "none", "left", "middle", "right", "back", "forward".
+                Allowed values: "none", "left", "middle", "right", "back", "forward".
             click_count: Number of times the mouse button was clicked (default: 0).
-                       For example, 2 for a double-click.
+                For example, 2 for a double-click.
             force: The normalized pressure, which has a range of [0,1] (default: 0).
-                  Used primarily for pressure-sensitive inputs.
+                Used primarily for pressure-sensitive inputs.
             tangential_pressure: The normalized tangential pressure, which has a range
-                               of [-1,1] (default: 0). Used for stylus input.
+                of [-1,1] (default: 0). Used for stylus input.
             tilt_x: The plane angle between the Y-Z plane and the plane containing both the stylus
-                  axis and the Y axis, in degrees of the range [-90,90]. A positive tiltX is
-                  to the right (default: 0).
+                axis and the Y axis, in degrees of the range [-90,90]. A positive tiltX is
+                to the right (default: 0).
             tilt_y: The plane angle between the X-Z plane and the plane containing both the stylus
-                  axis and the X axis, in degrees of the range [-90,90]. A positive tiltY is
-                  towards the user (default: 0).
+                axis and the X axis, in degrees of the range [-90,90]. A positive tiltY is
+                towards the user (default: 0).
             twist: The clockwise rotation of a pen stylus around its own major axis,
-                  in degrees in the range [0,359] (default: 0).
+                in degrees in the range [0,359] (default: 0).
             delta_x: X delta in CSS pixels for mouse wheel event (default: 0).
-                   Positive values scroll right.
+                Positive values scroll right.
             delta_y: Y delta in CSS pixels for mouse wheel event (default: 0).
-                   Positive values scroll up.
+                Positive values scroll up.
             pointer_type: Pointer type (default: "mouse"). Allowed values: "mouse", "pen".
 
         Returns:
@@ -317,7 +317,7 @@ def dispatch_drag_event(
                  - dragCancel: Fired when a drag operation is being canceled
             x: X coordinate of the event relative to the main frame's viewport in CSS pixels.
             y: Y coordinate of the event relative to the main frame's viewport in CSS pixels.
-               0 refers to the top of the viewport, and Y increases going down.
+                0 refers to the top of the viewport, and Y increases going down.
             data: Drag data containing items being dragged, their MIME types, and other information.
             modifiers: Bit field representing pressed modifier keys. Values:
                       Alt=1, Ctrl=2, Meta/Command=4, Shift=8 (default: 0).

pydoll/commands/network_commands.py

@@ -104,9 +104,6 @@ def clear_browser_cookies() -> Command[Response]:
         to simulate a fresh user session without any previously stored
         cookies that might affect the application's behavior.
 
-        Args:
-            None
-
         Returns:
             Command[Response]: A command to clear all cookies in the browser.
         """

pydoll/elements/__init__.py

@@ -55,7 +55,7 @@ async def find(  # noqa: PLR0913, PLR0917
         timeout: int = 0,
         find_all: bool = False,
         raise_exc: bool = True,
-        **attributes,
+        **attributes: dict[str, str],
     ) -> Union['WebElement', list['WebElement'], None]:
         """
         Find element(s) using combination of common HTML attributes.

pydoll/elements/mixins/find_elements_mixin.py

@@ -129,7 +129,7 @@ async def get_bounds_using_js(self) -> dict[str, int]:
         response = await self._execute_script(Scripts.BOUNDS, return_by_value=True)
         return json.loads(response['result']['result']['value'])
 
-    async def get_screenshot(self, path: str, quality: int = 100):
+    async def take_screenshot(self, path: str, quality: int = 100):
         """
         Capture screenshot of this element only.
 

pydoll/elements/web_element.py

@@ -0,0 +1 @@
+"""Chrome DevTools Protocol implementation."""

pydoll/protocol/__init__.py

@@ -0,0 +1 @@
+"""Browser domain implementation."""

pydoll/protocol/browser/__init__.py

@@ -0,0 +1 @@
+"""DOM domain implementation."""