Improve Docs: contact part

docs/introduction/use-padlocal-protocol.md

@@ -14,7 +14,7 @@
 
 ### 2.2 PadLocal
 
-当然也有一定的解决方案：商家可以换对应的IP池，通过不定期的购买新的IP来减少消息扎堆的问题。这种方法虽然是缓解了这个问题，可是羊毛出在羊身上，维护成本打了，`TOKEN`肯定就贵了，对于双方来说都不太好。于是社区就基于Pad协议提出了`Local`的概念：[wechaty-puppet-padlocal](https://github.com/wechaty/wechaty-puppet-padlocal).
+当然也有一定的解决方案：商家可以换对应的IP池，通过不定期的购买新的IP来减少消息扎堆的问题。这种方法虽然是缓解了这个问题，可是羊毛出在羊身上，维护成本大了，`TOKEN`肯定就贵了，对于双方来说都不太好。于是社区就基于Pad协议提出了`Local`的概念：[wechaty-puppet-padlocal](https://github.com/wechaty/wechaty-puppet-padlocal).
 
 要使用此协议，必须在本地开启一个Gateway来发送和接受官方服务器发送过来的消息，这样消息的来源和发送目的地都是由开发者自己决定，就类似于电脑的客户端接受和发送消息，这样就极大程度上减小了账号风险系数，这也是协议中`Local`的原因。
 

docs/references/contact-self.md

@@ -2,120 +2,176 @@
 title: ContactSelf
 ---
 
-Bot itself will be encapsulated as a ContactSelf. This class is extends Contact.
+机器人本身被封装为一个`ContactSelf`类。 这个类继承自联系人`Contact`类。
 
 ## ContactSelf
 
-Bot itself will be encapsulated as a ContactSelf.
+机器人本身被封装为一个`ContactSelf`类。
 
-> Tips: this class is extends Contact
+> 提示: 这个类继承自联系人`Contact`类。
 
-**Kind**: global class
+**类型**: 公共类
 
-* [ContactSelf](contact-self.md#contactself)
-  * [intance](contact-self.md#contactself)
-    * [contactSelf.avatar\(\[file\]\) ⇒ `Promise <void | FileBox>`](contact-self.md#contactselfavatarfile-⇒-promise)
-    * [contactSelf.qrcode\(\) ⇒ `Promise <string>`](contact-self.md#contactselfqrcode-⇒-promise)
-    * [contactSelf.signature\(signature\) ⇒ `Promise <string>`](contact-self.md#contactselfsignaturesignature)
-    * [contactSelf.name\(\[name\]\) ⇒ `Promise <void> | string`](contact-self.md#contactselfname-⇒-promisestring)
+* [contact_self](contact-self.md#contactself)
+  * [实例方法](contact-self.md#contactself)
+    * [contact_self.avatar\(\[file\]\) ⇒ `Optinal[FileBox]`](contact-self.md#contactselfavatarfile-⇒-promise)
+    * [contact_self.qrcode\(\) ⇒ `str`](contact-self.md#contactselfqrcode-⇒-str)
+    * [contact_self.signature\(signature\) ⇒ `None`](contact-self.md#contactselfsignaturesignature)
+    * [contact_self.name\(\) ⇒ `str`](contact-self.md#contactselfname-⇒-str)
+    * [contact_self.set_name\(\[name\]\) ⇒ `None`](contact-self.md#contactselfset_name-⇒-str)
 
-### contactSelf.avatar\(\[file\]\) ⇒ `Promise <void | FileBox>`
+### async def avatar(self, file: `Optional[FileBox]` = None) ⇒ `Optinal[FileBox]`
 
-GET / SET bot avatar
+获取/设置 机器人所使用账号的头像
 
-**Kind**: instance method of [`ContactSelf`](contact-self.md#ContactSelf)
+**类型**: [`ContactSelf`](contact-self.md#ContactSelf)类的实例方法
 
-| Param | Type |
+| 参数 | 类型 |
 | :--- | :--- |
 | \[file\] | `FileBox` |
 
-**Example** _\( GET the avatar for bot, return {Promise&lt;FileBox&gt;}\)_
+**示例** 
 
-```javascript
-// Save avatar to local file like `1-name.jpg`
+_\( 获取机器人账号的头像, 返回`FileBox`类型的对象\)_
 
-bot.on('login', async user => {
-  console.log(`user ${user} login`)
-  const file = await user.avatar()
-  const name = file.name
-  await file.toFile(name, true)
-  console.log(`Save bot avatar: ${user.name()} with avatar file: ${name}`)
-})
+```python
+# 保存头像到本地文件, 类似 `1-name.jpg`的格式
+import asyncio
+from wechaty import Wechaty, FileBox, Contact
+
+class MyBot(Wechaty):
+
+    async def on_login(self, contact: Contact) -> None:
+        print(f"用户{contact}登入")
+        file: FileBox = await contact.avatar()
+        name = file.name
+        await file.to_file(name, True)
+        print(f"保存头像: {contact.name} 和头像文件: {name}")
+
+
+asyncio.run(MyBot().start())
 ```
 
-**Example** _\(SET the avatar for a bot\)_
+**示例** 
+
+_\(设置机器人账号的头像\)_
+
+```python
+import asyncio
+from wechaty import Wechaty, FileBox, Contact
+
+class MyBot(Wechaty):
+
+    async def on_login(self, contact: Contact) -> None:
+        print(f"用户{contact}登入")
+        file_box: FileBox = FileBox.from_url('https://wechaty.github.io/wechaty/images/bot-qr-code.png')
+        await contact.avatar(file_box)
+        print(f"更改账号头像成功")
+
 
-```javascript
-import { FileBox }  from 'file-box'
-bot.on('login', user => {
-  console.log(`user ${user} login`)
-  const fileBox = FileBox.fromUrl('https://wechaty.github.io/wechaty/images/bot-qr-code.png')
-  await user.avatar(fileBox)
-  console.log(`Change bot avatar successfully!`)
-})
+asyncio.run(MyBot().start())
 ```
 
-### contactSelf.qrcode\(\) ⇒ `Promise <string>`
+### async def qr_code(self) ⇒ `str`
 
-Get bot qrcode
+获取机器人账号的二维码链接
 
-**Kind**: instance method of [`ContactSelf`](contact-self.md#ContactSelf)
+**类型**: [`ContactSelf`](contact-self.md#ContactSelf)的实例方法
 
-#### Example
+#### 示例
 
-```javascript
-import { generate } from 'qrcode-terminal'
-bot.on('login', async user => {
-  console.log(`user ${user} login`)
-  const qrcode = await user.qrcode()
-  console.log(`Following is the bot qrcode!`)
-  generate(qrcode, { small: true })
-})
+```python
+import asyncio
+from wechaty import Wechaty
+from wechaty.user import ContactSelf
+from wechaty.utils.qrcode_terminal import qr_terminal_str
+
+class MyBot(Wechaty):
+
+    async def on_login(self, contact: ContactSelf) -> None:
+        print(f"用户{contact}登入")
+        qr_code = await contact.qr_code()  # 获取二维码信息
+        print(qr_terminal_str(qr_code)) # 在控制台打印二维码
+
+asyncio.run(MyBot().start())
 ```
 
-### contactSelf.signature\(signature\) ⇒ `Promise <void>`
+### async def signature(self, signature: `str`) ⇒ `None`
 
-Change bot signature
+更改机器人账号的签名
 
-**Kind**: instance method of [`ContactSelf`](contact-self.md#ContactSelf)
+**类型**: [`ContactSelf`](contact-self.md#ContactSelf)的实例方法
 
-| Param | Description |
-| :--- | :--- |
-| signature | The new signature that the bot will change to |
-
-#### Example
-
-```javascript
-bot.on('login', async user => {
-  console.log(`user ${user} login`)
-  try {
-    await user.signature(`Signature changed by wechaty on ${new Date()}`)
-  } catch (e) {
-    console.error('change signature failed', e)
-  }
-})
+| 参数 |  类型 | 描述 |
+| :--- | :--- | :--- |
+| signature | `str` | 您想要改变的新的签名 |
+
+#### 示例
+
+```python
+import sys
+import asyncio
+from datetime import datetime
+from wechaty import Wechaty
+from wechaty.user import ContactSelf
+
+class MyBot(Wechaty):
+
+    async def on_login(self, contact: ContactSelf) -> None:
+        print(f"用户{contact}登入")
+        try:
+            await contact.signature(f"签名被Wechaty更改于{datetime.now()}")
+        except Exception as e:
+            print("更改签名失败", e, file=sys.stderr)
+
+asyncio.run(MyBot().start())
 ```
 
-### contactSelf.name\(\[name\]\) ⇒ `Promise<void> | string`
+### `@property` def name(self) ⇒ `str`   
 
-Get or change bot name.
+获取机器人的名字
 
-**Kind**: instance method of [`ContactSelf`](contact-self.md#contactself)
+**类型**: [`ContactSelf`](contact-self.md#contactself)的实例方法
 
-| Param | Description |
-| :--- | :--- |
-| \[name\] | The new alias that the bot will change to |
-
-#### Example
-
-```javascript
-bot.on('login', async user => {
-  console.log(`user ${user} login`)
-  const oldName = user.name() // get bot name
-  try {
-    await user.name(`${oldName}-${new Date().getTime()}`) // change bot name
-  } catch (e) {
-    console.error('change name failed', e)
-  }
-})
+
+#### 示例 \(更改名字与获取名字\)
+
+```python
+import sys
+import asyncio
+from datetime import datetime
+from wechaty import Wechaty
+from wechaty.user import ContactSelf
+
+
+class MyBot(Wechaty):
+
+    async def on_login(self, contact: ContactSelf) -> None:
+        old_name = contact.name  # 获取Bot账号的名字
+        print(old_name)
+
+asyncio.run(MyBot().start())
+```
+
+### async def set_name(self, name: `str`) -> `None`:
+
+获取机器人的名字
+
+**类型**: [`ContactSelf`](contact-self.md#contactself)的实例方法
+
+```python
+import sys
+import asyncio
+from datetime import datetime
+from wechaty import Wechaty
+from wechaty.user import ContactSelf
+
+
+class MyBot(Wechaty):
+
+    async def on_login(self, contact: ContactSelf) -> None:
+        old_name = contact.name  # 获取Bot账号的名字
+        contact.set_name(f"{old_name}{datetime.now()}")  # 更改Bot账号的名字
+
+asyncio.run(MyBot().start())
 ```