62 | {%- block content %}
63 |
67 |
68 |
76 |
77 | {%- block scripts %}
78 |
79 | {%- for path in extra_javascript %}
80 |
81 | {%- endfor %}
82 | {%- endblock %}
83 |
84 |
85 |
--------------------------------------------------------------------------------
/docs/bootstrap/nav.html:
--------------------------------------------------------------------------------
1 |
82 |
--------------------------------------------------------------------------------
/docs/intro/handler.md:
--------------------------------------------------------------------------------
1 | # 注册消息方法
2 |
3 | itchat将根据接收到的消息类型寻找对应的已经注册的方法。
4 |
5 | 如果一个消息类型没有对应的注册方法，该消息将会被舍弃。
6 |
7 | 在运行过程当中也可以动态注册方法，注册方式与结果不变。
8 |
9 | ## 注册
10 |
11 | 你可以通过两种方式注册消息方法
12 |
13 | ```python
14 | import itchat
15 | from itchat.content import *
16 |
17 | # 不带具体对象注册，将注册为普通消息的回复方法
18 | @itchat.msg_register(TEXT)
19 | def simple_reply(msg):
20 | return 'I received: %s' % msg['Text']
21 |
22 | # 带对象参数注册，对应消息对象将调用该方法
23 | @itchat.msg_register(TEXT, isFriendChat=True, isGroupChat=True, isMpChat=True)
24 | def text_reply(msg):
25 | msg.user.send('%s: %s' % (msg.type, msg.text))
26 | ```
27 |
28 | ## 消息类型
29 |
30 | 向注册方法传入的msg包含微信返回的字典的所有内容。
31 |
32 | 本api增加`Text`、`Type`（也就是参数）键值，方便操作。
33 |
34 | itchat.content中包含所有的消息类型参数，内容如下表所示：
35 |
36 | 参数 |类型 |Text键值
37 | :----------|:----------|:---------------
38 | TEXT |文本 |文本内容
39 | MAP |地图 |位置文本
40 | CARD |名片 |推荐人字典
41 | NOTE |通知 |通知文本
42 | SHARING |分享 |分享名称
43 | PICTURE |图片/表情 |下载方法
44 | RECORDING |语音 |下载方法
45 | ATTACHMENT |附件 |下载方法
46 | VIDEO |小视频 |下载方法
47 | FRIENDS |好友邀请 |添加好友所需参数
48 | SYSTEM |系统消息 |更新内容的用户或群聊的UserName组成的列表
49 |
50 | 比如你需要存储发送给你的附件：
51 |
52 | ```python
53 | @itchat.msg_register(ATTACHMENT)
54 | def download_files(msg):
55 | msg['Text'](msg['FileName'])
56 | ```
57 |
58 | 值得注意的是，群消息增加了三个键值：
59 |
60 | * isAt: 判断是否@本号
61 | * ActualNickName: 实际NickName
62 | * Content: 实际Content
63 |
64 | 可以通过本程序测试：
65 |
66 | ```python
67 | import itchat
68 | from itchat.content import TEXT
69 |
70 | @itchat.msg_register(TEXT, isGroupChat=True)
71 | def text_reply(msg):
72 | print(msg.isAt)
73 | print(msg.actualNickName)
74 | print(msg.text)
75 |
76 | itchat.auto_login()
77 | itchat.run()
78 | ```
79 |
80 | ## 注册消息的优先级
81 |
82 | 优先级分别为：后注册消息先于先注册消息，带参数消息先于不带参数消息。
83 |
84 | 以下面的两个程序为例：
85 |
86 | ```python
87 | import itchat
88 | from itchat.content import *
89 |
90 | itchat.auto_login()
91 |
92 | @itchat.msg_register(TEXT)
93 | def text_reply(msg):
94 | return 'This is the old register'
95 |
96 | @itchat.msg_register(TEXT)
97 | def text_reply(msg):
98 | return 'This is a new one'
99 |
100 | itchat.run()
101 | ```
102 |
103 | 在私聊发送文本时将会回复`This is a new one`。
104 | ```python
105 | import itchat
106 | from itchat.content import *
107 |
108 | itchat.auto_login()
109 |
110 | @itchat.msg_register
111 | def general_reply(msg):
112 | return 'I received a %s' % msg.type
113 |
114 | @itchat.msg_register(TEXT)
115 | def text_reply(msg):
116 | return 'You said to me one to one: %s' % msg.text
117 |
118 | itchat.run()
119 | ```
120 |
121 | 仅在私聊发送文本时将会回复`You said to me one to one`，其余情况将会回复`I received a ...`。
122 |
123 | ## 动态注册消息
124 |
125 | 动态注册时可以选择将`itchat.run()`放入另一线程或使用`configured_reply()`方法处理消息。
126 |
127 | 两种方法分别是：
128 |
129 | ```python
130 | # 使用另一线程，但注意不要让程序运行终止
131 | import thread
132 |
133 | thread.start_new_thread(itchat.run, ())
134 |
135 | # 使用configured_reply方法
136 | while 1:
137 | itchat.configured_reply()
138 | # some other functions
139 | time.sleep(1)
140 | ```
141 |
142 | 以下给出一个动态注册的例子：
143 |
144 | ```python
145 | #coding=utf8
146 | import thread
147 |
148 | import itchat
149 | from itchat.content import *
150 |
151 | replyToGroupChat = True
152 | functionStatus = False
153 |
154 | def change_function():
155 | if replyToGroupChat != functionStatus:
156 | if replyToGroupChat:
157 | @itchat.msg_register(TEXT, isGroupChat=True)
158 | def group_text_reply(msg):
159 | if u'关闭' in msg['Text']:
160 | replyToGroupChat = False
161 | return u'已关闭'
162 | elif u'开启' in msg['Text']:
163 | return u'已经在运行'
164 | return u'输入"关闭"或者"开启"测试功能'
165 | else:
166 | @itchat.msg_register(TEXT, isGroupChat=True)
167 | def group_text_reply(msg):
168 | if u'开启' in msg['Text']:
169 | replyToGroupChat = True
170 | return u'重新开启成功'
171 | functionStatus = replyToGroupChat
172 |
173 | thread.start_new_thread(itchat.run, ())
174 |
175 | while 1:
176 | change_function()
177 | time.sleep(.1)
178 | ```
179 |
--------------------------------------------------------------------------------
/itchat/components/hotreload.py:
--------------------------------------------------------------------------------
1 | import pickle, os
2 | import logging
3 |
4 | import requests
5 |
6 | from ..config import VERSION
7 | from ..returnvalues import ReturnValue
8 | from ..storage import templates
9 | from .contact import update_local_chatrooms, update_local_friends
10 | from .messages import produce_msg
11 |
12 | logger = logging.getLogger('itchat')
13 |
14 | def load_hotreload(core):
15 | core.dump_login_status = dump_login_status
16 | core.load_login_status = load_login_status
17 |
18 | def dump_login_status(self, fileDir=None):
19 | fileDir = fileDir or self.hotReloadDir
20 | try:
21 | with open(fileDir, 'w') as f:
22 | f.write('itchat - DELETE THIS')
23 | os.remove(fileDir)
24 | except:
25 | raise Exception('Incorrect fileDir')
26 | status = {
27 | 'version' : VERSION,
28 | 'loginInfo' : self.loginInfo,
29 | 'cookies' : self.s.cookies.get_dict(),
30 | 'storage' : self.storageClass.dumps()}
31 | with open(fileDir, 'wb') as f:
32 | pickle.dump(status, f)
33 | logger.debug('Dump login status for hot reload successfully.')
34 |
35 | def load_login_status(self, fileDir,
36 | loginCallback=None, exitCallback=None):
37 | try:
38 | with open(fileDir, 'rb') as f:
39 | j = pickle.load(f)
40 | except Exception as e:
41 | logger.debug('No such file, loading login status failed.')
42 | return ReturnValue({'BaseResponse': {
43 | 'ErrMsg': 'No such file, loading login status failed.',
44 | 'Ret': -1002, }})
45 |
46 | if j.get('version', '') != VERSION:
47 | logger.debug(('you have updated itchat from %s to %s, ' +
48 | 'so cached status is ignored') % (
49 | j.get('version', 'old version'), VERSION))
50 | return ReturnValue({'BaseResponse': {
51 | 'ErrMsg': 'cached status ignored because of version',
52 | 'Ret': -1005, }})
53 | self.loginInfo = j['loginInfo']
54 | self.loginInfo['User'] = templates.User(self.loginInfo['User'])
55 | self.loginInfo['User'].core = self
56 | self.s.cookies = requests.utils.cookiejar_from_dict(j['cookies'])
57 | self.storageClass.loads(j['storage'])
58 | try:
59 | msgList, contactList = self.get_msg()
60 | except:
61 | msgList = contactList = None
62 | if (msgList or contactList) is None:
63 | self.logout()
64 | load_last_login_status(self.s, j['cookies'])
65 | logger.debug('server refused, loading login status failed.')
66 | return ReturnValue({'BaseResponse': {
67 | 'ErrMsg': 'server refused, loading login status failed.',
68 | 'Ret': -1003, }})
69 | else:
70 | if contactList:
71 | for contact in contactList:
72 | if '@@' in contact['UserName']:
73 | update_local_chatrooms(self, [contact])
74 | else:
75 | update_local_friends(self, [contact])
76 | if msgList:
77 | msgList = produce_msg(self, msgList)
78 | for msg in msgList: self.msgList.put(msg)
79 | self.start_receiving(exitCallback)
80 | logger.debug('loading login status succeeded.')
81 | if hasattr(loginCallback, '__call__'):
82 | loginCallback()
83 | return ReturnValue({'BaseResponse': {
84 | 'ErrMsg': 'loading login status succeeded.',
85 | 'Ret': 0, }})
86 |
87 | def load_last_login_status(session, cookiesDict):
88 | try:
89 | session.cookies = requests.utils.cookiejar_from_dict({
90 | 'webwxuvid': cookiesDict['webwxuvid'],
91 | 'webwx_auth_ticket': cookiesDict['webwx_auth_ticket'],
92 | 'login_frequency': '2',
93 | 'last_wxuin': cookiesDict['wxuin'],
94 | 'wxloadtime': cookiesDict['wxloadtime'] + '_expired',
95 | 'wxpluginkey': cookiesDict['wxloadtime'],
96 | 'wxuin': cookiesDict['wxuin'],
97 | 'mm_lang': 'zh_CN',
98 | 'MM_WX_NOTIFY_STATE': '1',
99 | 'MM_WX_SOUND_STATE': '1', })
100 | except:
101 | logger.info('Load status for push login failed, we may have experienced a cookies change.')
102 | logger.info('If you are using the newest version of itchat, you may report a bug.')
103 |
--------------------------------------------------------------------------------
/docs/intro/login.md:
--------------------------------------------------------------------------------
1 | # 登陆
2 |
3 | 在上一章中你看到了基本的注册与登陆，而显然登陆使用的是itchat提供了`auto_login`方法，调用即可完成登录。
4 |
5 | 一般而言，我们都会在完成消息的注册后登陆。
6 |
7 | 当然这里需要特别强调的是三点，分别是短时间关闭重连、命令行二维码与自定义登陆内容。
8 |
9 | * itchat提供了登陆状态暂存，关闭程序后一定时间内不需要扫码即可登录。
10 | * 由于目前微信网页版提供上一次登录的微信号不扫码直接手机确认登陆，所以如果开启登陆状态暂存将会自动使用这一功能。
11 | * 为了方便在无图形界面使用itchat，程序内置了命令行二维码的显示。
12 | * 如果你需要就登录状态就一些修改（例如更改提示语、二维码出现后邮件发送等）。
13 |
14 | ## 短时间关闭程序后重连
15 |
16 | 这样即使程序关闭，一定时间内重新开启也可以不用重新扫码。
17 |
18 | 最简单的用法就是给`auto_login`方法传入值为真的hotReload。
19 |
20 | 该方法会生成一个静态文件`itchat.pkl`，用于存储登陆的状态。
21 |
22 | ```python
23 | import itchat
24 | from itchat.content import TEXT
25 |
26 | @itchat.msg_register(TEXT)
27 | def simple_reply(msg):
28 | print(msg.text)
29 |
30 | itchat.auto_login(hotReload=True)
31 | itchat.run()
32 | ```
33 |
34 | 通过设置statusStorageDir可以将静态文件指定为其他的值。
35 |
36 | 这一内置选项其实就相当于使用了以下两个函数的这一段程序：
37 |
38 | ```python
39 | import itchat
40 | from itchat.content import TEXT
41 |
42 | if itchat.load_login_status():
43 | @itchat.msg_register(TEXT)
44 | def simple_reply(msg):
45 | print(msg['Text'])
46 | itchat.run()
47 | itchat.dump_login_status()
48 | else:
49 | itchat.auto_login()
50 | itchat.dump_login_status()
51 | print('Config stored, so exit.')
52 | ```
53 |
54 | 其中load_login_status与dump_login_status分别对应读取与导出设置。
55 |
56 | 通过设置传入的fileDir的值可以设定导入导出的文件。
57 |
58 | ## 命令行二维码显示
59 |
60 | 通过以下命令可以在登陆的时候使用命令行显示二维码：
61 |
62 | ```python
63 | itchat.auto_login(enableCmdQR=True)
64 | ```
65 |
66 | 部分系统可能字幅宽度有出入，可以通过将enableCmdQR赋值为特定的倍数进行调整：
67 |
68 | ```python
69 | # 如部分的linux系统，块字符的宽度为一个字符（正常应为两字符），故赋值为2
70 | itchat.auto_login(enableCmdQR=2)
71 | ```
72 |
73 | 默认控制台背景色为暗色（黑色），若背景色为浅色（白色），可以将enableCmdQR赋值为负值：
74 |
75 | ```python
76 | itchat.auto_login(enableCmdQR=-1)
77 | ```
78 |
79 | ## 自定义登录过程
80 |
81 | 如果需要控制登录的过程，可以阅读下面的内容。
82 |
83 | 同时itchat也提供了登陆所需的每一步的方法，登陆的过程按顺序为：
84 |
85 | * 获取二维码uuid
86 | * 获取二维码
87 | * 判断是否已经登陆成功
88 | * 获取初始化数据
89 | * 更新微信相关信息（通讯录、手机登陆状态）
90 | * 循环扫描新信息（开启心跳）
91 |
92 | ### 获取二维码uuid
93 |
94 | 获取生成二维码所需的uuid，并返回。
95 |
96 | * 方法名称：`get_QRuuid`
97 | * 所需值：无
98 | * 返回值：成功->uuid，失败->None
99 |
100 | ### 获取二维码
101 |
102 | 根据uuid获取二维码并打开，返回是否成功。
103 |
104 | * 方法名称：`get_QR`
105 | * 所需值：uuid
106 | * 返回值：成功->True，失败->False
107 |
108 | ### 判断是否已经登陆成功
109 |
110 | 判断是否已经登陆成功，返回扫描的状态码。
111 |
112 | * 方法名称：`check_login`
113 | * 所需值：uuid
114 | * 返回值：登陆成功->'200'，已扫描二维码->'201'，二维码失效->'408'，未获取到信息->'0'
115 |
116 | ### 获取初始化数据
117 |
118 | 获取微信用户信息以及心跳所需要的数据。
119 |
120 | * 方法名称：`web_init`
121 | * 所需值：无
122 | * 返回值：存储登录微信用户信息的字典
123 |
124 | ### 获取微信通讯录
125 |
126 | 获取微信的所有好友信息并更新。
127 |
128 | * 方法名称：`get_friends`（曾用名：`get_contact`）
129 | * 所需值：无
130 | * 返回值：存储好友信息的列表
131 |
132 | ### 更新微信手机登陆状态
133 |
134 | 在手机上显示登录状态。
135 |
136 | * 方法名称：`show_mobile_login`
137 | * 所需值：无
138 | * 返回值：无
139 |
140 | ### 循环扫描新信息（开启心跳）
141 |
142 | 循环扫描是否有新的消息，开启心跳包。
143 |
144 | * 方法名称：`start_receiving`
145 | * 所需值：无
146 | * 返回值：无
147 |
148 | ## 示例
149 |
150 | itchat自带的`auto_login`通过如下代码可以实现：
151 |
152 | ```python
153 | import itchat, time, sys
154 |
155 | def output_info(msg):
156 | print('[INFO] %s' % msg)
157 |
158 | def open_QR():
159 | for get_count in range(10):
160 | output_info('Getting uuid')
161 | uuid = itchat.get_QRuuid()
162 | while uuid is None: uuid = itchat.get_QRuuid();time.sleep(1)
163 | output_info('Getting QR Code')
164 | if itchat.get_QR(uuid): break
165 | elif get_count >= 9:
166 | output_info('Failed to get QR Code, please restart the program')
167 | sys.exit()
168 | output_info('Please scan the QR Code')
169 | return uuid
170 |
171 | uuid = open_QR()
172 | waitForConfirm = False
173 | while 1:
174 | status = itchat.check_login(uuid)
175 | if status == '200':
176 | break
177 | elif status == '201':
178 | if waitForConfirm:
179 | output_info('Please press confirm')
180 | waitForConfirm = True
181 | elif status == '408':
182 | output_info('Reloading QR Code')
183 | uuid = open_QR()
184 | waitForConfirm = False
185 | userInfo = itchat.web_init()
186 | itchat.show_mobile_login()
187 | itchat.get_friends(True)
188 | output_info('Login successfully as %s'%userInfo['NickName'])
189 | itchat.start_receiving()
190 |
191 | # Start auto-replying
192 | @itchat.msg_register
193 | def simple_reply(msg):
194 | if msg['Type'] == 'Text':
195 | return 'I received: %s' % msg['Content']
196 | itchat.run()
197 | ```
198 |
--------------------------------------------------------------------------------
/itchat/components/register.py:
--------------------------------------------------------------------------------
1 | import logging, traceback, sys, threading
2 | try:
3 | import Queue
4 | except ImportError:
5 | import queue as Queue
6 |
7 | from ..log import set_logging
8 | from ..utils import test_connect
9 | from ..storage import templates
10 |
11 | logger = logging.getLogger('itchat')
12 |
13 | def load_register(core):
14 | core.auto_login = auto_login
15 | core.configured_reply = configured_reply
16 | core.msg_register = msg_register
17 | core.run = run
18 |
19 | def auto_login(self, hotReload=False, statusStorageDir='itchat.pkl',
20 | enableCmdQR=False, picDir=None, qrCallback=None,
21 | loginCallback=None, exitCallback=None):
22 | if not test_connect():
23 | logger.info("You can't get access to internet or wechat domain, so exit.")
24 | sys.exit()
25 | self.useHotReload = hotReload
26 | self.hotReloadDir = statusStorageDir
27 | if hotReload:
28 | if self.load_login_status(statusStorageDir,
29 | loginCallback=loginCallback, exitCallback=exitCallback):
30 | return
31 | self.login(enableCmdQR=enableCmdQR, picDir=picDir, qrCallback=qrCallback,
32 | loginCallback=loginCallback, exitCallback=exitCallback)
33 | self.dump_login_status(statusStorageDir)
34 | else:
35 | self.login(enableCmdQR=enableCmdQR, picDir=picDir, qrCallback=qrCallback,
36 | loginCallback=loginCallback, exitCallback=exitCallback)
37 |
38 | def configured_reply(self):
39 | ''' determine the type of message and reply if its method is defined
40 | however, I use a strange way to determine whether a msg is from massive platform
41 | I haven't found a better solution here
42 | The main problem I'm worrying about is the mismatching of new friends added on phone
43 | If you have any good idea, pleeeease report an issue. I will be more than grateful.
44 | '''
45 | try:
46 | msg = self.msgList.get(timeout=1)
47 | except Queue.Empty:
48 | pass
49 | else:
50 | if isinstance(msg['User'], templates.User):
51 | replyFn = self.functionDict['FriendChat'].get(msg['Type'])
52 | elif isinstance(msg['User'], templates.MassivePlatform):
53 | replyFn = self.functionDict['MpChat'].get(msg['Type'])
54 | elif isinstance(msg['User'], templates.Chatroom):
55 | replyFn = self.functionDict['GroupChat'].get(msg['Type'])
56 | if replyFn is None:
57 | r = None
58 | else:
59 | try:
60 | r = replyFn(msg)
61 | if r is not None:
62 | self.send(r, msg.get('FromUserName'))
63 | except:
64 | logger.warning(traceback.format_exc())
65 |
66 | def msg_register(self, msgType, isFriendChat=False, isGroupChat=False, isMpChat=False):
67 | ''' a decorator constructor
68 | return a specific decorator based on information given '''
69 | if not (isinstance(msgType, list) or isinstance(msgType, tuple)):
70 | msgType = [msgType]
71 | def _msg_register(fn):
72 | for _msgType in msgType:
73 | if isFriendChat:
74 | self.functionDict['FriendChat'][_msgType] = fn
75 | if isGroupChat:
76 | self.functionDict['GroupChat'][_msgType] = fn
77 | if isMpChat:
78 | self.functionDict['MpChat'][_msgType] = fn
79 | if not any((isFriendChat, isGroupChat, isMpChat)):
80 | self.functionDict['FriendChat'][_msgType] = fn
81 | return fn
82 | return _msg_register
83 |
84 | def run(self, debug=False, blockThread=True):
85 | logger.info('Start auto replying.')
86 | if debug:
87 | set_logging(loggingLevel=logging.DEBUG)
88 | def reply_fn():
89 | try:
90 | while self.alive:
91 | self.configured_reply()
92 | except KeyboardInterrupt:
93 | if self.useHotReload:
94 | self.dump_login_status()
95 | self.alive = False
96 | logger.debug('itchat received an ^C and exit.')
97 | logger.info('Bye~')
98 | if blockThread:
99 | reply_fn()
100 | else:
101 | replyThread = threading.Thread(target=reply_fn)
102 | replyThread.setDaemon(True)
103 | replyThread.start()
104 |
--------------------------------------------------------------------------------
/docs/intro/contact.md:
--------------------------------------------------------------------------------
1 | 在使用个人微信的过程当中主要有三种账号需要获取，分别为：
2 |
3 | * 好友
4 | * 公众号
5 | * 群聊
6 |
7 | itchat为这三种账号都提供了整体获取方法与搜索方法。
8 |
9 | 而群聊多出获取用户列表方法以及创建群聊、增加、删除用户的方法。
10 |
11 | 这里我们分这三种分别介绍如何使用。
12 |
13 | 在本章的最后还介绍了如何通过Uin唯一的确定好友与群聊。
14 |
15 | ## 好友
16 |
17 | 好友的获取方法为`get_friends`，将会返回完整的好友列表。
18 |
19 | * 其中每个好友为一个字典
20 | * 列表的第一项为本人的账号信息
21 | * 传入update键为True将可以更新好友列表并返回
22 |
23 | 好友的搜索方法为`search_friends`，有四种搜索方式：
24 | 1. 仅获取自己的用户信息
25 | 2. 获取特定`UserName`的用户信息
26 | 3. 获取备注、微信号、昵称中的任何一项等于`name`键值的用户
27 | 4. 获取备注、微信号、昵称分别等于相应键值的用户
28 |
29 | 其中三、四项可以一同使用，下面是示例程序：
30 |
31 | ```python
32 | # 获取自己的用户信息，返回自己的属性字典
33 | itchat.search_friends()
34 | # 获取特定UserName的用户信息
35 | itchat.search_friends(userName='@abcdefg1234567')
36 | # 获取任何一项等于name键值的用户
37 | itchat.search_friends(name='littlecodersh')
38 | # 获取分别对应相应键值的用户
39 | itchat.search_friends(wechatAccount='littlecodersh')
40 | # 三、四项功能可以一同使用
41 | itchat.search_friends(name='LittleCoder机器人', wechatAccount='littlecodersh')
42 | ```
43 |
44 | 更新用户信息的方法为`update_friend`。
45 |
46 | * 该方法需要传入用户的`UserName`，返回指定用户的最新信息
47 | * 同样也可以传入`UserName`组成的列表，那么相应的也会返回指定用户的最新信息组成的列表
48 |
49 | ```python
50 | memberList = itchat.update_friend('@abcdefg1234567')
51 | ```
52 |
53 | ## 公众号
54 |
55 | 公众号的获取方法为`get_mps`，将会返回完整的公众号列表。
56 |
57 | * 其中每个公众号为一个字典
58 | * 传入update键为True将可以更新公众号列表并返回
59 |
60 | 公众号的搜索方法为`search_mps`，有两种搜索方法：
61 | 1. 获取特定`UserName`的公众号
62 | 2. 获取名字中含有特定字符的公众号
63 |
64 | 如果两项都做了特定，将会仅返回特定`UserName`的公众号，下面是示例程序：
65 |
66 | ```python
67 | # 获取特定UserName的公众号，返回值为一个字典
68 | itchat.search_mps(userName='@abcdefg1234567')
69 | # 获取名字中含有特定字符的公众号，返回值为一个字典的列表
70 | itchat.search_mps(name='LittleCoder')
71 | # 以下方法相当于仅特定了UserName
72 | itchat.search_mps(userName='@abcdefg1234567', name='LittleCoder')
73 | ```
74 |
75 | ## 群聊
76 |
77 | 群聊的获取方法为`get_chatrooms`，将会返回完整的群聊列表。
78 |
79 | * 其中每个群聊为一个字典
80 | * 传入update键为True将可以更新群聊列表并返回通讯录中保存的群聊列表
81 | * 群聊列表为后台自动更新，如果中途意外退出存在极小的概率产生本地群聊消息与后台不同步
82 | * 为了保证群聊信息在热启动中可以被正确的加载，即使不需要持续在线的程序也需要运行`itchat.run()`
83 | * 如果不想要运行上述命令，请在退出程序前调用`itchat.dump_login_status()`，更新热拔插需要的信息
84 |
85 | 群聊的搜索方法为`search_chatrooms`，有两种搜索方法：
86 | 1. 获取特定`UserName`的群聊
87 | 2. 获取名字中含有特定字符的群聊
88 |
89 | 如果两项都做了特定，将会仅返回特定`UserName`的群聊，下面是示例程序：
90 |
91 | ```python
92 | # 获取特定UserName的群聊，返回值为一个字典
93 | itchat.search_chatrooms(userName='@@abcdefg1234567')
94 | # 获取名字中含有特定字符的群聊，返回值为一个字典的列表
95 | itchat.search_chatrooms(name='LittleCoder')
96 | # 以下方法相当于仅特定了UserName
97 | itchat.search_chatrooms(userName='@@abcdefg1234567', name='LittleCoder')
98 | ```
99 |
100 | 群聊用户列表的获取方法为`update_chatroom`。
101 |
102 | * 同样，如果想要更新该群聊的其他信息也可以用该方法
103 | * 群聊在首次获取中不会获取群聊的用户列表，所以需要调用该命令才能获取群聊的成员
104 | * 该方法需要传入群聊的`UserName`，返回特定群聊的详细信息
105 | * 同样也可以传入`UserName`组成的列表，那么相应的也会返回指定用户的最新信息组成的列表
106 |
107 | ```python
108 | memberList = itchat.update_chatroom('@@abcdefg1234567', detailedMember=True)
109 | ```
110 |
111 | 创建群聊、增加、删除群聊用户的方法如下所示：
112 |
113 | * 由于之前通过群聊检测是否被好友拉黑的程序，目前这三个方法都被严格限制了使用频率
114 | * 删除群聊需要本账号为群管理员，否则会失败
115 | * 将用户加入群聊有直接加入与发送邀请，通过`useInvitation`设置
116 | * 超过40人的群聊无法使用直接加入的加入方式，特别注意
117 |
118 | ```python
119 | memberList = itchat.get_friends()[1:]
120 | # 创建群聊，topic键值为群聊名
121 | chatroomUserName = itchat.create_chatroom(memberList, 'test chatroom')
122 | # 删除群聊内的用户
123 | itchat.delete_member_from_chatroom(chatroomUserName, memberList[0])
124 | # 增加用户进入群聊
125 | itchat.add_member_into_chatroom(chatroomUserName, memberList[0], useInvitation=False)
126 | ```
127 |
128 | ## Uins
129 |
130 | Uin 就是微信中用于标识用户的方式，每一个用户、群聊都有唯一且不同的Uin。
131 |
132 | 那么通过Uin，即使退出了重新登录，也可以轻松的确认正在对话的是上一次登陆的哪一个用户。
133 |
134 | 但注意，Uin与其他值不同，微信后台做了一定的限制，必须通过特殊的操作才能获取。
135 |
136 | 最简单来说，首次点开登陆用的手机端的某个好友或者群聊，itchat就能获取到该好友或者群聊的Uin。
137 |
138 | 如果想要通过程序获取，也可以用程序将某个好友或者群聊置顶（取消置顶）。
139 |
140 | 这里提供一个提示群聊更新的程序：
141 |
142 | ```python
143 | import re, sys, json
144 |
145 | import itchat
146 | from itchat.content import *
147 |
148 | itchat.auto_login(True)
149 |
150 | @itchat.msg_register(SYSTEM)
151 | def get_uin(msg):
152 | if msg['SystemInfo'] != 'uins': return
153 | ins = itchat.instanceList[0]
154 | fullContact = ins.memberList + ins.chatroomList + ins.mpList
155 | print('** Uin Updated **')
156 | for username in msg['Text']:
157 | member = itchat.utils.search_dict_list(
158 | fullContact, 'UserName', username)
159 | print(('%s: %s' % (
160 | member.get('NickName', ''), member['Uin']))
161 | .encode(sys.stdin.encoding, 'replace'))
162 |
163 | itchat.run(True)
164 | ```
165 |
166 | 每当Uin更新了，就会打印相应的更新情况。
167 |
168 | 同样的，如果你想要获取Uin更新的情况也通过获取SYSTEM类型消息实现。
169 |
--------------------------------------------------------------------------------
/itchat/storage/__init__.py:
--------------------------------------------------------------------------------
1 | import os, time, copy
2 | from threading import Lock
3 |
4 | from .messagequeue import Queue
5 | from .templates import (
6 | ContactList, AbstractUserDict, User,
7 | MassivePlatform, Chatroom, ChatroomMember)
8 |
9 | def contact_change(fn):
10 | def _contact_change(core, *args, **kwargs):
11 | with core.storageClass.updateLock:
12 | return fn(core, *args, **kwargs)
13 | return _contact_change
14 |
15 | class Storage(object):
16 | def __init__(self, core):
17 | self.userName = None
18 | self.nickName = None
19 | self.updateLock = Lock()
20 | self.memberList = ContactList()
21 | self.mpList = ContactList()
22 | self.chatroomList = ContactList()
23 | self.msgList = Queue(-1)
24 | self.lastInputUserName = None
25 | self.memberList.set_default_value(contactClass=User)
26 | self.memberList.core = core
27 | self.mpList.set_default_value(contactClass=MassivePlatform)
28 | self.mpList.core = core
29 | self.chatroomList.set_default_value(contactClass=Chatroom)
30 | self.chatroomList.core = core
31 | def dumps(self):
32 | return {
33 | 'userName' : self.userName,
34 | 'nickName' : self.nickName,
35 | 'memberList' : self.memberList,
36 | 'mpList' : self.mpList,
37 | 'chatroomList' : self.chatroomList,
38 | 'lastInputUserName' : self.lastInputUserName, }
39 | def loads(self, j):
40 | self.userName = j.get('userName', None)
41 | self.nickName = j.get('nickName', None)
42 | del self.memberList[:]
43 | for i in j.get('memberList', []):
44 | self.memberList.append(i)
45 | del self.mpList[:]
46 | for i in j.get('mpList', []):
47 | self.mpList.append(i)
48 | del self.chatroomList[:]
49 | for i in j.get('chatroomList', []):
50 | self.chatroomList.append(i)
51 | # I tried to solve everything in pickle
52 | # but this way is easier and more storage-saving
53 | for chatroom in self.chatroomList:
54 | if 'MemberList' in chatroom:
55 | for member in chatroom['MemberList']:
56 | member.core = chatroom.core
57 | member.chatroom = chatroom
58 | if 'Self' in chatroom:
59 | chatroom['Self'].core = chatroom.core
60 | chatroom['Self'].chatroom = chatroom
61 | self.lastInputUserName = j.get('lastInputUserName', None)
62 | def search_friends(self, name=None, userName=None, remarkName=None, nickName=None,
63 | wechatAccount=None):
64 | with self.updateLock:
65 | if (name or userName or remarkName or nickName or wechatAccount) is None:
66 | return copy.deepcopy(self.memberList[0]) # my own account
67 | elif userName: # return the only userName match
68 | for m in self.memberList:
69 | if m['UserName'] == userName:
70 | return copy.deepcopy(m)
71 | else:
72 | matchDict = {
73 | 'RemarkName' : remarkName,
74 | 'NickName' : nickName,
75 | 'Alias' : wechatAccount, }
76 | for k in ('RemarkName', 'NickName', 'Alias'):
77 | if matchDict[k] is None:
78 | del matchDict[k]
79 | if name: # select based on name
80 | contact = []
81 | for m in self.memberList:
82 | if any([m.get(k) == name for k in ('RemarkName', 'NickName', 'Alias')]):
83 | contact.append(m)
84 | else:
85 | contact = self.memberList[:]
86 | if matchDict: # select again based on matchDict
87 | friendList = []
88 | for m in contact:
89 | if all([m.get(k) == v for k, v in matchDict.items()]):
90 | friendList.append(m)
91 | return copy.deepcopy(friendList)
92 | else:
93 | return copy.deepcopy(contact)
94 | def search_chatrooms(self, name=None, userName=None):
95 | with self.updateLock:
96 | if userName is not None:
97 | for m in self.chatroomList:
98 | if m['UserName'] == userName:
99 | return copy.deepcopy(m)
100 | elif name is not None:
101 | matchList = []
102 | for m in self.chatroomList:
103 | if name in m['NickName']:
104 | matchList.append(copy.deepcopy(m))
105 | return matchList
106 | def search_mps(self, name=None, userName=None):
107 | with self.updateLock:
108 | if userName is not None:
109 | for m in self.mpList:
110 | if m['UserName'] == userName:
111 | return copy.deepcopy(m)
112 | elif name is not None:
113 | matchList = []
114 | for m in self.mpList:
115 | if name in m['NickName']:
116 | matchList.append(copy.deepcopy(m))
117 | return matchList
118 |
--------------------------------------------------------------------------------
/itchat/utils.py:
--------------------------------------------------------------------------------
1 | import re, os, sys, subprocess, copy, traceback, logging
2 |
3 | try:
4 | from HTMLParser import HTMLParser
5 | except ImportError:
6 | from html.parser import HTMLParser
7 | try:
8 | from urllib import quote as _quote
9 | quote = lambda n: _quote(n.encode('utf8', 'replace'))
10 | except ImportError:
11 | from urllib.parse import quote
12 |
13 | import requests
14 |
15 | from . import config
16 |
17 | logger = logging.getLogger('itchat')
18 |
19 | emojiRegex = re.compile(r'')
20 | htmlParser = HTMLParser()
21 | try:
22 | b = u'\u2588'
23 | sys.stdout.write(b + '\r')
24 | sys.stdout.flush()
25 | except UnicodeEncodeError:
26 | BLOCK = 'MM'
27 | else:
28 | BLOCK = b
29 | friendInfoTemplate = {}
30 | for k in ('UserName', 'City', 'DisplayName', 'PYQuanPin', 'RemarkPYInitial', 'Province',
31 | 'KeyWord', 'RemarkName', 'PYInitial', 'EncryChatRoomId', 'Alias', 'Signature',
32 | 'NickName', 'RemarkPYQuanPin', 'HeadImgUrl'):
33 | friendInfoTemplate[k] = ''
34 | for k in ('UniFriend', 'Sex', 'AppAccountFlag', 'VerifyFlag', 'ChatRoomId', 'HideInputBarFlag',
35 | 'AttrStatus', 'SnsFlag', 'MemberCount', 'OwnerUin', 'ContactFlag', 'Uin',
36 | 'StarFriend', 'Statues'):
37 | friendInfoTemplate[k] = 0
38 | friendInfoTemplate['MemberList'] = []
39 |
40 | def clear_screen():
41 | os.system('cls' if config.OS == 'Windows' else 'clear')
42 |
43 | def emoji_formatter(d, k):
44 | ''' _emoji_deebugger is for bugs about emoji match caused by wechat backstage
45 | like :face with tears of joy: will be replaced with :cat face with tears of joy:
46 | '''
47 | def _emoji_debugger(d, k):
48 | s = d[k].replace('') # fix missing bug
50 | def __fix_miss_match(m):
51 | return '' % ({
52 | '1f63c': '1f601', '1f639': '1f602', '1f63a': '1f603',
53 | '1f4ab': '1f616', '1f64d': '1f614', '1f63b': '1f60d',
54 | '1f63d': '1f618', '1f64e': '1f621', '1f63f': '1f622',
55 | }.get(m.group(1), m.group(1)))
56 | return emojiRegex.sub(__fix_miss_match, s)
57 | def _emoji_formatter(m):
58 | s = m.group(1)
59 | if len(s) == 6:
60 | return ('\\U%s\\U%s'%(s[:2].rjust(8, '0'), s[2:].rjust(8, '0'))
61 | ).encode('utf8').decode('unicode-escape', 'replace')
62 | elif len(s) == 10:
63 | return ('\\U%s\\U%s'%(s[:5].rjust(8, '0'), s[5:].rjust(8, '0'))
64 | ).encode('utf8').decode('unicode-escape', 'replace')
65 | else:
66 | return ('\\U%s'%m.group(1).rjust(8, '0')
67 | ).encode('utf8').decode('unicode-escape', 'replace')
68 | d[k] = _emoji_debugger(d, k)
69 | d[k] = emojiRegex.sub(_emoji_formatter, d[k])
70 |
71 | def msg_formatter(d, k):
72 | emoji_formatter(d, k)
73 | d[k] = d[k].replace('{% include "toc.html" %}
64 | {% include "content.html" %}
65 | {%- endblock %}
66 | ', '\n') 74 | d[k] = htmlParser.unescape(d[k]) 75 | 76 | def check_file(fileDir): 77 | try: 78 | with open(fileDir): 79 | pass 80 | return True 81 | except: 82 | return False 83 | 84 | def print_qr(fileDir): 85 | if config.OS == 'Darwin': 86 | subprocess.call(['open', fileDir]) 87 | elif config.OS == 'Linux': 88 | subprocess.call(['xdg-open', fileDir]) 89 | else: 90 | os.startfile(fileDir) 91 | 92 | def print_cmd_qr(qrText, white=BLOCK, black=' ', enableCmdQR=True): 93 | blockCount = int(enableCmdQR) 94 | if abs(blockCount) == 0: 95 | blockCount = 1 96 | white *= abs(blockCount) 97 | if blockCount < 0: 98 | white, black = black, white 99 | sys.stdout.write(' '*50 + '\r') 100 | sys.stdout.flush() 101 | qr = qrText.replace('0', white).replace('1', black) 102 | sys.stdout.write(qr) 103 | sys.stdout.flush() 104 | 105 | def struct_friend_info(knownInfo): 106 | member = copy.deepcopy(friendInfoTemplate) 107 | for k, v in copy.deepcopy(knownInfo).items(): member[k] = v 108 | return member 109 | 110 | def search_dict_list(l, key, value): 111 | ''' Search a list of dict 112 | * return dict with specific value & key ''' 113 | for i in l: 114 | if i.get(key) == value: 115 | return i 116 | 117 | def print_line(msg, oneLine = False): 118 | if oneLine: 119 | sys.stdout.write(' '*40 + '\r') 120 | sys.stdout.flush() 121 | else: 122 | sys.stdout.write('\n') 123 | sys.stdout.write(msg.encode(sys.stdin.encoding or 'utf8', 'replace' 124 | ).decode(sys.stdin.encoding or 'utf8', 'replace')) 125 | sys.stdout.flush() 126 | 127 | def test_connect(retryTime=5): 128 | for i in range(retryTime): 129 | try: 130 | r = requests.get(config.BASE_URL) 131 | return True 132 | except: 133 | if i == retryTime - 1: 134 | logger.error(traceback.format_exc()) 135 | return False 136 | 137 | def contact_deep_copy(core, contact): 138 | with core.storageClass.updateLock: 139 | return copy.deepcopy(contact) 140 | 141 | def get_image_postfix(data): 142 | data = data[:20] 143 | if b'GIF' in data: 144 | return 'gif' 145 | elif b'PNG' in data: 146 | return 'png' 147 | elif b'JFIF' in data: 148 | return 'jpg' 149 | return '' 150 | 151 | def update_info_dict(oldInfoDict, newInfoDict): 152 | ''' only normal values will be updated here 153 | because newInfoDict is normal dict, so it's not necessary to consider templates 154 | ''' 155 | for k, v in newInfoDict.items(): 156 | if any((isinstance(v, t) for t in (tuple, list, dict))): 157 | pass # these values will be updated somewhere else 158 | elif oldInfoDict.get(k) is None or v not in (None, '', '0', 0): 159 | oldInfoDict[k] = v 160 | -------------------------------------------------------------------------------- /docs/tutorial/tutorial0.md: -------------------------------------------------------------------------------- 1 | ## 一、课程介绍 2 | 3 | 本文最佳阅读方式为[实验楼的会员课程][vip]，建议点击链接在实验楼内阅读。 4 | 5 | ### 1. 课程来源 6 | 7 | 关于itchat进一步使用的问题你可以在[主页][itchat]加入官方交流群也可以在课程下面向我提问。 8 | 9 | 课程在常见的三种系统中都可以进行操作，itchat建议使用可以安装的最新版本。 10 | 11 | 本课程通过聊天机器人为例，介绍如何使用Python完成微信的点对点信息交互。 12 | 13 | ### 2. 内容简介 14 | 15 | * 课程实现微信个人号聊天机器人 16 | * 通过自定义消息处理方法加入聊天功能 17 | 18 | ### 3. 课程知识点 19 | 20 | 本课程项目完成过程中将学习： 21 | 22 | * 微信消息的基本获取与处理 23 | * 微信消息的指定发送 24 | 25 | 其中将重点介绍微信消息的获取与处理。 26 | 27 | ## 二、实验环境 28 | 29 | 在终端中输入以下命令，完成微信的API包itchat的安装。 30 | 31 | 我们这里使用python3的环境（python2也是可行的）： 32 | 33 | ```bash 34 | sudo pip3 install itchat --upgrade 35 | ``` 36 | 37 | 通过该命令判断是否安装成功： 38 | 39 | ```bash 40 | python3 -c "import itchat" 41 | ``` 42 | 43 | 如果没有报错信息说明你已经将实验环境安装完成。 44 | 45 | ![install][install] 46 | 47 | ## 三、实验原理 48 | 49 | 通过微信的Python接口itchat获取微信消息。 50 | 51 | 将微信消息传输到机器人接口（这里以图灵为例），获取机器人的返回消息。 52 | 53 | 将返回消息返回给微信消息的发送人。 54 | 55 | 实现将微信个人号变为聊天机器人的目的。 56 | 57 | ## 四、实验步骤 58 | 59 | ### 0. 基础知识 60 | 61 | 为了照顾一些从未使用过Python的新用户与使用其他语言的用户，这里简单的讲一下以下的代码如何使用。 62 | 63 | 下面的每一段描述都给出了相应的测试代码，如果没有特殊说明这段代码可以这样使用： 64 | 65 | 打开桌面的Xfce终端，先将目录通过以下命令切到桌面。 66 | 67 | ```bash 68 | cd Desktop 69 | ``` 70 | 71 | 之后使用gedit编辑器编辑我们的主程序。 72 | 73 | 你也完全可以使用vim，会使用vim的话想必也知道这里应该输入什么命令了。 74 | 75 | ```bash 76 | gedit test.py 77 | ``` 78 | 79 | 最后将给出的代码复制进编辑器，保存并退出，使用如下命令就可以使用了。 80 | 81 | ```bash 82 | python3 test.py 83 | ``` 84 | 85 | 那么，就让我们开始正式进入Python操作微信的探索之旅吧。 86 | 87 | ### 1. 实现微信消息的获取 88 | 89 | itchat的注册时根据类型注册的。 90 | 91 | 在获取相应类型的信息时会调用该函数。 92 | 93 | 我们现在只需要获取最简单的文本消息，那么只需要这样注册： 94 | 95 | ```python 96 | import itchat 97 | 98 | @itchat.msg_register(itchat.content.TEXT) 99 | def print_content(msg): 100 | print(msg['Text']) 101 | 102 | itchat.auto_login() 103 | itchat.run() 104 | ``` 105 | 106 | 其中第三行即注册的操作，通过装饰符将`print_content`注册为处理文本消息的函数。 107 | 108 | 微信有各种类型的数据，例如图片、语音、名片、分享等，也对应不同的注册参数： 109 | 110 | * 图片对应`itchat.content.PICTURE` 111 | * 语音对应`itchat.content.RECORDING` 112 | * 名片对应`itchat.content.CARD` 113 | * 其余的这里就不一一列举，更具体的内容可以自行搜索itchat阅读[文档][document] 114 | 115 | 执行命令 116 | ``` 117 | python3 test.py 118 | ``` 119 | 120 | 就可看到我们开始登陆微信： 121 | 122 | ![login][login] 123 | 124 | 扫码完成以后最基础的文本信息的接收就完成了，你可以尝试用他人的微信给自己发一条信息。 125 | 126 | 如果你不想要每次运行程序都扫码，可以在登陆命令中进行设置： 127 | 128 | ```python 129 | itchat.auto_login(hotReload=True) 130 | ``` 131 | 132 | ### 2. 实现微信消息的发送 133 | 134 | 微信可以发送各类消息，文本、图片、文件等，不过我们现在只需要使用文本的发送。 135 | 136 | 其余的消息的发送有兴趣可以自行阅读。 137 | 138 | ```python 139 | itchat.send('Message Content', 'toUserName') 140 | ``` 141 | 142 | 该发送消息的函数需要两个参数，消息的内容与接受者的UserName，即标识符。 143 | 144 | 那么我们试着向文件传输助手发送一条消息： 145 | 146 | ```python 147 | #coding=utf8 148 | import itchat 149 | 150 | itchat.auto_login(hotReload=True) 151 | 152 | # 注意实验楼环境的中文输入切换 153 | itchat.send(u'测试消息发送', 'filehelper') 154 | ``` 155 | 156 | 打开手机看一下是否就完成了消息的发送。 157 | 158 | 保存代码后，执行命令： 159 | 160 | ``` 161 | python3 test.py 162 | ``` 163 | 164 | 扫描登录后的效果如下： 165 | 166 | ![send-hello][send-hello] 167 | 168 | 当然，还有一种更加快捷的回复方法就是在注册函数中直接回复。 169 | 170 | 例如下面的例子将会将文本消息原封不动的返回。 171 | 172 | ```python 173 | import itchat 174 | 175 | @itchat.msg_register(itchat.content.TEXT) 176 | def print_content(msg): 177 | return msg['Text'] 178 | 179 | itchat.auto_login() 180 | itchat.run() 181 | ``` 182 | 183 | 这种方式显然更加直观也更加简单（不需要输入接受者的UserName） 184 | 185 | 我们本次实践将会采用这种方式。 186 | 187 | ### 3. 实现最简单的与图灵机器人的交互 188 | 189 | 要做一个能够与人交流的机器人有很多种方法，最简单的莫过于使用他人提供的接口。 190 | 191 | 我们这里以图灵机器人为例，演示这一功能。 192 | 193 | 图灵机器人简单而言就是以一定的规则给图灵的服务器发送数据包（包含你对他说的话） 194 | 195 | 图灵的服务器会以一定的规则给你返回数据包（包含他回复你的话） 196 | 197 | 你需要一个Tuling Key来告诉图灵服务器你有权和他对话，我这里免费提供一些： 198 | 199 | ```bash 200 | 8edce3ce905a4c1dbb965e6b35c3834d 201 | eb720a8970964f3f855d863d24406576 202 | 1107d5601866433dba9599fac1bc0083 203 | 71f28bf79c820df10d39b4074345ef8c 204 | ``` 205 | 206 | 下面我做一个配置图灵机器人的简单介绍，你想要自行了解或者申请Tuling Key可以看[这里][tuling] 207 | 208 | 发送的规则简而言之是这样的： 209 | 210 | ```json 211 | { 212 | 'key' : 'TULING_KEY', 213 | 'info' : 'YOUR_MSG', 214 | 'userid' : 'USERID', 215 | } 216 | ``` 217 | 218 | 其中userId是用户的标志，让机器人知道你是你。（也就是一个Tuling Key可以有多个用户） 219 | 220 | 而返回的内容基本是这样的： 221 | 222 | ```json 223 | { 224 | 'code': 0, 225 | 'text': 'RETURN_MSG', 226 | } 227 | ``` 228 | 229 | 我们需要的内容就在text键里面。 230 | 231 | 这里我们使用requests包完成整个操作（已经包含在itchat包的安装中了）。 232 | 233 | 最后值得一提的就是这是一个post请求，那么直接上代码应该比我絮絮叨叨的说要直观很多。 234 | 235 | ```python 236 | #coding=utf8 237 | import requests 238 | 239 | apiUrl = 'http://www.tuling123.com/openapi/api' 240 | data = { 241 | 'key' : '8edce3ce905a4c1dbb965e6b35c3834d', # 如果这个Tuling Key不能用，那就换一个 242 | 'info' : 'hello', # 这是我们发出去的消息 243 | 'userid' : 'wechat-robot', # 这里你想改什么都可以 244 | } 245 | # 我们通过如下命令发送一个post请求 246 | r = requests.post(apiUrl, data=data).json() 247 | 248 | # 让我们打印一下返回的值，看一下我们拿到了什么 249 | print(r) 250 | ``` 251 | 252 | 我们可以看到他回复了你好。 253 | 254 | ![reply-hello][reply-hello] 255 | 256 | 至此我们已经理解并掌握了所有需要的内容，下面将其组装起来即可。 257 | 258 | ## 五、实验程序 259 | 260 | 我先从概念上说一下组装是一个怎么样的过程。 261 | 262 | 当然，如果你觉得代码更直观，我也在代码中为你写好了注释。 263 | 264 | 这里我们首先将与图灵服务器的交互定义为一个函数。 265 | 266 | 我们需要这个函数接收我们要发送给图灵的消息，返回图灵返回给我们的消息。 267 | 268 | 再将与图灵交互并返回图灵返回结果的操作写成函数并在itchat中注册。 269 | 270 | 最后启动itchat，我们的程序就完成了。 271 | 272 | ```python 273 | #coding=utf8 274 | import requests 275 | import itchat 276 | 277 | KEY = '8edce3ce905a4c1dbb965e6b35c3834d' 278 | 279 | def get_response(msg): 280 | # 这里我们就像在“3. 实现最简单的与图灵机器人的交互”中做的一样 281 | # 构造了要发送给服务器的数据 282 | apiUrl = 'http://www.tuling123.com/openapi/api' 283 | data = { 284 | 'key' : KEY, 285 | 'info' : msg, 286 | 'userid' : 'wechat-robot', 287 | } 288 | try: 289 | r = requests.post(apiUrl, data=data).json() 290 | # 字典的get方法在字典没有'text'值的时候会返回None而不会抛出异常 291 | return r.get('text') 292 | # 为了防止服务器没有正常响应导致程序异常退出，这里用try-except捕获了异常 293 | # 如果服务器没能正常交互（返回非json或无法连接），那么就会进入下面的return 294 | except: 295 | # 将会返回一个None 296 | return 297 | 298 | # 这里是我们在“1. 实现微信消息的获取”中已经用到过的同样的注册方法 299 | @itchat.msg_register(itchat.content.TEXT) 300 | def tuling_reply(msg): 301 | # 为了保证在图灵Key出现问题的时候仍旧可以回复，这里设置一个默认回复 302 | defaultReply = 'I received: ' + msg['Text'] 303 | # 如果图灵Key出现问题，那么reply将会是None 304 | reply = get_response(msg['Text']) 305 | # a or b的意思是，如果a有内容，那么返回a，否则返回b 306 | # 有内容一般就是指非空或者非None，你可以用`if a: print('True')`来测试 307 | return reply or defaultReply 308 | 309 | # 为了让实验过程更加方便（修改程序不用多次扫码），我们使用热启动 310 | itchat.auto_login(hotReload=True) 311 | itchat.run() 312 | ``` 313 | 314 | ## 六、实验结果 315 | 316 | 在本机上通过如下命令可以运行该程序 317 | 318 | ```bash 319 | python3 main.py 320 | ``` 321 | 322 | 扫码登陆后程序就成功运行了。 323 | 324 | 之后在手机上使用别的账号给自己的微信号发送消息即可获得机器人的回复。 325 | 326 | 这里给出使用的效果图： 327 | 328 | ![demo][demo] 329 | 330 | 如果你想要通过与其他用户的交互完成该操作，自行在注册的函数中进行修改即可。 331 | 332 | 如果你想要进一步了解使用Python控制微信的细节，你也可以去到项目主页[itchat][itchat]。 333 | 334 | 或者直接阅读[文档][document]也是不错的选择。 335 | 336 | 如果你的本地环境并非Python3也没有关系，itchat同样完美支持Python2。 337 | 338 | ## 七、代码获取 339 | 340 | 我将整个项目目录做了一个打包，你可以直接下载后运行。 341 | 342 | 你可以在[这里][code-package]下载。 343 | 344 | 如果有什么问题，欢迎在我的[主页][author]留言或者[邮件][email]联系我。 345 | 346 | [vip]: https://www.shiyanlou.com/courses/684 347 | [author]: https://github.com/littlecodersh 348 | [install]: http://7xrip4.com1.z0.glb.clouddn.com/shiyanlou/itchat/2/install.png?imageView/2/h/300/ 349 | [tuling]: http://tuling123.com/help/h_cent_webapi.jhtml 350 | [login]: http://7xrip4.com1.z0.glb.clouddn.com/shiyanlou/itchat/2/login.png?imageView/2/h/300/ 351 | [send-hello]: http://7xrip4.com1.z0.glb.clouddn.com/shiyanlou/itchat/2/send-hello.png?imageView/2/h/400 352 | [reply-hello]: http://7xrip4.com1.z0.glb.clouddn.com/shiyanlou/itchat/2/reply-hello.png?imageView/2/h/300/ 353 | [demo]: http://7xrip4.com1.z0.glb.clouddn.com/shiyanlou/itchat/2/demo.png?imageView/2/h/400/ 354 | [code-package]: http://7xrip4.com1.z0.glb.clouddn.com/shiyanlou/itchat/2/main.py 355 | [email]: mailto:i7meavnktqegm1b@qq.com 356 | [itchat]: https://github.com/littlecodersh/itchat 357 | [document]: http://itchat.readthedocs.io/zh/latest/ 358 | -------------------------------------------------------------------------------- /docs/tutorial/tutorial2.md: -------------------------------------------------------------------------------- 1 | # 手把手教你扩展个人微信号（2） 2 | 3 | 现在的日常生活已经离不开微信，本文将会抛砖引玉演示如何使用Python调用微信API做一些有意思的东西。 4 | 5 | 看完这一系列教程，你就能从头开始实现自己关于微信的想法。 6 | 7 | 本文为教程的第二部分，主要以微信控制器、群发助手、好友删除检测为例演示如何调用微信API。 8 | 9 | Python基础并不困难，所以即使没有这方面基础辅助搜索引擎也完全可以学习本教程。 10 | 11 | 关于本教程有任何建议或者疑问，都欢迎邮件与我联系（i7meavnktqegm1b@qq.com），或者在[github][main-page]上提出。 12 | 13 | ## 教程流程简介 14 | 15 | 这一系列教程从如何分析微信协议开始，[第一部分][tutoral#1]教你如何从零开始获取并模拟扩展个人微信号所需要的协议。 16 | 17 | 第二部分将会就这些协议进行利用，以各项目为例介绍一些微信有意思功能的实现。 18 | 19 | 第三部分就协议的一些高级用法进行介绍，对框架做进一步介绍与扩展。 20 | 21 | 本文为教程的第二部分。 22 | 23 | ## 简单成果展示 24 | 25 | 完成了本文的学习，你将会完成三个小项目：（出于方便二次阅读，括号中都放上了源码链接） 26 | 27 | * 通过微信操作的音乐播放器（[源码][demo-pcmusicviawechat]） 28 | * 消息内容与对象可自定义的消息群发助手（[源码][demo-wechatsmartwish]） 29 | * 特定好友删除检测（[源码][demo-wechatcheckfriend]） 30 | 31 | 使用微信协议完成机器人较为平常，如果对具体细节感兴趣，可以添加个人号`littlecodersh`并回复“源代码”。 32 | 33 | 本文主要基于微信API的第三方包itchat，你可以在[项目主页][main-page]获取更多信息。 34 | 35 | ## 本部分所需环境 36 | 37 | 本文是这一教程的第二部分，需要基本的pip可用的Python环境。 38 | 39 | 本教程使用的环境如下： 40 | 41 | * Windows 8.1 （其他平台也可用） 42 | * Python 2 or 3 43 | * 微信版本6.3.25 44 | 45 | ## 微信控制器 46 | 47 | ![pic0][demo-pcmusicviawechat-0] ![pic1][demo-pcmusicviawechat-1] 48 | 49 | 在项目主页上，专门有人就微信作为智能家居入口向我提出了很多想法。 50 | 51 | 如果微信可以作为控制器，就可以不必自制手机端客户端的麻烦。 52 | 53 | 其实这个需求实现起来非常简单，这里我借鉴了yaphone的[RasWxMusicbox][yaphone-raswxmusicbox]，使用了其中部分的代码作为演示。 54 | 55 | 这是一个通过微信控制电脑播放音乐的小项目，那么主要就是三个功能： 56 | * 输入“帮助”，显示帮助 57 | * 输入“关闭”，关闭音乐播放 58 | * 输入具体歌名，进入歌曲的选择 59 | 60 | 换成代码就是这样一个逻辑： 61 | ```python 62 | if msg == u'关闭': 63 | close_music() 64 | print(u'音乐已关闭') 65 | if msg == u'帮助': 66 | print(u'帮助信息') 67 | else: 68 | print(interact_select_song(msg)) 69 | ``` 70 | 71 | 那么现在需要解决的就是如何关闭音乐，如何选择音乐和如何使用微信交互。 72 | 73 | 关闭音乐我们这里使用打开空文件的方式，而选择音乐我们使用网易云音乐的API完成： 74 | ```python 75 | import os 76 | # 通过该命令安装该API： pip install NetEaseMusicApi 77 | from NetEaseMusicApi import interact_select_song 78 | 79 | with open('stop.mp3', 'w') as f: pass 80 | def close_music(): 81 | os.startfile('stop.mp3') 82 | ``` 83 | 84 | 而微信的调用可以通过itchat包简单的完成，这里要注意的是： 85 | 86 | * 有些账号无法与自己通信，所以我们选择与文件传输助手（filehelper）通信 87 | * 为了防止对于其他消息的响应，我们在第一行过滤了无关信息 88 | * itchat.run的选项分别为允许热拔插，方便调试 89 | 90 | ```python 91 | # 接上段程序 92 | # 通过该命令安装该API： pip install itchat 93 | import itchat 94 | 95 | @itchat.msg_register(itchat.content.TEXT) 96 | def music_player(msg): 97 | if msg['ToUserName'] != 'filehelper': return 98 | if msg['Text'] == u'关闭': 99 | close_music() 100 | itchat.send(u'音乐已关闭', 'filehelper') 101 | if msg['Text'] == u'帮助': 102 | itchat.send(u'帮助信息', 'filehelper') 103 | else: 104 | itchat.send(interact_select_song(msg['Text']), 'filehelper') 105 | 106 | itchat.auto_login(True) 107 | itchat.send(HELP_MSG, 'filehelper') 108 | itchat.run() 109 | ``` 110 | 111 | itchat对常用功能都做好了封装，调用还是非常容易的。 112 | 113 | 完整的程序我放在了[gist][demo-pcmusicviawechat]上面，使用时不要忘记安装第三方包。 114 | 115 | 通过与文件传输助手的交互，微信就能够轻松变成其他程序的入口。 116 | 117 | ## 群发助手 118 | 119 | 在短信的时代，逢年过节都会需要接收和发送大量的短信。 120 | 121 | 虽然自己也看到短信就烦，但不发又怕会错过什么。 122 | 123 | 所以当时就产生了各式各样的群发工具，最简单的比如在消息中加入昵称，让人感觉不像群发。 124 | 125 | 不过可惜的是，微信自带的群发助手真的只是群发。 126 | 127 | 当然，稍加操作，一切皆有可能。 128 | 129 | 例如在消息中加入昵称： 130 | 131 | * 通过`get_friends`方法可以轻松获取所有的好友（好友首位是自己） 132 | * 基于不同的好友可以发送不同的消息 133 | * 这条程序运行后是真的会发消息出去，如果只是演示目的，把`itchat.send`改为`print`即可 134 | 135 | ```python 136 | #coding=utf8 137 | import itchat, time 138 | 139 | itchat.auto_login(True) 140 | 141 | SINCERE_WISH = u'祝%s新年快乐！' 142 | 143 | friendList = itchat.get_friends(update=True)[1:] 144 | for friend in friendList: 145 | # 如果是演示目的，把下面的方法改为print即可 146 | itchat.send(SINCERE_WISH % (friend['DisplayName'] 147 | or friend['NickName']), friend['UserName']) 148 | time.sleep(.5) 149 | ``` 150 | 151 | 又例如给特定的人发送特定的消息。 152 | 153 | 我们这里通过群聊实现，划定一个群聊，在群聊内则私信发送祝福。 154 | 155 | * 如果仅是创建群聊不说话，对方是不会有提示的 156 | * 群聊如果不**保存到通讯录**，是无法在各设备之间同步的（所以itchat也无法读取到） 157 | * 群聊在被获取的时候不会自带用户列表，所以需要使用`update_chatroom`更新用户列表 158 | * 当然，如果只是演示目的，把`itchat.send`改为`print`即可 159 | 160 | ```python 161 | #coding=utf8 162 | import itchat, time 163 | 164 | itchat.auto_login(True) 165 | 166 | REAL_SINCERE_WISH = u'祝%s新年快乐！！' 167 | 168 | chatroomName='wishgroup' 169 | itchat.get_chatrooms(update=True) 170 | chatrooms = itchat.search_chatrooms(name=chatroomName) 171 | if chatrooms is None: 172 | print(u'没有找到群聊：' + chatroomName) 173 | else: 174 | chatroom = itchat.update_chatroom(chatrooms[0]['UserName']) 175 | for friend in chatroom['MemberList']: 176 | friend = itchat.search_friends(userName=friend['UserName']) 177 | # 如果是演示目的，把下面的方法改为print即可 178 | itchat.send(REAL_SINCERE_WISH % (friend['DisplayName'] 179 | or friend['NickName']), friend['UserName']) 180 | time.sleep(.5) 181 | ``` 182 | 183 | 所以我的通讯录里会有从来不用的客户群、教师群什么的。 184 | 185 | 完整的程序我放在了[gist][demo-wechatsmartwish]上面，使用时不要忘记安装第三方包。 186 | 187 | 当然，为了防止误操作，完整程序中我把所有的`itchat.send`换成了`print`。 188 | 189 | 另外，不只有文字可以发送，文件、图片也都是可行的，具体操作见itchat的[文档][document]了。 190 | 191 | itchat获取微信可以获取到的各种内容也都非常方便。 192 | 193 | 其余的例如生日，节日什么的就看具体需求了。 194 | 195 | ## 好友删除检测 196 | 197 | ![pic][demo-wechatcheckfriend-0] 198 | 199 | 有时候我们会想知道某个好友有没有删除自己或者把自己拉入黑名单。 200 | 201 | 这一操作使用itchat也会变的非常简单。 202 | 203 | 原理的话，在于将好友拉入群聊时，非好友和黑名单好友不会被拉入群聊。 204 | 205 | 所以群聊的返回值中就有了好友与你关系的数据。 206 | 207 | 另外，群聊在第一次产生普通消息时才会被除创建者以外的人发现的（系统消息不算普通消息）。 208 | 209 | 这样，就可以隐蔽的完成好友检测。 210 | 211 | 写成代码的话，这个操作就是这样的：（只是演示，不能运行，运行版本在段末） 212 | 213 | ```python 214 | chatroomUserName = '@1234567' 215 | friend = itchat.get_friends()[1] 216 | 217 | r = itchat.add_member_into_chatroom(chatroomUserName, [friend]) 218 | if r['BaseResponse']['ErrMsg'] == '': 219 | status = r['MemberList'][0]['MemberStatus'] 220 | itchat.delete_member_from_chatroom(chatroom['UserName'], [friend]) 221 | return { 3: u'该好友已经将你加入黑名单。', 222 | 4: u'该好友已经将你删除。', }.get(status, 223 | u'该好友仍旧与你是好友关系。') 224 | ``` 225 | 226 | 其中，通过`add_member_into_chatroom`操作获取我们需要的返回值，即可得到好友的状态。 227 | 228 | 同样的，这次我们也将文件传输助手作为终端，具体方法与控制器一节类似。 229 | 230 | 这次我们确定的交互方式是接收“名片”消息，并判断名片中的好友与自己的关系。 231 | 232 | 那么获取名片信息的内容可以这么写： 233 | 234 | ```python 235 | import itchat 236 | 237 | @itchat.msg_register(itchat.content.CARD) 238 | def get_friend(msg): 239 | if msg['ToUserName'] != 'filehelper': return 240 | friendStatus = get_friend_status(msg['RecommendInfo']) 241 | itchat.send(friendStatus['NickName'], 'filehelper') 242 | 243 | itchat.auto_login(True) 244 | itchat.run() 245 | ``` 246 | 247 | 那么我们所需要的所有部分就都解决了，下面将他们组合起来即可。 248 | 249 | 完整的程序我放在了[gist][demo-wechatcheckfriend]上面，使用时不要忘记安装第三方包。 250 | 251 | 在网页版微信的接口受到限制之前完全可以批量进行这一操作，检测哪些好友删除了自己。 252 | 253 | 但目前显然操作存在频率限制，所以只能做一些变通了。 254 | 255 | ## 之后的内容 256 | 257 | 到这里这一篇文章的主要内容就结束了。 258 | 259 | 主要从微信作为终端使用、自定义的消息交互、微信协议研究三方面开了一个简单的头。 260 | 261 | 其余有一些过于大众，如机器人，就不再赘述。 262 | 263 | 而另一些，需要一定的基础或者不适合分享，就留给各位自行研究。 264 | 265 | 如果要留个悬念，可以想象添加好友的方法status传2，轻松实现好友病毒式扩张。 266 | 267 | 利用微信的API可以做很多事情，文档我放在[这里][document]，祝好运！ 268 | 269 | ## 结束语 270 | 271 | 希望读完这篇文章能对你有帮助，有什么不足之处万望指正（鞠躬）。 272 | 273 | 有什么想法或者想要关注我的更新，欢迎来[**Github**](https://github.com/littlecodersh/ItChat)上***Star***或者***Fork***。 274 | 275 | 160928 276 | 277 | LittleCoder 278 | 279 | EOF 280 | 281 | 282 | [document]: http://itchat.readthedocs.io/zh/latest/ 283 | [main-page]: https://github.com/littlecodersh/ItChat 284 | [tutoral#1]: http://python.jobbole.com/84918/ 285 | [yaphone-raswxmusicbox]: https://github.com/yaphone/RasWxMusicbox 286 | [demo-pcmusicviawechat]: https://gist.github.com/littlecodersh/8468afbbb8d34c0c0e6848b6f9009c4c 287 | [demo-wechatsmartwish]: https://gist.github.com/littlecodersh/ae13ed93e0e8f3c820226fc6871f436d 288 | [demo-wechatcheckfriend]: https://gist.github.com/littlecodersh/3fef7d2afb2d502e4735be083c9f79e1 289 | [demo-pcmusicviawechat-0]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat/Tutorial/2/demo-pcmusicviawechat-0.png?imageView/2/w/200/ 290 | [demo-pcmusicviawechat-1]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat/Tutorial/2/demo-pcmusicviawechat-1.png?imageView/2/w/200/ 291 | [demo-wechatcheckfriend-0]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat/Tutorial/2/demo-wechatcheckfriend.png?imageView/2/w/200/ 292 | -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # itchat 2 | 3 | ![py27][py27] ![py35][py35] 4 | 5 | itchat是一个开源的微信个人号接口，使用python调用微信从未如此简单。 6 | 7 | 使用不到三十行的代码，你就可以完成一个能够处理所有信息的微信机器人。 8 | 9 | 当然，该api的使用远不止一个机器人，更多的功能等着你来发现，比如[这些][tutorial2]。 10 | 11 | 该接口与公众号接口[itchatmp][itchatmp]共享类似的操作方式，学习一次掌握两个工具。 12 | 13 | 如今微信已经成为了个人社交的很大一部分，希望这个项目能够帮助你扩展你的个人的微信号、方便自己的生活。 14 | 15 | ## 安装 16 | 17 | 可以通过本命令安装itchat： 18 | 19 | ```python 20 | pip install itchat 21 | ``` 22 | 23 | ## 简单入门实例 24 | 25 | 有了itchat，如果你想要给文件传输助手发一条信息，只需要这样： 26 | 27 | ```python 28 | import itchat 29 | 30 | itchat.auto_login() 31 | 32 | itchat.send('Hello, filehelper', toUserName='filehelper') 33 | ``` 34 | 35 | 如果你想要回复发给自己的文本消息，只需要这样： 36 | 37 | ```python 38 | import itchat 39 | 40 | @itchat.msg_register(itchat.content.TEXT) 41 | def text_reply(msg): 42 | return msg.text 43 | 44 | itchat.auto_login() 45 | itchat.run() 46 | ``` 47 | 48 | 一些进阶应用可以在下面的开源机器人的源码和进阶应用中看到，或者你也可以阅览[文档][document]。 49 | 50 | ## 试一试 51 | 52 | 这是一个基于这一项目的[开源小机器人][robot-source-code]，百闻不如一见，有兴趣可以尝试一下。 53 | 54 | ![QRCode][robot-qr] 55 | 56 | ## 截屏 57 | 58 | ![file-autoreply][robot-demo-file] ![login-page][robot-demo-login] 59 | 60 | ## 进阶应用 61 | 62 | ### 特殊的字典使用方式 63 | 64 | 通过打印itchat的用户以及注册消息的参数，可以发现这些值都是字典。 65 | 66 | 但实际上itchat精心构造了相应的消息、用户、群聊、公众号类。 67 | 68 | 其所有的键值都可以通过这一方式访问： 69 | 70 | ```python 71 | @itchat.msg_register(TEXT) 72 | def _(msg): 73 | # equals to print(msg['FromUserName']) 74 | print(msg.fromUserName) 75 | ``` 76 | 77 | 属性名为键值首字母小写后的内容。 78 | 79 | ```python 80 | author = itchat.search_friends(nickName='LittleCoder')[0] 81 | author.send('greeting, littlecoder!') 82 | ``` 83 | 84 | ### 各类型消息的注册 85 | 86 | 通过如下代码，微信已经可以就日常的各种信息进行获取与回复。 87 | 88 | ```python 89 | import itchat, time 90 | from itchat.content import * 91 | 92 | @itchat.msg_register([TEXT, MAP, CARD, NOTE, SHARING]) 93 | def text_reply(msg): 94 | msg.user.send('%s: %s' % (msg.type, msg.text)) 95 | 96 | @itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO]) 97 | def download_files(msg): 98 | msg.download(msg.fileName) 99 | typeSymbol = { 100 | PICTURE: 'img', 101 | VIDEO: 'vid', }.get(msg.type, 'fil') 102 | return '@%s@%s' % (typeSymbol, msg.fileName) 103 | 104 | @itchat.msg_register(FRIENDS) 105 | def add_friend(msg): 106 | msg.user.verify() 107 | msg.user.send('Nice to meet you!') 108 | 109 | @itchat.msg_register(TEXT, isGroupChat=True) 110 | def text_reply(msg): 111 | if msg.isAt: 112 | msg.user.send(u'@%s\u2005I received: %s' % ( 113 | msg.actualNickName, msg.text)) 114 | 115 | itchat.auto_login(True) 116 | itchat.run(True) 117 | ``` 118 | 119 | ### 命令行二维码 120 | 121 | 通过以下命令可以在登陆的时候使用命令行显示二维码： 122 | 123 | ```python 124 | itchat.auto_login(enableCmdQR=True) 125 | ``` 126 | 127 | 部分系统可能字幅宽度有出入，可以通过将enableCmdQR赋值为特定的倍数进行调整： 128 | 129 | ```python 130 | # 如部分的linux系统，块字符的宽度为一个字符（正常应为两字符），故赋值为2 131 | itchat.auto_login(enableCmdQR=2) 132 | ``` 133 | 134 | 默认控制台背景色为暗色（黑色），若背景色为浅色（白色），可以将enableCmdQR赋值为负值： 135 | 136 | ```python 137 | itchat.auto_login(enableCmdQR=-1) 138 | ``` 139 | 140 | ### 退出程序后暂存登陆状态 141 | 142 | 通过如下命令登陆，即使程序关闭，一定时间内重新开启也可以不用重新扫码。 143 | 144 | ```python 145 | itchat.auto_login(hotReload=True) 146 | ``` 147 | 148 | ### 用户搜索 149 | 150 | 使用`search_friends`方法可以搜索用户，有四种搜索方式： 151 | 1. 仅获取自己的用户信息 152 | 2. 获取特定`UserName`的用户信息 153 | 3. 获取备注、微信号、昵称中的任何一项等于`name`键值的用户 154 | 4. 获取备注、微信号、昵称分别等于相应键值的用户 155 | 156 | 其中三、四项可以一同使用，下面是示例程序： 157 | 158 | ```python 159 | # 获取自己的用户信息，返回自己的属性字典 160 | itchat.search_friends() 161 | # 获取特定UserName的用户信息 162 | itchat.search_friends(userName='@abcdefg1234567') 163 | # 获取任何一项等于name键值的用户 164 | itchat.search_friends(name='littlecodersh') 165 | # 获取分别对应相应键值的用户 166 | itchat.search_friends(wechatAccount='littlecodersh') 167 | # 三、四项功能可以一同使用 168 | itchat.search_friends(name='LittleCoder机器人', wechatAccount='littlecodersh') 169 | ``` 170 | 171 | 关于公众号、群聊的获取与搜索在文档中有更加详细的介绍。 172 | 173 | ### 附件的下载与发送 174 | 175 | itchat的附件下载方法存储在msg的Text键中。 176 | 177 | 发送的文件的文件名（图片给出的默认文件名）都存储在msg的FileName键中。 178 | 179 | 下载方法接受一个可用的位置参数（包括文件名），并将文件相应的存储。 180 | 181 | ```python 182 | @itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO]) 183 | def download_files(msg): 184 | msg.download(msg.fileName) 185 | itchat.send('@%s@%s' % ( 186 | 'img' if msg['Type'] == 'Picture' else 'fil', msg['FileName']), 187 | msg['FromUserName']) 188 | return '%s received' % msg['Type'] 189 | ``` 190 | 191 | 如果你不需要下载到本地，仅想要读取二进制串进行进一步处理可以不传入参数，方法将会返回图片的二进制串。 192 | 193 | ```python 194 | @itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO]) 195 | def download_files(msg): 196 | with open(msg.fileName, 'wb') as f: 197 | f.write(msg.download()) 198 | ``` 199 | 200 | ### 用户多开 201 | 202 | 使用如下命令可以完成多开的操作： 203 | 204 | ```python 205 | import itchat 206 | 207 | newInstance = itchat.new_instance() 208 | newInstance.auto_login(hotReload=True, statusStorageDir='newInstance.pkl') 209 | 210 | @newInstance.msg_register(TEXT) 211 | def reply(msg): 212 | return msg.text 213 | 214 | newInstance.run() 215 | ``` 216 | 217 | ### 退出及登陆完成后调用特定方法 218 | 219 | 登陆完成后的方法需要赋值在`loginCallback`中。 220 | 221 | 而退出后的方法需要赋值在`exitCallback`中。 222 | 223 | ```python 224 | import time 225 | 226 | import itchat 227 | 228 | def lc(): 229 | print('finish login') 230 | def ec(): 231 | print('exit') 232 | 233 | itchat.auto_login(loginCallback=lc, exitCallback=ec) 234 | time.sleep(3) 235 | itchat.logout() 236 | ``` 237 | 238 | 若不设置loginCallback的值，则将会自动删除二维码图片并清空命令行显示。 239 | 240 | ## 常见问题与解答 241 | 242 | Q: 为什么中文的文件没有办法上传？ 243 | 244 | A: 这是由于`requests`的编码问题导致的。若需要支持中文文件传输，将[fields.py][fields.py-2](py3版本见[这里][fields.py-3])文件放入requests包的packages/urllib3下即可 245 | 246 | Q: 如何通过这个包将自己的微信号变为控制器？ 247 | 248 | A: 有两种方式：发送、接受自己UserName的消息；发送接收文件传输助手（filehelper）的消息 249 | 250 | Q: 为什么我发送信息的时候部分信息没有成功发出来？ 251 | 252 | A: 有些账号是天生无法给自己的账号发送信息的，建议使用`filehelper`代替。 253 | 254 | ## 作者 255 | 256 | [LittleCoder][littlecodersh]: 构架及维护Python2 Python3版本。 257 | 258 | [tempdban][tempdban]: 协议、构架及日常维护。 259 | 260 | [Chyroc][Chyroc]: 完成第一版本的Python3构架。 261 | 262 | ## 类似项目 263 | 264 | [youfou/wxpy][youfou-wxpy]: 优秀的api包装和配套插件，微信机器人/优雅的微信个人号API 265 | 266 | [liuwons/wxBot][liuwons-wxBot]: 类似的基于Python的微信机器人 267 | 268 | [zixia/wechaty][zixia-wechaty]: 基于Javascript(ES6)的微信个人账号机器人NodeJS框架/库 269 | 270 | [sjdy521/Mojo-Weixin][Mojo-Weixin]: 使用Perl语言编写的微信客户端框架，可通过插件提供基于HTTP协议的api接口供其他语言调用 271 | 272 | [HanSon/vbot][HanSon-vbot]: 基于PHP7的微信个人号机器人，通过实现匿名函数可以方便地实现各种自定义的功能 273 | 274 | ## 问题和建议 275 | 276 | 如果有什么问题或者建议都可以在这个[Issue][issue#1]和我讨论 277 | 278 | 或者也可以在gitter上交流：[![Gitter][gitter-picture]][gitter] 279 | 280 | 当然也可以加入我们新建的QQ群讨论：549762872 281 | 282 | [gitter-picture]: https://badges.gitter.im/littlecodersh/ItChat.svg 283 | [gitter]: https://gitter.im/littlecodersh/ItChat?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge 284 | [py27]: https://img.shields.io/badge/python-2.7-ff69b4.svg 285 | [py35]: https://img.shields.io/badge/python-3.5-red.svg 286 | [english-version]: https://github.com/littlecodersh/ItChat/blob/master/README_EN.md 287 | [itchatmp]: https://github.com/littlecodersh/itchatmp 288 | [document]: https://itchat.readthedocs.org/zh/latest/ 289 | [tutorial2]: http://python.jobbole.com/86532/ 290 | [robot-source-code]: https://gist.github.com/littlecodersh/ec8ddab12364323c97d4e36459174f0d 291 | [robot-qr]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat%2FQRCode2.jpg?imageView/2/w/400/ 292 | [robot-demo-file]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat%2FScreenshots%2F%E5%BE%AE%E4%BF%A1%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E5%9B%BE%E7%89%87.png?imageView/2/w/300/ 293 | [robot-demo-login]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat%2FScreenshots%2F%E7%99%BB%E5%BD%95%E7%95%8C%E9%9D%A2%E6%88%AA%E5%9B%BE.jpg?imageView/2/w/450/ 294 | [fields.py-2]: https://gist.github.com/littlecodersh/9a0c5466f442d67d910f877744011705 295 | [fields.py-3]: https://gist.github.com/littlecodersh/e93532d5e7ddf0ec56c336499165c4dc 296 | [littlecodersh]: https://github.com/littlecodersh 297 | [tempdban]: https://github.com/tempdban 298 | [Chyroc]: https://github.com/Chyroc 299 | [youfou-wxpy]: https://github.com/youfou/wxpy 300 | [liuwons-wxBot]: https://github.com/liuwons/wxBot 301 | [zixia-wechaty]: https://github.com/zixia/wechaty 302 | [Mojo-Weixin]: https://github.com/sjdy521/Mojo-Weixin 303 | [HanSon-vbot]: https://github.com/hanson/vbot 304 | [issue#1]: https://github.com/littlecodersh/ItChat/issues/1 305 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # itchat 2 | 3 | [![Gitter][gitter-picture]][gitter] ![py27][py27] ![py35][py35] [English version][english-version] 4 | 5 | itchat是一个开源的微信个人号接口，使用python调用微信从未如此简单。 6 | 7 | 使用不到三十行的代码，你就可以完成一个能够处理所有信息的微信机器人。 8 | 9 | 当然，该api的使用远不止一个机器人，更多的功能等着你来发现，比如[这些][tutorial2]。 10 | 11 | 该接口与公众号接口[itchatmp][itchatmp]共享类似的操作方式，学习一次掌握两个工具。 12 | 13 | 如今微信已经成为了个人社交的很大一部分，希望这个项目能够帮助你扩展你的个人的微信号、方便自己的生活。 14 | 15 | ## 安装 16 | 17 | 可以通过本命令安装itchat： 18 | 19 | ```python 20 | pip install itchat 21 | ``` 22 | 23 | ## 简单入门实例 24 | 25 | 有了itchat，如果你想要给文件传输助手发一条信息，只需要这样： 26 | 27 | ```python 28 | import itchat 29 | 30 | itchat.auto_login() 31 | 32 | itchat.send('Hello, filehelper', toUserName='filehelper') 33 | ``` 34 | 35 | 如果你想要回复发给自己的文本消息，只需要这样： 36 | 37 | ```python 38 | import itchat 39 | 40 | @itchat.msg_register(itchat.content.TEXT) 41 | def text_reply(msg): 42 | return msg.text 43 | 44 | itchat.auto_login() 45 | itchat.run() 46 | ``` 47 | 48 | 一些进阶应用可以在下面的开源机器人的源码和进阶应用中看到，或者你也可以阅览[文档][document]。 49 | 50 | ## 试一试 51 | 52 | 这是一个基于这一项目的[开源小机器人][robot-source-code]，百闻不如一见，有兴趣可以尝试一下。 53 | 54 | 由于好友数量实在增长过快，自动通过好友验证的功能演示暂时关闭。 55 | 56 | ![QRCode][robot-qr] 57 | 58 | ## 截屏 59 | 60 | ![file-autoreply][robot-demo-file] ![login-page][robot-demo-login] 61 | 62 | ## 进阶应用 63 | 64 | ### 特殊的字典使用方式 65 | 66 | 通过打印itchat的用户以及注册消息的参数，可以发现这些值都是字典。 67 | 68 | 但实际上itchat精心构造了相应的消息、用户、群聊、公众号类。 69 | 70 | 其所有的键值都可以通过这一方式访问： 71 | 72 | ```python 73 | @itchat.msg_register(TEXT) 74 | def _(msg): 75 | # equals to print(msg['FromUserName']) 76 | print(msg.fromUserName) 77 | ``` 78 | 79 | 属性名为键值首字母小写后的内容。 80 | 81 | ```python 82 | author = itchat.search_friends(nickName='LittleCoder')[0] 83 | author.send('greeting, littlecoder!') 84 | ``` 85 | 86 | ### 各类型消息的注册 87 | 88 | 通过如下代码，微信已经可以就日常的各种信息进行获取与回复。 89 | 90 | ```python 91 | import itchat, time 92 | from itchat.content import * 93 | 94 | @itchat.msg_register([TEXT, MAP, CARD, NOTE, SHARING]) 95 | def text_reply(msg): 96 | msg.user.send('%s: %s' % (msg.type, msg.text)) 97 | 98 | @itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO]) 99 | def download_files(msg): 100 | msg.download(msg.fileName) 101 | typeSymbol = { 102 | PICTURE: 'img', 103 | VIDEO: 'vid', }.get(msg.type, 'fil') 104 | return '@%s@%s' % (typeSymbol, msg.fileName) 105 | 106 | @itchat.msg_register(FRIENDS) 107 | def add_friend(msg): 108 | msg.user.verify() 109 | msg.user.send('Nice to meet you!') 110 | 111 | @itchat.msg_register(TEXT, isGroupChat=True) 112 | def text_reply(msg): 113 | if msg.isAt: 114 | msg.user.send(u'@%s\u2005I received: %s' % ( 115 | msg.actualNickName, msg.text)) 116 | 117 | itchat.auto_login(True) 118 | itchat.run(True) 119 | ``` 120 | 121 | ### 命令行二维码 122 | 123 | 通过以下命令可以在登陆的时候使用命令行显示二维码： 124 | 125 | ```python 126 | itchat.auto_login(enableCmdQR=True) 127 | ``` 128 | 129 | 部分系统可能字幅宽度有出入，可以通过将enableCmdQR赋值为特定的倍数进行调整： 130 | 131 | ```python 132 | # 如部分的linux系统，块字符的宽度为一个字符（正常应为两字符），故赋值为2 133 | itchat.auto_login(enableCmdQR=2) 134 | ``` 135 | 136 | 默认控制台背景色为暗色（黑色），若背景色为浅色（白色），可以将enableCmdQR赋值为负值： 137 | 138 | ```python 139 | itchat.auto_login(enableCmdQR=-1) 140 | ``` 141 | 142 | ### 退出程序后暂存登陆状态 143 | 144 | 通过如下命令登陆，即使程序关闭，一定时间内重新开启也可以不用重新扫码。 145 | 146 | ```python 147 | itchat.auto_login(hotReload=True) 148 | ``` 149 | 150 | ### 用户搜索 151 | 152 | 使用`search_friends`方法可以搜索用户，有四种搜索方式： 153 | 1. 仅获取自己的用户信息 154 | 2. 获取特定`UserName`的用户信息 155 | 3. 获取备注、微信号、昵称中的任何一项等于`name`键值的用户 156 | 4. 获取备注、微信号、昵称分别等于相应键值的用户 157 | 158 | 其中三、四项可以一同使用，下面是示例程序： 159 | 160 | ```python 161 | # 获取自己的用户信息，返回自己的属性字典 162 | itchat.search_friends() 163 | # 获取特定UserName的用户信息 164 | itchat.search_friends(userName='@abcdefg1234567') 165 | # 获取任何一项等于name键值的用户 166 | itchat.search_friends(name='littlecodersh') 167 | # 获取分别对应相应键值的用户 168 | itchat.search_friends(wechatAccount='littlecodersh') 169 | # 三、四项功能可以一同使用 170 | itchat.search_friends(name='LittleCoder机器人', wechatAccount='littlecodersh') 171 | ``` 172 | 173 | 关于公众号、群聊的获取与搜索在文档中有更加详细的介绍。 174 | 175 | ### 附件的下载与发送 176 | 177 | itchat的附件下载方法存储在msg的Text键中。 178 | 179 | 发送的文件的文件名（图片给出的默认文件名）都存储在msg的FileName键中。 180 | 181 | 下载方法接受一个可用的位置参数（包括文件名），并将文件相应的存储。 182 | 183 | ```python 184 | @itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO]) 185 | def download_files(msg): 186 | msg.download(msg.fileName) 187 | itchat.send('@%s@%s' % ( 188 | 'img' if msg['Type'] == 'Picture' else 'fil', msg['FileName']), 189 | msg['FromUserName']) 190 | return '%s received' % msg['Type'] 191 | ``` 192 | 193 | 如果你不需要下载到本地，仅想要读取二进制串进行进一步处理可以不传入参数，方法将会返回图片的二进制串。 194 | 195 | ```python 196 | @itchat.msg_register([PICTURE, RECORDING, ATTACHMENT, VIDEO]) 197 | def download_files(msg): 198 | with open(msg.fileName, 'wb') as f: 199 | f.write(msg.download()) 200 | ``` 201 | 202 | ### 用户多开 203 | 204 | 使用如下命令可以完成多开的操作： 205 | 206 | ```python 207 | import itchat 208 | 209 | newInstance = itchat.new_instance() 210 | newInstance.auto_login(hotReload=True, statusStorageDir='newInstance.pkl') 211 | 212 | @newInstance.msg_register(itchat.content.TEXT) 213 | def reply(msg): 214 | return msg.text 215 | 216 | newInstance.run() 217 | ``` 218 | 219 | ### 退出及登陆完成后调用特定方法 220 | 221 | 登陆完成后的方法需要赋值在`loginCallback`中。 222 | 223 | 而退出后的方法需要赋值在`exitCallback`中。 224 | 225 | ```python 226 | import time 227 | 228 | import itchat 229 | 230 | def lc(): 231 | print('finish login') 232 | def ec(): 233 | print('exit') 234 | 235 | itchat.auto_login(loginCallback=lc, exitCallback=ec) 236 | time.sleep(3) 237 | itchat.logout() 238 | ``` 239 | 240 | 若不设置loginCallback的值，则将会自动删除二维码图片并清空命令行显示。 241 | 242 | ## 常见问题与解答 243 | 244 | Q: 如何通过这个包将自己的微信号变为控制器？ 245 | 246 | A: 有两种方式：发送、接受自己UserName的消息；发送接收文件传输助手（filehelper）的消息 247 | 248 | Q: 为什么我发送信息的时候部分信息没有成功发出来？ 249 | 250 | A: 有些账号是天生无法给自己的账号发送信息的，建议使用`filehelper`代替。 251 | 252 | ## 作者 253 | 254 | [LittleCoder][littlecodersh]: 构架及维护Python2 Python3版本。 255 | 256 | [tempdban][tempdban]: 协议、构架及日常维护。 257 | 258 | [Chyroc][Chyroc]: 完成第一版本的Python3构架。 259 | 260 | ## 类似项目 261 | 262 | [youfou/wxpy][youfou-wxpy]: 优秀的api包装和配套插件，微信机器人/优雅的微信个人号API 263 | 264 | [liuwons/wxBot][liuwons-wxBot]: 类似的基于Python的微信机器人 265 | 266 | [zixia/wechaty][zixia-wechaty]: 基于Javascript(ES6)的微信个人账号机器人NodeJS框架/库 267 | 268 | [sjdy521/Mojo-Weixin][Mojo-Weixin]: 使用Perl语言编写的微信客户端框架，可通过插件提供基于HTTP协议的api接口供其他语言调用 269 | 270 | [HanSon/vbot][HanSon-vbot]: 基于PHP7的微信个人号机器人，通过实现匿名函数可以方便地实现各种自定义的功能 271 | 272 | [yaphone/itchat4j][yaphone-itchat4j]: 用Java扩展个人微信号的能力 273 | 274 | [kanjielu/jeeves][kanjielu-jeeves]: 使用springboot开发的微信机器人 275 | 276 | ## 问题和建议 277 | 278 | 如果有什么问题或者建议都可以在这个[Issue][issue#1]和我讨论 279 | 280 | 或者也可以在gitter上交流：[![Gitter][gitter-picture]][gitter] 281 | 282 | 当然也可以加入我们新建的QQ群讨论：549762872, 205872856 283 | 284 | [gitter-picture]: https://badges.gitter.im/littlecodersh/ItChat.svg 285 | [gitter]: https://gitter.im/littlecodersh/ItChat?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge 286 | [py27]: https://img.shields.io/badge/python-2.7-ff69b4.svg 287 | [py35]: https://img.shields.io/badge/python-3.5-red.svg 288 | [english-version]: https://github.com/littlecodersh/ItChat/blob/master/README_EN.md 289 | [itchatmp]: https://github.com/littlecodersh/itchatmp 290 | [document]: https://itchat.readthedocs.org/zh/latest/ 291 | [tutorial2]: http://python.jobbole.com/86532/ 292 | [robot-source-code]: https://gist.github.com/littlecodersh/ec8ddab12364323c97d4e36459174f0d 293 | [robot-qr]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat%2FQRCode2.jpg?imageView/2/w/400/ 294 | [robot-demo-file]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat%2FScreenshots%2F%E5%BE%AE%E4%BF%A1%E8%8E%B7%E5%8F%96%E6%96%87%E4%BB%B6%E5%9B%BE%E7%89%87.png?imageView/2/w/300/ 295 | [robot-demo-login]: http://7xrip4.com1.z0.glb.clouddn.com/ItChat%2FScreenshots%2F%E7%99%BB%E5%BD%95%E7%95%8C%E9%9D%A2%E6%88%AA%E5%9B%BE.jpg?imageView/2/w/450/ 296 | [littlecodersh]: https://github.com/littlecodersh 297 | [tempdban]: https://github.com/tempdban 298 | [Chyroc]: https://github.com/Chyroc 299 | [youfou-wxpy]: https://github.com/youfou/wxpy 300 | [liuwons-wxBot]: https://github.com/liuwons/wxBot 301 | [zixia-wechaty]: https://github.com/zixia/wechaty 302 | [Mojo-Weixin]: https://github.com/sjdy521/Mojo-Weixin 303 | [HanSon-vbot]: https://github.com/hanson/vbot 304 | [yaphone-itchat4j]: https://github.com/yaphone/itchat4j 305 | [kanjielu-jeeves]: https://github.com/kanjielu/jeeves 306 | [issue#1]: https://github.com/littlecodersh/ItChat/issues/1 307 | -------------------------------------------------------------------------------- /docs/intro/messages.md: -------------------------------------------------------------------------------- 1 | # 消息内容 2 | 3 | ## 微信一般消息内容 4 | 5 | ```python 6 | { 7 | "FromUserName": "", 8 | "ToUserName": "", 9 | "Content": "", 10 | "StatusNotifyUserName": "", 11 | "ImgWidth": 0, 12 | "PlayLength": 0, 13 | "RecommendInfo": {}, 14 | "StatusNotifyCode": 0, 15 | "NewMsgId": "", 16 | "Status": 0, 17 | "VoiceLength": 0, 18 | "ForwardFlag": 0, 19 | "AppMsgType": 0, 20 | "Ticket": "", 21 | "AppInfo": {}, 22 | "Url": "", 23 | "ImgStatus": 0, 24 | "MsgType": 0, 25 | "ImgHeight": 0, 26 | "MediaId": "", 27 | "MsgId": "", 28 | "FileName": "", 29 | "HasProductId": 0, 30 | "FileSize": "", 31 | "CreateTime": 0, 32 | "SubMsgType": 0 33 | } 34 | ``` 35 | 36 | 微信回复的所有消息都遵循这一格式，下面将就每种消息类型具体分析。 37 | 38 | ## 消息的具体内容 39 | 40 | 本段部分参考[Urinx的Github](https://github.com/Urinx/WeixinBot)并修改。 41 | 42 | ### 微信初始化消息 43 | 44 | ``` 45 | MsgType: 51 46 | FromUserName: 自己ID 47 | ToUserName: 自己ID 48 | StatusNotifyUserName: 最近联系的联系人ID 49 | Content: 50 |
xxx 286 | ``` 287 | 288 | itchat增加了三个群聊相关的键值： 289 | 290 | * isAt: 判断是否@本号 291 | * ActualNickName: 实际NickName 292 | * Content: 实际Content 293 | 294 | ### 红包消息 295 | 296 | ``` 297 | MsgType: 49 298 | AppMsgType: 2001 299 | FromUserName: 发送方ID 300 | ToUserName: 接收方ID 301 | Content: 未知 302 | ``` 303 | 304 | ### 系统消息 305 | 306 | ``` 307 | MsgType: 10000 308 | FromUserName: 发送方ID 309 | ToUserName: 自己ID 310 | Content: 311 | "你已添加了 xxx ，现在可以开始聊天了。" 312 | "如果陌生人主动添加你为朋友，请谨慎核实对方身份。" 313 | "收到红包，请在手机上查看" 314 | ``` 315 | -------------------------------------------------------------------------------- /README.rst: -------------------------------------------------------------------------------- 1 | itchat 2 | ====== 3 | 4 | |Python2| |Python3| 5 | 6 | itchat is an open source api for WeChat, a commonly-used Chinese social networking app. 7 | 8 | Accessing your personal wechat account through itchat in python has never been easier. 9 | 10 | A wechat robot can handle all the basic messages with only less than 30 lines of codes. 11 | 12 | And it's similiar to itchatmp (api for wechat massive platform), learn once and get two tools. 13 | 14 | Now Wechat is an important part of personal life, hopefully this repo can help you extend your personal wechat account's functionality and enbetter user's experience with wechat. 15 | 16 | **Installation** 17 | 18 | .. code:: bash 19 | 20 | pip install itchat 21 | 22 | **Simple uses** 23 | 24 | With itchat, if you want to send a message to filehelper, this is how: 25 | 26 | .. code:: python 27 | 28 | import itchat 29 | 30 | itchat.auto_login() 31 | 32 | itchat.send('Hello, filehelper', toUserName='filehelper') 33 | 34 | And you only need to write this to reply personal text messages. 35 | 36 | .. code:: python 37 | 38 | import itchat 39 | 40 | @itchat.msg_register(itchat.content.TEXT) 41 | def text_reply(msg): 42 | return msg.text 43 | 44 | itchat.auto_login() 45 | itchat.run() 46 | 47 | For more advanced uses you may continue on reading or browse the `document