chore: Use proper type declarations for methods returning self instances (appium#1039)

Author: mykola-mokhnach

Pipfile

@@ -20,3 +20,4 @@ types-python-dateutil = "~=2.9"
 
 [packages]
 selenium = "~=4.24"
+typing-extensions = "~=4.12.2"

appium/webdriver/extensions/action_helpers.py

@@ -19,15 +19,17 @@
 from selenium.webdriver.common.actions.action_builder import ActionBuilder
 from selenium.webdriver.common.actions.mouse_button import MouseButton
 from selenium.webdriver.common.actions.pointer_input import PointerInput
+from typing_extensions import Self
 
 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 +50,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 +61,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 +74,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 +100,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 +114,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 +132,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 +152,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 +161,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 +178,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,21 +11,18 @@
 # 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 selenium.common.exceptions import UnknownMethodException
+from typing_extensions import Self
 
 from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
 from appium.protocols.webdriver.can_execute_scripts import CanExecuteScripts
 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,9 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, cast
-
 from selenium.common.exceptions import UnknownMethodException
+from typing_extensions import Self
 
 from appium.common.helper import extract_const_attributes
 from appium.common.logger import logger
@@ -23,9 +22,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 +49,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 +78,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 +109,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 +139,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,9 +12,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, cast
-
 from selenium.common.exceptions import UnknownMethodException
+from typing_extensions import Self
 
 from appium.common.helper import extract_const_attributes
 from appium.common.logger import logger
@@ -23,9 +22,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 +110,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 +125,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 +154,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,23 +12,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, cast
-
 from selenium.common.exceptions import UnknownMethodException
+from typing_extensions import Self
 
 from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
 from appium.protocols.webdriver.can_execute_scripts import CanExecuteScripts
 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 +45,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 +69,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,21 +12,17 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from typing import TYPE_CHECKING, cast
-
 from selenium.common.exceptions import UnknownMethodException
+from typing_extensions import Self
 
 from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
 from appium.protocols.webdriver.can_execute_scripts import CanExecuteScripts
 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 +44,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