From 7a5169f8c83b743bed0f5c97eeb78eeec3b69439 Mon Sep 17 00:00:00 2001 From: wangweimin Date: Thu, 2 Apr 2020 13:52:03 +0800 Subject: [PATCH] update doc --- .gitignore | 3 +- README.md | 133 ----------------------------- README.rst | 137 ++++++++++++++++++++++++++++++ docs/guide.rst | 7 +- docs/index.rst | 8 +- pywebio/session/__init__.py | 2 + pywebio/session/coroutinebased.py | 3 +- 7 files changed, 150 insertions(+), 143 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/.gitignore b/.gitignore index 5aea1ba4..10383ef4 100755 --- a/.gitignore +++ b/.gitignore @@ -9,4 +9,5 @@ __pycache__/ /no_git /build /dist -/*.egg-info \ No newline at end of file +/*.egg-info +/docs/_build \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index 1b931767..00000000 --- a/README.md +++ /dev/null @@ -1,133 +0,0 @@ -## PyWebIO - -PyWebIO是一个用于在浏览器上获取输入和进行输出的工具库。通过浏览器来提供更多输入输出方式，能够将原有的通过终端交互的脚本快速服务化，供其他人在网络上通过浏览器访问使用；PyWebIO还可以方便地整合进现有的Web服务，非常适合于构建对UI要求不高的后端服务。 - -特点： - -- 使用同步而不是基于回调的方式获取输入，无需在各个步骤之间保存状态，使用更方便 -- 代码侵入性小，对于旧脚本代码仅需修改输入输出逻辑 -- 支持多用户与并发请求 -- 支持整合到现有的Web服务，目前支持与Tornado和Flask的集成 -- 同时支持基于线程的执行模型和基于协程的执行模型 - -## Install - -```bash -pip3 install pywebio -``` - -## Quick start - -假设你编写了如下脚本来计算[BMI指数](https://en.wikipedia.org/wiki/Body_mass_index)： - -```python -# BMI.py -def bmi(): - height = input("请输入你的身高(cm)：") - weight = input("请输入你的体重(kg)：") - - BMI = float(weight) / (float(height) / 100) ** 2 - - top_status = [(14.9, '极瘦'), (18.4, '偏瘦'), - (22.9, '正常'), (27.5, '过重'), - (40.0, '肥胖'), (float('inf'), '非常肥胖')] - - for top, status in top_status: - if BMI <= top: - print('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status)) - break - -if __name__ == '__main__': - bmi() -``` - -### 在浏览器中进行输入输出 - -仅仅需将输入、输出函数替换成`PyWebIO`的输入输出函数就完成了改造(下面代码通过注释标出了改动部分) - -```python -# BMI.py -from pywebio.input import input # Change 1 -from pywebio.output import put_text # Change 1 - -def bmi(): - height = input("请输入你的身高(cm)：") # Change 2 - weight = input("请输入你的体重(kg)：") # Change 2 - - BMI = float(weight) / (float(height) / 100) ** 2 - - top_status = [(14.9, '极瘦'), (18.4, '偏瘦'), - (22.9, '正常'), (27.5, '过重'), - (40.0, '肥胖'), (float('inf'), '非常肥胖')] - - for top, status in top_status: - if BMI <= top: - put_text('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status)) # Change 3 - break - -if __name__ == '__main__': - bmi() -``` - -运行代码就可以在自动弹出的浏览器中与代码交互了： - -![file](/docs/assets/demo.gif) - -### 向外提供服务 -上文对使用`PyWebIO`进行改造的程序，运行模式还是脚本，程序计算完毕后立刻退出。可以使用 `pywebio.start_server` 将程序功能作为Web服务提供： - -```python -# BMI.py -from pywebio import start_server -from pywebio.input import input -from pywebio.output import put_text - -def bmi(): - height = input("请输入你的身高(cm)：") - weight = input("请输入你的体重(kg)：") - - BMI = float(weight) / (float(height) / 100) ** 2 - - top_status = [(14.9, '极瘦'), (18.4, '偏瘦'), - (22.9, '正常'), (27.5, '过重'), - (40.0, '肥胖'), (float('inf'), '非常肥胖')] - - for top, status in top_status: - if BMI <= top: - put_text('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status)) - break - -if __name__ == '__main__': - start_server(bmi) -``` - -### 与现有Web框架整合 -仅需在现有的`Tornado`应用中加入加入两个`RequestHandler`，就可以将使用`PyWebIO`编写的函数整合进`Tornado`应用中了 - -```python -import tornado.ioloop -import tornado.web -from pywebio.platform.tornado import webio_handler -from pywebio import STATIC_PATH - -class MainHandler(tornado.web.RequestHandler): - def get(self): - self.write("Hello, world") - -if __name__ == "__main__": - application = tornado.web.Application([ - (r"/", MainHandler), - (r"/bmi/io", webio_handler(bmi)), # bmi 即为上文中使用`PyWebIO`进行改造的函数 - (r"/bmi/(.*)", tornado.web.StaticFileHandler, {"path": STATIC_PATH, 'default_filename': 'index.html'}) - ]) - application.listen(port=80, address='localhost') - tornado.ioloop.IOLoop.current().start() -``` -在 `http://localhost/bmi/` 页面上就可以计算BMI了 - -## Overview -`PyWebIO`支持丰富的输入输出形式，可以运行以下命令进行速览： - -```bash -python3 -m pywebio.demos.zh.overview -``` diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..9276ada4 --- /dev/null +++ b/README.rst @@ -0,0 +1,137 @@ +PyWebIO +================== + +PyWebIO是一个用于在浏览器上获取输入和进行输出的工具库。能够将原有的通过终端交互的脚本快速服务化，供其他人在网络上通过浏览器访问使用；PyWebIO还可以方便地整合进现有的Web服务，非常适合于构建对UI要求不高的后端服务。 + +特点： + +- 使用同步而不是基于回调的方式获取输入，无需在各个步骤之间保存状态，使用更方便 +- 代码侵入性小，对于旧脚本代码仅需修改输入输出逻辑 +- 支持多用户与并发请求 +- 支持整合到现有的Web服务，目前支持与Tornado和Flask的集成 +- 同时支持基于线程的执行模型和基于协程的执行模型 + +Install +------------ + +.. code-block:: bash + + pip3 install pywebio + +Quick start +------------ + +假设你编写了如下脚本来计算 `BMI指数 `_ ： + +.. code-block:: python + + # BMI.py + def bmi(): + height = input("请输入你的身高(cm)：") + weight = input("请输入你的体重(kg)：") + + BMI = float(weight) / (float(height) / 100) ** 2 + + top_status = [(14.9, '极瘦'), (18.4, '偏瘦'), + (22.9, '正常'), (27.5, '过重'), + (40.0, '肥胖'), (float('inf'), '非常肥胖')] + + for top, status in top_status: + if BMI <= top: + print('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status)) + break + + if __name__ == '__main__': + bmi() + +**在浏览器中进行输入输出** + +仅仅需将输入、输出函数替换成PyWebIO的输入输出函数就完成了改造(下面代码通过注释标出了改动部分) + +.. code-block:: python + + # BMI.py + from pywebio.input import input # Change 1 + from pywebio.output import put_text # Change 1 + + def bmi(): + height = input("请输入你的身高(cm)：") # Change 2 + weight = input("请输入你的体重(kg)：") # Change 2 + + BMI = float(weight) / (float(height) / 100) ** 2 + + top_status = [(14.9, '极瘦'), (18.4, '偏瘦'), + (22.9, '正常'), (27.5, '过重'), + (40.0, '肥胖'), (float('inf'), '非常肥胖')] + + for top, status in top_status: + if BMI <= top: + put_text('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status)) # Change 3 + break + + if __name__ == '__main__': + bmi() + +运行代码就可以在自动弹出的浏览器中与代码交互了： + +.. image:: /docs/assets/demo.gif + +**向外提供服务** + +上文对使用PyWebIO进行改造的程序，运行模式还是脚本，程序计算完毕后立刻退出。可以使用 ``pywebio.start_server`` 将程序功能作为Web服务提供： + +.. code-block:: python + + # BMI.py + from pywebio import start_server + from pywebio.input import input + from pywebio.output import put_text + + def bmi(): + height = input("请输入你的身高(cm)：") + weight = input("请输入你的体重(kg)：") + + BMI = float(weight) / (float(height) / 100) ** 2 + + top_status = [(14.9, '极瘦'), (18.4, '偏瘦'), + (22.9, '正常'), (27.5, '过重'), + (40.0, '肥胖'), (float('inf'), '非常肥胖')] + + for top, status in top_status: + if BMI <= top: + put_text('你的 BMI 值: %.1f，身体状态：%s' % (BMI, status)) + break + + if __name__ == '__main__': + start_server(bmi) + +**与现有Web框架整合** + +仅需在现有的Tornado应用中加入加入两个 ``RequestHandler`` ，就可以将使用PyWebIO编写的函数整合进 ``Tornado`` 应用中了 + +.. code-block:: python + + import tornado.ioloop + import tornado.web + from pywebio.platform.tornado import webio_handler + from pywebio import STATIC_PATH + + class MainHandler(tornado.web.RequestHandler): + def get(self): + self.write("Hello, world") + + if __name__ == "__main__": + application = tornado.web.Application([ + (r"/", MainHandler), + (r"/bmi/io", webio_handler(bmi)), # bmi 即为上文中使用`PyWebIO`进行改造的函数 + (r"/bmi/(.*)", tornado.web.StaticFileHandler, {"path": STATIC_PATH, 'default_filename': 'index.html'}) + ]) + application.listen(port=80, address='localhost') + tornado.ioloop.IOLoop.current().start() + +在 ``http://localhost/bmi/`` 页面上就可以计算BMI了 + +文档 +------------ + +使用手册和开发文档见 `https://pywebio.readthedocs.io `_ diff --git a/docs/guide.rst b/docs/guide.rst index 3806a1b3..394e12fb 100644 --- a/docs/guide.rst +++ b/docs/guide.rst @@ -382,16 +382,17 @@ PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务 start_server(main, auto_open_webbrowser=True) -与基于线程的会话类似，在基于协程的会话中，当任务函数和在会话内通过 ``run_async()`` 运行的携程全部结束后，会话关闭。 +`run_async(coro) ` 返回一个 `TaskHandle ` ，通过 ``TaskHandle`` 你可以查询协程运行状态和关闭协程。 +与基于线程的会话类似，在基于协程的会话中，当任务函数和在会话内通过 ``run_async()`` 运行的协程全部结束后，会话关闭。 .. note:: 在基于协程的会话中， :doc:`pywebio.input ` 模块中的输入函数都需要使用 ``await`` 语法来获取返回值， - 忘记使用 ``await`` 将会是你在使用基于协程的会话常常犯的错误。 + 忘记使用 ``await`` 将会是在使用基于协程的会话常常犯的错误。 与Web框架进行集成 """"""""""""""""""""" -基于协程的会话同样可以与Web框架进行集成，只需要在原来传入任务函数的地方改为传入携程函数即可。 +基于协程的会话同样可以与Web框架进行集成，只需要在原来传入任务函数的地方改为传入协程函数即可。 但当前在使用基于协程的会话集成进Flask时，存在一些限制： diff --git a/docs/index.rst b/docs/index.rst index 69affad6..1f578f2c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,9 +1,9 @@ PyWebIO ========== -PyWebIO是一个用于在浏览器上获取输入和进行输出的工具库。通过浏览器来提供更多输入输出方式，你可以将原有的通过终端交互的脚本快速服务化，供其他人在网络上通过浏览器访问使用；PyWebIO还可以方便地整合进现有的Web服务，非常适合于构建对UI要求不高的后端服务。 +PyWebIO是一个用于在浏览器上获取输入和进行输出的工具库。可以将原有的通过终端交互的脚本快速服务化，供其他人在网络上通过浏览器访问使用；PyWebIO还可以方便地整合进现有的Web服务，非常适合于构建对UI要求不高的后端服务。 -特点： +特点 ------------ - 使用同步而不是基于回调的方式获取输入，无需在各个步骤之间保存状态，使用更方便 @@ -51,9 +51,7 @@ Hello, world if __name__ == '__main__': bmi() -如果不是程序开始的头文件，你甚至不会意识到自己正在使用一个输入输出库。 - -运行以上代码就可以在自动弹出的浏览器中与代码交互了： +如果没有使用PywWebIO，这只是一个非常简单的脚本，而通过使用PywWebIO提供的输入输出函数，你可以在浏览器中与代码进行交互： .. image:: /assets/demo.* diff --git a/pywebio/session/__init__.py b/pywebio/session/__init__.py index 649656b5..a45fe731 100644 --- a/pywebio/session/__init__.py +++ b/pywebio/session/__init__.py @@ -2,6 +2,8 @@ .. autofunction:: run_async .. autofunction:: run_asyncio_coroutine .. autofunction:: register_thread +.. autoclass:: pywebio.session.coroutinebased.TaskHandle + :members: """ import asyncio diff --git a/pywebio/session/coroutinebased.py b/pywebio/session/coroutinebased.py index 00b6eb4e..c4ec97a3 100644 --- a/pywebio/session/coroutinebased.py +++ b/pywebio/session/coroutinebased.py @@ -211,13 +211,14 @@ async def run_asyncio_coroutine(self, coro_obj): class TaskHandle: + """协程任务句柄""" def __init__(self, close, closed): self._close = close self._closed = closed def close(self): - """关闭任务""" + """关闭协程任务""" return self._close() def closed(self):