# Python library

## 1.Quick <a href="#kuai-su-kai-shi" id="kuai-su-kai-shi"></a>

* Before use, use pip to install the imouse-py package
* `pip install imouse-py`

## 2.Use the API class basic interface <a href="#shi-yong-api-lei-ji-chu-jie-kou-diao-yong" id="shi-yong-api-lei-ji-chu-jie-kou-diao-yong"></a>

```python
import imouse
from imouse.types import MouseSwipeParams

# Connect to the iMouse server (default address is localhost)
api = imouse.api(host="localhost")  # Get the api instance. All interfaces provided by iMouse are called in the api instance.

# Perform mouse operations through the methods in the API class
api.mouse_click("FA:9E:10:3A:FE:E8", "", 100, 100)  # Left click screen coordinates (100, 100)
api.mouse_swipe("FA:9E:10:3A:FE:E8", params=MouseSwipeParams(  # Swipe up the screen from the bottom 10% to 90%
    direction='up',  # 
    len=0.9
))

```

## 3.Easier calling through helper class (recommended)

### 1.API provided by Console

Provides access to device management and global operations:

* **Device**: Device Management
* **AirPlay**: Screen projection connection and configuration
* **USB**: imouse Hardware Management
* **Group**: Group management
* **ImConfig**: iMouse Global configuration management
* **User**: iMouse Account Management

```python
import imouse

# Connect to the iMouse server (default address is localhost)
api = imouse.api(host="localhost")  # Get the API instance

helper = imouse.helper(api)  # Get the helper class instance

console = helper.console  # Get a console instance
ret = console.device.list_by_id()  # Get a list of all devices
print(ret)
# Cast screen to designated device
ret = console.airplay.connect('FA:9E:10:3A:FE:E8,FD:9E:10:3A:FE:E0')
if ret:
    print('成功')
else:
    print(f'失败:{console.error_msg}')

# 断开指定设备投屏
ret = console.airplay.disconnect('FA:9E:10:3A:FE:E8,FD:9E:10:3A:FE:E0')
if ret:
    print('成功')
else:
    print(f'失败:{console.error_msg}')

# 投屏所有离线设备
ret = console.airplay.connect_all()
if ret:
    print('成功')
else:
    print(f'失败:{console.error_msg}')
```

### 2.API provided by device

Provides control over individual devices:

* **Image**: Device image operations, such as screenshots, image search, text recognition, etc.
* **KeyBoard**: Keyboard operation
* **Mouse**: Mouse Operation
* **Shortcut**: Shortcut command operation

```python
import imouse
from imouse.utils import file_to_base64
from imouse.types import MouseSwipeParams

# Connect to the iMouse server (default address is localhost)
api = imouse.api(host="localhost")  # Get the API instance

helper = imouse.helper(api)  # Get the helper class instance

device = helper.device('FA:9E:10:3A:FE:E8')  # Get the device instance by device ID

# You can also get a list of all instances through the devices method
# device_list = helper.devices()
# device = device_list[0]

# screenshot
ret = device.image.screenshot()
if ret:
    print('截图成功')
    with open('test.bmp', "wb") as f:
        f.write(ret)
else:
    print(f'截图失败:{device.error_msg}')

# Find images through opencv
img_str = file_to_base64("test1.bmp")
ret = device.image.find_image_cv([img_str])
if len(ret) > 0:
    print(f"找图成功[{ret[0].centre[0]},{ret[0].centre[1]}]")
else:
    print(f'找图失败:{device.error_msg}')

# 向上滑动屏幕
ret = device.mouse.swipe(MouseSwipeParams(direction='up', len=0.9))  # Swipe from the bottom 10 percent of the screen to 90 percent of the screen
if ret:
    print('滑动成功')
else:
    print(f'滑动失败:{device.error_msg}')

```

### 3.iMouse Event Handling <a href="#imouse-shi-jian-chu-li" id="imouse-shi-jian-chu-li"></a>

```python
from typing import List
import imouse
from imouse.api import event
from imouse.models import DeviceInfo, UsbInfo, UserData, ImServerConfigData


@event.on("im_connect")
def im_connect(ver: str):
    print(f"[Event] Connect to kernel successfully: {ver}")


@event.on("im_disconnect")
def im_disconnect():
    print(f"[Event] Disconnected from kernel")


@event.on("dev_connect")
def dev_connect(device_info: DeviceInfo):
    print("[Event] A device is connected" + device_info.device_id)


@event.on("dev_disconnect")
def dev_disconnect(device_info: DeviceInfo):
    print("[Event] A device was disconnected->" + device_info.device_id)


@event.on("dev_rotate")
def dev_rotate(device_info: DeviceInfo):
    print("[Event] The device rotates->" + device_info.device_id)


@event.on("dev_change")
def dev_change(device_info: DeviceInfo):
    print("[Event] Equipment changed->" + device_info.device_id)


@event.on("dev_delete")
def dev_delete(deviceid_list: List[str]):
    print(f"[Event] Device deleted->{deviceid_list}")


@event.on("group_change")
def group_change(gid: str, name: str):
    print(f"[Event] There is a group change->{gid},{name}")


@event.on("group_change")
def group_change(gid: str, name: str):
    print(f"[Event] There is a group change->{gid},{name}")


@event.on("group_delete")
def group_delete(gid_list: List[str]):
    print(f"[Event] Group deletion->{gid_list}")


@event.on("usb_change")
def usb_change(usb_info: UsbInfo):
    print(f"[Event] USB device changed->{usb_info}")


@event.on("airplay_connect_log")
def usb_change(message: str):
    print(f"[Event] Automatic screen projection log->{message}")


@event.on("user_info")
def user_info(data: UserData):
    print(f"[Event] User information status->{data}")


@event.on("im_log")
def im_log(message: str):
    print(f"[Event]iMouse event->{message}")


@event.on("error_push")
def error_push(message: str, call_fun: str):
    print(f"[Event] iMouse Error Log->{message},{call_fun}")


@event.on("im_config_change")
def im_config_change(config: ImServerConfigData):
    print(f"[Event] iMouse kernel configuration changed->{config}")


@event.on("logout")
def logout():
    print(f"[Event] iMouse account exit-")


@event.on("dev_sort_change")
def dev_sort_change(sort_index: int, sort_value: int):
    print(f"[Event] iMouse device list sorting changed->{sort_index},{sort_value}")


api = imouse.api(host='192.168.9.9')

```

### 4.Configuring iMouse Log Output

```python
import logging
from imouse.utils import logger

logger.configure(
    is_debug=True,  # Whether to enable debug logging (info/debug will not be output when False)
    name='imouse',  # Log name (affects logger name and log file name)
    log_dir='logs',  # Log directory (default logs folder)
    log_level=logging.DEBUG,  # Log level
    log_show_thread_id=False,  # Whether to display thread ID
    log_show_file_and_line=False  #Whether to display file and line numbers
)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.some3c.com/iphone-farm-setup/xp-api-documentation/python-library.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.