========
pyzentao
========
.. image:: https://travis-ci.com/philip1134/pyzentao.svg?branch=master
:target: https://travis-ci.com/philip1134/pyzentao
:alt: Build Status
.. image:: https://img.shields.io/pypi/v/pyzentao.svg?color=orange
:target: https://pypi.python.org/pypi/pyzentao
:alt: PyPI Version
.. image:: https://img.shields.io/pypi/pyversions/pyzentao.svg
:target: https://pypi.org/project/pyzentao/
:alt: Supported Python versions
``pyzentao`` 是禅道API的Python SDK，简单封装了禅道API，将其映射成为Python方法，例如：
.. code:: text
GET /zentao/user-task-[userID]-[type]-[recTotal]-[recPerPage]-[pageID].json
被映射成为 ``Zentao.user_task(...)`` ，后续 ``[...]`` 里的参数被映射成为调用方法的参数。
在调用方法时，``pyzentao`` 会根据初始化时输入的配置参数获取禅道的授权，然后调用对应的API，并返回数据结果。
安装
----
.. code:: text
$ pip install -U pyzentao
使用时需要根据你家的禅道版本指定 API 规格，自 ``pyzentao r0.4.0`` 版本之后，规格文件由
`pyzentao-specs <https://github.com/philip1134/pyzentao-specs>`__ 项目维护，
在该项目下载对应的规格文件，放到你的项目下，初始化时指向这个路径即可，详见 ``pyzentao-specs`` 的说明。
也可以使用 `miaou <https://github.com/philip1134/miaou>`__ 自助生成规格文件。
用法
----
上栗子
~~~~~~
查询用户任务
^^^^^^^^^^^^
获取指定用户的任务，原生API为
.. code:: text
GET /zentao/user-task-[userID]-[type]-[recTotal]-[recPerPage]-[pageID].json
该API被映射为 ``user_task`` 方法
.. code:: python
import pyzentao
zentao = pyzentao.Zentao({
"url": "http://my.zentao.site/zentao",
"username": "admin",
"password": "123456",
"spec": "/path/to/my/project/v17.6"
})
tasks = zentao.user_task(
userID=1,
type="finishedBy",
...
)
print(tasks.status) # success
print(tasks.data) # dict...
创建任务
^^^^^^^^
对于需携带POST参数的API，可使用 ``data`` 传入，例如创建任务，原生API为
.. code:: text
GET/POST /zentao/task-create-[projectID]-[storyID]-[moduleID]-[taskID]-[todoID].json
该API被映射为 ``task_create`` 方法
.. code:: python
import pyzentao
zentao = pyzentao.Zentao({
"url": "http://my.zentao.site/zentao",
"username": "admin",
"password": "123456",
"spec": "/path/to/my/project/v17.6"
})
response = zentao.task_create(
executionID=2,
storyID=0,
moduleID=0,
...
data={
"execution": 2,
"type": "design",
"name": "锦囊喵叽",
"assignedTo[]": "老六",
"pri": 3,
"desc": "暴打小柯基"
...
},
)
print(response.status) # success
注意，在 POST参数中,使用 ``assignedTo[]`` 指派任务，而不是文档中的 ``assignedTo`` ⊙﹏⊙‖∣
初始化参数说明
~~~~~~~~~~~~~~
初始化 ``Zentao`` 对象时的参数说明如下：
- url
[必填] 禅道站点的域名，一般需要加上 zentao 这个前缀，如 "http://my.zentao.site/zentao"
- username
[必填] 登录禅道的帐号用户名，该帐号最好具有管理员权限
- password
[必填] 登录禅道的帐号密码
- spec
[必填] API规格文件路径，可以是 yaml 文件路径或是包含规格文件的目录路径
返回数据处理
~~~~~~~~~~~~
禅道原生API的返回数据中字段繁杂，默认情况下 ``pyzentao`` 做了整理，只保留了 ``status`` 和 ``data`` 的数据，
如果需要获得全部原生的数据，可在API调用中加入参数 ``raw=True``，例如
.. code:: python
tasks = zentao.user_task(
userID=1,
type="finishedBy",
...
raw=True
)
某些 POST API 调用的返回值为 {result, message, ...}，而非 {status, data} 格式，
我们均将其映射为后者，即 result 映射为 status, {message, ...} 赋值为 data 。
其他
~~~~
``pyzentao`` 对于API调用过程中出现的异常并不作捕获，建议业务层根据自身使用场景决定处理逻辑。
如果你的项目以 daemon 的形式在运行，在禅道 session 过期的时候可以重连，例如
.. code:: python
import pyzentao
zentao = pyzentao.Zentao(...)
# 调用 reconnect
zentao.reconnect()
# 或在调用某个 API 方法时使用 force_reconnect
zentao.user_task(
...
force_reconnect=True
)
如果 API 的返回数据中不包含合法的 json 数据，将会抛出 ``InvalidJSONResponseError`` 的异常，
一般原因是返回了 HTML 格式的数据，如404页面，请确认初始化时的 ``url`` 参数是否正确，或原生 API 的调用是否正常。
作为懒癌晚期患者，功能仅在 ``Linux/Python3.10`` 环境下测试，不打算兼容 ``Python2`` 和 ``Python3.3`` 以前版本 (๑¯ω¯๑)
Raw data
{
"_id": null,
"home_page": "https://github.com/philip1134/pyzentao",
"name": "pyzentao",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "Python SDK",
"author": "Philip CHAN",
"author_email": "philip1134@imior.com",
"download_url": "https://files.pythonhosted.org/packages/f1/c3/e8b4f002fec638acef603b97748c86706a778b84d1bf01d4dd8e8e386593/pyzentao-0.4.1.tar.gz",
"platform": "any",
"description": "========\npyzentao\n========\n\n.. image:: https://travis-ci.com/philip1134/pyzentao.svg?branch=master\n :target: https://travis-ci.com/philip1134/pyzentao\n :alt: Build Status\n\n.. image:: https://img.shields.io/pypi/v/pyzentao.svg?color=orange\n :target: https://pypi.python.org/pypi/pyzentao\n :alt: PyPI Version\n\n.. image:: https://img.shields.io/pypi/pyversions/pyzentao.svg\n :target: https://pypi.org/project/pyzentao/\n :alt: Supported Python versions\n\n``pyzentao`` \u662f\u7985\u9053API\u7684Python SDK\uff0c\u7b80\u5355\u5c01\u88c5\u4e86\u7985\u9053API\uff0c\u5c06\u5176\u6620\u5c04\u6210\u4e3aPython\u65b9\u6cd5\uff0c\u4f8b\u5982\uff1a\n\n.. code:: text\n\n GET /zentao/user-task-[userID]-[type]-[recTotal]-[recPerPage]-[pageID].json\n\n\u88ab\u6620\u5c04\u6210\u4e3a ``Zentao.user_task(...)`` \uff0c\u540e\u7eed ``[...]`` \u91cc\u7684\u53c2\u6570\u88ab\u6620\u5c04\u6210\u4e3a\u8c03\u7528\u65b9\u6cd5\u7684\u53c2\u6570\u3002\n\n\u5728\u8c03\u7528\u65b9\u6cd5\u65f6\uff0c``pyzentao`` \u4f1a\u6839\u636e\u521d\u59cb\u5316\u65f6\u8f93\u5165\u7684\u914d\u7f6e\u53c2\u6570\u83b7\u53d6\u7985\u9053\u7684\u6388\u6743\uff0c\u7136\u540e\u8c03\u7528\u5bf9\u5e94\u7684API\uff0c\u5e76\u8fd4\u56de\u6570\u636e\u7ed3\u679c\u3002\n\n\n\u5b89\u88c5\n----\n\n.. code:: text\n\n $ pip install -U pyzentao\n\n\u4f7f\u7528\u65f6\u9700\u8981\u6839\u636e\u4f60\u5bb6\u7684\u7985\u9053\u7248\u672c\u6307\u5b9a API \u89c4\u683c\uff0c\u81ea ``pyzentao r0.4.0`` \u7248\u672c\u4e4b\u540e\uff0c\u89c4\u683c\u6587\u4ef6\u7531\n`pyzentao-specs <https://github.com/philip1134/pyzentao-specs>`__ \u9879\u76ee\u7ef4\u62a4\uff0c\n\u5728\u8be5\u9879\u76ee\u4e0b\u8f7d\u5bf9\u5e94\u7684\u89c4\u683c\u6587\u4ef6\uff0c\u653e\u5230\u4f60\u7684\u9879\u76ee\u4e0b\uff0c\u521d\u59cb\u5316\u65f6\u6307\u5411\u8fd9\u4e2a\u8def\u5f84\u5373\u53ef\uff0c\u8be6\u89c1 ``pyzentao-specs`` \u7684\u8bf4\u660e\u3002\n\n\u4e5f\u53ef\u4ee5\u4f7f\u7528 `miaou <https://github.com/philip1134/miaou>`__ \u81ea\u52a9\u751f\u6210\u89c4\u683c\u6587\u4ef6\u3002\n\n\u7528\u6cd5\n----\n\n\u4e0a\u6817\u5b50\n~~~~~~\n\n\u67e5\u8be2\u7528\u6237\u4efb\u52a1\n^^^^^^^^^^^^\n\n\u83b7\u53d6\u6307\u5b9a\u7528\u6237\u7684\u4efb\u52a1\uff0c\u539f\u751fAPI\u4e3a\n\n.. code:: text\n\n GET /zentao/user-task-[userID]-[type]-[recTotal]-[recPerPage]-[pageID].json\n\n\u8be5API\u88ab\u6620\u5c04\u4e3a ``user_task`` \u65b9\u6cd5\n\n.. code:: python\n\n import pyzentao\n\n zentao = pyzentao.Zentao({\n \"url\": \"http://my.zentao.site/zentao\",\n \"username\": \"admin\",\n \"password\": \"123456\",\n \"spec\": \"/path/to/my/project/v17.6\"\n })\n\n tasks = zentao.user_task(\n userID=1,\n type=\"finishedBy\",\n ...\n )\n\n print(tasks.status) # success\n print(tasks.data) # dict...\n\n\u521b\u5efa\u4efb\u52a1\n^^^^^^^^\n\n\u5bf9\u4e8e\u9700\u643a\u5e26POST\u53c2\u6570\u7684API\uff0c\u53ef\u4f7f\u7528 ``data`` \u4f20\u5165\uff0c\u4f8b\u5982\u521b\u5efa\u4efb\u52a1\uff0c\u539f\u751fAPI\u4e3a\n\n.. code:: text\n\n GET/POST /zentao/task-create-[projectID]-[storyID]-[moduleID]-[taskID]-[todoID].json\n\n\u8be5API\u88ab\u6620\u5c04\u4e3a ``task_create`` \u65b9\u6cd5\n\n.. code:: python\n\n import pyzentao\n\n zentao = pyzentao.Zentao({\n \"url\": \"http://my.zentao.site/zentao\",\n \"username\": \"admin\",\n \"password\": \"123456\",\n \"spec\": \"/path/to/my/project/v17.6\"\n })\n\n response = zentao.task_create(\n executionID=2,\n storyID=0,\n moduleID=0,\n ...\n data={\n \"execution\": 2,\n \"type\": \"design\",\n \"name\": \"\u9526\u56ca\u55b5\u53fd\",\n \"assignedTo[]\": \"\u8001\u516d\",\n \"pri\": 3,\n \"desc\": \"\u66b4\u6253\u5c0f\u67ef\u57fa\"\n ...\n },\n )\n\n print(response.status) # success\n\n\u6ce8\u610f\uff0c\u5728 POST\u53c2\u6570\u4e2d,\u4f7f\u7528 ``assignedTo[]`` \u6307\u6d3e\u4efb\u52a1\uff0c\u800c\u4e0d\u662f\u6587\u6863\u4e2d\u7684 ``assignedTo`` \u2299\ufe4f\u2299\u2016\u2223\n\n\u521d\u59cb\u5316\u53c2\u6570\u8bf4\u660e\n~~~~~~~~~~~~~~\n\n\u521d\u59cb\u5316 ``Zentao`` \u5bf9\u8c61\u65f6\u7684\u53c2\u6570\u8bf4\u660e\u5982\u4e0b\uff1a\n\n\n- url\n [\u5fc5\u586b] \u7985\u9053\u7ad9\u70b9\u7684\u57df\u540d\uff0c\u4e00\u822c\u9700\u8981\u52a0\u4e0a zentao \u8fd9\u4e2a\u524d\u7f00\uff0c\u5982 \"http://my.zentao.site/zentao\"\n\n- username\n [\u5fc5\u586b] \u767b\u5f55\u7985\u9053\u7684\u5e10\u53f7\u7528\u6237\u540d\uff0c\u8be5\u5e10\u53f7\u6700\u597d\u5177\u6709\u7ba1\u7406\u5458\u6743\u9650\n\n- password\n [\u5fc5\u586b] \u767b\u5f55\u7985\u9053\u7684\u5e10\u53f7\u5bc6\u7801\n\n- spec\n [\u5fc5\u586b] API\u89c4\u683c\u6587\u4ef6\u8def\u5f84\uff0c\u53ef\u4ee5\u662f yaml \u6587\u4ef6\u8def\u5f84\u6216\u662f\u5305\u542b\u89c4\u683c\u6587\u4ef6\u7684\u76ee\u5f55\u8def\u5f84\n\n\u8fd4\u56de\u6570\u636e\u5904\u7406\n~~~~~~~~~~~~\n\n\u7985\u9053\u539f\u751fAPI\u7684\u8fd4\u56de\u6570\u636e\u4e2d\u5b57\u6bb5\u7e41\u6742\uff0c\u9ed8\u8ba4\u60c5\u51b5\u4e0b ``pyzentao`` \u505a\u4e86\u6574\u7406\uff0c\u53ea\u4fdd\u7559\u4e86 ``status`` \u548c ``data`` \u7684\u6570\u636e\uff0c\n\u5982\u679c\u9700\u8981\u83b7\u5f97\u5168\u90e8\u539f\u751f\u7684\u6570\u636e\uff0c\u53ef\u5728API\u8c03\u7528\u4e2d\u52a0\u5165\u53c2\u6570 ``raw=True``\uff0c\u4f8b\u5982\n\n.. code:: python\n\n tasks = zentao.user_task(\n userID=1,\n type=\"finishedBy\",\n ...\n raw=True\n )\n\n\u67d0\u4e9b POST API \u8c03\u7528\u7684\u8fd4\u56de\u503c\u4e3a {result, message, ...}\uff0c\u800c\u975e {status, data} \u683c\u5f0f\uff0c\n\u6211\u4eec\u5747\u5c06\u5176\u6620\u5c04\u4e3a\u540e\u8005\uff0c\u5373 result \u6620\u5c04\u4e3a status, {message, ...} \u8d4b\u503c\u4e3a data \u3002\n\n\n\u5176\u4ed6\n~~~~\n\n``pyzentao`` \u5bf9\u4e8eAPI\u8c03\u7528\u8fc7\u7a0b\u4e2d\u51fa\u73b0\u7684\u5f02\u5e38\u5e76\u4e0d\u4f5c\u6355\u83b7\uff0c\u5efa\u8bae\u4e1a\u52a1\u5c42\u6839\u636e\u81ea\u8eab\u4f7f\u7528\u573a\u666f\u51b3\u5b9a\u5904\u7406\u903b\u8f91\u3002\n\n\u5982\u679c\u4f60\u7684\u9879\u76ee\u4ee5 daemon \u7684\u5f62\u5f0f\u5728\u8fd0\u884c\uff0c\u5728\u7985\u9053 session \u8fc7\u671f\u7684\u65f6\u5019\u53ef\u4ee5\u91cd\u8fde\uff0c\u4f8b\u5982\n\n.. code:: python\n\n import pyzentao\n\n zentao = pyzentao.Zentao(...)\n\n # \u8c03\u7528 reconnect\n zentao.reconnect()\n\n # \u6216\u5728\u8c03\u7528\u67d0\u4e2a API \u65b9\u6cd5\u65f6\u4f7f\u7528 force_reconnect\n zentao.user_task(\n ...\n force_reconnect=True\n )\n\n\u5982\u679c API \u7684\u8fd4\u56de\u6570\u636e\u4e2d\u4e0d\u5305\u542b\u5408\u6cd5\u7684 json \u6570\u636e\uff0c\u5c06\u4f1a\u629b\u51fa ``InvalidJSONResponseError`` \u7684\u5f02\u5e38\uff0c\n\u4e00\u822c\u539f\u56e0\u662f\u8fd4\u56de\u4e86 HTML \u683c\u5f0f\u7684\u6570\u636e\uff0c\u5982404\u9875\u9762\uff0c\u8bf7\u786e\u8ba4\u521d\u59cb\u5316\u65f6\u7684 ``url`` \u53c2\u6570\u662f\u5426\u6b63\u786e\uff0c\u6216\u539f\u751f API \u7684\u8c03\u7528\u662f\u5426\u6b63\u5e38\u3002\n\n\u4f5c\u4e3a\u61d2\u764c\u665a\u671f\u60a3\u8005\uff0c\u529f\u80fd\u4ec5\u5728 ``Linux/Python3.10`` \u73af\u5883\u4e0b\u6d4b\u8bd5\uff0c\u4e0d\u6253\u7b97\u517c\u5bb9 ``Python2`` \u548c ``Python3.3`` \u4ee5\u524d\u7248\u672c (\u0e51\u00af\u03c9\u00af\u0e51)\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Zentao.",
"version": "0.4.1",
"split_keywords": [
"python",
"sdk"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f1c3e8b4f002fec638acef603b97748c86706a778b84d1bf01d4dd8e8e386593",
"md5": "b7c1e0ddaecb58823a81fc91420c8367",
"sha256": "f8f4a5b8a767698f2060193578597215c7cadbb14d64efecc87399772bb03fec"
},
"downloads": -1,
"filename": "pyzentao-0.4.1.tar.gz",
"has_sig": false,
"md5_digest": "b7c1e0ddaecb58823a81fc91420c8367",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 11804,
"upload_time": "2023-03-14T04:11:58",
"upload_time_iso_8601": "2023-03-14T04:11:58.882143Z",
"url": "https://files.pythonhosted.org/packages/f1/c3/e8b4f002fec638acef603b97748c86706a778b84d1bf01d4dd8e8e386593/pyzentao-0.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-14 04:11:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "philip1134",
"github_project": "pyzentao",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "pyzentao"
}
JSON
