Skip to content

Commit a613265

Browse files
longbailongbai
committed
Merge pull request #155 from forrest-mao/explanation_7.x
add comment for 7.x
2 parents 87ba610 + 37fed66 commit a613265

File tree

7 files changed

+415
-47
lines changed

7 files changed

+415
-47
lines changed

‎qiniu/auth.py

Lines changed: 71 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -10,27 +10,29 @@
1010
from .utils import urlsafe_base64_encode
1111

1212

13+
# 上传策略，参数规格详见
14+
# http://developer.qiniu.com/docs/v6/api/reference/security/put-policy.html
1315
_policy_fields = set([
14-
'callbackUrl',
15-
'callbackBody',
16-
'callbackHost',
17-
'callbackBodyType',
18-
'callbackFetchKey',
19-
20-
'returnUrl',
21-
'returnBody',
22-
23-
'endUser',
24-
'saveKey',
25-
'insertOnly',
26-
27-
'detectMime',
28-
'mimeLimit',
29-
'fsizeLimit',
30-
31-
'persistentOps',
32-
'persistentNotifyUrl',
33-
'persistentPipeline',
16+
'callbackUrl', # 回调URL
17+
'callbackBody', # 回调Body
18+
'callbackHost', # 回调URL指定的Host
19+
'callbackBodyType', # 回调Body的Content-Type
20+
'callbackFetchKey', # 回调FetchKey模式开关
21+
22+
'returnUrl', # 上传端的303跳转URL
23+
'returnBody', # 上传端简单反馈获取的Body
24+
25+
'endUser', # 回调时上传端标识
26+
'saveKey', # 自定义资源名
27+
'insertOnly', # 插入模式开关
28+
29+
'detectMime', # MimeType侦测开关
30+
'mimeLimit', # MimeType限制
31+
'fsizeLimit', # 上传文件大小限制
32+
33+
'persistentOps', # 持久化处理操作
34+
'persistentNotifyUrl', # 持久化处理结果通知URL
35+
'persistentPipeline', # 持久化处理独享队列
3436
])
3537

3638
_deprecated_policy_fields = set([
@@ -39,8 +41,17 @@
3941

4042

4143
class Auth(object):
44+
"""七牛安全机制类
45+
46+
该类主要内容是七牛上传凭证、下载凭证、管理凭证三种凭证的签名接口的实现，以及回调验证。
47+
48+
Attributes:
49+
__access_key: 账号密钥对中的accessKey，详见 https://portal.qiniu.com/setting/key
50+
__secret_key: 账号密钥对重的secretKey，详见 https://portal.qiniu.com/setting/key
51+
"""
4252

4353
def __init__(self, access_key, secret_key):
54+
"""初始化Auth类"""
4455
self.__checkKey(access_key, secret_key)
4556
self.__access_key, self.__secret_key = access_key, secret_key
4657
self.__secret_key = b(self.__secret_key)
@@ -58,6 +69,16 @@ def token_with_data(self, data):
5869
return '{0}:{1}:{2}'.format(self.__access_key, self.__token(data), data)
5970

6071
def token_of_request(self, url, body=None, content_type=None):
72+
"""带请求体的签名（本质上是管理凭证的签名）
73+
74+
Args:
75+
url: 待签名请求的url
76+
body: 待签名请求的body
77+
content_type: 待签名请求的body的Content-Type
78+
79+
Returns:
80+
管理凭证
81+
"""
6182
parsed_url = urlparse(url)
6283
query = parsed_url.query
6384
path = parsed_url.path
@@ -82,10 +103,15 @@ def __checkKey(access_key, secret_key):
82103
raise ValueError('invalid key')
83104

84105
def private_download_url(self, url, expires=3600):
85-
'''
86-
* return private url
87-
'''
106+
"""生成私有资源下载链接
107+
108+
Args:
109+
url: 私有空间资源的原始URL
110+
expires: 下载凭证有效期，默认为3600s
88111
112+
Returns:
113+
私有资源的下载链接
114+
"""
89115
deadline = int(time.time()) + expires
90116
if '?' in url:
91117
url += '&'
@@ -97,6 +123,17 @@ def private_download_url(self, url, expires=3600):
97123
return '{0}&token={1}'.format(url, token)
98124

99125
def upload_token(self, bucket, key=None, expires=3600, policy=None, strict_policy=True):
126+
"""生成上传凭证
127+
128+
Args:
129+
bucket: 上传的空间名
130+
key: 上传的文件名，默认为空
131+
expires: 上传凭证的过期时间，默认为3600s
132+
policy: 上传策略，默认为空
133+
134+
Returns:
135+
上传凭证
136+
"""
100137
if bucket is None or bucket == '':
101138
raise ValueError('invalid bucket name')
102139

@@ -119,6 +156,17 @@ def __upload_token(self, policy):
119156
return self.token_with_data(data)
120157

121158
def verify_callback(self, origin_authorization, url, body, content_type='application/x-www-form-urlencoded'):
159+
"""回调验证
160+
161+
Args:
162+
origin_authorization: 回调时请求Header中的Authorization字段
163+
url: 回调请求的url
164+
body: 回调请求的body
165+
content_type: 回调请求body的Content-Type
166+
167+
Returns:
168+
返回true表示验证成功，返回false表示验证失败
169+
"""
122170
token = self.token_of_request(url, body, content_type)
123171
authorization = 'QBox {0}'.format(token)
124172
return origin_authorization == authorization

‎qiniu/config.py

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,23 +1,23 @@
11
# -*- coding: utf-8 -*-
22

3-
RS_HOST = 'rs.qbox.me'
4-
IO_HOST = 'iovip.qbox.me'
5-
RSF_HOST = 'rsf.qbox.me'
6-
API_HOST = 'api.qiniu.com'
3+
RS_HOST = 'rs.qbox.me' # 管理操作Host
4+
IO_HOST = 'iovip.qbox.me' # 七牛源站Host
5+
RSF_HOST = 'rsf.qbox.me' # 列举操作Host
6+
API_HOST = 'api.qiniu.com' # 数据处理操作Host
77

8-
UPAUTO_HOST = 'up.qiniu.com'
9-
UPDX_HOST = 'updx.qiniu.com'
10-
UPLT_HOST = 'uplt.qiniu.com'
11-
UPBACKUP_HOST = 'upload.qiniu.com'
8+
UPAUTO_HOST = 'up.qiniu.com' # 默认上传Host
9+
UPDX_HOST = 'updx.qiniu.com' # 电信上传Host
10+
UPLT_HOST = 'uplt.qiniu.com' # 移动上传Host
11+
UPBACKUP_HOST = 'upload.qiniu.com' # 备用上传Host
1212

1313
_config = {
14-
'default_up_host': UPAUTO_HOST,
15-
'connection_timeout': 30,
16-
'connection_retries': 3,
17-
'connection_pool': 10,
14+
'default_up_host': UPAUTO_HOST, # 设置为默认上传Host
15+
'connection_timeout': 30, # 链接超时为时间为30s
16+
'connection_retries': 3, # 链接重试次数为3次
17+
'connection_pool': 10, # 链接池个数为10
1818

1919
}
20-
_BLOCK_SIZE = 1024 * 1024 * 4
20+
_BLOCK_SIZE = 1024 * 1024 * 4 # 断点续上传分块大小，该参数为接口规格，暂不支持修改
2121

2222

2323
def get_default(key):

‎qiniu/http.py

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,20 @@ def _post_with_auth(url, data, auth):
7878

7979

8080
class ResponseInfo(object):
81+
"""七牛HTTP请求返回信息类
82+
83+
该类主要是用于获取和解析对七牛发起各种请求后的响应包的header和body。
84+
85+
Attributes:
86+
status_code: 整数变量，响应状态码
87+
text_body: 字符串变量，响应的body
88+
req_id: 字符串变量，七牛HTTP扩展字段，参考 http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html
89+
x_log: 字符串变量，七牛HTTP扩展字段，参考 http://developer.qiniu.com/docs/v6/api/reference/extended-headers.html
90+
error: 字符串变量，响应的错误内容
91+
"""
92+
8193
def __init__(self, response, exception=None):
94+
"""用响应包和异常信息初始化ResponseInfo类"""
8295
self.__response = response
8396
self.exception = exception
8497
if response is None:

‎qiniu/services/processing/pfop.py

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,14 +5,37 @@
55

66

77
class PersistentFop(object):
8+
"""持久化处理类
9+
10+
该类用于主动触发异步持久化操作，具体规格参考：
11+
http://developer.qiniu.com/docs/v6/api/reference/fop/pfop/pfop.html
12+
13+
Attributes:
14+
auth: 账号管理密钥对，Auth对象
15+
bucket: 操作资源所在空间
16+
pipeline: 多媒体处理队列，详见 https://portal.qiniu.com/mps/pipeline
17+
notify_url: 持久化处理结果通知URL
18+
"""
819

920
def __init__(self, auth, bucket, pipeline=None, notify_url=None):
21+
"""初始化持久化处理类"""
1022
self.auth = auth
1123
self.bucket = bucket
1224
self.pipeline = pipeline
1325
self.notify_url = notify_url
1426

1527
def execute(self, key, fops, force=None):
28+
"""执行持久化处理:
29+
30+
Args:
31+
key: 待处理的源文件
32+
fops: 处理详细操作，规格详见 http://developer.qiniu.com/docs/v6/api/reference/fop/
33+
force: 强制执行持久化处理开关
34+
35+
Returns:
36+
一个dict变量，返回持久化处理的persistentId，类似{"persistentId": 5476bedf7823de4068253bae};
37+
一个ReponseInfo对象
38+
"""
1639
ops = ';'.join(fops)
1740
data = {'bucket': self.bucket, 'key': key, 'fops': ops}
1841
if self.pipeline:

0 commit comments

Comments
 (0)