Appium-Python-Client 5.2.0__py3-none-any.whl

appium/webdriver/extensions/__init__.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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.

appium/webdriver/extensions/action_helpers.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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, List, Optional, Tuple, cast
+
+from selenium.webdriver.common.action_chains import ActionChains
+from selenium.webdriver.common.actions import interaction
+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) -> Self:
+        """Scrolls from one element to another
+
+        Args:
+            origin_el: the element from which to begin scrolling (center of element)
+            destination_el: the element to scroll to (center of element)
+            duration: defines speed of scroll action when moving from originalEl to destinationEl.
+                Default is 600 ms for W3C spec.
+
+        Usage:
+            driver.scroll(el1, el2)
+
+        Returns:
+            Union['WebDriver', 'ActionHelpers']: Self instance
+        """
+        # XCUITest x W3C spec has no duration by default in server side
+        if duration is None:
+            duration = 600
+
+        touch_input = PointerInput(interaction.POINTER_TOUCH, 'touch')
+
+        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
+        actions.w3c_actions.pointer_action.move_to(origin_el)
+        actions.w3c_actions.pointer_action.pointer_down()
+        # setup duration for second move only, assuming duration always has atleast default value
+        actions.w3c_actions = ActionBuilder(self, mouse=touch_input, duration=duration)
+        actions.w3c_actions.pointer_action.move_to(destination_el)
+        actions.w3c_actions.pointer_action.release()
+        actions.perform()
+        return self
+
+    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:
+            origin_el: the element to drag
+            destination_el: the element to drag to
+            pause: how long the action pauses before moving after the tap and hold, in float seconds.
+
+        Returns:
+            Union['WebDriver', 'ActionHelpers']: Self instance
+        """
+        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 self
+
+    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
+
+        Args:
+            positions: an array of tuples representing the x/y coordinates of
+                the fingers to tap. Length can be up to five.
+            duration: length of time to tap, in ms
+
+        Usage:
+            driver.tap([(100, 20), (100, 60), (100, 100)], 500)
+
+        Returns:
+            Union['WebDriver', 'ActionHelpers']: Self instance
+        """
+        if len(positions) == 1:
+            actions = ActionChains(cast('WebDriver', self))
+            actions.w3c_actions = ActionBuilder(self, mouse=PointerInput(interaction.POINTER_TOUCH, 'touch'))
+            x = positions[0][0]
+            y = positions[0][1]
+            actions.w3c_actions.pointer_action.move_to_location(x, y)
+            actions.w3c_actions.pointer_action.pointer_down()
+            if duration:
+                actions.w3c_actions.pointer_action.pause(duration / 1000)
+            else:
+                actions.w3c_actions.pointer_action.pause(0.1)
+            actions.w3c_actions.pointer_action.release()
+            actions.perform()
+        else:
+            finger = 0
+            actions = ActionChains(cast('WebDriver', self))
+            actions.w3c_actions.devices = []
+
+            for position in positions:
+                finger += 1
+                x = position[0]
+                y = position[1]
+
+                # https://github.com/SeleniumHQ/selenium/blob/trunk/py/selenium/webdriver/common/actions/pointer_input.py
+                new_input = actions.w3c_actions.add_pointer_input('touch', f'finger{finger}')
+                new_input.create_pointer_move(x=x, y=y)
+                new_input.create_pointer_down(button=MouseButton.LEFT)
+                if duration:
+                    new_input.create_pause(duration / 1000)
+                else:
+                    new_input.create_pause(0.1)
+                new_input.create_pointer_up(MouseButton.LEFT)
+            actions.perform()
+        return self
+
+    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:
+            start_x: x-coordinate at which to start
+            start_y: y-coordinate at which to start
+            end_x: x-coordinate at which to stop
+            end_y: y-coordinate at which to stop
+            duration: defines the swipe speed as time taken to swipe from point a to point b, in ms.
+
+        Usage:
+            driver.swipe(100, 100, 100, 400)
+
+        Returns:
+            Union['WebDriver', 'ActionHelpers']: Self instance
+        """
+        touch_input = PointerInput(interaction.POINTER_TOUCH, 'touch')
+
+        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()
+        if duration > 0:
+            actions.w3c_actions = ActionBuilder(self, mouse=touch_input, duration=duration)
+        actions.w3c_actions.pointer_action.move_to_location(end_x, end_y)
+        actions.w3c_actions.pointer_action.release()
+        actions.perform()
+        return self
+
+    def flick(self, start_x: int, start_y: int, end_x: int, end_y: int) -> Self:
+        """Flick from one point to another point.
+
+        Args:
+            start_x: x-coordinate at which to start
+            start_y: y-coordinate at which to start
+            end_x: x-coordinate at which to stop
+            end_y: y-coordinate at which to stop
+
+        Usage:
+            driver.flick(100, 100, 100, 400)
+
+        Returns:
+            Union['WebDriver', 'ActionHelpers']: Self instance
+        """
+        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 self

appium/webdriver/extensions/android/activities.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 selenium.common.exceptions import TimeoutException, UnknownMethodException
+from selenium.webdriver.support.ui import WebDriverWait
+
+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
+
+
+class Activities(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    @property
+    def current_activity(self) -> str:
+        """Retrieves the current activity running on the device.
+
+        Returns:
+            str: The current activity name running on the device
+        """
+        ext_name = 'mobile: getCurrentActivity'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(Command.GET_CURRENT_ACTIVITY)['value']
+
+    def wait_activity(self, activity: str, timeout: int, interval: int = 1) -> bool:
+        """Wait for an activity: block until target activity presents or time out.
+
+        This is an Android-only method.
+
+        Args:
+            activity: target activity
+            timeout: max wait time, in seconds
+            interval: sleep interval between retries, in seconds
+
+        Returns:
+            `True` if the target activity is shown
+        """
+        try:
+            WebDriverWait(self, timeout, interval).until(  # type: ignore[type-var]
+                lambda d: d.current_activity == activity
+            )
+            return True
+        except TimeoutException:
+            return False
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(
+            Command.GET_CURRENT_ACTIVITY,
+            'GET',
+            '/session/$sessionId/appium/device/current_activity',
+        )

appium/webdriver/extensions/android/common.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 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
+
+
+class Common(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    def open_notifications(self) -> Self:
+        """Open notification shade in Android (API Level 18 and above)
+
+        Returns:
+            Union['WebDriver', 'Common']: Self instance
+        """
+        ext_name = 'mobile: openNotifications'
+        try:
+            self.assert_extension_exists(ext_name).execute_script(ext_name)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.OPEN_NOTIFICATIONS, {})
+        return self
+
+    @property
+    def current_package(self) -> str:
+        """Retrieves the current package running on the device."""
+        ext_name = 'mobile: getCurrentPackage'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(Command.GET_CURRENT_PACKAGE)['value']
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(
+            Command.GET_CURRENT_PACKAGE,
+            'GET',
+            '/session/$sessionId/appium/device/current_package',
+        )
+        self.command_executor.add_command(
+            Command.OPEN_NOTIFICATIONS,
+            'POST',
+            '/session/$sessionId/appium/device/open_notifications',
+        )

appium/webdriver/extensions/android/display.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 selenium.common.exceptions import UnknownMethodException
+
+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
+
+
+class Display(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    def get_display_density(self) -> int:
+        """Get the display density, Android only
+
+        Returns:
+            The display density of the Android device(dpi)
+
+        Usage:
+            self.driver.get_display_density()
+
+        Return:
+            int: The display density
+        """
+        ext_name = 'mobile: getDisplayDensity'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(Command.GET_DISPLAY_DENSITY)['value']
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(
+            Command.GET_DISPLAY_DENSITY,
+            'GET',
+            '/session/$sessionId/appium/device/display_density',
+        )

appium/webdriver/extensions/android/gsm.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python
+
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# 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 selenium.common.exceptions import UnknownMethodException
+from typing_extensions import Self
+
+from appium.common.helper import extract_const_attributes
+from appium.common.logger import logger
+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
+
+
+class GsmCallActions:
+    CALL = 'call'
+    ACCEPT = 'accept'
+    CANCEL = 'cancel'
+    HOLD = 'hold'
+
+
+class GsmSignalStrength:
+    NONE_OR_UNKNOWN = 0
+    POOR = 1
+    MODERATE = 2
+    GOOD = 3
+    GREAT = 4
+
+
+class GsmVoiceState:
+    UNREGISTERED = 'unregistered'
+    HOME = 'home'
+    ROAMING = 'roaming'
+    SEARCHING = 'searching'
+    DENIED = 'denied'
+    OFF = 'off'
+    ON = 'on'
+
+
+class Gsm(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    def make_gsm_call(self, phone_number: str, action: str) -> Self:
+        """Make GSM call (Emulator only)
+
+        Android only.
+
+        Args:
+            phone_number: The phone number to call to.
+            action: The call action.
+                A member of the const `appium.webdriver.extensions.android.gsm.GsmCallActions`
+
+        Usage:
+            self.driver.make_gsm_call('5551234567', GsmCallActions.CALL)
+
+        Returns:
+            Union['WebDriver', 'Gsm']: Self instance
+        """
+        ext_name = 'mobile: gsmCall'
+        constants = extract_const_attributes(GsmCallActions)
+        if action not in constants.values():
+            logger.warning(
+                f'{action} is unknown. Consider using one of {list(constants.keys())} constants. '
+                f'(e.g. {GsmCallActions.__name__}.CALL)'
+            )
+        args = {'phoneNumber': phone_number, 'action': action}
+        try:
+            self.assert_extension_exists(ext_name).execute_script(ext_name, args)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.MAKE_GSM_CALL, args)
+        return self
+
+    def set_gsm_signal(self, strength: int) -> Self:
+        """Set GSM signal strength (Emulator only)
+
+        Android only.
+
+        Args:
+            strength: Signal strength.
+                A member of the enum :obj:`appium.webdriver.extensions.android.gsm.GsmSignalStrength`
+
+        Usage:
+            self.driver.set_gsm_signal(GsmSignalStrength.GOOD)
+
+        Returns:
+            Union['WebDriver', 'Gsm']: Self instance
+        """
+        ext_name = 'mobile: gsmSignal'
+        constants = extract_const_attributes(GsmSignalStrength)
+        if strength not in constants.values():
+            logger.warning(
+                f'{strength} is out of range. Consider using one of {list(constants.keys())} constants. '
+                f'(e.g. {GsmSignalStrength.__name__}.GOOD)'
+            )
+        try:
+            self.assert_extension_exists(ext_name).execute_script(ext_name, {'strength': strength})
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(
+                Command.SET_GSM_SIGNAL, {'signalStrength': strength, 'signalStrengh': strength}
+            )
+        return self
+
+    def set_gsm_voice(self, state: str) -> Self:
+        """Set GSM voice state (Emulator only)
+
+        Android only.
+
+        Args:
+            state: State of GSM voice.
+                A member of the const `appium.webdriver.extensions.android.gsm.GsmVoiceState`
+
+        Usage:
+            self.driver.set_gsm_voice(GsmVoiceState.HOME)
+
+        Returns:
+            Union['WebDriver', 'Gsm']: Self instance
+        """
+        ext_name = 'mobile: gmsVoice'
+        constants = extract_const_attributes(GsmVoiceState)
+        if state not in constants.values():
+            logger.warning(
+                f'{state} is unknown. Consider using one of {list(constants.keys())} constants. '
+                f'(e.g. {GsmVoiceState.__name__}.HOME)'
+            )
+        args = {'state': state}
+        try:
+            self.assert_extension_exists(ext_name).execute_script(ext_name, args)
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.SET_GSM_VOICE, args)
+        return self
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.MAKE_GSM_CALL, 'POST', '/session/$sessionId/appium/device/gsm_call')
+        self.command_executor.add_command(Command.SET_GSM_SIGNAL, 'POST', '/session/$sessionId/appium/device/gsm_signal')
+        self.command_executor.add_command(Command.SET_GSM_VOICE, 'POST', '/session/$sessionId/appium/device/gsm_voice')