📝Write doc of contact module (#348)

wechaty · Jul 17, 2022 · f27a275 · f27a275
1 parent 696eb29
commit f27a275
Show file tree

Hide file tree

Showing 2 changed files with 168 additions and 318 deletions.
diff --git 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) |
+