chore: Use proper type declarations for methods returning self instances

Author: mykola-mokhnach

appium/webdriver/extensions/action_helpers.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, List, Optional, Tuple, cast
+from typing import TYPE_CHECKING, List, Optional, Self, Tuple, cast
 
 from selenium.webdriver.common.action_chains import ActionChains
 from selenium.webdriver.common.actions import interaction
@@ -23,11 +23,12 @@
 from appium.webdriver.webelement import WebElement
 
 if TYPE_CHECKING:
+    # noinspection PyUnresolvedReferences
     from appium.webdriver.webdriver import WebDriver
 
 
 class ActionHelpers:
-    def scroll(self, origin_el: WebElement, destination_el: WebElement, duration: Optional[int] = None) -> 'WebDriver':
+    def scroll(self, origin_el: WebElement, destination_el: WebElement, duration: Optional[int] = None) -> Self:
         """Scrolls from one element to another
 
         Args:
@@ -48,7 +49,7 @@ def scroll(self, origin_el: WebElement, destination_el: WebElement, duration: Op
 
         touch_input = PointerInput(interaction.POINTER_TOUCH, 'touch')
 
-        actions = ActionChains(self)
+        actions = ActionChains(cast('WebDriver', self))
         actions.w3c_actions = ActionBuilder(self, mouse=touch_input)
 
         # https://github.com/SeleniumHQ/selenium/blob/3c82c868d4f2a7600223a1b3817301d0b04d28e4/py/selenium/webdriver/common/actions/pointer_actions.py#L83
@@ -59,11 +60,9 @@ def scroll(self, origin_el: WebElement, destination_el: WebElement, duration: Op
         actions.w3c_actions.pointer_action.move_to(destination_el)
         actions.w3c_actions.pointer_action.release()
         actions.perform()
-        return cast('WebDriver', self)
+        return self
 
-    def drag_and_drop(
-        self, origin_el: WebElement, destination_el: WebElement, pause: Optional[float] = None
-    ) -> 'WebDriver':
+    def drag_and_drop(self, origin_el: WebElement, destination_el: WebElement, pause: Optional[float] = None) -> Self:
         """Drag the origin element to the destination element
 
         Args:
@@ -74,17 +73,17 @@ def drag_and_drop(
         Returns:
             Union['WebDriver', 'ActionHelpers']: Self instance
         """
-        actions = ActionChains(self)
+        actions = ActionChains(cast('WebDriver', self))
         # 'mouse' pointer action
         actions.w3c_actions.pointer_action.click_and_hold(origin_el)
         if pause is not None and pause > 0:
             actions.w3c_actions.pointer_action.pause(pause)
         actions.w3c_actions.pointer_action.move_to(destination_el)
         actions.w3c_actions.pointer_action.release()
         actions.perform()
-        return cast('WebDriver', self)
+        return self
 
-    def tap(self, positions: List[Tuple[int, int]], duration: Optional[int] = None) -> 'WebDriver':
+    def tap(self, positions: List[Tuple[int, int]], duration: Optional[int] = None) -> Self:
         """Taps on an particular place with up to five fingers, holding for a
         certain time
 
@@ -100,7 +99,7 @@ def tap(self, positions: List[Tuple[int, int]], duration: Optional[int] = None)
             Union['WebDriver', 'ActionHelpers']: Self instance
         """
         if len(positions) == 1:
-            actions = ActionChains(self)
+            actions = ActionChains(cast('WebDriver', self))
             actions.w3c_actions = ActionBuilder(self, mouse=PointerInput(interaction.POINTER_TOUCH, 'touch'))
             x = positions[0][0]
             y = positions[0][1]
@@ -114,7 +113,7 @@ def tap(self, positions: List[Tuple[int, int]], duration: Optional[int] = None)
             actions.perform()
         else:
             finger = 0
-            actions = ActionChains(self)
+            actions = ActionChains(cast('WebDriver', self))
             actions.w3c_actions.devices = []
 
             for position in positions:
@@ -132,9 +131,9 @@ def tap(self, positions: List[Tuple[int, int]], duration: Optional[int] = None)
                     new_input.create_pause(0.1)
                 new_input.create_pointer_up(MouseButton.LEFT)
             actions.perform()
-        return cast('WebDriver', self)
+        return self
 
-    def swipe(self, start_x: int, start_y: int, end_x: int, end_y: int, duration: int = 0) -> 'WebDriver':
+    def swipe(self, start_x: int, start_y: int, end_x: int, end_y: int, duration: int = 0) -> Self:
         """Swipe from one point to another point, for an optional duration.
 
         Args:
@@ -152,7 +151,7 @@ def swipe(self, start_x: int, start_y: int, end_x: int, end_y: int, duration: in
         """
         touch_input = PointerInput(interaction.POINTER_TOUCH, 'touch')
 
-        actions = ActionChains(self)
+        actions = ActionChains(cast('WebDriver', self))
         actions.w3c_actions = ActionBuilder(self, mouse=touch_input)
         actions.w3c_actions.pointer_action.move_to_location(start_x, start_y)
         actions.w3c_actions.pointer_action.pointer_down()
@@ -161,9 +160,9 @@ def swipe(self, start_x: int, start_y: int, end_x: int, end_y: int, duration: in
         actions.w3c_actions.pointer_action.move_to_location(end_x, end_y)
         actions.w3c_actions.pointer_action.release()
         actions.perform()
-        return cast('WebDriver', self)
+        return self
 
-    def flick(self, start_x: int, start_y: int, end_x: int, end_y: int) -> 'WebDriver':
+    def flick(self, start_x: int, start_y: int, end_x: int, end_y: int) -> Self:
         """Flick from one point to another point.
 
         Args:
@@ -178,11 +177,11 @@ def flick(self, start_x: int, start_y: int, end_x: int, end_y: int) -> 'WebDrive
         Returns:
             Union['WebDriver', 'ActionHelpers']: Self instance
         """
-        actions = ActionChains(self)
+        actions = ActionChains(cast('WebDriver', self))
         actions.w3c_actions = ActionBuilder(self, mouse=PointerInput(interaction.POINTER_TOUCH, 'touch'))
         actions.w3c_actions.pointer_action.move_to_location(start_x, start_y)
         actions.w3c_actions.pointer_action.pointer_down()
         actions.w3c_actions.pointer_action.move_to_location(end_x, end_y)
         actions.w3c_actions.pointer_action.release()
         actions.perform()
-        return cast('WebDriver', self)
+        return self

appium/webdriver/extensions/android/common.py

@@ -11,7 +11,7 @@
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 # See the License for the specific language governing permissions and
 # limitations under the License.
-from typing import TYPE_CHECKING, cast
+from typing import Self
 
 from selenium.common.exceptions import UnknownMethodException
 
@@ -20,12 +20,9 @@
 from appium.protocols.webdriver.can_remember_extension_presence import CanRememberExtensionPresence
 from appium.webdriver.mobilecommand import MobileCommand as Command
 
-if TYPE_CHECKING:
-    from appium.webdriver.webdriver import WebDriver
-
 
 class Common(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
-    def open_notifications(self) -> 'WebDriver':
+    def open_notifications(self) -> Self:
         """Open notification shade in Android (API Level 18 and above)
 
         Returns:
@@ -37,7 +34,7 @@ def open_notifications(self) -> 'WebDriver':
         except UnknownMethodException:
             # TODO: Remove the fallback
             self.mark_extension_absence(ext_name).execute(Command.OPEN_NOTIFICATIONS, {})
-        return cast('WebDriver', self)
+        return self
 
     @property
     def current_package(self) -> str:

appium/webdriver/extensions/android/gsm.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, cast
+from typing import Self
 
 from selenium.common.exceptions import UnknownMethodException
 
@@ -23,9 +23,6 @@
 from appium.protocols.webdriver.can_remember_extension_presence import CanRememberExtensionPresence
 from appium.webdriver.mobilecommand import MobileCommand as Command
 
-if TYPE_CHECKING:
-    from appium.webdriver.webdriver import WebDriver
-
 
 class GsmCallActions:
     CALL = 'call'
@@ -53,7 +50,7 @@ class GsmVoiceState:
 
 
 class Gsm(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
-    def make_gsm_call(self, phone_number: str, action: str) -> 'WebDriver':
+    def make_gsm_call(self, phone_number: str, action: str) -> Self:
         """Make GSM call (Emulator only)
 
         Android only.
@@ -82,9 +79,9 @@ def make_gsm_call(self, phone_number: str, action: str) -> 'WebDriver':
         except UnknownMethodException:
             # TODO: Remove the fallback
             self.mark_extension_absence(ext_name).execute(Command.MAKE_GSM_CALL, args)
-        return cast('WebDriver', self)
+        return self
 
-    def set_gsm_signal(self, strength: int) -> 'WebDriver':
+    def set_gsm_signal(self, strength: int) -> Self:
         """Set GSM signal strength (Emulator only)
 
         Android only.
@@ -113,9 +110,9 @@ def set_gsm_signal(self, strength: int) -> 'WebDriver':
             self.mark_extension_absence(ext_name).execute(
                 Command.SET_GSM_SIGNAL, {'signalStrength': strength, 'signalStrengh': strength}
             )
-        return cast('WebDriver', self)
+        return self
 
-    def set_gsm_voice(self, state: str) -> 'WebDriver':
+    def set_gsm_voice(self, state: str) -> Self:
         """Set GSM voice state (Emulator only)
 
         Android only.
@@ -143,7 +140,7 @@ def set_gsm_voice(self, state: str) -> 'WebDriver':
         except UnknownMethodException:
             # TODO: Remove the fallback
             self.mark_extension_absence(ext_name).execute(Command.SET_GSM_VOICE, args)
-        return cast('WebDriver', self)
+        return self
 
     def _add_commands(self) -> None:
         # noinspection PyProtectedMember,PyUnresolvedReferences

appium/webdriver/extensions/android/network.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, cast
+from typing import Self
 
 from selenium.common.exceptions import UnknownMethodException
 
@@ -23,9 +23,6 @@
 from appium.protocols.webdriver.can_remember_extension_presence import CanRememberExtensionPresence
 from appium.webdriver.mobilecommand import MobileCommand as Command
 
-if TYPE_CHECKING:
-    from appium.webdriver.webdriver import WebDriver
-
 
 class NetSpeed:
     GSM = 'gsm'  # GSM/CSD (up: 14.4(kbps), down: 14.4(kbps))
@@ -114,7 +111,7 @@ def set_network_connection(self, connection_type: int) -> int:
                 Command.SET_NETWORK_CONNECTION, {'parameters': {'type': connection_type}}
             )['value']
 
-    def toggle_wifi(self) -> 'WebDriver':
+    def toggle_wifi(self) -> Self:
         """Toggle the wifi on the device, Android only.
         This API only works reliably on emulators (any version) and real devices
         since API level 31.
@@ -129,9 +126,9 @@ def toggle_wifi(self) -> 'WebDriver':
             )
         except UnknownMethodException:
             self.mark_extension_absence(ext_name).execute(Command.TOGGLE_WIFI, {})
-        return cast('WebDriver', self)
+        return self
 
-    def set_network_speed(self, speed_type: str) -> 'WebDriver':
+    def set_network_speed(self, speed_type: str) -> Self:
         """Set the network speed emulation.
 
         Android Emulator only.
@@ -158,7 +155,7 @@ def set_network_speed(self, speed_type: str) -> 'WebDriver':
         except UnknownMethodException:
             # TODO: Remove the fallback
             self.mark_extension_absence(ext_name).execute(Command.SET_NETWORK_SPEED, {'netspeed': speed_type})
-        return cast('WebDriver', self)
+        return self
 
     def _add_commands(self) -> None:
         # noinspection PyProtectedMember,PyUnresolvedReferences

appium/webdriver/extensions/android/power.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, cast
+from typing import Self
 
 from selenium.common.exceptions import UnknownMethodException
 
@@ -21,14 +21,11 @@
 from appium.protocols.webdriver.can_remember_extension_presence import CanRememberExtensionPresence
 from appium.webdriver.mobilecommand import MobileCommand as Command
 
-if TYPE_CHECKING:
-    from appium.webdriver.webdriver import WebDriver
-
 
 class Power(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
     AC_OFF, AC_ON = 'off', 'on'
 
-    def set_power_capacity(self, percent: int) -> 'WebDriver':
+    def set_power_capacity(self, percent: int) -> Self:
         """Emulate power capacity change on the connected emulator.
 
         Android only.
@@ -49,9 +46,9 @@ def set_power_capacity(self, percent: int) -> 'WebDriver':
         except UnknownMethodException:
             # TODO: Remove the fallback
             self.mark_extension_absence(ext_name).execute(Command.SET_POWER_CAPACITY, args)
-        return cast('WebDriver', self)
+        return self
 
-    def set_power_ac(self, ac_state: str) -> 'WebDriver':
+    def set_power_ac(self, ac_state: str) -> Self:
         """Emulate power state change on the connected emulator.
 
         Android only.
@@ -73,7 +70,7 @@ def set_power_ac(self, ac_state: str) -> 'WebDriver':
         except UnknownMethodException:
             # TODO: Remove the fallback
             self.mark_extension_absence(ext_name).execute(Command.SET_POWER_AC, args)
-        return cast('WebDriver', self)
+        return self
 
     def _add_commands(self) -> None:
         # noinspection PyProtectedMember,PyUnresolvedReferences

appium/webdriver/extensions/android/sms.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, cast
+from typing import Self
 
 from selenium.common.exceptions import UnknownMethodException
 
@@ -21,12 +21,9 @@
 from appium.protocols.webdriver.can_remember_extension_presence import CanRememberExtensionPresence
 from appium.webdriver.mobilecommand import MobileCommand as Command
 
-if TYPE_CHECKING:
-    from appium.webdriver.webdriver import WebDriver
-
 
 class Sms(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
-    def send_sms(self, phone_number: str, message: str) -> 'WebDriver':
+    def send_sms(self, phone_number: str, message: str) -> Self:
         """Emulate send SMS event on the connected emulator.
 
         Android only.
@@ -48,7 +45,7 @@ def send_sms(self, phone_number: str, message: str) -> 'WebDriver':
         except UnknownMethodException:
             # TODO: Remove the fallback
             self.mark_extension_absence(ext_name).execute(Command.SEND_SMS, args)
-        return cast('WebDriver', self)
+        return self
 
     def _add_commands(self) -> None:
         # noinspection PyProtectedMember,PyUnresolvedReferences