From f27a275a6c833d9b2a430e0f2d130fa13b00063e Mon Sep 17 00:00:00 2001 From: Seng1e Date: Sun, 17 Jul 2022 23:19:31 +0800 Subject: [PATCH] :memo:Write doc of contact module (#348) --- docs/references/contact.md | 317 ++++++------------------------------ src/wechaty/user/contact.py | 169 +++++++++++++------ 2 files changed, 168 insertions(+), 318 deletions(-) diff --git a/docs/references/contact.md b/docs/references/contact.md index 0c1f297a..f7c2783f 100644 --- a/docs/references/contact.md +++ b/docs/references/contact.md @@ -2,53 +2,53 @@ title: Contact --- -## Classes +> 所有的微信联系人（朋友）都会被封装成一个`Contact`联系人对象。 -所有的微信联系人（朋友）都会被封装成一个`Contact`联系人对象。 +::: wechaty.user.contact.Contact.__init__ +::: wechaty.user.contact.Contact.get_id -## Contact +::: wechaty.user.contact.Contact.load -所有的微信联系人（朋友）都会被封装成一个`Contact`联系人对象。示例: -[示例/Contact-Bot](https://github.com/wechaty/python-wechaty-getting-started/blob/master/examples/basic/contact-bot.py) +::: wechaty.user.contact.Contact.find +### 示例代码 +```python +import asyncio +from wechaty import Wechaty, Contact +from wechaty_puppet import ContactQueryFilter -**类型**: 全局**属性** +class MyBot(Wechaty): -| **属性名** | 类型 | **描述** | -| :--- | :--- | :--- | -| id | `str` | 获取联系人对象的id. 此函数取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table) | + async def on_login(self, contact: Contact) -> None: + contact = await self.Contact.find(ContactQueryFilter(name="lijiarui")) + contact = await self.Contact.find(ContactQueryFilter(alias="ruirui")) -* [Contact](contact.md#Contact) - * _实例方法_ - * [.say\(textOrContactOrFileOrUrl\)](contact.md#Contact+say) ⇒ `Optional[Message]` - * [.name](contact.md#Contact+name)⇒ `str` - * [.alias\(new\_alias\)](contact.md#Contact+alias) ⇒ `Union[None, str]` - * [.is_friend\(\)](contact.md#Contact+friend) ⇒ `bool` - * [.is_offical\(\)](contact.md#Contact+offical) ⇒ `bool` - * [.is_personal\(\)](contact.md#Contact+personal) ⇒ `bool` - * [.type\(\)](contact.md#Contact+type) ⇒ `ContactType.CONTACT_TYPE_UNSPECIFIED` \| `ContactType.CONTACT_TYPE_PERSONAL` \| `ContactType.CONTACT_TYPE_OFFICIAL` \| `ContactType.CONTACT_TYPE_CORPORATION` - * [.gender\(\)](contact.md#Contact+gender) ⇒ `ContactGender.CONTACT_GENDER_UNSPECIFIED` \| `ContactGender.CONTACT_GENDER_MALE` \| `ContactGender.CONTACT_GENDER_FEMALE` - * [.province\(\)](contact.md#Contact+province) ⇒ `Optional[str]` - * [.city\(\)](contact.md#Contact+city) ⇒ `Optional[str]` - * [.avatar\(\)](contact.md#Contact+avatar) ⇒ `FileBox` - * [.sync\(\)](contact.md#Contact+sync) ⇒ `None` - * [.is_self\(\)](contact.md#Contact+self) ⇒ `bool` - * _静态方法_ - * [.find\(query\)](contact.md#Contact.find) ⇒ `Optional[Contact]` - * [.find_all\(\[queryArg\]\)](contact.md#Contact.findAll) ⇒ `List[Contact]` +asyncio.run(MyBot().start()) +``` -### async def say\(self, message: `Union[str, Message, FileBox, Contact, UrlLink]`\) ⇒ `Optional[Message]` +::: wechaty.user.contact.Contact.find_all +### 示例代码 +```python +import asyncio +from wechaty import Wechaty, Contact +from wechaty_puppet import ContactQueryFilter -> 提示: 此功能取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table) +class MyBot(Wechaty): -**类型**: [`Contact`](contact.md#Contact)的实例方法 + async def on_login(self, contact: Contact) -> None: + contact = await self.Contact.find_all() # 获取一个列表, 里面包含了Bot所有的联系人 + contact = await self.Contact.find_all(ContactQueryFilter(name="lijiarui")) # 获取一个包含所有名字为lijiarui的联系人的列表 + contact = await self.Contact.find_all(ContactQueryFilter(alias="ruirui")) # 获取一个包含所有别名(备注)为ruirui的联系人的列表 + +asyncio.run(MyBot().start()) +``` -| 参数 | 类型 | 描述 | -| :--- | :--- | :--- | -| 文本, 联系人对象, 文件对象, 链接或者小程序对象 | `str` \| [`Contact`](contact.md#Contact) \| `FileBox` \| `UrlLink` \| `MiniProgram` | 发送文本、联系人名片、文件或链接到目标联系人。 您可以使用 [FileBox](https://github.com/wechaty/python-wechaty-puppet/tree/master/src/wechaty_puppet/file_box) 类来发送文件。 | -#### 示例 +::: wechaty.user.contact.Contact.ready + +::: wechaty.user.contact.Contact.say +### 示例代码 ```python import asyncio from wechaty import Wechaty, Contact, FileBox, UrlLink @@ -100,129 +100,29 @@ class MyBot(Wechaty): asyncio.run(MyBot().start()) ``` -### `@property` def name\(self\) ⇒ `str` - -获取联系人对象的名字 - -**类型**: [`Contact`](contact.md#Contact) 的实例方法 - -**示例:** - -```python -name: str = contact.name -``` - -### async def alias\(self, `new_alias: Optional[str]` = None\) ⇒ `Union[None, str]` - -为一个联系人获取 / 设置 / 删除别名 - -> 测试表明如果过于频繁地设置别名会导致失败\(每分钟60次\). - -**类型**: [`Contact`](contact.md#Contact)对象的实例方法 - -**返回值**: Union\[None, str\] - -| 参数 | 类型 | -| :--- | :--- | -| newAlias | Optional\[str\] | - -**示例:** -_\(**获取**联系人对象的别名\(备注\)_ +::: wechaty.user.contact.Contact.name +::: wechaty.user.contact.Contact.alias +### 示例代码 ```python alias = await contact.alias() if alias is None or alias == "": print('您还没有为联系人设置任何别名' + contact.name) else: print('您已经为联系人设置了别名 ' + contact.name + ':' + alias) -``` -**示例** - -_\(为一个联系人**设置**别名\(备注\)\)_ - -```python -try: - await contact.alias('lijiarui') - print(f"改变{contact.name}的备注成功!") -except Exception: - print(f"改变{contact.name}的备注失败~") -``` - -**示例** - -_\(**删除**给联系人设置的别名\(备注\)\)_ - -```python -try: - oldAlias = await contact.alias(None) - print(f"成功删除{contact.name}的备注!") - print(f"旧的备注名为{oldAlias}") -except Exception: - print(f"删除{contact.name}的备注失败!") ``` -### def is_friend\(self\) ⇒ `Optional[bool]` - -检查这个联系人对象是否是自己的朋友 - -> 注意: 此功能取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table) - -**类型**: [`Contact`](contact.md#Contact) 的实例方法 - -**返回值**: `Optional[bool]` - 如果是自己的朋友则返回True, 不是则返回False, Unknown(未知)则返回None. - -**示例** - -```python -isFriend = contact.is_friend() -print(isFriend) -``` - -### def is_offical\(self\) ⇒ `bool` - -检查这个联系人对象是否是公众号 - -> 注意: 此功能取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table) +::: wechaty.user.contact.Contact.is_friend -**类型**: [`Contact`](contact.md#Contact) 的实例方法 +::: wechaty.user.contact.Contact.is_offical -**返回值**: `Optional[bool]` - 如果是公众号则返回True, 不是则返回False, Unknown(未知)则返回None. - -**示例** - -```python -isFriend = contact.is_offical() -print(isFriend) -``` - -### def is_personal\(self) ⇒ `bool` - -检查这个联系人对象是否是个人账号 - -> 注意: 此功能取决于Puppet的实现, 详见 [Puppet兼容表](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table) - -**类型**: [`Contact`](contact.md#Contact) 的实例方法 - -**返回值**: `Optional[bool]` - 如果是个人账号则返回True, 不是则返回False, Unknown(未知)则返回None. - -**示例** - -```python -isFriend = contact.is_personal() -print(isFriend) -``` - -### def type\(self\) ⇒ `ContactType.CONTACT_TYPE_UNSPECIFIED` \| `ContactType.CONTACT_TYPE_PERSONAL` \| `ContactType.CONTACT_TYPE_OFFICIAL` \| `CONTACT_TYPE_CORPORATION` - -返回联系人的类型 +::: wechaty.user.contact.Contact.is_personal +::: wechaty.user.contact.Contact.type +### 示例代码 > 注意: ContactType是个枚举类型. -**类型**: [`Contact`](contact.md#Contact)的实例方法 - -**示例** - ```python import asyncio from wechaty import Wechaty, Message, ContactType @@ -236,16 +136,12 @@ class MyBot(Wechaty): asyncio.run(MyBot().start()) ``` -### def gender(self)\(\) ⇒ `ContactGender.CONTACT_GENDER_UNSPECIFIED` \| `ContactGender.CONTACT_GENDER_MALE` \| `ContactGender.CONTACT_GENDER_FEMALE` - -获取联系人的性别 +::: wechaty.user.contact.Contact.star +::: wechaty.user.contact.Contact.gender +### 示例代码 > 注意: ContactGender是个枚举类型. -**类型**: [`Contact`](contact.md#Contact)的实例方法 - -**示例** - ```python import asyncio from wechaty import Wechaty, Message, ContactGender @@ -261,38 +157,11 @@ class MyBot(Wechaty): asyncio.run(MyBot().start()) ``` -### def province\(self\) ⇒ `Optional[str]` - -获取一个联系人-的省份信息 -**类型**: [`Contact`](contact.md#Contact)的实例方法 - -**示例** - -```python -province: str = contact.province() -``` - -### def city(self) ⇒ `Optional[str]` - -获取联系人所设置的城市 - -**类型**: [`Contact`](contact.md#Contact)的实例方法 - -**示例** - -```python -city: str = contact.city() -``` - -### sync def avatar\(self, file_box: `Optional[FileBox]` = None\) ⇒ `FileBox` - -获取联系人头像图片的文件流 - -**类型**: [`Contact`](contact.md#Contact)的实例方法 - -**示例** +::: wechaty.user.contact.Contact.city +::: wechaty.user.contact.Contact.avatar +### 示例代码 ```python # 以类似 `1-name.jpg`的格式保存头像图片到本地 import asyncio @@ -310,95 +179,12 @@ class MyBot(Wechaty): asyncio.run(MyBot().start()) ``` -### async def sync\(self\) ⇒ `None` - -强制重新加载联系人的数据，再次从低级 API 同步数据。 - -**类型**: [`Contact`](contact.md#Contact)的实例方法 - -**示例** - -```python -await contact.sync() -``` - -### def is_self\(self\) ⇒ `bool` - -检查该联系人对象是不是Bot自身 - -**类型**: [`Contact`](contact.md#Contact)的实例方法 - -**返回值**: `bool` - 如果该联系人对象是Bot自身则返回True, 若不是则返回False - -**示例** - -```python -is_self: bool = contact.self() -``` - -### `@classmethod` async def find\(cls, query: `Union[str, ContactQueryFilter, Callable[[Contact], bool]]`\) ⇒ `Optional[Contact]` - -尝试通过过滤器查找联系人: {name: string \| RegExp} / {alias: string \| RegExp} - -通过联系人的名字(name)或者别名(alias)来获取联系人对象, 如果查找的结果大于一个, 则返回第一个. - -**类型**: [`Contact`](contact.md#Contact)的**静态方法** - -**返回值**: `Optional[Contact]` - 如果能找到联系人，则返回找到的联系人对象，否则返回`None` +::: wechaty.user.contact.Contact.tags -| 参数 | 类型 | -| :--- | :--- | -| query | [`ContactQueryFilter`](contact.md#ContactQueryFilter) | +::: wechaty.user.contact.Contact.is_self -#### 示例 +::: wechaty.user.contact.Contact.weixin -```python -import asyncio -from wechaty import Wechaty, Contact -from wechaty_puppet import ContactQueryFilter - -class MyBot(Wechaty): - - async def on_login(self, contact: Contact) -> None: - contact = await self.Contact.find(ContactQueryFilter(name="lijiarui")) - contact = await self.Contact.find(ContactQueryFilter(alias="ruirui")) - -asyncio.run(MyBot().start()) -``` - -### `@classmethod` async def find_all\(cls, query: `Optional[Union[str, ContactQueryFilter, Callable[[Contact], bool]]]` = None\) -> `List[Contact]` - -通过 `name` 或者 `alias` 查找并获取联系人对象 - -使用 Contact.find_all\(\) 获取机器人的联系人列表。 包括来自机器人加入的房间内的联系人。 - -#### 定义 - -* `name` 由用户自己设置的名字, 叫做name -* `alias` 由Bot为联系人设置的名字\(备注/别名\). 该值可以传入正则表达式用于搜索用户 - -**类型**: [`Contact`](contact.md#Contact)的**静态方法** - -| 参数 | 类型 | -| :--- | :--- | -| queryArg | [`ContactQueryFilter`](contact.md#ContactQueryFilter) | - -#### 示例 - -```python -import asyncio -from wechaty import Wechaty, Contact -from wechaty_puppet import ContactQueryFilter - -class MyBot(Wechaty): - - async def on_login(self, contact: Contact) -> None: - contact = await self.Contact.find_all() # 获取一个列表, 里面包含了Bot所有的联系人 - contact = await self.Contact.find_all(ContactQueryFilter(name="lijiarui")) # 获取一个包含所有名字为lijiarui的联系人的列表 - contact = await self.Contact.find_all(ContactQueryFilter(alias="ruirui")) # 获取一个包含所有别名(备注)为ruirui的联系人的列表 - -asyncio.run(MyBot().start()) -``` ## Typedefs 类型定义 ### [ContactQueryFilter](contact.md#ContactQueryFilter) @@ -409,3 +195,4 @@ asyncio.run(MyBot().start()) | ---------- | -------- | ------------------------------------------------------------ | | name | `str` | 由用户本身(user-self)设置的名字, 叫做name | | alias | `str` | 由Bot为联系人设置的名字(备注/别名). 该值可以传入正则表达式用于搜索用户, 更多细节详见[issues#365](https://github.com/wechaty/wechaty/issues/365)和[源码](https://github.com/wechaty/python-wechaty-puppet/blob/master/src/wechaty_puppet/schemas/contact.py) | + diff --git a/src/wechaty/user/contact.py b/src/wechaty/user/contact.py index e37ef1ca..02cb8d97 100644 --- a/src/wechaty/user/contact.py +++ b/src/wechaty/user/contact.py @@ -73,23 +73,26 @@ class Contact(Accessory[ContactPayload], AsyncIOEventEmitter): _pool: Dict[str, 'Contact'] = {} def __init__(self, contact_id: str): - """init Contact object with id which will not be cached, - so we suggest that you use load method to get a cached contact object + """ + Init Contact object with id which will not be cached, + + so we suggest that you use load method to get a cached contact object + + Args: + contact_id (str): the union identifier of contact Examples: >>> contact = bot.Contact(contact_id) >>> # but the following method is suggested >>> contact = bot.Contact.load(contact_id) - - Args: - contact_id (str): the union identifier of contact """ super().__init__() self.contact_id: str = contact_id self.payload: Optional[ContactPayload] = None def get_id(self) -> str: - """get the contact_id + """ + Get the contact_id Examples: >>> contact_id = contact.get_id() @@ -101,19 +104,20 @@ def get_id(self) -> str: @classmethod def load(cls: Type[Contact], contact_id: str) -> Contact: - """load contact object, if it's not cached, create a new one and cache it. + """ + Load contact object, if it's not cached, create a new one and cache it. If you load it manually, you should call `ready()` to load the full info from puppet. + Args: + cls: the type of Contact + contact_id: the union identifier of contact + Examples: >>> contact = bot.Contact.load(contact_id) >>> await contact.ready() >>> is_friend = contact.is_friend() - Args: - cls (Type[Contact]): the type of Contact - contact_id (str): the union identifier of contact - Returns: Contact: the contact object """ @@ -181,13 +185,11 @@ async def find(cls, query: Union[str, ContactQueryFilter, Callable[[Contact], bool]] ) -> Optional[Contact]: """ - find the first of contacts based on query, which can be string, ContactQueryFilter, or callable function + Find the first of contacts based on query, which can be string, ContactQueryFilter, or callable function. Args: query: the query body to build filter - Args: - query: - + Examples: >>> # 1. find contacts based query string, will match one of: contact_id, weixin, name and alias >>> # what's more, contact_id and weixin will follow extract match, name and alias will follow fuzzy match @@ -205,7 +207,8 @@ async def find(cls, >>> return True >>> return False >>> Contact.find(filter_contacts) - Returns: filtered contact, None or Contact + Returns: + Contact: the contact object filtered by query or None """ log.info('find() <%s, %s>', cls, query) @@ -219,12 +222,10 @@ async def find_all(cls: Type[Contact], query: Optional[Union[str, ContactQueryFilter, Callable[[Contact], bool]]] = None ) -> List[Contact]: """ - find all contacts based on query, which can be string, ContactQueryFilter, or callable function + Find all contacts based on query, which can be string, ContactQueryFilter, or callable function. Args: query: the query body to build filter - Args: - query: Examples: >>> # 1. find contacts based query string, will match one of: contact_id, weixin, name and alias @@ -243,7 +244,9 @@ async def find_all(cls: Type[Contact], >>> return True >>> return False >>> Contact.find_all(filter_contacts) - Returns: filtered contacts/ + + Returns: + Contact: the contact object filtered by query """ log.info('find_all() <%s, %s>', cls, query) @@ -262,15 +265,16 @@ async def find_all(cls: Type[Contact], return contacts async def ready(self, force_sync: bool = False) -> None: - """make contact ready for use which will load contact payload info. + """ + Make contact ready for use which will load contact payload info. + + Args: + force_sync: if true, it will re-fetch the data although it exist. Examples: >>> contact = Contact.load('contact-id') >>> await await contact.ready() - Args: - force_sync (bool, optional): if true, it will re-fetch the data although it exist. Defaults to False. - Raises: WechatyPayloadError: when payload can"t be loaded """ @@ -288,7 +292,7 @@ async def ready(self, force_sync: bool = False) -> None: def __str__(self) -> str: """ - get contact string representation + Get contact string representation. """ if not self.is_ready() or not self.payload: return 'Contact <{}>'.format(self.contact_id) @@ -307,6 +311,13 @@ async def say(self, message: Union[str, Message, FileBox, Contact, UrlLink, Mini ) -> Optional[Message]: """say something to contact, which can be text, image, file, contact, url + Note: + Its implementation depends on the puppet, so if you want to use this method, please check + [Puppet](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table). + + Args: + message: the message object to be sended to contact + Examples: >>> contact = Contact.load('contact-id') >>> await contact.say('hello') @@ -317,11 +328,8 @@ async def say(self, message: Union[str, Message, FileBox, Contact, UrlLink, Mini >>> # the data format of mini program should pre-stored >>> await contact.say(MiniProgram('username', 'appid')) - Args: - message (Union[str, Message, FileBox, Contact, UrlLink, MiniProgram]): the message object to be sended to contact - Returns: - Optional[Message]: if the message is send successfully, return the message object, otherwise return None + Message: if the message is send successfully, return the message object, otherwise return None """ if not message: log.error('can"t say nothing') @@ -377,7 +385,10 @@ async def say(self, message: Union[str, Message, FileBox, Contact, UrlLink, Mini @property def name(self) -> str: """get name of contact - + Examples: + >>> contact = Contact.load('contact-id') + >>> name: str = contact.name + Returns: str: name of contact, if the payload is None, return empty string """ @@ -388,15 +399,20 @@ def name(self) -> str: async def alias(self, new_alias: Optional[str] = None ) -> Union[None, str]: - """get or set alias of contact. - If new_alias is given, it will set alias to new_alias, - otherwise return current alias + """ + Get or set alias of contact. + + If new_alias is given, it will set alias to new_alias, + otherwise return current alias + + Notes: + Setting aliases too often will result in failure (60 times per minute). Args: - new_alias (Optional[str], optional): the new alias of contact. Defaults to None. + new_alias: the new alias of contact. Returns: - Union[None, str]: the current alias of contact + alias: the current alias of contact """ log.info('Contact alias <%s>', new_alias) if not self.is_ready(): @@ -419,14 +435,15 @@ async def alias(self, return None def is_friend(self) -> Optional[bool]: - """check if the contact is friend + """ + Check if the contact is friend. Examples: >>> contact = Contact.load('contact-id') >>> is_friend = contact.is_friend() Returns: - Optional[bool]: if the contact is friend, return True, otherwise return False + bool: if the contact is friend, return True, otherwise return False """ if not self.payload: log.warning('please call `ready()` before `is_friend()`') @@ -438,7 +455,12 @@ def is_friend(self) -> Optional[bool]: return self.payload.friend def is_offical(self) -> bool: - """check if the contact is offical account + """ + Check if the contact is offical account. + + Notes: + Its implementation depends on the puppet, so if you want to use this method, please check + [Puppet](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table). Examples: >>> contact = Contact.load('contact-id') @@ -452,7 +474,16 @@ def is_offical(self) -> bool: return self.payload.type == ContactType.CONTACT_TYPE_OFFICIAL def is_personal(self) -> bool: - """check if the contact is personal account + """ + Check if the contact is personal account. + + Notes: + Its implementation depends on the puppet, so if you want to use this method, please check + [Puppet](https://github.com/wechaty/wechaty/wiki/Puppet#3-puppet-compatible-table). + + Examples: + >>> contact = Contact.load('contact-id') + >>> is_personal = contact.is_personal() Returns: bool: if the contact is personal account, return True, otherwise return False @@ -462,7 +493,12 @@ def is_personal(self) -> bool: return self.payload.type == ContactType.CONTACT_TYPE_PERSONAL def type(self) -> ContactType: - """get type of contact, which can person, official, corporation, and unspecified. + """ + Get type of contact, which can person, official, corporation, and unspecified. + + Examples: + >>> contact = Contact.load('contact-id') + >>> contact_type = contact.type() Returns: ContactType: the type of contact. @@ -472,18 +508,24 @@ def type(self) -> ContactType: return self.payload.type def star(self) -> Optional[bool]: - """check if the contact is a stared contact + """ + Check if the contact is a stared contact. + + Examples: + >>> contact = Contact.load('contact-id') + >>> is_star = contact.star() Returns: - Optional[bool]: if the contact is a stared contact, return True, otherwise return False. + bool: if the contact is a stared contact, return True, otherwise return False. """ if self.payload is None: return None return self.payload.star def gender(self) -> ContactGender: - """return the gender of contact - + """ + Return the gender of contact. + Returns: ContactGender: the object of contact gender """ @@ -492,7 +534,11 @@ def gender(self) -> ContactGender: return ContactGender.CONTACT_GENDER_UNSPECIFIED def province(self) -> Optional[str]: - """get the province of contact + """ + Get the province of contact. + + Examples: + >>> province: str = contact.province() Returns: Optional[str]: the province info in contact public info @@ -502,7 +548,12 @@ def province(self) -> Optional[str]: return self.payload.province def city(self) -> Optional[str]: - """get the city of contact + """ + Get the city of contact. + + Examples: + >>> contact = Contact.load('contact-id') + >>> city: str = contact.city() Returns: Optional[str]: the city info in contact public info @@ -512,11 +563,16 @@ def city(self) -> Optional[str]: return self.payload.city async def avatar(self, file_box: Optional[FileBox] = None) -> FileBox: - """get or set the avatar of contact, which is a FileBox object + """ + Get or set the avatar of contact, which is a FileBox object Args: - file_box (Optional[FileBox], optional): If given, it will set it as new avatar, + file_box: If given, it will set it as new avatar, else get the current avatar. Defaults to None. + + Examples: + >>> contact = Contact.load('contact-id') + >>> avatar = contact.avatar() Returns: FileBox: the avatar of contact @@ -526,14 +582,15 @@ async def avatar(self, file_box: Optional[FileBox] = None) -> FileBox: return avatar async def tags(self) -> List[Tag]: - """get the tags of contact which is a list of Tag object + """ + Get the tags of contact which is a list of Tag object. Examples: >>> contact = Contact.load('contact-id') >>> tags = await contact.tags() Returns: - List[Tag]: the tags of contact + List: the tags of contact """ log.info('load contact tags for %s', self) tag_ids = await self.puppet.tag_contact_list(self.contact_id) @@ -548,7 +605,8 @@ async def sync(self) -> None: await self.ready() def is_self(self) -> bool: - """check if the contact is self + """ + Check if the contact is self. Examples: >>> contact = Contact.load('contact-id') @@ -561,10 +619,15 @@ def is_self(self) -> bool: return login_user.contact_id == self.contact_id def weixin(self) -> Optional[str]: - """get the weixin union identifier of contact, which is specific for wechat account. + """ + Get the weixin union identifier of contact, which is specific for wechat account. + Examples: + >>> contact = Contact.load('contact-id') + >>> weixin = contact.weixin() + Returns: - Optional[str]: the weixin union identifier of contact + identifier: the weixin union identifier of contact """ if self.payload is None: return None