Merge branch 'release/v0.5.1'

doraemonext · Feb 3, 2015 · 5307f3e · 5307f3e
2 parents e5eef28 + a9106da
commit 5307f3e
Show file tree

Hide file tree

Showing 9 changed files with 437 additions and 47 deletions.
diff --git a/README.rst b/README.rst
@@ -32,6 +32,7 @@
   * 根据消息ID获取图片消息内容
   * 根据消息ID获取语音消息内容
   * 根据消息ID获取视频消息内容
+  * 获取图文分析信息
 
 **请注意：本开发包并不打算提供一个独立的完整微信解决方案，我们更希望这个开发包可以非常融洽的在各个框架中进行集成并使用，对于HTTP请求及响应方面并不涉及，该开发包仅仅接受必要参数，提供各种微信操作的方法，并返回相应的可以响应微信服务器的数据(Response)或操作执行结果。**
 
@@ -58,6 +59,13 @@
 ChangeLog
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+v0.5.1
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* 官方接口增加了 JS-SDK 支持，可对 URL 进行签名 (感谢 `https://github.com/JohnnyZhao <JohnnyZhao>`_)
+* 官方接口的文本回复方法增加了是否对内容进行转义的控制参数
+* 非官方接口增加了图文分析信息 (感谢 `https://github.com/svcvit <svcvit>`_)
+
 v0.5.0
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/docs/basic.rst b/docs/basic.rst
@@ -1,7 +1,7 @@
 微信官方接口操作 WechatBasic
 =================================
 
-.. py:class:: wechat_sdk.basic.WechatBasic(token=None, appid=None, appsecret=None, partnerid=None, partnerkey=None, paysignkey=None, access_token=None, access_token_expires_at=None)
+.. py:class:: wechat_sdk.basic.WechatBasic(token=None, appid=None, appsecret=None, partnerid=None, partnerkey=None, paysignkey=None, access_token=None, access_token_expires_at=None, jsapi_ticket=None, jsapi_ticket_expires_at=None)
 
     微信基本功能类
 
@@ -13,24 +13,24 @@
     :param str paysignkey: 商户签名密钥 Key, 支付权限专用
     :param str access_token: 直接导入的 ``access_token`` 值, 该值需要在上一次该类实例化之后手动进行缓存并在此处传入, 如果不传入, 将会在需要时自动重新获取
     :param str access_token_expires_at: 直接导入的 ``access_token`` 的过期日期，该值需要在上一次该类实例化之后手动进行缓存并在此处传入, 如果不传入, 将会在需要时自动重新获取
+    :param str jsapi_ticket: 直接导入的 ``jsapi_ticket`` 值, 该值需要在上一次该类实例化之后手动进行缓存并在此处传入, 如果不传入, 将会在需要时自动重新获取
+    :param str jsapi_ticket_expires_at: 直接导入的 ``jsapi_ticket`` 的过期日期，该值需要在上一次该类实例化之后手动进行缓存并在此处传入, 如果不传入, 将会在需要时自动重新获取
 
     **实例化说明：**
 
-    1. 当实例化 WechatBasic 时，你可以传递上述参数说明中任意多个参数进去，但是传递参数不足将会在使用部分功能时引发对应的异常，下面列举使用场景和应该传递哪些参数：
+    1. 当实例化 WechatBasic 时，你可以传递上述参数说明中任意多个参数进去，但是传递参数不足将会在使用部分功能时引发对应的异常。
 
-     - **订阅号(未认证)** ：仅传入 ``token`` 参数
+     **虽然认证订阅号、未认证服务号拥有 appid 及 appsecret，但不代表其能调用高级接口** ，这两种类型的账号仅能进行自定义菜单及JS相关操作，进行其他权限外操作仍然会抛出异常 ``OfficialAPIError``
 
-     - **其他(认证订阅号, 未认证服务号, 认证服务号)** ：传入 ``token``, ``appid``, ``appsecret``, ``access_token``, ``access_token_expires_at`` 参数，如果已经开通支付权限，请传入 ``partnerid``, ``partnerkey``, ``paysignkey`` 参数
+    2. **详细说明一下 access_token, access_token_expires_at, jsapi_ticket, jsapi_ticket_expires_at 参数的传入问题：**
 
-     **虽然认证订阅号、未认证服务号拥有 appid 及 appsecret，但不代表其能调用高级接口** ，这两种类型的账号仅能进行自定义菜单操作，进行其他权限外操作仍然会抛出异常 ``OfficialAPIError``
-
-    2. **详细说明一下 access_token 及 access_token_expires_at 参数的传入问题：**
-
-     因为此开发包并不打算以服务器的方式常驻，所以，每次请求均会重新实例化 ``WechatBasic`` ，而微信的 ``access_token`` 有效期为 7200 秒，不可能每次实例化的时候去重新获取，所以需要你以你自己的方式去保存上一次请求中实例化后的 ``WechatBasic`` 中 ``access_token`` 及 ``access_token_expires_at`` 参数，并在下一次的实例化的过程中传入，以此来保证 ``access_token`` 的持久性。
+     因为此开发包并不打算以服务器的方式常驻，所以，每次请求均会重新实例化 ``WechatBasic`` ，而微信的 ``access_token`` 和 ``jsapi_ticket`` 的有效期为 7200 秒，不可能每次实例化的时候去重新获取，所以需要你以你自己的方式去保存上一次请求中实例化后的 ``WechatBasic`` 中 ``access_token``, ``access_token_expires_at``, ``jsapi_ticket``, ``jsapi_ticket_expires_at`` 参数，并在下一次的实例化的过程中传入，以此来保证 ``access_token`` 及 ``jsapi_ticket`` 的持久性。
 
      获取 ``access_token`` 及 ``access_token_expires_at`` 的方式为调用 :func:`get_access_token` 方法
 
-     下一版本将会考虑更为简单通用的方法，在新版本发布之前，请用你自己的方式把得到的 ``access_token`` 及 ``access_token_expires_at`` 保存起来，不管是文件，缓存还是数据库都可以，获取 ``access_token`` 和 ``access_token_expires_at`` 的时间可以非常自由，不管是刚刚实例化完成还是得到响应结果之后都没有问题，在调用 :func:`get_access_token` 时如果没有 ``access_token`` 会自动获取的 :)
+     获取 ``jsapi_ticket`` 及 ``jsapi_ticket_expires_at`` 的方式为调用 :func:`get_jsapi_ticket` 方法
+
+     下一版本将会考虑更为简单通用的方法，在新版本发布之前，请用你自己的方式把得到的 ``access_token``, ``access_token_expires_at``, ``jsapi_ticket``, ``jsapi_ticket_expires_at`` 保存起来，不管是文件，缓存还是数据库都可以，获取它们的时间可以非常自由，不管是刚刚实例化完成还是得到响应结果之后都没有问题，在调用对应函数时如果没有 ``access_token`` 或 ``jsapi_ticket`` 的话会自动获取的 :)
 
     .. py:method:: check_signature(signature, timestamp, nonce)
 
@@ -45,6 +45,20 @@
         :param str nonce: 随机数
         :return: 通过验证返回 ``True``, 未通过验证返回 ``False``
 
+    .. py:method:: generate_jsapi_signature(timestamp, noncestr, url, jsapi_ticket=None)
+
+        使用 jsapi_ticket 对 url 进行签名
+
+        当未提供 ``jsapi_ticket`` 参数时检查：``appid``, ``appsecret``
+
+        可用公众号类型：认证/未认证订阅号，认证/未认证服务号
+
+        :param str timestamp: 时间戳
+        :param str noncestr: 随机数
+        :param str url: 要签名的 url，不包含 # 及其后面部分
+        :param str jsapi_ticket: (可选参数) jsapi_ticket 值 (如不提供将自动通过 appid 和 appsecret 获取)
+        :return: 返回 sha1 签名的 hexdigest 值
+
     .. py:method:: parse_data(data)
 
         解析微信服务器发送过来的数据并保存类中
@@ -76,7 +90,17 @@
 
         :return: dict 对象, key 包括 ``access_token`` 及 ``access_token_expires_at``
 
-    .. py:method:: response_text(content)
+    .. py:method:: get_jsapi_ticket()
+
+        获取 Jsapi Ticket 及 Jsapi Ticket 过期日期, 仅供缓存使用, 如果希望得到原生的 Jsapi Ticket 请求数据请使用 :func:`grant_jsapi_ticket`
+
+        运行时检查：``appid``, ``appsecret``
+
+        可用公众号类型：认证/未认证订阅号, 认证/未认证服务号
+
+        :return: dict 对象, key 包括 `jsapi_ticket` 及 `jsapi_ticket_expires_at`
+
+    .. py:method:: response_text(content, escape=False)
 
         将文字信息 content 组装为符合微信服务器要求的响应数据
 
@@ -85,6 +109,7 @@
         可用公众号类型：认证/未认证订阅号, 认证/未认证服务号
 
         :param str content: 回复文字
+        :param bool escape: 是否转义该文本内容 (默认不转义)
         :return: 符合微信服务器要求的 XML 响应数据
 
     .. py:method:: response_image(media_id)
@@ -160,6 +185,18 @@
 
         :return: 返回的 JSON 数据包
 
+    .. py:method:: grant_jsapi_ticket()
+
+        获取 Jsapi Ticket
+
+        运行时检查：``appid``, ``appsecret``
+
+        可用公众号类型：认证/未认证订阅号, 认证/未认证服务号
+
+        详情请参考 http://mp.weixin.qq.com/wiki/7/aaa137b55fb2e0456bf8dd9148dd613f.html#.E9.99.84.E5.BD.951-JS-SDK.E4.BD.BF.E7.94.A8.E6.9D.83.E9.99.90.E7.AD.BE.E5.90.8D.E7.AE.97.E6.B3.95
+
+        :return: 返回的 JSON 数据包
+
     .. py:method:: create_menu(menu_data)
 
         创建自定义菜单 ::

diff --git a/docs/conf.py b/docs/conf.py
@@ -49,9 +49,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.5.0'
+version = '0.5.1'
 # The full version, including alpha/beta/rc tags.
-release = '0.5.0'
+release = '0.5.1'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -187,7 +187,7 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
-  ('index', 'wechat.tex', u'wechat-platform Documentation',
+  ('index', 'wechat.tex', u'wechat-python-sdk Documentation',
    u'Ace Kwok', 'manual'),
 ]
 
@@ -217,7 +217,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ('index', 'wechat-platform', u'wechat-platform Documentation',
+    ('index', 'wechat-python-sdk', u'wechat-python-sdk Documentation',
      [u'Ace Kwok'], 1)
 ]
 
@@ -231,7 +231,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-  ('index', 'wechat-platform', u'wechat-platform Documentation',
+  ('index', 'wechat-python-sdk', u'wechat-python-sdk Documentation',
    u'Ace Kwok', 'wechat'),
 ]
 

diff --git a/docs/exceptions.rst b/docs/exceptions.rst
@@ -33,7 +33,7 @@
 
    该类为 ``wechat_sdk.exceptions.UnOfficialAPIError`` 的子类
 
-.. py:class:: wechat_sdk.exceptions.LoginVerifyCodeError():
+.. py:class:: wechat_sdk.exceptions.LoginVerifyCodeError()
 
    微信非官方API请求出错异常 - 登录出错 - 验证码错误