0
# Appium Python Client
1

2
A comprehensive Python client library for Appium, the open-source mobile automation framework. The Appium Python Client extends Selenium WebDriver with mobile-specific functionality for iOS and Android app testing, providing a unified API for mobile automation across platforms.
3

4
## Package Information
5

6
- **Package Name**: Appium-Python-Client
7
- **Language**: Python 3.9+
8
- **Installation**: `pip install Appium-Python-Client`
9
- **Version**: 5.2.2
10
- **Dependencies**: selenium>=4.26,<5.0, typing-extensions~=4.13
11
- **Appium Server**: Compatible with Appium 2.x (recommended 2.0+)
12
- **WebDriver Protocol**: Supports W3C WebDriver standard
13

14
## Core Imports
15

16
```python
17
from appium import webdriver
18
from appium.webdriver.common.appiumby import AppiumBy
19
from appium.options.android import UiAutomator2Options
20
from appium.options.ios import XCUITestOptions
21
```
22

23
For specific platform options:
24

25
```python
26
# Android options
27
from appium.options.android.uiautomator2 import UiAutomator2Options
28
from appium.options.android.espresso import EspressoOptions
29

30
# iOS options
31
from appium.options.ios.xcuitest import XCUITestOptions
32
from appium.options.ios.safari import SafariOptions
33

34
# Other platforms
35
from appium.options.mac.mac2 import Mac2Options
36
from appium.options.windows.windows import WindowsOptions
37
```
38

39
## Basic Usage
40

41
```python
42
from appium import webdriver
43
from appium.options.android import UiAutomator2Options
44
from appium.webdriver.common.appiumby import AppiumBy
45

46
# Configure Android options
47
options = UiAutomator2Options()
48
options.platform_name = "Android"
49
options.device_name = "Android Emulator"
50
options.app = "/path/to/your/app.apk"
51

52
# Start WebDriver session
53
driver = webdriver.Remote("http://localhost:4723", options=options)
54

55
# Find and interact with elements
56
element = driver.find_element(AppiumBy.ACCESSIBILITY_ID, "button1")
57
element.click()
58

59
# Use mobile-specific locators
60
android_element = driver.find_element(AppiumBy.ANDROID_UIAUTOMATOR, 
61
                                    'new UiSelector().text("Login")')
62

63
# Clean up
64
driver.quit()
65
```
66

67
## Architecture
68

69
The Appium Python Client follows a modular extension-based architecture:
70

71
- **WebDriver**: Core class extending Selenium's Remote WebDriver with Appium-specific capabilities
72
- **Extensions**: Mixin classes providing specialized functionality (applications, keyboard, context, etc.)
73
- **Options Classes**: Platform-specific capability configuration (Android, iOS, Windows, Mac)
74
- **Locators**: Mobile-specific element finding strategies via AppiumBy
75
- **Service Management**: Appium server lifecycle management
76
- **Platform Support**: Cross-platform testing with unified API
77

78
This design enables comprehensive mobile testing capabilities while maintaining compatibility with existing Selenium-based test frameworks.
79

80
## Capabilities
81

82
### WebDriver and Session Management
83

84
Core WebDriver functionality including session creation, element interaction, and mobile WebElement extensions. Provides the foundation for all mobile automation operations.
85

86
```python {.api}
87
class WebDriver:
88
    def __init__(self, command_executor: str, extensions: list = None, 
89
                 options = None, client_config = None): ...
90
    def start_session(self, capabilities: dict, browser_profile = None): ...
91
    def get_status(self) -> dict: ...
92
    def create_web_element(self, element_id: str): ...
93
```
94

95
[WebDriver Core](./webdriver-core.md)
96

97
### Mobile Element Location
98

99
Appium-specific locator strategies for finding mobile elements across iOS and Android platforms, extending beyond standard WebDriver locators.
100

101
```python {.api}
102
class AppiumBy:
103
    ACCESSIBILITY_ID: str = "accessibility id"
104
    ANDROID_UIAUTOMATOR: str = "-android uiautomator"
105
    IOS_PREDICATE: str = "-ios predicate string"
106
    IOS_CLASS_CHAIN: str = "-ios class chain"
107
    IMAGE: str = "-image"
108
    FLUTTER_INTEGRATION_SEMANTICS_LABEL: str = "-flutter semantics label"
109
```
110

111
[Element Location](./element-location.md)
112

113
### Application Management
114

115
Application lifecycle management including installation, background/foreground control, and state querying across mobile platforms.
116

117
```python {.api}
118
def background_app(self, seconds: int): ...
119
def is_app_installed(self, bundle_id: str) -> bool: ...
120
def install_app(self, app_path: str, **options): ...
121
def remove_app(self, app_id: str, **options): ...
122
def terminate_app(self, app_id: str, **options): ...
123
def activate_app(self, app_id: str): ...
124
def query_app_state(self, app_id: str) -> int: ...
125
```
126

127
[Application Management](./application-management.md)
128

129
### Device Interaction
130

131
Hardware-level device interactions including keyboard, device rotation, location services, and hardware actions like shake and lock.
132

133
```python {.api}
134
def hide_keyboard(self, key_name: str = None, key = None, strategy: str = None): ...
135
def is_keyboard_shown(self) -> bool: ...
136
def shake(self): ...
137
def lock(self, seconds: int = None): ...
138
def unlock(self): ...
139
def is_locked(self) -> bool: ...
140
def set_location(self, latitude: float, longitude: float, altitude: float = None): ...
141
```
142

143
[Device Interaction](./device-interaction.md)
144

145
### Android Platform
146

147
Android-specific capabilities including network management, activity control, SMS simulation, GSM operations, and power management.
148

149
```python {.api}
150
def start_activity(self, app_package: str, app_activity: str, **opts): ...
151
def current_activity(self) -> str: ...
152
def set_network_connection(self, connection_type: int): ...
153
def toggle_wifi(self): ...
154
def send_sms(self, phone_number: str, message: str): ...
155
def set_gsm_call(self, phone_number: str, action: str): ...
156
def set_power_capacity(self, percent: int): ...
157
```
158

159
[Android Platform](./android-platform.md)
160

161
### Configuration and Options
162

163
Platform-specific capability configuration classes for Android (UiAutomator2, Espresso), iOS (XCUITest, Safari), and other platforms.
164

165
```python {.api}
166
class UiAutomator2Options(AppiumOptions):
167
    def set_capability(self, name: str, value): ...
168
    def get_capability(self, name: str): ...
169
    def to_capabilities(self) -> dict: ...
170

171
class XCUITestOptions(AppiumOptions):
172
    def set_capability(self, name: str, value): ...
173
    def get_capability(self, name: str): ...
174
    def to_capabilities(self) -> dict: ...
175
```
176

177
[Configuration Options](./configuration-options.md)
178

179
### Service Management
180

181
Appium server lifecycle management including startup, shutdown, and connectivity validation for local and remote testing scenarios.
182

183
```python {.api}
184
class AppiumService:
185
    def start(self, **kwargs): ...
186
    def stop(self, timeout: int = None): ...
187
    @property
188
    def is_running(self) -> bool: ...
189
    @property
190
    def is_listening(self) -> bool: ...
191

192
def find_executable(executable: str) -> str: ...
193
def get_node() -> str: ...
194
```
195

196
[Service Management](./service-management.md)
197

198
### Advanced Features
199

200
Advanced capabilities including context switching, screen recording, image comparison, clipboard operations, and Flutter integration.
201

202
```python {.api}
203
@property
204
def contexts(self) -> list: ...
205
@property
206
def current_context(self) -> str: ...
207
def start_recording_screen(self, **options): ...
208
def stop_recording_screen(self) -> str: ...
209
def compare_images(self, base64_image1: str, base64_image2: str, **options): ...
210
def get_clipboard(self, content_type = None): ...
211
def set_clipboard(self, content: str, content_type = None): ...
212
```
213

214
[Advanced Features](./advanced-features.md)