cai.api package

Application APIs.

This module wraps the client methods to provide easier control (high-level api).

Copyright

Copyright (C) 2021-2021 cscs181

License

AGPL-3.0 or later. See LICENSE for detail.

Submodules

cai.api.client module

Application Client APIs.

Copyright

Copyright (C) 2021-2021 cscs181

License

AGPL-3.0 or later. See LICENSE for detail.

cai.api.client.get_client(uin: Optional[int] = None) → cai.client.client.Client

Get the specific client or existing client.

参数

uin (Optional[int], optional) – Specific account client to get. Defaults to None.

引发

• ClientNotAvailable – Client not exists.

• ClientNotAvailable – No client available.

• ClientNotAvailable – Multiple clients found and not specify which one to get.

返回

Current client to use.

返回类型

Client

async cai.api.client.close(uin: Optional[int] = None) → None

Close an existing client and delete it from clients.

参数

uin (Optional[int], optional) – Account of the client want to close. Defaults to None.

async cai.api.client.close_all() → None

Close all existing clients and delete them.

async cai.api.client.set_status(status: Union[int, cai.client.status_service.OnlineStatus], battery_status: Optional[int] = None, is_power_connected: bool = False, uin: Optional[int] = None) → None

Change client status.

This function wraps the register() method of the client.

参数

• status (OnlineStatus) – Status want to change.

• battery_status (Optional[int], optional) – Battery capacity. Defaults to None.

• is_power_connected (bool, optional) – Is power connected to phone. Defaults to False.

• uin (Optional[int], optional) – Account of the client want to change. Defaults to None.

引发

• RuntimeError – Client already exists and is running.

• RuntimeError – Password not provided when login a new account.

• ApiResponseError – Invalid API request.

• RegisterException – Register Failed.

cai.api.flow module

Application Flow APIs.

Copyright

Copyright (C) 2021-2021 cscs181

License

AGPL-3.0 or later. See LICENSE for detail.

cai.api.flow.add_event_listener(listener: Callable[[cai.client.client.Client, cai.client.event.Event], Awaitable[None]], uin: Optional[int] = None)

Add event listener.

If uin is None, listener will receive events from all clients.

参数

• listener (Callable[[Client, Event], Awaitable[None]]) – Event listener.

• uin (Optional[int], optional) – Account of the client want to listen. Defaults to None.

cai.api.flow.register_packet_handler(cmd: str, packet_handler: Callable[[cai.client.client.Client, cai.client.packet.IncomingPacket], Awaitable[cai.client.command.Command]]) → None

Register custom packet handler.

注解

This function is a low-level api to mock default behavior. Be aware of what you are doing!

参数

• cmd (str) – Command name of the packet.

• packet_handler (Callable[[Client, IncomingPacket], Awaitable[Command]]) – Asynchronous packet handler. A Command object should be returned.

cai.api.friend module

Application Friend APIs.

Copyright

Copyright (C) 2021-2021 cscs181

License

AGPL-3.0 or later. See LICENSE for detail.

async cai.api.friend.get_friend(friend_uin: int, cache: bool = True, uin: Optional[int] = None) → Optional[cai.client.models.Friend]

Get account friend.

This function wraps the get_friend() method of the client.

参数

• friend_uin (int) – Friend account uin.

• cache (bool, optional) – Use cached friend list. Defaults to True.

• uin (Optional[int], optional) – Account of the client want to use. Defaults to None.

返回

Friend object. None: Friend not exists.

返回类型

Friend

引发

• RuntimeError – Error response type got. This should not happen.

• ApiResponseError – Get friend list failed.

• FriendListException – Get friend list returned non-zero ret code.

async cai.api.friend.get_friend_list(cache: bool = True, uin: Optional[int] = None) → List[cai.client.models.Friend]

Get account friend list.

This function wraps the get_friend_list() method of the client.

参数

• cache (bool, optional) – Use cached friend list. Defaults to True.

• uin (Optional[int], optional) – Account of the client want to use. Defaults to None.

返回

List of Friend

引发

• RuntimeError – Error response type got. This should not happen.

• ApiResponseError – Get friend list failed.

• FriendListException – Get friend list returned non-zero ret code.

async cai.api.friend.get_friend_group(group_id: int, cache: bool = True, uin: Optional[int] = None) → Optional[cai.client.models.FriendGroup]

Get Friend Group.

This function wraps the get_friend_group() method of the client.

参数

• group_id (int) – Friend group id.

• cache (bool, optional) – Use cached friend group list. Defaults to True.

• uin (Optional[int], optional) – Account of the client want to use. Defaults to None.

返回

Friend group object. None: Friend group not exists.

返回类型

FriendGroup

引发

• RuntimeError – Error response type got. This should not happen.

• ApiResponseError – Get friend list failed.

• FriendListException – Get friend list returned non-zero ret code.

async cai.api.friend.get_friend_group_list(cache: bool = True, uin: Optional[int] = None) → List[cai.client.models.FriendGroup]

Get account friend group list.

This function wraps the get_friend_group_list() method of the client.

参数

• cache (bool, optional) – Use cached friend group list. Defaults to True.

• uin (Optional[int], optional) – Account of the client want to use. Defaults to None.

返回

Friend group list.

返回类型

List[FriendGroup]

引发

• RuntimeError – Error response type got. This should not happen.

• ApiResponseError – Get friend group list failed.

• FriendListException – Get friend group list returned non-zero ret code.

cai.api.group module

Application Group APIs.

Copyright

Copyright (C) 2021-2021 cscs181

License

AGPL-3.0 or later. See LICENSE for detail.

async cai.api.group.get_group(group_id: int, cache: bool = True, uin: Optional[int] = None) → Optional[cai.client.models.Group]

Get Group.

This function wraps the get_group() method of the client.

参数

• group_id (int) – Group id.

• cache (bool, optional) – Use cached friend group list. Defaults to True.

• uin (Optional[int], optional) – Account of the client want to use. Defaults to None.

返回

Group object. None: Group not exists.

返回类型

Group

引发

• RuntimeError – Error response type got. This should not happen.

• ApiResponseError – Get friend list failed.

• FriendListException – Get friend list returned non-zero ret code.

async cai.api.group.get_group_list(cache: bool = True, uin: Optional[int] = None) → List[cai.client.models.Group]

Get account group list.

This function wraps the get_group_list() method of the client.

参数

• cache (bool, optional) – Use cached group list. Defaults to True.

• uin (Optional[int], optional) – Account of the client want to use. Defaults to None.

返回

Group list.

返回类型

List[Group]

引发

• RuntimeError – Error response type got. This should not happen.

• ApiResponseError – Get group list failed.

• GroupListException – Get group list returned non-zero ret code.

async cai.api.group.get_group_member_list(group: Union[int, cai.client.models.Group], cache: bool = True, uin: Optional[int] = None) → Optional[List[cai.client.models.GroupMember]]

Get account group member list.

This function wraps the get_group_member_list() method of the client.

参数

• group (Union[int, Group]) – Group id or group object want to get members.

• cache (bool, optional) – Use cached group list. Defaults to True.

• uin (Optional[int], optional) – Account of the client want to use. Defaults to None.

返回

Group member list. None: Group not exists.

返回类型

List[GroupMember]

引发

• RuntimeError – Error response type got. This should not happen.

• ApiResponseError – Get group list failed.

• GroupMemberListException – Get group member list returned non-zero ret code.

cai.api.login module

Application Login APIs.

Copyright

Copyright (C) 2021-2021 cscs181

License

AGPL-3.0 or later. See LICENSE for detail.

async cai.api.login.login(uin: int, password_md5: Optional[bytes] = None) → cai.client.client.Client

Create a new client (or use an existing one) and login.

Password md5 should be provided when login a new account.

This function wraps the login() method of the client.

参数

• uin (int) – QQ account number.

• password_md5 (Optional[bytes], optional) – md5 bytes of the password. Defaults to None.

引发

• RuntimeError – Client already exists and is running.

• RuntimeError – Password not provided when login a new account.

• LoginSliderException – Need slider ticket.

• LoginCaptchaException – Need captcha image.

async cai.api.login.submit_captcha(captcha: str, captcha_sign: bytes, uin: Optional[int] = None) → bool

Submit captcha data to login.

This function wraps the submit_captcha() method of the client.

参数

• captcha (str) – Captcha data to submit.

• captcha_sign (bytes) – Captcha sign received when login.

• uin (Optional[int], optional) – Account of the client want to login. Defaults to None.

引发

• RuntimeError – Client already exists and is running.

• RuntimeError – Password not provided when login a new account.

• LoginSliderException – Need slider ticket.

• LoginCaptchaException – Need captcha image.

async cai.api.login.submit_slider_ticket(ticket: str, uin: Optional[int] = None) → bool

Submit slider ticket to login.

This function wraps the submit_slider_ticket() method of the client.

参数

• ticket (str) – Slider ticket to submit.

• uin (Optional[int], optional) – Account of the client want to login. Defaults to None.

引发

• RuntimeError – Client already exists and is running.

• RuntimeError – Password not provided when login a new account.

• LoginSliderException – Need slider ticket.

• LoginCaptchaException – Need captcha image.

async cai.api.login.request_sms(uin: Optional[int] = None) → bool

Request sms code message to login.

This function wraps the request_sms() method of the client.

参数

uin (Optional[int], optional) – Account of the client want to login. Defaults to None.

引发

• RuntimeError – Client already exists and is running.

• RuntimeError – Password not provided when login a new account.

• LoginSMSRequestError – Too many SMS messages were sent.

async cai.api.login.submit_sms(sms_code: str, uin: Optional[int] = None) → bool

Submit sms code to login.

This function wraps the submit_sms() method of the client.

参数

• sms_code (str) – SMS code to submit.

• uin (Optional[int], optional) – Account of the client want to login. Defaults to None.

引发

• RuntimeError – Client already exists and is running.

• RuntimeError – Password not provided when login a new account.

• LoginSliderException – Need slider ticket.

• LoginCaptchaException – Need captcha image.