diff --git a/.flake8 b/.flake8 index 51bc14d..f8e47b3 100644 --- a/.flake8 +++ b/.flake8 @@ -2,6 +2,11 @@ exclude = .git/, .venv/, + env/, + venv/, + ENV/, + env.bak/, + venv.bak/, .eggs/, __pycache__, docs/, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 85a4cd2..53e1ac0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,9 +4,9 @@ > > 这个项目需要 [Python][] `3.5` 及以上版本。 -## 复刻项目代码 +## 复刻项目 -复刻项目代码到工作目录,然后切换到项目的目录: +复刻项目源码到工作目录,然后切换到项目的目录: ```bash cd path/to/your/workspace/directory/ @@ -14,39 +14,61 @@ git clone https://github.com/tanbro/ks33requests.git cd ks33requests ``` -## 准备开发环境 +## 开发环境 -强烈建议在 [virtual environment][] 中进行开发工作。 +强烈建议在 [virtual environment][] 中进行开发工作。建议的方法有: - 标准库: - 使用标准库的 [venv][] 与 [pip][] 直接新建名为 `venv`(此处仅为举例,可根据实际需要使用其它目录) 的虚拟环境目录,将本项目以 **开发模式** 安装到这个环境,并安装开发工作所要使用的包: + 具体参考 ,此处以`Posix`+`bash`的常见情况为例 - ```bash - path/of/your/python -m venv venv - venv/bin/python setup.py develop - venv/bin/python -m pip install -r requires/dev.txt - ``` + 1. 在子目录 `` (目录名用一个变量代表,取决于具体的实际情况) 中创建虚拟环境 + + ```bash + path/of/your/python -m venv + ``` + + 1. 激活虚拟环境 + + ```bash + source /bin/activate + ``` + + 1. 将本项目以 **可编辑模式** 安装到这个环境,并安装开发工作所要使用的包 + + ```base + pip install -e ./ -r requirements/dev.txt + ``` - [Pipenv][]: - 使用 [Pipenv][] 命令直接安装: + 1. 按照 **开发模式** 为该项目安装一个新的虚拟环境 - ```bash - pipenv install --dev - ``` + ```bash + pipenv install --dev + ``` + + 1. 激活虚拟环境 + + ```bash + pipenv shell + ``` - [conda][]: - 使用 [conda][] 命令从配置文件 `environment.yml` 新建一个专用于这个项目的、名为`ks33requests-dev`的环境,然后激活它,将本项目以 **开发模式** 安装到这个环境: + 1. 从配置文件 `environment.yml` 为该项目安装一个新的虚拟环境,名为`ks33requests-dev`。本项目将以 **可编辑模式** 被安装到这个环境中。 + + ```bash + conda env create -f environment.yml + ``` + + 1. 激活虚拟环境 - ```bash - conda env create -f environment.yml - conda activate ks33requests-dev - python setup.py develop - ``` + ```bash + conda activate ks33requests-dev + ``` -### 编码条例 +## 编码条例 1. 代码风格遵照 [PEP 8](https://www.python.org/dev/peps/pep-0008/) 1. 版本命名遵照 [PEP 440](https://www.python.org/dev/peps/pep-0440/) @@ -58,7 +80,7 @@ cd ks33requests 1. 做静态检查,不提交带有错误或许多警告的代码 1. 提供有足够覆盖面的测试用例 -### XML Schema +## XML Schema [金山云][] [KS3][] 的 WebAPI 数据结构有许多与 [S3][] 兼容。 所以,这个项目直接使用来自 的 Schema 转换部分数据的结构。 @@ -73,30 +95,30 @@ generateDS.py -f -o s3_api.py -s s3_sub.py --super=s3_api schemas/AmazonS3.xsd 生成的源代码文件复制到名称空间 `ks33requests.schemas` 中,小幅修改 `s3_sub.py` 的源码即可使用。 -### 运行测试用例 +## 运行测试 ```bash -python setup.py test +python -m unittest ``` 如果需要在运行测试时进行代码覆盖性检查,可运行: ```bash -python -m coverage run setup.py test +python -m coverage run -m unittest ``` -### 静态代码检查 +## 静态检查 ```bash python -m flake8 ``` -### 文档生成 +## 文档生成 -执行下面的命令构建文档,输出到目录 `build/sphinx`: +下面的命令将构建 `HTML` 文档,输出到目录 `docs/_build`: ```bash -python setup.py build_sphinx +python -m sphinx docs/ docs/_build ``` > i **说明**: diff --git a/README.md b/README.md index f1d69a2..ebdf192 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,16 @@ # ks33requests +[![CircleCI](https://circleci.com/gh/tanbro/ks33requests.svg?style=svg)](https://circleci.com/gh/tanbro/ks33requests) +[![codecov](https://codecov.io/gh/tanbro/ks33requests/branch/master/graph/badge.svg)](https://codecov.io/gh/tanbro/ks33requests) +[![Documentation Status](https://readthedocs.org/projects/ks33requests/badge/?version=stable)](https://ks33requests.readthedocs.io/zh_CN/stable/?badge=stable) +[![GitHub](https://img.shields.io/github/license/tanbro/ks33requests.svg)](https://github.com/tanbro/ks33requests) +[![GitHub tag (latest SemVer)](https://img.shields.io/github/tag/tanbro/ks33requests.svg)](https://github.com/tanbro/ks33requests) +[![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/tanbro/ks33requests.svg)](https://libraries.io/github/tanbro/ks33requests) [![PyPI](https://img.shields.io/pypi/v/ks33requests.svg)](https://pypi.org/project/ks33requests/) [![PyPI - License](https://img.shields.io/pypi/l/ks33requests.svg)](https://pypi.org/project/ks33requests/) [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/ks33requests.svg)](https://pypi.org/project/ks33requests/) [![PyPI - Status](https://img.shields.io/pypi/status/ks33requests.svg)](https://pypi.org/project/ks33requests/) -[![CircleCI](https://circleci.com/gh/tanbro/ks33requests.svg?style=svg)](https://circleci.com/gh/tanbro/ks33requests) -[![codecov](https://codecov.io/gh/tanbro/ks33requests/branch/master/graph/badge.svg)](https://codecov.io/gh/tanbro/ks33requests) -[![Libraries.io dependency status for GitHub repo](https://img.shields.io/librariesio/github/tanbro/ks33requests.svg)](https://libraries.io/github/tanbro/ks33requests) -[![Documentation Status](https://readthedocs.org/projects/ks33requests/badge/?version=stable)](https://ks33requests.readthedocs.io/zh_CN/stable/?badge=stable) +[![Requirements Status](https://requires.io/github/tanbro/ks33requests/requirements.svg?branch=master)](https://requires.io/github/tanbro/ks33requests/requirements/?branch=master) ## 概述 @@ -25,9 +28,10 @@ pip install ks33requests ``` -- 源代码安装 +- 源码安装 ```bash + cd ks33requests python setuptools.py install ``` @@ -39,13 +43,13 @@ ## 用法 -参见: [notebooks](notebooks) 目录中的笔记 +见 [notebooks](notebooks) 目录中的笔记 ## 文档 -参见: +见 -以及代码仓库中的: +以及源码仓库中的文档: - [CHANGELOG](CHANGELOG.md) - [CONTRIBUTING](CONTRIBUTING.md) diff --git a/docs/conf.py b/docs/conf.py index e9b44a5..b787213 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -83,6 +83,6 @@ # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { - 'python': ('https://docs.python.org/{0[0]}'.format(sys.version_info), None), - 'requests': ('https://2.python-requests.org/en/stable/', None), + 'python': ('https://docs.python.org/{0}/{1[0]}'.format(language.lower().replace('_', '-'), sys.version_info), None), + 'requests': ('https://2.python-requests.org/{0}/latest'.format(language), None), } diff --git a/docs/index.rst b/docs/index.rst index f047b3a..70aecfa 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,15 +4,12 @@ contain the root `toctree` directive. ks33requests Documentations -########################### - +=========================== :Release: |release| :Date: |today| :Version: |version| ------- - Docs ---- @@ -34,8 +31,8 @@ Notebooks notebooks/* -API ---- +API Reference +------------- .. toctree:: :glob: @@ -43,9 +40,8 @@ API api/modules - Indices and tables -****************** +------------------ * :ref:`genindex` * :ref:`modindex` diff --git a/environment.yml b/environment.yml index 70a2470..29e1273 100644 --- a/environment.yml +++ b/environment.yml @@ -2,6 +2,7 @@ name: ks33requests-dev channels: - conda-forge dependencies: + - python - requests - lxml - jupyter @@ -18,3 +19,4 @@ dependencies: - pip: - generateDS - flake8-mypy + - -e ./ diff --git a/requires/dev.txt b/requirements/dev.txt similarity index 96% rename from requires/dev.txt rename to requirements/dev.txt index 18666d0..5c3ff27 100644 --- a/requires/dev.txt +++ b/requirements/dev.txt @@ -1,3 +1,4 @@ +-e . generateDS>=2.32 python-dotenv jupyter diff --git a/setup.cfg b/setup.cfg deleted file mode 100644 index c3995d0..0000000 --- a/setup.cfg +++ /dev/null @@ -1,36 +0,0 @@ -# setuptools configure of this package -# see: -# * https://packaging.python.org/ -# * https://setuptools.readthedocs.io/ - -[metadata] -name = ks33requests -description = 适用于金山云对象存储(KS3)的简单 Python3 客户端 -long_description = file: README.md, CHANGELOG.md, CONTRIBUTING.md, AUTHORS.md -long_description_content_type = text/markdown -url = https://github.com/tanbro/ks33requests -python_requires =>=3.5 -license = Apache Software License -classifiers = - License :: OSI Approved :: Apache Software License - Development Status :: 3 - Alpha - Intended Audience :: Developers - Natural Language :: Chinese (Simplified) - Operating System :: OS Independent - Programming Language :: Python - Programming Language :: Python :: 3 - Programming Language :: Python :: 3 :: Only - Topic :: Software Development :: Libraries :: Python Modules - Topic :: Internet :: WWW/HTTP - -[options] -package_dir = - = src -packages = find: - -setup_requires = - setuptools_scm - setuptools_scm_git_archive - -[options.packages.find] -where = src diff --git a/setup.py b/setup.py index acac477..e15496f 100644 --- a/setup.py +++ b/setup.py @@ -1,23 +1,53 @@ #!/usr/bin/env python # -*- coding: utf-8 -*- -"""setuptools script of this package -see: +import io +import os -* https://packaging.python.org/ -* https://setuptools.readthedocs.io/ -""" -from setuptools import setup +from setuptools import find_packages, setup setup( + name='ks33requests', + description='适用于金山云对象存储(KS3)的简单 Python3 客户端', + author="Liu Xue Yan", + author_email="liu_xue_yan@foxmail.com", + long_description=(2 * os.linesep).join( + io.open(file, encoding='utf-8').read() + for file in ('README.md', 'CHANGELOG.md', 'CONTRIBUTING.md', 'AUTHORS.md') + ), + long_description_content_type='text/markdown', + license='Apache Software License', + url='https://github.com/tanbro/ks33requests', + package_dir={'': 'src'}, + packages=find_packages(where='src'), + python_requires='>=3.5', + setup_requires=[ + 'setuptools_scm', + 'setuptools_scm_git_archive', + ], use_scm_version={ # guess-next-dev: automatically guesses the next development version (default) # post-release: generates post release versions (adds postN) 'version_scheme': 'guess-next-dev', 'write_to': 'src/ks33requests/_scm_version.py', }, + classifiers=[ + 'License :: OSI Approved :: Apache Software License', + 'Development Status :: 3 - Alpha', + 'Intended Audience :: Developers', + 'Natural Language :: Chinese (Simplified)', + 'Operating System :: OS Independent', + 'Programming Language :: Python', + 'Programming Language :: Python :: 3', + 'Programming Language :: Python :: 3 :: Only', + 'Topic :: Software Development :: Libraries :: Python Modules', + 'Topic :: Internet :: WWW/HTTP', + ], install_requires=[ 'requests<3.0,>=2.0', - 'lxml<5.0,>=4.0' - ] + 'lxml<5.0,>=4.0', + ], + tests_require=[ + 'python-dotenv', + ], ) diff --git a/src/ks33requests/client.py b/src/ks33requests/client.py index 89efa75..abacec3 100644 --- a/src/ks33requests/client.py +++ b/src/ks33requests/client.py @@ -34,12 +34,12 @@ class Client: """ def __init__( - self, - access_key: str = None, - secret_key: str = None, - endpoint: str = 'kss.ksyun.com', - session: requests.Session = None, - use_https: bool = True + self, + access_key: str = None, + secret_key: str = None, + endpoint: str = 'kss.ksyun.com', + session: requests.Session = None, + use_https: bool = True ): """ :param str access_key: `KS3` 颁发给您的 `AccessKey` (长度为20个字符的ASCII字符串)。用于标识客户的身份。 @@ -55,19 +55,19 @@ def __init__( self._use_https = bool(use_https) def send( - self, - method: str = 'get', - bucket_name: str = None, - object_key: str = None, - sub_resources: Union[str, List[str]] = None, - data=None, - encoding: str = None, - content_md5: str = None, - headers: Dict[str, str] = None, - params: Dict[str, str] = None, - check_status: bool = True, - session: requests.Session = None, - **kwargs + self, + method: str = 'get', + bucket_name: str = None, + object_key: str = None, + sub_resources: Union[str, List[str]] = None, + data=None, + encoding: str = None, + content_md5: str = None, + headers: Dict[str, str] = None, + params: Dict[str, str] = None, + check_status: bool = True, + session: requests.Session = None, + **kwargs ) -> requests.Response: """向 KS3 发送一个 HTTP API 请求,并返回对应的 HTTP 响应对象 @@ -97,14 +97,7 @@ def send( 把URL参数中的:: - "acl","lifecycle","location","logging","notification", - "partNumber","policy","requestPayment","torrent","uploadId", - "uploads","versionId","versioning","versions","website", - "delete","thumbnail","cors","queryadp","adp", - "asyntask","querytask","domain","response-content-type", - "response-content-language","response-expires", - "response-cache-control","response-content-disposition", - "response-content-encoding" + "acl","lifecycle","location","logging","notification", "partNumber","policy","requestPayment","torrent","uploadId", "uploads","versionId","versioning","versions","website", "delete","thumbnail","cors","queryadp","adp", "asyntask","querytask","domain","response-content-type", "response-content-language","response-expires", "response-cache-control","response-content-disposition", "response-content-encoding" # noqa 筛选出来,将这些查询字符串及其请求值(不做URL编码的请求值)按照字典序,从小到大排列,以 `&` 为分隔符排列,即可得到 `SubResource` 。 diff --git a/tests/__init__.py b/tests/__init__.py index e69de29..bf6bd6c 100644 --- a/tests/__init__.py +++ b/tests/__init__.py @@ -0,0 +1,3 @@ +from dotenv import load_dotenv + +load_dotenv() diff --git a/tests/test_upload.py b/tests/test_upload.py index 8e54ebd..f234565 100644 --- a/tests/test_upload.py +++ b/tests/test_upload.py @@ -3,12 +3,8 @@ import pathlib import unittest -from dotenv import load_dotenv - from ks33requests import Client, Ks3Error -load_dotenv() - KSYUN_ACCESS_KEY = os.environ['KSYUN_ACCESS_KEY'] KSYUN_SECRET_KEY = os.environ['KSYUN_SECRET_KEY'] KS3_ENDPOINT = os.environ['KS3_ENDPOINT']

AltStyle によって変換されたページ (->オリジナル) /