up2cos 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,90 @@
1
+ Metadata-Version: 2.4
2
+ Name: up2cos
3
+ Version: 0.2.0
4
+ Summary: Save uploaded pictures in Tencent COS.
5
+ Home-page: https://github.com/sapicd/up2cos
6
+ Author: staugur
7
+ Author-email: staugur@saintic.com
8
+ License: BSD 3-Clause
9
+ Description-Content-Type: text/x-rst
10
+ License-File: LICENSE
11
+ Requires-Dist: cos-python-sdk-v5>1.6.0
12
+ Dynamic: author
13
+ Dynamic: author-email
14
+ Dynamic: description
15
+ Dynamic: description-content-type
16
+ Dynamic: home-page
17
+ Dynamic: license
18
+ Dynamic: license-file
19
+ Dynamic: requires-dist
20
+ Dynamic: summary
21
+
22
+ up2cos
23
+ ========
24
+
25
+ 这是基于 `sapic <https://github.com/sapicd/sapic>`_ 图床(v2)的一个扩展模块,
26
+ 用来将上传的图片保存到腾讯云
27
+ `对象存储(COS) <https://cloud.tencent.com/product/cos>`_。
28
+
29
+ - 钩子名(模块名):``up2cos``
30
+ - 扩展类型:``upload``\ (存储驱动)
31
+ - 适用版本:sapic 2.x(V1 的 ``g.cfg`` / ``intpl_localhooksetting`` 契约已废弃)
32
+
33
+ 安装
34
+ -----
35
+
36
+ - 正式版本
37
+
38
+ ``$ pip install -U up2cos``
39
+
40
+ - 开发版本
41
+
42
+ ``$ pip install -U git+https://github.com/sapicd/up2cos.git@master``
43
+
44
+ 依赖 ``cos-python-sdk-v5``;未安装时钩子仍能加载,只是上传会返回
45
+ ``Please install cos-python-sdk-v5 module``。
46
+
47
+ 开始使用
48
+ ---------
49
+
50
+ 添加:
51
+ ^^^^^^
52
+
53
+ 在 **站点管理-钩子插件** 中导入模块名 ``up2cos``\ (或 ``POST /api/v2/hooks/import``\ ),
54
+ 然后启用它。启用后 sapic 会自动创建一条同名存储后端。
55
+
56
+ 配置:
57
+ ^^^^^^
58
+
59
+ 在 **站点管理-存储后端** 里为该后端填写(不是旧的“网站设置”):
60
+
61
+ - ``bucket``\ (必填):COS 存储桶名称,形如 ``test-1250000000``
62
+ - ``secret_id``\ (必填):腾讯云 API 密钥 SecretId,可用有 COS 管理权限的子用户
63
+ - ``secret_key``\ (必填):腾讯云 API 密钥 SecretKey,子用户需勾选“编程访问”
64
+ - ``region``:地域,如 ``ap-beijing``;留空则自动探测(需要列举存储桶权限)
65
+ - ``domain``:公有读加速域名;留空则由 sapic 的 ``/raw/<sha>`` 代理输出
66
+ - ``basedir``:存储根目录,默认桶根目录
67
+ - ``thumb_suffix``:缩略图参数,如 ``?imageMogr2/thumbnail/400x``
68
+
69
+ 填好后可点「检查存储桶」验证凭证与桶是否可达。
70
+
71
+ 同一个驱动可以建多条存储后端(不同桶、不同密钥、不同优先级),上传走优先级
72
+ 最高的那条,其余作为异步副本;判断依据是后端行的 ``priority``\ (数值越小越优先)。
73
+
74
+ 私有桶(签名读):
75
+ ^^^^^^^^^^^^^^^^^^
76
+
77
+ 桶为私有读时,把后端的「访问方式」设为 ``private`` 即可,``domain`` 可留空:
78
+
79
+ - 本驱动实现了 ``upimg_url``,后台不会再报 ``driver cannot read private objects``;
80
+ - 图片直链固定为 ``/raw/<sha>``,sapic 请求本驱动签发 ``get_presigned_url`` 的临时
81
+ 地址(有效期由核心决定,默认 300 秒),在服务端拉取并流式转发,签名与密钥都不
82
+ 会出现在浏览器;
83
+ - 签名针对 COS 源站(``{bucket}.cos.{region}.myqcloud.com``),不针对 CDN 域名;
84
+ - ``private`` 后端不再返回 ``src``,需要 CDN 直链的可同时建一个 ``public`` 后端副本。
85
+
86
+ V1 升级提示
87
+ ------------
88
+
89
+ V2 的配置存在存储后端行里,V1 站点设置中的 ``tencent_*`` 不会自动迁移,需要重新
90
+ 填写一次;已上传图片的记录与旧直链不受影响。
@@ -0,0 +1,6 @@
1
+ up2cos.py,sha256=IHOi1jE1lK8D0BOZmQAuZL7asvJxJPozkYxrVwoozXY,11725
2
+ up2cos-0.2.0.dist-info/licenses/LICENSE,sha256=_TvIC_P3El-HJSjxjxpYhe_Pi-KHYv3Z2nd8ciPV12U,1519
3
+ up2cos-0.2.0.dist-info/METADATA,sha256=7LwrkR_O-xou0itOtMA5hHTwTiav_JdNnDZlA-knBUQ,3348
4
+ up2cos-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
5
+ up2cos-0.2.0.dist-info/top_level.txt,sha256=OK1FL4dHOgdVzOkci18-3yQdmfTwNvgYb_DFmAWuFXA,7
6
+ up2cos-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2020, Hiroshi.tao
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ 1. Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ 2. Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ 3. Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1 @@
1
+ up2cos
up2cos.py ADDED
@@ -0,0 +1,348 @@
1
+ # -*- coding: utf-8 -*-
2
+ """up2cos — store objects in Tencent Cloud COS.
3
+
4
+ Driver contract (v2): ``upimg_save(filename, stream, upload_path, backend=...)``
5
+ returns ``{"code": 0, "path": <cos key>, "size": <bytes>, "etag": <md5>}`` plus
6
+ ``src`` when the backend declares a public ``domain``; without it the service
7
+ layer falls back to ``/raw/<sha>``.
8
+
9
+ ``upimg_url`` signs a temporary read address so the same driver can back a
10
+ ``private`` bucket: sapic relays the body itself and the signature never reaches
11
+ the browser.
12
+
13
+ Credentials come from ``backend["config"]`` (``bucket`` / ``region`` /
14
+ ``secret_id`` / ``secret_key`` / ``basedir`` / ``domain`` / ``thumb_suffix``);
15
+ nothing is read from the site settings any more, so one driver can back several
16
+ buckets with different keys.
17
+
18
+ :copyright: (c) 2020 by staugur.
19
+ :license: BSD 3-Clause, see LICENSE for more details.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import logging
25
+ from hashlib import sha256
26
+
27
+ try: # pragma: no cover - optional dependency
28
+ from qcloud_cos import CosConfig, CosS3Client
29
+ except ImportError: # pragma: no cover - optional dependency
30
+ CosConfig = CosS3Client = None
31
+
32
+ __version__ = '0.2.0'
33
+ __author__ = 'staugur <staugur@saintic.com>'
34
+ __description__ = '将图片保存到腾讯云'
35
+ __catalog__ = 'upload'
36
+ __state__ = 'disabled'
37
+ __appversion__ = '2.x'
38
+
39
+ logger = logging.getLogger(__name__)
40
+
41
+ FIELDS = (
42
+ (
43
+ 'domain',
44
+ 'input',
45
+ '加速域名',
46
+ 'COS 绑定的公有读加速域名;私有桶留空,由 sapic 的 /raw 转发读取',
47
+ ),
48
+ (
49
+ 'thumb_suffix',
50
+ 'input',
51
+ '缩略图参数',
52
+ '图片处理后缀,如 ?imageMogr2/thumbnail/400x;留空则列表页加载原图',
53
+ ),
54
+ ('bucket', 'input', 'Bucket', 'COS 存储桶名称,形如 test-1250000000'),
55
+ (
56
+ 'region',
57
+ 'input',
58
+ '地域',
59
+ '存储桶所在地域,如 ap-beijing;留空则自动探测(需要列举存储桶权限)',
60
+ ),
61
+ (
62
+ 'secret_id',
63
+ 'password',
64
+ 'SecretId',
65
+ '腾讯云 API 密钥的 SecretId,支持有 COS 管理权限的子用户',
66
+ ),
67
+ (
68
+ 'secret_key',
69
+ 'password',
70
+ 'SecretKey',
71
+ '腾讯云 API 密钥的 SecretKey,子用户需勾选编程访问',
72
+ ),
73
+ ('basedir', 'input', '存储根目录', '图片存储到 COS 的基础目录,默认是根目录'),
74
+ )
75
+ REQUIRED = ('bucket', 'secret_id', 'secret_key')
76
+ #: Region used for service level requests such as ``list_buckets``.
77
+ DEFAULT_REGION = 'ap-beijing'
78
+ #: ``region`` is probed once per (secret_id, bucket) and kept in memory: a
79
+ #: private backend asks for a read address on every image view.
80
+ _REGION_CACHE = {}
81
+
82
+
83
+ def hook_manifest():
84
+ return {
85
+ 'title': '腾讯云 COS',
86
+ 'catalog': 'upload',
87
+ 'config_schema': [
88
+ {
89
+ 'type': kind,
90
+ 'key': key,
91
+ 'label': label,
92
+ 'placeholder': hint,
93
+ 'required': key in REQUIRED,
94
+ }
95
+ for key, kind, label, hint in FIELDS
96
+ ],
97
+ 'actions': [
98
+ {
99
+ 'name': 'ping',
100
+ 'label': '检查存储桶',
101
+ 'scope': 'admin',
102
+ 'with_form': True,
103
+ }
104
+ ],
105
+ 'slots': [{'name': 'admin.hook_setting'}],
106
+ }
107
+
108
+
109
+ def slot_admin_hook_setting(context=None, **kwargs):
110
+ backend = (context or {}).get('backend') or {}
111
+ config = backend.get('config') or {}
112
+ children = [
113
+ {
114
+ 'type': kind,
115
+ 'key': key,
116
+ 'label': label,
117
+ 'help': hint,
118
+ 'default': config.get(key) or '',
119
+ 'required': key in REQUIRED,
120
+ }
121
+ for key, kind, label, hint in FIELDS
122
+ ]
123
+ children.append(
124
+ {'type': 'button', 'text': '检查存储桶', 'action': 'ping', 'with_form': True}
125
+ )
126
+ if backend.get('in_use'):
127
+ children.insert(
128
+ 0, {'type': 'alert', 'level': 'success', 'text': '当前正在使用'}
129
+ )
130
+ return [{'type': 'fieldset', 'legend': '腾讯云 COS', 'children': children}]
131
+
132
+
133
+ def _config(backend=None) -> dict:
134
+ return (backend or {}).get('config') or {}
135
+
136
+
137
+ def _value(values, config, key) -> str:
138
+ value = (values or {}).get(key)
139
+ if value in (None, ''):
140
+ value = (config or {}).get(key)
141
+ return str(value or '').strip()
142
+
143
+
144
+ def _key(basedir, upload_path, filename) -> str:
145
+ parts = []
146
+ for part in (basedir, upload_path, filename):
147
+ text = str(part or '').strip('/')
148
+ if text:
149
+ parts.append(text)
150
+ return '/'.join(parts)
151
+
152
+
153
+ def _detect_region(config: dict) -> str:
154
+ """Region of the configured bucket, empty when it cannot be probed."""
155
+ bucket = str(config.get('bucket') or '').strip()
156
+ secret_id = str(config.get('secret_id') or '').strip()
157
+ secret_key = str(config.get('secret_key') or '').strip()
158
+ cache_key = (secret_id, bucket)
159
+ if cache_key in _REGION_CACHE:
160
+ return _REGION_CACHE[cache_key]
161
+
162
+ region = ''
163
+ try:
164
+ client = CosS3Client(
165
+ CosConfig(
166
+ Region=DEFAULT_REGION,
167
+ SecretId=secret_id,
168
+ SecretKey=secret_key,
169
+ )
170
+ )
171
+ buckets = (client.list_buckets() or {}).get('Buckets', {}).get('Bucket') or []
172
+ for item in buckets:
173
+ if item.get('Name') == bucket:
174
+ region = str(item.get('Location') or '').strip()
175
+ break
176
+ except Exception:
177
+ logger.warning(
178
+ 'Failed to detect the region of COS bucket %s', bucket, exc_info=True
179
+ )
180
+ if region:
181
+ _REGION_CACHE[cache_key] = region
182
+ return region
183
+
184
+
185
+ def _client(config: dict):
186
+ """Return ``(CosS3Client, "")`` or ``(None, error message)``."""
187
+ if CosConfig is None:
188
+ return None, 'Please install cos-python-sdk-v5 module'
189
+ for key in REQUIRED:
190
+ if not str(config.get(key) or '').strip():
191
+ return None, 'The tencent %s parameter error' % key
192
+
193
+ region = str(config.get('region') or '').strip() or _detect_region(config)
194
+ if not region:
195
+ return None, 'The tencent region parameter error'
196
+ client = CosS3Client(
197
+ CosConfig(
198
+ Region=region,
199
+ SecretId=str(config['secret_id']).strip(),
200
+ SecretKey=str(config['secret_key']).strip(),
201
+ )
202
+ )
203
+ return client, ''
204
+
205
+
206
+ def _bucket(config: dict) -> str:
207
+ return str(config.get('bucket') or '').strip()
208
+
209
+
210
+ def _public_domain(config: dict, backend=None) -> str:
211
+ """Direct link prefix; empty for a ``private`` backend.
212
+
213
+ A private bucket rejects anonymous reads, so handing out ``src`` would give
214
+ the browser a 403. The service layer ignores it, but per the driver contract
215
+ the driver should not return one at all: private images are always served by
216
+ ``/raw/<sha>`` through :func:`upimg_url`.
217
+ """
218
+ visibility = str((backend or {}).get('visibility') or '').strip().lower()
219
+ if visibility == 'private':
220
+ return ''
221
+ return str(config.get('domain') or '').strip().rstrip('/')
222
+
223
+
224
+ def _status_of(exc) -> int:
225
+ """HTTP status carried by a ``CosServiceError`` (or any SDK exception)."""
226
+ for name in ('get_status_code', 'status_code', 'status'):
227
+ attr = getattr(exc, name, None)
228
+ if attr is None:
229
+ continue
230
+ if callable(attr):
231
+ try:
232
+ return int(attr())
233
+ except (TypeError, ValueError):
234
+ continue
235
+ try:
236
+ return int(attr)
237
+ except (TypeError, ValueError):
238
+ continue
239
+ return 0
240
+
241
+
242
+ def upimg_save(filename, stream, upload_path='', backend=None, **kwargs):
243
+ config = _config(backend)
244
+ if not filename or stream is None:
245
+ return {'code': 1, 'message': 'Parameter error'}
246
+ client, error = _client(config)
247
+ if error:
248
+ return {'code': 1, 'message': error}
249
+
250
+ data = stream if isinstance(stream, (bytes, bytearray)) else stream.read()
251
+ key = _key(config.get('basedir'), upload_path, filename)
252
+ try:
253
+ response = client.put_object(
254
+ Bucket=_bucket(config),
255
+ Key=key,
256
+ Body=data,
257
+ EnableMD5=False,
258
+ )
259
+ except Exception as exc:
260
+ return {'code': 1, 'message': str(exc)}
261
+
262
+ etag = str((response or {}).get('ETag') or '').replace('"', '').strip()
263
+ result = {
264
+ 'code': 0,
265
+ 'path': key,
266
+ 'size': len(data),
267
+ 'etag': etag or sha256(data).hexdigest()[:32],
268
+ }
269
+ #: 私有桶不给直链:读取一律走 /raw 的签名转发。
270
+ domain = _public_domain(config, backend)
271
+ if domain:
272
+ result['src'] = '%s/%s' % (domain, key)
273
+ return result
274
+
275
+
276
+ def upimg_url(save_result, filename='', backend=None, expires=300, **kwargs):
277
+ """Signed GET address for a ``private`` bucket.
278
+
279
+ Only called when the backend ``visibility`` is ``private``: sapic asks for a
280
+ temporary address and relays the body itself, so neither the signature nor
281
+ the credentials ever reach the browser. The signature is computed against
282
+ the bucket origin (not the CDN domain), because a CDN usually ignores the
283
+ query-string authorisation.
284
+ """
285
+ config = _config(backend)
286
+ key = str((save_result or {}).get('path') or '').strip()
287
+ if not key:
288
+ return {'code': 1, 'message': 'The object key is required'}
289
+ client, error = _client(config)
290
+ if error:
291
+ return {'code': 1, 'message': error}
292
+
293
+ bucket = _bucket(config)
294
+ seconds = int(expires or 300)
295
+ try:
296
+ url = client.get_presigned_url(
297
+ Bucket=bucket, Key=key, Method='GET', Expired=seconds
298
+ )
299
+ except (AttributeError, TypeError):
300
+ #: 老版本 SDK 只有 ``get_presigned_download_url``(或参数名不同)。
301
+ try:
302
+ url = client.get_presigned_download_url(
303
+ Bucket=bucket, Key=key, Expired=seconds
304
+ )
305
+ except Exception as exc:
306
+ return {'code': 1, 'message': str(exc)}
307
+ except Exception as exc:
308
+ return {'code': 1, 'message': str(exc)}
309
+ return {'code': 0, 'url': url}
310
+
311
+
312
+ def upimg_delete(sha, upload_path, filename, basedir, save_result, backend=None, **kwargs):
313
+ config = _config(backend)
314
+ client, error = _client(config)
315
+ if error:
316
+ return {'code': 1, 'message': error}
317
+
318
+ save_result = save_result or {}
319
+ key = save_result.get('path') or _key(
320
+ config.get('basedir') or basedir, upload_path, filename
321
+ )
322
+ if not key:
323
+ return {'code': 1, 'message': 'The object key is required'}
324
+ try:
325
+ client.delete_object(Bucket=_bucket(config), Key=key)
326
+ except Exception as exc:
327
+ #: 失败不要抛:核心按 code 判定,抛出会打断同批次的其它副本删除。
328
+ return {'code': 1, 'message': str(exc)}
329
+ return {'code': 0}
330
+
331
+
332
+ def action_ping(values=None, context=None, **kwargs):
333
+ config = ((context or {}).get('backend') or {}).get('config') or {}
334
+ merged = {key: _value(values, config, key) for key, _, _, _ in FIELDS}
335
+ client, error = _client(merged)
336
+ if error:
337
+ return {'code': 1, 'message': error}
338
+
339
+ #: ``head_bucket`` 是桶级请求:任何异常都说明桶不可用(403 凭证/权限,
340
+ #: 404 桶名,其它网络或地域错误),直接返回原因便于排查。
341
+ try:
342
+ client.head_bucket(Bucket=_bucket(merged))
343
+ except Exception as exc:
344
+ status = _status_of(exc)
345
+ if status in (401, 403):
346
+ return {'code': 1, 'message': 'invalid secret id, secret key or bucket'}
347
+ return {'code': 1, 'message': str(exc)[:200]}
348
+ return {'code': 0, 'toast': {'level': 'success', 'text': 'bucket is reachable'}}