[py] PEP 484 type hints for selenium.webdriver.common.print_page_options (#9608)

Signed-off-by: oleg.hoefling <[email protected]>

Co-authored-by: David Burns <[email protected]>

Author: hoefling

py/selenium/webdriver/common/print_page_options.py

@@ -15,30 +15,66 @@
 # specific language governing permissions and limitations
 # under the License.
 
-
-class PrintOptions():
+import sys
+from typing import TYPE_CHECKING, List, Optional
+
+# necessary to support types for Python 3.7
+if TYPE_CHECKING:
+    if sys.version_info >= (3, 8):
+        from typing import Literal, TypedDict
+    else:
+        from typing_extensions import Literal, TypedDict
+
+    Orientation = Literal['portrait', 'landscape']
+
+    class _MarginOpts(TypedDict, total=False):
+        left: float
+        right: float
+        top: float
+        bottom: float
+
+    class _PageOpts(TypedDict, total=False):
+        width: float
+        height: float
+
+    class _PrintOpts(TypedDict, total=False):
+        margin: _MarginOpts
+        page: _PageOpts
+        background: bool
+        orientation: Orientation
+        scale: float
+        shrinkToFit: bool
+        pageRanges: List[str]
+else:
+    from typing import Any, Dict
+
+    Orientation = str
+    _MarginOpts = _PageOpts = _PrintOpts = Dict[str, Any]
+
+
+class PrintOptions:
     ORIENTATION_VALUES = ['portrait', 'landscape']
 
-    def __init__(self):
-        self._print_options = {}
-        self._page = {}
-        self._margin = {}
+    def __init__(self) -> None:
+        self._print_options: _PrintOpts = {}
+        self._page: _PageOpts = {}
+        self._margin: _MarginOpts = {}
 
-    def to_dict(self):
+    def to_dict(self) -> _PrintOpts:
         """
         :Returns: A hash of print options configured
         """
         return self._print_options
 
     @property
-    def orientation(self):
+    def orientation(self) -> Optional[Orientation]:
         """
         :Returns: Orientation that was set for the page
         """
         return self._print_options.get('orientation', None)
 
     @orientation.setter
-    def orientation(self, value):
+    def orientation(self, value: Orientation) -> None:
         """
         Allows you to set orientation of the page
         :Args:
@@ -50,14 +86,14 @@ def orientation(self, value):
         self._print_options['orientation'] = value
 
     @property
-    def scale(self):
+    def scale(self) -> Optional[float]:
         """
         :Returns: Scale that was set for the page
         """
         return self._print_options.get('scale', None)
 
     @scale.setter
-    def scale(self, value):
+    def scale(self, value: float) -> None:
         """
         Allows you to to set scale for the page
         :Args:
@@ -71,14 +107,14 @@ def scale(self, value):
         self._print_options['scale'] = value
 
     @property
-    def background(self):
+    def background(self) -> Optional[bool]:
         """
         :Returns: Background value that was set
         """
         return self._print_options.get('background', None)
 
     @background.setter
-    def background(self, value):
+    def background(self, value: bool) -> None:
         """
         Allows you to set the boolean value for the background
         :Args:
@@ -89,14 +125,14 @@ def background(self, value):
         self._print_options['background'] = value
 
     @property
-    def page_width(self):
+    def page_width(self) -> Optional[float]:
         """
         :Returns: Page width that was set
         """
         return self._page.get('width', None)
 
     @page_width.setter
-    def page_width(self, value):
+    def page_width(self, value: float) -> None:
         """
         Allows you to set width of the page
         :Args:
@@ -108,14 +144,14 @@ def page_width(self, value):
         self._print_options['page'] = self._page
 
     @property
-    def page_height(self):
+    def page_height(self) -> Optional[float]:
         """
         :Returns: Page height that was set
         """
         return self._page.get('height', None)
 
     @page_height.setter
-    def page_height(self, value):
+    def page_height(self, value: float) -> None:
         """
         Allows you to set height of the page
         :Args:
@@ -127,14 +163,14 @@ def page_height(self, value):
         self._print_options['page'] = self._page
 
     @property
-    def margin_top(self):
+    def margin_top(self) -> Optional[float]:
         """
         :Returns: Top margin of the page
         """
         return self._margin.get('top', None)
 
     @margin_top.setter
-    def margin_top(self, value):
+    def margin_top(self, value: float) -> None:
         """
         Allows you to set top margin of the page
         :Args:
@@ -146,14 +182,14 @@ def margin_top(self, value):
         self._print_options['margin'] = self._margin
 
     @property
-    def margin_left(self):
+    def margin_left(self) -> Optional[float]:
         """
         :Returns: Left margin of the page
         """
         return self._margin.get('left', None)
 
     @margin_left.setter
-    def margin_left(self, value):
+    def margin_left(self, value: float) -> None:
         """
         Allows you to set left margin of the page
         :Args:
@@ -165,14 +201,14 @@ def margin_left(self, value):
         self._print_options['margin'] = self._margin
 
     @property
-    def margin_bottom(self):
+    def margin_bottom(self) -> Optional[float]:
         """
         :Returns: Bottom margin of the page
         """
         return self._margin.get('bottom', None)
 
     @margin_bottom.setter
-    def margin_bottom(self, value):
+    def margin_bottom(self, value: float) -> None:
         """
         Allows you to set bottom margin of the page
         :Args:
@@ -184,14 +220,14 @@ def margin_bottom(self, value):
         self._print_options['margin'] = self._margin
 
     @property
-    def margin_right(self):
+    def margin_right(self) -> Optional[float]:
         """
         :Returns: Right margin of the page
         """
         return self._margin.get('right', None)
 
     @margin_right.setter
-    def margin_right(self, value):
+    def margin_right(self, value: float) -> None:
         """
         Allows you to set right margin of the page
         :Args:
@@ -203,14 +239,14 @@ def margin_right(self, value):
         self._print_options['margin'] = self._margin
 
     @property
-    def shrink_to_fit(self):
+    def shrink_to_fit(self) -> Optional[bool]:
         """
         :Returns: Value set for shrinkToFit
         """
         return self._print_options.get('shrinkToFit', None)
 
     @shrink_to_fit.setter
-    def shrink_to_fit(self, value):
+    def shrink_to_fit(self, value: bool) -> None:
         """
         Allows you to set shrinkToFit
         :Args:
@@ -221,14 +257,14 @@ def shrink_to_fit(self, value):
         self._print_options['shrinkToFit'] = value
 
     @property
-    def page_ranges(self):
+    def page_ranges(self) -> Optional[List[str]]:
         """
         :Returns: value set for pageRanges
         """
         return self._print_options.get('pageRanges', None)
 
     @page_ranges.setter
-    def page_ranges(self, value):
+    def page_ranges(self, value: List[str]) -> None:
         """
         Allows you to set pageRanges for the print command
         :Args:
@@ -238,11 +274,11 @@ def page_ranges(self, value):
             raise ValueError('Page ranges should be a list')
         self._print_options['pageRanges'] = value
 
-    def __validate_num_property(self, property_name, value):
+    def __validate_num_property(self, property_name: str, value: float) -> None:
         """
         Helper function to validate some of the properties
         """
-        if not isinstance(value, float) and not isinstance(value, int):
+        if not isinstance(value, (int, float)):
             raise ValueError(f'{property_name} should be an integer or a float')
 
         if value < 0:

py/selenium/webdriver/remote/webdriver.py

@@ -21,7 +21,7 @@
 
 import pkgutil
 import sys
-from typing import Dict, List, Union
+from typing import Dict, List, Optional, Union
 
 import warnings
 
@@ -48,6 +48,7 @@
 from selenium.webdriver.common.timeouts import Timeouts
 from selenium.webdriver.common.html5.application_cache import ApplicationCache
 from selenium.webdriver.support.relative_locator import RelativeBy
+from selenium.webdriver.common.print_page_options import PrintOptions
 
 
 _W3C_CAPABILITY_NAMES = frozenset([
@@ -906,7 +907,7 @@ def minimize_window(self) -> None:
         """
         self.execute(Command.MINIMIZE_WINDOW)
 
-    def print_page(self, print_options=None) -> str:
+    def print_page(self, print_options: Optional[PrintOptions] = None) -> str:
         """
         Takes PDF of the current page.
         The driver makes a best effort to return a PDF based on the provided parameters.