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

appium/webdriver/extensions/keyboard.py

@@ -0,0 +1,168 @@
+#!/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 Dict, Optional
+
+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 ..mobilecommand import MobileCommand as Command
+
+
+class Keyboard(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    def hide_keyboard(self, key_name: Optional[str] = None, key: Optional[str] = None, strategy: Optional[str] = None) -> Self:
+        """Hides the software keyboard on the device.
+
+        In iOS, use `key_name` to press
+        a particular key, or `strategy`. In Android, no parameters are used.
+
+        Args:
+            key_name: key to press
+            key:
+            strategy: strategy for closing the keyboard (e.g., `tapOutside`)
+
+        Returns:
+            Union['WebDriver', 'Keyboard']: Self instance
+        """
+        ext_name = 'mobile: hideKeyboard'
+        try:
+            self.assert_extension_exists(ext_name).execute_script(
+                ext_name, {**({'keys': [key or key_name]} if key or key_name else {})}
+            )
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            data: Dict[str, Optional[str]] = {}
+            if key_name is not None:
+                data['keyName'] = key_name
+            elif key is not None:
+                data['key'] = key
+            elif strategy is None:
+                strategy = 'tapOutside'
+            data['strategy'] = strategy
+            self.mark_extension_absence(ext_name).execute(Command.HIDE_KEYBOARD, data)
+        return self
+
+    def is_keyboard_shown(self) -> bool:
+        """Attempts to detect whether a software keyboard is present
+
+        Returns:
+            `True` if keyboard is shown
+        """
+        ext_name = 'mobile: isKeyboardShown'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name)
+        except UnknownMethodException:
+            return self.mark_extension_absence(ext_name).execute(Command.IS_KEYBOARD_SHOWN)['value']
+
+    def keyevent(self, keycode: int, metastate: Optional[int] = None) -> Self:
+        """Sends a keycode to the device.
+
+        Android only.
+        Possible keycodes can be found in http://developer.android.com/reference/android/view/KeyEvent.html.
+
+        Args:
+            keycode: the keycode to be sent to the device
+            metastate: meta information about the keycode being sent
+
+        Returns:
+            Union['WebDriver', 'Keyboard']: Self instance
+        """
+        return self.press_keycode(keycode=keycode, metastate=metastate)
+
+    def press_keycode(self, keycode: int, metastate: Optional[int] = None, flags: Optional[int] = None) -> Self:
+        """Sends a keycode to the device.
+
+        Android only. Possible keycodes can be found
+        in http://developer.android.com/reference/android/view/KeyEvent.html.
+
+        Args:
+            keycode: the keycode to be sent to the device
+            metastate: meta information about the keycode being sent
+            flags: the set of key event flags
+
+        Returns:
+            Union['WebDriver', 'Keyboard']: Self instance
+        """
+        ext_name = 'mobile: pressKey'
+        args = {'keycode': keycode}
+        if metastate is not None:
+            args['metastate'] = metastate
+        if flags is not None:
+            args['flags'] = flags
+        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.PRESS_KEYCODE, args)
+        return self
+
+    def long_press_keycode(self, keycode: int, metastate: Optional[int] = None, flags: Optional[int] = None) -> Self:
+        """Sends a long press of keycode to the device.
+
+        Android only. Possible keycodes can be found in
+        http://developer.android.com/reference/android/view/KeyEvent.html.
+
+        Args:
+            keycode: the keycode to be sent to the device
+            metastate: meta information about the keycode being sent
+            flags: the set of key event flags
+
+        Returns:
+            Union['WebDriver', 'Keyboard']: Self instance
+        """
+        ext_name = 'mobile: pressKey'
+        args = {'keycode': keycode}
+        if metastate is not None:
+            args['metastate'] = metastate
+        if flags is not None:
+            args['flags'] = flags
+        try:
+            self.assert_extension_exists(ext_name).execute_script(
+                ext_name,
+                {
+                    **args,
+                    'isLongPress': True,
+                },
+            )
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(Command.LONG_PRESS_KEYCODE, args)
+        return self
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(
+            Command.HIDE_KEYBOARD,
+            'POST',
+            '/session/$sessionId/appium/device/hide_keyboard',
+        )
+        self.command_executor.add_command(
+            Command.IS_KEYBOARD_SHOWN,
+            'GET',
+            '/session/$sessionId/appium/device/is_keyboard_shown',
+        )
+        self.command_executor.add_command(Command.KEY_EVENT, 'POST', '/session/$sessionId/appium/device/keyevent')
+        self.command_executor.add_command(
+            Command.PRESS_KEYCODE,
+            'POST',
+            '/session/$sessionId/appium/device/press_keycode',
+        )
+        self.command_executor.add_command(
+            Command.LONG_PRESS_KEYCODE,
+            'POST',
+            '/session/$sessionId/appium/device/long_press_keycode',
+        )

appium/webdriver/extensions/location.py

@@ -0,0 +1,98 @@
+#!/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 Dict, Union
+
+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 ..mobilecommand import MobileCommand as Command
+
+
+class Location(CanExecuteCommands, CanExecuteScripts):
+    def toggle_location_services(self) -> Self:
+        """Toggle the location services on the device.
+        This API only reliably since Android 12 (API level 31)
+
+        Android only.
+
+        Returns:
+            Union['WebDriver', 'Location']: Self instance
+        """
+        try:
+            self.execute_script('mobile: toggleGps')
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.execute(Command.TOGGLE_LOCATION_SERVICES)
+        return self
+
+    def set_location(
+        self,
+        latitude: Union[float, str],
+        longitude: Union[float, str],
+        altitude: Union[float, str, None] = None,
+        speed: Union[float, str, None] = None,
+        satellites: Union[float, str, None] = None,
+    ) -> Self:
+        """Set the location of the device
+
+        Args:
+            latitude: String or numeric value between -90.0 and 90.00
+            longitude: String or numeric value between -180.0 and 180.0
+            altitude: String or numeric value (Android real device only)
+            speed: String or numeric value larger than 0.0 (Android real devices only)
+            satellites: String or numeric value of active GPS satellites in range 1..12. (Android emulators only)
+
+        Returns:
+            Union['WebDriver', 'Location']: Self instance
+        """
+        data = {
+            'location': {
+                'latitude': latitude,
+                'longitude': longitude,
+            }
+        }
+        if altitude is not None:
+            data['location']['altitude'] = altitude
+        if speed is not None:
+            data['location']['speed'] = speed
+        if satellites is not None:
+            data['location']['satellites'] = satellites
+        self.execute(Command.SET_LOCATION, data)
+        return self
+
+    @property
+    def location(self) -> Dict[str, float]:
+        """Retrieves the current location
+
+        Returns:
+            A dictionary whose keys are
+                - latitude (float)
+                - longitude (float)
+                - altitude (float)
+        """
+        return self.execute(Command.GET_LOCATION)['value']
+
+    def _add_commands(self) -> None:
+        """Add location endpoints. They are not int w3c spec."""
+        self.command_executor.add_command(
+            Command.TOGGLE_LOCATION_SERVICES,
+            'POST',
+            '/session/$sessionId/appium/device/toggle_location_services',
+        )
+        self.command_executor.add_command(Command.GET_LOCATION, 'GET', '/session/$sessionId/location')
+        self.command_executor.add_command(Command.SET_LOCATION, 'POST', '/session/$sessionId/location')

appium/webdriver/extensions/log_event.py

@@ -0,0 +1,68 @@
+#!/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 Dict, List, Union
+
+from typing_extensions import Self
+
+from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
+
+from ..mobilecommand import MobileCommand as Command
+
+
+class LogEvent(CanExecuteCommands):
+    def get_events(self, type: Union[List[str], None] = None) -> Dict[str, Union[str, int]]:
+        """Retrieves events information from the current session
+        (Since Appium 1.16.0)
+
+        Args:
+            type: The event type to filter with
+
+        Usage:
+            | events = driver.get_events()
+            | events = driver.get_events(['appium:funEvent'])
+
+        Returns:
+            `dict`: A dictionary of events timing information containing the following entries
+                | commands: (`list` of `dict`) List of dictionaries containing the following entries
+                | cmd: The command name that has been sent to the appium server
+                | startTime: Received time
+                | endTime: Response time
+        """
+        data = {}
+        if type is not None:
+            data['type'] = type
+        return self.execute(Command.GET_EVENTS, data)['value']
+
+    def log_event(self, vendor: str, event: str) -> Self:
+        """Log a custom event on the Appium server.
+        (Since Appium 1.16.0)
+
+        Args:
+            vendor: The vendor to log
+            event: The event to log
+
+        Usage:
+            driver.log_event('appium', 'funEvent')
+
+        Returns:
+            Union['WebDriver', 'LogEvent']: Self instance
+        """
+        data = {'vendor': vendor, 'event': event}
+        self.execute(Command.LOG_EVENT, data)
+        return self
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.GET_EVENTS, 'POST', '/session/$sessionId/appium/events')
+        self.command_executor.add_command(Command.LOG_EVENT, 'POST', '/session/$sessionId/appium/log_event')

appium/webdriver/extensions/logs.py

@@ -0,0 +1,53 @@
+#!/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 Any, Dict, List
+
+from appium.protocols.webdriver.can_execute_commands import CanExecuteCommands
+
+from ..mobilecommand import MobileCommand as Command
+
+
+class Logs(CanExecuteCommands):
+    @property
+    def log_types(self) -> List[str]:
+        """Gets a list of the available log types. This only works with w3c
+        compliant browsers.
+
+        Example:
+            .. code-block:: python
+
+                driver.log_types
+        """
+        return self.execute(Command.GET_AVAILABLE_LOG_TYPES)['value']
+
+    def get_log(self, log_type: str) -> List[Dict[str, Any]]:
+        """Gets the log for a given log type.
+
+        Args:
+            log_type: Type of log that which will be returned
+
+        Example:
+            .. code-block:: python
+
+                driver.get_log('browser')
+                driver.get_log('driver')
+                driver.get_log('client')
+                driver.get_log('server')
+        """
+        return self.execute(Command.GET_LOG, {'type': log_type})['value']
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.GET_LOG, 'POST', '/session/$sessionId/se/log')
+        self.command_executor.add_command(Command.GET_AVAILABLE_LOG_TYPES, 'GET', '/session/$sessionId/se/log/types')

appium/webdriver/extensions/remote_fs.py

@@ -0,0 +1,110 @@
+#!/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.
+
+import base64
+from typing import Optional
+
+from selenium.common.exceptions import InvalidArgumentException, 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 ..mobilecommand import MobileCommand as Command
+
+
+class RemoteFS(CanExecuteCommands, CanExecuteScripts, CanRememberExtensionPresence):
+    def pull_file(self, path: str) -> str:
+        """Retrieves the file at `path`.
+
+        Args:
+            path: the path to the file on the device
+
+        Returns:
+            The file's contents encoded as Base64.
+        """
+        ext_name = 'mobile: pullFile'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name, {'remotePath': path})
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(Command.PULL_FILE, {'path': path})['value']
+
+    def pull_folder(self, path: str) -> str:
+        """Retrieves a folder at `path`.
+
+        Args:
+            path: the path to the folder on the device
+
+        Returns:
+            The folder's contents zipped and encoded as Base64.
+        """
+        ext_name = 'mobile: pullFolder'
+        try:
+            return self.assert_extension_exists(ext_name).execute_script(ext_name, {'remotePath': path})
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            return self.mark_extension_absence(ext_name).execute(Command.PULL_FOLDER, {'path': path})['value']
+
+    def push_file(self, destination_path: str, base64data: Optional[str] = None, source_path: Optional[str] = None) -> Self:
+        """Puts the data from the file at `source_path`, encoded as Base64, in the file specified as `path`.
+
+        Specify either `base64data` or `source_path`, if both specified default to `source_path`
+
+        Args:
+            destination_path: the location on the device/simulator where the local file contents should be saved
+            base64data: file contents, encoded as Base64, to be written
+            to the file on the device/simulator
+            source_path: local file path for the file to be loaded on device
+
+        Returns:
+            Union['WebDriver', 'RemoteFS']: Self instance
+        """
+        if source_path is None and base64data is None:
+            raise InvalidArgumentException('Must either pass base64 data or a local file path')
+
+        if source_path is not None:
+            try:
+                with open(source_path, 'rb') as f:
+                    file_data = f.read()
+            except IOError as e:
+                message = f'source_path "{source_path}" could not be found. Are you sure the file exists?'
+                raise InvalidArgumentException(message) from e
+            base64data = base64.b64encode(file_data).decode('utf-8')
+
+        ext_name = 'mobile: pushFile'
+        try:
+            self.assert_extension_exists(ext_name).execute_script(
+                ext_name,
+                {
+                    'remotePath': destination_path,
+                    'payload': base64data,
+                },
+            )
+        except UnknownMethodException:
+            # TODO: Remove the fallback
+            self.mark_extension_absence(ext_name).execute(
+                Command.PUSH_FILE,
+                {
+                    'path': destination_path,
+                    'data': base64data,
+                },
+            )
+        return self
+
+    def _add_commands(self) -> None:
+        self.command_executor.add_command(Command.PULL_FILE, 'POST', '/session/$sessionId/appium/device/pull_file')
+        self.command_executor.add_command(Command.PULL_FOLDER, 'POST', '/session/$sessionId/appium/device/pull_folder')
+        self.command_executor.add_command(Command.PUSH_FILE, 'POST', '/session/$sessionId/appium/device/push_file')