众所周知,异步并发编程可以帮助程序更好地处理阻塞操作,比如网络 IO 操作或文件 IO 操作,避免因等待这些操作完成而导致程序卡住的情况。云存储文件传输场景正好包含网络 IO 操作和文件 IO 操作,比如业内相对著名的七牛云存储,官方sdk的默认阻塞传输模式虽然差强人意,但未免有些循规蹈矩,不够锐意创新。在全球同性交友网站Github上找了一圈,也没有找到异步版本,那么本次我们来自己动手将同步阻塞版本改造为异步非阻塞版本,并上传至Python官方库。
异步改造
首先参见七牛云官方接口文档:https://developer.qiniu.com/kodo,新建qiniu_async.py文件:
# @Author:Liu Yue (v3u.cn) # @Software:Vscode # @Time:2022/12/30 import base64 import hmac import time from hashlib import sha1 import json import httpx import aiofiles class Qiniu: def __init__(self, access_key, secret_key): """初始化""" self.__checkKey(access_key, secret_key) self.__access_key = access_key self.__secret_key = secret_key.encode('utf-8') def get_access_key(self): return self.__access_key def get_secret_key(self): return self.__secret_key def __token(self, data): hashed = hmac.new(self.__secret_key,data.encode('utf-8'), sha1) return self.urlsafe_base64_encode(hashed.digest()) def token(self, data): return '{0}:{1}'.format(self.__access_key, self.__token(data)) def token_with_data(self, data): data = self.urlsafe_base64_encode(data) return '{0}:{1}:{2}'.format( self.__access_key, self.__token(data), data) def urlsafe_base64_encode(self,data): if isinstance(data, str): data = data.encode('utf-8') ret = base64.urlsafe_b64encode(data) data = ret.decode('utf-8') return data @staticmethod def __checkKey(access_key, secret_key): if not (access_key and secret_key): raise ValueError('invalid key') def upload_token( self, bucket, key=None, expires=3600, policy=None, strict_policy=True): """生成上传凭证 Args: bucket: 上传的空间名 key: 上传的文件名,默认为空 expires: 上传凭证的过期时间,默认为3600s policy: 上传策略,默认为空 Returns: 上传凭证 """ if bucket is None or bucket == '': raise ValueError('invalid bucket name') scope = bucket if key is not None: scope = '{0}:{1}'.format(bucket, key) args = dict( scope=scope, deadline=int(time.time()) + expires, ) return self.__upload_token(args) @staticmethod def up_token_decode(up_token): up_token_list = up_token.split(':') ak = up_token_list[0] sign = base64.urlsafe_b64decode(up_token_list[1]) decode_policy = base64.urlsafe_b64decode(up_token_list[2]) decode_policy = decode_policy.decode('utf-8') dict_policy = json.loads(decode_policy) return ak, sign, dict_policy def __upload_token(self, policy): data = json.dumps(policy, separators=(',', ':')) return self.token_with_data(data) @staticmethod def __copy_policy(policy, to, strict_policy): for k, v in policy.items(): if (not strict_policy) or k in _policy_fields: to[k] = v
这里有两个很关键的异步非阻塞三方库,分别是httpx和aiofiles,对应处理网络IO和文件IO阻塞问题:
pip3 install httpx pip3 install aiofiles
随后按照文档流程通过加密方法获取文件上传token,这里无须进行异步改造,因为并不涉及IO操作:
q = Qiniu(access_key,access_secret) token = q.upload_token("空间名称") print(token)
程序返回:
➜ mydemo git:(master) ✗ /opt/homebrew/bin/python3.10 "/Users/liuyue/wodfan/work/mydemo/src/test.py" q06bq54Ps5JLfZyP8Ax-qvByMBdu8AoIVJpMco2m:8RjIo9a4CxHM3009DwjbMxDzlU8=:eyJzY29wZSI6ImFkLWgyMTEyIiwiZGVhZGxpbmUiOjE2NzIzNjg2NTd9
接着添加文件流推送方法,先看官方原版逻辑:
def put_data( up_token, key, data, params=None, mime_type='application/octet-stream', check_crc=False, progress_handler=None, fname=None, hostscache_dir=None, metadata=None): """上传二进制流到七牛 Args: up_token: 上传凭证 key: 上传文件名 data: 上传二进制流 params: 自定义变量,规格参考 https://developer.qiniu.com/kodo/manual/vars#xvar mime_type: 上传数据的mimeType check_crc: 是否校验crc32 progress_handler: 上传进度 hostscache_dir: host请求 缓存文件保存位置 metadata: 元数据 Returns: 一个dict变量,类似 {"hash": "", "key": ""} 一个ResponseInfo对象 """ final_data = b'' if hasattr(data, 'read'): while True: tmp_data = data.read(config._BLOCK_SIZE) if len(tmp_data) == 0: break else: final_data += tmp_data else: final_data = data crc = crc32(final_data) return _form_put(up_token, key, final_data, params, mime_type, crc, hostscache_dir, progress_handler, fname, metadata=metadata) def _form_put(up_token, key, data, params, mime_type, crc, hostscache_dir=None, progress_handler=None, file_name=None, modify_time=None, keep_last_modified=False, metadata=None): fields = {} if params: for k, v in params.items(): fields[k] = str(v) if crc: fields['crc32'] = crc if key is not None: fields['key'] = key fields['token'] = up_token if config.get_default('default_zone').up_host: url = config.get_default('default_zone').up_host else: url = config.get_default('default_zone').get_up_host_by_token(up_token, hostscache_dir) # name = key if key else file_name fname = file_name if not fname or not fname.strip(): fname = 'file_name' # last modify time if modify_time and keep_last_modified: fields['x-qn-meta-!Last-Modified'] = rfc_from_timestamp(modify_time) if metadata: for k, v in metadata.items(): if k.startswith('x-qn-meta-'): fields[k] = str(v) r, info = http._post_file(url, data=fields, files={'file': (fname, data, mime_type)}) if r is None and info.need_retry(): if info.connect_failed: if config.get_default('default_zone').up_host_backup: url = config.get_default('default_zone').up_host_backup else: url = config.get_default('default_zone').get_up_host_backup_by_token(up_token, hostscache_dir) if hasattr(data, 'read') is False: pass elif hasattr(data, 'seek') and (not hasattr(data, 'seekable') or data.seekable()): data.seek(0) else: return r, info r, info = http._post_file(url, data=fields, files={'file': (fname, data, mime_type)}) return r, info
这里官方使用两个方法,先试用put_data方法将字符串转换为二进制文件流,随后调用_form_put进行同步上传操作,这里_form_put这个私有方法是可复用的,既兼容文件流也兼容文件实体,写法上非常值得我们借鉴,弄明白了官方原版的流程后,让我们撰写文件流传输的异步版本:
# 上传文件流 async def upload_data(self,up_token, key,data,url="http://up-z1.qiniup.com",params=None,mime_type='application/octet-stream',file_name=None,metadata=None): data.encode('utf-8') fields = {} if params: for k, v in params.items(): fields[k] = str(v) if key is not None: fields['key'] = key fields['token'] = up_token fname = file_name if not fname or not fname.strip(): fname = 'file_name' async with httpx.AsyncClient() as client: # 调用异步使用await关键字 res = await client.post(url,data=fields,files={'file': (fname,data,mime_type)}) print(res.text)
这里我们声明异步方法upload_data,通过encode直接转换文件流,并使用异步httpx.AsyncClient()对象将文件流推送到官网接口地址:up-z1.qiniup.com
随后进行测试:
import asyncioq = qiniu_async.Qiniu("accesskey","accesssecret") token = q.upload_token("空间名称") #文件流上传 asyncio.run(q.upload_data(token,"3343.txt","123测试"))
程序返回:
➜ mydemo git:(master) ✗ /opt/homebrew/bin/python3.10 "/Users/liuyue/wodfan/work/mydemo/src/test.py" {"hash":"FtnQXAXft5AsOH1mrmXGaRzSt-95","key":"33434.txt"}
接口会返回文件流的hash编码,没有问题。
接着查看文件上传流程:
def put_file(up_token, key, file_path, params=None, mime_type='application/octet-stream', check_crc=False, progress_handler=None, upload_progress_recorder=None, keep_last_modified=False, hostscache_dir=None, part_size=None, version=None, bucket_name=None, metadata=None): """上传文件到七牛 Args: up_token: 上传凭证 key: 上传文件名 file_path: 上传文件的路径 params: 自定义变量,规格参考 https://developer.qiniu.com/kodo/manual/vars#xvar mime_type: 上传数据的mimeType check_crc: 是否校验crc32 progress_handler: 上传进度 upload_progress_recorder: 记录上传进度,用于断点续传 hostscache_dir: host请求 缓存文件保存位置 version: 分片上传版本 目前支持v1/v2版本 默认v1 part_size: 分片上传v2必传字段 默认大小为4MB 分片大小范围为1 MB - 1 GB bucket_name: 分片上传v2字段 空间名称 metadata: 元数据信息 Returns: 一个dict变量,类似 {"hash": "", "key": ""} 一个ResponseInfo对象 """ ret = {} size = os.stat(file_path).st_size with open(file_path, 'rb') as input_stream: file_name = os.path.basename(file_path) modify_time = int(os.path.getmtime(file_path)) if size > config.get_default('default_upload_threshold'): ret, info = put_stream(up_token, key, input_stream, file_name, size, hostscache_dir, params, mime_type, progress_handler, upload_progress_recorder=upload_progress_recorder, modify_time=modify_time, keep_last_modified=keep_last_modified, part_size=part_size, version=version, bucket_name=bucket_name, metadata=metadata) else: crc = file_crc32(file_path) ret, info = _form_put(up_token, key, input_stream, params, mime_type, crc, hostscache_dir, progress_handler, file_name, modify_time=modify_time, keep_last_modified=keep_last_modified, metadata=metadata) return ret, info
这里官方使用的是标准库上下文管理器同步读取文件,改写为异步方法:
# 上传文件实体 async def upload_file(self,up_token,key,path,url="http://up-z1.qiniup.com",params=None,mime_type='application/octet-stream',file_name=None,metadata=None): async with aiofiles.open(path, mode='rb') as f: contents = await f.read() fields = {} if params: for k, v in params.items(): fields[k] = str(v) if key is not None: fields['key'] = key fields['token'] = up_token fname = file_name if not fname or not fname.strip(): fname = 'file_name' async with httpx.AsyncClient() as client: # 调用异步使用await关键字 res = await client.post(url,data=fields,files={'file': (fname,contents,mime_type)}) print(res.text)
通过aiofiles异步读取文件后,在通过httpx.AsyncClient()进行异步传输。
需要注意的是,这里默认传输到up-z1.qiniup.com接口,如果是不同区域的云存储服务器,需要更改url参数的值,具体服务器接口列表请参照官网文档。
至此,文件流和文件异步传输就改造好了。
上传至Python官方库
为了方便广大七牛云用户使用异步传输版本库,可以将qiniu-async上传到Python官方库,首先注册成为Python官方库的开发者:pypi.org/
随后在项目根目录下新建setup.py文件:
import setuptools import pathlib here = pathlib.Path(__file__).parent.resolve() long_description = (here / "README.md").read_text(encoding="utf-8") setuptools.setup( name="qiniu-async", version="1.0.1", author="LiuYue", author_email="zcxey2911@gmail.com", description="qiniu_async python library", long_description=long_description, long_description_content_type="text/markdown", url="https://github.com/qiniu-async", packages=setuptools.find_packages(), license="Apache 2.0", classifiers=[ "Development Status :: 3 - Alpha", "Intended Audience :: Developers", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.7", "Programming Language :: Python :: 3.8", "Programming Language :: Python :: 3.9", "Programming Language :: Python :: 3.10", "Programming Language :: Python :: 3 :: Only", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ], keywords="qiniu, qiniu_async, async", py_modules=[ 'qiniu_async' ], install_requires=["aiofiles","httpx"], )
这是安装文件,主要为了声明该模块的名称、作者、版本以及依赖库。
随后本地打包文件:
python3 setup.py sdist
程序会根据setup.py文件生成压缩包:
➜ qiniu_async tree . ├── README.md ├── dist │ └── qiniu-async-1.0.1.tar.gz ├── https: │ └── github.com │ └── zcxey2911 │ └── qiniu-async.git ├── qiniu_async.egg-info │ ├── PKG-INFO │ ├── SOURCES.txt │ ├── dependency_links.txt │ ├── requires.txt │ └── top_level.txt ├── qiniu_async.py └── setup.py
接着安装twine库, 准备提交Python官网:
pip3 install twine
随后在根目录运行命令提交:
twine upload dist/*
在官网进行查看:https://pypi.org/project/qiniu-async/
随后本地就可以直接通过pip命令句进行安装了:
pip install qiniu-async -i https://pypi.org/simple
非常方便。
结语
云端存储,异步加持,猛虎添翼,未敢拥钵独飨,除了通过pip安装qiniu-async库,也奉上Github项目地址:https://github.com/zcxey2911/qiniu-async ,与众乡亲同飨。